Native API
一、启动配置接口
调用小程序SDK的启动接口前，需在app.js文件开头引入小程序SDK，通过调用SDK对外暴露的BonreeSDK上的start方法启动SDK
微信小程序中引入：
const BonreeSDK = require('./bonreeSDK_MP_Wechat.min.js')
抖音小程序中引入：
const BonreeSDK = require('./bonreeSDK_MP_Tiktok.min.js')
BonreeSDK启动接口
启动小程序SDK需要调用start函数，并在参数对象中设置Config地址与AppID。
<#Config地址#> 与 <#AppID#> 请于平台上获取，获取方式参见《如何查询AppID和Config地址？》。如有问题请联系技术支持。
function start({
configAddress: "",
appId: ""
})
- 接口说明
| 参数名 | 类型 | 注释 |
|---|---|---|
| configAddress | String | Config地址 |
| appId | String | 博睿SDK平台生成的应用唯一ID |
-
示例
const BRSAgent = BonreeSDK.start({
configAddress: "<#Config地址#>",
appId: "<#AppID#>"
})
设置小程序版本
小程序版本默认获取真实版本号。如有主动配置需求，需要启动接口参数中设置verson字段即可。
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| version | String | 需要设置的版本信息 | 最大长度不超过64 |
-
示例
const BRSAgent = BonreeSDK.start({
configAddress: "<#Config地址#>",
appId: "<#AppID#>",
version: "1.0.0"
})
小程序默认的版本号在小程序开发者后台中发布时设置，debug环境下获取不到，建议根据真实版本情况设置，保证数据的完整性。
设置渠道
小程序SDK支持渠道信息设置，在启动接口参数中设置channelId字段即可。
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| channelId | String | 需要设置的渠道名称 | 最大长度不超过256 |
-
示例
const BRSAgent = BonreeSDK.start({
configAddress: "<#Config地址#>",
appId: "<#AppID#>",
channelId: "channel001"
})
设置自定义的设备ID
设备ID（deviceID）默认由SDK生成并在local storage中保存。如有主动配置需求，在启动接口参数中设置deviceId字段即可。
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| deviceId | String | 需要设置的设备ID | 最大长度不超过256 |
-
示例
const BRSAgent = BonreeSDK.start({
configAddress: "<#Config地址#>",
appId: "<#AppID#>",
deviceId: "0123456789"
})
设置网络请求超时
网络请求超时（timeout）用于配置config请求和upload请求的超时时间，若未配置，则默认60000ms超时。
- 接口说明
| 参数名 | 类型 | 注释 |
|---|---|---|
| timeout | number | 请求超时时间（ms） |
-
示例
const BRSAgent = BonreeSDK.start({
configAddress: "<#Config地址#>",
appId: "<#AppID#>",
timeout: 10000
})
二、自定义功能接口
一般自定义接口的调用位置不在小程序的入口文件App.js中，因此需要在调用接口的文件开头引入SDK实例化对象：
const BRSAgent = require("../../app")
通常情况下在代码中直接键入实例化对象后，微信/抖音开发者工具会自动补全对象的引用。
自定义用户信息
BonreeSDK支持设置与用户相关的信息，从而完成性能数据与实际用户相关联的需求场景。
设置用户信息有两种方式：
1. 设置用户ID，以字符串形式给用户做标识。接口如下：
/// 设置用户ID
function setUserId(userId)
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| userId | String | 用户ID | 字符串可为空或空串。 字符串小于等于256，超过调用无效。允许中文、数字、字母、冒号、空格、斜杠、下划线、连字符、英文句号、@、#、*、! |
-
示例
BRSAgent.setUserId("1234")
2. 以对象形式设置用户附加信息。接口如下：
该接口已废弃，请使用setUserExtraInfo接口。
/// 设置附加信息
function setExtraInfo(extraInfo)
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| extraInfo | Object | 用户附加信息。 | Map可为空或空集合。 转JSON后长度在7000字符以内，否则接口调用失败。 |
-
示例
BRSAgent.setExtraInfo({
key0: "value0",
key1: "value1"
})
3. 设置用户附加信息:
function setUserExtraInfo(extraInfo)
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| extraInfo | Object | 用户附加信息 | 字段的有效kv数量限制为64，超过时取64个。 key限制为(0, 256]长度的字符串。 value限制为非空字符串、数字及布尔值。字符串长度超过512，超过截取 |
-
示例
BRSAgent.setUserExtraInfo({name:'jack'})
4. 添加用户附加信息
function addUserExtraInfo(key,value)
-
接口说明
该接口中key、value的限制与
setUserExtraInfo接口中的限制相同。 -
示例
BRSAgent.addUserExtraInfo("location","Beijing")
BRSAgent.addUserExtraInfo("age",18)
5. 移除用户附加信息
function removeUserExtraInfo(key)
-
接口说明
该接口中key的限制与
setUserExtraInfo接口中的限制相同。 -
示例
BRSAgent.removeUserExtraInfo('name')
BRSAgent.removeUserExtraInfo('location')
6. 对用户的附加信息进行累加
function increaseUserExtraInfo(key,value)
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| key | String | 键 | 限制与setUserExtraInfo接口中的限制相同 |
| value | Number | 值 | 限制为Number类型 |
-
示例
BRSAgent.increaseUserExtraInfo('age',2)
自定义事件属性
1. 添加事件公共属性（一组）
function addEventAttributes(attributes,local)
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| attributes | Object | 事件公共属性 | 字段的有效kv数量限制为64，超过时取64个。 key限制为(0, 256]长度的字符串。 value限制为非空字符串、Number、Boolean。字符串长度超过512，超过截取 |
| local | Boolean | 是否持久化到本地 | 持久化到本地的属性，在应用下次启动时自动生效。未持久化到本地的属性，仅当前进程中有效。 |
-
示例
BRSAgent.addEventAttributes({a:1}, false)
2. 添加事件公共属性（单条）
function addEventAttributeWithKey(key,value,local)
调用该接口，与调用addEventAttributes({key:value},local)等价。
该接口中key和value的限制、local的作用与addEventAttributes({key:value},local)接口中的相同。
-
示例
BRSAgent.addEventAttributeWithKey("b", 2, false)
3. 移除事件公共属性
function removeEventAttributeWithKeys(keys)
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| keys | Array | 数组元素为要移除的事件公共属性的key | 数组中元素的限制与addEventAttributes接口中key的限制相同 |
| 调用该接口，将同时移除内存中和本地（如果存在）的事件公共属性。 |
-
示例
BRSAgent.removeEventAttribute(["b"])
4. 移除所有事件公共属性
function removeAllEventAttributes()
移除所有的事件公共属性（包括本地）。
-
示例
BRSAgent.removeAllEventAttributes()
自定义视图
调用接口并传入相应参数，可完成自定义视图数据统计功能。
// 自定义视图——标记视图开始（和视图结束方法成对调用）
function customPageStart(name, alias)
// 自定义视图——标记视图结束（和视图开始方法成对调用）
function customPageEnd(name, alias)
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| name | String | 视图名称。必传参数，空或空串接口调用无效。 | 字符串长度大于0，小于等于256，否则接口调用失败。 |
| alias | String | 视图别名。可选参数。 | 字符串可为空或空串。 字符串小于等于256，超长截取。 |
-
示例
BRSAgent.customPageStart("page01", "首页")
BRSAgent.customPageEnd("page01", "首页")
注意：自定义视图的开始与结束记录接口必须成对调用，并且同一视图的name必须一致，才能正确统计一个完整自定义视图数据并上报。
自定义事件（完整版）
分别调用开始与结束接口并传入相应参数，可完成自定义事件数据与事件持续时间的统计功能。
// 自定义事件开始
function customEventStart(eventId, eventName, eventLabel, eventParam, info)
// 自定义事件结束
function customEventEnd(eventId, eventName, eventLabel, eventParam,info)
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| eventId | String | 事件ID。必传参数，空或空串接口调用无效。 | 字符串长度大于0，小于等于256 |
| eventName | String | 事件名称，可选参数。 | 字符串可为空或空串。 字符串小于等于256，超长截取。 |
| eventLabel | String | 事件标签，可选参数。 | 字符串可为空或空串 字符串小于等于256，超长截取。 |
| eventParam | String | 事件附加信息，可选参数。 | 字符串可为空或空串 字符串小于等于7000，超长截取。 |
| info | Object | 事件业务信息，可选参数。 | 转JSON后长度在7000字符以内，否则接口调用失败。 |
-
示例
BRSAgent.customEventStart("001", "用户登录", "Login", "",{"key":"value"})
// Some code...
BRSAgent.customEventEnd("001", "用户登录", "Login", "",{"key":"value"})
注意：1.自定义事件开始与结束的匹配使用eventID唯一匹配，使用时请确保未结束事件ID的唯一性。2.info参数为object类型，对象中的key和value值需为string类型
自定义事件（精简版）
调用接口并传入相应参数，可完成自定义事件数据统计功能。
/// 自定义事件
function customEvent(eventId, eventName, eventLabel, eventParam, info)
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| eventId | String | 事件ID。必传参数，空或空串接口调用无效。 | 字符串长度大于0，小于等于256，否则接口调用失败。 |
| eventName | String | 事件名称，可选参数。 | 字符串可为空或空串。 字符串小于等于256，超长截取。 |
| eventLabel | String | 事件标签，可选参数。 | 字符串可为空或空串 字符串小于等于256，超长截取。 |
| eventParam | String | 事件附加信息，可选参数。 | 字符串可为空或空串 字符串小于等于7000，超长截取。 |
| info | Object | 事件业务信息，可选参数。 | 转JSON后长度在7000字符以内，否则接口调用失败。 |
-
示例
BRSAgent.customEvent("001", "用户登录", "Login", "",{"key":"value"})
注意：info参数为object类型，对象中的key和value值需为string类型
自定义日志
调用接口并传入相应参数，可完成自定义日志数据统计功能。
/// 自定义日志
function customLog(info, param)
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| info | String | 日志信息。必传参数，空或空串接口调用无效。 | 字符串长度大于0，否则接口调用失败。 字符串小于等于10000，超长截取。 |
| param | String | 附加信息（预留字段，暂无使用场景），可选参数。 | 字符串长度大于0，否则接口调用失败。 字符串小于等于10000，超长截取。 |
-
示例
BRSAgent.customLog("2020-01-01 08:30:00 Print log info.")
自定义指标
调用接口并传入相应参数，可完成自定义指标数据统计功能。
/// 自定义指标
function customMetric(metricName, metricValue, param)
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| metricName | String | 指标名称。必传参数，空或空串接口调用无效。 | 字符串长度大于0，小于等于256，否则接口调用失败。 |
| metricValue | Number | 指标值。必传参数，指标为空接口调用无效。 | - |
| param | String | 附加信息（预留字段，暂无使用场景），可选参数。 | 字符串长度大于0，否则接口调用失败。 字符串小于等于10000，超长截取。 |
-
示例
BRSAgent.customMetric("测试指标01", 1)
自定义操作结束
调用该接口，结束根据调用栈匹配到的操作。该方法必须直接或间接地由操作相关的方法调用，否则调用无效。
function recordCustomActionEnd()
- 使用场景
以登录场景为例
- 点击登录按钮，触发
onClickHandle方法； onClickHandle方法中，调用了login方法和其他的一些方法；
如果我们只关注触发登录按钮到调用login方法结束时的耗时及函数调用关系等数据，不关注login方法后等其他方法执行的数据，那么我们可以在 login 方法后调用自定义操作结束接口。
-
示例
Page({
...
onClickHandle:function(){
...
login()
BRSAgent.recordCustomActionEnd()
...
// 其他方法或请求
},
login:function(){
...
}
...
})
三、协议扩展接口
本章节介绍基于自定义执行单元相关接口的使用及说明。
创建执行单元
调用创建接口，返回实现了Span类的实例。
/// 创建span
function startSpan(name,type)
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| name | String | 执行单元的名称。必传参数 | 字符串长度大于0，小于等于256，超过截取。 不包含特殊字符(仅支持字母数字下划线_连接符-斜杠/冒号:和符号@、符号.及符号空格)，否则调用无效。 纯空格字符串接口调用无效 |
| type | String | 执行单元的类型。必传参数 | 字符串长度大于0，小于等于256，超过截取。 不包含特殊字符(仅支持字母数字下划线_连接符-斜杠/冒号:和符号@、符号.及符号空格)，否则调用无效。 纯空格字符串接口调用无效。 |
| 返回值类型 | 注释 |
|---|---|
| Span对象 | 创建的主span |
-
示例
const BRSAgent = require("../../app")
const span=BRSAgent.startSpan('name','type')
注意：创建接口即startSpan需和完成接口即finish成对调用。 以下接口均为执行单元(Span类)实例方法
完成执行单元
完成该执行单元，完成后调用其他实例方法无效。
/// 完成span,且将span状态设置为status
function finish(status)
如果没有调用 setStatus设置span状态，则span状态为success。
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| status | number | 执行单元状态。可选参数 | 参数status选填：[0:unknown，1:success，2:fail] |
-
示例
/// 通过调用startSpan接口后的返回值span调用
span.finish(1)
注意：创建接口即startSpan需和完成接口即finish成对调用。 以下接口均为执行单元(Span类)实例方法
创建子执行单元
在一个执行单元上创建一个子执行单元，返回Span类的实例。
/// 创建一个子span
function startChild(name,type)
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| name | String | 执行单元的名称。必传参数，空或空串接口调用无效。 | 字符串长度大于0，小于等于256，超过截取。 不包含特殊字符(仅支持字母数字下划线_连接符-斜杠/冒号:和符号@、符号.及符号空格)，否则调用无效。 纯空格字符串接口调用无效 |
| type | String | 执行单元的类型。必传参数，空或空串接口调用无效。 | 字符串长度大于0，小于等于256，超过截取。 不包含特殊字符(仅支持字母数字下划线_连接符-斜杠/冒号:和符号@、符号.及符号空格)，否则调用无效。 纯空格字符串接口调用无效（需与父span类型一致，否则沿用父span类型） |
| 返回值类型 | 注释 |
|---|---|
| Span对象 | 创建的子span |
-
示例
const subSpan = span.startChild('name','type')
注意：完成父执行单元时会自动将其所有子执行单元完成(若没设置过状态的默认为success)
当前仅支持单层子执行单元，即顶层Span可以创建子Span，但是不支持子Span下的子Span。
当Span类型为socket或websocket两个预留类型之一时，暂不支持其下创建子Span。
设置Data数据
设置执行单元内的Data数据
/// 设置data
function setData(key,value)
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| key | String | Data对应的key值。必传参数，空或空串接口调用无效。 | 字符串长度大于0，小于等于200，超过调用无效。 仅支持字母开头与结尾(中间可包含._-),否则调用无效。 |
| value | String | Data值。必传参数，空或空串接口调用无效。 | 字符串长度大于0，小于等于7000，超过截取。 |
-
示例
span.setData("key","value")
设置Tag数据
设置执行单元内的Tag数据
/// 设置tag
function setTag(key,value)
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| key | String | Tag对应的key值。必传参数，空或空串接口调用无效。 | 字符串长度大于0，小于等于200，超过调用无效。 仅支持字母开头与结尾(中间可包含._-),否则调用无效 |
| value | String | Tag值。必传参数，空或空串接口调用无效。 | 字符串长度大于0，小于等于7000，超过截取。 |
-
示例
span.setTag("key","tag")
设置Metric数据
/// 设置metric
function setMetric(key,value,unit)
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| key | String | Metric对应的key值。必传参数，空或空串接口调用无效。 | 字符串长度大于0，小于等于200，超过调用无效。 仅支持字母开头与结尾(中间可包含._-)，否则调用无效 |
| value | Number | Metric值。必传参数，空或空串接口调用无效。 | 无 |
| unit | String | Metric的单位名称。可选参数。 | 字符串长度大于0，小于等于256，超过仅单位设置无效 不包含特殊字符(仅支持字母数字下划线_连接符-斜杠/冒号:和符号@、符号.及符号空格)，否则单位设置无效。 |
-
示例
有单位设置
span.setMetric("tcp",100,"ms")无单位设置
span.setMetric("tcp",100);
移除Data数据
移除执行单元内的Data数据
/// 移除指定data
function removeData(key)
- 接口说明
| 参数名 | 类型 | 注释 |
|---|---|---|
| key | String | 要删除Data对应的key值 |
-
示例
span.removeData("key")
移除Tag数据
移除执行单元内的Tag数据
/// 移除指定tag
function removeTag(key)
- 接口说明
| 参数名 | 类型 | 注释 |
|---|---|---|
| key | String | 要删除Tag对应的key值 |
-
示例
span.removeTag("key")
移除Metric数据
移除执行单元内的Metric数据
/// 移除指定metric
function removeMetric(key)
- 接口说明
| 参数名 | 类型 | 注释 |
|---|---|---|
| key | String | 要删除Metric对应的key值 |
-
示例
span.removeMetric("key")
设置Status
设置执行单元的状态。
/// 设置span的状态
function setStatus(status)
- 接口说明
| 参数名 | 类型 | 注释 |
|---|---|---|
| status | Number | 参数status选填：[0:unknown，1:success，2:fail] |
-
示例
span.setStatus(1)
设置Duration
主动设置span耗时，如果未主动调用该方法，则span耗时为从start到finish的时长。
/// 设置span的耗时
function setDuration(duration)
- 接口说明
| 参数名 | 类型 | 注释 |
|---|---|---|
| duration | Number | 执行单元耗时，单位：微秒us。 |
-
示例
span.setDuration(100)
设置StatusCode
设置执行单元的状态码。
/// 设置span的状态码
function setStatusCode(statusCode)
- 接口说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| statusCode | String | 状态码值。 | 字符串长度大于0，小于等于7000，超过调用无效。 |
-
示例
span.setStatusCode("200")
四、使用插件
使用小程序SDK的插件，需先解压获取到的BonreeSDK_TDEM_MP_Wechat.zip文件，将对应的插件引入到项目中，并调用install方法注册插件。
数据加密插件
加密功能当前仅支持One平台。使用该功能前请务必先与技术支持或实施沟通获取加密Key，保证与平台配置一致，否则会导致SDK数据请求异常。抖音小程序中暂不支持该插件
-
解压获取到的
BonreeSDK_TDEM_MP_Wechat.zip文件，并将对应的borneeEncryptor.js在app.js中引入const BonreeSDK = require('./bonreeSDK_MP_Wechat.min.js')
const BorneeEncryptor = require('./borneeEncryptor.js') -
注册插件
const BonreeSDK = require('./bonreeSDK_MP_Wechat.min.js')
const BorneeEncryptor = require('./borneeEncryptor.js')
BonreeSDK.install(BorneeEncryptor,{key:string,identifier:string})
const BRSAgent = BonreeSDK.start(...)注：BonreeSDK.install方法需在BonreeSDK.start方法前调用
- 参数说明
| 参数名 | 类型 | 注释 | 参数限制 |
|---|---|---|---|
| key | String | 加密秘钥，从平台获取 | 需为16字节字符串，请勿使用< > & ' " %特殊字符 |
| identifier | String | 加密标识，从平台获取 | 字符串长度大于0且不超过256 不能包含中文及特殊字符 |
-
示例
const BonreeSDK = require('./bonreeSDK_MP_Wechat.min.js')
const BorneeEncryptor = require('./borneeEncryptor.js')
BonreeSDK.install(BorneeEncryptor,{key:'qawsedrftgyhujik',identifier:'v20'})
const BRSAgent = BonreeSDK.start(...)