Android 集成步骤

重要说明
TikTok 应用事件 SDK 的使用受 TikTok for Business 商业服务条款的约束。使用 TikTok 应用事件 SDK，即表示你还同意遵守 TikTok 商业产品（数据）条款，并且你不会与 TikTok 分享敏感数据。

适用于 Android 的 TikTok 应用事件 SDK 在公共 GitHub 仓库中维护。

前提条件

在开始之前，确保已获取以下 TikTok for Business 账号信息： - 你的 Android 应用的 ID（例如 com.example.app）。这是你的应用包的名称。 - 事件管理工具中应用设置页面的 TikTok 应用 ID。 - 用于验证的应用密钥。如果你没有这些信息，请先查看快速入门，然后再继续操作。

将 SDK 添加为构建依赖项

Maven 集成（推荐）

在项目层级的 build.gradle 文件中，确保已在仓库块中声明 mavenCentral()、google() 和 jitpack.io。

(code curl http)
// project/build.gradle
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}
(/code)

在应用层级的 build.gradle 文件中，添加 TikTok SDK 及其所需库的 implementation 依赖项。

(code curl http)
// app/build.gradle
android {
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
}

dependencies {
    // TikTok App Events SDK
    implementation 'com.github.tiktok:tiktok-business-android-sdk:1.7.0'

    // Required for automatic event reporting and lifecycle tracking
    implementation 'androidx.lifecycle:lifecycle-process:2.3.1'
    implementation 'androidx.lifecycle:lifecycle-common-java8:2.3.1'

    // Required for automatic in-app purchase reporting
    implementation 'com.android.billingclient:billing:6.1.0'

    // Required for Play Store install referrer attribution
    implementation 'com.android.installreferrer:installreferrer:2.2'
}
(/code)

手动集成

从 GitHub 最新发布的版本中下载 .aar 二进制资源。
如果应用模块中不存在 libs 目录（例如 app/libs），请创建一个。
将下载的 .aar 文件复制到 app/libs 目录中。
将依赖项添加到应用层级的 build.gradle 文件中。

(code curl http)
// app/build.gradle
android {
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
}

dependencies {
    // TikTok App Events SDK (Manual)
    implementation files('libs/tiktok-business-android-sdk-1.6.1.aar') // Ensure the filename matches

    // Add the same required libraries as in the Maven setup
    implementation 'androidx.lifecycle:lifecycle-process:2.3.1'
    implementation 'androidx.lifecycle:lifecycle-common-java8:2.3.1'
    implementation 'com.android.billingclient:billing:6.1.0'
    implementation 'com.android.installreferrer:installreferrer:2.2'
}
(/code)

添加权限

在 AndroidManifest.xml 文件中，声明 INTERNET 和 AD_ID 权限。

(code curl http)
<!-- AndroidManifest.xml -->
<manifest ...>
    <uses-permission android:name="android.permission.INTERNET" />
    <!-- Required for advertising and analytics purposes on Android 13+ -->
    <uses-permission android:name="com.google.android.gms.permission.AD_ID" />

    <application ...>
        ...
    </application>
</manifest>
(/code)

ProGuard 混淆

为防止 SDK 在发布版本中被删除或损坏，请将以下规则添加到应用的 proguard-rules.pro 文件中：

(code curl http)
# proguard-rules.pro

# TikTok SDK
-keep class com.tiktok.** { *; }

# Google Play Billing Library
-keep class com.android.billingclient.api.** { *; }

# Google Install Referrer
-keep class com.android.installreferrer.api.** { *; }

# Android Lifecycle
-keep class androidx.lifecycle.** { *; }
(/code)

配置并初始化 SDK

在你的 Application 类中，使用你的应用密钥、应用 ID 以及从事件管理工具获取的 TikTok 应用 ID 创建 TTConfig 实例。然后，调用 TikTokBusinessSdk.initializeSdk 启动 SDK。建议使用完成处理程序来管理成功或失败的情况。

重要说明
此 SDK 仅支持在主进程和主线程中进行初始化和使用。首次初始化时，SDK 还将通过 WebView 获取设备用户代理。为了避免出现锁定冲突，请仅在初始化成功后再使用 WebView。

注意
处理多个 TikTok 应用 ID
如果你使用多个广告账号，可以提供以逗号分隔的 TikTok 应用 ID 字符串。确保该字符串不包含空格，也不以逗号结尾。如果应用 ID 与 TikTok 应用 ID 不匹配，SDK 将无法初始化。

(code curl http)
// YourApplicationClass.java
import com.tiktok.TikTokBusinessSdk;
import com.tiktok.TikTokBusinessSdk.TTConfig;

