iOS SDK

Tenjin 的原生 iOS SDK

Tenjin iOS SDK 允许客户在他们的 iOS 应用程序中跟踪事件和安装。 要了解有关 Tenjin 和我们的产品的更多信息，请访问 https://www.tenjin.com.

• 请参照我们的 Release Notes 来查看历史版本.
• 关于 Unity 的说明请查看 https://github.com/tenjin/tenjin-unity-sdk.
• 如有任何问题或者需要帮助，请联系 support@tenjin.com

注释:

• 如果使用 iOS SDK v1.12.17 及更高版本，则需要 Xcode 13。
• 对于 App 跟踪透明度, 请确保更新您的项目文件.plist并添加Privacy - Tracking Usage Description (NSUserTrackingUsageDescription) 以及要向用户显示的文本信息，该库仅适用于 iOS 14.0 以上版本。
• 对于 Apple Search Ads Attribution（苹果搜索广告归因） 支持, 请务必升级至 v1.12.6+ 并添加 AdServices.framework库，该库仅适用于 iOS 14.3 以上版本。

目录

• SDK 集成
  • 使用 ATTrackingManager 初始化 Tenjin
    •  展示 ATT 授权提示
      • 设置用户追踪描述
  • SKAdNetwork 与 Conversion value 转化值
    • SKAdNetwork 与 iOS 15+ 广告主回调
  • Tenjin 与 GDPR
  • • Opt in/Opt out CMP
  • 设备层级数据
• 购买事件
  • 订阅服务
• 自定义事件
• S2S 服务端集成
• 应用子版本及 A/B 测试
• 广告展示层级收益集成
• LiveOps 动态运营
• 用户ID
• 分析安装ID
• Retry/cache events and IAP重试逻辑
• Google DMA 参数

SDK 集成

Cocoapods

如果你使用 pods 添加 pod 'TenjinSDK' 到你的 Podfile ，然后运行 pod install 并跳过以下第 5 步。

Swift Package Manager

如果您使用 SPM，请通过 Xcode 将 Tenjin 的SDK包添加到此库中，并跳过以下第 5 步。

1. 在此处下载最新版本的 SDK。

2. 拖动 TenjinSDK.xcframework 和 TenjinSDK.h 到 project。
   注意： 如果你是测试32位的 iOS 模拟设备（i386），你需要使用 libTenjinSDKUniversal.a 而不是 libTenjinSDK.a。

3. 添加以下 Frameworks 到你的 project:

• AdServices.framework
• AdSupport.framework
• AppTrackingTransparency.framework
• iAd.framework
• StoreKit.framework
  

4. 在 Build 设置中包含 linker flags -ObjC
   

5. 转到 AppDelegate 文件, 默认为 AppDelegate.m, 和 #import "TenjinSDK.h"。

6. 您可以在应用 App 页面获取 SDK_KEY 。请注意：每个应用的 SDK_KEY 都是唯一的，您可以为每个应用生成最多3个 SDK_KEY 。

   

7. a. 在 didFinishLaunchingWithOptions method 添加:

[TenjinSDK init:@"<SDK_KEY>"];
[TenjinSDK connect];

这是一个 AppDelegate.m 文件在集成中的样例:

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [TenjinSDK init:@"<SDK_KEY>"];
    [TenjinSDK connect];

    //All your other stuff
    ...
}

注意：如果你使用的是 Swift 5, 请使用 getInstance() 方法，而不是 init()。查看我们的 Swift app 样例

7.b. 另一种初始化来处理其他服务中的深度链接（请勿同时使用 7a 和 7b，二选一即可）。
如果你使用其他服务产生延迟的深度链接，你可以向 Tenjin 发送这个链接，来处理已经已经打开 Tenjin 归因的深度链接。

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  
    [TenjinSDK init:@"<SDK_KEY>"];

    //get your deep link from your other 3rd party service
    NSURL *url = [NSURL withString: @"your_deep_link"];
    
    //if you have a deep link that's generated from a third party service then pass it to tenjin to handle the attribution of deep links holistically
    if(url) {
      [TenjinSDK connectWithDeferredDeeplink:url];
    }
    else{
      [TenjinSDK connect];
    }

    //All your other stuff
    //...
}

你可以通过我们的 Live Test Device Data Tool 来测试 SDK 集成是否正常。添加 advertising_id 或者 IDFA/GAID 到测试设备列表。你在 Support -> Test Devices， 转到SDK Live page 从你的设备发送事件。你应该可以看到实时的事件如下

