设备指纹
MOBILE

React Native

使用 Geelab 设备指纹 v2 React Native 插件完成 Android 与 iOS 客户端接入

本指南帮助你在 React Native 应用中接入 GeelabGuard，初始化原生 SDK，并生成可发送给业务后端的设备凭据（receipt）。

概览

geelabguard-rn-plugin 同时支持 React Native Legacy Architecture 和 New Architecture，对外提供一致的 Promise API。完成本指南后，你将能够：

  1. 安装 React Native 插件及单独授权的原生 SDK。
  2. 使用 AppID 初始化 GeelabGuard。
  3. 在业务事件发生时生成本地凭据或提交凭据。
  4. 将 token 安全发送到自己的业务后端。

本指南只覆盖 React Native 客户端集成。凭据的服务端校验、风险判断和业务处置应在你的后端完成。

前置条件

开始前，请确认：

  • 已配置可正常构建的 React Native 开发环境。
  • React Native 版本为 0.71.0 或更高版本。
  • Android 应用的 minSdkVersion 为 21 或更高版本。
  • iOS 应用的最低部署版本为 12.4 或更高版本。
  • 已通过授权的 GeelabGuard 渠道获得 AppID。
  • 已通过授权的 GeelabGuard 渠道获得目标平台的原生 SDK：
平台原生 SDK安装到 npm 包内的相对路径
Androidgeelabguard_android_vx.y.z_date.aarandroid/libs/geelabguard_android_vx.y.z_date.aar
iOSGeelabGuardSDK.xcframework x.y.zios/Frameworks/GeelabGuardSDK.xcframework

原生 SDK 二进制文件不包含在 GitHub 仓库或 npm 包中。React Native Web 不受支持。

1. 准备 React Native 项目

如果你已有 React Native 项目，可直接进入下一节。否则，可使用 React Native Community CLI 创建项目：

npx @react-native-community/cli init GeelabGuardRN
cd GeelabGuardRN

先运行未接入插件的应用，确认 React Native 开发环境工作正常：

npx react-native start

在另一个终端运行目标平台：

# Android
npx react-native run-android

# iOS
npx react-native run-ios

2. 安装 React Native 插件

在应用根目录执行：

npm install geelabguard-rn-plugin

如果使用 Yarn：

yarn add geelabguard-rn-plugin

3. 安装原生 SDK

只需安装应用实际构建平台对应的原生 SDK。

Android

将授权获得的 AAR 复制到插件的 android/libs 目录：

mkdir -p node_modules/geelabguard-rn-plugin/android/libs
cp /path/to/geelabguard_android_v2.7.4_20260428.aar \
  node_modules/geelabguard-rn-plugin/android/libs/

插件会在 Gradle 配置阶段检查该文件。如果文件缺失，构建会中止并显示预期路径。

原生 SDK 的 manifest 已声明 android.permission.INTERNET；插件的 consumer ProGuard 规则会保留 tech.geelab.core 和 tech.geelab.geegateway 命名空间。

iOS

将授权获得的 XCFramework 复制到插件的 ios/Frameworks 目录，然后安装 Pods：

mkdir -p node_modules/geelabguard-rn-plugin/ios/Frameworks
cp -R /path/to/GeelabGuardSDK.xcframework \
  node_modules/geelabguard-rn-plugin/ios/Frameworks/

cd ios
pod install
cd ..

插件的 podspec 会在 CocoaPods 解析阶段检查该目录，并自动添加所需的 -ObjC 链接参数。

重新安装、裁剪或重建 node_modules 后，手动复制的原生 SDK 可能被删除。发生此情况时，请重新复制 SDK，并重新构建原生应用。

4. 初始化 SDK

在调用其他接口前，先使用 AppID 初始化 GeelabGuard：

import { GeelabGuard } from 'geelabguard-rn-plugin';

await GeelabGuard.initialize('your-app-id');

省略 serverUrl 时，原生 SDK 使用默认全球服务地址。如果 AppID 对应特定区域，可传入该区域配置的上报地址：

await GeelabGuard.initialize(
  'your-app-id',
  'https://riskct-eu.geelabapi.com/api/v1/client_report'
);

