Unity 集成步骤

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

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

前提条件

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

将 SDK 添加为构建依赖项

注意
要将 TikTokBusinessSDK.unitypackage 集成到 Unity 中，必须先安装 Newtonsoft Json。如需详细了解如何添加此依赖项，参见 NuGet 文档。

步骤	描述	截图
0	从 GitHub 仓库下载最新的 TikTokBusinessSDK.unitypackage。	N/A
1	前往 Assets > Import Package > Custom Package
2	选择 TikTokBusinessSDK.unitypackage
3	点击 All， 然后点击 Import

在某些版本的 Unity 中，.xcframework 文件可能被识别为文件夹（如图 1 所示的错误）。在为 iOS 导出时，若想解决此问题，需在该文件夹内为不同的框架架构选择所需的平台。如图 2 和图 3 所示，在检查器中为 iOS 导出选择 ARM64 架构文件夹 (ios-arm64)，而未选择 x86 架构 (ios-arm64_x86_64)。

从现有原生 Android 或 iOS SDK 迁移至 Unity

已集成 Android（Java、Kotlin）原生 TikTok 应用事件 SDK 或 iOS（Swift、Objective-C）原生 TikTok 应用事件 SDK 的开发者可通过以下方式迁移至 Unity SDK： - 将 TikTokBusinessSDK.xcframework (iOS) 和 tiktok-business-android-sdk (Android) 的集成方法更换为 TikTokBusinessSDK.unitypackage (Unity)，以及 - 使用我们提供的 C# 接口替换所有现有的原生配置和桥接接口。混合接口可能会导致代码冲突，因此既不推荐也不支持使用。

配置并初始化 SDK

在游戏的首个场景显示前，尽早初始化 SDK。 建议在Awake时调用它。

注意
此 SDK 仅支持在主进程和主线程中进行初始化和使用。 首次初始化时，Android SDK 会通过 WebView 获取设备用户代理。为了避免出现锁定冲突，请仅在初始化成功后再使用 WebView。 如果你使用多个广告账号，可以提供以逗号分隔的 TikTok 应用 ID 字符串。确保该字符串不包含空格，也不以逗号结尾。如果应用 ID 与 TikTok 应用ID 不匹配，SDK 将无法初始化。

(code curl http)
using TikTok.Business.SDK;

private void Awake()
{
    // Initialize with your iOS and Android credentials
    TikTokConfig config = new TikTokConfig(
        "YOUR_IOS_APP_SECRET", 
        "YOUR_IOS_APP_ID", 
        "YOUR_IOS_TIKTOK_APP_ID",
        "YOUR_ANDROID_APP_SECRET",
        "YOUR_ANDROID_APP_ID",
        "YOUR_ANDROID_TIKTOK_APP_ID"
    );

    // For multiple TikTok App IDs:
    // TikTokConfig config = new TikTokConfig(
    //     "YOUR_IOS_APP_SECRET", 
    //     "YOUR_IOS_APP_ID", 
    //     "IOS_TIKTOK_APP_ID_1,IOS_TIKTOK_APP_ID_2",
    //     "YOUR_ANDROID_APP_SECRET",
    //     "YOUR_ANDROID_APP_ID",
    //     "ANDROID_TIKTOK_APP_ID_1,ANDROID_TIKTOK_APP_ID_2"
    // );

    // Continue to initialisation...
    TikTokBusinessSDK.InitializeSdk(
        config,
        (success, code, message) =>
        {
            if (success)
            {
                Debug.Log("TikTok App Events SDK initialized successfully");
            }
            else
            {
                Debug.LogError($"TikTok App Events SDK initialisation failed: code={code}, message={message}");
            }
        }
    );
}
(/code)

延迟事件传输

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

平台设置说明

Android：权限、Proguard 和 Gradle 选项

• 权限：在 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)

• Gradle 选项：确保你的应用层级 build.gradle 或 mainTemplate.gradle 支持 Java 8。

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

iOS：应用跟踪透明度 (ATT) 和 SKAdNetwork

应用跟踪透明度 （ATT）：对于 iOS 14.5 及以上版本，必须请求用户同意才能访问设备的广告标识符 (IDFA)。将 NSUserTrackingUsageDescription 键添加到 Info.plist，并附上信息，说明请求监测权限的原因。

SKAdNetwork （SKAN）： - SDK 支持 SKAN 框架，用于隐私保护归因。如果你在应用中使用其他 SDK（例如 MMP）来管理 SKAN 更新，必须禁用应用事件 SDK 的 SKAdNetwork 支持，以免发生冲突。

(code curl http)
// In your TikTokConfig initialisation
config.IOS_DisableSKAdNetworkSupport();
(/code)

• 为准确报告从 Apple 接收的转化值，必须提供架构映射。如需了解如何配置这一映射，参见 SKAdNetwork 报告和架构映射。

