JavaScript

Integrate Geelab Device Fingerprint v2 into Web and H5 applications with the JavaScript SDK

Overview and Resources

This document provides a detailed description of all frontend-related configuration items and APIs for Device Fingerprint Verification.

Environment Requirements

Item
Compatibility	IE10+, Chrome, Firefox, Safari, Opera, major mobile browsers, and embedded WebViews on iOS and Android

Note: The loadGeelabGuard() Promise API requires native Promise support; for browsers such as IE10, load a Promise polyfill before gld_v2.js.

Installation

Include the Initialization JS

<!-- Browsers without Promise support, such as IE10, must load this first. -->
<script src="./promise-polyfill.min.js"></script>
<script src="./gld_v2.js"></script>

After including gld_v2.js, call loadGeelabGuard() to obtain an instance, then call instance.get() to obtain the device token. Customer pages do not need to call the underlying service endpoints directly.

React, Vue 3, Angular, Next.js, Svelte, and other frontend frameworks can reuse the script-based integration on this page; no npm SDK package is required.

Shared Client Module for Frameworks

In a framework project, centralize SDK initialization and token retrieval in one client module to avoid initializing the SDK more than once:

// src/geeGuardClient.js
let instancePromise;

const config = {
  publicKey: 'your_public_key',
  protocol: 'https://',
  apiServers: ['riskct-global.geelabapi.com'],
};

export function preloadGeeGuard() {
  if (typeof window === 'undefined') {
    return Promise.reject(new Error('GeeLabGuard can only run in a browser'));
  }
  if (typeof window.loadGeelabGuard !== 'function') {
    return Promise.reject(new Error('GeeLabGuard SDK was not loaded correctly'));
  }

  if (!instancePromise) {
    const pending = window.loadGeelabGuard(config);
    instancePromise = pending;
    pending.catch(function () {
      if (instancePromise === pending) instancePromise = undefined;
    });
  }

  return instancePromise;
}

export async function getGeeToken() {
  const instance = await preloadGeeGuard();
  const result = await instance.get();
  if (!result || result.status !== 'success' || !result.data) {
    throw new Error('GeeLabGuard did not return a successful result');
  }

  const { respondedGeeToken, geeToken, offline, local_id } = result.data;
  const token = respondedGeeToken || geeToken;
  if (!token) throw new Error('GeeLabGuard did not return a usable GeeToken');

  return { token, offline: Boolean(offline), localId: local_id };
}

TypeScript projects also need a global declaration for the browser script:

// src/geelabguard.d.ts
export {};

interface GeeGuardInstance {
  get(): Promise<{
    status: 'success';
    data: {
      offline: boolean;
      respondedGeeToken: string;
      geeToken: string;
      local_id: string;
    };
  }>;
}

declare global {
  interface Window {
    loadGeelabGuard(config: {
      publicKey: string;
      protocol?: 'http://' | 'https://';
      apiServers?: string[];
      networkTimeout?: number;
      customInfo?: string;
    }): Promise<GeeGuardInstance>;
  }
}

Configuration Parameters

The configuration parameters described here refer to the config object (a key-value structure) passed when calling Device Fingerprint Verification. In other words, these are the optional parameters in the first argument of the initialization function.

Except for publicKey, all parameters are optional. Unless you clearly understand how to use them, do not set the other parameters below, as they may cause side effects in different scenarios.

Parameter	Required	Type	Description	Default	Allowed Values
publicKey	Y	string	Public integration identifier obtained from the Geelab dashboard
protocol	N	string	Protocol prefix. In local or hybrid development, this must be set manually.	Uses the current page protocol by default	`http://`, `https://`
apiServers	N	string[]	Service domain names corresponding to the region selected in the dashboard	Uses the global region service domain by default	See the region mapping below
networkTimeout	N	number	Timeout for the `client_report` request	7000 (ms)	Positive integer greater than 0
customInfo	N	string	A unique serial number or credential for the current business request, used to prevent GeeToken from being detached from the business scenario

Region Mapping

Configure apiServers based on the region selected in the dashboard:

Region	`apiServers` Value
🌏 Global	`['riskct-global.geelabapi.com']`
🇪🇺 Europe	`['riskct-eu.geelabapi.com']`
🇺🇸 North America	`['riskct-na.geelabapi.com']`

