API功能

一、启动配置接口

BonreeSDK启动接口

/// 启动 BonreeSDK
+ (void)startWithAppID:(NSString *)appID;

• 接口说明

• 示例

  Objective-C

    [BRSAgent startWithAppID:@"40766f87-13a8-48d3-9c96-1ce7c3cde50f"];
  

  Swift

    BRSAgent.startWithAppID("40766f87-13a8-48d3-9c96-1ce7c3cde50f")
  

设置Config地址

私有云客户设置私有部署的config地址时使用。公有云客户请勿调用。该接口需要在调用+ startWithAppID:前设置。

/// 设置Config地址（请在BonreeSDK启动之前设置） 默认为公有云地址，无需设置
+ (void)setConfigAddress:(NSString *)configAddress;

• 接口说明

• 示例

  Objective-C

    [BRSAgent setConfigAddress:@"https://sdkupload.bonree.com/config"];
  

  Swift

    BRSAgent.setConfigAddress("https://sdkupload.bonree.com/config")
  

设置App版本

App版本默认在配置文件中获取真实版本号。如有主动配置需求，需要在调用+ startWithAppID:前调用以下接口设置版本信息。

/// 设置app版本（请在BonreeSDK启动之前设置） 默认获取应用CFBundleShortVersionString
+ (void)setAppVersion:(NSString *)appVersion;

• 接口说明

• 示例

  Objective-C

    [BRSAgent setAppVersion:@"3.2.1"];
  

  Swift

    BRSAgent.setAppVersion("3.2.1")
  

设置下载渠道名称

渠道名称默认为apple。如有主动配置需求，需要在调用+ startWithAppID:前调用以下接口设置渠道名称。

/// 设置渠道标识（请在BonreeSDK启动之前设置）
+ (void)setChannelID:(NSString *)channelID;

• 接口说明

• 示例

  Objective-C

    [BRSAgent setChannelID:@"AppStore"];
  

  Swift

    BRSAgent.setChannelID("AppStore")
  

设置自定义的设备ID

设备ID（deviceID）默认由SDK生成并在Keychain中保存。如有主动配置需求，需要在调用+ startWithAppID:前调用以下接口设置设备ID。

/// 配置自定义的设备deviceID（请在BonreeSDK启动之前设置）
+ (void)setDeviceID:(NSString *)deviceID;

• 接口说明

• 示例

  Objective-C

    [BRSAgent setDeviceID:@"0123456789"];
  

  Swift

    BRSAgent.setDeviceID("0123456789")
  

设置持续丢帧时间

设置判定卡顿时需要的持续丢帧时间。需要在调用+ startWithAppID:前调用以下接口设置。

/// 设置持续丢帧监测时间（请在BonreeSDK启动之前设置） 
+ (void)setDropFrameTime:(NSInteger)time;

• 接口说明

• 示例

  Objective-C

    [BRSAgent setDropFrameTime:5];
  

  Swift

    BRSAgent.setDropFrameTime(5)
  

设置mPaaS框架使用状态

阿里mPaaS框架下的数据获取与处理需要特殊配置。如果使用了该框架，请在+ startWithAppID:调用前设置为YES。未使用无需调用设置接口。

/// 是否使用了mPaaS框架（请在BonreeSDK启动之前设置）
+ (void)useMpaas:(BOOL)used;

• 接口说明

• 示例

  Objective-C

    [BRSAgent useMpaas:YES];
  

  Swift

    BRSAgent.useMpaas(true)
  

设置请求头中自定义业务字段

如需获取Http请求头中与业务相关的自定义字段的值，可以将字段以字符串数组形式调用该接口配置给SDK，相关数据会与对应的网络性能数据一同展示，用于客户的业务区分。请在+ startWithAppID:调用该设置接口。

使用场景举例：mPaaS框架下的移动网关功能，请求业务以请求头中的Operation-Type字段区分。设置好该字段即可区分不同的业务请求性能数据。

/// 设置请求头中自定义业务字段
+ (void)setCustomBusinessHeaders:(NSArray<NSString *> *)headerArr;

• 接口说明

• 示例

  Objective-C

    [BRSAgent setCustomBusinessHeaders:@[@"Operation-Type"]];
  

  Swift

    BRSAgent.setCustomBusinessHeaders(["Operation-Type"])
  

