← 返回目录
📁 Marketing API › Ad Measurement › Guides › TikTok App Events SDK › Getting started

iOS 集成步骤

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

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

前提条件

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

将 SDK 添加为构建依赖项

CocoaPods 集成

  1. 在 Podfile 中，添加 TikTokBusinessSDK 组件：
(code curl http)
# Podfile
pod 'TikTokBusinessSDK'
(/code)
  1. 在项目目录中运行以下命令来安装该组件：
(code curl http)
pod install
(/code)

Swift 包管理工具集成

1.3.8 及以上版本支持 Swift 包管理工具。

  1. 在 Xcode 中，前往 File → Add Package Dependencies

Asset

  1. 在搜索字段中输入 TikTokBusinessSDK GitHub 仓库 URL：https://github.com/tiktok/tiktok-business-ios-sdk

Asset

  1. 选择所需的 SDK 版本，并将其添加到要使用的目标中

  2. 选择 Add Package，将 SDK 添加到你的项目中。

Asset

手动集成 (xcframework)

  1. 从 GitHub 发布页面下载最新的 TikTokBusinessSDK.xcframework.zip。
  2. 解压下载的文件。
  3. 在 Xcode 中，前往项目设置页面，选择你的应用目标，然后进入 General 选项卡。
  4. 将 TikTokBusinessSDK.xcframework 拖放到 Frameworks, Libraries, and Embedded Content 版块。

配置构建设置

在 Xcode 中，前往应用目标的 Build Settings，找到 Other Linker Flags 并添加 -ObjC 和 -lc++。

配置应用跟踪透明度 (ATT)

对于 iOS 14.5 及以上版本，必须请求用户同意才能访问设备的广告标识符 (IDFA)。

  1. 在 Info.plist 文件中，添加 NSUserTrackingUsageDescription 键，并附上信息，说明请求监测权限的原因。
(code curl http)
<!-- Info.plist -->
<key>NSUserTrackingUsageDescription</key>
<string>YOUR_CUSTOM_DESCRIPTION</string>
(/code)
  1. 在应用生命周期的适当阶段请求用户授权。
(code curl http)
// Swift
func requestIDFA() {
  if #available(iOS 14, *) {
    TikTokBusiness.requestTrackingAuthorization { status in
      // Handle authorization status
    }
  }
}
(/code)

(code curl http)
// Objective-C
- (void)requestIDFA {
  if (@available(iOS 14, *)) {
    [TikTokBusiness requestTrackingAuthorizationWithCompletionHandler:^(NSUInteger status) {
      // Handle authorization status
    }];
  }
}
(/code)

配置并初始化 SDK

在你的 AppDelegate中，在 application(_:didFinishLaunchingWithOptions:) 方法内配置并初始化 SDK。

使用你的应用密钥、应用 ID 以及从事件管理工具获取的 TikTok 应用 ID 创建 TikTokConfig 对象。 然后，调用TikTokBusiness.initializeSdk启动 SDK。 建议使用完成处理程序来管理成功或失败的情况。

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

(code curl http)
// Swift
// AppDelegate.swift

import TikTokBusinessSDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        guard let config = TikTokConfig(accessToken: "YOUR_APP_SECRET", appId: "YOUR_APP_ID", tiktokAppId: "YOUR_TIKTOK_APP_ID") else {
            return true
        }

        // For multiple TikTok App IDs:
        // guard let config = TikTokConfig(accessToken: "YOUR_APP_SECRET", appId: "YOUR_APP_ID", tiktokAppId: "TIKTOK_APP_ID1,TIKTOK_APP_ID2,TIKTOK_APP_ID3") else {
        //     return true
        // }

        // Continue to initialisation...
        TikTokBusiness.initializeSdk(config) { (success, error) in
            if success {
                print("TikTok App Events SDK initialized successfully")
            } else {
                print("TikTok App Events SDK initialisation failed: \(error?.localizedDescription ?? "Unknown error")")
            }
        }

        return true
    }
}
(/code)

(code curl http)
// Objective-C
// AppDelegate.m