使用 ATTrackingManager 初始化 Tenjin

从 iOS 14 开始，你可以选择初始话并显示 ATTrackingManager 权限提示，让用户选择允许或不允许。如果用户选择不允许追踪，IDFA 的值将会是0，如果用户选择同意追踪， connect() 方法就会发送 IDFA 到我们的服务器。即便不使用 ATTrackingManager，你也可以调用 Tenjin connect(), 目前 ATTrackingManager 弹窗尚未强制弹出，预计苹果会在2021年初强制推行。

#import "TenjinSDK.h"

@implementation TJNAppDelegate

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

    [TenjinSDK init:@"<SDK_KEY>"];

    if (@available(iOS 14, *)) {
        [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
            [TenjinSDK connect];
        }];
    } else {
        [TenjinSDK connect];
    }
}

展示 ATT 授权提示

要遵守 Apple 的 ATT 指南，您必须提供 ATT 权限提示的描述，然后在您的应用程序中实施权限请求。

注意：在您的游戏中投放广告之前，您必须执行权限请求。

设定用户跟踪描述

Apple 需要开发者描述 ATT 提示的用途。您需要在 Xcode 项目的 Info.plist 文件中使用 NSUserTrackingUsageDescription 设置描述。您必须提供一条消息，告知用户您为何请求使用设备跟踪数据的权限：

• 在您的 Xcode 项目导航器中，打开 Info.plist 文件。
• 单击属性列表编辑器中任意键旁边的添加按钮 (+) 以创建新的属性键。
• 输入键名NSUserTrackingUsageDescription。
• 选择字符串 String 值类型。
• 在值字段中输入应用跟踪透明度消息。一些例子包括：
• “我们将使用您的数据来提供更好的个性化广告体验。”
• “我们会尝试根据您使用的应用程序、您使用的设备以及您所在的国家/地区展示您最感兴趣的应用程序和产品的广告。”
• “我们会尝试根据您使用的应用为您最感兴趣的应用和产品展示广告。”

注意：Apple 提供了特定的应用商店指南，为所有面向最终用户的隐私相关功能定义了可接受的使用和消息传递。Tenjin 不提供法律意见。因此，此页面上的信息不能替代您寻求自己的法律顾问来确定您的业务和流程的法律要求以及如何解决这些要求。

SKAdNetwork 与 Conversion value 转化值

作为 SKAdNetwork 的一部分，我们为 updatePostbackConversionValue(_:) 创建的封装方案，可以注册等效的 SKAdNetwork 方案并同时发送 conversion values 到我们的服务器。

updatePostbackConversionValue(_:) 6位值来对应应用内事件，不能二进制形式输入，而应为 0-63 的整数。我们的服务器将拒绝任何无效值。

• 内购为主的游戏样例
• 广告变现为主的游戏样例

对于支持 SKAdNetwork 4.0 的 iOS 16.1 之后的版本，现可通过发送 coarseValue （String 字符串格式，可能的变体为 "low"，"medium" 或者 "high"）以及 lockWindow（Boolean 布尔值）作为更新版回传方法的参数

updatePostbackConversionValue(_ conversionValue: Integer, coarseValue: String)

updatePostbackConversionValue(_ conversionValue: Integer, coarseValue: String, lockWindow: Bool)

• 对于 iOS 版本为 16.1+，即支持 SKAdNetwork 4.0，您可以根据需要多次调用此方法，并可以使转换值低于或高于上一个值。

• 对于 iOS 版本低于 16.1，即所支持的 SKAdnetWork 版本低于 4.0，您仍可以调用此方法，我们的 SDK 将自动检测 iOS 版本并仅更新 conversionValue 转换值。

#import "TenjinSDK.h"

@implementation TJNAppDelegate

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

    [TenjinSDK init:@"<SDK_KEY>"];
    [TenjinSDK connect];

    //
    // This will call [SKAdNetwork updatePostbackConversionValue: <Integer between 0 and 63>]
    // and also send conversion value to our servers.
    //
    // You will need to use a value between 0-63.
    //
    [TenjinSDK updatePostbackConversionValue: <Integer between 0 and 63>];
   
   // For iOS 16.1+ (SKAN 4.0)

    [TenjinSDK updatePostbackConversionValue: <Integer between 0 and 63> coarseValue:@"medium"];

    [TenjinSDK updatePostbackConversionValue: <Integer between 0 and 63> coarseValue:@"medium" lockWindow:true];
}