自定义冷启动结束时间

如需自定义冷启动的结束时机，可以调用以下两个接口完成自定义功能。具体使用方式为：

1. 调用自定义冷启动开关接口，开启自定冷启动功能。（该接口需在BonreeSDK启动前设置）
2. 在需要的时机调用冷启动结束接口，记录冷启动结束。

/// 标识使用自定义冷启动结束时间（需在BonreeSDK启动之前设置）
+ (void)useCustomLaunch:(BOOL)used;
/// 记录冷启动结束
+ (void)recordCustomLaunchEnd;

• 接口说明

• 示例

  Objective-C

    // 需在BonreeSDK启动之前设置
    [BRSAgent useCustomLaunch:YES];
  
    // ...
  
    // 在需求时机位置调用
    [BRSAgent recordCustomLaunchEnd];
  

  Swift

    // 需在BonreeSDK启动之前设置
    BRSAgent.useCustomLaunch(true)
  
    // ...
  
    // 在需求时机位置调用
    BRSAgent.recordCustomLaunchEnd()
  

注意：开启自定义冷启动功能后，若30s内未调用记录冷启动结束接口，冷启动监控过程会强制结束。

设置SDK自身请求Header

调用本接口，可以给SDK自身发起的请求的请求头Header中添加信息。需要在调用+ startWithAppID:前调用以下接口设置。

/// 设置SDK内请求的Header（需在BonreeSDK启动之前设置）
+ (void)setSDKRequestHeaders:(NSDictionary<NSString *, NSString *> *)headers;

• 接口说明

• 示例

  Objective-C

    [BRSAgent setSDKRequestHeaders:@{
        @"headerKey0":@"headerValue0",
        @"headerKey1":@"headerValue1"
    }];
  

  Swift

    BRSAgent.setSDKRequestHeaders([
        "headerKey0":"headerValue0",
        "headerKey1":"headerValue1"
    ])
  

  注意：使用设置自定义请求信息接口需升级iOS客户端至7.3.2及以上版本。

开启加密并设置加密信息

调用本接口，可以对SDK自身发起的请求进行国密加密。需要在调用+ startWithAppID:前调用以下接口设置。

加密功能当前仅支持One平台。使用该功能前请务必先与技术支持或实施沟通获取加密Key，保证与平台配置一致，否则会导致SDK数据请求异常。

/// 设置国密SM4算法加解密key与identifier
/// @param key          秘钥
/// @param identifier     对应key的唯一标识
+ (BOOL)enableGMSM4EncryptWithKey:(NSString *)key identifier:(NSString *)identifier;

• 接口说明

• 示例

  Objective-C

    [BRSAgent enableGMSM4EncryptWithKey:@"符合上述限制的key" identifier:@"符合上述限制的标识"];
  

  Swift

    BRSAgent.enableGMSM4Encrypt(withKey: "符合上述限制的key", identifier: "符合上述限制的标识")
  

  注意：使用国密加密接口需升级iOS客户端至8.3.0及以上版本。

二、数据获取接口

获取设备ID

默认情况下，设备的唯一ID由BonreeSDK内部生成并持久维护，用来标识产生各性能数据的设备。我们提供了获取该设备ID的接口，用以支持监控数据在设备维度的自主关联等需求场景。

/// 获取设备的deviceID
+ (NSString *)deviceID;

• 接口说明

• 示例

  Objective-C

    NSString *deviceID = [BRSAgent deviceID];
  

  Swift

    let deviceID = BRSAgent.deviceID()
  

获取SDK版本

/// 获取SDK的版本号
+ (NSString *)SDKVersion;

• 接口说明

• 示例

  Objective-C

    NSString *version = [BRSAgent SDKVersion];
  

  Swift

    let version = BRSAgent.sdkVersion()
  

三、自定义功能接口

自定义用户信息

BonreeSDK支持设置与用户相关的信息，从而完成性能数据与实际用户相关联的需求场景。

设置用户信息有两种方式：

1. 设置用户ID，以字符串形式给用户做标识。接口如下：

/// 设置用户ID
+ (void)setUserID:(nullable NSString *)userID;

