uni-app API

一、启动配置接口

调用小程序SDK的启动接口前，需在main.js文件开头引入小程序SDK，通过调用SDK对外暴露的BonreeSDK上的start方法启动SDK

微信小程序中运行时引入：

import {BonreeRUM} from './bonreeSDK_MP_Wechat.min.esm.js'

抖音小程序中运行时引入：

import {BonreeRUM} from './bonreeSDK_MP_Tiktok.min.esm.js'

BonreeSDK启动接口

启动小程序SDK需要调用start函数，并在参数对象中设置Config地址与AppID。

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

function start({
    configAddress: "",
    appId: ""
})

• 接口说明

参数名	类型	注释
configAddress	String	Config地址
appId	String	博睿SDK平台生成的应用唯一ID

• 示例

  BonreeRUM.start({
      configAddress: "<#Config地址#>",
      appId: "<#AppID#>"
  })

设置小程序版本

小程序版本默认获取真实版本号。如有主动配置需求，需要启动接口参数中设置verson字段即可。

• 接口说明

参数名	类型	注释	参数限制
version	String	需要设置的版本信息	最大长度不超过64

• 示例

  BonreeRUM.start({
      configAddress: "<#Config地址#>",
      appId: "<#AppID#>",
      version: "1.0.0"
  })

小程序默认的版本号在小程序开发者后台中发布时设置，debug环境下获取不到，建议根据真实版本情况设置，保证数据的完整性。

设置渠道

小程序SDK支持渠道信息设置，在启动接口参数中设置channelId字段即可。

• 接口说明

参数名	类型	注释	参数限制
channelId	String	需要设置的渠道名称	最大长度不超过256

• 示例

  BonreeRUM.start({
      configAddress: "<#Config地址#>",
      appId: "<#AppID#>",
      channelId: "channel001"
  })

设置自定义的设备ID

设备ID（deviceID）默认由SDK生成并在local storage中保存。如有主动配置需求，在启动接口参数中设置deviceId字段即可。

• 接口说明

参数名	类型	注释	参数限制
deviceId	String	需要设置的设备ID	最大长度不超过256

• 示例

  BonreeRUM.start({
      configAddress: "<#Config地址#>",
      appId: "<#AppID#>",
      deviceId: "0123456789"
  })

设置网络请求超时

网络请求超时（timeout）用于配置config请求和upload请求的超时时间，若未配置，则默认60000ms超时。

• 接口说明

参数名	类型	注释
timeout	number	请求超时时间（ms）

• 示例

  BonreeRUM.start({
      configAddress: "<#Config地址#>",
      appId: "<#AppID#>",
      timeout: 10000
  })

设置错误采集

该配置主要用于采集vue3中的js错误数据，当项目中未在App.vue文件中使用onError方法来处理js错误时，通过配置consoleError来采集vue3项目中的js错误数据。若项目中在App.vue文件中使用onError方法来处理js错误时，需在onError方法中调用BonreeRUM.onError方法来获取js错误数据。BonreeRUM.onError方法的使用请参考自定义功能接口中的错误数据采集。使用vue2项目无需关注该配置。

• 接口说明

参数名	类型	注释
consoleError	boolean	js错误采集（vue3项目）

• 示例

  BonreeRUM.start({
      configAddress: "<#Config地址#>",
      appId: "<#AppID#>",
      consoleError: true
  })

二、自定义功能接口

uniapp中使用小程序SDK自定义接口。在需要使用自定义接口页面的script标签中引入BonreeRUM，再调用挂载在BonreeRUM上的自定义方法。

• 示例

<script>
import {BonreeRUM} from './bonreeSDK_MP_Wechat.min.esm.js'    // 微信小程序中引入
// import {BonreeRUM} from './bonreeSDK_MP_Tiktok.min.esm.js' // 抖音小程序中引入
export default {
    data() {
        return {
            title: 'operation'
        }
    },
    onLoad() {
        BonreeRUM.customEvent({...})
    },
    methods: {
        ...
    }
}
</script>

自定义用户信息

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

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

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

/// 设置用户ID
function setUserId(userId)