SKAdNetwork 和 iOS 15+ 广告主回调

需要将 Tenjin 指定为 SKAdNetwork 回调接收方，请进行以下操作：

1. 在 Xcode 的项目导航器中选择 Info.plist。
2. 单击"属性/Property"列表编辑器中某个键旁边的添加按钮 (+)，然后按回车键。
3. 输入名称 NSAdvertisingAttributionReportEndpoint。
4. 从"类型/Type"列的弹出菜单中选择"String"。
5. 输入 https://tenjin-skan.com。

以上操作是为适配 Apple 的指引，具体详情可参考网址：
[https://developer.apple.com/documentation/storekit/skadnetwork/configuring_an_advertised_app]

Tenjin 与 GDPR

作为 GDPR 合规的一部分，使用 Tenjin 的 SDK，你可以选择加入和退出设备/用户，或选择要加入或退出的特定于设备的相关参数。OptOut() 不会向 Tenjin 发送任何 API 请求，我们也不会处理任何事件。

如何 opt-in/opt-out:

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  
  [TenjinSDK init:@"<SDK_KEY>"];

  if ([self checkOptInValue]) {
      [TenjinSDK optIn];
  }
  else {
      [TenjinSDK optOut];
  }

  [TenjinSDK connect];

  //All your other stuff
  //..
}

-(BOOL) checkOptInValue
{
  // check opt-in value
  // return YES; // if user opted-in
  return NO;
}

要选择加入/退出特定的设备相关参数，可以使用 OptInParams() 或 OptOutParams()。 OptInParams() 将仅发送指定的设备相关参数. OptOutParams() 将发送除指定参数外的所有与设备相关的参数。 请注意，我们需要至少 ip_address, advertising_id, developer_device_id, limit_ad_tracking, referrer (Android), 和 iad (iOS) 来正确地跟踪在 Tenjin 系统中的设备。如果你打算使用 Google，则还需要添加: platform, os_version, locale, device_model, app_verision 和 build_id.

如果只想使用 OptInParams()获取与设备相关的特定参数，在下面的样例中, 我们只发送这些设备相关的参数: ip_address, advertising_id, developer_device_id, limit_ad_tracking, referrer, 和 iad:

[TenjinSDK init:@"<SDK_KEY>"];

NSArray *optInParams = @[@"ip_address", @"advertising_id", @"developer_device_id", @"limit_ad_tracking", @"referrer", @"iad"];
[TenjinSDK optInParams:optInParams];

[TenjinSDK connect];

如果要使用 OptOutParams()发送除特定设备相关参数以外的所有参数，如下样例中，我们会发送除了 locale, timezone, 和 build_id 之外的所有相关的参数。

[TenjinSDK init:@"<SDK_KEY>"];

NSArray *optOutParams = @[@"country", @"timezone", @"language"];
[TenjinSDK optOutParams:optOutParams];

[TenjinSDK connect];

Opt in/out CMP

