Title: React Native SDK
Locale: zh
URL: https://sensorswave.com/docs/data-integration/client-sdks/reactnative/
Description: React Native SDK 集成指南和 API 参考
Sensors Wave React Native SDK 是专为 React Native 应用设计的移动端数据采集和 AB 实验工具。

## 核心功能

React Native SDK 提供以下核心能力：

- **事件追踪**：手动追踪自定义事件和用户行为
- **自动埋点**：自动采集应用安装、启动、结束、页面浏览、点击等事件
- **用户识别**：支持匿名用户和登录用户身份关联
- **用户属性管理**：完整的用户属性操作（设置、追加、增量更新等）
- **A/B 测试集成**：支持功能开关（Feature Gate）和实验变量获取
- **导航追踪**：完整支持 React Navigation v6/v7+，自动追踪页面变化
- **批量发送**：优化网络请求性能，每 5 秒批量发送最多 10 个事件
- **公共属性**：支持静态和动态公共属性，自动附加到所有事件
- **React Hooks**：提供 `useSensorswave` hook 便于在组件中使用

## 环境要求

- **React Native >= 0.74.0**
- **React >= 18.0.0**

## 安装

### NPM 安装

```bash
npm install @sensorswave/react-native-sdk
```

### Yarn 安装

```bash
yarn add @sensorswave/react-native-sdk
```

### PNPM 安装

```bash
pnpm add @sensorswave/react-native-sdk
```

## 快速开始

### 基础初始化

在您的应用入口文件中初始化 SDK：

```typescript

// 初始化 SDK
Sensorswave.init('YOUR_SOURCE_TOKEN', {
  apiHost: 'https://your-api-endpoint.com',  // 数据上报地址
  debug: false,                               // 调试模式
  autoCapture: true,                          // 开启自动埋点
  enableClickTrack: true,                     // 开启点击自动追踪
  enableAB: true,                             // 开启 A/B 测试
});
```

### 使用 Provider 包裹应用

使用 `SensorswaveProvider` 包裹您的应用，以启用自动导航追踪：

```tsx

const App = () => {
  return (
    
      
        
          
          
        
      
    
  );
};
```

### 发送第一个事件

初始化完成后，您可以立即开始上报事件：

```typescript

// 追踪用户点击按钮
Sensorswave.trackEvent('ButtonClick', {
  button_name: 'submit',
  page: 'home'
});
```

## 配置选项

`init` 方法的第二个参数是配置对象，支持以下选项：

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `apiHost` | `string` | `''` | **必填**，数据上报的 API 地址，您可以在 Pipeline 中查看 |
| `debug` | `boolean` | `false` | 是否开启调试模式，开启后在控制台输出详细日志 |
| `autoCapture` | `boolean` | `true` | 是否开启自动埋点，自动采集应用安装、启动、结束、页面浏览事件 |
| `enableClickTrack` | `boolean` | `false` | 是否开启点击自动追踪（追踪 TouchableOpacity、Pressable、Button 等组件） |
| `enableAB` | `boolean` | `false` | 是否开启 A/B 测试功能 |
| `batchSend` | `boolean` | `true` | 是否使用批量发送，每 5 秒批量发送最多 10 个事件 |
| `abRefreshInterval` | `number` | `600000` | A/B 测试配置刷新间隔（毫秒），默认 10 分钟 |

### 完整配置示例

```typescript
Sensorswave.init('YOUR_SOURCE_TOKEN', {
  apiHost: 'https://your-api-endpoint.com',
  debug: true,                          // 开发环境开启调试
  autoCapture: true,                    // 开启自动埋点
  enableClickTrack: true,               // 开启点击追踪
  batchSend: true,                      // 批量发送优化性能
  enableAB: true,                       // 开启 A/B 测试
  abRefreshInterval: 10 * 60 * 1000     // A/B 测试数据每 10 分钟刷新
});
```

> **提示**：在生产环境中建议关闭 `debug` 模式，以避免在控制台输出过多日志。