#import <TikTokBusinessSDK/TikTokBusinessSDK.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    TikTokConfig *config = [TikTokConfig configWithAccessToken:@"YOUR_APP_SECRET" appId:@"YOUR_APP_ID" tiktokAppId:@"YOUR_TIKTOK_APP_ID"];

    // For multiple TikTok App IDs:
    // TikTokConfig *config = [TikTokConfig configWithAccessToken:@"YOUR_APP_SECRET" appId:@"YOUR_APP_ID" tiktokAppId:@"TIKTOK_APP_ID1,TIKTOK_APP_ID2,TIKTOK_APP_ID3"];

    // Continue to initialisation...
    [TikTokBusiness initializeSdk:config completionHandler:^(BOOL success, NSError * _Nullable error) {
        if (success) {
            NSLog(@"TikTok App Events SDK initialized successfully");
        } else {
            NSLog(@"TikTok App Events SDK initialisation failed: %@", error.localizedDescription);
        }
    }];
}
(/code)

在应用中配置 SKAdNetwork 更新

SDK 支持 Apple 的 SKAdNetwork (SKAN) 框架，用于隐私保护归因。监测到的事件会映射到你已配置的 SKAN 架构，并调用相关的 Apple API 来更新转化值。为准确报告从 Apple 接收的转化值，必须提供架构映射。如需了解如何配置这一映射，参见 SKAdNetwork 报告和架构映射。

确保你的应用中只有一个 SDK 负责更新 SKAN 转化值。 如果你使用其他 SDK（例如 MMP）来管理 SKAN，必须禁用 TikTok SDK 的 SKAdNetwork 支持，以免发生冲突。

若想禁用，需在初始化 SDK 之前，对 TikTokConfig对象调用 disableSKAdNetworkSupport()。

(code curl http)
// Swift
guard let config = TikTokConfig(accessToken: "YOUR_APP_SECRET", appId: "YOUR_APP_ID", tiktokAppId: "YOUR_TIKTOK_APP_ID") else {
    return true
}
// Add this line to disable SKAN updates
config.disableSKAdNetworkSupport()
TikTokBusiness.initializeSdk(config)
(/code)

(code curl http)
// Objective-C
TikTokConfig *config = [TikTokConfig configWithAccessToken:@"YOUR_APP_SECRET" appId:@"YOUR_APP_ID" tiktokAppId:@"YOUR_TIKTOK_APP_ID"];
// Add this line to disable SKAN updates
[config disableSKAdNetworkSupport];
[TikTokBusiness initializeSdk:config];
(/code)

延迟事件传输

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

应用事件报告

自动记录的事件

标准事件

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

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

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

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

(code curl http)
// Swift
guard let config = TikTokConfig(accessToken: "YOUR_APP_SECRET", appId: "YOUR_APP_ID", tiktokAppId: "YOUR_TIKTOK_APP_ID") else {
    return true
}

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

// Option 2: Disable specific automatic events
config.disableInstallTracking()
config.disableLaunchTracking()
config.disableRetentionTracking()
config.disablePaymentTracking()

TikTokBusiness.initializeSdk(config)
(/code)

(code curl http)
// Objective-C
TikTokConfig *config = [TikTokConfig configWithAccessToken:@"YOUR_APP_SECRET" appId:@"YOUR_APP_ID" tiktokAppId:@"YOUR_TIKTOK_APP_ID"];

// Option 1: Disable ALL automatic events
[config disableAutomaticTracking];

// Option 2: Disable specific automatic events
[config disableInstallTracking];
[config disableLaunchTracking];
[config disableRetentionTracking];
[config disablePaymentTracking];

[TikTokBusiness initializeSdk:config];
(/code)

关于 StoreKit 交易报告

通过 Apple StoreKit API 处理的应用内购买会被 SDK 自动记录并报告为 Purchase 事件。下表列出了自动报告的商品类别：

|应用内商品类别 {60%}|StoreKit 1 {20%}|StoreKit 2 {20%}|
|---|---|---|
|消耗品：可购买、消耗并按需再次购买的商品。例如电商商品、游戏币等游戏商品。|✅|❌|
|非消耗品：用户只需购买一次即可永久使用的商品。例如：游戏关卡升级或一次性应用购买。|✅|✅|
|自动续费型订阅：可定期订阅、到期自动续费的商品。例如：交友应用订阅或流媒体服务订阅。|✅|✅|
|非续费型订阅：可在固定期限内订阅、期限内只需单次付费的商品。一年后再次订阅此商品需要另行付费。|✅|✅|

若想自动记录通过 StoreKit 2 购买的消耗品的事件，需将 SKIncludeConsumableInAppPurchaseHistory 键添加到应用的 Info.plist 文件中，并设置为 true。

(code curl http)
<!-- Info.plist -->
<key>SKIncludeConsumableInAppPurchaseHistory</key>
<true/>
(/code)

该 SDK 还会自动记录并分别报告不同交易状态：

