摘要

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

请参阅我们的版本历史记录。
有关Unity专门的说明，请访问https://github.com/tenjin/tenjin-unity-sdk。
有关任何问题或支持，请联系：[email protected]

备注

需要Xcode 13要求，如果您正在使用iOS SDK v1.12.17及以上版本。
对于AppTrackingTransparency，请确保更新项目的.plist文件，并添加隐私 - 跟踪用途描述 (NSUserTrackingUsageDescription) 及您想要显示给用户的文本信息。此库仅在iOS 14.0以上可用。
对于Apple Search Ads Attribution支持，请确保升级到v1.12.6+并添加AdServices.framework库。此库仅在iOS 14.3以上可用。

SDK整合

如果您使用pods，请在Podfile中添加pod 'TenjinSDK'，然后运行pod install并跳到步骤5。

在此处下载最新的SDK版本：https://github.com/tenjin/tenjin-ios-sdk/releases。
将TenjinSDK.xcframework和TenjinSDK.h拖动到您的项目中的“构建阶段”-》"将二进制与库链接"。
将以下框架添加到您的项目中
1. AdServices.framework
2. AdSupport.framework
3. AppTrackingTransparency.framework
4. iAd.framework
5. StoreKit.framework
在您的构建设置中包含以下链接器标志-ObjC，详情请点击

Objective-C项目步骤

进入您的AppDelegate文件，通常是AppDelegate.m，并添加#import "TenjinSDK.h"。
从你的应用页面获取SDK_KEY。注意：SDK_KEY对每个应用是唯一的。你可以为同一应用创建最多3个密钥。
在你didFinishLaunchingWithOptions方法中加入以下内容：
```
[TenjinSDK initialize:@"<SDK_KEY>"];
[TenjinSDK connect];
```

为了启用Tenjin iOS SDK调试日志，请添加以下内容：

  [TenjinSDK debugLogs];

以下是一个在你的Objective-C项目中集成时的示例，应在你的AppDelegate.m文件中

#import "TenjinSDK.h"

@implementation TJNAppDelegate

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

    //All your other stuff
    ...
}

Swift项目的步骤

为Swift项目添加Objective-C桥接头文件：
1. 创建一个头文件：
  1. 文件 -> 新建 -> 文件 -> “源”
  2. 选择“头文件” - > 点击“下一步”
  3. 头文件名应为“YourProjectName-Bridging-Header” -> 在“目标” -> 选择应用目标 -> 点击“下一步”
2. 在头文件中 - “YourProjectName-Bridging-Header.h”
  1. 添加 - `#import "TenjinSDK.h"`
3. 转到应用目标，在“构建设置”下
  1. 转到“Swift编译器 - 常规”部分
  2. 转到“Objective-C桥接头”子部分，并将头文件“YourProjectName-Bridging-Header.h”拖到字段中。
从你的Tenjin组织标签中获取SDK_KEY。
在你didFinishLaunchingWithOptions方法中加入以下内容：
```
TenjinSDK.getInstance("<SDK_KEY>")
TenjinSDK.connect()
```
如果你使用Swift 5，请使用getInstance()方法而不是init()。查看我们的示例Swift应用。

为了启用Tenjin iOS SDK调试日志，请添加以下内容：

  TenjinSDK.debugLogs();

以下是在你的Swift项目中集成时的示例，应在你的AppDelegate.swift文件中

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Override point for customization after application launch.
    TenjinSDK.getInstance("<SDK_KEY>")
    TenjinSDK.connect() 
    return true
}

注意：请确保在每次didFinishLaunchingWithOptions中实现此代码，而不仅仅是应用首次打开时。如果我们发现你没有遵循我们的建议，我们可能无法为您提供适当的支持，或者您的账户可能会被暂停。

在第7步中，您还可以尝试使用备用初始化方法来处理来自其他服务的深度链接。如果您使用其他服务生成延迟深度链接，可以将这些深度链接传递给Tenjin，以便与您启用的深度链接一起处理归因逻辑。

#import "TenjinSDK.h"

@implementation TJNAppDelegate

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

    [TenjinSDK initialize:@"<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
    //...
}

您可以通过我们的实时测试设备数据工具验证集成是否正常工作。将您的advertising_id或IDFA/GAID添加到测试设备列表中。您可以在“支持” -> 测试设备下找到此内容。转到SDK实时页面并从您的应用发送测试事件。您应该会看到实时事件进入

使用ATTrackingManager初始化Tenjin

