You need to enable JavaScript to run this app.
增长分析（私有化）

增长分析（私有化）

请输入
  • 文档首页
    • 增长分析（私有化）开发者指南数据接入：SDK与生态客户端SDKAndroid SDKAndroid SDK 集成
复制全文
我的收藏
Android SDK
Android SDK 集成
复制全文
我的收藏
Android SDK 集成

文档导读

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

埋点规划

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

基本概念

基本概念

概念说明

埋点规划与 SDK 集成要点

详细指导文档

事件、事件属性、事件公共属性、用户属性

DataFinder 的用户行为数据分析是基于事件+用户模型的分析模型。

  • 事件&事件属性：用户的某一种或一类行为称之为“事件”，事件属性即事件触发时同步采集的事件发生的形式、位置等用来描述事件的信息。例如，某个用户购买了某个商品，则该用户的行为事件为“购买”，事件属性为“商品名称”、“商品分类”、“支付金额”等。
  • 事件公共属性：指不与某个事件强关联、在多个或所有事件中都共同存在的不频繁变化的属性，例如，应用的版本号、设备信息等。
  • 用户&用户属性：用户指的是事件行为的发生主体人。用户属性指的是用户自身状态的属性（与行为无关，例如年龄、性别等）或与行为有关但不常变化的用户相关属性（如 VIP 等级、注册时间等）。

您需根据业务分析需要，规划好待采集的事件、事件属性、用户属性有哪些、类型是什么，进行 SDK 集成时

详细概念介绍请参见数据模型。

埋点、全埋点、自定义埋点

  • 埋点：通过 SDK 的开发，将事件逻辑写入代码的过程，称之为埋点。DataFinder 为您提供了预置事件及事件属性，这类事件及事件属性无需您手动埋点，只需打开采集开关即可。
  • 全埋点：是 DataFinder 提供的预置事件和事件属性的一种，在 DataFinder 中，采集的全埋点事件为 bav2b_click 按钮点击， bav2b_page 页面浏览。不需要研发额外投入，但会以上报大量数据为代价，并且只可以采集简单的 PV、UV，对于丰富业务数据的采集显得有些‘力不从心’。
  • 代码埋点：代码埋点指的是开发工程师，按照业务个性化需求，人工写入代码中以实现数据采集逻辑。采集范围广、应用灵活。但需要研发投入，且需要一定的技术能力。

通常建议您结合 DataFinder 提供的预置事件/属性和自定义埋点进行埋点规划。

埋点、全埋点

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

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

字段

作用

Android 端数据示例

header

存放事件公共属性。
app_id、os_name 这些都是预置的，会直接放在 header下，如果是您自定义设置的事件公共属性，会放到header.custom 下。

