iOS SDK集成

1.1 使用CocoaPods引入source源 #

在Podfile中，添加source源。

source 'https://github.com/volcengine/volcengine-specs.git'

1.2 引入SDK #

在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节
    ]

1.3 引入调试工具 - DevTools组件(可选) #

6.12.0+ 支持
开发调试阶段集成，请勿带入线上环境。

DevTools是辅助开发者或测试人员进行应用内埋点验证和SDK接入问题排查的组件。

1. SDK subspecs 添加 DevTools

   pod 'RangersAppLog', 'SDK-VERSION', 
       :subspecs => [
           ...
           'DevTools', 
           ...
       ]
   

2. 开启相关功能

   #import <RangersAppLog/BDAutoTrackDevTools.h>
   // 配置开启DevTool功能
   config.devToolsEnabled = YES;
   
   // 在 BDAutoTrack 初始化之后添加方法 显示悬浮按钮入口
   [BDAutoTrackDevTools showFloatingEntryButton];
   

详细接入文档请查阅iOS埋点开发工具。

1.4 实时埋点检测和圈选功能(可选) #

如需使用实时埋点检测或圈选功能，请引入Log子库，否则可跳过此步骤。
请注意，除引入子库外，您还需要完成下文3.配置Scheme的步骤。

1.5 反作弊风控子库(可选) #

如需使用广告监测功能，为使其反作弊识别准确度更高，请额外引入VolMetaSecML风控子库，否则可跳过此步骤。

1.6 手动引入须知 #

推荐您通过CocoaPods引入SDK。如特殊情况需要手动引入，请阅读本小节。

将安装包下的文件复制到项目文件夹下，并在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

2.1 获取appid #

在开始集成前，首先需要在集团中拥有一个应用，请参考如何创建应用。
「应用列表」-> 接入应用的「详情」->「应用ID」中可查看您的appid。

2.2 获取数据上送地址 #

私有化部署版本需要获取数据上送地址。
如您不清楚此地址，请联系您的项目经理或客户成功经理。

2.3 初始化SDK #

2.3.1 SaaS版本 #

如您使用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
      }
  

2.3.2 私有化版本 #

如您使用私有化部署版本，请参照如下代码初始化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
      }
  

2.3.3 SaaS云原生版本 #

如您使用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
      }
  

2.4 多实例初始化(可选) #

多实例初始化，指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，否则可跳过此步骤。

3.1 获取URL Scheme #

「应用列表」-> 接入应用的「详情」->「URL Scheme」中可查看您的scheme，一般为rangersapplog.xxxxx的形式。

3.2 添加URL Scheme #

把URL Scheme添加到您的项目中。

3.3 重写回调方法 #

请根据需要使用实时埋点检测或圈选事件功能的设备版本，并添加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。

4.1 全埋点设置开关 #

• Objecetive-C请参考：

  // 开启全埋点事件的上送
  config.autoTrackEnabled = YES; // 全埋点开关，YES开启，NO关闭
  

• Swift请参考：

  // 开启全埋点事件的上送
  config.autoTrackEnabled = true // 全埋点开关，true开启，false关闭
  

4.2 开启圈选埋点 #

在1.2节的引入中，引入Picker子库即开启圈选埋点。相反，移除Picker子库即关闭圈选埋点。

4.3 查看日志打印 #

• Objecetive-C请参考：

  // 在控制台输出日志，可用于观察用户行为日志上报情况，建议在上线时关闭
  config.showDebugLog = NO; // YES:开启日志，NO:关闭日志
  

• Swift请参考：

  // 在控制台输出日志，可用于观察用户行为日志上报情况，建议在上线时关闭
  config.showDebugLog = false // true:开启日志，false:关闭日志
  

4.4 加密设置开关 #

加密设置默认开启。您可在debug阶段关闭加密，以便于抓包联调。

• Objecetive-C请参考：

  // 加密设置开关，线上版本建议开启
  config.logNeedEncrypt = YES; // YES:打开加密，NO:关闭加密
  

• Swift请参考：

  // 加密设置开关，线上版本建议开启
  config.logNeedEncrypt = true // true:打开加密，false:关闭加密
  

4.4.1 国密 SM2 #

国密 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
  

4.5 设置APP Language 和 APP Region #

• 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")
  

4.6 打通内嵌H5页 #

开启内嵌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.*"]
  

4.7 原生端采集H5全埋点 #

原生端内嵌webview页时，通过打开以下开关，可从原生端全埋点事件采集h5页全埋点事件。

• Objecetive-C请参考：

  //内嵌H5页面的全埋点事件
  config.H5AutoTrackEnabled = YES; // YES:开启h5全埋点事件，NO:关闭h5全埋点事件
  

• Swift请参考：

  //内嵌H5页面的全埋点事件
  config.H5AutoTrackEnabled = true; // true:开启h5全埋点事件，false:关闭h5全埋点事件
  

4.8 关闭设备IDFA采集 #

设备IDFA的采集通过Unique子库完成。在1.2节的引入SDK中，引入Unique子库即开启采集，移除Unique子库即关闭采集。

4.9 开启屏幕方向采集 #

本小节功能在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
  

4.10 设置GPS坐标 #

引入 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)
  

4.11 开启崩溃采集 #

引入 Exception 子库：

pod 'RangersAppLog', 'SDK-VERSION', 
    :subspecs => [
        ...
        'Exception', #崩溃采集
        ...
    ]

• Objective-C 请参考：

  // 目前仅支持采集 NSException 崩溃
  config.trackCrashEnabled = YES;
  

• Swift 请参考：

  // 目前仅支持采集 NSException 崩溃
  config.trackCrashEnabled = true
  

5.1 私有化云控能力 #

注意：本功能仅限私有化V4.4.0以上版本、SDK6.15.0以上版本支持

可以通过私有化服务端下发 SDK 设置，详细介绍文档请查阅：https://www.volcengine.com/docs/6285/196764