跳到主要内容

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'

支付宝小程序中运行时引入：

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

BonreeSDK启动接口​

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

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

function start({
    configAddress: "",
    appId: ""
})
  • 接口说明
参数名类型注释
configAddressStringConfig地址
appIdString博睿SDK平台生成的应用唯一ID

  • 示例

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

设置小程序版本​

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

  • 接口说明
参数名类型注释参数限制
versionString需要设置的版本信息最大长度不超过64

  • 示例

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

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

设置渠道​

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

  • 接口说明
参数名类型注释参数限制
channelIdString需要设置的渠道名称最大长度不超过256

  • 示例

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

设置自定义的设备ID​

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

  • 接口说明
参数名类型注释参数限制
deviceIdString需要设置的设备ID最大长度不超过256

  • 示例

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

设置网络请求超时​

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

  • 接口说明
参数名类型注释
timeoutnumber请求超时时间（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项目无需关注该配置。

  • 接口说明
参数名类型注释
consoleErrorbooleanjs错误采集（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' // 抖音小程序中引入
// import {BonreeRUM} from './bonreeSDK_MP_Alipay.min.esm.js' // 支付宝小程序中引入
export default {
    data() {
        return {
            title: 'operation'
        }
    },
    onLoad() {
        BonreeRUM.customEvent({...})
    },
    methods: {
        ...
    }
}
</script>

自定义用户信息​

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

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

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

/// 设置用户ID
function setUserId(userId)
  • 接口说明
参数名类型注释参数限制
userIdString用户ID字符串可为空或空串。
字符串小于等于256，超过调用无效。允许中文、数字、字母、冒号、空格、斜杠、下划线、连字符、英文句号、@、#、*、!

  • 示例

    BonreeRUM.setUserId("1234")

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

/// 设置附加信息
function setExtraInfo(extraInfo)
  • 接口说明
参数名类型注释参数限制
extraInfoObject用户附加信息。Map可为空或空集合。
转JSON后长度在7000字符以内，否则接口调用失败。

  • 示例

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

3. 设置用户附加信息​

function setUserExtraInfo(extraInfo)
  • 接口说明
参数名类型注释参数限制
extraInfoObject用户附加信息字段的有效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)
  • 接口说明
参数名类型注释参数限制
keyString键限制与setUserExtraInfo接口中的限制相同
valueNumber值限制为Number类型

  • 示例

    BonreeRUM.increaseUserExtraInfo('age',2)

自定义事件属性​

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

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

  • 示例

    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)
  • 接口说明
参数名类型注释参数限制
keysArray数组元素为要移除的事件公共属性的key数组中元素的限制与addEventAttributes接口中key的限制相同

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

  • 示例

    BonreeRUM.removeEventAttribute(["b"])

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

function removeAllEventAttributes()

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

  • 示例

    BonreeRUM.removeAllEventAttributes()

自定义异常​

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

/// 自定义异常
function customException(exceptionType, causedBy, errorDump)
  • 接口说明
参数名类型注释参数限制
exceptionTypeString异常类型。必传参数，空或空串接口调用无效。字符串长度大于0，小于等于256，否则接口调用失败。
causedByString异常原因字符串可为空或空串。
字符串小于等于512，超长截取。
errorDumpString异常堆栈超出10000字符时会被切割

  • 示例

    BonreeRUM.customException("Custom exception type", "Caused by customer.", "Custom error dump 0\nCustom error dump 1")

自定义事件（完整版）​

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

// 自定义事件开始
function customEventStart(eventId, eventName, eventLabel, eventParam, info)

// 自定义事件结束
function customEventEnd(eventId, eventName, eventLabel, eventParam,info)
  • 接口说明
