React Native (Expo) SDK 接入指南

在 React Native (Expo) 项目中集成 @xxinstall/native，支持 iOS 和 Android 原生归因。

概述

@xxinstall/native 是 XXinstall 的 React Native 原生归因 SDK，通过 Expo Modules 桥接 iOS（Swift）和 Android（Kotlin）原生实现。核心逻辑在原生层运行。

安装

npm install @xxinstall/native@2.0.1

要求 expo-modules-core >= 1.0.0，react-native >= 0.72.0

快速开始

import { XXinstall } from '@xxinstall/native';

// 1. 设置 API 地址（全局，只需调用一次）
XXinstall.setHost('https://your-api-domain.com');

// 2. 初始化并获取归因结果（自动采集 23 维指纹 + 设备画像上报）
const result = await XXinstall.init({
  appKey: 'YOUR_APP_KEY',
  appSecret: 'YOUR_APP_SECRET',
  debug: true,
});

console.log('归因结果:', result);
// { inviteCode, channel, matchType, confidence, scene }

完整示例

import { useEffect, useState } from 'react';
import { View, Text } from 'react-native';
import { XXinstall } from '@xxinstall/native';

XXinstall.setHost('https://your-api-domain.com');

export default function App() {
  const [result, setResult] = useState(null);
  const [status, setStatus] = useState('初始化中...');

  useEffect(() => {
    XXinstall.init({
      appKey: 'YOUR_APP_KEY',
      appSecret: 'YOUR_APP_SECRET',
    })
      .then((attr) => {
        setResult(attr);
        setStatus(`归因完成: ${attr.matchType}`);
      })
      .catch((err) => setStatus(`归因失败: ${err.message}`));
  }, []);

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text>{status}</Text>
      {result && (
        <>
          <Text>邀请码: {result.inviteCode ?? '无'}</Text>
          <Text>渠道: {result.channel}</Text>
          <Text>置信度: {result.confidence}</Text>
        </>
      )}
    </View>
  );
}

API

`XXinstall.setHost(url: string)`

设置 API 服务器地址。必须在 init() 之前调用。

`XXinstall.setDebug(enabled: boolean)`

开启或关闭调试日志输出。

`XXinstall.init(config): Promise<AttributionResult>`

初始化 SDK 并执行归因匹配。SDK 内部自动采集 23 个维度的设备指纹（原生 + WebView），并在归因完成后异步上报设备画像。

参数	类型	必填	说明
`appKey`	string	是	应用 Key
`appSecret`	string	是	应用 Secret
`baseUrl`	string	否	API 地址（优先于 setHost）
`deviceId`	string	否	自定义设备 ID
`debug`	boolean	否	是否输出调试日志（默认 true）
`skipCache`	boolean	否	跳过缓存，强制重新归因（默认 false）
`skipClipboard`	boolean	否	跳过剪贴板读取（默认 false）
`skipWebView`	boolean	否	跳过内置 WebView 指纹采集（默认 false）

`XXinstall.getAttribution(): Promise<AttributionResult | null>`

获取缓存的归因结果（不发起网络请求）。

`XXinstall.clearCache(): Promise<void>`

清除本地缓存的归因结果。

类型定义

interface AttributionResult {
  inviteCode: string | null;
  channel: string;
  matchType: 'clipboard' | 'fingerprint' | 'ipua' | 'direct' | 'none';
  confidence: number;
  scene: string;
}

interface DeviceProfile {
  buildFingerprint: string;
  installedAppsHash: string;
  sensorListHash: string;
  brand: string;
  model: string;
  [key: string]: any;
}