下图为您概要介绍 SDK 集成相关文档的组织思路，您可参考以下导读示意图了解文档结构，查阅对应文档完成 集成操作。

在进行 SDK 集成前，您需结合您的业务分析情况先进行埋点规划，明确出待分析的业务指标中可能需要埋点的事件有哪些、属性有哪些等。进行埋点规划时，您需了解一些基本概念和 DataFinder 为您预置提供的埋点事件和属性、DataFinder 的用户标识逻辑等前置信息，结合 DataFinder 为您提供的能力进行埋点规划。

基本概念

了解数据上报要求（格式、数量限制等）

进行埋点规划时，您需明确清楚需采集上报的事件、属性的数据格式要求，以及采集上报的一些限制要求，避免后续因为数据格式等不满足要求，进而导致数据采集后无法入库、后续无法查询分析。
SDK上报的数据通常有固定的格式，主要包括 header、事件两个部分。

其中，需要上报自定义事件、自定义属性时，您需确保事件和属性的数据格式符合要求，当前 DataFinder 支持的数据格式要求和数据上报的限制请参见支持的数据格式与事件/属性分类。
常见问题：

• 事件属性数据类型传输错误，需要修改怎么办？Q1：事件属性数据类型传输错误，需要修改怎么办？
• 各端数据类型传输不一致，系统如何处理？如何修改？Q2： 各端数据类型传输不一致，系统如何处理？如何修改？

了解用户标识逻辑

进行埋点规划时，您需要了解 DataFinder 的用户标识逻辑，用于结合自身业务的用户标识逻辑进而最终统一用户的标识数据来源。DataFinder 默认以用户作为统计分析的对象，默认使用 SSID 作为用户唯一标识 ID 来计算指标，此时用户的 SSID 就是默认的统计口径。当您的分析对象为用户时，建议保持默认统计口径 SSID，DataFinder 可通过 ID_Mapping 将用户的device_id、user_unique_id 等进行 mapping 后，尽量通过一个 SSID 还原一个真实的用户个体。

• device_id：可作为设备的唯一 id，多为无法获取用户实名 id的场景下使用。
• user_unique_id：为登录态用户标识，多为在能获取用户实名 ID 场景下使用，一般情况直接使用产品业务中使用的用户标识，比如登录账号。当 user_unique_id 未设定时，在 SaaS 版本中，系统会自动使用 device_id 替代。
• SSID：为 DataFinder 的用户统计口径 ID，与设备标识 device_id、登录态用户标识 user_unique_id 互相 Mapping，能保证用户匿名和实名状态下的 ID 统一。

三类 ID 的 mapping 逻辑和更多关于用户标识的介绍详情请参见支持的用户唯一标识。

了解客户端支持的预置事件和属性

如上文所述，大部分业务分析场景中，您需要结合自身业务特性进行自定义埋点的规划和集成，在此之前，您可以先了解下当前 DataFinder 已为您提供的预置事件、预置属性有哪些，结合已有的预置事件和属性能力，进一步规划自定义代码埋点的需求。

• App 端支持的预置事件和属性列表请参见Android端预置事件及属性。
• 同时您还需关注当前禁用的预置属性列表，后续规划自定义埋点及属性时需避免与禁用属性同名，否则会导致数据无法正常上报，详情请参见禁用属性列表。

梳理埋点需求设计埋点方案

• 如何梳理需求
• 如何设计埋点采集方案
• 指标体系demo
• 埋点方案模板

步骤1（可选）：创建埋点需求/录入自定义埋点

完成埋点规划后，建议您根据规划将埋点需求创建再 DataFinder 的需求管理页面，并将自定义埋点先录入 DataFinder 完成自定义埋点在 DataFinder 元数据的入库。

• 埋点需求管理：您可以通过 DataFinder 的埋点需求管理功能来管理埋点需求，后续可在埋点需求管理页面中持续维护和管理需求，提高管理效率。创建埋点需求管理的操作请参见需求管理。
• 自定义埋点录入：您可以根据埋点规划，先将自定义埋点创建录入至 DataFinder 的元数据，操作详情请参见新增事件、新增事件属性、新增用户属性。

步骤2：获取 APPID

在开始集成前，首先需要在集团中拥有一个应用，进行 SDK 集成前，您需要获取对应应用的 appid 信息。

• SaaS-云原生场景下，您可以在「项目中心」->「项目管理」->「项目详情」-> 接入应用的「详情」->「应用 ID」中可查看您的 appid，详情请参见项目管理。
  
• SaaS-非云原生场景下，您可以在「应用列表」-> 接入应用的「详情」->「应用 ID」中可查看您的 appid，详情请参见应用列表。
  

步骤3：获取上报地址

进行数据接入上报时，您需要根据当前的环境类型和端类型确认您的数据上报地址。如果上报地址设置错误，后续会导致您无法正常上报、查询到数据。

获取数据上报地址

SaaS-云原生 & SaaS-非云原生

私有化环境

私有化部署场景下，您需要获取部署私有化环境时，自行规划配置的数据上送地址。如您不清楚此地址，请联系您的项目经理或客户成功经理。

