API功能

一、启动配置接口

BonreeSDK启动接口

/// 启动 BonreeSDK
+ (void)startWithAppID:(NSString *)appID;
  • 接口说明
参数名 类型 注释
appID NSString 博睿SDK平台生成的应用唯一ID
  • 示例

    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;
  • 接口说明
参数名 类型 注释
configAddress NSString 私有云config地址
  • 示例

    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;
  • 接口说明
参数名 类型 注释
appVersion NSString 需要设置的版本信息
  • 示例

    Objective-C

      [BRSAgent setAppVersion:@"3.2.1"];
    

    Swift

      BRSAgent.setAppVersion("3.2.1")
    

设置下载渠道名称

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

/// 设置渠道标识(请在BonreeSDK启动之前设置)
+ (void)setChannelID:(NSString *)channelID;
  • 接口说明
参数名 类型 注释
channelID NSString 需要设置的渠道名称
  • 示例

    Objective-C

      [BRSAgent setChannelID:@"AppStore"];
    

    Swift

      BRSAgent.setChannelID("AppStore")
    

设置自定义的设备ID

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

/// 配置自定义的设备deviceID(请在BonreeSDK启动之前设置)
+ (void)setDeviceID:(NSString *)deviceID;
  • 接口说明
参数名 类型 注释
deviceID NSString 需要设置的设备ID
  • 示例

    Objective-C

      [BRSAgent setDeviceID:@"0123456789"];
    

    Swift

      BRSAgent.setDeviceID("0123456789")
    

设置持续丢帧时间

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

/// 设置持续丢帧监测时间(请在BonreeSDK启动之前设置) 
+ (void)setDropFrameTime:(NSInteger)time;
  • 接口说明
参数名 类型 注释
time NSInteger 持续丢帧时间(s),0< dropFrameTime <=30,不设置默认5s)
  • 示例

    Objective-C

      [BRSAgent setDropFrameTime:5];
    

    Swift

      BRSAgent.setDropFrameTime(5)
    

设置mPaaS框架使用状态

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

/// 是否使用了mPaaS框架(请在BonreeSDK启动之前设置)
+ (void)useMpaas:(BOOL)used;
  • 接口说明
参数名 类型 注释
used BOOL 是否使用了mPaaS框架
  • 示例

    Objective-C

      [BRSAgent useMpaas:YES];
    

    Swift

      BRSAgent.useMpaas(true)
    

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

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

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

/// 设置请求头中自定义业务字段
+ (void)setCustomBusinessHeaders:(NSArray<NSString *> *)headerArr;
  • 接口说明
参数名 类型 注释
headerArr NSArray 要获取的请求头中自定义业务字段数组(最多设置64个)
  • 示例

    Objective-C

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

    Swift

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

自定义冷启动结束时间

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

  1. 调用自定义冷启动开关接口,开启自定冷启动功能。(该接口需在BonreeSDK启动前设置)
  2. 在需要的时机调用冷启动结束接口,记录冷启动结束。
/// 标识使用自定义冷启动结束时间(需在BonreeSDK启动之前设置)
+ (void)useCustomLaunch:(BOOL)used;
/// 记录冷启动结束
+ (void)recordCustomLaunchEnd;
  • 接口说明
参数名 类型 注释
used BOOL 是否使用自定义冷启动结束时间
  • 示例

    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;
  • 接口说明
参数名 类型 注释
headers NSDictionary 要设置的请求头键值对(最多设置64个,key长度限制256个字符,value长度限制512个字符)
  • 示例

    Objective-C

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

    Swift

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

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

二、数据获取接口

获取设备ID

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

/// 获取设备的deviceID
+ (NSString *)deviceID;
  • 接口说明
返回值类型 注释
NSString SDK中生成的设备ID。如果事先设置了,则返回设置的值。
  • 示例

    Objective-C

      NSString *deviceID = [BRSAgent deviceID];
    

    Swift

      let deviceID = BRSAgent.deviceID()
    

获取SDK版本

/// 获取SDK的版本号
+ (NSString *)SDKVersion;
  • 接口说明
返回值类型 注释
NSString SDK的版本号
  • 示例

    Objective-C

      NSString *version = [BRSAgent SDKVersion];
    

    Swift

      let version = BRSAgent.sdkVersion()
    

三、自定义功能接口

自定义用户信息

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

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

1. 设置用户ID,以字符串形式给用户做标识。接口如下:
/// 设置用户ID
+ (void)setUserID:(nullable NSString *)userID;
  • 接口说明
参数名 类型 注释
userID NSString 用户ID
  • 示例

    Objective-C

      [BRSAgent setUserID:@"user id"];
    

    Swift

      BRSAgent.setUserID("user id")
    
2. 以 Key-Value 形式设置用户附加信息。接口如下:
/// 设置附加信息
+ (void)setExtraInfo:(nullable NSDictionary <NSString *, id>*)extraInfo;
  • 接口说明
参数名 类型 注释
extraInfo NSDictionary 用户附加信息。Value限制NSString或NSNumber类型。
  • 示例

    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;
  • 接口说明
参数名 类型 注释
exceptionType NSString 异常类型。必传参数,空或空串接口调用无效。
causedBy NSString 异常原因
errorDump NSString 异常堆栈
  • 示例

    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;
  • 接口说明
参数名 类型 注释
pageName NSString 页面名称。必传参数,空或空串接口调用无效。
pageAlias NSString 页面别名
  • 示例

    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)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;
  • 接口说明
参数名 类型 注释
eventID NSString 事件ID。必传参数,空或空串接口调用无效。
eventName NSString 事件名称
eventLabel NSString 事件标签
param NSString 附加信息(预留字段,暂无使用场景)
  • 示例

    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;
  • 接口说明
参数名 类型 注释
eventID NSString 事件ID。必传参数,空或空串接口调用无效。
eventName NSString 事件名称
eventLabel NSString 事件标签
param NSString 附加信息(预留字段,暂无使用场景)
  • 示例

    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;
  • 接口说明
参数名 类型 注释
logInfo NSString 日志信息。必传参数,空或空串接口调用无效。
param NSString 附加信息(预留字段,暂无使用场景)
  • 示例

    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;
  • 接口说明
参数名 类型 注释
metricName NSString 指标名称。必传参数,空或空串接口调用无效。
metricValue NSInteger 指标值。必传参数,指标为空接口调用无效。
param NSString 附加信息(预留字段,暂无使用场景)
  • 示例

    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;
  • 接口说明
参数名 类型 注释
methodName NSString 方法名称。必传参数,空或空串接口调用无效。
param NSString 附加信息(预留字段,暂无使用场景)
  • 示例

    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;
  • 接口说明
参数名 类型 注释
networkModel BRSNetworkModel 指标名称。必传参数,传空接口调用无效。
// 自定义网络数据模型定义
@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;
  • 接口说明
参数名 类型 注释
headerKey NSString 需要匹配的请求头Key。必传参数,空或空串接口调用无效。
value NSString 需要匹配的请求头Value。必传参数,空或空串接口调用无效。
info NSString 关联的自定义信息。为空则清除对应键值缓存的信息。
  • 示例

    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及以上版本。

results matching ""

    No results matching ""