## API 方法

### 事件追踪

#### trackEvent - 追踪自定义事件

手动追踪自定义事件及其属性。

**参数**：
- `eventName` (string，必填)：事件名称
- `properties` (Object，可选)：事件属性，键值对形式

**示例**：

```typescript
// 追踪按钮点击
Sensorswave.trackEvent('ButtonClick', {
  button_name: 'submit',
  page: 'home'
});
```

**实际场景示例**：

```typescript
// 电商场景：用户浏览商品
Sensorswave.trackEvent('ProductView', {
  product_id: '12345',
  product_name: '无线蓝牙耳机',
  category: '电子产品',
  price: 299.00,
  currency: 'CNY'
});

// 电商场景：用户加入购物车
Sensorswave.trackEvent('AddToCart', {
  product_id: '12345',
  quantity: 1,
  price: 299.00
});

// 内容平台：文章阅读
Sensorswave.trackEvent('ArticleRead', {
  article_id: 'article_001',
  title: 'React Native 性能优化技巧',
  category: '技术博客',
  read_duration: 120  // 阅读时长（秒）
});
```

#### track - 高级事件追踪

发送完整的事件对象，支持更精细的控制。此方法允许您手动指定所有事件字段。

**参数**：
- `event` (AdvanceEvent，必填)：完整事件对象，包含以下字段：
  - `event` (string，必填)：事件名称
  - `properties` (Record，可选)：事件属性
  - `time` (number，必填)：时间戳（毫秒）
  - `anon_id` (string，可选)：匿名用户 ID
  - `login_id` (string，可选)：登录用户 ID。login_id 和 anon_id 必须传一个，同时传递时，优先使用 login_id
  - `trace_id` (string，必填)：请求追踪 ID
  - `user_properties` (Record，可选)：用户属性

**示例**：

```typescript
Sensorswave.track({
  event: 'purchaseCompleted',
  properties: {
    product_id: '12345',
    amount: 99.99,
    currency: 'USD'
  },
  time: Date.now(),
  trace_id: 'unique-trace-id-12345',
  anon_id: 'anonymous-user-id',
  login_id: 'user_12345',
  user_properties: {
    // $set: 代表插入或者更新一条用户属性信息
    $set: {
      plan: 'premium',
      signup_date: '2024-01-01'
    }
  }
});
```

> **注意**：`track` 方法是高级功能，大多数场景下使用 `trackEvent` 即可满足需求。

### 用户识别

#### identify - 设置登录用户 ID

设置登录用户 ID 并发送绑定事件，将匿名行为与已识别用户关联。

**参数**：
- `loginId` (string | number，必填)：用户的唯一标识符（如邮箱、用户 ID、用户名）

**示例**：

```typescript
// 用户登录后设置用户 ID
Sensorswave.identify('user_12345');
```

**完整登录流程示例**：

```typescript
// 用户登录流程
async function handleUserLogin(email: string, password: string) {
  try {
    // 调用登录 API
    const response = await fetch('/api/login', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ email, password })
    });

    const { userId } = await response.json();

    // 设置用户 ID 并关联匿名行为
    Sensorswave.identify(userId);
  } catch (error) {
    console.error('登录失败:', error);
  }
}
```

> **重要提醒**：如果 `loginId` 包含隐私信息（如手机号、邮箱、身份证号等），请务必在加密后再进行传输，避免敏感信息明文上报。

#### setLoginId - 仅设置登录 ID

设置登录用户 ID，但不发送绑定事件。如果您只想识别用户但不需要关联用户，可以使用此方法。

**参数**：
- `loginId` (string | number，必填)：用户的唯一标识符

**示例**：

```typescript
Sensorswave.setLoginId('user_12345');
```

> **重要提醒**：如果 `loginId` 包含隐私信息（如手机号、邮箱、身份证号等），请务必在加密后再进行传输，避免敏感信息明文上报。

