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
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.
| 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);
// 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 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 })
});
})
.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
| 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.