设备指纹
WEB

JavaScript

使用 Geelab 设备指纹 v2 JavaScript SDK 完成 Web 与 H5 接入

概述及资源

本文用于详细说明设备验前端相关的所有配置和接口。

环境需求

条目
兼容性IE10+、Chrome、Firefox、Safari、Opera、主流手机浏览器、iOS 及 Android 上的内嵌 WebView

注意： loadGeelabGuard() Promise API 需要浏览器支持 Promise；IE10 等不提供 Promise 的浏览器，请在 gld_v2.js 前引入 Promise polyfill。

安装

引入初始化 JS

<!-- IE10 等不支持 Promise 的浏览器需要先加载此 polyfill；现代浏览器可省略。 -->
<script src="./promise-polyfill.min.js"></script>
<script src="./gld_v2.js"></script>

页面引入 gld_v2.js 后，调用 loadGeelabGuard() 获取实例，再通过 instance.get() 获取设备令牌。客户页面不需要直接调用底层服务接口。

React、Vue 3、Angular、Next.js、Svelte 等前端框架都可以复用本页的脚本接入方式， 不需要安装 npm SDK。

框架共用客户端模块

框架项目建议把 SDK 初始化和令牌获取集中在一个客户端模块中，避免组件重复初始化：

// src/geeGuardClient.js
let instancePromise;

const config = {
  publicKey: 'your_public_key',
  protocol: 'https://',
  apiServers: ['riskct-global.geelabapi.com'],
};

export function preloadGeeGuard() {
  if (typeof window === 'undefined') {
    return Promise.reject(new Error('GeeLabGuard 只能在浏览器环境中使用'));
  }
  if (typeof window.loadGeelabGuard !== 'function') {
    return Promise.reject(new Error('GeeLabGuard SDK 未正确加载'));
  }

  if (!instancePromise) {
    const pending = window.loadGeelabGuard(config);
    instancePromise = pending;
    pending.catch(function () {
      if (instancePromise === pending) instancePromise = undefined;
    });
  }

  return instancePromise;
}

export async function getGeeToken() {
  const instance = await preloadGeeGuard();
  const result = await instance.get();
  if (!result || result.status !== 'success' || !result.data) {
    throw new Error('GeeLabGuard 未返回成功结果');
  }

  const { respondedGeeToken, geeToken, offline, local_id } = result.data;
  const token = respondedGeeToken || geeToken;
  if (!token) throw new Error('GeeLabGuard 未返回可用的 GeeToken');

  return { token, offline: Boolean(offline), localId: local_id };
}

TypeScript 项目还需要为脚本提供全局类型声明：

// src/geelabguard.d.ts
export {};

interface GeeGuardInstance {
  get(): Promise<{
    status: 'success';
    data: {
      offline: boolean;
      respondedGeeToken: string;
      geeToken: string;
      local_id: string;
    };
  }>;
}

declare global {
  interface Window {
    loadGeelabGuard(config: {
      publicKey: string;
      protocol?: 'http://' | 'https://';
      apiServers?: string[];
      networkTimeout?: number;
      customInfo?: string;
    }): Promise<GeeGuardInstance>;
  }
}

配置参数

这里说的配置参数，是指调用设备验时传入的 config 对象（key-value 结构），也就是调用初始化函数时所传入的第一个参数的可选参数配置。

除了 publicKey，其它均为可选配置参数（以下配置参数除非您知道如何去使用，否则不要去设置（可能在不同的场景下带来副作用））：

参数必填类型说明默认值可选值
publicKeyYstring设备验 integration 公开标识，在 Geelab 控制台申请得到
protocolNstring协议头，本地或混合开发一定要手动设置默认取当前页面协议头http://、https://
apiServersNstring[]根据控制台选择的地域配置对应的服务域名默认使用全球地域服务域名见下方地域配置
networkTimeoutNnumberclient_report 上报请求的超时时间7000（ms）大于0的整数
customInfoNstring唯一标记本次业务的流水号或凭证，用于防止 GeeToken 从业务场景剥离

地域配置

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

地域apiServers 配置
🌏 全球['riskct-global.geelabapi.com']
🇪🇺 欧洲['riskct-eu.geelabapi.com']
🇺🇸 北美['riskct-na.geelabapi.com']
// 北美地域
loadGeelabGuard({
    publicKey: 'your_public_key',
    protocol: 'https://',
    apiServers: ['riskct-na.geelabapi.com']
});

调用方式

客户接入统一使用 loadGeelabGuard()。

Promise API

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

基础用法

loadGeelabGuard({
    publicKey: 'your_public_key',
    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({
            publicKey: 'your_public_key',
            protocol: 'https://'
        });

        const result = await instance.get();

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

            if (offline) {
                // 离线模式，使用本地令牌 geeToken
                console.log('离线模式，使用本地令牌:', geeToken);
            } else {
                // 在线模式，使用服务端令牌 respondedGeeToken
                console.log('在线模式，使用服务端令牌:', respondedGeeToken);
            }

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

预加载用法（推荐）

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

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

// 用户提交表单时直接获取 token
document.getElementById('submitBtn').addEventListener('click', function() {
    geeGuardPromise
        .then(function(instance) {
            return instance.get();
        })
        .then(function(result) {
            // 提交表单及 token 到服务器
            return sendToServer({
                gee_token: result.data.respondedGeeToken || result.data.geeToken
            });
        })
        .catch(function(error) {
            console.error('错误:', error);
        });
});

降级使用 GeeToken

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

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

    // 在线模式优先使用 respondedGeeToken，离线降级时使用 geeToken
    var geeToken = result.data.respondedGeeToken || result.data.geeToken;

    if (!geeToken) {
        throw new Error('未获取到可用的 GeeToken');
    }

    return sendToServer({
        gee_token: geeToken,
        offline: result.data.offline
    });
})
.catch(function(error) {
    console.error('获取或提交失败:', error);
});

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

返回格式

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

// 请求失败返回示例
{
    status: 'error',
    data: {
        code: number|string,   // 错误码，如 60001、60100、60101
        msg: string     // 错误信息，如 "integration not found"
    }
}

常见问题

Q1：respondedGeeToken 什么时候为空？

A： 在以下情况下 respondedGeeToken 为空字符串：

  • 网络请求失败自动降级到离线模式

此时应使用 geeToken（本地生成的令牌）提交给服务端。

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

A： 如需在不支持 Promise 的浏览器（如 IE）使用 loadGeelabGuard()，请先加载交付包中的 promise-polyfill.min.js，再加载 gld_v2.js。现代浏览器可直接加载 gld_v2.js。

获取结果

将 GeeToken 和业务数据一起提交到业务服务端，后续按业务服务端流程处理。

使用说明

Previous Page

React

Next Page

On this page

概述及资源环境需求安装引入初始化 JS框架共用客户端模块配置参数地域配置调用方式Promise API基础用法Async/Await 用法预加载用法（推荐）降级使用 GeeToken返回格式常见问题Q1：respondedGeeToken 什么时候为空？Q2：老旧浏览器如何使用 Promise API？获取结果