> **使用建议**：通常情况下推荐使用 `identify` 方法，因为它会记录用户身份关联事件，有助于后续分析。

#### getLoginId - 获取当前登录 ID

获取当前设置的登录用户 ID。

**返回值**：string | undefined

**示例**：

```typescript
const loginId = Sensorswave.getLoginId();
console.log('当前用户 ID:', loginId);
```

#### getAnonId - 获取匿名 ID

获取当前的匿名用户 ID。

**返回值**：string

**示例**：

```typescript
const anonId = Sensorswave.getAnonId();
console.log('匿名用户 ID:', anonId);
```

### 用户属性

用户属性用于描述用户的特征，如会员等级、注册时间、偏好设置等。与事件属性不同，用户属性会持久化保存并与用户关联。

#### profileSet - 设置用户属性

设置用户属性，如果属性已存在则覆盖。

**参数**：
- `properties` (Object，必填)：要设置的用户属性

**示例**：

```typescript
// 用户完成注册后，设置用户属性
Sensorswave.profileSet({
  name: '张三',
  age: 30,
  plan: 'premium'
});
```

#### profileSetOnce - 仅首次设置

设置用户属性，仅在属性不存在时设置，已存在的属性不会被覆盖。

**参数**：
- `properties` (Object，必填)：要设置的用户属性

**示例**：

```typescript
// 记录用户首次访问信息（仅记录一次，后续不会覆盖）
Sensorswave.profileSetOnce({
  signup_date: '2024-01-15',
  initial_referrer: 'google',
  initial_campaign: 'spring_sale'
});
```

#### profileIncrement - 增量更新数值属性

对数值类型的用户属性进行增减操作。仅支持数值属性。

**参数**：
- `properties` (Object，必填)：要增减的属性及其数值

**示例**：

```typescript
// 增加单个属性
Sensorswave.profileIncrement({
  login_count: 1
});

// 增加多个属性
Sensorswave.profileIncrement({
  login_count: 1,
  points_earned: 100,
  purchases_count: 1
});
```

#### profileAppend - 追加到数组属性

向数组类型的用户属性追加新值，不进行去重。

**参数**：
- `properties` (Object，必填)：要追加的属性及其数组值

**示例**：

```typescript
Sensorswave.profileAppend({
  categories_viewed: ['电子产品', '手机'],
  tags: ['新客户', '2024Q1']
});
```

#### profileUnion - 追加到集合属性（去重）

向数组类型的用户属性追加新值，自动去重。

**参数**：
- `properties` (Object，必填)：要追加的属性及其数组值

**示例**：

```typescript
// 第一次调用
Sensorswave.profileUnion({
  interests: ['科技', '游戏']
});

// 第二次调用，'科技' 不会重复添加
Sensorswave.profileUnion({
  interests: ['科技', '音乐']  // 只会增加 '音乐'
});
```

#### profileUnset - 删除指定属性

将指定的用户属性设置为 null。

**参数**：
- `propertyNames` (string | string[]，必填)：要置为 null 的属性名或属性名数组

**示例**：

```typescript
// 处理单个属性
Sensorswave.profileUnset('temporary_campaign');

// 处理多个属性
Sensorswave.profileUnset(['old_plan', 'expired_flag', 'temp_id']);
```

#### profileDelete - 删除所有用户属性

删除当前用户的所有用户属性数据。此操作不可撤销。

**示例**：

```typescript
// 用户注销账号时，删除所有用户属性
Sensorswave.profileDelete();
```

> **警告**：`profileDelete` 会删除所有用户属性，请谨慎使用。

#### 用户属性使用示例

**会员升级场景**：

```typescript
function handleMembershipUpgrade(newPlan: string) {
  // 更新会员等级和升级时间
  Sensorswave.profileSet({
    plan: newPlan,
    upgrade_time: new Date().toISOString()
  });

  // 增加升级次数
  Sensorswave.profileIncrement({
    upgrade_count: 1
  });

  // 追踪升级事件
  Sensorswave.trackEvent('membershipUpgrade', {
    from_plan: 'basic',
    to_plan: newPlan
  });
}
```