• 接口说明

• 示例

  Objective-C

    [BRSAgent setUserID:@"user-id"];
  

  Swift

    BRSAgent.setUserID("user-id")
  

2. 以 Key-Value 形式设置用户附加信息。接口如下：

/// 设置附加信息
+ (void)setExtraInfo:(nullable NSDictionary <NSString *, id>*)extraInfo;

• 接口说明

• 示例

  Objective-C

    [BRSAgent setExtraInfo:@{@"id":@"123456", @"name":@"Tom"}];
  

  Swift

    BRSAgent.setExtraInfo(["id":"123456", "name":"Tom"])
  

自定义异常

调用接口并传入相应参数，可完成自定义异常数据的统计功能。

/// 自定义异常收集
+ (void)setCustomExceptionWithType:(NSString *)exceptionType
                           causeBy:(NSString * _Nullable)causedBy
                         errorDump:(NSString * _Nullable)errorDump;

• 接口说明

• 示例

  Objective-C

    [BRSAgent setCustomExceptionWithType:@"Custom exception type"
                                 causeBy:@"Caused by customer."
                               errorDump:@"Custom error dump 0\nCustom error dump 1"];
  

  Swift

    BRSAgent.setCustomExceptionWithExceptionType("Custom exception type",
                                                 causeBy: "Caused by customer.",
                                                 errorDump: "Custom error dump 0\nCustom error dump 1")
  

注意：即使在自定义异常接口中传入了正确的崩溃堆栈，平台也不会进行崩溃堆栈的符号解析。

自定义视图

调用接口并传入相应参数，可完成自定义视图数据统计功能。

/// 自定义视图——标记视图开始（和视图结束方法成对调用）
///     一般调用位置：viewWillAppear或者viewDidAppear
+ (void)setCustomPageStartWithName:(NSString *)pageName
                         pageAlias:(nullable NSString *)pageAlias;
/// 自定义视图——标记视图结束（和视图开始方法成对调用）
///     一般调用位置：viewWillDisappear或者viewDidDisappear
+ (void)setCustomPageEndWithName:(NSString *)pageName
                       pageAlias:(nullable NSString *)pageAlias;

• 接口说明

• 示例

  Objective-C

    - (void)viewWillAppear:(BOOL)animated {
        [super viewWillAppear:animated];
  
        [BRSAgent setCustomPageStartWithName:@"page01" pageAlias:@"首页"];
    }
  
    - (void)viewWillDisappear:(BOOL)animated {
        [super viewWillDisappear:animated];
  
        [BRSAgent setCustomPageEndWithName:@"page01" pageAlias:@"首页"];
    }
  

  Swift

    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
  
        BRSAgent.setCustomPageStartWithName("page01", pageAlias: "首页")
    }
  
    override func viewWillDisappear(_ animated: Bool) {
      super.viewWillDisappear(animated)
  
        BRSAgent.setCustomPageEndWithName("page01", pageAlias: "首页")
    }
  

注意：自定义视图的开始与结束记录接口必须成对调用，并且同一视图的pageName必须一致，才能正确统计一个完整自定义视图数据并上报。

自定义事件（完整版）

分别调用开始与结束接口并传入相应参数，可完成自定义事件数据与事件持续时间的统计功能。

/// 自定义事件开始
+ (void)setCustomEventStartWithID:(NSString *)eventID
                             name:(nullable NSString *)eventName;

+ (void)setCustomEventStartWithID:(NSString *)eventID
                             name:(nullable NSString *)eventName
                            label:(nullable NSString *)eventLabel;

+ (void)setCustomEventStartWithID:(NSString *)eventID
                             name:(nullable NSString *)eventName
                            label:(nullable NSString *)eventLabel
                            param:(nullable NSString *)param;

+ (void)setCustomEventStartWithID:(NSString *)eventID
                             name:(nullable NSString *)eventName
                            label:(nullable NSString *)eventLabel
                            param:(nullable NSString *)param
                             info:(nullable NSDictionary<NSString *, NSString *> *)info;
/// 自定义事件结束
+ (void)setCustomEventEndWithID:(NSString *)eventID
                           name:(nullable NSString *)eventName;

