Swarm SDK

GeoComply Integration

Developer reference for getGeoComplyLicense and geoComplyGeolocationCheck from @softconstruct/betchain-core-client.

Introduction

GeoComply is a geolocation compliance service used to verify that users are physically located in a permitted jurisdiction before sensitive actions (login, bet placement, registration) are processed. The integration is spread across two layers:

Action-time verification — triggered on demand when a user initiates an action such as login. A license token is fetched from the backend, the GeoComply HTML5 client performs a device-side geolocation measurement, and the resulting token is forwarded to the action.
Background monitoring — a periodic re-check that runs while the user is authenticated, plus an automatic check whenever the user's IP address changes. Uses geoComplyGeolocationCheck to validate the token server-side and enforces logout if the location is rejected.

Both paths depend on the two SDK functions documented here: getGeoComplyLicense (obtains the license token from the backend) and geoComplyGeolocationCheck (validates a geolocation token against the backend after the device-side handshake completes).

getGeoComplyLicense

.ts

import { getGeoComplyLicense } from '@softconstruct/betchain-core-client'

Makes a backend request to retrieve the GeoComply license string required to initialise a geolocation session with the GeoComply HTML5 client. This is always the first step of any GeoComply flow — the returned token must be passed to the HTML5 client before a geolocation request can be made.

Parameters

Parameter	Type	Description
params	{}	Empty object. Reserved for future filter parameters.

Return value

Field	Type	Description
data.details.LicenseString	string	The license token passed to the HTML5 client.

Usage example

.ts
import {
  getGeoComplyLicense
} from '@softconstruct/betchain-core-client';

const {
  data: {
    details: {
      LicenseString: token
    } = {}
  } = {},
  error
} =
await getGeoComplyLicense({});

if (!token) {
  // abort — cannot proceed without a valid license
  return;
}

// pass the token to the GeoComply HTML5 client
const geoComplyToken = await geoComplyClient.setLicenseAndRequest({
  token,
  reason,
  userName,
});

Behaviour notes

If the response does not contain LicenseString, the flow must be aborted — the HTML5 client cannot operate without a valid license.
The license token is short-lived; it must be obtained fresh for every new GeoComply session — it is never cached locally.
The error field in the response is populated on failure but the function itself does not throw.

geoComplyGeolocationCheck

.ts

import { geoComplyGeolocationCheck } from '@softconstruct/betchain-core-client'

Sends the geolocation token produced by the GeoComply HTML5 client to the backend for server-side validation. The backend verifies the token and responds with a success/failure result. This is the backend's authoritative verdict on whether the user's location is permitted.

Parameters

Parameter	Type	Required	Description
locationToken	string	Yes	The geolocation token returned by the GeoComply HTML5 client after a successful device-side geolocation handshake.

Return value

Field	Type	Description
data.details.IsSuccess	boolean	true = user is in an allowed jurisdiction
data.details.ErrorMessage	string (optional)	Localisation key or message shown on failure.

Usage example

.ts
import {
  geoComplyGeolocationCheck
} from '@softconstruct/betchain-core-client';

const {
  data: {
    details: {
      IsSuccess: isSuccess,
      ErrorMessage: errorMessage
    } = {}
  } = {},
} = (await geoComplyGeolocationCheck({
  locationToken: geoComplyToken
})) || {};

if (!isSuccess) {
  // user's location is not permitted — show error and log out
  showError(errorMessage || 'geocomply_logout');
  logout();
}

Behaviour notes

If IsSuccess is false, the consuming application should immediately revoke the user's session.
The ErrorMessage value is intended to be used as a localisation key. If absent, a safe fallback key such as 'geocomply_logout' should be displayed.
This function is used exclusively in the background monitoring path. In the action-triggered path (login, bet placement), the backend validates the geolocation token as part of the main action — no separate call to geoComplyGeolocationCheck is needed.

GeoComply HTML5 Client

The GeoComply HTML5 client is a browser-side wrapper around window.GcHtml5 — the global object injected by the GeoComply SDK script. It sits between the two SDK functions: after getGeoComplyLicense provides a license token, the HTML5 client performs the actual device-side geolocation measurement and produces thegeoComplyToken that is subsequently validated by geoComplyGeolocationCheck.

.ts

const client = window.GcHtml5.createClient();

