uni-app API
1. Startup Configuration Interfaces
Before calling the mini program SDK's startup interface, you need to import the mini program SDK at the beginning of the main.js file and start the SDK by calling the start method exposed on BonreeRUM.
Import when running in WeChat Mini Program:
import {BonreeRUM} from './bonreeSDK_MP_Wechat.min.esm.js'
Import when running in Douyin Mini Program:
import {BonreeRUM} from './bonreeSDK_MP_Tiktok.min.esm.js'
BonreeSDK Startup Interface
To start the mini program SDK, call the start function and set the Config address and AppID in the parameter object.
<#Config Address#> and <#AppID#> can be obtained from the platform. For the method to obtain them, please refer to How to Query AppID and Config Address?. If you have any questions, please contact technical support.
function start({
configAddress: "",
appId: ""
})
- Interface Description
| Parameter | Type | Description |
|---|---|---|
| configAddress | String | Config address |
| appId | String | The unique application ID generated by the Bonree SDK platform |
-
Example
BonreeRUM.start({
configAddress: "<#Config Address#>",
appId: "<#AppID#>"
})
Set Mini Program Version
The mini program version gets the real version number by default. If active configuration is required, set the version field in the startup interface parameters.
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| version | String | The version information to set | Maximum length not exceeding 64 |
-
Example
BonreeRUM.start({
configAddress: "<#Config Address#>",
appId: "<#AppID#>",
version: "1.0.0"
})
The default version number of the mini program is set when publishing in the mini program developer backend and cannot be obtained in the debug environment. It is recommended to set it according to the real version situation to ensure data integrity.
Set Channel
The mini program SDK supports channel information settings. Set the channelId field in the startup interface parameters.
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| channelId | String | The channel name to set | Maximum length not exceeding 256 |
-
Example
BonreeRUM.start({
configAddress: "<#Config Address#>",
appId: "<#AppID#>",
channelId: "channel001"
})
Set Custom Device ID
The device ID (deviceID) is generated by the SDK by default and saved in local storage. If active configuration is required, set the deviceId field in the startup interface parameters.
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| deviceId | String | The device ID to set | Maximum length not exceeding 256 |
-
Example
BonreeRUM.start({
configAddress: "<#Config Address#>",
appId: "<#AppID#>",
deviceId: "0123456789"
})
Set Network Request Timeout
Network request timeout (timeout) is used to configure the timeout time for config requests and upload requests. If not configured, it defaults to 60000ms timeout.
- Interface Description
| Parameter | Type | Description |
|---|---|---|
| timeout | number | Request timeout time (ms) |
-
Example
BonreeRUM.start({
configAddress: "<#Config Address#>",
appId: "<#AppID#>",
timeout: 10000
})
Set Error Collection
This configuration is mainly used to collect js error data in vue3. When the project does not use the onError method in the App.vue file to handle js errors, configure consoleError to collect js error data in vue3 projects. If the project uses the onError method in the App.vue file to handle js errors, you need to call the BonreeRUM.onError method in the onError method to obtain js error data. The use of the BonreeRUM.onError method please refer to Error Data Collection in Custom Function Interfaces. Vue2 projects do not need to pay attention to this configuration.
- Interface Description
| Parameter | Type | Description |
|---|---|---|
| consoleError | boolean | js error collection (vue3 project) |
-
Example
BonreeRUM.start({
configAddress: "<#Config Address#>",
appId: "<#AppID#>",
consoleError: true
})
2. Custom Function Interfaces
Using mini program SDK custom interfaces in uniapp. Import BonreeRUM in the script tag of the page that needs to use custom interfaces, and then call the custom methods mounted on BonreeRUM.
- Example
<script>
import {BonreeRUM} from './bonreeSDK_MP_Wechat.min.esm.js' // Import in WeChat Mini Program
// import {BonreeRUM} from './bonreeSDK_MP_Tiktok.min.esm.js' // Import in Douyin Mini Program
export default {
data() {
return {
title: 'operation'
}
},
onLoad() {
BonreeRUM.customEvent({...})
},
methods: {
...
}
}
</script>
Custom User Information
BonreeSDK supports setting user-related information to fulfill scenarios where performance data needs to be associated with actual users.
There are two ways to set user information:
1. Set User ID: Identify the user using a string. The interface is as follows:
/// Set User ID
function setUserId(userId)
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| userId | String | User ID | Can be empty or an empty string. String length less than or equal to 256, call invalid if exceeded. Allows Chinese characters, numbers, letters, colons, spaces, slashes, underscores, hyphens, English periods, @, #, *, ! |
-
Example
BonreeRUM.setUserId("1234")
2. Set user additional information in object form. The interface is as follows:
This interface has been deprecated, please use the setUserExtraInfo interface.
/// Set Additional Information
function setExtraInfo(extraInfo)
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| extraInfo | Object | User additional information. | Can be empty or an empty Map. The length after converting to JSON must be within 7000 characters, otherwise the interface call fails. |
-
Example
BonreeRUM.setExtraInfo({
key0: "value0",
key1: "value1"
})
3. Set User Additional Information
function setUserExtraInfo(extraInfo)
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| extraInfo | Object | User additional information | The effective kv quantity limit for fields is 64, take 64 if exceeded. key limit is a string of length (0, 256]. value limit is non-empty string, number, and boolean value. String length exceeds 512, truncate if exceeded |
-
Example
BonreeRUM.setUserExtraInfo({name:'jack'})
4. Add User Additional Information
function addUserExtraInfo(key,value)
-
Interface Description
The restrictions on key and value in this interface are the same as those in the
setUserExtraInfointerface. -
Example
BonreeRUM.addUserExtraInfo("location","Beijing")
BonreeRUM.addUserExtraInfo("age",18)
5. Remove User Additional Information
function removeUserExtraInfo(key)
-
Interface Description
The restriction on key in this interface is the same as that in the
setUserExtraInfointerface. -
Example
BonreeRUM.removeUserExtraInfo('name')
BonreeRUM.removeUserExtraInfo('location')
6. Accumulate User Additional Information
function increaseUserExtraInfo(key,value)
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| key | String | Key | Restrictions are the same as those in the setUserExtraInfo interface |
| value | Number | Value | Restricted to Number type |
-
Example
BonreeRUM.increaseUserExtraInfo('age',2)
Custom Event Attributes
1. Add Event Common Attributes (Group)
function addEventAttributes(attributes,local)
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| attributes | Object | Event common attributes | The effective kv quantity limit for fields is 64, take 64 if exceeded. key limit is a string of length (0, 256]. value limit is non-empty string, Number, Boolean. String length exceeds 512, truncate if exceeded |
| local | Boolean | Whether to persist to local | Attributes persisted to local will take effect automatically when the application starts next time. Attributes not persisted to local are only valid in the current process. |
-
Example
BonreeRUM.addEventAttributes({a:1}, false)
2. Add Event Common Attribute (Single)
function addEventAttributeWithKey(key,value,local)
Calling this interface is equivalent to calling addEventAttributes({key:value},local).
The restrictions on key and value in this interface, and the function of local are the same as those in the addEventAttributes({key:value},local) interface.
-
Example
BonreeRUM.addEventAttributeWithKey("b", 2, false)
3. Remove Event Common Attributes
function removeEventAttributeWithKeys(keys)
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| keys | Array | Array elements are the keys of the event common attributes to be removed | The restrictions on elements in the array are the same as those on key in the addEventAttributes interface |
Calling this interface will remove both the event common attributes in memory and locally (if they exist).
-
Example
BonreeRUM.removeEventAttribute(["b"])
4. Remove All Event Common Attributes
function removeAllEventAttributes()
Remove all event common attributes (including local).
-
Example
BonreeRUM.removeAllEventAttributes()
Custom Views
Call the interface with the corresponding parameters to complete the statistics collection for custom view data.
// Custom View - Mark View Start (called in pair with the view end method)
function customPageStart(name, alias)
// Custom View - Mark View End (called in pair with the view start method)
function customPageEnd(name, alias)
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| name | String | View name. Required parameter. Interface call is invalid if empty or null. | String length must be greater than 0 and less than or equal to 256, otherwise the interface call fails. |
| alias | String | View alias. Optional parameter. | Can be empty or an empty string. String length less than or equal to 256, truncated if too long. |
-
Example
BonreeRUM.customPageStart("page01", "Home Page")
BonreeRUM.customPageEnd("page01", "Home Page")
Note: The start and end recording interfaces for a custom view must be called in pairs, and the
namefor the same view must be consistent to correctly collect and report a complete custom view data.
Custom Events (Full Version)
Call the start and end interfaces respectively with the corresponding parameters to complete the statistics collection for custom event data and event duration.
// Custom event start
function customEventStart(eventId, eventName, eventLabel, eventParam, info)
// Custom event end
function customEventEnd(eventId, eventName, eventLabel, eventParam,info)
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| eventId | String | Event ID. Required parameter. Interface call is invalid if empty or null. | String length greater than 0, less than or equal to 256 |
| eventName | String | Event name, optional parameter. | Can be empty or an empty string. String length less than or equal to 256, truncated if too long. |
| eventLabel | String | Event label, optional parameter. | Can be empty or an empty string String length less than or equal to 256, truncated if too long. |
| eventParam | String | Event additional information, optional parameter. | Can be empty or an empty string String length less than or equal to 7000, truncated if too long. |
| info | Object | Event business information, optional parameter. | The length after converting to JSON must be within 7000 characters, otherwise the interface call fails. |
-
Example
BonreeRUM.customEventStart("001", "User Login", "Login", "",{"key":"value"})
// Some code...
BonreeRUM.customEventEnd("001", "User Login", "Login", "",{"key":"value"})
Note: 1. The start and end of a custom event are matched uniquely by eventID. Please ensure the uniqueness of the event ID for unfinished events. 2. The info parameter is of object type, and the key and value values in the object must be of string type.
Custom Events (Simplified Version)
Call the interface with the corresponding parameters to complete the statistics collection for custom event data.
/// Custom Event
function customEvent(eventId, eventName, eventLabel, eventParam, info)
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| eventId | String | Event ID. Required parameter. Interface call is invalid if empty or null. | String length must be greater than 0 and less than or equal to 256, otherwise the interface call fails. |
| eventName | String | Event name, optional parameter. | Can be empty or an empty string. String length less than or equal to 256, truncated if too long. |
| eventLabel | String | Event label, optional parameter. | Can be empty or an empty string String length less than or equal to 256, truncated if too long. |
| eventParam | String | Event additional information, optional parameter. | Can be empty or an empty string String length less than or equal to 7000, truncated if too long. |
| info | Object | Event business information, optional parameter. | The length after converting to JSON must be within 7000 characters, otherwise the interface call fails. |
-
Example
BonreeRUM.customEvent("001", "User Login", "Login", "",{"key":"value"})
Note: The info parameter is of object type, and the key and value values in the object must be of string type.
Custom Logs
Call the interface with the corresponding parameters to complete the statistics collection for custom log data.
/// Custom Log
function customLog(info, param)
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| info | String | Log information. Required parameter. Interface call is invalid if empty or null. | String length must be greater than 0, otherwise the interface call fails. String length less than or equal to 10000, truncated if too long. |
| param | String | Additional information (reserved field, no current usage scenario), optional parameter. | String length must be greater than 0, otherwise the interface call fails. String length less than or equal to 10000, truncated if too long. |
-
Example
BonreeRUM.customLog("2020-01-01 08:30:00 Print log info.")
Custom Metrics
Call the interface with the corresponding parameters to complete the statistics collection for custom metric data.
/// Custom Metric
function customMetric(metricName, metricValue, param)
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| metricName | String | Metric name. Required parameter. Interface call is invalid if empty or null. | String length must be greater than 0 and less than or equal to 256, otherwise the interface call fails. |
| metricValue | Number | Metric value. Required parameter. Interface call is invalid if the metric is empty. | - |
| param | String | Additional information (reserved field, no current usage scenario), optional parameter. | String length must be greater than 0, otherwise the interface call fails. String length less than or equal to 10000, truncated if too long. |
-
Example
BonreeRUM.customMetric("Test Metric 01", 1)
Custom Action End
Call this interface to end the operation matched based on the call stack. This method must be called directly or indirectly by the operation-related method, otherwise the call is invalid, only effective in vue2 projects.
function recordCustomActionEnd()
- Usage Scenario
Take the login scenario as an example
- Click the login button, triggering the
onClickHandlemethod; - In the
onClickHandlemethod, theloginmethod and some other methods are called;
If we only care about the time consumption and function call relationship data from triggering the login button to the end of calling the login method, and do not care about the data after the login method and other method executions, then we can call the custom operation end interface after the login method.
-
Example
<script>
import {BonreeRUM} from './bonreeSDK_MP_Wechat.min.esm.js' // Import in WeChat Mini Program
// import {BonreeRUM} from './bonreeSDK_MP_Tiktok.min.esm.js' // Import in Douyin Mini Program
export default {
data() {
return {}
},
onLoad() {},
methods: {
...
onClickHandle:function(){
...
login()
BonreeRUM.recordCustomActionEnd()
...
// Other methods or requests
},
login:function(){
...
}
...
}
}
</script>
Error Data Collection
Call this interface and pass in Error type data to complete the statistics collection for js error data.
function onError(Error)
- Interface Description
| Parameter | Type | Description |
|---|---|---|
| error | Error | Error information. Required parameter. Interface call is invalid if empty or null. |
-
Usage Scenario
In vue3 projects, when using the onError method in the App.vue file to handle js errors, it will cause the SDK to be unable to capture js errors. You need to call this API in the onError method to collect js error data.
-
Example
// APP.vue
<script>
import Vue from 'vue'
import {BonreeRUM} from './bonreeSDK_MP_Wechat.min.esm.js' // Import in WeChat Mini Program
// import {BonreeRUM} from './bonreeSDK_MP_Tiktok.min.esm.js' // Import in Douyin Mini Program
export default {
globalData: {},
onLaunch: function() {...},
onShow: function() {...},
onHide: function() {...},
onError:function(error){
...
BonreeRUM.onError(error)
...
}
}
</script>
3. Protocol Extension Interfaces
This chapter introduces the use and description of interfaces based on custom execution units.
Create Execution Unit
Call the creation interface to return an instance that implements the Span class.
/// Create span
function startSpan(name,type)
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| name | String | The name of the execution unit. Required parameter | String length greater than 0, less than or equal to 256, truncated if exceeded. Does not contain special characters (only letters, numbers, underscore _, hyphen -, slash /, colon :, and symbols @, ., and space), otherwise call is invalid. Pure space string interface call is invalid |
| type | String | The type of the execution unit. Required parameter | String length greater than 0, less than or equal to 256, truncated if exceeded. Does not contain special characters (only letters, numbers, underscore _, hyphen -, slash /, colon :, and symbols @, ., and space), otherwise call is invalid. Pure space string interface call is invalid |
| Return Type | Description |
|---|---|
| Span object | The created main span |
-
Example
<script>
import {BonreeRUM} from './bonreeSDK_MP_Wechat.min.esm.js' // Import in WeChat Mini Program
// import {BonreeRUM} from './bonreeSDK_MP_Tiktok.min.esm.js' // Import in Douyin Mini Program
export default {
data() {
return {}
},
onLoad() {},
methods: {
...
login:function(){
const span=BonreeRUM.startSpan('name','type')
}
...
}
}
</script>
Note: The creation interface, i.e., startSpan, must be called in pairs with the completion interface, i.e., finish.
The following interfaces are all instance methods of the execution unit (Span class).
Complete Execution Unit
Complete this execution unit. Calling other instance methods after completion is invalid.
/// Complete the span, and set the span status to status
function finish(status)
If setStatus is not called to set the span status, the span status is success.
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| status | number | Execution unit status. Optional parameter | Parameter status optional: [0:unknown,1:success,2:fail] |
-
Example
/// Called through the return value span after calling the startSpan interface
span.finish(1)
Note: The creation interface, i.e., startSpan, must be called in pairs with the completion interface, i.e., finish.
Create Child Execution Unit
Create a child execution unit on an execution unit, returning an instance of the Span class.
/// Create a child span
function startChild(name,type)
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| name | String | The name of the execution unit. Required parameter, interface call is invalid if empty or null. | String length greater than 0, less than or equal to 256, truncated if exceeded. Does not contain special characters (only letters, numbers, underscore _, hyphen -, slash /, colon :, and symbols @, ., and space), otherwise call is invalid. Pure space string interface call is invalid |
| type | String | The type of the execution unit. Required parameter, interface call is invalid if empty or null. | String length greater than 0, less than or equal to 256, truncated if exceeded. Does not contain special characters (only letters, numbers, underscore _, hyphen -, slash /, colon :, and symbols @, ., and space), otherwise call is invalid. Pure space string interface call is invalid (should be consistent with the parent span type, otherwise use the parent span type) |
| Return Type | Description |
|---|---|
| Span object | The created child span |
-
Example
const subSpan = span.startChild('name','type')
Note: When completing the parent execution unit, all its child execution units will be automatically completed (if the status has not been set, it defaults to success).
Currently, only single-layer child execution units are supported, that is, the top-level Span can create child Spans, but child Spans under child Spans are not supported.
When the Span type is one of the two reserved types, socket or websocket, creating child Spans under it is temporarily not supported.
Set Data
Set the Data data within the execution unit.
/// Set data
function setData(key,value)
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| key | String | The key value corresponding to Data. Required parameter, interface call is invalid if empty or null. | String length greater than 0, less than or equal to 200, call invalid if exceeded. Only supports letters starting and ending (middle can contain . _ -), otherwise call is invalid |
| value | String | Data value. Required parameter, interface call is invalid if empty or null. | String length greater than 0, less than or equal to 7000, truncated if exceeded. |
-
Example
span.setData("key","value")
Set Tag Data
Set the Tag data within the execution unit.
/// Set tag
function setTag(key,value)
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| key | String | The key value corresponding to Tag. Required parameter, interface call is invalid if empty or null. | String length greater than 0, less than or equal to 200, call invalid if exceeded. Only supports letters starting and ending (middle can contain . _ -), otherwise call is invalid |
| value | String | Tag value. Required parameter, interface call is invalid if empty or null. | String length greater than 0, less than or equal to 7000, truncated if exceeded. |
-
Example
span.setTag("key","tag")
Set Metric Data
/// Set metric
function setMetric(key,value,unit)
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| key | String | The key value corresponding to Metric. Required parameter, interface call is invalid if empty or null. | String length greater than 0, less than or equal to 200, call invalid if exceeded. Only supports letters starting and ending (middle can contain . _ -), otherwise call is invalid |
| value | Number | Metric value. Required parameter, interface call is invalid if empty or null. | None |
| unit | String | The unit name of the Metric. Optional parameter. | String length greater than 0, less than or equal to 256, only unit setting is invalid if exceeded Does not contain special characters (only letters, numbers, underscore _, hyphen -, slash /, colon :, and symbols @, ., and space), otherwise unit setting is invalid. |
-
Example
With unit setting
span.setMetric("tcp",100,"ms")Without unit setting
span.setMetric("tcp",100);
Remove Data
Remove the Data data within the execution unit.
/// Remove specified data
function removeData(key)
- Interface Description
| Parameter | Type | Description |
|---|---|---|
| key | String | The key value corresponding to the Data to be deleted |
-
Example
span.removeData("key")
Remove Tag Data
Remove the Tag data within the execution unit.
/// Remove specified tag
function removeTag(key)
- Interface Description
| Parameter | Type | Description |
|---|---|---|
| key | String | The key value corresponding to the Tag to be deleted |
-
Example
span.removeTag("key")
Remove Metric Data
Remove the Metric data within the execution unit.
/// Remove specified metric
function removeMetric(key)
- Interface Description
| Parameter | Type | Description |
|---|---|---|
| key | String | The key value corresponding to the Metric to be deleted |
-
Example
span.removeMetric("key")
Set Status
Set the status of the execution unit.
/// Set the status of the span
function setStatus(status)
- Interface Description
| Parameter | Type | Description |
|---|---|---|
| status | Number | Parameter status optional: [0:unknown,1:success,2:fail] |
-
Example
span.setStatus(1)
Set Duration
Actively set the span duration. If this method is not actively called, the span duration is the time from start to finish.
/// Set the duration of the span
function setDuration(duration)
- Interface Description
| Parameter | Type | Description |
|---|---|---|
| duration | Number | Execution unit duration, unit: microseconds us. |
-
Example
span.setDuration(100)
Set Status Code
Set the status code of the execution unit.
/// Set the status code of the span
function setStatusCode(statusCode)
- Interface Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| statusCode | String | Status code value. | String length greater than 0, less than or equal to 7000, call invalid if exceeded. |
-
Example
span.setStatusCode("200")
4. Using Plugins
To use the mini program SDK's plugins, first unzip the obtained BonreeSDK_TDEM_MP_Wechat.zip file, import the corresponding plugin into the project, and call the install method to register the plugin.
Data Encryption Plugin
Encryption function currently only supports the One platform. Before using this function, be sure to communicate with technical support or implementation to obtain the encryption Key to ensure consistency with the platform configuration, otherwise it will cause abnormal SDK data requests. This plugin is temporarily not supported in Douyin Mini Program.
-
Unzip the obtained
BonreeSDK_TDEM_MP_Wechat.zipfile and import the correspondingborneeEncryptor.esm.jsin main.jsimport {BonreeRUM} from './bonreeSDK_MP_Wechat.min.esm.js'
import BorneeEncryptor from '././borneeEncryptor.esm.js' -
Register Plugin
import {BonreeRUM} from './bonreeSDK_MP_Wechat.min.esm.js'
import BorneeEncryptor from '././borneeEncryptor.esm.js'
BonreeRUM.install(BorneeEncryptor,{key:string,identifier:string})
BonreeRUM.start(...)Note: The BonreeSDK.install method must be called before the BonreeSDK.start method.
- Parameter Description
| Parameter | Type | Description | Parameter Restrictions |
|---|---|---|---|
| key | String | Encryption key, obtained from the platform | Must be a 16-byte string, do not use < > & ' " % special characters |
| identifier | String | Encryption identifier, obtained from the platform | String length greater than 0 and not exceeding 256 Cannot contain Chinese characters and special characters |
-
Example
import {BonreeRUM} from './bonreeSDK_MP_Wechat.min.esm.js'
import BorneeEncryptor from '././borneeEncryptor.esm.js'
BonreeRUM.install(BorneeEncryptor,{key:'qawsedrftgyhujik',identifier:'v20'})
BonreeRUM.start(...)