### 公共属性

公共属性会自动添加到所有事件中，适用于需要在每个事件中都包含的通用信息。支持静态属性（字符串值）和动态属性（函数返回值）。

#### registerCommonProperties - 注册公共属性

注册静态或动态公共属性，这些属性将自动包含在所有事件中。

**参数**：
- `properties` (Record，必填)：要注册的属性
  - 静态属性：字符串值
  - 动态属性：函数（每次发送事件时调用）

**示例**：

```typescript
Sensorswave.registerCommonProperties({
  // 静态属性
  app_version: '1.0.0',
  environment: 'production',

  // 动态属性（每次发送事件时调用）
  current_time: () => new Date().toISOString(),
  user_session_id: () => getSessionId(),

  // 用户相关的动态数据
  user_tier: () => getUserTier()
});
```

#### clearCommonProperties - 清除公共属性

移除指定的已注册公共属性。

**参数**：
- `propertyNames` (string[]，必填)：要移除的属性名数组

**示例**：

```typescript
Sensorswave.clearCommonProperties(['app_version', 'user_session_id']);
```

> **注意**：公共属性会增加每个事件的数据量，建议仅添加确实需要的通用属性。

### A/B 测试

React Native SDK 内置了 A/B 测试支持，可以获取功能开关状态和实验变量。

#### 开启 A/B 测试功能

```typescript
Sensorswave.init('YOUR_SOURCE_TOKEN', {
  apiHost: 'https://your-api-endpoint.com',
  enableAB: true,                       // 开启 A/B 测试
  abRefreshInterval: 10 * 60 * 1000     // 配置刷新间隔（10 分钟）
});
```

#### checkFeatureGate - 检查功能开关

检查功能开关（Feature Flag）是否为当前用户启用。返回 Promise，解析为布尔值。

**参数**：
- `key` (string，必填)：功能开关的 Key

**返回值**：Promise

**示例**：

```typescript
// 检查功能是否启用
async function initFeature() {
  const isEnabled = await Sensorswave.checkFeatureGate('advanced_search');
  if (isEnabled) {
    enableAdvancedSearch();
  }
}
```

#### getExperiment - 获取实验变量

获取当前用户的实验变量数据。返回 Promise，解析为实验配置对象。

**参数**：
- `key` (string，必填)：实验的 Key

**返回值**：Promise

返回的对象包含实验的变量配置值（Record）。

**示例**：

```typescript
// 获取实验配置
async function initExperiment() {
  const experiment = await Sensorswave.getExperiment('pricing_display');
  if (experiment) {
    const { price_format, discount_type } = experiment;
    updatePricingDisplay(price_format, discount_type);
  }
}
```

**完整 A/B 测试示例**：

```typescript
// 电商首页 CTA 按钮 A/B 测试
async function initHomepageCTA() {
  try {
    const experiment = await Sensorswave.getExperiment('homepage_cta_test');

    if (experiment) {
      const { button_text, button_color, button_size } = experiment;

      // 应用实验配置
      setCTAConfig({
        text: button_text || '立即购买',
        color: button_color || '#ff6600',
        size: button_size || '16px'
      });
    }
  } catch (error) {
    console.error('获取实验变量失败:', error);
    // 使用默认配置
  }
}

// 页面加载时初始化
useEffect(() => {
  initHomepageCTA();
}, []);
```

> **提示**：A/B 测试功能需要在 Sensors Wave 后台配置实验和功能开关后才能使用。

## 导航追踪

SDK 为不同的导航场景提供了自动页面浏览追踪。请选择适合您导航设置的方法：

### 导航追踪对比

