Kade Web SDK

Overview

The SDK exposes a global GeoFenceSDK constructor. It encrypts ping and server fingerprint payloads, manages location collection, and supports one-off or continuous checks.

Install

Add the CDN bundle before your application code. The published bundle creates window.GeoFenceSDK.

<script src="https://sdk.videntrix.com/latest.js"></script>

Current production bundle size: ~113 KB minified / ~38 KB gzipped.

Quick start

Initialize once, request location from a user gesture when your experience needs an explicit permission prompt, then send a ping.

const sdk = new GeoFenceSDK({
  apiToken: 'your-api-token',
  regionId: 123
});

sdk.onError((error, context) => {
  console.error(`Kade SDK error in ${context}`, error);
});

// Recommended at startup; ping() also initializes automatically.
await sdk.init();

// Call from a click or tap handler if permission may need to be prompted.
document.querySelector('#verify-location').addEventListener('click', async () => {
  await sdk.requestLocationPermission();

  const result = await sdk.ping({
    userId: 'player-123',
    source: 'login',
    email: 'player@example.com'
  });

  if (result.blocked) {
    console.log('Blocked:', result.code, result.message);
  } else {
    console.log('Inside:', result.inside);
    console.log('Area:', result.area?.name);
  }
});

Core API

These methods form the documented host-facing surface used by browser integrations.

Location permissions

Browsers are most reliable when permission is requested in direct response to a user click or tap.

const allowButton = document.querySelector('#allow-location');

allowButton.addEventListener('click', async () => {
  try {
    const location = await sdk.primeLocation();
    console.log(location.latitude, location.longitude, location.accuracy);
  } catch (error) {
    console.error('Location was unavailable', error);
  }
});

Network-only estimate

const estimate = await sdk.estimateLocation({ userId: 'player-123' });

if (estimate.province || estimate.country) {
  console.log(estimate.province?.code, estimate.country?.code);
} else {
  // No answer: feature disabled, insufficient beacons, or degraded scoring.
}

Email evaluation

Submit registration identity data for server-side fraud evaluation. The verdict is available to operators through backoffice or webhooks, never returned to the browser.

await sdk.evaluateEmail({
  email: 'new.user@example.com',
  firstName: 'New',
  lastName: 'User',
  userId: 'player-123'
});

Configuration

Common configuration

PingOptions

interface PingOptions {
  userId?: string;
  silent?: boolean;
  skipLocation?: boolean;
  source?: string;
  regionId?: number;
  email?: string;
  firstName?: string;
  lastName?: string;
}

• silent requests a minimal success response after server processing.
• skipLocation avoids browser geolocation for the SDK instance's session.
• source is a free-form flow tag such as login or deposit.
• regionId overrides the instance region for that ping.
• email, firstName, and lastName associate identity fields with the server-side client record.

Advanced location tuning

Advanced options include locationMaxAge, locationMaxStalenessRadius, locationMaxAgeCeilingMs, locationMaxAgeAssumedSpeedMps, locationRecoveryAfterMs, locationRecoveryMinIntervalMs, locationRecoveryFailureCooldownMs, locationRecoveryMaxAccuracy, and locationFixSendCapMs. Their defaults coordinate caching, movement assumptions, and recovery throttling and should normally remain unchanged. Adjust them only with Kade integration guidance.

Response handling

ping() resolves to PingResponse. A matched area is represented by PingArea { id, name }.

interface PingArea {
  id: number;
  name: string;
}

interface PingResponse {
  inside: boolean;
  status: number;
  message?: string;
  code?: GeoFenceResponseCode;
  interval: number;
  distanceToBorder: number;
  regionId?: number;
  area?: PingArea;
  blocked?: boolean;
  clientId?: string;
}

const response = await sdk.ping({ userId: 'player-123' });

if (response.blocked) {
  handleBlocked(response.code, response.message);
} else if (response.inside) {
  console.log(`Matched ${response.area?.name ?? 'configured area'}`);
} else {
  console.log(`Outside by ${response.distanceToBorder} metres`);
}

Known block response codes

The response type also permits future string codes. Handle unknown codes as blocked when blocked === true.

Request signing

When signingSecret is configured, the SDK applies HMAC-SHA256 only to encrypted ping() and server fingerprint requests.

const sdk = new GeoFenceSDK({
  apiToken: 'your-api-token',
  signingSecret: 'your-workspace-signing-secret'
});

Message and header format

The signed message is timestamp.nonce.JSON.stringify(encryptedPayload). The returned signature header has this format:

X-Signature: t=1708012345678,n=a1b2c3d4e5f6...,s=64_character_hex_hmac
X-Request-Time: 1708012345678

The timestamp and random nonce are generated by the signing function. Signing failures are best-effort and do not change the encryption applied to these payloads.

TypeScript

The script and declaration files are separate downloads. Save the declaration in your project so builds do not depend on a network type reference.

curl -o types/geofence-sdk.d.ts \
  https://sdk.videntrix.com/geofence-sdk.d.ts

Add it to your compilation with a local reference:

/// <reference path="./types/geofence-sdk.d.ts" />

const sdk = new GeoFenceSDK({ apiToken: 'your-api-token' });
const result: GeoFenceSDK.PingResponse = await sdk.ping({
  userId: 'player-123'
});
const localFingerprint: GeoFenceSDK.FingerprintResult =
  await sdk.getFingerprint();

Key exported types

GeoFenceConfig, PingOptions, PingResponse, PingArea, FingerprintResult, FingerprintServerResponse, EvaluateEmailOptions, GeoLocation, and LocationEstimateResult.

Playground

Exercise the bundle loaded by this page. Credentials entered here are used only by the in-page SDK instance.

Best practices

• Fingerprint and static markers are included on every ping.
• Treat silent responses as acknowledgement, not as a geofence verdict.
• Branch on blocked first and tolerate new response-code strings.
• Keep advanced recovery tuning at its defaults unless Kade advises a change for your integration.