应用事件报告

自动记录的事件

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

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

你可以选择禁用自动事件记录。禁用自动事件记录后，将不再默认监测应用安装和应用启动等事件。

如果你需要这些事件用于度量或分析，必须在应用代码中部署手动记录，以捕获并发送这些事件。

(code curl http)
TikTokConfig config = new TikTokConfig(/*...*/);

// Option 1: Disable ALL automatic events
config.DisableAutoTrack();

// Option 2: Disable specific automatic events
config.DisableInstallTrack();
config.DisableLaunchTrack();
config.DisableRetentionTrack();
config.DisablePayTrack();

TikTokBusinessSDK.InitializeSdk(config);
(/code)

手动记录的事件

标准事件

对于没有属性的简单事件，使用 TTEventName 枚举值中的事件常量创建 TikTokBaseEvent。如需查看 TTEventName 枚举值的完整列表，参见标准事件常量和事件类。

示例：Registration 事件

(code curl http)
// Example: A user completes a registration
TikTokBaseEvent registrationEvent = new TikTokBaseEvent(TTEventName.TTEventNameRegistration);
TikTokBusinessSDK.TrackTTEvent(registrationEvent);
(/code)

为标准事件添加属性

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

|标准事件{30%}|Builder 类{70%}|
|---|---|
|加入购物车|`TikTokAddToCartEvent`|
|加入心愿单|`TikTokAddToWishlistEvent`|
|结账|`TikTokCheckoutEvent`|
|付费|`TikTokPurchaseEvent`|
|查看内容|`TikTokViewContentEvent`|

示例：ViewContent 事件 Builder 类

(code curl http)
// Example: A user adds an item to the cart
TikTokAddToCartEvent cartEvent = new TikTokAddToCartEvent();
cartEvent.SetDescription("Description of the product");
cartEvent.SetCurrency(TTCurrency.TTCurrencyUSD);
cartEvent.SetValue("4.99");
cartEvent.SetContentType("product_group");
cartEvent.SetContentId("ABC-123");

TikTokContentParams eventContent = new TikTokContentParams();
eventContent.price = 4.99;
eventContent.quantity = 1;
eventContent.brand = "AwesomeBrand";
eventContent.contentName = "The Best Product";
TikTokContentParams[] contents = { eventContent };

cartEvent.SetContents(contents);
TikTokBusinessSDK.TrackTTEvent(cartEvent);
(/code)

示例：CompleteTutorial 事件

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

(code curl http)
// Example: A user completes the onboarding tutorial
TikTokBaseEvent tutorialEvent = new TikTokBaseEvent(TTEventName.TTEventNameCompleteTutorial);

// Standard properties (replace with actual values)
tutorialEvent.AddProperty("currency", TTCurrency.TTCurrencyUSD); // ISO 4217 currency code
tutorialEvent.AddProperty("value", 9.99);                        // Order or items value
tutorialEvent.AddProperty("content_id", "CONTENT_ID");           // Unique product/content ID
tutorialEvent.AddProperty("content_type", "CONTENT_TYPE");       // Type of content in the event
tutorialEvent.AddProperty("price", 9.99);                        // Item price
tutorialEvent.AddProperty("quantity", 1);                        // Number of items

TikTokBusinessSDK.TrackTTEvent(tutorialEvent);
(/code)

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

应用内广告收入

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

自定义事件

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

(code curl http)
// Example: A user shares content
TikTokBaseEvent baseEvent = new TikTokBaseEvent("ShareContent");
TikTokBusinessSDK.TrackTTEvent(baseEvent);
(/code)

启用高级匹配

To improve audience matching, use Identify() to set advanced matching properties when user information becomes available (e.g., after login or sign-up), and Logout() to clear it.

(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 或以上版本。 - （仅限 iOS）你已同时为你的应用和 TikTok 应用授予应用跟踪透明度 (ATT) 权限。

|步骤{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>|

手动调试模式

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

启用调试模式

在初始化时将 OpenDebugMode() 添加到你的TikTokConfig中。你也可以使用 SetLogLevel() 获取更详细的输出。

(code curl http)
TikTokConfig config = new TikTokConfig(/*...*/);
config.OpenDebugMode();
config.SetLogLevel(TiktokLogLevel.VERBOSE); // Optional

TikTokBusinessSDK.InitializeSdk(config);
(/code)

可用的日志级别包括 NONE、INFO、WARN、DEBUG和 VERBOSE。

禁用调试模式

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

(code curl http)
// REMOVEME
// config.OpenDebugMode();
// config.SetLogLevel(TiktokLogLevel.VERBOSE);
(/code)

生成和验证事件

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

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

其他功能和指南

• 高级预测式度量
• 深度链接和延迟深度链接
• 强化数据回传
• 应用内广告收入报告
• SKAdNetwork 报告和架构映射
• 合规最佳实践