{
  "magic_tag":"ss_app_log",
  "header":{
    "platform":"Android",
    "sdk_lib":"Android",
    "device_model":"M2012K11AC",
    "device_brand":"Redmi",
    "device_manufacturer":"Xiaomi",
    "cpu_abi":"arm64-v8a",
    "sdk_target_version":29,
    "os":"Android",
    "os_api":33,
    "os_version":"13",
    "sdk_version":61710190,
    "sdk_version_code":16169789,
    "sdk_version_name":"6.17.1",
    "channel":"test",
    "not_request_sender":0,
    "aid":*******,
    "app_region":"CN",
    "user_unique_id":"test_unique_id",
    "density_dpi":440,
    "display_density":"xxhdpi",
    "resolution":"2400x1080",
    "language":"zh",
    "timezone":8,
    "region":"CN",
    "tz_name":"Asia\/Shanghai",
    "tz_offset":28800,
    "access":"wifi",
    "package":"com.bytedance.test",
    "app_version":"2.3",
    "version_code":11,
    "update_version_code":11,
    "manifest_version_code":11,
    "display_name":"AppLog",
    "rom":"MIUI-V816.0.6.0.TKHCNXM",
    "rom_version":"miui_V816_V816.0.6.0.TKHCNXM",
    "bd_did":*******,
    "install_id":*******,
    "register_time":1744808564902,
    "sig_hash":*******,
    "sim_region":"gb",
    "carrier":"中国移动",
    "mcc_mnc":"46000",
    "clientudid":"ca9cc331-7103-4731-b737-048fbd1c03f2",
    "openudid":*******,
    "cdid":"64234011-3fd2-49f4-ba3e-c7e80cf67070",
    "oaid":*******,
    "ssid":*******
  },
  "launch":[
    {
      "local_time_ms":1744808577740,
      "tea_event_index":1001,
      "session_id":"0ce8d2ed-f4c4-4d71-9d2a-f322f6ce6137",
      "user_unique_id":"test_unique_id",
      "ssid":*******,
      "datetime":"2025-04-16 21:02:57",
      "ab_sdk_version":"348170",
      "$page_title":"初始化页面",
      "$page_key":"com.bytedance.test.InitActivity",
      "$resume_from_background":"false"
    },
  ],
  "terminate":[
    {
      "local_time_ms":1744808575991,
      "tea_event_index":1003,
      "session_id":"1fd1f14a-e32e-47e0-922e-73672aa55de6",
      "stop_timestamp":1744808575,
      "duration":8,
      "datetime":"2025-04-16 21:02:55",
      "user_unique_id":"test_unique_id",
      "ssid":*******,
      "ab_sdk_version":"348170",
      "launch_from":1,
      "$page_title":"初始化页面",
      "$page_key":"com.bytedance.test.InitActivity",
      "activites":[
        [
          "com.bytedance.test.InitActivity",
          4
        ]
    }
  ],
  "event_v3":[
    {
      "local_time_ms":1744808577743,
      "tea_event_index":1002,
      "session_id":"02cd457b-c9bf-4252-8bd2-a940426f18cb",
      "user_unique_id":"test_unique_id",
      "ssid":*******,
      "event":"abtest_exposure",
      "params":{
        "ab_sdk_version":*******,
        "$app_version":"2.3"
      },
      "nt":4,
      "datetime":"2025-04-16 21:02:57",
      "ab_sdk_version":*******
    }
  ],
  "local_time":1744808577
}

事件

存放事件及事件属性。
事件分为 launch、terminate、event_v3。
其中 launch、terminate 为预置的启动、退出事件。
event_v3 存放自定义事件、page 事件等，每个 event_v3 类型事件都有 event、params、local_time_ms、session_id 几个字段，其中local_time_ms、session_id 是SDK自动产生的，而event、params 是业务设置的，event 是事件名，params 存放的是事件属性（值是 JSON 对象进行了序列化操作）。

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

了解用户标识逻辑

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

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

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

说明

  • 如果您的业务中用户实名 ID 有多种 ID 类型，例如，可通过账号 ID、用户手机号等多种 ID 类型来标注用户的实名信息，您也可以使用多ID类型功能，详情请参见使用多ID类型。

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

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

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

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

准备工作

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

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

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

步骤2：获取 APPID

在开始集成前，首先需要在集团中拥有一个应用，进行SDK集成前，您需要获取对应应用的appid、app key、schema等信息。
私有化场景下您可以在「项目中心」->「项目管理」->「项目详情」-> 接入应用的「详情」->「应用ID」中可查看您的appid、app key、schema，详情请参见项目详情与应用列表。
Image

步骤3：获取上报地址

进行数据接入上报时，您需要根据当前的环境类型和端类型确认您的数据上报地址。如果上报地址设置错误，后续会导致您无法正常上报、查询到数据。
私有化部署场景下，您需要获取部署私有化环境时，自行规划配置的数据上送地址。如您不清楚此地址，请联系您的项目经理或客户成功经理。

集成SDK

（可选）下载示例 demo

以下为您提供了一个简单的 Android 项目作为示例 demo，下文的 SDK 集成操作指导也基于此 demo，您可先下载 demo 文件用于学习了解 Android SDK 的集成操作。
基于 Android Studio 2024.2.2 Patch1 & Gradle JDK 21 版本。

FinderDemo.zip
未知大小

step1：添加SDK所需依赖

在 Android Studio 中添加 SDK 仓库与依赖。

操作指导

操作录屏

  1. 添加火山仓库依赖

    • 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/")
        }
    }
}

  2. 添加 SDK 依赖：在 App 级别下 build.gradle 文件的 dependencies 中 引入 SDK。

    // 在 App 级别下 build.gradle 文件的 dependencies 中 引入 SDK，集成 All 版本，推荐此版本
implementation 'com.bytedance.applog:RangersAppLog-All-cn:6.17.6'

// 如您不需要全埋点采集、圈选、web 打通等功能，仅需要自定义埋点，可集成 Lite 版本：
// 在 App 级别下 build.gradle 文件的 dependencies 中引入SDK，集成Lite版本
implementation 'com.bytedance.applog:RangersAppLog-Lite-cn:6.17.6'

示例视频为 Gradle 7.0 以上

step2：初始化 SDK

通常建议集成 Android 时参考以下通用流程：

初始化 SDK ---> 上报自定义事件 ---> 设置自定义用户 ---> 设置上报域名 ---> 验证上报

