You need to enable JavaScript to run this app.
导航
MacOS SDK集成
最近更新时间:2024.05.29 16:21:49首次发布时间:2024.04.29 10:58:47

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

下载并集成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>
    

初始化SDK

获取appid

在开始集成前,首先需要在集团中拥有一个应用,进行SDK集成前,您需要获取对应应用的appid信息。
私有化场景下您可以在「项目中心」->「项目管理」->「项目详情」-> 接入应用的「详情」->「应用ID」中可查看您的appid,详情请参见项目详情与应用列表
图片

获取数据上报地址(仅私有化)

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

初始化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. 事件与事件属性

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