initialize()

Must be called once on application load before any geolocation requests are made. Dynamically loads the GeoComply SDK script, creates the client instance, and registers the IP-tracking callbacks.

Signature

.ts

initialize({
  checkGeolocation?: (params: { reason: string }) => void | Promise<void>
}): Promise<void>

What it does

Step	Description
Load SDK script	Dynamically injects the GeoComply script into the page. Throws if window.GcHtml5 is not available after loading.
Create client	this.client = window.GcHtml5.createClient() — stores the client instance used by all subsequent calls.
onMyIpSuccess	Registered on window.GcHtml5. Fires when the SDK detects an IP address change. Invokes the caller-supplied checkGeolocation callback with reason "IPCHANGE", then calls window.GcHtml5.ackMyIPSuccess() to acknowledge the event.
onMyIpFailure	Registered on window.GcHtml5. Fires on IP detection error — informational only, no action is taken.

Code sample

.ts

await loadGeoComplyScript();
if (!window.GcHtml5) {
  throw new Error('GeoComply client is not available.');
}
this.client = window.GcHtml5.createClient();
this.isInitialized = true;

window.GcHtml5.onMyIpSuccess = () => {
  if (!this.client) return;
  checkGeolocation?.({
    reason: 'IPCHANGE'
  });
  window.GcHtml5?.ackMyIPSuccess();
};

window.GcHtml5.onMyIpFailure = () => {
  console.error('GeoComply IP detection error');
};

setLicenseAndRequest()

The core method that configures the client for a geolocation session and triggers the device-side measurement. Returns a Promise that resolves with the geolocation token on success, or rejects on failure.

Signature

.ts

setLicenseAndRequest({
  token: string; // LicenseString from getGeoComplyLicense
  reason?: string; // reason code key, e.g. 'LOGIN'
  userName?: FieldValueType;
  handleLocationBlock?: () => void;
}): Promise<string>

Execution steps

Step	Description
setLicense(token)	Applies the license string obtained from getGeoComplyLicense.
setUserId(hash(userName))	Assigns a hashed user identifier to the session.
allowHint(true)	Permits the SDK to use a previously cached location as a hint to speed up measurement.
setReasonCode(REASON_CODE[reason])	Maps the string reason key to the SDK's internal numeric code.
startMyIpService({ resumable: true })	Starts the background IP tracking service. resumable: true keeps it running across multiple geolocation requests.
request({ acceptNoCoordinates: false })	Triggers the geolocation measurement. Coordinates are required.

Events

After request() is called, the outcome is communicated asynchronously through client.events — the event emitter exposed on the instance returned by window.GcHtml5.createClient(). Two events are relevant:

Event	Payload	Behaviour
'success'	token: string	Geolocation completed successfully. The Promise resolves with the token, which becomes the geoComplyToken passed to the action or to geoComplyGeolocationCheck.
'failed'	code: string, message?: string	Geolocation failed. The Promise rejects with { code, message }. If code is 611 (no coordinates available), handleLocationBlock is called before rejecting.

Code sample

.ts
return new Promise((resolve, reject) => {
  this.client?.setLicense(token);
  this.client?.setUserId(String(hash(userName)));
  this.client?.allowHint(true);

  if (reason) {
    this.client!.setReasonCode(this.client!.REASON_CODE[reason]);
  }

  window.GcHtml5?.startMyIpService({
    license: token,
    resumable: true
  });

  if (!this.client?.isActive()) return;

  this.client?.request({
    acceptNoCoordinates: false
  });

  this.client?.events
    .on('success', (token: string) => {
      resolve(token);
    })
    .on('failed', (code: string, message ? : string) => {
      if (Number(code) === 611) {
        handleLocationBlock?.
      (); // coordinates unavailable — caller handles UX
      }
      reject({
        code,
        message
      });
    });
});

stopIpTracking()

Stops the background IP tracking service started by startMyIpService. Should be called when the user logs out to release SDK resources and prevent stale IP-change events from firing.

.ts

if (window.GcHtml5) {
  window.GcHtml5.stopMyIpService();
}

Background Monitoring

Beyond action-triggered checks, GeoComply requires continuous monitoring while the user is authenticated. The consuming application is responsible for implementing this — the SDK provides the two functions needed: getGeoComplyLicense to start each check cycle and geoComplyGeolocationCheck to validate the result server-side.

