iOS SDK
  • 04 Jan 2023
  • 4 阅读时间
  • 黑暗模式
    白天模式

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.0 或以上版本,请使用 Xcode 12。
  • 针对 ATT(AppTrackingTransparency),请确保更新你的 .plist 文件,并在添加 Privacy - Tracking Usage Description (NSUserTrackingUsageDescription) 的同时,向用户展示你认为需要展示的文字信息。 此 library 仅支持 iOS 14.0 以上。
  • 如果你需要对于 Apple Search Ads 的归因支持,请务必升级到 v1.12.6 及以后版本,并添加 AdServices.framework 库。此 library 仅支持 iOS 14.3 以上

目录


SDK 集成

Cocapods

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

Swift Package Manager

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

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

  2. 拖动 libTenjinSDK.aTenjinSDK.h 到 project。
    注意: 如果你是测试32位的 iOS 模拟设备(i386),你需要使用 libTenjinSDKUniversal.a 而不是 libTenjinSDK.a

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

  • AdServices.framework
  • AdSupport.framework
  • AppTrackingTransparency.framework
  • iAd.framework
  • StoreKit.framework
    Dashboard
  1. 在 Build 设置中包含 linker flags -ObjC
    Dashboard

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

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

    app_api_key.png

  4. 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 的整数。我们的服务器将拒绝任何无效值。

#import "TenjinSDK.h"

@implementation TJNAppDelegate

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

    [TenjinSDK init:@"<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>];
}

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 请求,我们也不会处理任何事件。

GDPR

任何要求处理或使用欧盟公民个人数据的组织/品牌,都需要遵守《通用数据保护条例》(General Data Protection Regulations,简称 GDPR)在访问数据、转移数据、更正数据和删除数据方面的规范。

如何 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, 和 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];

设备层级数据

Param Description Reference
ip_address IP 地址
advertising_id 设备 Advertising ID iOS
developer_device_id ID for Vendor iOS
limit_ad_tracking 开启限制广告追踪 iOS
platform platform iOS
iad Apple 搜索广告参数 iOS
os_version 操作系统版本 iOS
device 设备名称 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 build ID iOS (kern.osversion)
locale 设备区域 iOS
country 区域国家 iOS
timezone 时区 iOS

购买事件

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 的 public key 到 Tenjin 的控制面板。你可以在通过以下途径获取 iOS 的共享密钥 iTunes Connect Console > Select your app > Features > In-App Purchases > 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

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

展示层级收益数据为付费功能,如有需要请联系你的客户经理讨论合约事宜。


归因信息

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

这将允许广告主实时收集和分析这些用户级归因数据。以下是使用 Tenjin 归因信息回调的实用案例:

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

注意: SDK 层面获取到用户归因信息为付费功能,如有需要请联系你的客户经理讨论合约事宜。



本文对您有帮助吗?

What's Next