参数名类型注释参数限制
eventIdString事件ID。必传参数，空或空串接口调用无效。字符串长度大于0，小于等于256
eventNameString事件名称，可选参数。字符串可为空或空串。
字符串小于等于256，超长截取。
eventLabelString事件标签，可选参数。字符串可为空或空串
字符串小于等于256，超长截取。
eventParamString事件附加信息，可选参数。字符串可为空或空串
字符串小于等于7000，超长截取。
infoObject事件业务信息，可选参数。转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)
  • 接口说明
参数名类型注释参数限制
eventIdString事件ID。必传参数，空或空串接口调用无效。字符串长度大于0，小于等于256，否则接口调用失败。
eventNameString事件名称，可选参数。字符串可为空或空串。
字符串小于等于256，超长截取。
eventLabelString事件标签，可选参数。字符串可为空或空串
字符串小于等于256，超长截取。
eventParamString事件附加信息，可选参数。字符串可为空或空串
字符串小于等于7000，超长截取。
infoObject事件业务信息，可选参数。转JSON后长度在7000字符以内，否则接口调用失败。

  • 示例

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

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

自定义日志​

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

/// 自定义日志
function customLog(info, param)
  • 接口说明
参数名类型注释参数限制
infoString日志信息。必传参数，空或空串接口调用无效。字符串长度大于0，否则接口调用失败。
字符串小于等于10000，超长截取。
paramString附加信息（预留字段，暂无使用场景），可选参数。字符串长度大于0，否则接口调用失败。
字符串小于等于10000，超长截取。

  • 示例

    BonreeRUM.customLog("2020-01-01 08:30:00 Print log info.")

自定义指标​

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

/// 自定义指标
function customMetric(metricName, metricValue, param)
  • 接口说明
参数名类型注释参数限制
metricNameString指标名称。必传参数，空或空串接口调用无效。字符串长度大于0，小于等于256，否则接口调用失败。
metricValueNumber指标值。必传参数，指标为空接口调用无效。-
paramString附加信息（预留字段，暂无使用场景），可选参数。字符串长度大于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' // 抖音小程序中引入
    // import {BonreeRUM} from './bonreeSDK_MP_Alipay.min.esm.js' // 支付宝小程序中引入
    export default {
        data() {
            return {}
        },
        onLoad() {},
        methods: {
            ...
            onClickHandle:function(){
                ...
                login()
                BonreeRUM.recordCustomActionEnd()
                ...
              // 其他方法或请求  
            },
            login:function(){
                ...
            }
            ...
        }
    }
    </script>

错误数据采集​

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

function onError(Error)
  • 接口说明
参数名类型注释
errorError报错信息。必传参数，空或空串接口调用无效。

  • 使用场景

    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' // 抖音小程序中引入
    // import {BonreeRUM} from './bonreeSDK_MP_Alipay.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)
  • 接口说明
参数名类型注释参数限制
nameString执行单元的名称。必传参数字符串长度大于0，小于等于256，超过截取。
不包含特殊字符(仅支持字母数字下划线_连接符-斜杠/冒号:和符号@、符号.及符号空格)，否则调用无效。
纯空格字符串接口调用无效
typeString执行单元的类型。必传参数字符串长度大于0，小于等于256，超过截取。
不包含特殊字符(仅支持字母数字下划线_连接符-斜杠/冒号:和符号@、符号.及符号空格)，否则调用无效。
纯空格字符串接口调用无效
返回值类型注释
Span对象创建的主span

  • 示例

    <script>
    import {BonreeRUM} from './bonreeSDK_MP_Wechat.min.esm.js'    // 微信小程序中引入
    // import {BonreeRUM} from './bonreeSDK_MP_Tiktok.min.esm.js' // 抖音小程序中引入
    // import {BonreeRUM} from './bonreeSDK_MP_Alipay.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。

  • 接口说明
参数名类型注释参数限制
statusnumber执行单元状态。可选参数参数status选填：[0:unknown，1:success，2:fail]

  • 示例

    /// 通过调用startSpan接口后的返回值span调用
    span.finish(1)

注意：创建接口即startSpan需和完成接口即finish成对调用。

