Client-Side SDK Reference (Advanced)

JavaScript SDK — Advanced Reference · Version 1.5 · October 2026

How to drop the JavaScript SDK into a client site, plus the full API surface for finer control. Three install flavors (one-line, data-attribute, manual); all expose window.mub_fp.

For the simpler quickstart, see Client-Side Integration (HTML). For React, see Client-Side Integration (React).

Prerequisites

Modern browser: Chrome 60+, Firefox 55+, Safari 11+, Edge 79+
Required globals: fetch, Promise, localStorage, JSON, setTimeout
A site_key issued server-side (starts with public_)
A backend_url for your region — fp.de.mubeen.ai (EU) or fp.sa.mubeen.ai (KSA). Required on every initialization regardless of install flavor.

Install Flavors

backend_url is required

All three install flavors below require backend_url. Initialization will fail if it is missing. Pick the region that matches your data-residency obligations — see Regional Endpoints.

Option 1 — One-Line (recommended)

Simplest path. Query-string site_key and backend_url are picked up automatically; auto-init runs on DOMContentLoaded.

<script src="https://cdn.mubeen.ai/fp/mub_fp.js?site_key=YOUR_SITE_KEY&backend_url=fp.sa.mubeen.ai"></script>

Option 2 — Data Attribute Auto-Init

Useful when you cannot mutate the src URL (for example, serving the SDK from your own static host).

<script src="dist/mub_fp.js"
        data-auto-init
        data-site-key="YOUR_SITE_KEY"
        data-backend-url="fp.sa.mubeen.ai"></script>

Option 3 — Manual Initialization

Full control over timing and config. Use this when you need to wait for consent, defer until after a user action, or plug in custom options.

<script src="dist/mub_fp.js"></script>
<script>
  window.mub_fp.init({
    site_key: "YOUR_SITE_KEY",
    backend_url: "fp.sa.mubeen.ai"
  }).then(result => {
    console.log("Fingerprint initialized:", result);
  });
</script>

Versioning & Updates

The CDN URL is unversioned

https://cdn.mubeen.ai/fp/mub_fp.js is served unversioned — it updates in place, so a new build can change SDK behavior in production without any change on your side. For production stability:

Pin to a specific version once a versioned URL is available (ask Mubeen), or
Self-host a known-good build (Option 2 — Data Attribute Auto-Init) so you control when the SDK changes.

Review changes before adopting a new build.

Global API (`window.mub_fp`)

Method	Purpose
`init(config)`	Initialize and auto-collect. Returns a promise resolving to `{ deviceId, fingerprint, ... }`
`collect(config?)`	Collect fingerprint once, no persistence
`getDeviceId(config?)`	Return the persisted device ID (mints one if missing)
`testConnectivity(endpoint?)`	Ping the collection endpoint
`checkSupport()`	Report browser-capability flags
`create(config)`	Build a `Fingerprinter` instance without auto-collecting — returns the instance for fine control

Configuration Presets

window.mub_fp.Config.minimal — smallest payload, only cheap collectors
window.mub_fp.Config.basic — default everyday set
window.mub_fp.Config.comprehensive — every collector, BACKGROUND tier included

Instance API

Returned by create(config) when you need imperative control.

const fp = await window.mub_fp.create({
  site_key: "YOUR_SITE_KEY",
  backend_url: "fp.sa.mubeen.ai"
});

await fp.collectNow();          // Force immediate collection
await fp.getDeviceId();         // Read current device ID
await fp.rotateDeviceId();      // Mint a fresh device ID

fp.updateConfig({ ... });       // Patch config at runtime
fp.getConfig();                 // Inspect current config
fp.getStatus();                 // Lifecycle + collector readiness
fp.destroy();                   // Release listeners, stop behavioral loop

Advanced Configuration

Pass an object to init() or create(). Only override what you need — defaults cover most cases.