（可选）下载示例 demo

以下为您提供了一个简单的 React Native 项目作为示例 Demo，您可先下载 Demo 文件用于学习了解 React Native SDK 的集成操作。

注意：使用Demo时请将其中的app_id和上报域名更换成自己的。

Demo	带全埋点Demo
ReactNavigationExample.zip 未知大小	ReactNavigationExample_带全埋点.zip 未知大小

step1：添加React Native插件以及原生端依赖

使用React Native插件以及原生端依赖，具体操作如下：

添加React Native插件

npm install rangers_applog_reactnative_plugin

添加原生端依赖

• iOS原生端依赖配置及安装

  说明

  详细配置请参考iOS SDK 集成文档中step1：添加SDK所需依赖部分，这边只列出关键部分以示例。

  在Podfile中，添加source源，并引入SDK，并执行pod install --repo-update更新Pods。

  云原生环境	私有化	非云原生环境
  source 'https://github.com/volcengine/volcengine-specs.git' # target 'TestDemo' do # ... pod 'RangersAppLog', '6.17.3', :subspecs => [ 'Core', 'UITracker' ] # end	source 'https://github.com/volcengine/volcengine-specs.git' # target 'TestDemo' do # ... pod 'RangersAppLog', '6.17.3', :subspecs => [ 'Core', 'UITracker' ] # end	source 'https://github.com/volcengine/volcengine-specs.git' # target 'TestDemo' do # ... pod 'RangersAppLog', '6.17.3', :subspecs => [ 'Core', # 非云原生-国内 'Host/CN', # 非云原生-海外 # 'Host/SG', 'UITracker' ] # end

• Android原生端依赖配置及安装

  说明

  详细配置请参考Android SDK 集成文档中step1：添加SDK所需依赖部分，这边只列出关键部分以示例。

  添加火山仓库依赖，并添加SDK依赖。

  全部环境一致

  添加火山仓库依赖 Gradle 7.0 以下：在根目录级别的 build.gradle 中添加 maven 仓库 // 在根目录级别的 build.gradle 中添加 maven 仓库 allprojects { repositories { // 其他仓库 // 配置 Finder SDK 拉取仓库 maven { url 'https://artifact.bytedance.com/repository/Volcengine/' } } } Gradle 7.0 以上：在根目录级别的 setting.gradle 中添加 maven 仓库 // 在根目录级别的 setting.gradle 中添加 maven 仓库 dependencyResolutionManagement { repositories { // 其他仓库 // 配置 Finder SDK 拉取仓库 maven { url = uri("https://artifact.bytedance.com/repository/Volcengine/") } } } 添加 SDK 依赖：在 App 级别下 build.gradle 文件的 dependencies 中 引入 SDK。 // 在 App 级别下 build.gradle 文件的 dependencies 中 引入 SDK，集成 All 版本，推荐此版本 implementation 'com.bytedance.applog:RangersAppLog-All-cn:6.17.1' // 如您不需要全埋点采集、圈选、web 打通等功能，仅需要自定义埋点，可集成 Lite 版本： // 在 App 级别下 build.gradle 文件的 dependencies 中引入SDK，集成Lite版本 implementation 'com.bytedance.applog:RangersAppLog-Lite-cn:6.17.1'

step2：初始化 SDK

以下示例，为您逐步演示大部分场景下初始化SDK的代码接入。

导入并初始化

• iOS端请参考：

  操作指导

  Objective-C请参考： #import <RangersAppLog/BDAutoTrack.h> #import <RangersAppLog/BDAutoTrackConfig.h> - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { /* 初始化SDK开始 */ BDAutoTrackConfig*config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:launchOptions]; // 设置渠道，iOS一般默认App Store渠道 config.channel = @"App Store"; // 设置数据上送地址，您需根据使用的DataFinder服务所在地域配置上送地址，详情见上文 获取数据上送地址 章节 config.serviceVendor = BDAutoTrackServiceVendorPrivate; BDAutoTrackRequestHostBlock block = ^NSString *(BDAutoTrackServiceVendor vendor, BDAutoTrackRequestURLType requestURLType) { return @"https://gator.volces.com"; }; [BDAutoTrack setRequestHostBlock:block]; config.autoTrackEnabled = YES; // 全埋点开关，YES开启，NO关闭 config.showDebugLog = NO; // YES:开启日志，NO:关闭日志 config.logNeedEncrypt = YES; // 加密开关，YES开启，NO关闭 [BDAutoTrack sharedTrackWithConfig:config]; /* 初始化SDK结束 */ // 授权后 [[BDAutoTrack sharedTrack] startTrack]; //SDK启动 return YES; } Swift请参考： import RangersAppLog func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { /* 初始化SDK开始 */ let config = BDAutoTrackConfig(appID: "{{APPID}}") // 设置渠道，iOS一般默认App Store渠道 config.channel = "App Store" // 设置数据上送地址，您需根据使用的DataFinder服务所在地域配置上送地址 config.serviceVendor = .private BDAutoTrack.setRequestHostBlock {(vendor: BDAutoTrackServiceVendor, requestURLType:BDAutoTrackRequestURLType) -> String? in return "https://gator.volces.com" } config.autoTrackEnabled = true // 全埋点开关，true开启，false关闭 config.showDebugLog = false // true:开启日志，需要参考4.3设置Logger，false:关闭日志 config.logNeedEncrypt = true // 加密开关，true开启，false关闭 BDAutoTrack.sharedTrack(with: config) /* 初始化SDK结束 */ BDAutoTrack.shared().start() //SDK启动 return true }