// North America region
loadGeelabGuard({
    publicKey: 'your_public_key',
    protocol: 'https://',
    apiServers: ['riskct-na.geelabapi.com']
});

Usage

Use loadGeelabGuard() for the integration.

Promise API

Use the loadGeelabGuard() function. It returns a Promise and supports preloading as well as async/await.

Basic Usage

loadGeelabGuard({
    publicKey: 'your_public_key',
    protocol: 'https://'
}).then(instance => instance.get()).then(result => {
    console.log('Status:', result.status);
    console.log('Device ID:', result.data.local_id);
    console.log('Server Token:', result.data.respondedGeeToken);
    console.log('Local Token:', result.data.geeToken);
    console.log('Offline Mode:', result.data.offline);

    // Send the token to your business server
    sendToServer(result.data);
}).catch(error => {
    console.error('Failed to retrieve fingerprint:', error);
});

Async/Await Usage

async function getFingerprint() {
    try {
        const instance = await loadGeelabGuard({
            publicKey: 'your_public_key',
            protocol: 'https://'
        });

        const result = await instance.get();

        if (result.status === 'success') {
            const { offline, respondedGeeToken, geeToken, local_id } = result.data;

            if (offline) {
                // Offline mode: use the local token geeToken
                console.log('Offline mode, use local token:', geeToken);
            } else {
                // Online mode: use the server token respondedGeeToken
                console.log('Online mode, use server token:', respondedGeeToken);
            }

            await sendToServer(result.data);
        }
    } catch (error) {
        console.error('Failed to retrieve fingerprint:', error);
    }
}

Preloading Usage (Recommended)

Preloading improves user experience by starting initialization as soon as the page loads. When the user performs an action, the token can be retrieved immediately without extra waiting.

// Start preloading immediately when the page loads
const geeGuardPromise = loadGeelabGuard({
    publicKey: 'your_public_key',
    protocol: 'https://'
});

// Retrieve the token directly when the user submits the form
document.getElementById('submitBtn').addEventListener('click', function() {
    geeGuardPromise.then(function(instance) {
            return instance.get();
        }).then(function(result) {
            // Submit the form and token to the server
            return sendToServer({
                gee_token: result.data.respondedGeeToken || result.data.geeToken
            });
        }).catch(function(error) {
            console.error('Error:', error);
        });
});

Fallback to GeeToken

When the SDK's online request succeeds, submit the server-provided respondedGeeToken. If the network request fails and the SDK enters offline mode, respondedGeeToken is empty; fall back to the locally generated geeToken.

loadGeelabGuard({
    publicKey: 'your_public_key',
    protocol: 'https://'
}).then(function(instance) {
    return instance.get();
}).then(function(result) {
    if (!result || result.status !== 'success' || !result.data) {
        throw new Error('Failed to retrieve the device fingerprint');
    }

    // Prefer respondedGeeToken online and use geeToken after offline fallback
    var geeToken = result.data.respondedGeeToken || result.data.geeToken;

    if (!geeToken) {
        throw new Error('No usable GeeToken was returned');
    }

    return sendToServer({
        gee_token: geeToken,
        offline: result.data.offline
    });
}).catch(function(error) {
    console.error('Failed to retrieve or submit the token:', error);
});

When offline: true, the submitted value is the locally generated geeToken. Send the offline flag to your business server or record it in your logs so the token source remains visible.

Return Format

// Successful response example
{
    status: 'success',
    data: {
        offline: boolean,           // Whether the request is in offline mode
        respondedGeeToken: string,  // Token returned by the server (empty string in offline mode)
        geeToken: string,           // Locally generated encrypted token
        local_id: string            // Unique device identifier
    }
}

// Failed response example
{
    status: 'error',
    data: {
        code: number|string,   // Error code, such as 60001, 60100, or 60101
        msg: string     // Error message, such as "integration not found"
    }
}

FAQ

Q1: When is `respondedGeeToken` empty?

A: respondedGeeToken is an empty string in the following case:

The network request fails and the SDK automatically falls back to offline mode

In this case, submit geeToken (the locally generated token) to your server instead.

Q2: How can older browsers use the Promise API?

A: For browsers without Promise support, such as IE10, load the delivered promise-polyfill.min.js before gld_v2.js. Modern browsers can load gld_v2.js directly.

Retrieving Results

Submit the GeeToken together with your business data to your business server and process it according to your server-side workflow.

For the server-side query flow, see Server API.

JavaScript

On this page