appId 和显式传入的 serverUrl 均不能为空字符串。AppID 与服务地址必须属于同一配置区域。

5. 生成并提交设备凭据

在线提交

大多数需要服务端响应的业务场景可调用 submitReceipt：

const receipt = await GeelabGuard.submitReceipt('business-request-id');

// 将 respondedGeeToken 发送给你自己的业务后端进行后续校验和风控处理。
const token = receipt.respondedGeeToken;

signData 用于绑定当前业务请求，可以使用业务侧生成的请求标识。不要传入密码、私钥或其他敏感明文。

仅生成本地凭据

不需要立即向服务端提交时，可调用 fetchReceipt：

const receipt = await GeelabGuard.fetchReceipt('business-request-id');

// 将 geeToken 发送给你自己的业务后端。
const token = receipt.geeToken;

signData 必须是字符串；业务无需绑定数据时可传入空字符串。

6. 添加一个最小可运行示例

下面的 App.tsx 示例会在页面加载后初始化 SDK，并在用户点击按钮时提交设备凭据。示例只显示操作状态，不会把 token 输出到界面或日志。

import { useEffect, useState } from 'react';
import { Button, SafeAreaView, StyleSheet, Text } from 'react-native';
import { GeelabGuard, GeelabGuardError } from 'geelabguard-rn-plugin';

const APP_ID = 'your-app-id';

export default function App() {
  const [initialized, setInitialized] = useState(false);
  const [status, setStatus] = useState('正在初始化 GeelabGuard…');

  useEffect(() => {
    let active = true;

    GeelabGuard.initialize(APP_ID).then(
      () => {
        if (!active) return;
        setInitialized(true);
        setStatus('GeelabGuard 已初始化');
      },
      (error: unknown) => {
        if (!active) return;
        setStatus(
          error instanceof GeelabGuardError
            ? `初始化失败：${error.code}`
            : '初始化失败'
        );
      }
    );

    return () => {
      active = false;
    };
  }, []);

  const identifyDevice = async () => {
    setStatus('正在生成设备凭据…');

    try {
      const receipt = await GeelabGuard.submitReceipt('business-request-id');
      const token = receipt.respondedGeeToken;
      if (!token) throw new Error('响应中没有 respondedGeeToken');

      // 在此调用你自己的 HTTPS 业务接口，将 token 交给后端处理。
      // 不要在客户端保存服务端私钥，也不要直接信任客户端风控结果。
      setStatus('设备凭据已生成，请发送到业务后端');
    } catch (error) {
      if (error instanceof GeelabGuardError) {
        // 网络或服务异常时，error.receipt 可能包含可供降级使用的本地 geeToken。
        setStatus(`生成失败：${error.code}`);
        return;
      }
      setStatus('生成失败：未知错误');
    }
  };

  return (
    <SafeAreaView style={styles.container}>
      <Text style={styles.status}>{status}</Text>
      <Button
        title="生成设备凭据"
        disabled={!initialized}
        onPress={identifyDevice}
      />
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    padding: 24,
  },
  status: {
    marginBottom: 16,
  },
});

实际项目中，请将 your-app-id 和 business-request-id 替换为你的配置和业务请求标识，并在标注位置接入自己的 HTTPS 后端接口。

7. 运行并验证

安装或变更原生依赖后，必须重新构建应用；仅刷新 JavaScript 不足以加载新的原生模块。

启动 Metro：

npx react-native start

在另一个终端运行目标平台：

# Android
npx react-native run-android

# iOS
npx react-native run-ios

建议按以下顺序验证：

  1. 应用能够完成原生构建并启动。
  2. GeelabGuard.initialize 成功完成。
  3. 点击“生成设备凭据”后，submitReceipt 返回 receipt。
  4. 应用按自身接口契约将 respondedGeeToken 通过 HTTPS 发送到业务后端。
  5. 业务后端完成 token 校验和风险决策。

如需确认当前安装的原生 SDK 版本，可调用：

const version = await GeelabGuard.getVersion();

Receipt 字段