• Android端请参考：

  操作指导

  // 第一个参数 APPID: 参考 准备工作-步骤2 获取 // 第二个参数 CHANNEL: 填写渠道信息（您的包当前是上传到哪个渠道，比如小米、华为、Google），请注意不能为空 // {{APPID}}、{{CHANNEL}} 为占位符，请替换为实际内容 final InitConfig config = new InitConfig("{{APPID}}", "{{CHANNEL}}"); // 设置数据上送地址，您需根据使用的 DataFinder 服务所在地域配置上送地址， // 此处以SaaS-云原生的华北地域做示例，详情见上文 获取数据上送地址 部分 config.setUriConfig(UriConfig.createByDomain("https://gator.volces.com", null)); // 确保 start 才开始用用户信息采集 config.setAutoStart(false); // 全埋点开关，true开启，false关闭 config.setAutoTrackEnabled(true); // true:开启日志，false:关闭日志，默认关闭，可在本地调试时打开 config.setLogEnable(false); // 加密开关，true:开启，false:关闭 AppLog.setEncryptAndCompress(true); // 初始化一次即可 // Applition 中初始化建议使用该方法 AppLog.init(this, config); // Activity 中初始化建议使用该方法 AppLog.init(this, config, this); // 请在用户授权后调用如下方法，start 开始实际采集用户信息+上报： AppLog.start();

上报自定义事件

在原生端代码中完成初始化后，就可以在React Native侧使用onEventV3来上报自定义事件了。

import { NativeModules } from 'react-native';
const { RangersAppLogModule } = NativeModules;

// 示例：上报事件event_name，该事件包含两个属性
//      一个string类型的属性，属性名为key_string，属性值为value_string
//      一个int类型的属性，属性名为key_int，属性值为10
RangersAppLogModule.onEventV3("event_name", {
    "key_string": "value_string",
    "key_int": 10
});

设置用户登录态

如果需要设置用户登录态，可以在React Native侧使用setUserUniqueId 方法设置 user_unique_id 属性。
通常对于需要用户实名登录时，业务上会使用一个 ID 来唯一标识这个用户，您可以通过 setUserUniqueId 方法上报对应的业务的用户标识 ID。通常这个取值可以通过业务接口获取，或者直接读取已有的固定用户标识 ID 值。如果您需要了解 DataFinder 的用户标识逻辑，详情请参见支持的用户唯一标识。

import { NativeModules } from 'react-native';
const { RangersAppLogModule } = NativeModules;

// 登录时设置您账号体系的ID, 并保证其唯一性
RangersAppLogModule.setUserUniqueId('{{USER_UNIQUE_ID}}');

step3：验证上报

目前可以参考各个原生端的验证方式。

• iOS端：请参考iOS SDK 集成中step3：验证上报部分。
• Android端：请参考Android SDK 集成中step3：验证上报部分。

更多SDK集成实践

事件公共属性

详情请参见事件公共属性。

上报自定义用户属性

详情请参见user_unique_id、用户属性相关。

全埋点采集

详情请参见全埋点场景。

更多场景实践

更多场景实践请参见React Native SDK 集成场景实践。

埋点数据验证

完成初始化验证后，您可以在客户端进行测试操作，触发一些待采集上报的事件，测试事件上报后，大约15分钟内，您可以在增长分析平台中的用户细查页面查看具体用户行为流数据，即能看到测试事件及事件属性数据，用于验证埋点数据是否可正常采集上报。

• 用户细查页面中展示的用户行为流数据通常有固定的格式，主要包括user、header、events三个部分，分别展示采集上报的用户属性数据、公共事件属性属性、事件及事件属性数据，上报的数据包含了开启采集的预置和自定义的数据。

• 如果在用户细查处能看到对应事件，表明事件上报成功，通过观察事件的属性，可以确认相应属性是否也成功上报上来了。

• 如果数据没有正常在用户细查中查询到，您可检查一下：

  • 上报数据的数据格式等是否符合要求：支持的数据格式与事件/属性分类。
  • 检查下集成代码中的AppID是否正确：导入并初始化。
  • SaaS-云原生环境和私有化环境的话，需检查下集成代码中的上报域名是否配置正确。
  
  

DataFinder为您提供了丰富的API接口，除了上述通用流程中介绍的核心接口和典型场景的使用示例外，您也可以了解当前iOS 支持的主要API接口和其作用，根据业务需求可灵活调用对应接口完成业务数据埋点。