以下为一个简单的初始化 SDK 代码示例，您可通过此示例来快速了解 SDK 集成时的代码、涉及的初始化接口、典型的配置参数等，后续步骤中会为您逐步介绍 SDK 集成的详细操作要点。

// 第一个参数 APPID: 参考 准备工作-步骤2 获取
// 第二个参数 CHANNEL: 填写渠道信息（您的包当前是上传到哪个渠道，比如小米、华为、Google），请注意不能为空
// yourAPPID、yourCHANNEL 为占位符，请替换为实际内容
final InitConfig config = new InitConfig("yourAPPID", "yourCHANNEL");
// 设置数据上送地址，您需根据使用的 DataFinder 服务所在地域配置上送地址，详情见上文 获取数据上送地址 部分
config.setUriConfig(UriConfig.createByDomain("https://****.****.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();

以下以 Android 原生平台场景项目进行示例，为您逐步演示大部分场景下初始化SDK的代码接入。

上报自定义事件

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

操作指导

截图示例

  • 仅上报事件的代码埋点，示例如下：
// 示例：上报事件 event，该事件不包含属性
// 置于业务逻辑对应位置
AppLog.onEventV3("event");
  • 上报事件和对应属性的代码埋点，示例如下：
// 示例：上报事件 event，该事件包含两个属性
// 一个 string 类型的属性，属性名为 key_string，属性值为 value_string
// 一个 int 类型的属性，属性名为 key_int，属性值为 10
// 置于业务逻辑对应位置
JSONObject paramsObj = new JSONObject();
try {
    paramsObj.put("key_string", "value_string");
    paramsObj.put("key_int", 10);
} catch (JSONException e) {
    e.printStackTrace();
}
AppLog.onEventV3("event", paramsObj);

不带自定义属性：
Image
带自定义属性：
Image

  • 涉及核心API：
    • onEventV3：使用 onEventV3 方法可以上报自定义事件。该方法支持单个事件方式。

设置自定义用户

如果需要设置自定义用户，可以调用 AppLog.setUserUniqueID 方法设置 user_unique_id 属性。
通常对于需要用户实名登录时，业务上会使用一个 ID 来唯一标识这个用户，您可以通过 AppLog.setUserUniqueID 方法上报对应的业务的用户标识 ID。通常这个取值可以通过业务接口获取，或者直接读取已有的固定用户标识 ID 值，以下以上报固定取值作为示例。

操作指导

操作录屏

  • 用户登录
    如您的产品中有账户体系，请在用户登录后立即设置 uuid，以保证用户登录前后口径一致性。 6.13.0+ 版本支持在初始化 AppLog 之前调用，用于设置已登录的用户 uuid。

    // 设置您账号体系的 ID, 并保证其唯一性
// 6.13.0+ 版本支持此方法在初始化 AppLog 前调用
AppLog.setUserUniqueID("your_USER_UNIQUE_ID");

    （6.13.0+ 版本不推荐使用）通过该方法设置 uuid，仅在首次冷启动时设置生效。由于 AppLog.setUserUniqueID 在 6.13.0+ 已支持在初始化之前调用，所以不再推荐使用该方法设置 uuid，建议统一使用 AppLog.setUserUniqueID。

    // 初始化时设置uuid
// 6.13.0+版本请勿使用此方法
config.setUserUniqueId("your_USER_UNIQUE_ID");

  • 用户登出
    在账户登出时调用。

    // 登出时设置 uuid 为 null
AppLog.setUserUniqueID(null);

用户登录：
Image
用户登出
Image

  • 涉及核心API：
    • 您可以通过 AppLog.setUserUniqueID 方法来设置用户的业务标识 ID——user_unique_id，设置前您需要先了解 DataFinder 的用户标识逻辑（详情请参见支持的用户唯一标识），更多 AppLog 接口的介绍和参数说明请参见。

设置上报域名

如果您当前的环境是者私有化环境，您需要设置对应环境的数据上报域名，即在初始化时设置 config.setUriConfig。如果设置不正确后续会导致数据无法正常查询分析。

操作指导

操作录屏

// 第一个参数 APPID: 参考 准备工作-步骤2 获取
// 第二个参数 CHANNEL: 填写渠道信息（您的包当前是上传到哪个渠道，比如小米、华为、Google），请注意不能为空
// yourAPPID、yourCHANNEL 为占位符，请替换为实际内容
final InitConfig config = new InitConfig("yourAPPID", "yourCHANNEL");
// 设置数据上送地址，您需根据使用的 DataFinder 服务所在地域配置上送地址，详情见上文 获取数据上送地址 部分
config.setUriConfig(UriConfig.createByDomain("https://****.****.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();

Image

  • 操作要点：设置数据上报域名前，您需要先明确您使用的环境和所在的地域，根据实际情况设置上报域名。私有化部署场景下，您需要获取部署私有化环境时，自行规划配置的数据上送地址。如您不清楚此地址，请联系您的项目经理或客户成功经理。
  • 涉及核心API：您可以在 InitConfig 接口中：
    • 私有化环境通过设置 setUriConfig 来设置上报域名。
    • 如果您还开启了A/B 实验的场景，您还需根据您使用的环境和所在的地域配置 init 接口中的 A/B 实验的分流地址。

step3：验证上报

使用 Android Devtools 调试工具

  1. 集成 Devtools
接入要求
 - 已接入增长营销套件 Android SDK，支持的最小版本为 6.12.0
 - 仅支持 AndroidX 项目
 - Kotlin版本不低于 1.3.70
 - Android版本不低于 14
 - 项目本身需要依赖recyclerview组件（没有的话可以额外依赖）
debugImplementation 'com.bytedance.applog:RangersAppLog-DevTools:3.4.8'
  1. 查看 SDK 接入版本 / 接入状态

接入栏中显示了 DevTools 对增长营销套件 SDK 的核心信息的检查结果。首次接入增长营销套件 SDK 时可以通过该栏信息判断是否接入成功。
Image

  1. 查看事件状态

在 DevTools 面板中的功能栏点击“事件”即可切换到事件栏。通过实时查看事件信息可以检查事件参数与查看事件状态。
Image

  1. 查看网络状态

在控制台面板中点击“网络抓包”即可进入网络抓包页面。通过网络请求的状态和请求体可以查看埋点上报是否成功。
Image

更多SDK集成实践

SDK 离线集成包说明

详情请参见离线文件说明。

user_unique_id相关

详情请参见user_unique_id 相关。

多实例场景

详情请参见Finder SDK 实例相关。

H5打通介绍

详情请参见H5 打通介绍。

全埋点场景

详情请参见全埋点场景。

更多场景实践

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

埋点数据验证

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

  • 用户细查页面中展示的用户行为流数据通常有固定的格式，主要包括user、header、events三个部分，分别展示采集上报的用户属性数据、公共事件属性属性、事件及事件属性数据，上报的数据包含了开启采集的预置和自定义的数据。
  • 如果在用户细查处能看到对应事件，表明事件上报成功，通过观察事件的属性，可以确认相应属性是否也成功上报上来了。
  • 如果数据没有正常在用户细查中查询到，您可检查一下：

Android SDK API 列表

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

分类

API列表

API说明

主要API

init

是对SDK实例进行初始化配置，init 之后产生的事件就都会存储到本地数据库里确保事件不会丢失。

start

启动 SDK，配合 initConfig.setAutoStart 使用，常用于隐私合规。

onEventV3

上报自定义事件，Android 支持 init 前 / init 后调用。

setUserUniqueID

设置 user_unique_id，可以调用多次，后面设置会覆盖之前相同设置项。

setHeaderInfo

设置事件公共属性，可以调用多次，后面设置会覆盖之前相同设置项。

removeHeaderInfo

移除事件公共属性。

setEncryptAndCompress

设置请求是否压缩加密，默认开启。

getDid

获取当前设备的 device_id。

getSsid

获取当前用户对应的 SSID。

addDataObserver / removeDataObserver

添加 / 移除各类数据回调监听，配套使用。

setGPSLocation

为事件追加 gps 相关自定义属性。

InitConfig API

InitConfig SDK 配置 API 介绍

InitConfig的一系列配置方法。

模块API

AB实验功能及 API 介绍

SDK 提供 AB 实验能力，并提供了一系列的方法：getAbConfig、getAbSdkVersion、getAllAbTestConfigs、setExternalAbVersion、pullAbTestConfigs。

用户属性模块及 API 介绍

提供设置用户属性能力，并提供了一系列的方法：profileSet、profileSetOnce、profileUnset、profileIncrement、profileAppend。

元素曝光功能及 API 介绍

提供设置曝光采集的能力。

相关操作

控制台云控配置

私有化V4.4.0以上版本，DataFinder支持通过服务端下发 SDK 设置，包括上报时机、全埋点开关等，详细介绍文档请查阅：SDK设置。

最近更新时间：2025.12.17 14:22:36
这个页面对您有帮助吗？
有用
有用
无用
无用