public class YourApplicationClass extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        TTConfig ttConfig = new TTConfig(getApplicationContext(), "YOUR_APP_SECRET")
            .setAppId("YOUR_APP_ID") // Your app's package name, e.g., com.example.app
            .setTTAppId("YOUR_TIKTOK_APP_ID");

        // For multiple TikTok App IDs:
        // TTConfig ttConfig = new TTConfig(getApplicationContext(), "YOUR_APP_SECRET")
        //    .setAppId("YOUR_APP_ID") // Your app's package name, e.g., com.example.app
        //    .setTTAppId("TIKTOK_APP_ID1,TIKTOK_APP_ID2,TIKTOK_APP_ID3");

        // Continue to initialisation...
        TikTokBusinessSdk.initializeSdk(ttConfig, new TikTokBusinessSdk.TTInitCallback() {
            @Override
            public void success() {
                // SDK initialized successfully
            }
            @Override
            public void fail(int code, String msg) {
                // SDK initialisation failed
            }
        });
    }
}
(/code)

延迟事件传输

在集成 TikTok 应用事件 SDK 时，客户可能需要根据特定司法管辖区的法律要求配置 SDK，以延迟数据传输和事件收集。TikTok 提供相关资源帮助客户遵守这些法律，可按照针对获得用户同意后共享数据的资源中的说明进行集成。

应用事件报告

自动记录的事件

如果在配置过程中未禁用，SDK 会自动记录以下事件。

|事件{20%}<br><br>{50%}|描述{80%}<br><br>{50%}|
|---|---|
|`InstallApp`|安装后首次打开应用。<br><br>首次集成 SDK 时，你可能会发现报告的安装事件数量有所增加。这是正常现象，因为安装量的度量基于 SDK 首次检测到的应用启动。如果你对此有顾虑，请在投放付费推广系列之前预留出几天时间，让现有用户更新应用。|
|`LaunchAPP`|每次打开应用。|
|`2DRetention`|用户在首次打开应用后的次日再次打开应用。|
|`Purchase`|通过 Google Play 结算库成功完成交易。非 Google Play 交易必须手动记录。|

你可以选择禁用自动事件记录。禁用自动事件记录后，将不再默认监测应用安装和打开应用等事件。如果你需要这些事件用于度量或分析，必须在应用代码中部署手动记录，以捕获并发送这些事件。

(code curl http)
TTConfig ttConfig = new TTConfig(getApplicationContext(), "YOUR_APP_SECRET")
    // ... other configurations

    // Option 1: Disable ALL automatic events (Install, Launch, 2DRetention, Purchase)
    .disableAutoEvents()

    // Option 2: Disable specific automatic events
    .disableInstallLogging() // Disable install reporting only
    .disableLaunchLogging() // Disable automatic app launch reporting only
    .disableRetentionLogging() // Disable automatic 2DRetention reporting only
    .disableAutoIapTrack() // Disable automatic Purchase reporting only

TikTokBusinessSdk.initializeSdk(ttConfig);
(/code)

手动记录的事件

标准事件

对于没有属性的简单事件，使用 trackTTEvent() 以及 EventName 枚举值中的事件常量。如需查看 EventName 枚举值的完整列表，参见标准事件常量和事件类。

示例： Registration 事件

(code curl http)
// Example: Track a user registration
TikTokBusinessSdk.trackTTEvent(EventName.REGISTRATION);
(/code)

为标准事件添加属性

对于包含商品或价值详细信息的事件，针对以下标准事件使用 TTContentsEvent Builder 类，针对其他所有标准事件使用 TTBaseEvent ：

|标准事件<br><br>{20%}<br><br>{50%}|Builder 类<br><br>{80%}<br><br>{50%}|
|---|---|
|加入购物车|`TTAddToCartEvent`|
|加入心愿单|`TTAddToWishlistEvent`|
|结账|`TTCheckoutEvent`|
|付费|`TTPurchaseEvent`|
|查看内容|`TTViewContentEvent`|

示例： ViewContent 事件 Builder 类

(code curl http)
// Example: A user views a product
TTContentsEvent viewContentEvent = TTViewContentEvent.newBuilder()
    .setContentType("sku")
    .setCurrency(Currency.USD)
    .setValue(99.99)
    .setDescription("A fantastic product")
    .setContents(TTContentParams.newBuilder()
        .setPrice(99.99f)
        .setQuantity(1)
        .setContentId("12345")
        .setContentCategory("Electronics")
        .setContentName("Wireless Headphones")
        .setBrand("AudioBrand")
        .build())
    .build();

TikTokBusinessSdk.trackTTEvent(viewContentEvent);
(/code)

示例： CompleteTutorial 事件

对于具有标准属性的其他标准事件，使用TTBaseEvent Builder 以及 EventName 枚举值中的常量。

(code curl http)
// Example: A user completes the onboarding tutorial
TTBaseEvent tutorialEvent = TTBaseEvent.newBuilder(EventName.COMPLETE_TUTORIAL)
    .addProperty("currency", "<currency>") // The ISO 4217 currency code
    .addProperty("value", "<value>") // Value of the order or items sold
    .addProperty("content_id", "<content id value>") // Unique ID of the product or content
    .addProperty("content_type", "<content type value>") // The type of content in the event
    .addProperty("price", "<price>") // The price of the item
    .addProperty("quantity", "<quantity>") // The number of items
    .build();