type GeelabGuardReceipt = {
  appId: string | null;
  geeToken: string | null;
  geeId: string | null;
  geeIdTimestamp: string | null;
  respondedGeeToken: string | null;
  originalResponseBase64: string | null;
};
  • geeToken：本地生成的 token，可用于本地凭据流程或网络失败时的降级处理。
  • respondedGeeToken：提交成功后服务端响应的 token，通常发送给业务后端继续处理。
  • 其他字段用于关联和诊断；使用方式以你的 GeelabGuard 服务端接入方案为准。
  • originalResponseBase64 是原始二进制响应的 Base64 表示，只应在必要的受控诊断流程中解码。

不要在生产日志、分析平台或用户界面中输出 AppID、signData、token 或 originalResponseBase64。

错误处理

插件将错误规范化为 GeelabGuardError：

import { GeelabGuard, GeelabGuardError } from 'geelabguard-rn-plugin';

try {
  const receipt = await GeelabGuard.submitReceipt('business-request-id');
  // 将 receipt.respondedGeeToken 安全发送到业务后端。
} catch (error) {
  if (error instanceof GeelabGuardError) {
    const fallbackGeeToken = error.receipt?.geeToken;
    // 根据 error.code 和业务策略决定是否使用 fallbackGeeToken 降级。
  }
}
错误码含义
INVALID_ARGUMENTAppID、服务地址或参数无效。
NOT_INITIALIZED尚未初始化 SDK，或原生 SDK 未返回凭据。
NETWORK_ERROR原生提交发生网络错误。
INVALID_RESPONSE服务响应格式无效。
SERVICE_FAILURE服务端报告处理失败。
UNKNOWN_NATIVE_ERROR原生 SDK 返回未归类的错误。

对 NETWORK_ERROR、INVALID_RESPONSE 或 SERVICE_FAILURE，错误对象可能携带包含本地 geeToken 的 receipt。是否降级使用该 token 应由你的后端和业务策略决定。

常见问题

Android 构建提示缺少 SDK

确认文件位于：

node_modules/geelabguard-rn-plugin/android/libs/geelabguard_android_vx.y.z_date.aar

如果刚重新安装过依赖，请再次复制 AAR 后重新构建。

iOS 执行 pod install 时提示缺少 SDK

确认目录位于：

node_modules/geelabguard-rn-plugin/ios/Frameworks/GeelabGuardSDK.xcframework

再次执行 pod install，然后重新构建 iOS 应用。

出现 GeelabGuard is not linked

确认已经安装原生依赖，并完全重新构建 Android 或 iOS 应用。刷新 Metro 或重新加载 JavaScript 无法完成原生模块链接。

iOS 出现重复符号

不要在宿主应用中声明另一个名为 GeelabGuard 的 Objective-C 类。原生 SDK 已导出该类；React Native 桥内部注册为 RNGeelabGuard，JavaScript 模块名仍为 GeelabGuard。

无法获取 receipt

确保先成功等待 GeelabGuard.initialize，再调用 fetchReceipt 或 submitReceipt。如果传入了区域服务地址，请确认它与 AppID 属于同一配置区域。

生产环境检查清单

  • 原生 SDK 来自授权渠道，版本与插件要求一致。
  • AppID 与区域服务地址配置匹配。
  • token 只通过 HTTPS 发送到可信业务后端。
  • 服务端私钥和风险决策逻辑不放入 React Native 客户端。
  • 生产日志不记录 AppID、signData、token 或原始响应。

下一步

  • 根据业务场景选择 fetchReceipt 或 submitReceipt。
  • 在业务后端接收 token，完成校验、风险判断和降级策略。

iOS

Previous Page

Flutter

Next Page

On this page

概览前置条件1. 准备 React Native 项目2. 安装 React Native 插件3. 安装原生 SDKAndroidiOS4. 初始化 SDK5. 生成并提交设备凭据在线提交仅生成本地凭据6. 添加一个最小可运行示例7. 运行并验证Receipt 字段错误处理常见问题Android 构建提示缺少 SDKiOS 执行 pod install 时提示缺少 SDK出现 GeelabGuard is not linkediOS 出现重复符号无法获取 receipt生产环境检查清单下一步