Overview and Resources

This document describes the frontend configuration and APIs for the GeeTest Device Fingerprint SDK.

Environment Requirements

This guide uses the loadGeeGuard() Promise API. For IE10/IE11, note the following:

• IE10/IE11 do not support Promise natively. Load a Promise polyfill before calling loadGeeGuard().
• The Promise chaining example below uses ES5 syntax and can be used after loading the polyfill. The Async/Await example must be transpiled by your build tools into code compatible with IE10/IE11.

Installation

Include the Initialization Script

Download URL for gd.js: https://static.geetest.com/g5/gd.js

If you need to support IE10/IE11, load a Promise polyfill before calling loadGeeGuard(). Browsers with native Promise support do not require an additional polyfill.

<script src="https://static.geetest.com/g5/gd.js"></script>

gd.js is updated periodically. We recommend loading it directly from the hosted URL.

Configuration Parameters

Pass the configuration as the config object in loadGeeGuard(config).

Only appId is required. All other parameters are optional. Leave them at their defaults unless your integration requires a specific setting.

Initialize the SDK

1. Register an application in the GeeTest console to obtain an AppID.
2. Pass the AppID as appId when calling loadGeeGuard().
3. Call instance.get() to obtain the token data, using either example below.

loadGeeGuard() returns a Promise that resolves to an instance. The token result is returned by instance.get(), which also returns a Promise.

In these examples, sendToServer represents your own application backend submission function. Implement it according to your application’s API.

Option 1: Promise Chaining

loadGeeGuard({
    appId: 'your_app_id'
})
.then(function (instance) {
    return instance.get();
})
.then(function (result) {
    console.log('Status:', result.status);
    console.log('Fallback status:', result.data.offline);
    var geeToken = result.data.offline ? result.data.geeToken : result.data.respondedGeeToken;
    console.log('Token to submit:', geeToken);
    console.log('Device ID:', result.data.local_id);

    // Send the token and data to your application backend.
    sendToServer(geeToken, result.data);
})
.catch(function (error) {
    console.error('Failed to obtain token:', error);
});

Option 2: Async/Await

async function getFingerprint() {
    try {
        const instance = await loadGeeGuard({
            appId: 'your_app_id'
        });

        const result = await instance.get();

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

            // Send the token and business data to your application backend.
            await sendToServer(token, result.data);
        }
    } catch (error) {
        console.error('Failed to obtain token:', error);
    }
}

Response Structure

The following shows the field types for successful and error responses:

// Successful response
{
    status: 'success',
    data: {
        offline: boolean,           // Whether the SDK has fallen back to a local token
        respondedGeeToken: string,  // Server-issued token; empty when using fallback
        geeToken: string,           // Locally generated encrypted token
        local_id: string            // Device identifier
    }
}

// Error response
{
    status: 'error',
    data: {
        code: -50101,
        msg: string
    }
}

Frequently Asked Questions

When is respondedGeeToken empty?

When the SDK automatically falls back to a local token, respondedGeeToken is an empty string and the returned offline field is true. In this case, submit geeToken to your application backend.

offline is provided by the SDK in the returned data and only indicates whether the SDK has fallen back to a local token. It is not an integration configuration parameter and must not be passed to loadGeeGuard().

Query the Result

Submit the GeeToken together with your business data to your application backend. Your backend then queries the GeeTest Device Fingerprint service for the result.