+ (void)setCustomEventEndWithID:(NSString *)eventID
                           name:(nullable NSString *)eventName
                          label:(nullable NSString *)eventLabel;

+ (void)setCustomEventEndWithID:(NSString *)eventID
                           name:(nullable NSString *)eventName
                          label:(nullable NSString *)eventLabel
                          param:(nullable NSString *)param;

+ (void)setCustomEventEndWithID:(NSString *)eventID
                           name:(nullable NSString *)eventName
                          label:(nullable NSString *)eventLabel
                          param:(nullable NSString *)param
                           info:(nullable NSDictionary<NSString *, NSString *> *)info;

• 接口说明

• 示例

  Objective-C

    [BRSAgent setCustomEventStartWithID:@"001" name:@"用户登录" label:@"Login"];
    // Some code...
    [BRSAgent setCustomEventEndWithID:@"001" name:@"用户登录" label:@"Login"];
  

  Swift

    BRSAgent.setCustomEventStartWithID("001", name: "用户登录", label: "Login")
    // Some code...
    BRSAgent.setCustomEventEndWithID("001", name: "用户登录", label: "Login")
  

注意：自定义事件开始与结束的匹配使用eventID唯一匹配，使用时请确保未结束事件ID的唯一性。

使用完整版自定义事件接口需升级iOS客户端至7.6.0及以上版本。

自定义事件（精简版）

调用接口并传入相应参数，可完成自定义事件数据统计功能。

/// 自定义事件
+ (void)setCustomEventWithID:(NSString *)eventID
                        name:(nullable NSString *)eventName;

+ (void)setCustomEventWithID:(NSString *)eventID
                        name:(nullable NSString *)eventName
                       param:(nullable NSString *)param;

+ (void)setCustomEventWithID:(NSString *)eventID
                        name:(nullable NSString *)eventName
                       label:(nullable NSString *)eventLabel;

+ (void)setCustomEventWithID:(NSString *)eventID
                        name:(nullable NSString *)eventName
                       label:(nullable NSString *)eventLabel
                       param:(nullable NSString *)param;

+ (void)setCustomEventWithID:(NSString *)eventID
                        name:(nullable NSString *)eventName
                       label:(nullable NSString *)eventLabel
                       param:(nullable NSString *)param
                        info:(nullable NSDictionary<NSString *, NSString *> *)info;

• 接口说明

• 示例

  Objective-C

    [BRSAgent setCustomEventWithID:@"001" name:@"用户登录" label:@"Login"];
  

  Swift

    BRSAgent.setCustomEventWithID("001", name: "用户登录", label: "Login")
  

注意：使用自定义事件中的Label字段需升级iOS客户端至7.6.0及以上版本。

自定义日志

调用接口并传入相应参数，可完成自定义日志数据统计功能。

/// 自定义日志
+ (void)setCustomLog:(NSString *)logInfo;

+ (void)setCustomLog:(NSString *)logInfo
               param:(nullable NSString *)param;

• 接口说明

• 示例

  Objective-C

    [BRSAgent setCustomLog:@"2020-01-01 08:30:00 Print log info."];
  

  Swift

    BRSAgent.setCustomLog("2020-01-01 08:30:00 Print log info.")
  

自定义指标

调用接口并传入相应参数，可完成自定义指标数据统计功能。

/// 自定义指标
+ (void)setCustomMetricWithName:(NSString *)metricName
                          value:(NSInteger)metricValue;

+ (void)setCustomMetricWithName:(NSString *)metricName
                          value:(NSInteger)metricValue
                          param:(nullable NSString *)param;

• 接口说明

• 示例

  Objective-C

    [BRSAgent setCustomMetricWithName:@"测试指标01" value:1];
  

  Swift

    BRSAgent.setCustomMetricWithName("测试指标01", value: 1)
  

自定义方法

调用接口并传入相应参数，可完成自定义方法数据统计功能。

/// 自定义方法开始
+ (void)setCustomMethodStartWithName:(NSString *)methodName;

+ (void)setCustomMethodStartWithName:(NSString *)methodName
                               param:(nullable NSString *)param;

/// 自定义方法结束
+ (void)setCustomMethodEndWithName:(NSString *)methodName;

