Version: 3.7.0

Native 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 app.js file and start the SDK by calling the start method exposed on BonreeSDK.

Import in WeChat Mini Program:

const BonreeSDK = require('./bonreeSDK_MP_Wechat.min.js') 

Import in Douyin Mini Program:

const BonreeSDK = require('./bonreeSDK_MP_Tiktok.min.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

const BRSAgent = BonreeSDK.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

const BRSAgent = BonreeSDK.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

const BRSAgent = BonreeSDK.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

const BRSAgent = BonreeSDK.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

const BRSAgent = BonreeSDK.start({
    configAddress: "<#Config Address#>",
    appId: "<#AppID#>",
    timeout: 10000
})

2. Custom Function Interfaces

Generally, the calling location of custom interfaces is not in the mini program's entry file App.js, so you need to import the SDK instantiated object at the beginning of the file calling the interface:

const BRSAgent = require("../../app")

Normally, after directly typing the instantiated object in the code, WeChat/Douyin Developer Tools will automatically complete the object reference.

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
```
BRSAgent.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

BRSAgent.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

BRSAgent.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 setUserExtraInfo interface.

Example

BRSAgent.addUserExtraInfo("location","Beijing")
BRSAgent.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 setUserExtraInfo interface.

Example

BRSAgent.removeUserExtraInfo('name')
BRSAgent.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
```
BRSAgent.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

BRSAgent.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

BRSAgent.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
```
BRSAgent.removeEventAttribute(["b"])
```

4. Remove All Event Common Attributes

function removeAllEventAttributes()

Remove all event common attributes (including local).

Example
```
BRSAgent.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

BRSAgent.customPageStart("page01", "Home Page")

BRSAgent.customPageEnd("page01", "Home Page")

Note: The start and end recording interfaces for a custom view must be called in pairs, and the name for 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

BRSAgent.customEventStart("001", "User Login", "Login", "",{"key":"value"})
// Some code...
BRSAgent.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

BRSAgent.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

BRSAgent.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

BRSAgent.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.

function recordCustomActionEnd()

Usage Scenario

Take the login scenario as an example

Click the login button, triggering the onClickHandle method;
In the onClickHandle method, the login method 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

Page({
    ...
    onClickHandle:function(){
        ...
        login()
        BRSAgent.recordCustomActionEnd()
        ...
      // Other methods or requests  
    },
    login:function(){
        ...
    }
    ...
})

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

const BRSAgent = require("../../app")

const span=BRSAgent.startSpan('name','type')

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. The following interfaces are all instance methods of the execution unit (Span class).

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.zip file and import the corresponding borneeEncryptor.js in 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(...)

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

const BonreeSDK = require('./bonreeSDK_MP_Wechat.min.js') 
const BorneeEncryptor = require('./borneeEncryptor.js')

BonreeSDK.install(BorneeEncryptor,{key:'qawsedrftgyhujik',identifier:'v20'})

const BRSAgent = BonreeSDK.start(...)

1. Startup Configuration Interfaces​

BonreeSDK Startup Interface​

Set Mini Program Version​

Set Channel​

Set Custom Device ID​

Set Network Request Timeout​

2. Custom Function Interfaces​

Custom User Information​

1. Set User ID: Identify the user using a string. The interface is as follows:​

2. Set user additional information in object form. The interface is as follows:​

3. Set User Additional Information:​

4. Add User Additional Information​

5. Remove User Additional Information​

6. Accumulate User Additional Information​

Custom Event Attributes​

1. Add Event Common Attributes (Group)​

2. Add Event Common Attribute (Single)​

3. Remove Event Common Attributes​

4. Remove All Event Common Attributes​

Custom Views​

Custom Events (Full Version)​

Custom Events (Simplified Version)​

Custom Logs​

Custom Metrics​

Custom Action End​

3. Protocol Extension Interfaces​

Create Execution Unit​

Complete Execution Unit​

Create Child Execution Unit​

Set Data​

Set Tag Data​

Set Metric Data​

Remove Data​

Remove Tag Data​

Remove Metric Data​

Set Status​

Set Duration​

Set Status Code​

4. Using Plugins​

Data Encryption Plugin​

1. Startup Configuration Interfaces

BonreeSDK Startup Interface

Set Mini Program Version

Set Channel

Set Custom Device ID

Set Network Request Timeout

2. Custom Function Interfaces

Custom User Information

1. Set User ID: Identify the user using a string. The interface is as follows:

2. Set user additional information in object form. The interface is as follows:

3. Set User Additional Information:

4. Add User Additional Information

5. Remove User Additional Information

6. Accumulate User Additional Information

Custom Event Attributes

1. Add Event Common Attributes (Group)

2. Add Event Common Attribute (Single)

3. Remove Event Common Attributes

4. Remove All Event Common Attributes

Custom Views

Custom Events (Full Version)

Custom Events (Simplified Version)

Custom Logs

Custom Metrics

Custom Action End

3. Protocol Extension Interfaces

Create Execution Unit

Complete Execution Unit

Create Child Execution Unit

Set Data

Set Tag Data

Set Metric Data

Remove Data

Remove Tag Data

Remove Metric Data

Set Status

Set Duration

Set Status Code

4. Using Plugins

Data Encryption Plugin