请参照我们的版本说明来查看历史版本。
关于 Unity 的说明请查看 https://github.com/tenjin/tenjin-unity-sdk
有任何问题或者需要帮助,请联系 support@tenjin.com
Tenjin iOS SDK (v1.12.4)
Tenjin 的原生 iOS SDK,集成到您的 iOS 应用中,以获取 Tenjin 提供的各项功能。
请注意:
- 如果您集成 iOS SDK v1.12.0 或以上版本,请使用 Xcode 12。
- 针对 ATT(AppTrackingTransparency),请确保更新您的
.plist
文件,并在添加Privacy - Tracking Usage Description
(NSUserTrackingUsageDescription) 的同时,向用户展示您认为需要展示的文字信息。
Tenjin 初始化:
- 如果您使用 pods, 添加
pod 'TenjinSDK'
到您的Podfile
然后运行pod install
后跳至步骤 5
1. 在此处下载 SDK 内容
2. 拖动 libTenjinSDK.a
和 TenjinSDK.h
到 project.
注意: 如果您是测试32位的 iOS 模拟设备(i386),您需要使用 libTenjinSDKUniversal.a
而不是 libTenjinSDK.a
.
3. 添加以下 Frameworks 到您的 project:
AdSupport.framework
AppTrackingTransparency.framework
iAd.framework
StoreKit.framework
4. 在 Build 设置中包含 linker flags -ObjC
5. 转到 AppDelegate 文件, 默认为 AppDelegate.m
, 和 #import "TenjinSDK.h"
.
6. 在 Tenjin Organization tab 取得 API_KEY
7a. 在 didFinishLaunchingWithOptions
method 添加:
[TenjinSDK init:@"<API_KEY>"];
[TenjinSDK connect];
这是一个 AppDelegate.m
文件在集成中的样例:
#import "TenjinSDK.h"
@implementation TJNAppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
[TenjinSDK init:@"<API_KEY>"];
[TenjinSDK connect];
//All your other stuff
...
}
注意:如果您使用的是 Swift 5, 请使用 getInstance()
方法,而不是 init()
。查看我们的 Swift app 样例
7b. 另一种初始化来处理其他服务中的深度链接(请勿同时使用 7a 和 7b,二选一即可)。
如果您使用其他服务产生延迟的深度链接,您可以向 Tenjin 发送这个链接,来处理已经已经打开 Tenjin 归因的深度链接。
#import "TenjinSDK.h"
@implementation TJNAppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
[TenjinSDK init:@"<API_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 初始化
从 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:@"<API_KEY>"];
if (@available(iOS 14, *)) {
[ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
[TenjinSDK connect];
}];
} else {
[TenjinSDK connect];
}
}
SKAdNetwork 和 Conversion value:
作为 SKAdNetwork 的一部分,我们为 registerAppForAdNetworkAttribution()
和 updateConversionValue(_:)
创建的封装方案,可以注册等效的 SKAdNetwork 方案并同时发送 conversion values 到我们的服务器。
updateConversionValue(_:) 6位值来对应应用内事件,不能二进制形式输入,而应为 0-63 的整数。我们的服务器将拒绝任何无效值。
#import "TenjinSDK.h"
@implementation TJNAppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
[TenjinSDK init:@"<API_KEY>"];
//
// This will call [SKAdNetwork registerAppForAdNetworkAttribution]
//
[TenjinSDK registerAppForAdNetworkAttribution];
[TenjinSDK connect];
//
// This will call [SKAdNetwork updateConversionValue: <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 updateConversionValue: <YOUR 6 bit value>];
}
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:@"<API_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:@"<API_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:@"<API_KEY>"];
NSArray *optOutParams = @[@"country", @"timezone", @"language"];
[TenjinSDK optOutParams:optOutParams];
[TenjinSDK connect];
设备相关参数 Device-Related Parameters
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 |
应用内购相关的事件集成说明:
有两种处理营收事件(revenue events)的方法:
1. 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
Tenjin 自定义事件集成说明:
重要提示:请不要在 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 将不发送事件。
Tenjin 延迟深度链接(deferred deeplink)集成说明:
通过 Tenjin 生成的广告活动追踪链接(campaign tracking URLs),有将用户指向 App 特定部分的功能。您可以通过 registerDeepLinkHandler
来处理延迟的深度链接 params[@"deferred_deeplink_url"]
。具体测试说明如下 here.
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
//initialize the Tenjin SDK like you normally would for attribution
[TenjinSDK init:@"<API_KEY>"];
[TenjinSDK connect]
//If you want to utilize the deeplink capabilities in Tenjin, utilize the registerDeepLinkHandler to retrieve the deferred_deeplink_url from the params NSDictionary object
[[TenjinSDK sharedInstance] registerDeepLinkHandler:^(NSDictionary *params, NSError *error) {
if([params[@"clicked_tenjin_link"] boolValue]){
if([params[@"is_first_session"] boolValue]){
//use the params to retrieve deferred_deeplink_url through params[@"deferred_deeplink_url"]
//use the deferred_deeplink_url to direct the user to a specific part of your app
} else{
}
}
}];
}
如果延迟深度链接中包含以下参数,可添加到回传中
Parameter | Description |
---|---|
advertising_id | IDFA of the device |
developer_device_id | IDFV of the device |
ad_network | Ad Network of the campaign |
campaign_id | Tenjin campaign ID |
campaign_name | Tenjin campaign name |
site_id | Site ID of source app |
deferred_deeplink_url | The deferred deep-link of the campaign |
clicked_tenjin_link | Boolean representing if the device was tracked by Tenjin |
is_first_session | Boolean representing if this is the first session for the device |
您也可以使用 v1.7.2+ SDK 中 registerDeepLinkHandler
的params
来处理 App 安装后的逻辑。比如,您有一个付费安装的 App,您可以按照以下方法:
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
//initialize the Tenjin SDK like you normally would for attribution
[TenjinSDK init:@"<API_KEY>"];
[TenjinSDK connect]
//If you want to utilize the deeplink capabilities in Tenjin, utilize the registerDeepLinkHandler to retrieve the deferred_deeplink_url from the params NSDictionary object
[[TenjinSDK sharedInstance] registerDeepLinkHandler:^(NSDictionary *params, NSError *error) {
if([params[@"is_first_session"] boolValue]){
//send paid app price and revenue to Tenjin
} else{
}
}];
}
用于 A/B 测试的 App Subversion 参数 (需要使用 DataVault)
如果您想运行 A/B 测试和差异报告,我们可以使用 appendAppSubversion
方法将数字值附加到您的应用程序版本中。例如,如果您的应用程序版本 1.0.1
设置了 appendAppSubversion: @8888
,报告中将为1.0.1.8888
。
这些数据将在 DataVault 中,您可以通过 subversion 值来运行报告。
[TenjinSDK init:@"<API_KEY>"];
[TenjinSDK appendAppSubversion:@8888];
[TenjinSDK connect];