+ (void)setCustomMethodEndWithName:(NSString *)methodName
                             param:(nullable NSString *)param;

• 接口说明

• 示例

  Objective-C

    - (void)testCustomMethod {
        [BRSAgent setCustomMethodStartWithName:@"testCustomMethod"];
  
        // Do something...
  
        [BRSAgent setCustomMethodStartWithName:@"testCustomMethod"];
   }
  

  Swift

    func testCustomMethod() -> Void {
        BRSAgent.setCustomMethodStartWithName("testCustomMethod")
  
        // Do something...
  
        BRSAgent.setCustomMethodEndWithName("testCustomMethod")
    }
  

  注意：自定义方法以方法名参数匹配同一方法的前后调用，使用时须保证执行期间方法名唯一。

自定义网络

调用接口并传入相应参数，可完成自定义网络数据统计功能。

/// 自定义网络接口
+ (void)setCustomNetwork:(BRSNetworkModel *)networkModel;

• 接口说明

// 自定义网络数据模型定义
@interface BRSNetworkModel : NSObject

@property (nonatomic, copy)   NSString *requestUrl; //请求地址「必传」
@property (nonatomic, assign) uint32_t protocolType;//协议类型「0:其它协议,1:h1,2:h1s,3:h2,5:ws,6:wss,7:tcp,10:udp,11:quic」
@property (nonatomic, copy, nullable) NSString *targetIpV6; //目标IP(支持IPv4、IPv6)
@property (nonatomic, assign) uint32_t targetPort;  //目标端口

@property (nonatomic, strong, nullable) NSDictionary<NSString *, id> *requestHeader; //请求header
@property (nonatomic, strong, nullable) NSDictionary<NSString *, id> *responseHeader;//响应header

@property (nonatomic, copy, nullable)   NSString *method;       //请求方式 [大写]
@property (nonatomic, copy, nullable)   NSString *resourceType; //资源类型「响应头Content-Type内容 eg:image/jpeg、text/html」
@property (nonatomic, strong, nullable) NSArray<NSString *> *cnames;//cname的数组

@property (nonatomic, assign) uint64_t dnsTimeUs;       //dns查询耗时「单位:us」
@property (nonatomic, assign) uint64_t connectTimeUs;   //tcp建连耗时「单位:us」
@property (nonatomic, assign) uint64_t ssltimeUs;       //ssl握手耗时「单位:us」
@property (nonatomic, assign) uint64_t requestTimeUs;   //请求耗时「单位:us」
@property (nonatomic, assign) uint64_t responseTimeUs;  //响应耗时「单位:us」
@property (nonatomic, assign) uint64_t downloadTimeUs;  //下载耗时「单位:us」
@property (nonatomic, assign) int64_t requestDataSize;  //请求大小「单位:byte」
@property (nonatomic, assign) int64_t responseDataSize; //响应数据「单位:byte」

/// 目前版本暂不支持自定义的网络错误，以下字段请勿赋值
@property (nonatomic, strong, nullable) NSNumber *errorCode;    //错误码
@property (nonatomic, copy, nullable)   NSString *errorMessage; //错误信息「非错误请求请勿赋值」
@property (nonatomic, strong, nullable) NSNumber *errorOccurrentprocess;//错误过程「1:SSL过程，2:DNS过程，3:TCP过程，4:其他过程」

@end

属性中标记nullable的字段均为非必传。

• 示例

  Objective-C

    BRSNetworkModel *model = [[BRSNetworkModel alloc] init];
    model.requestUrl = @"https://www.bonree.com/";
    // ...
    // 依次设置全部BRSNetworkModel全部属性
  
    [BRSAgent setCustomNetwork:model];
  

  Swift

    let model = BRSNetworkModel()
    model.requestUrl = "https://www.bonree.com/"
    // ...
    // 依次设置全部BRSNetworkModel全部属性
  
    BRSAgent.setCustomNetwork(model)
  

设置自定义请求信息接口

调用接口并传入相应参数，可以给匹配到的网络数据关联自定义的字符串信息。

/// 设置请求信息接口
/// @param headerKey 请求头中对应的键
/// @param value 需要匹配的value值
/// @param info 设置的请求信息
+ (void)setRquestExtraInfoWithHeaderKey:(nonnull NSString *)headerKey value:(nonnull NSString *)value info:(nullable NSString *)info;