TikTokBusinessSdk.trackTTEvent(tutorialEvent);
(/code)

注意
如需查看受支持标准属性的完整列表，参见属性对象参考。不支持自定义属性键，这些键将被丢弃。

应用内广告收入

SDK 1.5.0 及以上版本支持使用 TTAdRevenueEvent 报告应用内广告聚合收入数据。如需了解 AppLovin Max、ironSource 和 Google AdMob 的详细部署指南，参见应用内广告收入报告。

自定义事件

若想监测未列为标准事件的其他事件，需使用 TTBaseEvent Builder 和自定义事件名称字符串。

(code curl http)
// Example: A user shares content to a social platform
TTBaseEvent customEvent = TTBaseEvent.newBuilder("ShareContent")
    .build();

TikTokBusinessSdk.trackTTEvent(customEvent);
(/code)

启用高级匹配

若想改进受众匹配，需在用户信息可用（例如登录、注册）时使用 identify() 设置高级匹配属性，并使用 logout() 清除这些信息。

(code curl http)
// When user logs in or signs up
TikTokBusinessSdk.identify(
    "user-external-id-123",  // externalId
    "user-name-456",         // externalUserName
    "+15551234567",         // phoneNumber (E.164 format)
    "user@example.com"     // email
);

// When user logs out
TikTokBusinessSdk.logout();
(/code)

验证集成

使用 TikTok 事件管理工具验证是否正确接收事件。这一操作会将事件发送到单独的接口进行测试，不会影响生产环境数据。

无代码测试事件（推荐）

此方法可用于在无需修改代码的情况下，调试特定设备的事件。在开始之前，请确保： - 你的设备上已安装最新版本的 TikTok 应用 - 你的应用中已安装 SDK 1.5.0 或以上版本 - 你已为自己的应用和 TikTok 应用授予广告 ID 权限

|步骤{25%}|说明{75%}|
|---|---|
|生成二维码|<ul><li>在应用的<b>事件管理工具</b>中，前往<b>测试事件</b>选项卡。</li><li>点击<b>生成二维码</b>。系统将生成一个二维码，有效期为 24 小时。</li><li>若想让二维码在到期前提前失效，点击<b>禁用二维码</b>。</li></ul>|
|绑定设备|<ul><li>在测试设备上打开 TikTok 应用，前往<b>主页</b>。</li><li>点击右上角的菜单图标 (☰)，选择<b>我的二维码</b>。</li><li>点击右上角的扫描图标，扫描事件管理工具生成的二维码。</li><li>点击<b>授权</b>，以绑定你的设备并启用测试模式。</li></ul>|
|验证事件|<ul><li>在你的应用中触发事件。这些事件将实时显示在<b>测试事件</b>选项卡中。</li><li>如果你配置了多个 TikTok 应用 ID，事件管理工具中只会显示列表中<b>首个</b> ID 的测试事件。</li></ul>|

手动调试模式

重要说明
在正式发布应用之前，务必禁用手动调试模式和详细日志记录。测试事件将被丢弃，不会用于推广系列报告。

启用调试模式

SDK 必需初始化为调试模式，才能将所有生成的事件标记为测试事件。要做到这一点，需在初始化时将 enableDebugMode() 添加到你的 TTConfig 中。你也可以使用 setLogLevel() 获取更详细的日志输出。

(code curl http)
TTConfig ttConfig = new TTConfig(getApplicationContext(), "YOUR_APP_SECRET")
    .setAppId("YOUR_APP_ID")
    .setTTAppId("YOUR_TIKTOK_APP_ID")
    .openDebugMode() // Enable debug mode
    .setLogLevel(TikTokBusinessSdk.LogLevel.DEBUG) // Enable logging

TikTokBusinessSdk.initializeSdk(ttConfig);
(/code)

可用的日志级别包括： - NONE：不记录。 - INFO：记录信息类消息和异常情况。 - WARN：记录警告和异常情况。 - DEBUG：记录详细的调试输出、异常情况和消息。

禁用调试模式

集成通过验证后，在提交应用之前删除所有 openDebugMode() 和 setLogLevel() 调用。

(code curl http)
// REMOVEME
// ttConfig.openDebugMode()
// ttConfig.setLogLevel(TikTokBusinessSdk.LogLevel.DEBUG)
(/code)

生成和验证事件

启用调试模式后，运行你的应用并触发一些事件。你可以在应用的事件管理工具页面的测试事件选项卡下，实时查看接收到的事件。

如果你的 SDK 配置中包含多个 TikTok 应用 ID，测试事件将仅显示在与配置字符串中的首个 TikTok 应用 ID 关联的广告账号的事件管理工具中。

Asset