基础 API 介绍（React Native）

用户关联

用户关联是为了对用户进行唯一标识，提高用户行为分析的准确性。目前神策提供了简易用户关联和全域用户关联分为用于支撑不同的业务场景。

• 简易用户关联（IDM 2.0）
• 全域用户关联（IDM 3.0）

用户属性

• 关于事件属性和用户属性的区别，请参考数据模型
• 用户属性的命名约束，请参考数据格式

记录初次设定的用户属性

对于只在首次设置时有效的属性，我们可以使用 profileSetOnce() 记录这些属性。与 profileSet() 方法不同的是，如果被设置的用户属性已存在，则这条记录会被忽略而不会覆盖已有数据，如果属性不存在则会自动创建。因此，profileSetOnce() 适用于为用户设置首次激活时间、首次注册时间等属性。例如：

// 设定用户渠道为 "developer@sensorsdata.cn" 的 "AdSource" 属性值为 "XXX Store"
sensors.profileSetOnce({ AdSource: "XXX Store"	})
// 再次设定用户渠道，设定无效， "AdSource" 属性值仍然是 "XXX Store"
sensors.profileSetOnce({ AdSource : "Email" })

数值类型的属性

对于数值型的用户属性，可以使用 profileIncrement() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如：

// 将用户游戏次数属性增加一次
sensors.profileIncrement("GamePlayed", 1);

列表类型的属性

对于用户喜爱的电影、用户点评过的餐厅等属性，可以记录列表型属性，例如：

// 设定用户观影列表属性，设定后属性 "Movies" 为: ["Sicario", "Love Letter"]
sensors.profileAppend('Movies', ['Sicario','Love Letter']);

需要注意的是，列表型属性中的元素必须为 String 类型。关于列表型限制请见数据格式。

属性取消

如果需要取消已设置的某个用户属性，可以调用 profileUnset() 进行取消：

sensors.profileUnset("age");

埋点事件采集

在 SDK 初始化完成之后，您可以通过以下接口进行数据埋点。

代码埋点追踪事件

SDK 初始化后，可以通过 track() 方法追踪用户行为事件，并为事件添加自定义属性。

//触发一条 BuyProduct 事件，同时设置商品 ID、商品类别属性
sensors.track('BuyProduct', { ProductID: 123456, ProductCatalog:'Laptop Computer'})

事件名和事件属性的格式规范，请参考数据格式。

埋点事件采集时长属性

可以通过计时器统计事件的持续时间。首先，在事件开始时调用 trackTimerStart("Event") ，该方法并不会真正发送事件；在事件结束时，调用 trackTimerEnd("Event", properties)，SDK 会触发 "Event" 事件，并自动将事件持续时间记录在事件属性 "$event_duration" 中。例如记录用户浏览商品页面的时间：

sensors.trackTimerStart('ViewProduct');   
// 调用 track，记录 ViewProduct 事件，并在属性 event_duration 中记录用户浏览商品的时间
sensors.trackTimerEnd('ViewProduct', {product_id:'PRODUCT_ID'}); 

多次调用 trackTimerStart("Event") 时，事件 "Event" 的开始时间以最后一次调用时为准。注意务必确保 trackTimerStart 和 trackTimerEnd 接口配对使用，多次调用 trackTimerEnd 会触发无时长的埋点事件。

统计事件时长支持暂停和恢复，通过调用 trackTimerPause(String eventName) 和 trackTimerResume(String eventName) 来分别实现暂停和恢复。如果需要清空已记录的时长事件则调用 clearTrackTimer() 接口。

物品元数据上报

设置物品属性

直接设置一个物品，如果已存在则覆盖。除物品 ID 与物品所属类型外，其他物品属性需在 properties 中定义。物品属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。

// 为物品类型为 itemType 且物品 ID 为 itemId 的物品，设置物品属性 
sensors.itemSet('itemType', 'itemId', {
                    price: 100,
                  })

删除物品属性

如果物品不可被推荐需要下线，删除该物品即可，如不存在则忽略。除物品 ID 与 物品所属类型外，不解析其他物品属性。

// 删除物品，类型为 itemType，ID 为 itemId 
sensors.itemDelete(itemType, itemId);

事件属性

在进行埋点事件追踪时，您可以根据需求对埋点事件进行属性的定义。目前 SDK 中提供了公共属性用于给每个埋点事件添加属性，同时公共属性又分为静态公共属性和动态公共属性。静态公共属性用于设置更新频率较低的属性，动态公共属性用于设置更新频率高的属性。当同一事件中出现相同 Key 的属性时，SDK 覆盖优先级：预置属性 < 静态公共属性 < 动态公共属性 < 自定义属性。

获取预置属性

可以调用 getPresetProperties() 方法获取预置属性。服务端埋点需要 App 端的一些预置属性时，可以通过此方法获取 App 端的预置属性，再传给服务端。

//获取预置属性 
sensors.getPresetPropertiesPromise().then((result) => {
                     var presetProperties = result;
                  })

静态公共属性

静态公共属性是指对于所有事件都需要添加的属性，初始化 SDK 后，可以通过 registerSuperProperties() 将属性注册为公共属性。设置方法如下:

// 将应用名称作为事件公共属性，后续所有 track 类型事件都会自动带上 "AppName" 属性
sensors.registerSuperProperties({
                    AppName: 'AppName'
                  })

注册的静态公共属性可以通过 unregisterSuperProperty(key:string) 方法删除指定 key 的静态公共属性。

设置事件动态公共属性

对于本次应用生命周期内所有事件都需要添加，且属性值经常发生变化的属性。初始化 SDK 后，可以使用 registerDynamicSuperProperties() 方法获取监听对象：

import sensors from 'sensorsdata-analytics-react-native';

var dynamic = sensors.registerDynamicSuperProperties();
//赋值给监听对象的 properties 属性，设置为动态公共属性
 onPress={() => {
    dynamic.properties = {subject.key1:subject.key2}
    }
}

Android SDK 版本需满足 v6.2.1 及以上

iOS SDK 版本需满足 v4.2.1 及以上

数据存储与发送

需要更精细地控制神策分析可以通过以下选项设置数据采集功能。

数据采集

在每次调用 track()、login()、profileSet() 等方法时，神策分析 SDK 会将埋点事件保存在数据库中，并会检查如下条件，以判断是否向服务器上传数据:

1. 是否是 WIFI/2G/3G/4G/5G 网络条件
2. 是否满足发送条件之一:
   1. 与上次发送的时间间隔是否大于 flushInterval
   2. 本地缓存日志数目是否大于 flushBulkSize
   3. 事件类型为 login() 方法触发的 $SignUp 事件

默认的 flushBulkSize 为 100 条，默认的 flushInterval 为 15 秒。满足条件后，神策分析 SDK 会将数据 gzip 压缩后，批量发送到神策分析。

如果追求数据采集的时效性，可以调用 flush() 方法，强制将数据发送到神策分析，例如：

// 记录用户登录事件
sensors.track("UserLogin");

// 强制发送数据
sensors.flush();

在 App 进入后台状态或网络切换到有网络时，SDK 会调用 flush() 方法，将缓存的数据发送到神策分析。

设置发送数据的网络策略

默认情况下，在 WIFI/3G/4G/5G 网络条件下，SDK 都会尝试去同步数据。 sensors.setFlushNetworkPolicy() 方法来指定发送数据的网络策略。例如：

/**
 * 设置 flush 时网络发送策略，默认 3G、4G、WI-FI 环境下都会尝试 flush
 * TYPE_NONE = 0;//NULL
 * TYPE_2G = 1;//2G
 * TYPE_3G = 1 << 1;//3G 2
 * TYPE_4G = 1 << 2;//4G 4
 * TYPE_WIFI = 1 << 3;//WIFI 8
 * TYPE_5G = 1 << 4;//5G 16
 * TYPE_ALL = 0xFF;//ALL 255
 * 例：若需要开启 4G 5G 发送数据，则需要设置 4 + 16 = 20
 */
//指定只在 3G/4G/WIFI 条件下发送数据。
sensors.setFlushNetworkPolicy(14);

清空本地缓存事件

可以通过 deleteAll() 方法，删除 App 本地存储的所有事件。

如果不是特殊要求，请不要调用此方法。

//删除 App 本地存储的所有事件
sensors.deleteAll();

全埋点

全埋点是指 $AppStart（App 启动）、$AppEnd（App 退出）、$AppViewScreen（浏览页面） 和 $AppClick（控件点击） 四种事件。
针对 App 启动和退出，Android SDK 为了应对多进程、强杀等场景，加入了 30 秒的 session 机制，用户退出 App 到后台 30 秒的时候，才会触发退出事件，之后再启动 App，才会触发启动事件，用户如果在 30 秒内打开了 App，那么是没有对应的退出事件与启动事件的。另外，如果在退出 App 到后台 30 秒内，进程还没有被杀掉，那么此时会触发退出事件并尝试上报，如果进程被杀掉了，那么退出事件会在下一次启动时补发。所以在查看数据时，一般退出事件比启动事件少。

开启全埋点

SDK 可以自动采集一些用户行为，如 App 启动、退出、浏览页面、控件点击。初始化 SDK 时，可以配置需要开启的全埋点类型：

sensors.init({
	//... 其他配置
    auto_track:SAAutoTrackType.START|SAAutoTrackType.END|SAAutoTrackType.CLICK|SAAutoTrackType.VIEW_SCREEN
})

忽略 React Native 全埋点采集

由于存在混合开发的场景，支持单独关闭 React Native 的页面浏览和元素点击，在项目 package.json 中增加 sensorsData 配置：

 {
  "name": "reactNativeDemo",
  //...
  "sensorsData": {
    "ignoreScreen": true ,//忽略页面浏览
    "ignoreClick": true   //忽略点击事件
  }
}

配置后需要重新执行 node node_modules/sensorsdata-analytics-react-native/SensorsDataRNHook.js -run 命令 

全埋点事件属性补充

如果在使用全埋点 App 页面浏览和 App 元素点击时遇到如下问题：