您可以使用CMP （目的 1）的条款，实现自动选择opt in/out功能，并返回布尔值(boolean）。该功能基于用户设备中已存储的信息，无需额外交互。

OptInOutUsingCMP()

BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");
optInOut = instance.OptInOutUsingCMP(); 

设备层级数据

购买事件

Pass (SKPaymentTransaction *) transaction 和 (NSData *)receipt object:
在一个购买被验证之后，并且 SKPaymentTransactionStatePurchased 你可传递交易到 Tenjin:

//Get the NSData receipt
NSURL *receiptURL = [[NSBundle mainBundle] appStoreReceiptURL];
NSData *receiptData = [NSData dataWithContentsOfURL:receiptURL];

//Pass the transaction and the receiptData to Tenjin
[TenjinSDK transaction: transaction andReceipt: receiptData];

订阅服务

重要提示： 如果你有内购订阅，你需要添加 App 的 share secret 到 Tenjin 的控制面板。你可以在通过以下途径获取 iOS 的共享密钥 iTunes Connect Console >iTunes Connect Console > Select your app > App Information > App-Specific Shared Secret.

请注意，你需要在每个订阅期间内发送相应的订阅交易（例如，如果是按月订阅，你需要每月向我们发送1笔交易）。

在下面的示例时间轴中，交易事件仅应在“首次收费 First Charge”和“续订 Renewal”事件中发送。在试用期间，请勿将交易事件发送给 Tenjin。Tenjin 不会对重复交易进行数据删除。

有关订阅的更多信息，请参阅： Apple documentation on Working with Subscriptions

自定义事件

重要提示：请不要在 CONNECT/INITIALIZATION 事件之前发送自定义事件. 必须先进行初始化，然后再发送自定义事件。

使用 Tenjin SDK 传递自定义事件：

• sendEventWithName: (NSString *)eventName and

你可以使用自定义事件来向 Tenjin 传递不同获客渠道的用户成本，样例如下：

//send a particular event for when someone swipes on a part of your app
[TenjinSDK sendEventWithName:@"swipe_right"];

自定义事件也可以传递 NSString eventValue。 Tenjin 将 eventValue 作为同一个eventName的总和。 eventValue 必须为整数，如果不是整数，Tenjin 将不发送事件。

S2S 服务端集成

Tenjin 提供服务端的集成功能，如果有需要，请发送邮件至 support@tenjin.com 。

应用子版本及 A/B 测试（需要DataVault）

如果你想运行 A/B 测试和差异报告，我们可以使用 appendAppSubversion 方法将数字值附加到你的应用程序版本中。例如，如果你的应用程序版本 1.0.1 设置了 appendAppSubversion: @8888，报告中将为1.0.1.8888。

这些数据将在 DataVault 中，你可以通过 subversion 值来运行报告。

[TenjinSDK init:@"<SDK_KEY>"];
[TenjinSDK appendAppSubversion:@8888];
[TenjinSDK connect];

广告展示层级收益集成

Tenjin 目前支持与以下聚合平台展示数据进行集成：,

• AppLovin
• Unity LevelPlay
• HyperBid
• AdMob
• TopOn
• CAS
• TradPlus

此功能将允许您获取每一个广告展示的明细数据，该功能可用于广告投放渠道基于广告收益的优化策略，以及更精确的用户层级收益计算等。如有需要，请联系您的客户经理。

LiveOps 动态运营

Tenjin 支持在 SDK 层面获取用户的来源信息，包括买量渠道及广告计划等。如有需要，请联系您的客户经理。

这将允许广告主实时收集和分析这些用户级归因数据。以下是使用 Tenjin LiveOps 动态运营的实用案例：

• 如果您有自己的数据分析工具，自定义回调将允许您将归因数据与设备级别的游戏内数据联系起来，也就是将推广数据与应用内事件数据相联系。
• 根据用户的来源显示不同的应用程序内容。例如，用户 A 是自然量用户，而用户 B 是 Facebook 买量用户。由于用户 B 可能更喜欢您的应用程序，因此您可能希望为用户 B 显示游戏内的特别优惠，这时就可以使用归因信息回调。如果您想讨论更多具体的用例，请联系 Tenjin 成功经理。

用户 ID

发送事件时可以设置自定义的用户 ID。

setCustomerUserId(userId: "user_id")
getCustomerUserId()

[TenjinSDK initialize:@"<SDK_KEY>"];
[TenjinSDK setCustomerUserId:@"user_id"];
userId = [TenjinSDK getCustomerUserId]; 

分析ID Analytics Installation ID

您可以在设备的本地储备中获取分析ID(Analytics Installation ID)，该ID是随机生成的。
GetAnalyticsInstallationId()

BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");
analyticsId = instance.GetAnalyticsInstallationId; 

Retry/cache events and IAP重试逻辑

当请求失败或用户没有网络连接时，您可以启用/禁用重试和缓存事件以及内购。 这些事件将在新事件添加到队列并且用户恢复连接后发送。

setCacheEventSetting(true)

[TenjinSDK setCacheEventSetting:true];

Google DMA 参数

若您已集成CMP的模式，Google DMA参数将由Tenjin SDK自动采集，且无需额外操作。 若您希望取代CMP，或者构建自己的用户协议机制，您可以使用以下方法：

setGoogleDMAParametersWithAdPersonalization(bool, bool)

[TeninSDK sharedInstance] setGoogleDMAParametersWithAdPersonalization:adPersonalization adUserData:adUserData]; 

您可以选择加入或退出谷歌 DMA 参数的收集，从而管理谷歌DMA参数的收集。默认情况下会加入，但您可以使用 optInGoogleDMA 或 optOutGoogleDMA 方法轻松更改您的偏好，从而完全控制您的数据隐私设置。

[TeninSDK optInGoogleDMA]; 
[TeninSDK optOutGoogleDMA];