|StoreKit 交易状态 {30%}|记录的事件 {30%}|StoreKit 1 {20%}|StoreKit 2 {20%}|
|---|---|---|---|
|付费中|付费中|✅|❌|
|已付费|Purchase|✅|✅|
|已恢复|PurchaseRestored|✅|✅|
|失败|PurchaseFailed|✅|❌|
|延迟|PurchaseDeferred|✅|❌|

StoreKit 2 不会自动监测失败的付费尝试。若想报告这些失败操作，需在 StoreKit 2 交易流程中调用 trackStoreKit2PurchaseFailed：

(code curl http)
// Swift
func purchaseProduct(_ productId: String) async throws {
    let products = try await Product.products(for: [productId])
    guard let product = products.first else {
        return
    }
    do {
        let result = try await product.purchase()
        switch result {
        case .success(let verifiedTransaction):
            // Handle successful purchase.
        case .pending:
            // Handle pending purchase.
        default:
            TikTokBusiness.getInstance().trackStoreKit2PurchaseFailed(productId: product.id)
        }
    } catch {
        TikTokBusiness.getInstance().trackStoreKit2PurchaseFailed(productId: product.id)
        throw error
    }
}
(/code)

手动记录的事件

标准事件

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

示例：Registration 事件

(code curl http)
// Swift
let registrationEvent = TikTokBaseEvent(eventName: TTEventName.registration.rawValue)
TikTokBusiness.trackTTEvent(registrationEvent)
(/code)

(code curl http)
// Objective-C
TikTokBaseEvent *registrationEvent = [TikTokBaseEvent eventWithName:TTEventNameRegistration];
[TikTokBusiness trackTTEvent:registrationEvent];
(/code)

为标准事件添加属性

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

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

示例：ViewContent 事件 Builder 类

(code curl http)
// Swift
// Example: A user views a product
let contentParams = TikTokContentParams()
contentParams.price = 99.99
contentParams.quantity = 1
contentParams.contentId = "12345"
contentParams.contentCategory = "Electronics"
contentParams.contentName = "Wireless Headphones"
contentParams.brand = "AudioBrand"

let viewContentEvent: TikTokContentsEvent = TikTokViewContentEvent()
viewContentEvent.setValue("99.99")
viewContentEvent.setCurrency(TTCurrency.USD)
viewContentEvent.setDescription("A fantastic product")
viewContentEvent.setContentType("product_group")
viewContentEvent.setContents([contentParams])

TikTokBusiness.trackTTEvent(viewContentEvent)
(/code)

(code curl http)
// Objective-C
// Example: A user views a product
TikTokContentParams *contentParams = [[TikTokContentParams alloc] init];
contentParams.price = @(99.99);
contentParams.quantity = 1;
contentParams.contentId = @"12345";
contentParams.contentCategory = @"Electronics";
contentParams.contentName = @"Wireless Headphones";
contentParams.brand = @"AudioBrand";

TikTokViewContentEvent *viewContentEvent = [[TikTokViewContentEvent alloc] init];
[viewContentEvent setValue:@"99.99"];
[viewContentEvent setCurrency:TTCurrencyUSD];
[viewContentEvent setDescription:@"A fantastic product"];
[viewContentEvent setContentType:@"product_group"];
[viewContentEvent setContents:@[contentParams]];

[TikTokBusiness trackTTEvent:viewContentEvent];
(/code)

示例：CompleteTutorial 事件

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

(code curl http)
// Swift
// Example: A user completes the onboarding tutorial
let tutorialEvent = TikTokBaseEvent(eventName: TTEventName.completeTutorial.rawValue)
tutorialEvent.addProperty(withKey: "currency", value: TTCurrency.USD) // ISO 4217 currency code
tutorialEvent.addProperty(withKey: "value", value: 9.99) // Order or items value
tutorialEvent.addProperty(withKey: "content_id", value: "CONTENT_ID") // Unique product/content ID
tutorialEvent.addProperty(withKey: "content_type", value: "CONTENT_TYPE") // Type of content
tutorialEvent.addProperty(withKey: "price", value: 9.99) // Item price
tutorialEvent.addProperty(withKey: "quantity", value: 1) // Number of items
TikTokBusiness.trackTTEvent(tutorialEvent)
(/code)