window.mub_fp.init({
  site_key: "YOUR_SITE_KEY",

  userAgent: {
    enabled: true,
    attributes: {
      userAgentString: true,
      platform: true,
      language: true,
      languages: true,
      cookieEnabled: true
    }
  },

  deviceId: {
    enabled: true,
    storage: "both",              // "cookie" | "localStorage" | "both"
    expiration: 365,              // days
    cookieDomain: ".yourdomain.com",
    cookieName: "__fp_device_id",
    storageKey: "__fp_device_id"
  },

  // Backend base URL — REQUIRED. The library appends `/v1/web/collect` and
  // `/v1/web/collect-update` automatically. Accepts either a bare domain
  // or a full URL; `https://` is assumed when no scheme is given.
  backend_url: "fp.sa.mubeen.ai",

  execution: {
    delay: 100,                   // ms after load before starting
    useRequestIdleCallback: true
  }
});

Regional Endpoints

Pick the region closest to your users — or the region required by your data-residency obligations. Data collected by each endpoint is stored in that region.

Region	`backend_url`	Data residency
Germany (EU)	`fp.de.mubeen.ai`	Frankfurt — default, suits GDPR
Saudi Arabia	`fp.sa.mubeen.ai`	Riyadh — suits PDPL / KSA residency
Zain Cloud (KSA)	`fp.efm.zaincloud.com.sa`	Zain-specific deployment — use if your keys were issued for Zain

// EU / GDPR workloads (default)
window.mub_fp.init({ site_key: "YOUR_SITE_KEY", backend_url: "fp.de.mubeen.ai" });

// KSA workloads — keep data in Saudi Arabia
window.mub_fp.init({ site_key: "YOUR_SITE_KEY", backend_url: "fp.sa.mubeen.ai" });

Backend URL formats

All of these are accepted and resolve to the same endpoints:

backend_url: "fp.sa.mubeen.ai"           // bare domain → https:// prefixed
backend_url: "https://fp.sa.mubeen.ai"   // full URL
backend_url: "https://fp.sa.mubeen.ai/"  // trailing slash stripped
backend_url: "http://localhost:8080"     // http preserved (for local dev)

backend_url has no default — you must supply it on every initialization. The library then derives:

Initial collect → <backend_url>/v1/web/collect
Behavioral updates → <backend_url>/v1/web/collect-update

navigator.doNotTrack is respected when the privacy.respectDNT config flag is on
No PII is collected by default
For GDPR: delay init() until the user accepts tracking, or call destroy() on withdrawal
Cross-subdomain device ID requires deviceId.cookieDomain set to the shared parent (for example, .yourdomain.com)

Server Expectations

The library ships to the endpoint derived from backend_url. The server replies with:

{
  "success": true,
  "deviceId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Fingerprint collected successfully"
}

After the initial collect, the library streams 10 behavioral updates over ~20 seconds to /v1/web/collect-update. A 5-minute per-device cooldown follows each behavioral cycle.

Troubleshooting

window.mub_fp is undefined

The <script> tag failed to load. Check the network tab and your Content Security Policy (script-src).

No network request to /v1/web/collect

Likely causes:

site_key is missing
execution.delay is too large
navigator.doNotTrack is enabled and privacy.respectDNT is on

Device ID changes every visit

Cookie is blocked (third-party contexts, Safari ITP) and localStorage was cleared. Set deviceId.cookieDomain and confirm the page runs in a first-party context.

CORS errors

The server must allow the site origin on POST to the collect endpoints.

Next Steps

Client-Side Integration (HTML) — simpler quickstart
Client-Side Integration (React) — React hook-based integration
Server-Side Integration — validate the device ID server-side

Client-Side SDK Reference (Advanced)

Prerequisites​

Install Flavors​

Option 1 — One-Line (recommended)​

Option 2 — Data Attribute Auto-Init​

Option 3 — Manual Initialization​

Versioning & Updates​

Global API (window.mub_fp)​

Configuration Presets​

Instance API​

Advanced Configuration​

Regional Endpoints​

Backend URL formats​

Consent & Privacy​

Server Expectations​

Troubleshooting​

Next Steps​