When to run a background check

Trigger	Recommended action
Periodic interval (e.g. every 30 minutes)	Run a full check cycle with reason "INTERVAL" while the user is logged in.
User's IP address changes	Run a full check cycle with reason "IPCHANGE"; acknowledge the event to the GeoComply SDK.
User logs out	Stop the IP tracking service to release SDK resources.

Check cycle

Each background check follows the same three-step sequence as the action-triggered flow, but uses geoComplyGeolocationCheck for the server-side verdict instead of a business action:

.ts
// 1. get a fresh license token from the backend
const {
  LicenseString: token
} = await getGeoComplyLicense({});

// 2. device-side geolocation handshake
const geoComplyToken = await geoComplyClient.setLicenseAndRequest({
  token,
  reason,
  userName
});

// 3. server-side validation
const {
  data: {
    details: {
      IsSuccess: isSuccess,
      ErrorMessage: errorMessage
    } = {}
  } = {},
} = (await geoComplyGeolocationCheck({
  locationToken: geoComplyToken
})) || {};

// 4. enforce result — revoke session if location is not permitted
if (!isSuccess) {
  showError(errorMessage || 'geocomply_logout');
  logout();
}

geoComplyGeolocationCheck is only needed in background checks. When the geoComplyToken is attached to a business action (login, bet placement), the backend validates the token as part of that action — there is no need to call geoComplyGeolocationCheck separately.

Action-triggered Usage

For actions that require a geolocation proof (login, registration, bet placement), the consuming code defines an action callback that accepts a geoComplyToken parameter. The GeoComply flow runs first to obtain that token; the action is only dispatched once the token is available.

.ts

// the action callback receives the token produced by the GeoComply flow
const loginAction = ({
    geoComplyToken
  }: {
    geoComplyToken ? : string
  }) =>
  performLogin({
    password,
    userName,
    geoComplyToken, // proof of geolocation forwarded to the backend
  });

Location blocked (error code 611): If the GeoComply HTML5 client cannot obtain coordinates, it emits a failed event with code 611. The consuming application should intercept this case, inform the user, and prevent the action from being submitted.

Flows

Action-triggered (Login)

Periodic background check

IP address change

Reason Codes

Passed to the GeoComply HTML5 client's setReasonCode method. The client maps these string keys to its internal numeric codes via REASON_CODE[reason].

Value	When used
'LOGIN'	User submits login credentials
'INTERVAL'	Periodic background check
'IPCHANGE'	IP-change event detected by the GeoComply SDK
'REGISTRATION'	User completes registration

Error Handling

Error scenario	Where detected	User-visible effect
License fetch fails / empty LicenseString	getGeoComplyLicense response	Location coordinates unavailable
Location coordinates unavailable (code 611)	GeoComply HTML5 client failed event	Consuming application handles the blocked state
Generic SDK error during geolocation	GeoComply HTML5 client failed event	Error surfaced to the consuming application
Backend rejects location	geoComplyGeolocationCheck (IsSuccess: false) response	Error shown to user + session revoked (background monitoring path only)
GeoComply SDK unavailable on window	initialize()	None (silent); the triggered action is not dispatched

TypeScript Types

GeoComplyLicenseResponse

Returned by getGeoComplyLicense.

.ts
interface GeoComplyLicenseResponse {
  data: {
    details: {
      LicenseString: string;
    };
  };
}

GeolocationCheckResponse

Returned by geoComplyGeolocationCheck.

.ts
{
  data: {
    details: {
      IsSuccess: boolean;
      ErrorMessage ? : string;
    };
  };
}

ExecuteGeoComplyResult

Returned by the action callback after the full GeoComply flow completes.

.ts

interface ExecuteGeoComplyResult {
  code ? : number;
  hasError ? : boolean;
  isLocationBlocked ? : boolean;
  isTelegramVerificationNeeded ? : boolean | 0;
  response ? : {
    status ? : number;
    result ? : string;
    auth_token ? : string;
    details ? : {
      uid ? : number;Key ? : string; /* ... */
    };
  };
  loginResponse ? : GeoComplyResponse;
  result ? : CreateBetResultProps;
  handleLoginAfterRegister ? : () => Promise < {
    code ? : number
  } > ;
}