• 接口说明

• 示例

  Objective-C

    [BRSAgent setRquestExtraInfoWithHeaderKey:@"brkey" value:@"30F032AA-7837-479E-971D-E382B0F90D9B" info:@"name=TOM&age=12"];
  

  Swift

    BRSAgent.setRquestExtraInfoWithHeaderKey("brkey", value: "30F032AA-7837-479E-971D-E382B0F90D9B", info: "name=TOM&age=12")
  

使用本接口前，需要保证目标请求的请求头中有唯一标识，比如，某请求的请求头如下：

POST /upload HTTP/1.1
Host: sdkupload.bonree.com
Content-Type: application/json
Content-Length: 781
Connection: keep-alive
Br-Content-Encoding: gzip
brkey: 30F032AA-7837-479E-971D-E382B0F90D9B

其中brkey为该请求的唯一标识字段，若要给该请求关联信息

name=TOM&age=12

则需要在请求发出之前调用

[BRSAgent setRquestExtraInfoWithHeaderKey:@"brkey" value:@"30F032AA-7837-479E-971D-E382B0F90D9B" info:@"name=TOM&age=12"];

注意：使用设置自定义请求信息接口需升级iOS客户端至7.6.0及以上版本。

设置在线调试功能授权

在线调试功能需要应用给客户端提前授权，才能可以执行平台下发的指令。

授权过程提供如下两个接口：

/// 在线调试授权
/// @param isAuthorized 是否授权
+ (void)authorizeOnlineTracking:(BOOL)isAuthorized;
/**
 授权接口可随时调用,开启或关闭授权.
 授权状态仅单次应用生命周期内有效.
*/

/// 设置在线调试功能授权回调
/// @param authHandler 回调Block
+ (void)setOnlineTrackingAuthorizationCallback:(nullable void (^)(void))authHandler;
/**
 单次追踪过程中若未授权,会且仅会询问一次.
 authHandler是在主线程执行.
*/

在线调试授权接口可以单独使用，随时控制App当前生命周期内的授权状态。不调用接口默认关闭。

在线调试功能授权回调设置接口提供了对客户端进行动态的授权能力，在使用该接口设置好回调block的前提下，当平台请求客户端调试权限时，会执行回调block。开发者可以在回调block中自行设计权限的处理方式，比如弹窗进行权限询问等。该接口不是必须使用的，可以在不设置授权回调的前提下，直接使用在线调试授权接口进行权限控制。

• 示例

  Objective-C

    [BRSAgent setOnlineTrackingAuthorizationCallback:^{
  
        // Do something...
  
        [BRSAgent authorizeOnlineTracking:YES];
    }];
  

  Swift

    BRSAgent.setOnlineTrackingAuthorizationCallback {
  
        // Do something...
  
        BRSAgent.authorizeOnlineTracking(true)
    }
  

注意：使用在线调试功能授权系列接口需升级iOS客户端至7.8.0及以上版本。

自定义操作结束

调用该接口，结束根据调用栈匹配到的操作。该方法必须直接或间接地由操作相关的方法调用，否则调用无效。

• 使用场景

以登录场景为例，

1. 点击登录按钮，触发 login 方法；
2. login 方法中，发送 login 请求；
3. login 请求成功后，持久化用户信息，并跳转到主页；
4. 在主页的控制器中执行其他业务逻辑；

如果我们定义登录操作的结束点为主页的控制器出现，那么我们就可以在 viewDidAppear(_:) 方法中调用自定义操作结束接口。

// 登录
@objc func login() {
    // some code

    // 登录请求
    URLSession.shared
        .dataTask(with: request) { data, response, _ in
            // 持久化用户信息

            DispatchQueue.main.async {
                self.present(FeedListViewController(), animated: true)
            }
        }
        .resume()

    // some code
}

// 主页的控制器

override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)

    BRSAgent.recordCustomActionEnd()

    // some code
}

• 接口定义

+ (void)recordCustomActionEnd;

• 示例

Objective-C

[BRSAgent recordCustomActionEnd];

Swift

BRSAgent.recordCustomActionEnd()