Web 集成指南

概述及资源

本文用于详细说明设备指纹 Web 侧的配置项与调用接口。

环境需求

条目	说明
兼容性	IE9+、Chrome、Firefox、Safari、Opera、主流手机浏览器，以及 iOS / Android 上的内嵌 WebView

loadGeelabGuard() Promise API 需要浏览器支持 Promise。IE 需引入 polyfill。initGeelabGuard() 回调方式支持所有浏览器。

安装

引入初始化 JS

<script src="./gld.js"></script>

配置参数

这里说的配置参数，是指调用设备指纹时传入的 config 对象，也就是初始化函数第一个参数中的可选配置项。

除了 appId，其它参数都属于可选项。除非明确知道其作用，否则不建议额外设置，以免在不同场景下引入副作用。

参数	必填	类型	说明	默认值	可选值
appId	Y	string	设备验 id，Geelab 后台申请得到
protocol	N	string	协议头，本地或混合开发一定要手动设置	默认取当前页面协议头	`http://`、`https://`
apiServers	N	string[]	根据控制台选择的地域配置对应的服务域名	默认使用全球地域服务域名	见下方地域配置
networkTimeout	N	number	设置验证过程中单个请求超时时间	7000（ms）	大于0的整数
customInfo	N	string	唯一标记本次业务的流水号或凭证，用于防止 GeeToken 从业务场景剥离

地域配置

请根据您在控制台选择的地域配置对应的 apiServers：

地域	apiServers 配置
🌏 全球	`['riskct-global.geelabapi.com']`
🇪🇺 欧洲	`['riskct-eu.geelabapi.com']`
🇺🇸 北美	`['riskct-na.geelabapi.com']`

// 北美地域
loadGeelabGuard({
    appId: 'your_app_id',
    protocol: 'https://',
    apiServers: ['riskct-na.geelabapi.com']
});

调用方式

gld.js 提供两种调用方式，可按需选择，两种方式可以在同一页面共存。

方式一：Promise API（推荐）

使用 loadGeelabGuard() 函数，返回 Promise，支持预加载和 async/await 语法。

基础用法

loadGeelabGuard({
    appId: 'your_app_id',
    protocol: 'https://'
})
.then(instance => instance.get())
.then(result => {
    console.log('状态:', result.status);
    console.log('设备ID:', result.data.local_id);
    console.log('服务端令牌:', result.data.respondedGeeToken);
    console.log('本地令牌:', result.data.geeToken);
    console.log('是否离线模式:', result.data.offline);

    // 将 token 发送到业务服务器
    sendToServer(result.data);
})
.catch(error => {
    console.error('获取失败:', error);
});

Async/Await 用法

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('离线模式，使用本地令牌:', geeToken);
            } else {
                console.log('在线模式，使用服务端令牌:', respondedGeeToken);
            }

            await sendToServer(result.data);
        }
    } catch (error) {
        console.error('获取失败:', error);
    }
}

预加载用法（推荐）

预加载可以提升用户体验，在页面加载时即开始初始化，用户操作时直接获取 token，无需等待。

// 页面加载时立即预加载
const geeGuardPromise = loadGeelabGuard({
    appId: 'your_app_id',
    protocol: 'https://'
});

// 用户提交表单时直接获取 token
document.getElementById('submitBtn').addEventListener('click', function() {
    geeGuardPromise
        .then(function(instance) {
            return instance.get();
        })
        .then(function(result) {
            // 提交表单及 token 到服务器
            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);
        });
});

降级使用 GeeToken

SDK 在线请求成功时，应优先提交服务端返回的 respondedGeeToken。当网络请求失败并自动进入离线模式时，respondedGeeToken 为空，此时应降级提交本地生成的 geeToken。

loadGeelabGuard({ appId: 'your_app_id', protocol: 'https://' })
    .then(instance => instance.get())
    .then(result => {
        if (!result || result.status !== 'success' || !result.data) {
            throw new Error('获取设备指纹失败');
        }

        const geeToken = result.data.respondedGeeToken || result.data.geeToken;
        if (!geeToken) throw new Error('未获取到可用的 GeeToken');

        return fetch('/api/submit', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ gee_token: geeToken, offline: result.data.offline })
        });
    });

offline: true 表示当前提交的是本地 geeToken。建议将该字段一并传给业务服务端或记录到日志中，以便区分 Token 来源。

返回格式

// 请求成功返回示例
{
    status: 'success',
    data: {
        offline: boolean,           // 是否为离线模式
        respondedGeeToken: string,  // 服务端返回的令牌，离线时为空字符串
        geeToken: string,           // 本地生成的加密令牌
        local_id: string            // 设备唯一标识
    }
}

// 请求失败返回示例
{
    status: 'error',
    data: {
        code: number,   // 错误码，如 -50101
        msg: string     // 错误信息，如 "not app_id"
    }
}

方式二：回调 API

使用 initGeelabGuard() 函数，通过回调函数获取结果，兼容所有浏览器（包括 IE9+）。

initGeelabGuard({
    appId: 'your_app_id',
    protocol: 'https://'
}, function(data) {
    if (data.status === 'success') {
        // 获取到 token，处理业务逻辑
        console.log('GeeToken:', data.data.gee_token);
    } else {
        // 请求失败
        console.error('错误码:', data.data.code);
        console.error('错误信息:', data.data.msg);
    }
});

返回格式

// 请求成功返回示例
{
    "status": "success",
    "data": {
        "gee_token": "znqlmmF+XoPIKni/..."
    }
}

// 请求失败返回示例
{
    "status": "error",
    "data": {
        "code": -50101,
        "msg": "not app_id"
    }
}

两种 API 对比

特性	`initGeelabGuard()`（回调）	`loadGeelabGuard()`（Promise）
调用方式	回调函数	Promise / async-await
预加载能力	无，需等待回调	支持，可提前加载
实例复用	不支持，需重新调用	支持，实例可多次调用 `get()`
错误处理	回调参数判断	Promise reject / try-catch
浏览器兼容性	所有浏览器（含 IE9+）	需 Promise 支持（IE 需 polyfill）

常见问题

Q1：`respondedGeeToken` 什么时候为空？

A：在网络请求失败的情况下，respondedGeeToken 为空字符串。

Q2：`loadGeelabGuard()` 和 `initGeelabGuard()` 能否同时使用？

A：可以，两种方式完全兼容，可以在同一页面共存，共享底层 JS 资源，不会重复加载。

Q3：老旧浏览器如何使用 Promise API？

A：如需在不支持 Promise 的浏览器（如 IE）使用 loadGeelabGuard()，请先引入 Promise polyfill：

否则请使用 initGeelabGuard() 回调方式。

获取结果

将 GeeToken 和业务数据一起提交到业务的服务端，服务端再向 Geelab 设备指纹服务查询结果。请参考服务端接入文档。

Web 集成指南

On this page