从iOS 14开始，您可以选择显示初始的ATTrackingManager权限提示和选择，以让用户选择允许或拒绝跟踪。如果设备不接受跟踪权限，IDFA将变为零。如果设备接受跟踪权限，则connect()方法将发送IDFA到我们的服务器。在没有使用ATTrackingManager的情况下，您仍然可以在iOS 14以下版本调用Tenjin的connect()方法。ATTrackingManager权限提示从2021年春季末开始是强制性的。

#import "TenjinSDK.h"

@implementation TJNAppDelegate

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

    [TenjinSDK initialize:@"<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。
选择字符串值类型。
在值字段中输入应用跟踪透明度消息。以下是一些示例
- "我们将使用您的数据提供更好的个性化广告体验。"
- "我们将根据您使用的应用程序、您所在的设备和您所在的国家/地区显示您可能感兴趣的应用和产品广告。"
- "我们将根据您使用的应用程序显示您可能感兴趣的应用和产品广告。"

注意：苹果提供了具体的应用商店指南，其中定义了所有面向最终用户的隐私相关功能的可接受使用方式和信息。Tenjin不提供法律建议。因此，本页面的信息不能代替您自行寻求法律咨询，以确定您的业务和流程的法定要求和如何处理这些问题。

SKAdNetwork和转化价值

作为<=$((https://developer.apple.com/documentation/storekit/skadnetwork))>SKAdNetwork的一部分，我们为<=$((https://developer.apple.com/documentation/storekit/skadnetwork/3919928-updatepostbackconversionvalue))>updatePostbackConversionValue(_:)创建了一个包装方法。我们的方法将注册等效的SKAdNetwork方法，并将转化值发送到我们的服务器。

updatePostbackConversionValue(\_:)的6位值应与应用程序内事件相对应，不应该以二进制表示形式输入，而应该以0-63的整数形式输入。有关如何实施转化值的更多信息，请参考此页面。

截至iOS 16.1，它支持SKAdNetwork 4.0，您现在可以在更新后回传方法上发送coarseValue（字符串，可能的变体为"低"、"中"或"高"）和lockWindow（布尔值）作为参数。

updatePostbackConversionValue(_ conversionValue: Integer, coarseValue: String)

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

对于支持SKAdNetwork 4.0的iOS 16.1+版本，您可以多次调用此方法，并将转化值设置为低于或高于上一个值。
对于低于16.1的iOS版本，它们支持低于4.0的SKAdnetWork版本，您可以调用此方法，我们的SDK将自动检测iOS版本，并仅更新conversionValue。

#import "TenjinSDK.h"

@implementation TJNAppDelegate

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

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

    [TenjinSDK updatePostbackConversionValue: <YOUR 6 bit value> coarseValue:@"medium"];

    [TenjinSDK updatePostbackConversionValue: <YOUR 6 bit value> coarseValue:@"medium" lockWindow:true];

}
}

SKAdNetwork和iOS 15+广告主回传

为了将Tenjin指定为您的SK Ad Network回传的目的地，请按照以下步骤操作：

在Xcode的项目导航器中选择Info.plist。
在属性列表编辑器中，点击键旁边的添加按钮（+）并按回车。
键入关键字名NSAdvertisingAttributionReportEndpoint。
在类型列的弹出菜单中选择String。
输入https://tenjin-skan.com

这些步骤改编自苹果在https://developer.apple.com/documentation/storekit/skadnetwork/configuring_an_advertised_app上的说明。

Tenjin 和 GDPR

为了符合 GDPR 规定，使用 Tenjin 的 SDK，您可以选择加入、退出设备/用户，或选择哪些具体的设备相关参数要加入或退出。OptOut() 不会向 Tenjin 发送任何 API 请求，我们也不会处理任何事件。

选择加入/退出

#import "TenjinSDK.h"

@implementation TJNAppDelegate

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

  [TenjinSDK initialize:@"<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() 将发送所有设备相关参数（除了指定的参数）。

请注意，我们需要以下参数才能在 Tenjin 系统中正确跟踪设备。如果缺少必填参数，事件将不会处理或记录。
- developer_device_id

如果您打算使用 Google Ads，还需要添加：platform、os_version、locale、device_model 和 build_id。

如果您只想获取特定的设备相关参数，请使用 OptInParams()。下面的例子中，我们只会发送以下设备相关参数：ip_address、advertising_id、developer_device_id、limit_ad_tracking 和 iad

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

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

[TenjinSDK connect];

如果您希望发送除了特定设备相关参数外的所有参数，请使用 OptOutParams()。以下是例子，我们将发送除以下参数外的所有设备相关参数：locale、timezone 和 build_id。

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

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

[TenjinSDK connect];

设备相关参数

参数	描述	参考
ip_address	IP 地址
advertising_id	设备广告 ID	iOS
developer_device_id	供应商 ID	iOS
limit_ad_tracking	启用广告跟踪限制	iOS
platform	platform	iOS
iad	Apple Search Ad 参数	iOS
os_version	操作系统版本	iOS
设备	设备名称	iOS (hw.machine)
device_model	设备型号	iOS (hw.model)
device_model_name	设备型号名称	iOS (hw.model)
device_cpu	设备 CPU 名称	iOS (hw.cputype)
os_version_release	操作系统版本	iOS
build_id	构建 ID	iOS (kern.osversion)
locale	设备区域设置	iOS
国家	区域设置国家	iOS
timezone	timezone	iOS

购物事件

传递(SKPaymentTransaction *) transaction和(NSData *)receipt对象，在完成购买验证后，然后可以将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];

免责声明：如果您是第一次在Tenjin上实施购买事件，请在开始扩大您使用购买数据获取用户活动的营销活动之前，务必验证与其他工具使用的数据。

订阅内购

重要的：如果您有订阅内购，您需要在Tenjin仪表板中添加您应用的公钥。您可以从iTunes Connect控制台 > 选择您的应用 > 功能 > 内购 > 应用特定共享密钥中检索iOS应用特定共享密钥。

请注意，您需要在每个订阅间隔期间（例如，对于月度订阅，您需要每月向我们发送1笔交易）发送一次订阅交易。

以下示例时间线中，交易事件应该在“首次收费”和“续订”事件时发送。在试用期，请勿向Tenjin发送交易事件。Tenjin不会去重重复交易。

有关订阅的更多信息，请参阅：Apple关于处理订阅的文档

自定义事件

重要的：不要在上述 CONNECT/INITIALIZATION 事件之前发送自定义事件。初始化必须在发送任何自定义事件之前进行。

重要的：将自定义事件名称限制在80个字符以下。不要超过500个唯一自定义事件名称。

您还可以使用Tenjin SDK传递自定义事件

sendEventWithName: (NSString *)eventName 和

您可以使用这些功能将Tenjin自定义交互传递到您的应用中，通过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 必须是整数。如果 eventValue 不是一个整数，我们将不会发送此事件。

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

延迟深链接

Tenjin支持通过Tenjin的跟踪URL将用户引导到新安装的应用的特定部分。

⚠️ 注意：延迟深链接是一个付费功能，如果您对此感兴趣，请联系您的Tenjin账户经理。

服务器到服务器集成

Tenjin提供服务器到服务器的集成。如果您想访问文档，请发送电子邮件至 [email protected]。

适用于A/B测试的应用子版本参数（需要DataVault）

如果您正在运行A/B测试并希望报告差异，我们可以在使用 appendAppSubversion 方法给您的应用版本追加数字值。例如，如果您的应用版本是 1.0.1，并将 appendAppSubversion: @8888 设置，则将报告为 1.0.1.8888。

这些数据将在DataVault中显示，您可以使用应用子版本值进行报告。

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

影响级广告收入集成

Tenjin支持与以下平台的印象级广告收入（ILRD）功能集成：

AppLovin
Unity LevelPlay
HyperBid
AdMob
TopOn
CAS

此功能允许您接收与每次向用户展示广告相关并影响您广告收入的事件。要启用此功能，请遵循以下说明。

⚠️ 注意：ILRD是一项付费功能，请在发送ILRD事件之前先联系Tenjin账户经理讨论价格。

归因信息

Tenjin支持获取开发人员需要获取安装ID（以前称为Tenjin参考ID）所需的属性。当不存在广告ID时，可以使用此参数。

⚠️ 注意：归因信息是一项付费功能，如果您对此感兴趣，请联系您的Tenjin账户经理。

客户用户ID

您可以通过设置和检索客户用户ID将其作为参数发送到事件中。

setCustomerUserId(userId: "user_id")

getCustomerUserId()

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

事件的重试/缓存/IAP

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

setCacheEventSetting(true)

[TenjinSDK setCacheEventSetting:true];

TenjinSDK 1.14.3

TenjinSDK 1.14.3

TenjinSDK 1.14.3

摘要

备注

目录

SDK整合

Objective-C项目步骤

Swift项目的步骤

使用ATTrackingManager初始化Tenjin

显示ATT权限提示

配置用户跟踪描述

SKAdNetwork和转化价值

SKAdNetwork和iOS 15+广告主回传

Tenjin 和 GDPR

设备相关参数

购物事件

订阅内购

自定义事件

延迟深链接

服务器到服务器集成

适用于A/B测试的应用子版本参数（需要DataVault）

影响级广告收入集成

归因信息

客户用户ID

事件的重试/缓存/IAP