• SDK版本：当前SDK版本在不断迭代发布中，您可前往Git开源页面查看各端的SDK版本情况，推荐使用最新版本SDK。本文中的代码示例以一个版本号作为示例，您实际使用时，需根据使用的实际SDK版本修改其中的版本号。
• 下载SDK包：集成SDK时，如果您需要手动引入SDK，需前往Git开源页面下载对应版本的SDK包。

1. 请前往macOS SDK包下载页面获取对应版本的SDK包。

   说明

   macOS离线包名称为*版本号-xxxx-macOS*.zip格式。例如：6.9.0-alpha.4-macOS.zip，其中6.9.0为SDK版本号。

2. 将安装包下的文件复制到项目文件夹下，并在XCode中依次添加到项目中。添加依赖：

• libz.tbd

• libsqlite3.tbd

• CoreGraphics.framework

• CoreFoundation.framework

• Foundation.framework

• Security.framework

• AppKit.framework

• WebKit.framework

• SystemConfiguration.framework (判断网络状态)
  同时需要添加编译项 other linker flags，如下图：

  • -ObjC

    

  • 或者-force_load $(PROJECT_DIR)/yourpath/RangersAppLog.framework/Versions/A/RangersAppLog
    在 Build Phases-> Link Binary With Libraries 中添加 RangersAppLog-6.9.2.xcframework 和 VolcEngineEncryptor.xcframework

    

  如果项目无法访问网络，则给项目的配置添加（即 entitlements 文件）：

  <plist version="1.0">
  <dict>
  ...
  <key>com.apple.security.network.client</key>
  <true/>
  ...
  </dict>
  </plist>
  

获取appid

在开始集成前，首先需要先接入一个应用，并获取应用的appid。操作详情请参见快速入门：管理员（SaaS-云原生版）。

获取数据上报地址（仅私有化）

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

初始化SDK

如您使用私有化部署版本，请参照如下代码初始化SDK。

#import <RangersAppLog/BDAutoTrack.h>
#import <RangersAppLog/BDAutoTrackConfig.h>
#import <RangersAppLog/BDAutoTrackURLHostItemCN.h>
#import <RangersAppLog/RangersAppLog.h>

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
 /* 初始化SDK开始 */
 // 参数APPID: 参考上述章节获取
 BDAutoTrackConfig*config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:nil];
 // 设置渠道，iOS一般默认App Store渠道
 config.channel = @"App Store"; 
 
 // 设置私有化部署数据上送地址，参考上述章节获取，{{REPORT_URL}} 例如 https://yourdomain.com，注意域名后不要加“/”
 config.serviceVendor = BDAutoTrackServiceVendorPrivate;
 BDAutoTrackRequestHostBlock block =
 ^NSString *(BDAutoTrackServiceVendor vendor, BDAutoTrackRequestURLType requestURLType) {
 return @"{{REPORT_URL}}";
 };
 [BDAutoTrack setRequestHostBlock:block];
 
 config.showDebugLog = NO; // YES:开启日志，需要参考4.3设置Logger，NO:关闭日志
 config.logNeedEncrypt = YES; // 加密开关，YES开启，NO关闭
 [BDAutoTrack startTrackWithConfig:config];
 /* 初始化SDK结束 */ 
}

登录态变化调用

3.1.1 账户登录

如您的产品中有账户体系，请在用户登录后立即设置uuid，以保证用户登录前后口径一致性。

• Objective-C请参考

  #import <RangersAppLog/RangersAppLog.h>
  // 设置您账号体系的ID, 并保证其唯一性
  [BDAutoTrack setCurrentUserUniqueID:@"{{USER_UNIQUE_ID}}"];
  

• Swift请参考

  BDAutoTrack.setCurrentUserUniqueID("{{USER_UNIQUE_ID}}")
  

如您在初始化SDK时，已获取到可设置的uuid，例如已登录的用户，请在初始化时调用设置。初始化后无需再次调用重复设置。

• Objective-C请参考

  // 初始化时设置uuid
  config.initialUserUniqueID = @"{{USER_UNIQUE_ID}}";
  

• Swift请参考

  // 初始化时设置uuid
  config.initialUserUniqueID = "{{USER_UNIQUE_ID}}"
  

3.1.2 账户登出

在账户登出时调用。

• Objective-C请参考

  [BDAutoTrack clearUserUniqueID];
  

• Swift请参考

  BDAutoTrack.clearUserUniqueID();
  

3.2 设置用户属性

3.2.1 profileSet

设置用户属性，存在则覆盖，不存在则创建。

• Objective-C请参考

  // 示例：设置用户属性，属性名为key，属性值为value
  NSDictionary *profileDict = @{@"key": @("value")};
  [BDAutoTrack profileSet:profileDict];
  

• Swift请参考

  // 示例：设置用户属性，属性名为key，属性值为value
  let profileDict: [AnyHashable: Any] = [
   "key": "value"
  ]
  BDAutoTrack.profileSet(profileDict)
  

3.2.2 profileSetOnce

