版本：3.7.0

SDK API

一、启动配置接口

<#Config地址#> 与 <#AppID#> 请于平台上获取，获取方式参见《如何查询AppID和Config地址？》。如有问题请联系技术支持。

BonreeSDK启动接口

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

接口说明

参数名	类型	注释
appID	NSString	博睿SDK平台生成的应用唯一ID

示例

Objective-C

[BRSAgent startWithAppID:@"<#AppID#>"];

Swift

BRSAgent.startWithAppID("<#AppID#>")

设置Config地址

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

/// 设置Config地址（请在BonreeSDK启动之前设置）
+ (void)setConfigAddress:(NSString *)configAddress;

接口说明

参数名	类型	注释	参数限制
configAddress	NSString	私有云config地址	字符串长度大于0，小于等于2083，否则接口调用失败

示例

Objective-C

[BRSAgent setConfigAddress:@"<#Config地址#>"];

Swift

BRSAgent.setConfigAddress("<#Config地址#>")

设置App版本

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

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

接口说明

参数名	类型	注释	参数限制
appVersion	NSString	需要设置的版本信息	字符串长度大于0，小于等于64，否则接口调用失败

示例

Objective-C

[BRSAgent setAppVersion:@"3.2.1"];

Swift

BRSAgent.setAppVersion("3.2.1")

设置应用环境

使用该接口设置当前应用环境。需要在调用+ startWithAppID:前调用该接口。

/// 设置应用环境（请在BonreeSDK启动之前设置）
/// @param environment 应用环境
+ (void)setAppEnvironment:(NSString *)environment;

接口说明

参数名	类型	注释	参数限制
environment	NSString	需要设置的应用环境	字符串不可为空或空串，否则接口调用无效。字符串长度大于0，小于等于256，否则调用无效。允许中文、数字、字母、冒号、空格、斜杠、下划线、连字符、英文句号、@、#、*、!

示例

Objective-C

[BRSAgent setAppEnvironment:@"xxx"];

Swift

BRSAgent.setAppEnvironment("xxxx")

设置下载渠道名称

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

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

接口说明

参数名	类型	注释	参数限制
channelID	NSString	需要设置的渠道名称	符串长度大于0，小于等于256，否则接口调用失败

示例

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	字符串长度大于0，小于等于256，超过调用失败。允许数字、字母、冒号、空格、斜杠、下划线、连字符、英文句号、@

示例

Objective-C

[BRSAgent setDeviceID:@"0123456789"];

Swift

BRSAgent.setDeviceID("0123456789")

设置持续丢帧时间

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

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

接口说明

