ⓘ 提示
iOS SDK 要求最低系统版本为 iOS 11.0
Add the following to your Package.swift file:
dependencies:
.package(url: "https://github.com/lovinjoy/datatower.ai-core-ios",from:"{上面的最新版本}")
Build your project:
$ swift build
CocoaPods is a dependency manager for Cocoa projects. To install ROIQueryCoreFrame with CocoaPods:
Make sure CocoaPods is installed.
# Using the default Ruby install will require you to use sudo when
# installing and updating gems.
[sudo] gem install cocoapods
Update your Podfile to include the following:
use_frameworks!
target 'YourAppTargetName' do
pod 'DataTowerAICore', '~> {上面的最新版本}'
end
Run pod install --repo-update.
DataTower.ai Core SDK 唯一初始化入口
+ (void)initSDK:(NSString *)appid
serverUrl:(NSString *)url
channel:(DTChannel)channel
isDebug:(BOOL)debug
logLevel:(DTLoggingLevel)logLevel
enableTrack:(BOOL)enableTrack
参数名 | 类型 | 是否必传 | 说明 | 示例 |
---|---|---|---|---|
appId | NSString | 是 | 创建项目后 DT 后台分配的 app_id,如没有创建项目权限需联系公司超级管理员角色或 DT 工作人员 | dt_test |
serverUrl | NSString | 是 | 数据上报地址,创建项目后 DT 后台自动分配,请在【项目设置-项目详情】中获取 | https://xxx.roiquery.com |
channel | DTChannel | 是 | 渠道,打多渠道包时需要用到,可使用 SDK 内部提供的实现 | DTChannelAppStore |
isDebug | BOOL | 是 | 是否打开调试,调试模式下将打印 log, 默认为 false;log 标签为 DataTower | true/false |
logLevel | DTLoggingLevel | 是 | log 的级别,仅在 isDebug = true 有效 | DTLoggingLevelDebug、DTLoggingLevelInfo、DTLoggingLevelError |
enableTrack | BOOL | 是 | 是否上报到服务器,一般填Yes,如果需要先传入公共属性,填No,待设置完相应属性后,需调用setEnableTracking开启上传,标志未开启前,数据不会上报到后台 | Yes/No |
@import DataTowerAICore;
// 在程序入口调用
[DT initSDK:@"appid" serverUrl:@"serverUrl" channel:DTChannelAppStore isDebug:YES logLevel:DTLoggingLevelDebug enableTrack:YES];
可以在用户每一次登录时,调用 setAccountId
设置用户的账号 ID, DT 系统将会以账号 ID 作为身份识别 ID,多次调用 setAccountId
将覆盖先前的账号 ID
若您的应用没有账号体系可以不设置
+ (void)setAccountId:(NSString *)accountId
参数名 | 类型 | 是否必传 | 说明 |
---|---|---|---|
id | NSString | 是 | 自有用户系统的 id |
[DTAnalytics setAccountId:@"123456"];
获取由 SDK 生成的设备标识 DT ID。
+ (NSString *)getDataTowerId
NSString *dtId = [DTAnalytics getDataTowerId]
调用 trackEventName
设置自动上报的埋点事件和事件属性
+ (void)trackEventName:(NSString *)eventName properties:(NSDictionary *)properties
参数名 | 类型 | 是否必传 | 说明 |
---|---|---|---|
eventName | NSString | 是 | 事件名称 |
properties | NSDictionary | 否 | 自定义事件属性 |
NSDictionary *eventProperties = @{ @"product_name": @"商品名"};
[DTAnalytics trackEventName:@"product_buy" properties:eventProperties];
// or 不传属性
[DTAnalytics trackEventName:@"dt_track_simple"]
DT 系统支持的用户属性设置类型总览说明如下
操作 | 对应事件名 | 处理规则 |
---|---|---|
覆盖用户属性 | #user_set |
对用户表进行操作,覆盖用户的原有属性值,如果之前不存在该用户属性,则会新建该用户属性,类型与覆盖操作传入属性的类型一致 |
初始化用户属性 | #user_set_once |
对用户表进行操作,初始化用户属性,如果该属性已有值存在,系统忽略本次操作 |
累加用户属性 | #user_add |
对用户表进行操作,对数值型的用户属性做累加计算,如果该属性还未被设置,则会赋值 0 后再进行计算,可传入负值等同于相减操作 |
清空用户属性值 | #user_unset |
对用户表进行操作,清空用户属性的属性值,即设置成 NULL,如果被清空的属性不存在也不会新建该属性 |
追加列表型用户属性的元素 | #user_append |
对用户表进行操作,对列表类型的用户属性追加元素,如果被追加的列表属性不存在,系统将自动生成并进行追加 |
追加并去重列表类型用户属性的元素 | #user_uniq_append |
对用户表进行操作,对列表类型的用户属性值追加元素,并会进行一次全列表去重(去重保证前后原有的元素顺序不变),如果被追加的列表属性不存在,系统将自动生成并进行追加再去重 |
对于一般的用户属性,您可以调用 userSet
来进行设置,使用该接口上传的属性将会覆盖原有的属性值,如果之前不存在该用户属性,则会新建该用户属性,类型与覆盖操作传入属性的类型一致
+ (void)userSet:(NSDictionary *)properties
参数名 | 类型 | 是否必传 | 说明 |
---|---|---|---|
properties | NSDictionary | 是 | 事件属性 |
// 设置用户属性
[DTAnalytics userSet:@{@"username": @"dt_name"}];
// 此时"username"为"dt_name"
[DTAnalytics userSet:@{@"username": @"dt_name2"}];
// 此时"username"为"dt_name2"
如果您要上传的用户属性只要设置一次,则可以调用 userSetOnce
来进行设置,当该属性之前已经有值的时候,将会忽略这条信息
+ (void)userSetOnce:(NSDictionary *)properties
参数名 | 类型 | 是否必传 | 说明 |
---|---|---|---|
properties | NSDictionary | 是 | 事件属性 |
// 设置用户属性
[DTAnalytics userSetOnce:@{@"username": @"dt_name"}];
// 假设"username"从来没被设置过,此时"username"为"dt_name"
[DTAnalytics userSet:@{@"username": @"dt_name2"}];
// 此时"username"仍为"dt_name"
[DTAnalytics userSetOnce:@{@"username": @"dt_name3"}];
// 此时"username"为"dt_name"
当您要上传数值型的属性时,您可以调用 userAdd
来对该属性进行累加操作,如果该属性还未被设置,则会赋值 0 后再进行计算,可传入负值,等同于相减操作
+ (void)userAdd:(NSDictionary *)properties
参数名 | 类型 | 是否必传 | 说明 |
---|---|---|---|
properties | NSDictionary | 是 | 事件属性 设置的属性 key 为字符串,Value 只允许为数值,否则操作不生效 |
// 设置用户属性
[DTAnalytics userAdd:@{@"usermoney": [NSNumber numberWithInt:6]}];
// 此时"usermoney"为 6
[DTAnalytics userAdd:@{@"usermoney": [NSNumber numberWithInt:6]}];
// 此时"usermoney"为 12
当您要清空用户的用户属性值时,您可以调用 userUnset
来对指定属性进行清空操作,如果该属性还未创建,则 userUnset
不会创建该属性
+ (void)userUnset:(NSString *)propertyName
参数名 | 类型 | 是否必传 | 说明 |
---|---|---|---|
propertyName | NSString | 是 | 用户属性名称 |
// 清空用户属性
[DTAnalytics userUnset:@"key1"];
user_delete
将这名用户删除,您将无法再查询该名用户的用户属性,但该用户产生的事件仍然可以被查询到。+ (void)userDelete
userAppend
对列表类型的用户数据追加元素。+ (void)userAppend:(NSDictionary<NSString *, NSArray *> *)properties
参数名 | 类型 | 是否必传 | 说明 |
---|---|---|---|
properties | NSDictionary | 是 | 用户属性名称集 |
NSArray *course = @[@"History",@"Now"];
NSDictionary *userAppendProperties = @{
@"course":course,
};
[DTAnalytics userAppend:userAppendProperties];
userUniqAppend
对列表类型的用户数据追加唯一元素。调用 userUniqAppend
接口会对追加的用户属性进行去重, userAppend
接口不做去重,用户属性可存在重复。+ (void)userUniqAppend:(NSDictionary<NSString *, NSArray *> *)properties
参数名 | 类型 | 是否必传 | 说明 |
---|---|---|---|
properties | NSDictionary | 是 | 用户属性名称集 |
// 此时user_list的属性值为["apple","ball"]
[DTAnalytics userAppend:@{@"user_list":@[@"apple", @"ball"]}];
// 此时user_list的属性值为["apple","apple","ball","cube"]
[DTAnalytics userAppend:@{@"user_list":@[@"apple", @"cube"]}];
// 此时user_list的属性值为["apple","ball","cube"]
[DTAnalytics userUniqAppend:@{@"user_list":@[@"apple", @"cube"]}];
DT 平台处理数据时,需要获取 IOS 支付平台原始订单 ID,以此作为关联 Apple 支付用户的标识。请在使用支付相关的事件上报时,务必调用此方法。
+ (void)setIasOriginalOrderId:(NSString *)oorderId;
参数名 | 类型 | 是否必传 | 说明 |
---|---|---|---|
orderId | NSString | 是 | Apple 支付原始订单 ID |
[DTAnalytics setIasOriginalOrderId:@"123434"]
事件名称 | 显示名 | 事件描述 |
---|---|---|
#ad_load_begin | 广告加载开始 | 广告加载开始 |
#ad_load_end | 广告加载结束 | 广告加载结束 |
#ad_to_show | 广告预展示 | 将要展示广告 |
#ad_show | 广告展示 | 参与广告收益计算的重要事件;在广告展示时上报 |
#ad_show_failed | 广告展示失败 | 广告展示失败 |
#ad_close | 广告关闭 | 广告已经关闭 |
#ad_click | 广告点击 | 参与广告收益计算的重要事件;在广告点击时上报 |
#ad_rewarded | 广告获得奖励 | 只针对激励广告获得奖励 |
#ad_conversion | 广告收益 | 参与广告收益计算的重要事件;在用户获得广告奖励后上报 |
#ad_paid | 广告展示价值 | 广告平台给每个广告的预估价值 |
// 上报广告开始加载事件
+ (void) reportLoadBegin:(NSString *)adid
type:(DTAdType)type
platform:(DTAdPlatform)platform
seq:(NSString *)seq
properties:(NSDictionary *)properties;
// 上报广告结束加载事件
+ (void) reportLoadEnd:(NSString *)adid
type:(DTAdType)type
platform:(DTAdPlatform)platform
duration:(NSNumber *)duration
result:(BOOL)result
seq:(NSString *)seq
errorCode:(NSInteger)errorCode
errorMessage:(NSString *)errorMessage
properties:(NSDictionary *)properties;
// 上报广告预展示事件,在想展示广告之前调用
+ (void) reportToShow:(NSString *)adid
type:(DTAdType)type
platform:(DTAdPlatform)platform
location:(NSString *)location
seq:(NSString *)seq
properties:(NSDictionary *)properties
entrance:(NSString *)entrance;
// 上报广告展示事件,在展示广告时调用
+ (void) reportShow:(NSString *)adid
type:(DTAdType)type
platform:(DTAdPlatform)platform
location:(NSString *)location
seq:(NSString *)seq
properties:(NSDictionary *)properties
entrance:(NSString *)entrance;
// 上报广告展示失败事件,在展示广告失败时调用
+ (void) reportAdShowFail:(NSString *)adid
type:(DTAdType)type
platform:(DTAdPlatform)platform
location:(NSString *)location
seq:(NSString *)seq
errorCode:(NSInteger)errorCode
errorMessage:(NSString *)errorMessage
properties:(NSDictionary *)properties
entrance:(NSString *)entrance;
// 上报广告关闭事件,在广告被关闭时调用
+ (void) reportClose:(NSString *)adid
type:(DTAdType)type
platform:(DTAdPlatform)platform
location:(NSString *)location
seq:(NSString *)seq
properties:(NSDictionary *)properties
entrance:(NSString *)entrance;
// 上报广告点击事件,在广告被点击时调用
+ (void) reportClick:(NSString *)adid
type:(DTAdType)type
platform:(DTAdPlatform)platform
location:(NSString *)location
seq:(NSString *)seq
mediation:(DTAdMediation)mediation
mediationId:(NSString *)mediationId
properties:(NSDictionary *)properties
entrance:(NSString *)entrance)
// 上报广告获得奖励事件,在激励广告获取奖励后调用
+ (void) reportClick:(NSString *)adid
type:(DTAdType)type
platform:(DTAdPlatform)platform
location:(NSString *)location
seq:(NSString *)seq
properties:(NSDictionary *)properties
entrance:(NSString *)entrance;
// 上报广告收益转化事件,在点击广告时调用(#ad_conversion_source = by_click)
+ (void) reportConversionByClick:(NSString *)adid
type:(DTAdType)type
platform:(DTAdPlatform)platform
location:(NSString *)location
seq:(NSString *)seq
properties:(NSDictionary *)properties
entrance:(NSString *)entrance;
// 上报广告收益转化事件,在获得广告激励时调用(#ad_conversion_source = by_rewarded)
+ (void) reportConversionByRewarded:(NSString *)adid
type:(DTAdType)type
platform:(DTAdPlatform)platform
location:(NSString *)location
seq:(NSString *)seq
properties:(NSDictionary *)properties
entrance:(NSString *)entrance;
// 上报广告收益转化事件,在点击广告后跳出App时调用(#ad_conversion_source = by_left_app)
+ (void) reportConversionByLeftApp:(NSString *)adid
type:(DTAdType)type
platform:(DTAdPlatform)platform
location:(NSString *)location
seq:(NSString *)seq
properties:(NSDictionary *)properties
entrance:(NSString *)entrance;
// 上报广告展示价值事件,在广告SDK回调时调用
+ (void) reportPaid:(NSString *)adid
type:(DTAdType)type
platform:(DTAdPlatform)platform
location:(NSString *)location
seq:(NSString *)seq
value:(NSString *)value
currency:(NSString *)currency
precision:(NSString *)precision
properties:(NSDictionary *)properties
entrance:(NSString *)entrance;
+ (void) reportPaid:(NSString *)adid
type:(DTAdType)type
platform:(DTAdPlatform)platform
location:(NSString *)location
seq:(NSString *)seq
mediation:(DTAdMediation)mediation
mediationId:(NSString *)mediationId
value:(NSString *)value
precision:(NSString *)precision
country:(NSString *)country
properties:(NSDictionary *)properties
entrance:(NSString *)entrance;
// 上报离开app事件,在点击广告链接,离开当前app(页面)时调用
+ (void) reportLeftApp:(NSString *)adid
type:(DTAdType)type
platform:(DTAdPlatform)platform
location:(NSString *)location
seq:(NSString *)seq
properties:(NSDictionary *)properties
entrance:(NSString *)entrance;
// 上报返回app事件,在访问广告链接,回到当前app(页面)时调用
+ (void) reportReturnApp:(NSString *)adid
type:(DTAdType)type
platform:(DTAdPlatform)platform
location:(NSString *)location
clickGap:(NSNumber *)clickGap
returnGap:(NSNumber *)returnGap
seq:(NSString *)seq
properties:(NSDictionary *)properties
entrance:(NSString *)entrance;
参数名 | 类型 | 是否必传 | 说明 |
---|---|---|---|
seq | String | 是 | 广告系列事件的标识 |
id | String | 是 | Network 广告单元 ID |
type | DTAdType | 是 | 详见 类型 Type |
platform | DTAdPlatform | 是 | 详见 广告平台 Platform |
entrance | String | 否 | 广告展示入口 |
result | Boolean | 是 | 广告加载结果,true 为广告加载成功 |
duration | Long | 是 | 广告加载时长 |
location | String | 是 | 广告位置,通常为在广告平台配置的位置值 |
errorCode | Int | 否 | 失败码,值为应用接入的对应的广告平台给出的错误码 |
errorMessage | String | 否 | 失败信息,应用接入的对应的广告平台给出的错误信息 |
value | String | 是 | 广告价值,应用接入的对应的广告平台给出的广告价值信息 |
currency | String | 是 | 广告价值对应的货币单位,请传入 USD |
precision | String | 是 | 精确度,广告价值所对应的精确度 |
country | String | 是 | 广告展示所在的国家/地区信息 |
mediation | DTAdMediation | 是 | 详见 聚合广告平台 Mediation |
mediationId | String | 是 | 聚合平台广告单元 ID |
properties | NSDictionary<String, Any> | 否 | 应用自定义的额外属性 |
场景一:独立广告平台
@import DataTowerAICore;
@import GoogleMobileAds;
@import UIKit;
@interface ViewController () <GADFullScreenContentDelegate>
@property(nonatomic, strong) GADInterstitialAd *interstitial;
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
// 广告位,比如这页面是主页
NSString *location = @"main";
// Admob 广告单元
NSString *adUnit = @"ca-app-pub-3940256099942544/1033173712";
// 整个过程的行为系列标识
NSString *seq = [NSUUID UUID].UUIDString;
GADRequest *request = [GADRequest request];
[GADInterstitialAd loadWithAdUnitID:adUnit
request:request
completionHandler:^(GADInterstitialAd *ad, NSError *error) {
}];
- (IBAction)showad:(id)sender {
if (self.interstitial) {
[self.interstitial presentFromRootViewController:self];
} else {
NSLog(@"Ad wasn't ready");
}
}
// 展示失败的回调
- (void)ad:(nonnull id<GADFullScreenPresentingAd>)ad
didFailToPresentFullScreenContentWithError:(nonnull NSError *)error {
}
// 关闭的回调
- (void)adDidDismissFullScreenContent:(nonnull id<GADFullScreenPresentingAd>)ad {
NSLog(@"Ad did dismiss full screen content.");
}
// 点击的回调(如果有的话)
- (void)adClicked{
// 上报广告转化
[DTAdReport reportConversionByClick:adUnit type:DTAdTypeInterstitial
platform:DTAdPlatformAdmob location:location seq:seq properties:@{} entrance:@""];
}
}
对于激励广告,会有获得激励回调
// 获得激励的回调(对于激励广告)
- (void)adRewarded{
// 上报广告转化
[DTAdReport reportConversionByRewarded:adUnit type:DTAdTypeInterstitial
platform:DTAdPlatformAdmob location:location seq:seq properties:@{} entrance:@""];
}
场景二:聚合广告平台(Mediation)
由于聚合广告平台展示广告的时候,通常没有返回具体是哪个广告平台(Network)的广告和对应信息,所以需要在回调中判断,如 onAdShowed 回调
_/// 展示的回调
- (void)adWillPresentFullScreenContent:(nonnull id<GADFullScreenPresentingAd>)ad {
NSLog(@"Ad will present full screen content.");
// 上报展示
[DTAdReport reportShow:adUnit type:DTAdTypeInterstitial platform:DTAdPlatformAdmob location:location seq:seq properties:@{} entrance:@""];
__}_
其他回调类似
如果你的产品具备内购变现(IAP)功能,DT SDK 已经预置了一些常用的事件接口。在产品的内购变现相关场景中,你可以调用相应的接口。一旦调用了这些接口成功,您可以在我们的后台实时查看内购变现全链路的表现数据。
// 上报购买成功事件,购买成功的时候上报
+ (void)reportPurchased:(NSString *)order
sku:(NSString *)sku
price:(NSNumber *)price
currency:(NSString *)currency
seq:(NSString *)seq
placement:(NSString *)placement;
参数名 | 类型 | 是否必传 | 说明 |
---|---|---|---|
seq | NSString | 是 | 购买行为系列事件的标识 |
placement | NSString | 是 | 购买行为发生所在的位置,可为空 |
currency | NSString | 是 | 购买所用的货币单位,与 price 共同决定购买所需的价格 |
price | NSNumber | 是 | 购买所需的价格 |
sku | NSString | 是 | 购买商品 id |
order | NSString | 是 | 购买订单 |
如果你的产品具备内购变现(IAS)功能,DT SDK 已经预置了一些常用的事件接口。在产品的订阅变现相关场景中,你可以调用相应的接口。一旦调用了这些接口成功,您可以在我们的后台实时查看订阅变现全链路的表现数据。
// 订阅成功事件上报,订阅成功时上报
+ (void)reportSubscribeSuccess:(NSString *)seq
entrance:(NSString *)entrance
placement:(NSString *)placement
sku:(NSString *)sku
orderId:(NSString *)orderId
originalOrderId:(NSString *)originalOrderId
price:(NSString *)price
currency:(NSString *)currency
properties:(NSDictionary *)properties;
参数名 | 类型 | 是否必传 | 说明 |
---|---|---|---|
seq | NSString | 是 | 订阅行为系列事件的标识 |
entrance | NSString | 是 | 订阅行为入口 |
placement | NSString | 是 | 订阅行为发生所在的位置 |
currency | NSString | 是 | 订阅所用的货币单位,与 price 共同决定订阅所需的价格 |
price | NSString | 是 | 订阅所需的价格 |
sku | NSString | 是 | 订阅商品 id |
orderId | NSString | 是 | 订阅订单 |
originalOrderId | NSString | 是 | 订阅原始订单 id |
properties | NSDictionary | 是 | 自定义属性 |
如果您需将三方数据同步至 DT 平台,请在三方 SDK 初始化之前调用获取 dt_id 的方法,然后按照 DT 集成各平台的操作文档传入三方平台的对应参数
NSString *dtId = [DTAnalytics getDataTowerId];
如果您需将 DT 数据从服务端发送至三方平台,请初始化三方 SDK 之后获取三方设备 ID,然后使用 DT SDK 进行数据上报
// 需先获取对应 id
// Firebase
[DTAnalytics setFirebaseAppInstanceId:""];
// AppsFlyer
[DTAnalytics setAppsFlyerId:@""];
// Adjust
[DTAnalytics setAdjustId:@""];
// Kochava
[DTAnalytics setKochavaId:@""];
// Tenjin
[DTAnalytics setTenjinId:@""];
调用接口 | 对应三方平台 | 公共事件属性 | 用户属性 |
---|---|---|---|
setFirebaseAppInstanceId() | Firebase | #firebase_iid | #latest_firebase_iid |
setAppsFlyerId() | AppsFlyer | #appsflyer_id | #latest_appsflyer_id |
setAdjustId() | Adjust | #adjust_id | #latest_adjust_id |
setKochavaId() | Kochava | #kochava_id | #latest_kochava_id |
setTenjinId() | Tenjin | #tenjin_id | #latest_tenjin_id |
如果您需要记录某个事件的持续时长,可以调用 DTAnalyticsUtils
来开始计时。
在事件开始时,调用 trackTimerStart
并不会真正发送事件;在事件结束时调用 trackTimerEnd
,SDK 会上报 "event" 事件,并自动在"event" 事件属性中加入 #duration
这一属性来表示记录的事件持续时长。多次调用 trackTimerStart
\ trackTimerPause
时,事件 "event" 的开始时间\暂停时间以最后一次调用时为准。多次调用 trackTimerEnd
\ trackTimerResume
时,事件 "event" 的结束时间\恢复时间以最先一次调用时为准。
// 开始事件计时
[DTAnalyticsUtils trackTimerStart@"event"]
// 如果需要暂停事件计时
[DTAnalyticsUtils trackTimerPause@"event"]
// 如果需要恢事件计时
[DTAnalyticsUtils trackTimerResume@"event"]
// 结束事件计时
[DTAnalyticsUtils trackTimerEnd@"event"]