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
| Item | Description |
|---|---|
| Compatibility | IE9+, 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
<script src="./gld.js"></script>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.
| Parameter | Required | Type | Description | Default | Allowed Values |
|---|---|---|---|---|---|
| appId | Y | string | Device Fingerprint Verification ID 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 each individual request during the verification process | 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({
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.
Method 1: Promise API (Recommended)
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);
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({
appId: 'your_app_id',
protocol: 'https://'
});
const result = await instance.get();
if (result.status === 'success') {
const { offline, respondedGeeToken, geeToken, local_id } = result.data;
if (offline) {
console.log('Offline mode, use local token:', geeToken);
} else {
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({
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 || result.data.geeToken })
});
})
.catch(function(error) {
console.error('Error:', error);
});
});Fallback to GeeToken
When the SDK request succeeds online, submit the server-returned respondedGeeToken. If the request fails and the SDK enters offline mode, respondedGeeToken is empty; submit the locally generated geeToken instead.
loadGeelabGuard({ appId: 'your_app_id', protocol: 'https://' })
.then(instance => instance.get())
.then(result => {
if (!result || result.status !== 'success' || !result.data) {
throw new Error('Failed to retrieve fingerprint');
}
const geeToken = result.data.respondedGeeToken || result.data.geeToken;
if (!geeToken) throw new Error('No available GeeToken');
return fetch('/api/submit', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ gee_token: geeToken, offline: result.data.offline })
});
});offline: true means the submitted token is a local geeToken. Send this field to your server or record it in logs so the token source can be distinguished.
Return Format
// Successful response example
{
status: 'success',
data: {
offline: boolean, // Whether offline mode is in use
respondedGeeToken: string, // Server token; empty in offline mode
geeToken: string, // Locally generated encrypted token
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
| Feature | initGeelabGuard() (Callback) | loadGeelabGuard() (Promise) |
|---|---|---|
| Invocation style | Callback function | Promise / async-await |
| Preloading support | No, must wait for the callback | Yes, can be loaded in advance |
| Instance reuse | Not supported, must call again | Supported, the same instance can call get() multiple times |
| Error handling | Check callback data manually | Promise reject / try-catch |
| Browser compatibility | All 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.