更新时间:2023.06.02 17:21:52
在Podfile中,添加source源。
source 'https://github.com/volcengine/volcengine-specs.git'
在Podfile中,引入SDK,并执行pod install --repo-update
更新Pods。
pod 'RangersAppLog', '6.15.1', :subspecs => [ 'Host/CN', #SaaS版本需引入,私有化版本无需引入 'Core', 'UITracker', 'Log', #无需圈选和实时埋点检测可以移除,参考1.3节 'Picker', #无需圈选功能可以移除,参考4.2节 'Unique' #用于在授权后采集IDFA,无需采集可以移除,参考4.8节 ]
6.12.0+ 支持
开发调试阶段集成,请勿带入线上环境。
DevTools
是辅助开发者或测试人员进行应用内埋点验证和SDK接入问题排查的组件。
SDK subspecs 添加 DevTools
pod 'RangersAppLog', 'SDK-VERSION', :subspecs => [ ... 'DevTools', ... ]
开启相关功能
#import <RangersAppLog/BDAutoTrackDevTools.h> // 配置开启DevTool功能 config.devToolsEnabled = YES; // 在 BDAutoTrack 初始化之后添加方法 显示悬浮按钮入口 [BDAutoTrackDevTools showFloatingEntryButton];
详细接入文档请查阅iOS埋点开发工具。
如需使用实时埋点检测或圈选功能,请引入Log
子库,否则可跳过此步骤。
请注意,除引入子库外,您还需要完成下文3.配置Scheme
的步骤。
如需使用广告监测功能,为使其反作弊识别准确度更高,请额外引入VolMetaSecML
风控子库,否则可跳过此步骤。
推荐您通过CocoaPods引入SDK。如特殊情况需要手动引入,请阅读本小节。
iOS SDK下载 | SDK版本 | MD5 |
---|---|---|
增长营销套件SDK下载 | 6.15.1 | ac52763286fc88a2bea3b58a9595446d |
将安装包下的文件复制到项目文件夹下,并在XCode中依次添加到项目中。添加依赖:
libz.tbd
libsqlite3.tbd
CoreGraphics.framework
Security.framework
CoreTelephony.framework (读取运营商名称)
SystemConfiguration.framework (判断网络状态)
JavaScriptCore.framework
WebKit.framework
AdSupport.framework (不使用全埋点或圈选功能就不需要依赖)
AppTrackingTransparency.framework (不集成Unique模块不需要依赖)
设置 Build Settings -> Header Search Paths 添加 Headers 文件夹路径:
设置 Build Settings -> Linking -> Other Linker Flags 添加 -ObjC:
如果需要在已有的SDK离线包中增加 Devtools,请保证 SDK & Devtools 版本匹配的前提下,拷贝如下文件:
RangersAppLog.bundle
libRangersAppLog_DevTools_awesome_ios.a
Headers/BDAutoTrackDevTools.h
说明
SDK会在初始化的时候就采集客户信息,请确保您采集用户信息之前已经得到用户的授权,建议的操作如下:
1. 授权后再初始化SDK,授权前所有的信息都不会采集,但一些预置事件也不会被采集;
2. 正常初始化,可以设置采集不上报,在授权后,设置上报,具体方法参考Applog 初始化后控制数据发送。
在开始集成前,首先需要在集团中拥有一个应用,请参考如何创建应用。
「应用列表」-> 接入应用的「详情」->「应用ID」中可查看您的appid。
私有化部署版本需要获取数据上送地址。
如您不清楚此地址,请联系您的项目经理或客户成功经理。
如您使用SaaS部署版本,请参照如下代码初始化SDK。初始化代码必须在主线程执行。
Objective-C
请参考:
#import <RangersAppLog/BDAutoTrack.h> #import <RangersAppLog/BDAutoTrackConfig.h> #import <RangersAppLog/BDAutoTrackURLHostItemCN.h> - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { /* 初始化SDK开始 */ // 参数APPID: 参考2.1节获取 BDAutoTrackConfig *config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:launchOptions]; // 设置渠道,iOS一般默认App Store渠道 config.channel = @"App Store"; // 设置数据上送地址 config.serviceVendor = BDAutoTrackServiceVendorCN; config.autoTrackEnabled = YES; // 全埋点开关,YES开启,NO关闭 config.showDebugLog = NO; // YES:开启日志,需要参考4.3设置Logger,NO:关闭日志 config.logNeedEncrypt = YES; // 加密开关,YES开启,NO关闭 [BDAutoTrack sharedTrackWithConfig:config]; //SDK初始化 // 如果需要设置当前登陆态 since 6.13.0+ // [[BDAutoTrack sharedTrack] setCurrentUserUniqueID:@"当前登陆态UUID" withType:@"uuid_type"]; [[BDAutoTrack sharedTrack] startTrack]; //SDK启动 /* 初始化SDK结束 */ }
Swift
请参考:
import RangersAppLog func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { /* 初始化SDK开始 */ // 参数APPID: 参考2.1节获取 let config = BDAutoTrackConfig(appID: "{{APPID}}") // 设置渠道,iOS一般默认App Store渠道 config.channel = "App Store" // 设置数据上送地址 config.serviceVendor = BDAutoTrackServiceVendor.CN config.autoTrackEnabled = true // 全埋点开关,true开启,false关闭 config.showDebugLog = false // true:开启日志,需要参考4.3设置Logger,false:关闭日志 config.logNeedEncrypt = true // 加密开关,true开启,false关闭 BDAutoTrack.sharedTrack(with: config) // 如果需要设置当前登陆态 since 6.13.0+ // BDAutoTrack.shared().setCurrentUserUniqueID("uuid", withType: "uuidtype") BDAutoTrack.shared().start() /* 初始化SDK结束 */ return true }
如您使用私有化部署版本,请参照如下代码初始化SDK,初始化代码必须在主线程执行。
Objective-C
请参考:
#import <RangersAppLog/BDAutoTrack.h> #import <RangersAppLog/BDAutoTrackConfig.h> #import <RangersAppLog/BDAutoTrackURLHostItemCN.h> - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { /* 初始化SDK开始 */ // 参数APPID: 参考2.1节获取 BDAutoTrackConfig*config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:launchOptions]; // 设置渠道,iOS一般默认App Store渠道 config.channel = @"App Store"; // 设置私有化部署数据上送地址,参考2.2节获取,{{REPORT_URL}} 例如 https://yourdomain.com,注意域名后不要加“/” config.serviceVendor = BDAutoTrackServiceVendorPrivate; BDAutoTrackRequestHostBlock block = ^NSString *(BDAutoTrackServiceVendor vendor, BDAutoTrackRequestURLType requestURLType) { return @"{{REPORT_URL}}"; }; [BDAutoTrack setRequestHostBlock:block]; config.autoTrackEnabled = YES; // 全埋点开关,YES开启,NO关闭 config.showDebugLog = NO; // YES:开启日志,需要参考4.3设置Logger,NO:关闭日志 config.logNeedEncrypt = YES; // 加密开关,YES开启,NO关闭 [BDAutoTrack sharedTrackWithConfig:config]; //SDK初始化 // 如果需要设置当前登陆态 since 6.13.0+ // [[BDAutoTrack sharedTrack] setCurrentUserUniqueID:@"当前登陆态UUID" withType:@"uuid_type"]; [[BDAutoTrack sharedTrack] startTrack]; //SDK启动 /* 初始化SDK结束 */ }
Swift
请参考:
import RangersAppLog func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { /* 初始化SDK开始 */ // 参数APPID: 参考2.1节获取 let config = BDAutoTrackConfig(appID: "{{APPID}}") // 设置渠道,iOS一般默认App Store渠道 config.channel = "App Store" // 设置私有化部署数据上送地址,参考2.2节获取,{{REPORT_URL}} 例如 https://yourdomain.com,注意域名后不要加“/” BDAutoTrack.setRequestHostBlock {(vendor: BDAutoTrackServiceVendor, requestURLType:BDAutoTrackRequestURLType) -> String? in return "{{REPORT_URL}}" } config.autoTrackEnabled = true // 全埋点开关,true开启,false关闭 config.showDebugLog = false // true:开启日志,需要参考4.3设置Logger,false:关闭日志 config.logNeedEncrypt = true // 加密开关,true开启,false关闭 BDAutoTrack.sharedTrack(with: config) // 如果需要设置当前登陆态 since 6.13.0+ // BDAutoTrack.shared().setCurrentUserUniqueID("uuid", withType: "uuidtype") BDAutoTrack.shared().start() /* 初始化SDK结束 */ return true }
如您使用Saas云原生部署版本,请参照如下代码初始化SDK,初始化代码必须在主线程执行。
Objective-C
请参考:
#import <RangersAppLog/BDAutoTrack.h> #import <RangersAppLog/BDAutoTrackConfig.h> #import <RangersAppLog/BDAutoTrackURLHostItemCN.h> - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { /* 初始化SDK开始 */ // 参数APPID: 参考2.1节获取 BDAutoTrackConfig*config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:launchOptions]; // 设置渠道,iOS一般默认App Store渠道 config.channel = @"App Store"; // 设置数据上送地址 config.serviceVendor = BDAutoTrackServiceVendorPrivate; BDAutoTrackRequestHostBlock block = ^NSString *(BDAutoTrackServiceVendor vendor, BDAutoTrackRequestURLType requestURLType) { return @"https://gator.volces.com"; }; [BDAutoTrack setRequestHostBlock:block]; config.autoTrackEnabled = YES; // 全埋点开关,YES开启,NO关闭 config.showDebugLog = NO; // YES:开启日志,需要参考4.3设置Logger,NO:关闭日志 config.logNeedEncrypt = YES; // 加密开关,YES开启,NO关闭 // 如果需要设置当前登陆态 since 6.13.0+ // [[BDAutoTrack sharedTrack] setCurrentUserUniqueID:@"当前登陆态UUID" withType:@"uuid_type"]; [BDAutoTrack startTrackWithConfig:config]; /* 初始化SDK结束 */
Swift
请参考:
import RangersAppLog func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { /* 初始化SDK开始 */ // 参数APPID: 参考2.1节获取 let config = BDAutoTrackConfig(appID: "{{APPID}}") // 设置渠道,iOS一般默认App Store渠道 config.channel = "App Store" // 设置数据上送地址 BDAutoTrack.setRequestHostBlock {(vendor: BDAutoTrackServiceVendor, requestURLType:BDAutoTrackRequestURLType) -> String? in return "https://gator.volces.com" } config.autoTrackEnabled = true // 全埋点开关,true开启,false关闭 config.showDebugLog = false // true:开启日志,需要参考4.3设置Logger,false:关闭日志 config.logNeedEncrypt = true // 加密开关,true开启,false关闭 // 如果需要设置当前登陆态 since 6.13.0+ // BDAutoTrack.shared().setCurrentUserUniqueID("uuid", withType: "uuidtype") BDAutoTrack.start(with: config) /* 初始化SDK结束 */ return true }
多实例初始化,指SDK支持在同包名的App中向多个应用(多个appid)开启埋点,且埋点数据相互隔离,每一个appid对应一个单独的实例。使用场景例如:
第三方SDK依赖增长营销套件SDK做SDK内部产生的埋点时;
同一个App或系统中,关联多个埋点应用(多个appid),共用增长营销套件SDK时。
Objective-C
请参考:
BDAutoTrackConfig* config1 = [BDAutoTrackConfig configWithAppID:@"{{APPID_1}}" launchOptions:launchOptions]; BDAutoTrack *track1 = [BDAutoTrack trackWithConfig:config1]; [track1 startTrack]; BDAutoTrackConfig* config2 = [BDAutoTrackConfig configWithAppID:@"{{APPID_2}}" launchOptions:launchOptions]; BDAutoTrack *track2 = [BDAutoTrack trackWithConfig:config2]; [track2 startTrack];
Swift
请参考:
let config1 = BDAutoTrackConfig.init(appID: "{{APPID_1}}", launchOptions: launchOptions) let tracker1 = BDAutoTrack.init(config: config1); tracker1!.start() let config2 = BDAutoTrackConfig.init(appID: "{{APPID_2}}", launchOptions: launchOptions) let tracker2 = BDAutoTrack.init(config: config2); tracker2!.start()
如需使用实时埋点检测或圈选事件,请配置Scheme,否则可跳过此步骤。
「应用列表」-> 接入应用的「详情」->「URL Scheme」中可查看您的scheme,一般为rangersapplog.xxxxx
的形式。
把URL Scheme添加到您的项目中。
请根据需要使用实时埋点检测或圈选事件功能的设备版本,并添加URL的处理。
在AppDelegate
回调里面添加 URL 的处理。
#import <RangersAppLog/BDAutoTrackSchemeHandler.h> - (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options { // 参数APPID: 参考2.1节获取 if ([[BDAutoTrackSchemeHandler sharedHandler] handleURL:url appID:@"appid" scene:nil]) { return YES; } // …… return NO; }
在 iOS 13+ 版本中,使用 UISceneSession
需要在 UISceneDelegate
回调方法添加URL的处理。
Objective-C
请参考:
#import <RangersAppLog/BDAutoTrackSchemeHandler.h> - (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts { for (UIOpenURLContext *context in URLContexts) { NSURL *URL = context.URL; // 参数APPID: 参考2.1节获取 if ([[BDAutoTrackSchemeHandler sharedHandler] handleURL:URL appID:@"{{APPID}}" scene:scene]) { continue; } /// …… } }
Swift
请参考:
import RangersAppLog func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool { // 参数APPID: 参考2.1节获取 if(BDAutoTrackSchemeHandler.shared().handle(url, appID: "{{APPID}}", scene: nil)) { return true } return false }
以下为常用的初始化基本配置,config
均指初始化时的BDAutoTrackConfig
。
注意
全埋点开关默认开启。
Objecetive-C
请参考:
// 开启全埋点事件的上送 config.autoTrackEnabled = YES; // 全埋点开关,YES开启,NO关闭
Swift
请参考:
// 开启全埋点事件的上送 config.autoTrackEnabled = true // 全埋点开关,true开启,false关闭
在1.2节的引入中,引入Picker
子库即开启圈选埋点。相反,移除Picker
子库即关闭圈选埋点。
注意
日志打印默认关闭,建议上线生产包关闭。
Objecetive-C
请参考:
// 在控制台输出日志,可用于观察用户行为日志上报情况,建议在上线时关闭 config.showDebugLog = NO; // YES:开启日志,NO:关闭日志
Swift
请参考:
// 在控制台输出日志,可用于观察用户行为日志上报情况,建议在上线时关闭 config.showDebugLog = false // true:开启日志,false:关闭日志
加密设置默认开启。您可在debug阶段关闭加密,以便于抓包联调。
Objecetive-C
请参考:
// 加密设置开关,线上版本建议开启 config.logNeedEncrypt = YES; // YES:打开加密,NO:关闭加密
Swift
请参考:
// 加密设置开关,线上版本建议开启 config.logNeedEncrypt = true // true:打开加密,false:关闭加密
国密 SM2 算法的请求加密仅私有化版本支持,支持的最低版本:6.15.0。
引入国密 SM2子库:
pod 'RangersAppLog', 'SDK-VERSION', :subspecs => [ ... 'Encryptor/SM2', #仅私有化版本支持 ... ]
Objecetive-C
请参考:
#import "BDAutoTrackEncryptorSM2.h" // 设置 SM2 加密 NSString * const publicKey = @"your public key"; [BDAutoTrackEncryptorSM2 setPublickKey:publicKey]; config.encryptionType = BDAutoTrackEncryptionTypeCstcSM2;
Swift
请参考:
// 设置 SM2 加密 let publicKey = "your public key" BDAutoTrackEncryptorSM2.setPublickKey(publicKey) config.encryptionType = .cstcSM2
Objecetive-C
请参考:
// 修改语言和地区,设置APP Language 和 APP Region [BDAutoTrack setAppLauguage:@"zh/en/jp/fr"]; [BDAutoTrack setAppRegion:@"cn"];
Swift
请参考:
// 修改语言和地区,设置APP Language 和 APP Region BDAutoTrack.setAppLauguage("zh/en/jp/fr") BDAutoTrack.setAppRegion("cn")
开启内嵌H5页打通后,内嵌H5页上产生的事件将通过iOS SDK上报,不在js SDK上报,并复用iOS端设置的user_unique_id
和公共属性。
请注意,打通功能还需在H5页上集成js SDK,并开启js的打通开关,请参考 Web/JS SDK 集成 3.4节。
Objecetive-C
请参考:
// 开启内嵌H5打通开关 config.enableH5Bridge = YES;
Swift
请参考:
// 开启内嵌H5打通开关 config.enableH5Bridge = true;
开关开启后,必须配置打通白名单。仅白名单内配置的域名生效打通,白名单可用通配符方式添加,*
表示通配符。
Objective-C
请参考:
// 内嵌H5页白名单配置 // 示例:如需打通 www.volcengine.com 和 www.bytedance.com 两个H5页 config.H5BridgeAllowedDomainPatterns = @[@"www.volcengine.com",@"*.bytedance.*"]; // 适配 www.bytedance.com 的白名单有多种,请根据业务场景配置白名单,例如: // www.bytedance.com 或 *.bytedance.* 或 *.*.* 均可实现。
Swift
请参考:
// 内嵌H5页白名单配置 // 示例:如需打通 www.volcengine.com 和 www.bytedance.com 两个H5页 config.h5BridgeAllowedDomainPatterns = ["www.volcengine.com", "*.bytedance.*"]
原生端内嵌webview页时,通过打开以下开关,可从原生端全埋点事件采集h5页全埋点事件。
注意
此开关的使用无需在h5页内集成js SDK,且与js SDK全埋点功能独立无关联。
Objecetive-C
请参考:
//内嵌H5页面的全埋点事件 config.H5AutoTrackEnabled = YES; // YES:开启h5全埋点事件,NO:关闭h5全埋点事件
Swift
请参考:
//内嵌H5页面的全埋点事件 config.H5AutoTrackEnabled = true; // true:开启h5全埋点事件,false:关闭h5全埋点事件
设备IDFA的采集通过Unique
子库完成。在1.2节的引入SDK中,引入Unique
子库即开启采集,移除Unique
子库即关闭采集。
本小节功能在6.11.0+后开始支持。
引入 DeviceOrientation 子库:
pod 'RangersAppLog', 'SDK-VERSION', :subspecs => [ ... 'DeviceOrientation', #屏幕方向采集 ... ]
屏幕方向信息会自动带入每个埋点的params
中,接口文档如下:
/*! @abstract 是否采集屏幕方向,默认不采集(NO) */ @property (nonatomic) BOOL screenOrientationEnabled;
Objective-C 请参考:
config.screenOrientationEnabled = YES;
Swift 请参考:
config.screenOrientationEnabled = true
引入 Location 子库:
pod 'RangersAppLog', 'SDK-VERSION', :subspecs => [ ... 'Location', #GPS采集 ... ]
GPS 信息会自动带入每个埋点的 params
中:
/*! @abstract 是否采集GPS,默认不采集(NO) */ @property (nonatomic) BOOL trackGPSLocationEnabled;
Objective-C
请参考:
config.trackGPSLocationEnabled = YES;
Swift
请参考:
config.trackGPSLocationEnabled = true
您也可以自行手动设置GPS,手动设置后,SDK将不再使用自动采集的GPS信息:
@interface BDAutoTrack ... + (void)setGPSLocation:(enum BDAutoTrackGeoCoordinateSystem)geoCoordinateSystem longitude:(double)longitude latitude:(double)latitude; ... @end // WGS84 地球坐标系 // GCJ02 火星坐标系 // BD09 百度坐标系 // BDCS 北斗坐标系 typedef NS_ENUM(NSInteger, BDAutoTrackGeoCoordinateSystem) { BDAutoTrackGeoCoordinateSystemWGS84 = 1 << 0, BDAutoTrackGeoCoordinateSystemGCJ02 = 1 << 1, BDAutoTrackGeoCoordinateSystemBD09 = 1 << 2, BDAutoTrackGeoCoordinateSystemBDCS = 1 << 3 };
Objective-C
请参考:
[BDAutoTrack setGPSLocation:BDAutoTrackGeoCoordinateSystemWGS84 longitude:116.3683244 latitude:39.915085];
Swift
请参考:
BDAutoTrack.setGPSLocation(BDAutoTrackGeoCoordinateSystem.WGS84, longitude: 116.3683244, latitude: 39.915085)
引入 Exception 子库:
pod 'RangersAppLog', 'SDK-VERSION', :subspecs => [ ... 'Exception', #崩溃采集 ... ]
Objective-C
请参考:
// 目前仅支持采集 NSException 崩溃 config.trackCrashEnabled = YES;
Swift
请参考:
// 目前仅支持采集 NSException 崩溃 config.trackCrashEnabled = true
注意:本功能仅限私有化V4.4.0以上版本、SDK6.15.0以上版本支持
可以通过私有化服务端下发 SDK 设置,详细介绍文档请查阅:https://www.volcengine.com/docs/6285/196764