# iOS SDK 使用指南
提示
在接入前, 请先阅读接入前准备。
您可以在 GitHub (opens new window) 获取 iOS SDK 源码。
iOS SDK 要求最低系统版本为iOS 8.0
iOS SDK ( Framework 格式) 大小约为 8.1 MB
最新版本为: 2.8.1.2
更新时间为: 2022-07-06
# 一、集成与初始化 SDK
# 1.1 自动集成 SDK
- 使用 CocoaPods 安装 SDK
1.创建并编辑 Podfile 内容(如果已有,直接编辑):
创建 Podfile,项目工程(.xcodeproj
)文件同目录下命令行执行命令:
pod init
编辑 Podfile 的内容如下:
platform :ios, '9.0'
target 'YourProjectTarget' do
pod 'ThinkingSDK' #ThinkingSDK
end
从 v2.8.1 版本开始,SDK 支持在 AppExtension 中进行数据采集。
如果您的项目存在 AppExtension,那么编辑 Podfile 的内容如下:
target 'YourAppExtensionTarget' do
pod "ThinkingSDK/Extension"
end
2.执行安装命令
pod install
成功以后,会出现如下记录:
3.导入成功,启动工程
命令执行成功后,会生成 .xcworkspace
文件,说明您已成功导入 iOS SDK
。打开 .xcworkspace
文件以启动工程(注意:此时不能同时开启 .xcodeproj
文件)
- 使用Carthage方式安装SDK
1.在 Cartfile 文件中添加以下配置:
github "ThinkingDataAnalytics/ios-sdk"
2.执行 carthage update --platform iOS
并将 ThinkingSDK.framework
添加到您的项目中
# 1.2 手动集成 SDK
1.下载并解压 iOS SDK (opens new window)
2.将 ThinkingSDK.framework
拖入 XCode Project Workspace 工程项目中
3.修改工程设置 Targets 选项下的 Build Settings 选项卡中 Other linker flags 的设置 添加 -ObjC
4.切换到 Build Phases 选项卡,在 Link Binary With Libraries 栏目下添加如下依赖项:
libz.dylib
、Security.framework
、SystemConfiguration.framework
、libsqlite3.tbd
# 1.3 初始化 SDK
在 v1.2.0 版本中,新增多 APP ID 实例的特性,关于多 APPID 的使用指南,请参考 iOS SDK 多 APPID 指南一节
在 AppDelegate.m 中添加 #import <ThinkingSDK/ThinkingAnalyticsSDK.h>
然后在 application:didFinishLaunchingWithOptions:
中添加初始化
如下
参数 APP_ID
是您的项目的 APP_ID ,在您申请项目时会给出,请在此处填入
参数 SERVER_URL
为数据上传的 URL
如果您使用的是云服务,请输入以下 URL:
https://global-receiver-ta.thinkingdata.cn
如果您使用的是私有化部署的版本,请输入以下 URL:
https://数据采集地址
使用 https 协议,请自行申请具有 SSL 证书的域名,TA 工作人员将会协助进行端口配置。
在完成初始化后,您可以按以下方式来使用 SDK :
在 v2.7.3 版本中,新增实例名特性,在实例初始化时传入实例名称 name ,用于标识实例。您也可以根据实例名称 name 获取实例。
# 1.4 后台自启事件说明
iOS 12 及以下版本(iOS 13 没有使用 EnableSceneSupport
)时,后台自启事件默认不统计,通过 trackRelaunchedInBackgroundEvents
来配置,YES
表示采集,NO
表示不采集。
iOS 13 使用了 EnableSceneSupport
,必须传入 launchOptions
参数。
# 1.5 开启与 H5 页面的打通(可选)
如果需要与采集 H5 页面数据的 JavaScript SDK 进行打通,请调用如下接口,详情请参考 H5 与 APP SDK 打通一节
# 1.6 AppExtension 事件采集
SDK 从 2.8.1 版本后支持在 AppExtension 中进行事件采集。
在 AppExtension 中初始化专用事件采集模块:
// 如果需要时间校准,请开启这一行代码
[TAAppExtensionAnalytic calibrateTimeWithNtp:@"time.apple.com"];
// 初始化
NSString *token = @"您的事件采集类的唯一标识,一般为appid";
NSString *appGroupId = @"您的应用组标识";
TAAppExtensionAnalytic *analytic = [TAAppExtensionAnalytic analyticWithInstanceName:token appGroupId:appGroupId];
AppExtension 中的事件采集操作:
[analytic writeEvent:@"event_name" properties:@{@"property_key": @"value"}];
AppExtension 中的事件采集,只做记录,不会上报,数据存储在 AppGroup 的共享存储中。所以需要在主 App 启动时,从共享存储获取数据,并进行上报。在主 App 启动完成,且 SDK 初始化完成后,调用如下代码:
NSString *token = @"您的事件采集类的唯一标识,一般为appid";
ThinkingAnalyticsSDK *instance = [ThinkingAnalyticsSDK sharedInstanceWithAppid:token];
NSString *appGroupId = @"您的应用组标识";
[instance trackFromAppExtensionWithAppGroupId:appGroupId];
# 二、设置用户 ID
SDK 实例会使用ID_安装次数作为每个用户的默认访客 ID,该 ID 将会作为用户在未登录状态下身份识别 ID。需要注意的是,访客 ID 在用户重新安装 App 以及更换设备时将会变更。
# 2.1 设置访客 ID(可选)
如果用户在您的产品中可以未登录状态下使用,且您需要配置用户在未登录状态下的访客 ID ,则您可以调用 identify:
来进行设置:
如果您需要替换访客 ID ,则应当在初始化 SDK 结束之后立即进行调用,请勿多次调用,以免产生无用的账号
如果需要获得当前访客 ID,可以调用 getDistinctId
获取:
# 2.2 设置账号 ID
在用户进行登录时,可调用 login:
来设置用户的账号 ID, TA 平台优先以账号 ID 作为身份标识,设置后的账号 ID 将会被保存,多次调用 login:
将覆盖先前的账号 ID :
请注意,该方法不会上传用户登录的事件
# 2.3 清空账号 ID
在用户产生登出行为之后,可调用 logout
来清除账号 ID ,在下次调用 login:
之前,将会以访客 ID 进行身份识别
我们推荐您在显性的登出事件时调用 logout
,比如用户产生注销行为时才调用,不需要在关闭 App 时进行调用。
请注意,该方法不会上传用户登出的事件
# 三、发送事件
在 SDK 初始化完成之后,您就可以调用 track:
、 track:properties:
来上传事件,一般情况下,您可能需要上传 20~100 个不同的事件,如果您是第一次使用 TA 后台,我们推荐您先上传几个关键事件。
# 3.1 发送事件
您可以调用 track:
、 track:properties:
来上传事件,建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件:
事件的名称是 NSString
类型,只能以字母开头,可包含数字,字母和下划线“_”,长度最大为 50 个字符,对字母大小写不敏感。
- 事件的属性是一个
NSDictionary
对象,其中每个元素代表一个属性。 - Key 的值为属性的名称,为
NSString
类型,规定只能以字母开头,包含数字,字母和下划线“_”,长度最大为 50 个字符,对字母大小写不敏感。 - Value 为该属性的值,可以为
NSString
、NSNumber
、NSDate
、NSArray
、NSDictionary
。NSDictionary
中的内容可以包含NSString
、NSNumber
、NSDate
以及NSArray
(其中内容为字符串);NSArray
中的内容可以包含NSDictionary
和NSString
- 如果您需要上传布尔型的属性,则请以
@YES
与@NO
或[NSNumber numberWithBool:YES]
与[NSNumber numberWithBool:NO]
来赋值。
不可以使用 @true
、 @false
、 @TRUE
和 @FALSE
赋值布尔型数据。
注意:
NSArray 类型在 v2.4.0 版本开始支持,需配合 TA 后台 v2.5 及后续版本使用.
NSDictionary类型v2.7.3 版本开始支持,需配合TA后台v3.5及后续版本使用
在 v2.2.0 版本中加入了设置事件触发时间及时间偏移的方法重载,支持传入 NSDate类型的参数来设置事件触发时间,以 NSTimeZone 类型的参数来设置时间偏移。不传入该参数,则取 track: 被调用时的本机时间以及偏移作为事件触发时间以及时区偏移:
注意:尽管事件可以设置触发时间,但是接收端会做如下的限制,只接收相对服务器时间在前 10 天至后 3 天的数据,超过时限的数据将会被视为异常数据,整条数据无法入库。
自 v2.3.1 版本开始,您可以通过设置 SDK 默认时区的方式,对齐多个时区下的事件时间,请参考设置默认时区小节。
自 v2.5.0 开始,您可以通过校准 SDK 时间接口来统一使用服务端时间完成数据采集。请参考校准时间小节。
# 3.2 设置公共事件属性
对于一些重要的属性,譬如用户的会员等级、来源渠道等,这些属性需要设置在每个事件中,此时您可以将这些属性设置为公共事件属性。公共事件属性指的就是每个事件都会带有的属性,您可以调用 setSuperProperties:
来设置公共属性 ,我们推荐您在发送事件前,先设置公共事件属性。
公共事件属性的格式要求与事件属性一致。
公共事件属性将会被保存到缓存中,无需每次启动 App 时调用。如果调用 setSuperProperties:
设置了先前已设置过的公共事件属性,则会覆盖之前的属性。如果公共事件属性和 track:properties:
上传的某个属性的 Key 重复,则该事件的属性会覆盖公共事件属性:
如果您需要删除某个公共事件属性,可以调用 unsetSuperProperty:
清除指定的公共事件属性;如果您想要清空所有公共事件属性,则可以调用 clearSuperProperties
;如果您想要获取所有公共事件属性,可以调用currentSuperProperties
;
# 3.3 设置动态公共属性
在 v1.2.0 版本中,新增了动态公共属性的特性,即公共属性可以上报时获取当时的值,使得诸如会员等级之类的可变公共属性可以被便捷地上报。通过 registerDynamicSuperProperties
设置动态公共属性类之后,SDK 将会在事件上报时自动执行并获取返回值中的属性,添加到触发的事件中。以下例子是每次上报时将获取当前时间并切换时区,当任意事件触发时,SDK 会将返回的时间加入到该事件的属性中。
# 3.4 记录事件时长
如果您需要记录某个事件的持续时长,可以调用 timeEvent
来开始计时,配置您想要计时的事件名称,当您上传该事件时,将会自动在您的事件属性中加入 #duration
这一属性来表示记录的时长,单位为秒。
# 四、用户属性
TA 平台目前支持的用户属性设置接口为 user_set:
、user_setOnce:
、user_add:
、user_unset:
、user_delete
与user_append
# 4.1 user_set
对于一般的用户属性,您可以调用 user_set:
来进行设置,使用该接口上传的属性将会覆盖原有的属性值,如果之前不存在该用户属性,则会新建该用户属性,类型与传入属性的类型一致
属性格式要求与事件属性保持一致。
# 4.2 user_setOnce
如果您要上传的用户属性只要设置一次,则可以调用 user_setOnce:
来进行设置,当该属性之前已经有值的时候,将会忽略这条信息。
属性格式要求与事件属性保持一致。
# 4.3 user_add
当您要上传数值型的属性时,您可以调用 user_add:
来对该属性进行累加操作,如果该属性还未被设置,则会赋值 0 后再进行计算
设置的属性key为字符串,Value 只允许为数值。
# 4.4 user_unset
当您要清空用户的某个用户属性值时,您可以调用 user_unset:
来对指定属性进行清空操作,如果该属性还未在集群中被创建,则 user_unset:
不会创建该属性
user_unset传入值为被清空属性的 Key 值。
# 4.5 user_delete
如果您要删除某个用户,可以调用 user_delete
将这名用户删除,您将无法再查询该名用户的用户属性,但该用户产生的事件仍然可以被查询到
# 4.6 user_append
从 v2.4.0 版本开始,您可以调用 user_append
对 NSArray 类型的用户属性进行追加操作。
# 4.7 user_uniqAppend
从 v2.8.0 版本开始,您可以调用 user_uniqAppend
对 NSArray 类型的用户属性进行追加操作。
和 user_append
接口的区别,调用 user_uniqAppend
接口会对追加的用户属性进行去重, user_append
接口不做去重,用户属性可存在重复。
# 五、自动采集事件
关于自动采集事件的具体使用方法,请参考 iOS SDK 自动采集指南一章。
# 六、SDK 配置
# 6.1 设置上传的网络条件
在默认情况下,SDK 将会网络条件为在 2G, 3G, 4G, 5G 及 Wifi 时上传数据,您可以通过下列方法修改允许上传的网络条件:
# 6.2 数据上报状态
在 v2.8.0 版本中,新增了 SDK 数据上报状态,一共有四种状态:
# 6.2.1 暂停 SDK 上报(TATrackStatusPause)
您可能希望在一些场景下,暂时停止 SDK 的数据采集以及上报,比如用户处于测试环境中、或者用户登录了一个测试账号,此时您可以调用下列接口,暂时停止 SDK 的上报。
您可以通过某一实例(包括主要实例以及轻实例)调用 setTrackStatus:
,传入 TATrackStatusPause
来暂停 SDK 的上报,该实例已经设置的 #distinct_id
、#account_id
、公共属性等将保留;该实例已经采集但还未上报成功的数据将继续尝试上报;后续该实例不能采集以及上报任何新数据、不能设置访客 ID、账户 ID 以及公共属性等,但是可以读取该实例已经设置的公共属性和设备 ID、访客 ID、账号 ID 等信息。
实例的停止状态将会被保存在本地缓存,直到调用 setTrackStatus:
、传入 TATrackStatusNormal
,SDK 实例将会重新恢复数据采集以及上报,需要注意轻实例因为不进行缓存,因此每次打开 APP 后,轻实例的暂停状态不会被保留,将重新开启上报。
# 6.2.2 停止SDK上报并清除缓存(TATrackStatusStop)
在一些特殊场景下,您可能需要完全停止 SDK 的功能,比如在适用 GDPR 的地区,用户选择不提供数据采集权限,则您可以调用如下接口完全关闭 SDK 的功能。
TATrackStatusStop
只能通过主要实例调用,与 TATrackStatusPause
的最大区别在于,其将会清空该实例的本地缓存,包括本实例的访客 ID,账号 ID,公共属性,以及未上报的数据队列。之后再关闭该实例的采集和上报功能。
实例的停止状态也将保存在本地缓存,直到调用 setTrackStatus:
、传入 TATrackStatusNormal
,后续可以继续上报,但此时相当于一个全新的实例
# 6.2.3 数据采集入库但暂停上报数据(TATrackStatusSaveOnly)
您可能希望在一些场景下,暂时停止 SDK 数据的网络上报,以免影响用户体验,比如用户处于游戏战斗场景,此时您可以调用下列接口,暂时停止 SDK 的网络上报。
您可以通过某一实例(包括主要实例以及轻实例)调用 setTrackStatus:
,传入 TATrackStatusSaveOnly
来暂停 SDK 的网络上报(数据采集依然存在);
实例的停止状态将会被保存在本地缓存,直到调用 setTrackStatus:
、传入 TATrackStatusNormal
,SDK 实例将会把本地库中未上报数据立即上报,需要注意轻实例因为不进行缓存,因此每次打开 APP 后,轻实例的暂停状态不会被保留,将重新开启上报。
# 6.2.4 正常状态(TATrackStatusNormal)
SDK 正常状态TATrackStatusNormal
,数据会进行采集并网络上报。
SDK不进行数据上报状态设置的话,就是默认此状态。
# 6.3 打印数据 Log
可以调用setLogLevel
来开启(默认是关闭的):
# 6.4 获取设备 ID
在 v2.0.0 版本,加入了获取设备 ID(也就是预置属性#device_id
)的接口,您可以通过调用 getDeviceId
来获取设备 ID:
[instance getDeviceId];
// 如果需要将设备ID设置成访客ID可以如下调用
// [instance identify:[instance getDeviceId]];
# 6.5 配置 HTTPS 校验方法:
从 v2.3.0 版本开始,SDK 可以配置 HTTPS 校验方法,需要在初始化的时候首先获取 TDConfig 实例,然后用 TDConfig 完成初始化。
# 6.6 设置默认时区
默认情况下,如果用户不指定事件发生时间,SDK 默认会使用接口调用时的本机时间作为事件发生时间上报。自 v2.3.1 版本开始,您也可以通过设置默认时区接口,指定默认的时区,这样所有的事件(包括自动采集事件)都将按照您设置的时区来对齐事件时间:
// 获取 TDConfig 实例
TDConfig *config = [[TDConfig alloc] init];
// 设置默认时区为 UTC
config.defaultTimeZone = [NSTimeZone timeZoneWithName:@"UTC"];
// 初始化 SDK
ThinkingAnalyticsSDK *instance = [ThinkingAnalyticsSDK startWithAppId:@"YOUR_APPID" withUrl:@"YOUR_SERVER_URL" withConfig:config];
注意:用指定时区对齐事件时间,会丢掉设备本机时区信息。如果需要保留设备本机时区信息,目前需要您自己为事件添加相关属性。
# 6.7 开启 Debug 模式
从 v2.4.0 版本开始,客户端 SDK 支持 Debug 模式,需要配合 TA 平台 2.5 之后的版本使用。
Debug 模式可能会影响数据采集质量和 App 的稳定性,只用于集成阶段数据验证,不要在线上环境使用。
当前 SDK 实例支持三种运行模式,在 TDConfig
中定义:
/**
Debug模式
- ThinkingAnalyticsDebugOff : 默认 不开启Debug模式
*/
typedef NS_OPTIONS(NSInteger, ThinkingAnalyticsDebugMode) {
/**
默认 不开启Debug模式
*/
ThinkingAnalyticsDebugOff = 0,
/**
开启Debug_only模式,只对数据做校验,不会入库
*/
ThinkingAnalyticsDebugOnly = 1 << 0,
/**
Debug 模式,数据逐条上报。当出现问题时会以日志和异常的方式提示用户
*/
ThinkingAnalyticsDebug = 1 << 1
};
为了设置 SDK 实例运行模式,请使用 TDConfig
来完成 SDK 初始化:
// 获取 TDConfig 实例
TDConfig *config = [[TDConfig alloc] init];
// 设置运行模式为 Debug 模式
config.debugMode = ThinkingAnalyticsDebug;
// 初始化 SDK
ThinkingAnalyticsSDK *instance = [ThinkingAnalyticsSDK startWithAppId:@"YOUR_APPID" withUrl:@"YOUR_SERVER_URL" withConfig:config];
为了避免 Debug 模式在生产环境上线,规定只有指定的设备才能开启 Debug 模式。只有在客户端开启了 Debug 模式,并且设备 ID 在 TA 后台的"埋点管理"页的"Debug 数据"板块中配置了的设备才能开启 Debug 模式。
设备 ID 可以通过以下三种方式获取:
- TA 平台中事件数据中的 #device_id 属性
- 客户端日志:SDK 初始化完成后会打印设备 DeviceId
- 通过实例接口调用:获取设备 ID
# 6.8 校准时间
SDK 默认会使用本机时间作为事件发生时间上报,如果用户手动修改设备时间会影响到您的业务分析,自 v2.5.0 版本开始,您可以使用从服务端获取的当前时间戳对 SDK 的时间进行校准。此后,所有为指定时间的调用,包括事件数据和用户属性设置操作,都会使用校准后的时间作为发生时间。
我们也提供了从 NTP 获取时间对 SDK 校准的功能。您需要传入您的用户可以访问的 NTP 服务器地址。之后 SDK 会尝试从传入的 NTP 服务地址中获取当前时间,并对 SDK 时间进行校准。如果在默认的超时时间(3 秒)之内,未获取正确的返回结果,后续将使用本地时间上报数据。
注意:
- 您需要谨慎地选择您的 NTP 服务器地址,以保证网络状况良好的情况下,用户设备可以很快的获取到服务器时间。
- 使用 NTP 服务进行时间校准存在一定的不确定性,建议您优先考虑用时间戳校准的方式。
除了以上校准时间接口外,在 v2.5.0 提供了所有用户属性接口的时间函数重载,您可以在调用用户属性相关接口时,传入 Date 对象,则系统会使用传入的 Date 对象来设定数据的 #time
字段。
# 七、相关预置属性
# 7.1 所有事件带有的预置属性
以下预置属性,是 iOS SDK 中所有事件(包括自动采集事件)都会带有的预置属性
属性名 | 中文名 | 说明 |
---|---|---|
#ip | IP 地址 | 用户的 IP 地址,TA 将以此获取用户的地理位置信息 |
#country | 国家 | 用户所在国家,根据 IP 地址生成 |
#country_code | 国家代码 | 用户所在国家的国家代码(ISO 3166-1 alpha-2,即两位大写英文字母),根据 IP 地址生成 |
#province | 省份 | 用户所在省份,根据 IP 地址生成 |
#city | 城市 | 用户所在城市,根据 IP 地址生成 |
#os_version | 操作系统版本 | iOS 11.2.2、Android 8.0.0 等 |
#manufacturer | 设备制造商 | 用户设备的制造商,如 Apple,vivo 等 |
#os | 操作系统 | 如 Android、iOS 等 |
#device_id | 设备 ID | 用户的设备 ID,iOS 取用户的 IDFV 或 UUID,Android 取 androidID |
#screen_height | 屏幕高度 | 用户设备的屏幕高度,如 1920 等 |
#screen_width | 屏幕宽度 | 用户设备的屏幕高度,如 1080 等 |
#device_model | 设备型号 | 用户设备的型号,如 iPhone 8 等 |
#app_version | APP 版本 | 您的 APP 的版本 |
#bundle_id | 应用唯一标识 | 应用包名或进程名 |
#lib | SDK 类型 | 您接入 SDK 的类型,如 Android,iOS 等 |
#lib_version | SDK 版本 | 您接入 SDK 的版本 |
#network_type | 网络状态 | 上传事件时的网络状态,如 WIFI、3G、4G 等 |
#carrier | 网络运营商 | 用户设备的网络运营商,如中国移动,中国电信等 |
#zone_offset | 时区偏移 | 数据时间相对 UTC 时间的偏移小时数 |
#install_time | 程序安装时间 | 用户安装应用的时间,值来源于系统 |
#simulator | 是/否为模拟器 | 设备是否是模拟器 true/false |
#ram | 设备运行内存状态 | 用户设备的当前剩余内存和总内存,单位GB,如 1.4/2.4 |
#disk | 设备存储空间状态 | 用户设备的当前剩余存储空间和总存储空间,单位GB,如 30 /200 |
#fps | 设备 FPS | 用户设备的当前图像每秒传输帧率,如 60 |
#system_language | 系统语言 | 用户设备的系统语言(ISO 639-1,即两位小写英文字母),如 zh, en 等 |
# 7.2 自动采集事件的预置属性
以下预置属性,是各个自动采集事件中所特有的预置属性
- APP 启动事件(ta_app_start)的预置属性
属性名 | 中文名 | 说明 |
---|---|---|
#resume_from_background | 是否从后台唤醒 | 表示 APP 是被开启还是从后台唤醒,取值为 true 表示从后台唤醒,false 为直接开启 |
#start_reason | 应用启动来源 | 内容为JSON字符串;应用使用url或者intent方式打开APP时,自动记录url内容以及intent中的data数据,数据样例参考{url:"thinkingdata://","data":{}} |
#backgroud_duration | 后台停留时长 | 记录两次start事件发生区间内,应用在后台的停留时长,单位是秒 |
- APP 关闭事件(ta_app_end)的预置属性
属性名 | 中文名 | 说明 |
---|---|---|
#duration | 事件时长 | 表示该次 APP 访问(自启动至结束)的时长,单位是秒 |
- APP 浏览页面事件(ta_app_view)的预置属性
属性名 | 中文名 | 说明 |
---|---|---|
#title | 页面标题 | 为 View Controller 的标题,取值为 controller.navigationItem.title 属性的值 |
#screen_name | 页面名称 | 为 View Controller 的类名 |
#url | 页面地址 | 当前页面的地址,需要调用 getScreenUrl 进行 url 的设置 |
#referrer | 前向地址 | 跳转前页面的地址,跳转前页面需要调用 getScreenUrl 进行 url 的设置 |
- APP 控件点击事件(ta_app_click)的预置属性
属性名 | 中文名 | 说明 |
---|---|---|
#title | 页面标题 | 为 View Controller 的标题,取值为 controller.navigationItem.title 属性的值 |
#screen_name | 页面名称 | 为 View Controller 的类名 |
#element_id | 元素 ID | 控件的 ID,需要 thinkingAnalyticsViewID 进行设置 |
#element_type | 元素类型 | 控件的类型 |
#element_selector | 元素选择器 | 为控件的 viewPath 的拼接 |
#element_position | 元素位置 | 控件的位置信息,只有当控件类型为 UITableView 或 UICollectionView 才会存在,表示控件被点击的位置,取值为 组号(Section):行号(Row) |
#element_content | 元素内容 | 控件上的内容 |
- APP 崩溃事件(ta_app_crash)的预置属性
属性名 | 中文名 | 说明 |
---|---|---|
#app_crashed_reason | 异常信息 | 字符型,记录崩溃时的堆栈轨迹 |
# 7.3 其他预置属性
除了上述提到预置属性,还有部分预置属性需要调用对应接口才会被记录:
属性名 | 中文名 | 说明 |
---|---|---|
#duration | 事件时长 | 需要调用计时功能接口 timeEvent: ,记录事件发生时长,单位是秒 |
#background_duration | 后台停留时长 | 需要调用计时功能接口 timeEvent ,记录事件发生区间内,应用在后台的停留时长,单位是秒 |
# 7.4 获取预置属性
v2.7.0 及以后的版本可以调用 getPresetProperties
方法获取预置属性。
服务端埋点需要 App 端的一些预置属性时,可以通过此方法获取 App 端的预置属性,再传给服务端。
IP,国家城市信息由服务端解析生成,客户端不提供接口获取这些属性
# 7.6 预制属性开关
从 v2.7.4 开始, SDK 支持屏蔽指定预制属性的上报。
在工程的info.plist文件中添加TDDisPresetProperties字段,类型是Array,添加的字段对应的预置属性将不会上传。
如屏蔽"#fps", @"#ram", @"#disk", @"#start_reason", @"#simulator"等预制属性,配置如下图:
# 八、进阶功能
从 v2.6.0 开始,SDK 支持上报三种特殊类型事件: 首次事件、可更新事件、可重写事件。这三种事件需要配合 TA 系统 2.8 及之后的版本使用。由于特殊事件只在某些特定场景下适用,所以请在数数科技的客户成功和分析师的帮助下使用特殊事件上报数据。
# 8.1 首次事件
首次事件是指针对某个设备或者其他维度的 ID,只会记录一次的事件。例如在一些场景下,您可能希望记录在某个设备上第一次发生的事件,则可以用首次事件来上报数据。
如果您希望以设备以外的其他维度来判断是否首次,则可以为首次事件设置 FIRST_CHECK_ID. 例如您需要记录某个账号的首次事件,可以将账号 ID 设置为首次事件的 FIRST_CHECK_ID:
注意:由于在服务端完成对是否首次的校验,首次事件会延时 1 小时入库。
# 8.2 可更新事件
您可以通过可更新事件实现特定场景下需要修改事件数据的需求。可更新事件需要指定标识该事件的 ID,并在创建可更新事件对象时传入。TA 后台将根据事件名和事件 ID 来确定需要更新的数据。
# 8.3 可重写事件
可重写事件与可更新事件类似,区别在于可重写事件会用最新的数据完全覆盖历史数据,从效果上看相当于删除前一条数据,并入库最新的数据。TA 后台将根据事件名和事件 ID 来确定需要更新的数据。
# 九、加密功能
从 v2.8.0 版本开始,SDK 支持加密功能,客户端支持AES+RSA对数据进行加密,再由服务端对数据进行解密,加解密能力需要客户端和服务端配合完成,具体请咨询客户成功人员。
分别设置TDConfig
对象的enableEncrypt
属性为YES
,设置secretKey
属性为TDSecretKey
自定义对象。
TDSecretKey
配置了版本号、公钥等密钥信息
NSString *appid = @"APPIDXXX";
NSString *url = @"https://XXXX";
TDConfig *config = [TDConfig new];
config.appid = appid;
config.configureURL = url;
// 开启加密功能
config.enableEncrypt = YES;
// 配置版本号、公钥等密钥信息
config.secretKey = [[TDSecretKey alloc] initWithVersion:1 publicKey:@"MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCzAKEGsq67Yd03/RF77VKJ/cQ3\nzfSboK1wzlQfH2E1fr504WCJHHL/UVgjfUGUjMLIN15FNEelp7TXLToqtYlqqMbE\nXCfSc14ulRatKQioYnJ8EzgUhG0HcRlulni6vxGJHR9iq4weDNyJFRaZuwIQSrUz\nIaiVq/3hYijxxhhFqQIDAQAB"];
[ThinkingAnalyticsSDK startWithConfig:config];
[[ThinkingAnalyticsSDK sharedInstance] login:@"login1"];
[[ThinkingAnalyticsSDK sharedInstance] track:@"secret_event" properties:@{@"a":@"asadas",@"b":@"djGNVWOzMC/4D2v/JGN.EsH3uP2stjoZ=+/", @"wangdaji":@"王大吉"}];
[[ThinkingAnalyticsSDK sharedInstance] user_uniqAppend:@{@"abc":@[@"aaa",@"bbb",@"ccc"]}];
[[ThinkingAnalyticsSDK sharedInstance] flush];
# 十、支持三方数据接入
从v2.8.0开始支持三方数据接入
# 10.1 Appsflyer
- 在AppsFlyer SDK调用start方法之前调用API
[[ThinkingAnalyticsSDK sharedInstance] enableThirdPartySharing: TDThirdPartyShareTypeAPPSFLYER];
- 注册创角色之后(可选)
[[ThinkingAnalyticsSDK sharedInstance] login:@"account_id"];
[[ThinkingAnalyticsSDK sharedInstance] enableThirdPartySharing: TDThirdPartyShareTypeAPPSFLYER customMap:@{@"ta_data11":@"ta_value11"}];
如果调用了TA的login方法(会修改account_id)或者identify方法(会修改distinct_id),需要再次调用enableThirdPartySharing同步数据
注意:如果您也需要调用AppsFlyer SDK的setAdditionalData方法
NSDictionary *dic = @{@"af_test_key1": @"test1",@"af_test_key2": @"test2"};
[AppsFlyerLib.shared setAdditionalData:dic];
因为setAdditionalData调用多次,会覆盖之前的参数,可以将参数传递给TA,TASDK内部会将参数进行拼接合并
NSDictionary *dic = @{@"af_test_key1": @"test1",@"af_test_key2": @"test2"};
[[ThinkingAnalyticsSDK sharedInstance] enableThirdPartySharing: TDThirdPartyShareTypeAPPSFLYER customMap: dic];
# 10.2 Adjust
- 在Adjust SDK初始化之前调用
[[ThinkingAnalyticsSDK sharedInstance] enableThirdPartySharing:TDThirdPartyShareTypeADJUST];
- 注册创角色之后(可选)
[[ThinkingAnalyticsSDK sharedInstance] login:@"account_id"];
[[ThinkingAnalyticsSDK sharedInstance] enableThirdPartySharing:TDThirdPartyShareTypeADJUST];
# 10.3 Branch
- 在Branch SDK初始化之前调用
[[ThinkingAnalyticsSDK sharedInstance] enableThirdPartySharing:TDThirdPartyShareTypeBRANCH];
- 注册创角色之后(可选)
[[ThinkingAnalyticsSDK sharedInstance] login:@"account_id"];
[[ThinkingAnalyticsSDK sharedInstance] enableThirdPartySharing:TDThirdPartyShareTypeBRANCH];
# 10.4 TopOn
- 在ATSDK初始化之前调用
[[ThinkingAnalyticsSDK sharedInstance] enableThirdPartySharing:TDThirdPartyShareTypeTOPON];
注意:如果您也需要调用ATSDK的setCustomData方法
NSDictionary *dic = @{@"af_test_key1": @"test1",@"af_test_key2": @"test2"};
[[ATAPI sharedInstance] setCustomData: dic];
因为setCustomData调用多次,会覆盖之前的参数,可以将参数传递给TA,TASDK内部会将参数进行拼接合并
NSDictionary *dic = @{@"af_test_key1": @"test1",@"af_test_key2": @"test2"};
[[ThinkingAnalyticsSDK sharedInstance] enableThirdPartySharing:TDThirdPartyShareTypeTOPON customMap: dic];
# 10.5 热云
在账号注册之后调用
[[ThinkingAnalyticsSDK sharedInstance] enableThirdPartySharing:TDThirdPartyShareTypeTRACKING];
# 10.6 Tradplus
在TradPlusSdk初始化之前调用
[[ThinkingAnalyticsSDK sharedInstance] enableThirdPartySharing:TDThirdPartyShareTypeTRADPLUS];
# 10.7 IronSource
在IronSourceSdk初始化之后调用
[[ThinkingAnalyticsSDK sharedInstance] enableThirdPartySharing: TDThirdPartyShareTypeIRONSOURCE];
注意:
- enableThirdPartySharing: 方法
- enableThirdPartySharing: customMap: 方法
第一个方法参数是支持位运算的,如果想同步多个平台的数据
[[ThinkingAnalyticsSDK sharedInstance] enableThirdPartySharing:TDThirdPartyShareTypeAPPSFLYER | TDThirdPartyShareTypeADJUST |TDThirdPartyShareTypeTRADPLUS | TDThirdPartyShareTypeTRACKING | TDThirdPartyShareTypeTOPON | TDThirdPartyShareTypeBRANCH | TDThirdPartyShareTypeIRONSOURCE];
如果Appsflyer,TopOn需要增加额外参数,需要用到第二个API的时候,第一个参数是不支持位运算的。
# ChangeLog
# v2.8.1.1 2022/06/27
- 代码优化,提升SDK稳定性
# v2.8.1 2022/06/13
- 提供AppExtension数据采集模块
# v2.8.0.1 2022/05/23
- 修复获取推送启动原因时导致的系统回调无法执行
# v2.8.0 2022/04/18
- 代码优化
- 添加三方数据集成功能
- 添加加密功能
# v2.7.4 2022/01/18
- 代码优化
- 添加启动原因、性能指标等预制属性
# v2.7.3 2021/11/09
- 支持复杂数据类型
# v2.7.2 2021/08/18
- 代码优化
- 优化安装事件采集逻辑
# v2.7.1 2021/07/21
- 代码优化
# v2.7.0 2021/06/16
- 支持预置属性获取
- 代码优化
# v2.6.5 2021/04/19
- 代码优化
# v2.6.4 2021/03/15
- 新增预置属性#bundle_id(应用包名)
- 适配iOS 14
# v2.6.3 2021/01/18
- 优化获取网络类型逻辑
# v2.6.2 2020/10/29
- 适配 5G 网络
- 优化 install,start 事件上报逻辑
- 优化数据传输格式
- 默认网络上报策略调整为 2G/3G/4G/5G/WIFI
# v2.6.1 2020/08/25
- 修复特殊事件设置 timeZone 的逻辑, 现在不设置 timeZone 上报数据不会再带有#zone_offset=0 了.
# v2.6.0 2020/08/24
- 支持首次事件, 允许传入自定义的 ID 校验是否首次上报
- 支持可更新、可重写的事件
# v2.5.6 2020/08/11
- 优化时间校准 API, 现在多次调用会多次生效.
# v2.5.5 2020/06/23
- 修复部分机型 #system_language 异常
# v2.5.4 2020/06/22
- 修复 v2.5.3 undeclared selector 'applicationWillTerminateNotification:' [-Wundeclared-selector]
# v2.5.3 2020/06/22
- 新增预置属性 #system_language
- 固定预置属性 #os 为 "iOS"
- 优化代码
# v2.5.2 2020/05/15
- 修复 v2.5.1 中 Debug 模式会因数据格式错误降级的问题
# v2.5.1 2020/05/14
- 适配 TA 后台 2.7 版本屏蔽事件配置接口
- 调整 DEBUG 模式,去除客户端抛异常逻辑
# v2.5.0 2020/04/03
- 支持客户端 SDK 的时间校准功能
- 新增指定时间的用户属性设置接口
- 代码优化
# v2.4.3 2020/03/11
- 去除 UIWebView 相关代码
# v2.4.2 2020/03/09
- 延迟初始化时正常按间隔上报数据
- 代码优化
# v2.4.1 2020/02/21
- 修复 v2.3.0、v2.3.1、v2.4.0 引入的 bug
# v2.4.0 2020/02/10
- 支持 NSArray 类型
- 新增 user_append 接口
- 去除客户端的属性格式检查
# v2.3.1 2020/01/07
- 支持配置默认时区
# v2.3.0 2019/12/31
- 支持 Debug 模式: 需配合后台 Debug 设备白名单一起开启
- H5 与原生 SDK 打通支持多实例
- 优化 SDK 配置: 增加全局设置;上报策略允许针对不同项目配置
- 支持配置 HTTPS 证书校验
# v2.2.2 2019/12/01
- 修复使用
EnableSceneSupport
时,APP 启动事件(ta_app_install
)中的属性#resume_from_background
取值异常的问题
# v2.2.1 2019/11/22
- 依据 Appstore ITMS-90809 默认去除 UIWebView 相关内容
# v2.2.0 2019/10/21
- 新增
user_unset
接口,可用于清空一个用户属性 - 新增预置属性
#zone_offset
,单位为小时。 默认情况下会将本地时区的偏移上报到服务端,该时间偏移会受夏令时影响。满足如下公式:
utc_time + #zone_offset = #event_time
# v2.1.1 2019/10/11
- 优化上报逻辑,解决极端情况下数据异常上报的问题
# v2.1.0 2019/09/16
- 支持轻量级实例, 便于上报被动事件等需求
- 新增 enableTracking 接口, 可以打开或关闭实例上报功能
- 新增 optOutTracking/optInTracking 接口
- 其他代码优化
# v2.0.1 2019/07/15
- 调整了自动采集事件中 ta_app_install(APP 安装事件)的触发顺序,现在将在 ta_app_start(APP 启动事件)前触发
# v2.0.0 2019/07/12
- 自动采集事件新增 APP 安装事件
- 默认不采集后台自启时产生的数据,后续会添加后台自启接口,可控制是否采集后台自启时产生的数据
# v1.2.0 2019/06/20
- 新增多 APPID 实例功能
- 新增动态公共属性特性
- 自动采集事件新增 APP 崩溃事件