参数名	类型	注释
time	NSInteger	持续丢帧时间(s)，设置区间(0, 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"])

自定义冷启动结束时间

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

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

/// 标识使用自定义冷启动结束时间（需在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中添加信息。需要在调用+ startWithAppID:前调用以下接口设置。

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

接口说明

参数名	类型	注释
headers	`NSDictionary<NSString , NSString >`	要设置的请求头键值对（最多设置64个，key长度限制256个字符，value长度限制512个字符）

示例

Objective-C

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

Swift

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

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

设置探针内请求的身份验证挑战处理程序

+ (void)setAuthenticationChallengeHandler:(id (^)(NSURLSession *session, NSURLSessionTask *task, NSURLAuthenticationChallenge *challenge, void (^completionHandler)(NSURLSessionAuthChallengeDisposition , NSURLCredential * _Nullable)))authenticationChallengeHandler;

接口说明

参数名	类型	注释
authenticationChallengeHandler	id (^)(NSURLSession session, NSURLSessionTask task, NSURLAuthenticationChallenge challenge, void (^completionHandler)(NSURLSessionAuthChallengeDisposition , NSURLCredential _Nullable))	身份验证挑战处理程序

注意：该接口需要在探针启动前调用。

设置一个block，该block用于处理探针内主动发起的请求的身份验证挑战。

在实现身份验证挑战处理时，您应首先检查身份验证方法(challenge.protectionSpace.authenticationMethod)，以决定是自己处理身份验证挑战，还是在探针内的默认处理。如果您希望探针处理身份验证挑战，请返回@(NSURLSessionAuthChallengePerformDefaultHandling)。例如，在authentication method == NSURLAuthenticationMethodServerTrust时，您希望探针根据安全策略（security policy）来处理证书验证。

如果您想自己处理跳针，则有四个选项：

返回nil，表示您必须自己调用completionHandler。
返回一个NSError对象。您不得调用completionHandler，返回的错误对象会在任务的completionHandler中体现。
返回一个NSURLCredential。您不得调用completionHandler，返回的凭证用于满足挑战。
返回一个包装NSURLSessionAuthChallengeDisposition的NSNumber对象，支持的值有@(NSURLSessionAuthChallengePerformDefaultHandling), @(NSURLSessionAuthChallengeCancelAuthenticationChallenge) 和 @(NSURLSessionAuthChallengeRejectProtectionSpace)。您不得调用completionHandler。

如果您返回其他内容，将抛出一个异常。

示例

Objective-C

[BRSAgent setAuthenticationChallengeHandler:^id _Nonnull(NSURLSession * _Nonnull session,
NSURLSessionTask * _Nonnull task, NSURLAuthenticationChallenge * _Nonnull challenge, void
(^ _Nonnull completionHandler)(NSURLSessionAuthChallengeDisposition, NSURLCredential *
_Nullable)) {
    return @(NSURLSessionAuthChallengePerformDefaultHandling);
}];

Swift

BRSAgent.setAuthenticationChallengeHandler { _, _, _, _ in
    return URLSession.AuthChallengeDisposition.performDefaultHandling
}

设置安全策略

注意：该接口需要在探针启动前调用。

设置一个安全策略，用于评估探针发起的请求的安全连接的服务器信任。探针内默认使用defaultPolicy。

+ (void)setSecurityPolicy:(BRSSecurityPolicy *)securityPolicy;

接口说明

参数名	类型	注释
key	BRSSecurityPolicy	安全策略

示例

Objective-C

BRSSecurityPolicy *policy = [BRSSecurityPolicy policyWithPinningMode:BRSSSLPinningModeCertificate];
policy.pinnedCertificates = [NSSet setWithObject:yourCerData]; // yourCerData替换为自己的证书
[BRSAgent setSecurityPolicy:policy];

Swift

let policy = BRSSecurityPolicy(pinningMode: .certificate)
policy.pinnedCertificates = [yourCerData] // yourCerData替换为自己的证书
BRSAgent.setSecurityPolicy(policy)

开启加密并设置加密信息

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

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

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

接口说明

参数名	类型	注释
key	NSString	国密加密的秘钥（长度必须为16个字节，请勿使用< > & ' " %特殊字符）
identifier	NSString	对应key的唯一标识（长度限制1-256个字符，仅支持字母数字下划线_和横线-）

示例

Objective-C

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

Swift

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

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

设置忽略SIGPIPE

注意：该接口需在探针启动前调用。

设置忽略SIGPIPE。

默认情况下，探针会捕获SIGPIPE崩溃。

设置忽略SIGPIPE后，探针内会主动将SIGPIPE的处理方式设置为SIG_IGN。您必须在代码中检查send()、 write()的返回值，并在errno为EPIPE时妥善处理断开链接的错误。

同时，您应当知晓，signal handler会被覆盖。

+ (void)ignoreSIGPIPE;

示例

Objective-C

[BRSAgent ignoreSIGPIPE];

Swift

BRSAgent.ignoreSIGPIPE()

崩溃回调接口

设置崩溃回调接口，可以在应用发生崩溃时，配合summaryOfCrashReportWithEventID:接口获取崩溃信息。

注意，崩溃时应用处于一个不稳定且脆弱的状态，理论上要求执行的代码是async-safe的。若无必要，不要调用该方法。

+ (void)setCrashCallback:(void(^)(NSString *eventID))crashCallback;

示例 Objective-C

[BRSAgent setCrashCallback:^(NSString * _Nonnull eventID) {
  NSDictionary *summary = [BRSAgent summaryOfCrashReportWithEventID:eventID];
  // ...
}];

Swift

BRSAgent.setCrashCallback { eventID in
  let summary = BRSAgent.summaryOfCrashReport(withEventID: eventID);
  // ...
}

开启会话回放上报

在会话回放模块开启时，默认情况下探针根据配置开启会话回放数据上报。在探针未开始会话回放数据上报时，调用该接口，可以立即开启会话回放的数据上报功能。

注意，同一会话中，该接口只需调用一次即可。

+ (void)startSessionReplayUpload;

示例 Objective-C

[BRSAgent startSessionReplayUpload];

Swift

BRSAgent.startSessionReplayUpload()

二、数据获取接口

获取设备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	字符串可为空或空串。字符串小于等于256，超过调用无效。允许中文、数字、字母、冒号、空格、斜杠、下划线、连字符、英文句号、@、#、*、!

示例

Objective-C

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

Swift

BRSAgent.setUserID("user-id")

2. 以 Key-Value 形式设置用户附加信息。

该接口已废弃，请使用setUserExtraInfo:接口。

/// 设置附加信息
+ (void)setExtraInfo:(nullable NSDictionary <NSString *, id>*)extraInfo __attribute__((deprecated(" Use setUserExtraInfo: instead.")));

接口说明

参数名	类型	注释	参数限制
extraInfo	NSDictionary	用户附加信息。Value限制NSString或NSNumber类型。	Map可为空或空集合。转JSON后长度在7000字符以内，否则接口调用失败。

示例

Objective-C

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

Swift

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

3. 设置用户附加信息

+ (void)setUserExtraInfo:(NSDictionary<NSString *, id>*)extraInfo;

接口说明

参数名	类型	注释	参数限制
extraInfo	NSDictionary	用户附加信息	字段的有效kv数量限制为64，超过时取64个。 key限制为(0, 256]长度的字符串。 value限制为非空字符串、NSNumber、NSDate。字符串长度超过512，超过截取

示例

Objective-C

[BRSAgent setUserExtraInfo:@{@"name": @"Jack"}];

Swift

BRSAgent.setUserExtraInfo(["name": "Jack"])

4. 添加用户附加信息

+ (void)addUserExtraInfoWithKey:(NSString *)key value:(id)value;

接口说明

该接口中key、value的限制与setUserExtraInfo:接口中的限制相同。

示例

Objective-C

[BRSAgent addUserExtraInfoWithKey:@"height" value:@(17)];

Swift

BRSAgent.addUserExtraInfo(withKey: "age", value: 23)
BRSAgent.addUserExtraInfo(withKey: "location", value: "earth")

5. 移除用户附加信息

+ (void)removeUserExtraInfoWithKey:(NSString *)key;

接口说明

该接口中key的限制与setUserExtraInfo:接口中的限制相同。

示例

Objective-C

[BRSAgent removeUserExtraInfoWithKey:@"name"];

Swift

BRSAgent.removeUserExtraInfo(withKey: "location")

6. 对用户的附加信息进行累加

+ (void)increaseUserExtraInfoWithKey:(NSString *)key value:(NSNumber *)value;

接口说明

参数名类型注释参数限制
key NSString 键限制与setUserExtraInfo:接口中的限制相同
value NSNumber 值限制为NSNumber类型

参数名	类型	注释	参数限制
key	NSString	键	限制与`setUserExtraInfo:`接口中的限制相同
value	NSNumber	值	限制为NSNumber类型

示例

Objective-C

[BRSAgent increaseUserExtraInfoWithKey:@"height" value:@(3)];

Swift

BRSAgent.increaseUserExtraInfo(withKey: "age", value: 1)

自定义事件属性

1. 添加事件公共属性（一组）

+ (void)addEventAttributes:(NSDictionary<NSString *, id> *)attributes local:(BOOL)local;

接口说明

参数名	类型	注释	参数限制
attributes	NSDictionary	事件公共属性	字段的有效kv数量限制为64，超过时取64个。 key限制为(0, 256]长度的字符串。 value限制为非空字符串、NSNumber、NSDate。字符串长度超过512，超过截取
local	BOOL	是否持久化到本地	持久化到本地的属性，在应用下次启动时自动生效。未持久化到本地的属性，仅当前进程中有效。

示例

Objective-C

[BRSAgent addEventAttributes:@{@"a": @1} local:YES];

Swift

BRSAgent.addEventAttributes(["a": 1], local: false)

添加事件公共属性（单条）

+ (void)addEventAttributeWithKey:(NSString *)key value:(id)value local:(BOOL)local;

调用该接口，与调用addEventAttributes:local:等价。

该接口中key和value的限制、local的作用与addEventAttributes:local:接口中的相同。

示例

Objective-C

[BRSAgent addEventAttributeWithKey:@"b" value:@2 local:NO];

Swift

BRSAgent.addEventAttribute(withKey: "b", value: 2, local: false)

2. 移除事件公共属性

+ (void)removeEventAttributeWithKeys:(NSArray<NSString *> *)keys;

接口说明

参数名类型注释参数限制
keys NSArray 数组元素为要移除的事件公共属性的key 数组中元素的限制与addEventAttributes:local:接口中key的限制相同

调用该接口，将同时移除内存中和本地（如果存在）的事件公共属性。

参数名	类型	注释	参数限制
keys	NSArray	数组元素为要移除的事件公共属性的key	数组中元素的限制与`addEventAttributes:local:`接口中key的限制相同

示例

Objective-C

[BRSAgent removeEventAttributeWithKeys:@[@"b"]];

Swift

BRSAgent.removeEventAttribute(withKeys: ["b"])

3. 移除所有事件公共属性

+ (void)removeAllEventAttributes;

移除所有的事件公共属性（包括本地）。

示例

Objective-C

[BRSAgent removeAllEventAttributes];

Swift

BRSAgent.removeAllEventAttributes()

自定义异常

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

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

接口说明

参数名	类型	注释	参数限制
exceptionType	NSString	异常类型。必传参数，空或空串接口调用无效。	字符串长度大于0，小于等于256，否则接口调用失败。
causedBy	NSString	异常原因	字符串可为空或空串。字符串小于等于512，超长截取。
errorDump	NSString	异常堆栈	超出10000字符时会被切割

示例

Objective-C

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

Swift

BRSAgent.setCustomExceptionWithType("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	页面名称。必传参数，空或空串接口调用无效。	字符串长度大于0，小于等于256，否则接口调用失败。
pageAlias	NSString	页面别名	字符串可为空或空串。字符串小于等于256，超长截取。

示例

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必须一致，才能正确统计一个完整自定义视图数据并上报。

自定义视图标题

自定义标题需控制器遵循协议并实现协议中方法，可完成自定义视图标题功能。

@protocol BRSViewControllerCustomizable <NSObject>

@optional
/// 自定义页面标题[控制器实现协议]
/// @return 自定义页面标题
- (NSString *)brsViewTitle;

@end

协议说明

方法名	返回类型	注释	参数限制
brsViewTitle	NSString	页面标题名称。	类型必须为NSString，其余类型无效。

示例

Objective-C

@interface Controller()<BRSViewControllerCustomizable>
...

- (NSString *)brsViewTitle {
	return @"Title";
}

...
@end

Swift

extension Controller: BRSViewControllerCustomizable {
	func brsViewTitle() -> String? {
		return "Title"
	}
}

注意：控制器遵循了协议并实现了协议方法，即会使用方法的返回值作为视图标题，方法返回内容为空也会使用。

自定义事件（完整版）

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

/// 自定义事件开始
+ (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;

接口说明

参数名	类型	注释	参数限制
eventID	NSString	事件ID。必传参数，空或空串接口调用无效。	字符串长度大于0，小于等于256，否则接口调用失败。
eventName	NSString	事件名称	字符串可为空或空串。字符串小于等于256，超长截取。
eventLabel	NSString	事件标签	字符串可为空或空串。字符串小于等于256，超长截取。
param	NSString	事件附加信息	字符串可为空或空串。字符串小于等于7000，超长截取。
info	NSDictionary	事件业务信息	字典可为空。转JSON后长度在7000字符以内，否则接口调用失败。

示例

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;

接口说明

参数名	类型	注释	参数限制
eventID	NSString	事件ID。必传参数，空或空串接口调用无效。	字符串长度大于0，小于等于256，否则接口调用失败。
eventName	NSString	事件名称	字符串可为空或空串。字符串小于等于256，超长截取。
eventLabel	NSString	事件标签	字符串可为空或空串。字符串小于等于256，超长截取。
param	NSString	事件附加信息	字符串可为空或空串。字符串小于等于7000，超长截取。
info	NSDictionary	事件业务信息	字典可为空。转JSON后长度在7000字符以内，否则接口调用失败。

示例

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	日志信息。必传参数，空或空串接口调用无效。	字符串长度大于0，否则接口调用失败。字符串小于等于10000，超长截取。
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	指标名称。必传参数，空或空串接口调用无效。	字符串长度大于0，小于等于256，否则接口调用失败。
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	方法名称。必传参数，空或空串接口调用无效。	字符串长度大于0，小于等于256，否则接口调用失败。
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。必传参数，空或空串接口调用无效。	字符串长度大于0，小于等于256，否则接口调用失败。
value	NSString	需要匹配的请求头Value。必传参数，空或空串接口调用无效。	字符串长度大于0，小于等于256，否则接口调用失败。
info	NSString	关联的自定义信息。为空则清除对应键值缓存的信息。	字符串长度大于0，小于等于256，若为空则清除对应键值缓存的信息。

示例

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

自定义操作结束

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

使用场景

以登录场景为例，

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

如果我们定义登录操作的结束点为主页的控制器出现，那么我们就可以在 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()

ReactNative中Bundle启动接口

该接口为Bundle开始加载接口，传入Bundle名称和Module名称。

该接口需和Bundle中JS加载结束接口成对调用。

/// React Native Bundle开始加载
+ (void)reportBundleStartLoadWithBundle:(NSString *)bundleName
                             moduleName:(NSString *)moduleName;

接口说明

参数名	类型	注释
bundleName	NSString	Bundle名称。必传参数。
moduleName	NSString	Module名称。必传参数。

示例

Objective-C

[BRSAgent reportBundleStartLoadWithBundle:@"BundleName" moduleName:@"ModuleName"];

Swift

BRSAgent.reportBundleStartLoad(withBundle: "BundleName", moduleName: "ModuleName")

ReactNative中Bundle中JS加载结束接口

该接口为Bundle中JS加载结束接口，传入Bundle名称。

该接口需和Bundle启动接口成对调用。

/// React Native Bundle中JS完成加载
+ (void)reportBundleJSFinishLoadWithBundle:(NSString *)bundleName;

接口说明

参数名	类型	注释
bundleName	NSString	Bundle名称。必传参数。

示例

Objective-C

[BRSAgent reportBundleJSFinishLoadWithBundle:@"BundleName"];

Swift

BRSAgent.reportBundleJSFinishLoad(withBundle: "BundleName")

设置控件实例脱敏

该接口可将某个控件(实例对象)设置为脱敏，则SDK将不采集该控件的敏感信息。

/// UIView实例是否敏感
@property (nonatomic, assign) BOOL brsSensitive;

使用前需引入头文件，#import <BonreeRUM/UIView+BRSSensitive.h>

属性说明

属性名	类型	注释
brsSensitive	BOOL	YES：敏感[过滤文本等信息] NO：不敏感[正常采集]

示例

Objective-C

aView.brsSensitive = YES;

Swift

aView.brsSensitive = true

设置敏感的控件类型

该接口可将控件类型设置为脱敏，则该类型的所有实例都会进行脱敏处理，SDK将不采集该控件的敏感信息。

设置控件类型会将其子类视为敏感，例如设置了UIControl类型，则UIControl的子类UIButton同样为敏感。

/// 设置敏感的控件类型
+ (void)setViewSensitiveClasses:(NSArray<Class> *)classes;

属性说明

属性名	类型	注释
classes	`NSArray<Class>`	设置为敏感的控件类型，例：`UILabel.class`,`UIControl.class`

示例

Objective-C

[BRSAgent setViewSensitiveClasses:@[UIButton.class, UILabel.class]];

Swift

BRSAgent.setViewSensitiveClasses([UIButton.self, UILabel.self])

设置自定义控件标题

该接口给控件设置自定义标题，SDK在采集该控件点击行为时优先使用自定义标题。

使用前先导入#import <BonreeRUM/UIView+BRSExternalExt.h>。控件类型支持：UIView和UIBarItem。

/// 自定义标题，点击时生效
@property (nonatomic, copy) NSString *brsActionControlTitle;

属性说明

属性名	类型	注释
brsActionControlTitle	NSString	控件的自定义标题

示例

Objective-C

//UIView
UIView *view = xxx;
view.brsActionControlTitle = @"CustomTitle";
//UIBarItem
UIBarItem *item = xxx;
item.brsActionControlTitle = @"CustomTitle";

Swift

//UIView
let view: UIView = xxx;
view.brsActionControlTitle = "CustomTitle"
//UIBarItem
let item: UIBarItem = xxx;
item.brsActionControlTitle = "CustomTitle"

设置WebView中是否存在PDF

调用该接口可告知SDK在会话回放截图时是否进行PDF的WebView检测。

/// 设置WebView中是否存在PDF[会话回放]
+ (void)setHavePDFWebView:(BOOL)isPDFWebView;

属性说明

属性名	类型	注释
isPDFWebView	BOOL	WebView中是否包含PDF。YES:包含PDF，会话回放会查找PDF内容，找到则录制 NO:忽略PDF内容

示例

Objective-C

[BRSAgent setHavePDFWebView:YES];

Swift

BRSAgent.setHavePDFWebView(true)

该接口用于包含PDF的WebView会话回放。

设置包含PDF的WebView实例

WebView会话回放截图时会优先使用此接口设置的WebView实例检测。

/// 设置包含PDF的WebView[会话回放]
+ (void)setPDFWebView:(WKWebView *)webView;

属性说明

属性名	类型	注释	参数限制
webView	WKWebView *	包含PDF的WebView实例，如果存在多个WebView,需指明包含PDF的WebView,否则无法捕获正确的内容	WKWebView实例，空值无效。

示例

Objective-C

[BRSAgent setPDFWebView:webView];

Swift

BRSAgent.setPDFWebView(webView)

该接口用于包含PDF的WebView会话回放。

四、协议扩展接口

本章节介绍基于自定义执行单元相关接口的使用及说明。

创建执行单元

调用创建接口，返回实现了BRSSpan协议的实例。

/// 创建span
/// - Parameters:
///   - name: span名称
///   - type: span类型
+ (nullable id<BRSSpan>)startSpanWithName:(NSString *)name type:(NSString *)type;

接口说明

参数名	类型	注释	参数限制
name	NSString	执行单元的名称。必传参数，空或空串接口调用无效。	字符串长度大于0，小于等于256，超过截取。允许数字、字母、冒号、空格、斜杠、下划线、连字符、英文句号、@
type	NSString	执行单元的类型。必传参数，空或空串接口调用无效。	字符串长度大于0，小于等于256，超过截取。允许数字、字母、冒号、空格、斜杠、下划线、连字符、英文句号、@

返回值类型	注释
`id<BRSSpan>`	遵从`BRSSpan`协议的对象。创建失败时返回nil

示例

Objective-C

id<BRSSpan> span = [BRSAgent startSpanWithName:@"name"
                                          type:@"type"];

Swift

let span = BRSAgent.startSpan(withName: "name",
                                  type: "type")

注意：创建接口即startSpanWithName:type: 需和完成接口即finish或finishWithStatus:成对调用。

以下接口均为执行单元(实现BRSSpan协议)实例方法

完成执行单元

完成该执行单元，完成后调用其他实例方法无效。

/// 完成span
/// - Note 如果没有调用 -setStatus:设置span状态，则span状态为success。
- (void)finish;

/// 完成span，且将span状态设置为status。
- (void)finishWithStatus:(BRSSpanStatus)status;

接口说明

参数名	类型	注释
status	BRSSpanStatus	执行单元状态，取值`BRSSpanStatusUnknown`、`BRSSpanStatusSuccess`，`BRSSpanStatusFailed`

示例

Objective-C

[span finish];
//or
[span finishWithStatus:BRSSpanStatusSuccess];

Swift

span.finish()
//or
span.finish(with: .success)

注意：创建接口即startSpanWithName:type: 需和完成接口即finish或finishWithStatus:成对调用。

创建子执行单元

在一个执行单元上创建一个子执行单元，返回实现BRSSpan协议的实例。

/// 创建一个子span
/// - Parameters:
///   - name: span名称
///   - type: span类型
- (nullable id<BRSSpan>)startChildWithName:(NSString *)name type:(NSString *)type;

接口说明

参数名	类型	注释	参数限制
name	NSString	执行单元的名称。必传参数，空或空串接口调用无效。	字符串长度大于0，小于等于256，超过截取。允许数字、字母、冒号、空格、斜杠、下划线、连字符、英文句号、@
type	NSString	执行单元的类型。必传参数，空或空串接口调用无效。（需与父span类型一致，否则沿用父span类型）	字符串长度大于0，小于等于256，超过截取。允许数字、字母、冒号、空格、斜杠、下划线、连字符、英文句号、@

返回值类型	注释
`id<BRSSpan>`	遵从`BRSSpan`协议的对象。创建失败时返回nil

示例

Objective-C

id<BRSSpan> subSpan = [span startChildWithName:@"name"
                                          type:@"type"];

Swift

let subSpan = span.startChild(withName: "name",
                                  type: "type")

注意：完成父执行单元时会自动将其所有子执行单元完成(若没设置过状态的默认为success)

当前仅支持单层子执行单元，即顶层Span可以创建子Span，但是不支持子Span下的子Span。

当Span类型为socket或websocket两个预留类型之一时，暂不支持其下创建子Span。

设置Data数据

设置执行单元内的Data数据

/// 设置data
/// - Parameters:
///   - value: data的值
///   - key: key值
- (void)setDataValue:(NSString *)value forKey:(NSString *)key;

接口说明

参数名	类型	注释	参数限制
value	NSString	Data值。	字符串长度大于0，小于等于7000，超过截取。
key	NSString	Data对应的key值。大小写不敏感。必传参数，空或空串接口调用无效。	字符串长度大于0，小于等于200，超过调用无效。允许字母、下划线、连字符、英文句号，且必须以字母开始、字母结束

示例

Objective-C

[span setDataValue:@"value" forKey:@"key"];

Swift

span.setDataValue("value", forKey: "key")

设置Tag数据

设置执行单元内的Tag数据

/// 设置tags
/// - Parameters:
///   - value: tag的值
///   - key: key值
- (void)setTagValue:(NSString *)value forKey:(NSString *)key;

接口说明

参数名	类型	注释	参数限制
value	NSString	Tag值。	字符串长度大于0，小于等于7000，超过截取。
key	NSString	Tag对应的key值。大小写不敏感。必传参数，空或空串接口调用无效。	字符串长度大于0，小于等于200，超过调用无效。允许字母、下划线、连字符、英文句号，且必须以字母开始、字母结束

示例

Objective-C

[span setTagValue:@"tag" forKey:@"key"];

Swift

span.setTagValue("tag", forKey: "key")

设置Metric数据

1.设置执行单元内的Metric数据(无单位)

/// 设置metrics
/// - Parameters:
///   - value: metric的值
///   - key: key值
- (void)setMetricValue:(long long)value forKey:(NSString *)key;

接口说明

参数名	类型	注释	参数限制
value	long long	Metric值。	无
key	NSString	Metric对应的key值。大小写不敏感。必传参数，空或空串接口调用无效。	字符串长度大于0，小于等于200，超过调用无效。允许字母、下划线、连字符、英文句号，且必须以字母开始、字母结束

示例

Objective-C

[span setMetricValue:100 forKey:@"ms"];

Swift

span.setMetricValue(100, forKey: "tcp")

2.设置执行单元内的Metric数据(有单位)

/// 设置metrics
/// - Parameters:
///   - value: metric的值
///   - unit: value的单位名称
///   - key: key值
- (void)setMetricValue:(long long)value unit:(NSString *)unit forKey:(NSString *)key;

接口说明

参数名	类型	注释	参数限制
value	long long	Metric值。	无
unit	NSString	Metric的单位名称。	字符串长度大于0，小于等于256，超过仅单位设置无效。允许数字、字母、冒号、空格、斜杠、下划线、连字符、英文句号、@
key	NSString	Metric对应的key值。大小写不敏感。必传参数，空或空串接口调用无效。	字符串长度大于0，小于等于200，超过调用无效。允许字母、下划线、连字符、英文句号，且必须以字母开始、字母结束

示例

Objective-C

[span setMetricValue:100 unit:@"ms" forKey:@"tcp"];

Swift

span.setMetricValue(100, unit: "ms", forKey: "tcp")

注意：SDK内部预置了unit单位，预置单位类型见BRSSpan.h中的BRSSpanMetricUnitNames[ ]，支持自定义单位。

移除Data数据

移除执行单元内的Data数据

/// 移除指定data
- (void)removeDataForKey:(NSString *)key;

接口说明

参数名	类型	注释
key	NSString	要删除Data对应的key值

示例

Objective-C

[span removeDataForKey:@"key"];

Swift

span.removeData(forKey: "key")

移除Tag数据

移除执行单元内的Tag数据

/// 移除指定tag
- (void)removeTagForKey:(NSString *)key;

接口说明

参数名	类型	注释
key	NSString	要删除Tag对应的key值

示例

Objective-C

[span removeTagForKey:@"key"];

Swift

span.removeTag(forKey: "key")

移除Metric数据

移除执行单元内的Metric数据

/// 移除指定metric
- (void)removeMetricForKey:(NSString *)key;

接口说明

参数名	类型	注释
key	NSString	要删除Metric对应的key值

示例

Objective-C

[span removeMetricForKey:@"key"];

Swift

span.removeMetric(forKey: "key")

设置Status

设置执行单元的状态。

/// 设置span的状态
- (void)setStatus:(BRSSpanStatus)status;

接口说明

参数名	类型	注释
status	BRSSpanStatus	执行单元状态，取值`BRSSpanStatusUnknown`、`BRSSpanStatusSuccess`，`BRSSpanStatusFailed`

示例

Objective-C

[span setStatus:BRSSpanStatusSuccess];

Swift

span.setStatus(.success)

设置Duration

主动设置span耗时，如果未主动调用该方法，则span耗时为从start到finish的时长。

/// 设置span的耗时
/// - Parameter duration: 耗时时长（单位us）
- (void)setDuration:(long long)duration;

接口说明

参数名	类型	注释
duration	long long	执行单元耗时，单位：微秒us。

示例

Objective-C

[span setDuration:100];

Swift

span.setDuration(100)

设置StatusCode

设置执行单元的状态码。

/// 设置span的状态码
/// - Parameter statusCode: 状态码
- (void)setStatusCode:(NSString *)statusCode;

接口说明

参数名	类型	注释	参数限制
statusCode	NSString	状态码值。	字符串长度大于0，小于等于7000，超过调用无效。

示例

Objective-C

[span setStatusCode:@"200"];

Swift

span.setStatusCode("200")

一、启动配置接口​

BonreeSDK启动接口​

设置Config地址​

设置App版本​

设置应用环境​

设置下载渠道名称​

设置自定义的设备ID​

设置持续丢帧时间​

设置mPaaS框架使用状态​

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

自定义冷启动结束时间​

设置SDK自身请求Header​

设置探针内请求的身份验证挑战处理程序​

设置安全策略​

开启加密并设置加密信息​

设置忽略SIGPIPE​

崩溃回调接口​

开启会话回放上报​

二、数据获取接口​

获取设备ID​

获取SDK版本​

三、自定义功能接口​

自定义用户信息​

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

2. 以 Key-Value 形式设置用户附加信息。​

3. 设置用户附加信息​

4. 添加用户附加信息​

5. 移除用户附加信息​

6. 对用户的附加信息进行累加​

自定义事件属性​

1. 添加事件公共属性（一组）​

添加事件公共属性（单条）​

2. 移除事件公共属性​

3. 移除所有事件公共属性​

自定义异常​

自定义视图​

自定义视图标题​

自定义事件（完整版）​

自定义事件（精简版）​

自定义日志​

自定义指标​

自定义方法​

自定义网络​

设置自定义请求信息接口​

设置在线调试功能授权​

自定义操作结束​

ReactNative中Bundle启动接口​

ReactNative中Bundle中JS加载结束接口​

设置控件实例脱敏​

设置敏感的控件类型​

设置自定义控件标题​

设置WebView中是否存在PDF​

设置包含PDF的WebView实例​

四、协议扩展接口​

创建执行单元​

完成执行单元​

创建子执行单元​

设置Data数据​

设置Tag数据​

设置Metric数据​

1.设置执行单元内的Metric数据(无单位)​

2.设置执行单元内的Metric数据(有单位)​

移除Data数据​

移除Tag数据​

移除Metric数据​

设置Status​

设置Duration​

设置StatusCode​

一、启动配置接口

BonreeSDK启动接口

设置Config地址

设置App版本

设置应用环境

设置下载渠道名称

设置自定义的设备ID

设置持续丢帧时间

设置mPaaS框架使用状态

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

自定义冷启动结束时间

设置SDK自身请求Header

设置探针内请求的身份验证挑战处理程序

设置安全策略

开启加密并设置加密信息

设置忽略SIGPIPE

崩溃回调接口

开启会话回放上报

二、数据获取接口

获取设备ID

获取SDK版本

三、自定义功能接口

自定义用户信息

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

2. 以 Key-Value 形式设置用户附加信息。

3. 设置用户附加信息

4. 添加用户附加信息

5. 移除用户附加信息

6. 对用户的附加信息进行累加

自定义事件属性

1. 添加事件公共属性（一组）

添加事件公共属性（单条）

2. 移除事件公共属性

3. 移除所有事件公共属性

自定义异常

自定义视图

自定义视图标题

自定义事件（完整版）

自定义事件（精简版）

自定义日志

自定义指标

自定义方法

自定义网络

设置自定义请求信息接口

设置在线调试功能授权

自定义操作结束

ReactNative中Bundle启动接口

ReactNative中Bundle中JS加载结束接口

设置控件实例脱敏

设置敏感的控件类型

设置自定义控件标题

设置WebView中是否存在PDF

设置包含PDF的WebView实例

四、协议扩展接口

创建执行单元

完成执行单元

创建子执行单元

设置Data数据

设置Tag数据

设置Metric数据

1.设置执行单元内的Metric数据(无单位)

2.设置执行单元内的Metric数据(有单位)

移除Data数据

移除Tag数据

移除Metric数据

设置Status

设置Duration

设置StatusCode