下图为您概要介绍 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 端支持的预置事件和属性列表请参见APP预置事件及属性。
• 同时您还需关注当前禁用的预置属性列表，后续规划自定义埋点及属性时需避免与禁用属性同名，否则会导致数据无法正常上报，详情请参见禁用属性列表。

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

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

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

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

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

步骤2：获取 APPID

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

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

步骤3：获取上报地址

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

SaaS环境

私有化环境

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

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

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

添加Flutter插件

1. 在 Flutter 项目的 pubspec.yaml 中添加 rangers_applog_flutter_plugin 依赖

   dependencies:
     # ...
     rangers_applog_flutter_plugin: 1.5.0
   

2. 执行安装

   flutter packages get
   

添加原生端依赖：iOS

在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',
            # 非云原生-海外BytePlus环境
            # 'Host/SG',
            'UITracker'
        ]
# end

添加原生端依赖：Android

关键步骤为添加火山仓库依赖，并添加SDK依赖这两个部分，此部分的操作流程在各个环境中一致，要点如下。

1. 添加火山仓库依赖

   Gradle 7.0 及以下	Gradle 7.0 以上
   在根目录级别的 build.gradle 中添加 maven 仓库 // 在根目录级别的 build.gradle 中添加 maven 仓库 allprojects { repositories { // 其他仓库 // 配置 Finder SDK 拉取仓库 maven { url 'https://artifact.bytedance.com/repository/Volcengine/' } } }	在根目录级别的 setting.gradle 中添加 maven 仓库 // 在根目录级别的 setting.gradle 中添加 maven 仓库 dependencyResolutionManagement { repositories { // 其他仓库 // 配置 Finder SDK 拉取仓库 maven { url = uri("https://artifact.bytedance.com/repository/Volcengine/") } } }

2. 添加 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'
   

添加原生端依赖：鸿蒙

关键步骤为添加必要权限、添加SDK依赖这两个部分，此部分的操作流程在各个环境中一致，要点如下。

1. 添加必要权限。

   在oh-package.json5文件中添加

   在module.json5中添加必要的权限

   { // ... "dependencies": { // sdk 强 依 赖 用 于 gzip 压 缩 "pako": "^2.1.0", // 引入 AppLog 组 件 时， 请确保组 件 名 称 是 这个 "@volcengine/applog": "file:./applogx/applogx.har", // 调 试工具 （可 选 ） "@volcengine/applog_devtools": "file:./applogx/applogx_devtools.har" }, "overrides": { // 重 写 "@volcengine/applog": "file:./applogx/applogx.har", } }

   requestPermissions: [ { // 网 络 权 限 ，必 要 添 加 name: 'ohos.permission.INTERNET', }, { // wifi 信 息获取，必 要 添 加 name: 'ohos.permission.GET_WIFI_INFO', }, { // 获取网 络 信 息，必 要 添 加 name: 'ohos.permission.GET_NETWORK_INFO', }, { // 资产 持 久 化 ，建 议 添 加，与 deviceId name: 'ohos.permission.STORE_PERSISTENT_DATA', }, { // oaid 权 限 （可 选 ），建 议 添 加 name: 'ohos.permission.APP_TRACKING_CONSENT', reason: '$string:app_name', usedScene: { abilities: [], when: 'inuse', }, }, ],

2. 在鸿蒙原生工程添加插件（一般安装依赖后会自动link上，需要自己检查一下）。

   // GeneratedPluginRegistrant.ets
   import RangersApplogFlutterPlugin from 'rangers_applog_flutter_plugin';
   
   export class GeneratedPluginRegistrant {
     static registerWith(flutterEngine: FlutterEngine) {
       try {
         // ...
         // 这里添加RangersApplogFlutterPlugin
         flutterEngine.getPlugins()?.add(new RangersApplogFlutterPlugin());
       } catch (e) {
         // ...
       }
     }
   }
   

添加原生端依赖：其他端

step2：初始化 SDK

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

导入并初始化

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

// 初始化SDK
String appId = '{{APPID}}'; // 替换成自己的
String channel = '{{CHANNEL}}'; // 填写App下载/分发渠道，例如iOS一般是'App Store'
bool enableEncrypt = true; // 加密开关
bool enableDebugLog = false; // 原生端日志开关
bool enableAB = false; // AB实验开关

// 设置数据上送地址，假设国内-华北
String? host = 'https://gator.volces.com';

RangersApplogFlutterPlugin.addInitParams({
    'service_vendor': 'private', // 固定值 private
});

RangersApplogFlutterPlugin.initRangersAppLog(appId, channel, enableAB, enableEncrypt, enableDebugLog, host);

关于各环境上报域名示例
设置数据上报域名前，您需要先明确您使用的环境和所在的地域，根据实际情况设置上报域名。确认您当前使用的环境类型请参见：SaaS云原生/非云原生&私有化环境。

// 初始化SDK
// ...

// 设置数据上送地址
// 国内-华北
String? host = 'https://gator.volces.com';
// 国内-华南
// String? host = 'https://gator.uba.cn-guangzhou.volces.com';
// 海外-柔佛
// String? host = 'https://gator.uba.ap-southeast-1.volces.com';

RangersApplogFlutterPlugin.addInitParams({
    'service_vendor': 'private', // 固定值 private
});

// ...

// 初始化SDK
// ...

// 设置私有化部署数据上送地址，{{REPORT_URL}} 例如 https://yourdomain.com，注意域名后不要加“/”
String? host = '{{REPORT_URL}}';

RangersApplogFlutterPlugin.addInitParams({
    'service_vendor': 'private', // 固定值 private
});

// ...

// 初始化SDK
// ...

// 非云原生环境使用默认的数据上报地址
String? host = '';

RangersApplogFlutterPlugin.addInitParams({
    // 国内环境
    'service_vendor': '',
    // 海外byteplus
    // 'service_vendor': 'sg',
});

// ...

上报自定义事件

根据埋点规划，如果需要采集上报自定义事件，您可以使用“onEventV3”设置自定义事件名和事件属性。

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

// 示例：上报事件event_name，该事件不包含属性
RangersApplogFlutterPlugin.onEventV3("event_name");

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

设置用户登录态

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

import 'package:rangers_applog_flutter_plugin/rangers_applog_flutter_plugin.dart';

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

step3：验证上报

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

• iOS端：请参考iOS SDK 集成中step3：验证上报部分。
• Android端：请参考Android SDK 集成中step3：验证上报部分。
• 鸿蒙端：请参考HarmonyOS Next SDK 集成中DevTools 工具部分。

更多SDK集成实践

事件公共属性

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

上报自定义用户属性

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

全埋点采集

详情请参见全埋点场景。

更多场景实践

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

埋点数据验证

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

• 用户细查页面中展示的用户行为流数据通常有固定的格式，主要包括user、header、events三个部分，分别展示采集上报的用户属性数据、公共事件属性属性、事件及事件属性数据，上报的数据包含了开启采集的预置和自定义的数据。
• 如果在用户细查处能看到对应事件，表明事件上报成功，通过观察事件的属性，可以确认相应属性是否也成功上报上来了。
• 如果数据没有正常在用户细查中查询到，您可检查一下：
  • 上报数据的数据格式等是否符合要求：支持的数据格式与事件/属性分类。
  • 检查下集成代码中的AppID是否正确：导入并初始化。
  • SaaS-云原生环境和私有化环境的话，需检查下集成代码中的上报域名是否配置正确：设置上报域名。

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