• 接口说明

参数名	类型	注释	参数限制
userId	String	用户ID	字符串可为空或空串。 字符串小于等于256，超过调用无效。允许中文、数字、字母、冒号、空格、斜杠、下划线、连字符、英文句号、@、#、*、!

• 示例

  BonreeRUM.setUserId("1234")

2. 以对象形式设置用户附加信息。接口如下：

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

/// 设置附加信息
function setExtraInfo(extraInfo)

• 接口说明

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

• 示例

  BonreeRUM.setExtraInfo({
      key0: "value0",
      key1: "value1"
  })

3. 设置用户附加信息

function setUserExtraInfo(extraInfo)

• 接口说明

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

• 示例

  BonreeRUM.setUserExtraInfo({name:'jack'})

4. 添加用户附加信息

function addUserExtraInfo(key,value)

• 接口说明

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

• 示例

  BonreeRUM.addUserExtraInfo("location","Beijing")
  BonreeRUM.addUserExtraInfo("age",18)

5. 移除用户附加信息

function removeUserExtraInfo(key)

• 接口说明

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

• 示例

  BonreeRUM.removeUserExtraInfo('name')
  BonreeRUM.removeUserExtraInfo('location')

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

function increaseUserExtraInfo(key,value)

• 接口说明

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

• 示例

  BonreeRUM.increaseUserExtraInfo('age',2)

自定义事件属性

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

function addEventAttributes(attributes,local)

• 接口说明

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

• 示例

  BonreeRUM.addEventAttributes({a:1}, false)

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

function addEventAttributeWithKey(key,value,local)

调用该接口，与调用addEventAttributes({key:value},local)等价。

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

• 示例

  BonreeRUM.addEventAttributeWithKey("b", 2, false)

3. 移除事件公共属性

function removeEventAttributeWithKeys(keys)

• 接口说明

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

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

• 示例

  BonreeRUM.removeEventAttribute(["b"])

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

function removeAllEventAttributes()

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

• 示例

  BonreeRUM.removeAllEventAttributes()

自定义视图

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

// 自定义视图——标记视图开始（和视图结束方法成对调用）
function customPageStart(name, alias)

// 自定义视图——标记视图结束（和视图开始方法成对调用）
function customPageEnd(name, alias)

• 接口说明

参数名	类型	注释	参数限制
name	String	视图名称。必传参数，空或空串接口调用无效。	字符串长度大于0，小于等于256，否则接口调用失败。
alias	String	视图别名。可选参数。	字符串可为空或空串。 字符串小于等于256，超长截取。

• 示例

  BonreeRUM.customPageStart("page01", "首页")
  
  BonreeRUM.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字符以内，否则接口调用失败。

• 示例

  BonreeRUM.customEventStart("001", "用户登录", "Login", "",{"key":"value"})
  // Some code...
  BonreeRUM.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字符以内，否则接口调用失败。

• 示例

  BonreeRUM.customEvent("001", "用户登录", "Login", "",{"key":"value"})

注意：info参数为object类型，对象中的key和value值需为string类型

自定义日志

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

/// 自定义日志
function customLog(info, param)

• 接口说明

参数名	类型	注释	参数限制
info	String	日志信息。必传参数，空或空串接口调用无效。	字符串长度大于0，否则接口调用失败。 字符串小于等于10000，超长截取。
param	String	附加信息（预留字段，暂无使用场景），可选参数。	字符串长度大于0，否则接口调用失败。 字符串小于等于10000，超长截取。

• 示例

  BonreeRUM.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，超长截取。

• 示例

  BonreeRUM.customMetric("测试指标01", 1)

自定义操作结束

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

function recordCustomActionEnd()

• 使用场景

以登录场景为例

1. 点击登录按钮，触发 onClickHandle 方法；
2. onClickHandle 方法中，调用了 login 方法和其他的一些方法；

如果我们只关注触发登录按钮到调用login方法结束时的耗时及函数调用关系等数据，不关注login方法后等其他方法执行的数据，那么我们可以在 login 方法后调用自定义操作结束接口。