设置用户属性，存在则不设置，不存在则创建，适合首次相关的用户属性，比如首次访问时间等。

• Objective-C请参考

  // 示例：设置用户属性，属性名为key_once，属性值为value_once
  NSDictionary *profileDict = @{@"key_once": @("value_once")};
  [BDAutoTrack profileSetOnce:profileDict];
  

• Swift请参考

  // 示例：设置用户属性，属性名为key_once，属性值为value_once
  let profileDict: [AnyHashable: Any] = [
   "key_once": "value_once"
  ]
  BDAutoTrack.profileSetOnce(profileDict)
  

3.2.3 profileIncrement

设置数值类型的属性，可进行累加。

• Objective-C请参考

  // 示例：设置用户属性，属性名为key，属性值为1
  [BDAutoTrack profileIncrement:@{@"key": @(1)}];
  

• Swift请参考

  // 示例：设置用户属性，属性名为key，属性值为1
  let profileDict: [AnyHashable: Number] = [
   "key": 1
  ]
  BDAutoTrack.profileIncrement(profileDict)
  

3.2.4 profileAppend

设置List类型的用户属性，可持续向List内添加。

• Objective-C请参考

  // 示例：设置用户属性，属性名为key，原本已有属性值，现添加属性值为value_append
  [BDAutoTrack profileAppend:@{
   @"key": @[@"value_append"]
  }];
  

• Swift请参考

  // 示例：设置用户属性，属性名为key，原本已有属性值，现添加属性值为value_append
  BDAutoTrack.profileAppend([["key"]:["value_append"]])
  

3.2.5 profileUnset

删除用户的属性。

• Objective-C请参考

  // 示例：删除用户属性，属性名为key
  [BDAutoTrack profileUnset:@"key"];
  

• Swift请参考

  // 示例：删除用户属性，属性名为key
  BDAutoTrack.profileUnset("key")
  

4.1 上报代码埋点

用户行为日志采用事件event+属性params的形式，事件一般对应多个属性，也可以仅有事件没有属性。代码埋点方案一般由数据分析师或产品运营设计。
仅上报事件的代码埋点，示例如下：

• Objective-C请参考

  // 示例：上报事件event，该事件不包含属性
  // 置于业务逻辑对应位置
  [BDAutoTrack eventV3:@"event" params: NULL];
  

• Swift请参考

  // 示例：上报事件event，该事件不包含属性
  // 置于业务逻辑对应位置
  BDAutoTrack.eventV3("event", params: nil)
  

上报事件和对应属性的代码埋点，示例如下：

• Objective-C请参考

  // 示例：上报事件event，该事件包含两个属性
  // 一个string类型的属性，属性名为key_string，属性值为value_string
  //. 一个int类型的属性，属性名为key_int，属性值为10
  // 置于业务逻辑对应位置
  [BDAutoTrack eventV3:@"event" 
   params:@{@"key_string":@"value_string",
   @"key_int": @(10)}];
  

• Swift请参考

  // 示例：上报事件event，该事件包含两个属性
  // 一个string类型的属性，属性名为key_string，属性值为value_string
  //. 一个int类型的属性，属性名为key_int，属性值为10
  // 置于业务逻辑对应位置
  BDAutoTrack.eventV3("event", params: ["key_string": "value_string",
   "key_int": 10])
  

4.2 事件公共属性

如需在每个事件中都包括某属性，可通过公共属性设置，无需在每个事件中重复设置。公共属性只需设置一次，即可包括在所有代码埋点事件、预置事件和全埋点事件中。

4.2.1 设置公共属性

• Objective-C请参考

  /* 
   * 示例：设置自定义的公共属性，属性名为key_public，属性值为value_public
   * 关于自定义 “公共属性” 请注意：
   * 1. 上报机制是随着每一次日志发送进行提交，默认的日志发送频率是1分钟，
   *    所以如果在一分钟内连续修改自定义公共属性，按照日志发送前的最后一次修改为准； 
   * 2. 不推荐高频次修改，如每秒修改一次。
   */
  [BDAutoTrack setCustomHeaderValue:@"value_public" forKey:@"key_public"];
  

• Swift请参考

  /* 
   * 示例：设置自定义的公共属性，属性名为key_public，属性值为value_public
   * 关于自定义 “公共属性” 请注意：
   * 1. 上报机制是随着每一次日志发送进行提交，默认的日志发送频率是1分钟，
   *    所以如果在一分钟内连续修改自定义公共属性，按照日志发送前的最后一次修改为准； 
   * 2. 不推荐高频次修改，如每秒修改一次。
   */
  BDAutoTrack.setCustomHeaderValue { () -> [String : Any] in
   return ["key_public":"value_public"]
  }
  

4.2.2 移除公共属性

• Objective-C请参考

  // 示例：移除属性名为key_public的公共属性
  [BDAutoTrack removeCustomHeaderValueForKey:@"key_public"];
  

• Swift请参考

  // 示例：移除属性名为key_public的公共属性
  BDAutoTrack.removeCustomHeaderValueForKey("key_public");