| 导航类型 | 使用方式 | 自动追踪 | 限制 |
|---------|---------|---------|------|
| React Navigation v6- | `SensorswaveProvider` | ✅ 是 | 无 |
| React Navigation v7+ | `createNavigationRef()` | ✅ 是 | 需要设置 ref |
| React Native Navigation (Wix) | 手动 `trackScreen()` | ❌ 否 | 需手动调用 |
| 自定义导航 | 手动 `trackScreen()` | ❌ 否 | 需手动调用 |

### 方式一：React Navigation v6 及以下版本（推荐）

只需用 `SensorswaveProvider` 包裹应用，无需额外配置。

```tsx

const Stack = createStackNavigator();

const App = () => {
  return (
    
      
        
          
          
        
      
    
  );
};
```

**工作原理**：SDK 内部使用 `useNavigationState` hook 自动追踪路由变化。

### 方式二：React Navigation v7+

对于 React Navigation v7+，使用 `createNavigationRef` 创建一个被追踪的导航引用：

```tsx

const navigationRef = createNavigationRef();

const App = () => {
  return (
    
      
        
          
          
        
      
    
  );
};
```

> **为什么需要这样**：React Navigation v7+ 改变了导航状态的访问方式，需要使用基于 ref 的方法。

### 方式三：手动追踪

对于自定义导航方案或无法自动追踪的情况：

```tsx

// 当页面变化时调用
trackScreen('CustomScreen', {
  title: '自定义页面标题',
  custom_property: 'value',
});
```

### 自定义页面名称

您可以自定义页面名称的采集方式：

```tsx
 {
        // 自定义页面名称逻辑
        if (name === 'Detail') {
          return `Product_${params?.productId}`;
        }
        return name;
      },
      routeToProperties: (name, params) => ({
        // 添加自定义属性到页面浏览事件
        category: params?.category || 'unknown',
      }),
    },
  }}
>
  {/* ... */}

```

### 禁用自动页面追踪

```tsx

  {/* ... */}

// 或

  {/* ... */}

```

## 自动埋点

开启自动埋点后，SDK 会自动采集以下事件类型：

| 事件名称 | 说明 | 触发时机 |
|---------|------|---------|
| `$AppInstall` | 应用安装 | 应用安装后首次启动时 |
| `$AppStart` | 应用启动 | 应用启动或从后台进入前台时 |
| `$AppEnd` | 应用结束 | 应用进入后台时 |
| `$AppPageView` | 页面浏览 | 导航到新页面时 |
| `$AppPageLeave` | 页面离开 | 离开页面时（包含页面停留时长） |

当开启 `enableClickTrack` 时：

| 事件名称 | 说明 | 触发时机 |
|---------|------|---------|
| `$AppClick` | 元素点击 | 用户点击元素时 |

### 开启自动埋点

```typescript
Sensorswave.init('YOUR_SOURCE_TOKEN', {
  apiHost: 'https://your-api-endpoint.com',
  autoCapture: true,           // 开启自动埋点
  enableClickTrack: true       // 开启点击自动追踪
});
```

> **提示**：自动埋点功能可以大幅减少手动编码工作量，但会增加一定的数据量。建议根据实际需求选择性开启。

## 点击追踪（$AppClick）

SDK 提供自动点击追踪功能，当初始化时设置 `enableClickTrack: true` 即可启用。

### 自动追踪的组件

SDK 自动追踪以下 React Native 组件的点击事件：

| 组件类型 | 示例 | 说明 |
|---------|------|------|
| **可触摸组件** | TouchableOpacity、TouchableHighlight、TouchableWithoutFeedback | 自动追踪 |
| **Pressable** | `` | 自动追踪 |
| **Button** | `` | 自动追踪 |

### 基础用法

只需正常使用组件即可，SDK 会自动追踪点击事件：

```tsx

  提交

  登录

```

### 忽略组件类型

配置要忽略的组件类型：

```tsx

  

```

### 采集自定义属性

从被点击的元素中采集自定义属性：

```tsx

  

```

**效果**：自定义属性将随标准属性一起包含在 `$AppClick` 事件中。

### 完整示例

