Device Fingerprint
Deployment

Web Integration

Installation, initialization, and token retrieval for the Web SDK

Overview and Resources

This document describes the configuration items and APIs used by the Device Fingerprint Web SDK.

Environment Requirements

ItemDescription
CompatibilityIE9+, Chrome, Firefox, Safari, Opera, major mobile browsers, and embedded WebViews on iOS and Android

The loadGeelabGuard() Promise API requires Promise support. For IE, include a Promise polyfill. The initGeelabGuard() callback API is supported in all browsers.

Installation

Include the Initialization JS

Download URL for gld.js: https://static.geelabapi.com/geelab-fp/gld.js

<script src="https://static.geelabapi.com/geelab-fp/gld.js"></script>
<!-- This JS file is updated from time to time. Using the online URL directly is recommended. -->

Configuration Parameters

The configuration parameters described here refer to the config object passed to the initialization method.

Except for appId, all parameters are optional. Unless you clearly understand the behavior, avoid setting additional parameters because they may introduce side effects in some scenarios.

ParameterRequiredTypeDescriptionDefaultAllowed Values
appIdYstringDevice Fingerprint Verification ID obtained from the Geelab dashboard
protocolNstringProtocol prefix. In local or hybrid development, this must be set manually.Uses the current page protocol by defaulthttp://, https://
apiServersNstring[]Service domain names corresponding to the region selected in the dashboardUses the global region service domain by defaultSee the region mapping below
networkTimeoutNnumberTimeout for each individual request during the verification process7000 (ms)Positive integer greater than 0
customInfoNstringA 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:

RegionapiServers Value
🌏 Global['riskct-global.geelabapi.com']
🇪🇺 Europe['riskct-eu.geelabapi.com']
🇺🇸 North America['riskct-na.geelabapi.com']
// North America region
loadGeelabGuard({
    appId: 'your_app_id',
    protocol: 'https://',
    apiServers: ['riskct-na.geelabapi.com']
});

Usage

gld.js provides two integration methods. You can choose either based on your needs, and both methods can coexist on the same page.

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

Basic Usage

loadGeelabGuard({
    appId: 'your_app_id',
    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);

    // 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({
            appId: 'your_app_id',
            protocol: 'https://'
        });

        const result = await instance.get();

        if (result.status === 'success') {
            const { respondedGeeToken } = result.data;
            console.log('Server token:', respondedGeeToken);

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

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({
    appId: 'your_app_id',
    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 fetch('/api/submit', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({ gee_token: result.data.respondedGeeToken })
            });
        })
        .catch(function(error) {
            console.error('Error:', error);
        });
});

Return Format

// Successful response example
{
    status: 'success',
    data: {
        respondedGeeToken: string,  // Token returned by the server
        local_id: string            // Unique device identifier
    }
}

// Failed response example
{
    status: 'error',
    data: {
        code: number,   // Error code, such as -50101
        msg: string     // Error message, such as "not app_id"
    }
}

Method 2: Callback API

Use the initGeelabGuard() function to retrieve the result through a callback. This method is compatible with all browsers, including IE9+.

initGeelabGuard({
    appId: 'your_app_id',
    protocol: 'https://'
}, function(data) {
    if (data.status === 'success') {
        // Token retrieved successfully, proceed with business logic
        console.log('GeeToken:', data.data.gee_token);
    } else {
        // Request failed
        console.error('Error code:', data.data.code);
        console.error('Error message:', data.data.msg);
    }
});

Return Format

// Successful response example
{
    "status": "success",
    "data": {
        "gee_token": "znqlmmF+XoPIKni/..."
    }
}

// Failed response example
{
    "status": "error",
    "data": {
        "code": -50101,
        "msg": "not app_id"
    }
}

API Comparison

FeatureinitGeelabGuard() (Callback)loadGeelabGuard() (Promise)
Invocation styleCallback functionPromise / async-await
Preloading supportNo, must wait for the callbackYes, can be loaded in advance
Instance reuseNot supported, must call againSupported, the same instance can call get() multiple times
Error handlingCheck callback data manuallyPromise reject / try-catch
Browser compatibilityAll browsers, including IE9+Requires Promise support (IE needs a polyfill)

FAQ

Q1: When is respondedGeeToken empty?

A: respondedGeeToken is an empty string when the network request fails.


Q2: Can loadGeelabGuard() and initGeelabGuard() be used at the same time?

A: Yes. The two methods are fully compatible and can coexist on the same page. They share the same underlying JS resource and will not load it twice.


Q3: How can older browsers use the Promise API?

A: If you need to use loadGeelabGuard() in browsers that do not support Promise (such as IE), include a Promise polyfill first.

Otherwise, use the initGeelabGuard() callback API.


Retrieving Results

Submit the GeeToken together with your business data to your server, and then have your server query the result from the Geelab Device Fingerprint service. Please refer to the server-side integration documentation.