· 需要给 App 点击事件或 App 页面浏览事件添加自定义属性
· 部分预置属性未采集到，如图片按钮采集不到 $element_content 属性，页面未采集到 $title 属性
· 采集的预置属性不符合业务需求

此时可以通过 SDK 提供的方法修改或者补充默认的属性取值。

设置页面自定义属性

在通过 Navigation  跳转时，可以在 params 中添加自定义属性，SDK 会自动使用 params 中的设置值对 App 页面浏览事件的属性进行补充或覆盖。

 
		this.props.navigation.navigate('PersonCenter',{
			sensorsdataparams:{
				$title: 'title',//默认为 routename，
				param1: 'param1',
				param2: 'param2',
		},
	})
}>

设置控件自定义属性

 {}}
  title="button"
  sensorsdataparams={{ name: 'button', ignore: true }}
/>
 {}}
  sensorsdataparams={{ name: 'TouchableHighlight', ignore: true }}
>
 TouchableHighlight
 

忽略单个页面全埋点事件

目前忽略 $AppViewScreen 事件有两种方式：

方式 一

在 params 中添加 sensorsdataparams 属性，当其中包含 SAIgnoreViewScreen 属性且值为 true 时会忽略该页面浏览事件，但该页面的点击事件仍然为该页面 $screen_name 。

createBottomTabNavigator(
  {
    Component: {
      screen: Tab1,
      params: {
        sensorsdataparams: {
          $screen_name: "screen",
          $title: "title",
          SAIgnoreViewScreen:true
        },
      },
    },
    API: {
      screen: Tab2,
    },
    Other: {
      screen: Tab3,
    },
  }
)

方式二

在通过 navigate、pop、goBack、push 等方式进行导航时，在 params 中添加 sensorsdataparams 属性，当其中包含 SAIgnoreViewScreen 属性且值为 true 时会忽略该页面浏览事件，但该页面的点击事件仍然为该页面 $screen_name 。

this.props.navigation.navigate(‘RouteName’, {
  sensorsdataparams: {
    $screen_name: "screen",
    $title: "title",
    SAIgnoreViewScreen : true
  },
})

忽略组件采集

在 sensorsdataparams 中包含 ignore 属性且值为 true 时忽略该组件的点击事件。

 {}}
/>

全埋点支持版本

• App  元素点击事件支持 React Native 0.23 ~ 0.70.0;
• App 页面浏览事件支持 React Navigation ^2.0 ~ ^6.0；
• App 可视化全埋点要求 React Native 0.46 ~ 0.70.0。

手动触发全埋点事件

手动触发全埋点事件是指由开发者主动调用 SDK 提供的接口触发 App 页面浏览事件，与 SDK 自动触发的全埋点事件的区别是开发者调用接口触发的全埋点事件 lib_method 取值为 code，由 SDK 触发的全埋点事件取值为 autoTrack，注意该功能建议不要与全埋点重复混合使用，防止事件增加。

手动触发页面的浏览事件

通过 trackViewScreen() 方法可以手动触发 App 页面浏览事件，并且该接口不受忽略等条件的限制。

sensors.trackViewScreen(url, {title:'title'})

其他功能

可视化全埋点

开启可视化全埋点

版本要求

• 神策分析 v1.17.2517+
• Android SDK v4.0.0+
• iOS SDK 

SDK 初始化时，进行如下配置，即可开启可视化全埋点：

sensors.init({
	//... 其他配置
  visualized: {
    auto_track: true,// 可视化开关，默认 false
  }
})

Android 初始化配置可参考：

iOS 初始化配置可参考：

可视化全埋点自定义属性

版本要求

• 神策分析 v1.17.2517+
• Android SDK v6.0.0+
• iOS SDK 

如果您需要使用可视化全埋点自定义属性，需进行如下配置：

sensors.init({
	//... 其他配置
  visualized: {
    properties: true,// 可视化开关，默认 false
  }
})

此属性为 false 的情况下，创建的可视化自定义属性无法采集。开启此开关即可默认开启可视化全埋点。

• 本功能使用前，请确保您 Android 项目中已完成配置 Scheme
• 可视化全埋点在神策分析中的使用，请参考可视化全埋点

Android 初始化配置可参考：

iOS 初始化配置可参考：

开启点击分析功能

版本要求

• 神策分析 v2.2.0.240
• Android SDK v5.0.0 版本及以上

• 此功能依赖于全埋点中点击事件采集的开启
• 使用此功能前，确保您的 App 中配置了当前项目的 Scheme，详细操作可参考配置 Scheme

SDK 初始化时配置 heat_map 属性

sensors.init({
	//... 其他配置
    heat_map: true
})

SDK 网络请求开关

SDK 提供 enableNetworkRequest(boolean isRequest) 的接口用于控制 SDK 的网络请求，参数为 true 表示允许 SDK 发起网络请求，参数为 false 表示禁止 SDK 发起网络请求。注意使用时一定要注意调用时机，防止 SDK 处于禁用网络状态，导致事件无法及时上报。

// 开启网络请求
sensors.enableNetworkRequest(true);
// 禁用网络请求
sensors.enableNetworkRequest(false);