```tsx

function App() {
  return (
    
      
    
  );
}

function MyScreen() {
  return (
    
      {/* 自动追踪 - TouchableOpacity */}
      
        提交表单
      

      {/* 自动追踪 - Pressable */}
      
        取消
      
    
  );
}
```

### 事件数据示例

用户点击按钮时采集的数据：

```json
{
  "event": "$AppClick",
  "properties": {
    "$screen_name": "FormScreen",
    "$element_type": "TouchableOpacity",
    "$element_content": "提交表单",
    "$element_selector": "View > TouchableOpacity > Text [提交表单]",
    "$element_path": "View > TouchableOpacity > Text > [提交表单]",
    "variant": "primary"
  }
}
```

## React Hooks

SDK 提供了 React hooks 以便更方便地在组件中使用。

### useSensorswave

通过 hook 获取 SDK 实例。

```tsx

function MyComponent() {
  const Sensorswave = useSensorswave();

  const handlePress = () => {
    Sensorswave.trackEvent('ButtonPressed', {
      button: 'my_button',
    });
  };

  return ;
}
```

## 注意事项

### 性能优化

- 避免在循环中频繁调用 `trackEvent`，建议合并事件或使用节流
- 批量发送功能默认已开启，可有效减少网络请求
- 自动埋点会增加一定性能开销，仅在需要时开启

### 数据安全

- 不要在事件属性中传递敏感信息（如密码、信用卡号、身份证号）
- Source Token 应妥善保管，避免在公开代码仓库中暴露
- 确保数据上报地址使用 HTTPS 协议

### 平台兼容性

- 支持 iOS 和 Android 平台
- 支持 React Native 0.74.0 及以上版本
- 支持 React Navigation v6/v7+

### 数据丢失风险

- 移动端埋点可能受网络环境、应用关闭等因素影响，存在一定数据丢失
- 核心业务数据建议使用服务端埋点，详见 [埋点方案选择](../tracking-strategy.mdx)
- 应用被强制关闭时，部分事件可能丢失

## 常见问题

### 为什么我的数据没有上报成功？

检查以下几点：

1. **Source Token 是否正确**：确认 `sourceToken` 参数是否正确
2. **数据上报地址是否正确**：确认 `apiHost` 配置是否正确
3. **网络连接**：检查设备网络连接是否正常
4. **调试模式**：开启 `debug: true` 查看控制台日志
5. **权限设置**：确认应用有网络访问权限

### 如何避免在开发环境发送数据？

```typescript
const isDevelopment = __DEV__; // React Native 环境变量

if (!isDevelopment) {
  Sensorswave.init('YOUR_SOURCE_TOKEN', {
    apiHost: 'https://your-api-endpoint.com'
  });
}

// 封装一个安全的追踪方法
function trackEvent(eventName: string, properties: Record) {
  if (!isDevelopment) {
    Sensorswave.trackEvent(eventName, properties);
  } else {
    console.log('[Analytics]', eventName, properties);
  }
}

// 使用示例
trackEvent('ButtonClick', { button_name: 'submit' });
```

### 页面浏览未追踪

1. 确保 `SensorswaveProvider` 包裹了 `NavigationContainer`
2. React Navigation v7+ 请使用 `createNavigationRef()`
3. 检查 `autoCapture` 是否被禁用
4. 确认导航配置正确

### 事件未发送

1. 检查 `apiHost` 配置是否正确
2. 启用 `debug: true` 查看日志
3. 检查网络连接和权限
4. 确认 SDK 已正确初始化

## 相关文档

- [埋点方案选择](../tracking-strategy.mdx)：了解服务端埋点和客户端埋点的优劣
- [如何正确的标识用户](../user-identification.mdx)：用户身份识别的最佳实践
- [数据模型](../data-model.mdx)：理解 Sensors Wave 的数据结构
- [事件和属性](../events-and-properties.mdx)：事件设计规范和最佳实践

---

**最后更新时间**：2026 年 3 月 27 日
**许可证**：Apache-2.0