• 示例

  <script>
  import {BonreeRUM} from './bonreeSDK_MP_Wechat.min.esm.js'    // 微信小程序中引入
  // import {BonreeRUM} from './bonreeSDK_MP_Tiktok.min.esm.js' // 抖音小程序中引入
  export default {
      data() {
          return {}
      },
      onLoad() {},
      methods: {
          ...
          onClickHandle:function(){
              ...
              login()
              BonreeRUM.recordCustomActionEnd()
              ...
            // 其他方法或请求  
          },
          login:function(){
              ...
          }
          ...
      }
  }
  </script>

错误数据采集

调用该接口，并传入Error类型的数据，可完成js错误数据的统计功能。

function onError(Error)

• 接口说明

参数名	类型	注释
error	Error	报错信息。必传参数，空或空串接口调用无效。

• 使用场景

  vue3项目中，当在App.vue文件中使用onError方法来处理js错误时，会导致SDK无法捕获js错误，需通过在onError方法中调用该API来采集js错误数据

• 示例

  // APP.vue
  <script>
  import Vue from 'vue'
  import {BonreeRUM} from './bonreeSDK_MP_Wechat.min.esm.js'    // 微信小程序中引入
  // import {BonreeRUM} from './bonreeSDK_MP_Tiktok.min.esm.js' // 抖音小程序中引入
  export default {
  	globalData: {},
  	onLaunch: function() {...},
  	onShow: function() {...},
  	onHide: function() {...},
  	onError:function(error){
          ...
  		BonreeRUM.onError(error)
  		...
  	}
  }
  </script>

三、协议扩展接口

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

创建执行单元

调用创建接口，返回实现了Span类的实例。

/// 创建span
function startSpan(name,type)

• 接口说明

参数名	类型	注释	参数限制
name	String	执行单元的名称。必传参数	字符串长度大于0，小于等于256，超过截取。 不包含特殊字符(仅支持字母数字下划线_连接符-斜杠/冒号:和符号@、符号.及符号空格)，否则调用无效。 纯空格字符串接口调用无效
type	String	执行单元的类型。必传参数	字符串长度大于0，小于等于256，超过截取。 不包含特殊字符(仅支持字母数字下划线_连接符-斜杠/冒号:和符号@、符号.及符号空格)，否则调用无效。 纯空格字符串接口调用无效

返回值类型	注释
Span对象	创建的主span

• 示例

  <script>
  import {BonreeRUM} from './bonreeSDK_MP_Wechat.min.esm.js'    // 微信小程序中引入
  // import {BonreeRUM} from './bonreeSDK_MP_Tiktok.min.esm.js' // 抖音小程序中引入
  
  export default {
      data() {
          return {}
      },
      onLoad() {},
      methods: {
          ...
          login:function(){
             const span=BonreeRUM.startSpan('name','type') 
          }
          ...
      }
  }
  </script>

注意：创建接口即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
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.esm.js在main.js中引入

  import {BonreeRUM} from './bonreeSDK_MP_Wechat.min.esm.js' 
  import BorneeEncryptor from '././borneeEncryptor.esm.js'

• 注册插件

  import {BonreeRUM} from './bonreeSDK_MP_Wechat.min.esm.js' 
  import BorneeEncryptor from '././borneeEncryptor.esm.js'
  
  BonreeRUM.install(BorneeEncryptor,{key:string,identifier:string})
  
  BonreeRUM.start(...)

  注：BonreeSDK.install方法需在BonreeSDK.start方法前调用

• 参数说明

参数名	类型	注释	参数限制
key	String	加密秘钥，从平台获取	需为16字节字符串，请勿使用< > & ' " %特殊字符
identifier	String	加密标识，从平台获取	字符串长度大于0且不超过256 不能包含中文及特殊字符

• 示例

  import {BonreeRUM} from './bonreeSDK_MP_Wechat.min.esm.js' 
  import BorneeEncryptor from '././borneeEncryptor.esm.js'
  
  BonreeRUM.install(BorneeEncryptor,{key:'qawsedrftgyhujik',identifier:'v20'})
  
  BonreeRUM.start(...)