创建子执行单元​

在一个执行单元上创建一个子执行单元，返回Span类的实例。

/// 创建一个子span
function startChild(name,type)
  • 接口说明
参数名类型注释参数限制
nameString执行单元的名称。必传参数，空或空串接口调用无效。字符串长度大于0，小于等于256，超过截取。
不包含特殊字符(仅支持字母数字下划线_连接符-斜杠/冒号:和符号@、符号.及符号空格)，否则调用无效。
纯空格字符串接口调用无效
typeString执行单元的类型。必传参数，空或空串接口调用无效。字符串长度大于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)
  • 接口说明
参数名类型注释参数限制
keyStringData对应的key值。必传参数，空或空串接口调用无效。字符串长度大于0，小于等于200，超过调用无效。
仅支持字母开头与结尾(中间可包含._-),否则调用无效
valueStringData值。必传参数，空或空串接口调用无效。字符串长度大于0，小于等于7000，超过截取。

  • 示例

    span.setData("key","value")

设置Tag数据​

设置执行单元内的Tag数据

/// 设置tag
function setTag(key,value)
  • 接口说明
参数名类型注释参数限制
keyStringTag对应的key值。必传参数，空或空串接口调用无效。字符串长度大于0，小于等于200，超过调用无效。
仅支持字母开头与结尾(中间可包含._-),否则调用无效
valueStringTag值。必传参数，空或空串接口调用无效。字符串长度大于0，小于等于7000，超过截取。

  • 示例

    span.setTag("key","tag")

设置Metric数据​

/// 设置metric
function setMetric(key,value,unit)
  • 接口说明
参数名类型注释参数限制
keyStringMetric对应的key值。必传参数，空或空串接口调用无效。字符串长度大于0，小于等于200，超过调用无效。
仅支持字母开头与结尾(中间可包含._-),否则调用无效
valueNumberMetric值。必传参数，空或空串接口调用无效。无
unitStringMetric的单位名称。可选参数。字符串长度大于0，小于等于256，超过仅单位设置无效
不包含特殊字符(仅支持字母数字下划线_连接符-斜杠/冒号:和符号@、符号.及符号空格)，否则单位设置无效。

  • 示例

    有单位设置

    span.setMetric("tcp",100,"ms")

    无单位设置

    span.setMetric("tcp",100);

移除Data数据​

移除执行单元内的Data数据

/// 移除指定data
function removeData(key)
  • 接口说明
参数名类型注释
keyString要删除Data对应的key值

  • 示例

    span.removeData("key")

移除Tag数据​

移除执行单元内的Tag数据

/// 移除指定tag
function removeTag(key)
  • 接口说明
参数名类型注释
keyString要删除Tag对应的key值

  • 示例

    span.removeTag("key")

移除Metric数据​

移除执行单元内的Metric数据

/// 移除指定metric
function removeMetric(key)
  • 接口说明
参数名类型注释
keyString要删除Metric对应的key值

  • 示例

    span.removeMetric("key")

设置Status​

设置执行单元的状态。

/// 设置span的状态
function setStatus(status)
  • 接口说明
参数名类型注释
statusNumber参数status选填：[0:unknown，1:success，2:fail]

  • 示例

    span.setStatus(1)

设置Duration​

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

/// 设置span的耗时
function setDuration(duration)
  • 接口说明
参数名类型注释
durationNumber执行单元耗时，单位：微秒us。

  • 示例

    span.setDuration(100)

设置StatusCode​

设置执行单元的状态码。

/// 设置span的状态码
function setStatusCode(statusCode)
  • 接口说明
参数名类型注释参数限制
statusCodeString状态码值。字符串长度大于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方法前调用

  • 参数说明
参数名类型注释参数限制
keyString加密秘钥，从平台获取需为16字节字符串，请勿使用< > & ' " %特殊字符
identifierString加密标识，从平台获取字符串长度大于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(...)