(code curl http)
// Objective‑C
// Example: A user completes the onboarding tutorial
TikTokBaseEvent *tutorialEvent = [TikTokBaseEvent eventWithName:TTEventNameCompleteTutorial];
[tutorialEvent addPropertyWithKey:@"currency" value:TTCurrencyUSD]; // ISO 4217 currency code
[tutorialEvent addPropertyWithKey:@"value" value:@(9.99)]; // Order or items value
[tutorialEvent addPropertyWithKey:@"content_id" value:@"CONTENT_ID"]; // Unique product/content ID
[tutorialEvent addPropertyWithKey:@"content_type" value:@"CONTENT_TYPE"]; // Type of content
[tutorialEvent addPropertyWithKey:@"price" value:@(9.99)]; // Item price
[tutorialEvent addPropertyWithKey:@"quantity" value:@(1)]; // Number of items
[TikTokBusiness trackTTEvent:tutorialEvent];
(/code)

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

应用内广告收入

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

自定义事件

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

(code curl http)
// Swift
// Example: A user shares content to a social platform
let customEvent = TikTokBaseEvent(eventName: "ShareContent")
TikTokBusiness.trackTTEvent(customEvent)
(/code)

(code curl http)
// Objective-C
// Example: A user shares content to a social platform
TikTokBaseEvent *customEvent = [TikTokBaseEvent eventWithName:@"ShareContent"];
[TikTokBusiness trackTTEvent:customEvent];
(/code)

启用高级匹配

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

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

// When user logs out
TikTokBusiness.logout()
(/code)

(code curl http)
// Objective-C
// When user logs in or signs up
[TikTokBusiness identifyWithExternalID:@"user-external-id-123"
                      externalUserName:@"user-name-456"
                           phoneNumber:@"+15551234567" // E.164 format
                                 email:@"user@example.com"];

// When user logs out
[TikTokBusiness logout];
(/code)

支持的属性

根据标准行业惯例，客户电子邮箱和电话号码信息在离开设备之前将使用 SHA256 算法进行散列处理。TikTok 在美国和英国通过了 ISO 27001 认证。如需详细了解我们如何使用此信息，参见 TikTok 商业产品（数据）条款。

属性 格式要求
externalId

来自广告主的唯一 ID，例如忠诚度会员 ID 或用户 ID。		 未经散列处理的纯文本。清除首尾空格。 "user-id-abc"
externalUserName

来自广告主的用户名。		 未经散列处理的纯文本。清除首尾空格。 "testuser"
email 未经散列处理的纯文本。清除首尾空格，将所有字符转换为小写。 "email@example.com"
phoneNumber 未经散列处理的纯文本。转换为规范的 E.164 格式（例如 +[country code][number]）。 "+15551234567"

验证集成

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

无代码测试事件（推荐）

此方法可用于在无需修改代码的情况下，调试特定设备的事件。在开始之前，请确保： - 你的测试设备上已安装最新版本的 TikTok 应用。 - 你的应用中已安装 SDK 1.5.0 或以上版本。 - 你已同时为你的应用和 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>|

手动调试模式

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

启用调试模式

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

(code curl http)
// Swift
guard let config = TikTokConfig(accessToken: "YOUR_APP_SECRET", appId: "YOUR_APP_ID", tiktokAppId: "YOUR_TIKTOK_APP_ID") else {
    return true
}
config.enableDebugMode()
config.setLogLevel(TikTokLogLevelVerbose) // Optional: for detailed logs

TikTokBusiness.initializeSdk(config)
(/code)

(code curl http)
// Objective-C
TikTokConfig *config = [TikTokConfig configWithAccessToken:@"YOUR_APP_SECRET" appId:@"YOUR_APP_ID" tiktokAppId:@"YOUR_TIKTOK_APP_ID"];
[config enableDebugMode];
[config setLogLevel:TikTokLogLevelVerbose]; // Optional: for detailed logs

[TikTokBusiness initializeSdk:config];
(/code)

可用的日志级别包括： - TikTokLogLevelNone - TikTokLogLevelInfo - TikTokLogLevelWarn - TikTokLogLevelDebug - TikTokLogLevelVerbose

禁用调试模式

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

(code curl http)
// Swift
// REMOVEME
// config.enableDebugMode()
// config.setLogLevel(TikTokLogLevelVerbose)
(/code)

(code curl http)
// Objective-C
// REMOVEME
// [config enableDebugMode];
// [config setLogLevel:TikTokLogLevelVerbose];
(/code)

生成和验证事件

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

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

Asset

其他功能和指南

← Unity 集成步骤Android 集成步骤 →

内容来源：TikTok API for Business 官方文档 · 本地归档

在接这个接口时卡住了？
Stuck wiring this API into production? We build ad-delivery tooling on these platforms — campaign automation, reporting pipelines, error-handling and migration between API versions.
联系我们 · Talk to us 每日平台更新简报 →