Atomic Service

Integration

I. Pre-configure Bonree SDK Environment

Copy the atomic-signed.har file to the hars folder in the project root directory.

II. Add atomic-signed.har

2.1 Add the har package dependency to the dependencies field in the project's oh-package.json5: "@bonree/atomic": "file:./hars/atomic-signed.har"

Example configuration:

{
  "modelVersion": "5.0.0",
  "description": "Please describe the basic information.",
  "dependencies": {
    "@bonree/atomic": "file:./hars/atomic-signed.har" // Add this configuration to reference the Meta Service SDK
  },
  "devDependencies": {
    "@ohos/hypium": "1.0.18",
    "@ohos/hamock": "1.0.0"
  }
}

2.2 Use the new ohmurl concatenation and parsing method

Modify the useNormalizedOHMUrl in the project-level build-profile.json5 to true. If this configuration item does not exist, please add it manually.

{
  "app": {
    "products": [
      {
         "buildOption": {
           "strictMode": {
             "useNormalizedOHMUrl": true
           }
         }
      }
    ]
  }
}

III. Sync & Rebuild Project

Step 1:

Click [Sync Now] in the upper right corner.

If it doesn't appear, you can use the DevEco Studio shortcut: select Run 'ohpm install'

Step 2:

Rebuild the project to ensure the configuration takes effect.

Access

I. Configure Authorization Information

Check the application's module.json5 configuration file and ensure the following permissions are included as much as possible:

// The following permissions are necessary. For details, refer to the permission description section in the "Privacy Policy":
ohos.permission.INTERNET	        Send network data
ohos.permission.GET_NETWORK_INFO	Get network status information

II. Initialize SDK

Please obtain <#Config Address#> and <#AppID#> from the platform. For the method to obtain them, refer to How to Query AppID and Config Address?. Please contact technical support if you have any questions.

Please add the following code in the onCreate function of the custom AbilityStage in the entry module:

Bonree.withAppID("<#AppID#>")
   .withConfigAddress("<#Config Address#>")
   .start(this.context.getApplicationContext());

Sample Code:

import { Bonree } from '@bonree/atomic'
import AbilityStage from '@ohos.app.ability.AbilityStage'

export default class EntryAbilityStage extends AbilityStage {

  onCreate() {
    this.initBonreeSdk();
  }

  private initBonreeSdk() {
    Bonree.withAppID("<#AppID#>")
      .withConfigAddress("<#Config Address#>")
      .start(this.context.getApplicationContext());
  }
}

III. View/Launch Data Collection

Important Notes:

1. View data collection in child windows is temporarily not supported. Please ignore this step for views in child windows.

2. When using uiObserver.off() and UIObserver.off() series interfaces, you must pass the callback. If callback is not passed when calling off, all registrations will be canceled, causing abnormal SDK data collection.

4.1 Ability Data Collection

Add the @BonreeTrace.InjectAbility decorator to the subclass declaration of UIAbility.

import { BonreeTrace } from '@bonree/atomic';

@BonreeTrace.InjectAbility
export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {

  }

  onWindowStageCreate(windowStage: window.WindowStage): void {

  }

  onForeground(): void {

  }

  onBackground(): void {

  }

  onWindowStageDestroy(): void {

  }

  onDestroy() {

  }
}

4.2 AbilityStage Data Collection

Add the @BonreeTrace.InjectStage decorator to the subclass declaration of AbilityStage.

import { BonreeTrace } from '@bonree/atomic';

@BonreeTrace.InjectStage
export default class EntryAbilityStage extends AbilityStage {

  onCreate() {
  }

  onMemoryLevel(level: AbilityConstant.MemoryLevel): void {
  }
}

4.3 UI Page/Page Data Collection

Add the BonreeTrace.InjectPage(Index) interface call below all custom components decorated with @Entry and pass the current structure. The Page lifecycle functions (aboutToAppear, onPageShow, onPageHide, aboutToDisappear) should be overridden as much as possible; otherwise, it may affect snapshot data collection and performance accuracy.

import { BonreeTrace } from '@bonree/atomic';

@Entry
@Component
struct Index {
  build() {
  }

  aboutToAppear(): void {
  }

  onPageShow(): void {
  }

  onPageHide(): void {
  }

  aboutToDisappear(): void {
  }
}

BonreeTrace.InjectPage(Index)

V. Network Collection

Currently supports collection for the frameworks: ohos.net.http, ohos.net.webSocket. When collecting for the corresponding network framework, you need to use BonreeTrace to reference these framework classes. The API usage for each network framework is the same as the official documentation. Below are examples for each network collection.

5.1 'ohos.net.http'

Important Note: There are two mutually exclusive schemes for http. When integrating, you can only choose one.

Scheme One (Recommended):

Only need to add the BonreeTrace prefix reference before the http.createHttp API.

import { http } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { BonreeTrace } from '@bonree/atomic';

let httpRequest = BonreeTrace.http.createHttp(); // Add BonreeTrace prefix reference here
let options: http.HttpRequestOptions = {};
let promise = httpRequest.request(
   'request url', options
);
promise.then((responseData: http.HttpResponse) => {
}).catch((err: BusinessError) => {
})

Scheme Two:

Step 1 (Optional configuration): For end-to-end full link tracking, you need to insert Bonree's custom business request headers. If you don't need full link business, you can skip this step.

Important API Note: The custom business request header is returned based on URL rules. Each network request's custom header needs to be obtained and assigned separately. It is strictly forbidden to reuse the API call results for different requestUrl calls!

  function getInsertHeaderMap(requestUrl: string): Map<string, string> | undefined

Parameter	Description	Parameter Constraints	Failure Result
requestUrl	Request URL (Required)	string type. Valid request address	Current fetch is invalid

import http from '@ohos.net.http'
import { BonreeTrace } from '@bonree/atomic'

let httpRequest = http.createHttp();
let customHeaders: Record<string, string> = {};
// Add: Get end-to-end request headers here. If you don't have end-to-end business, you can skip this.
BonreeTrace.http.getInsertHeaderMap("Current request URL")?.forEach((value, key) => {
  customHeaders[key] = value;
})
let options: http.HttpRequestOptions = {
  header: customHeaders,
};
let promise = httpRequest.request("Current request URL", options);

Step 2 (Required configuration): Collect normal/abnormal network data

function handleSuccess(requestUrl: string, method: string, responseCode: number, requestDataSizeByte: number,
      downloadSizeByte: number, timing: OhosHttp.PerformanceTiming, remoteAddressIP?: string,
      requestHeader?: Record<string, Object>, responseHeader?: Record<string, Object>, resourceType?: string,
      optionsUsingProtocol?: string, requestBody?: string)

Parameter	Description	Parameter Constraints	Failure Result
requestUrl	Request URL (Required)	string type. Valid request address	Current network event not collected
method	Request method (Required)	string type. For non-http request methods, pass an empty string	Current network event not collected
responseCode	Response code (Required)	number type	Current network event not collected
requestDataSizeByte	Request upload data size (Required)	number type (Unit: Byte)	Current network event not collected
downloadSizeByte	Download size (Required)	number type (Unit: Byte)	Current network event not collected
timing	Time spent in each stage of the HTTP request (Required)	http.PerformanceTiming type	Current network event not collected
remoteAddressIP	Target address IP	string type	Current network event missing related field
requestHeader	Request header	Record<string, Object> type	Current network event missing related field
responseHeader	Response header	Record<string, Object> type	Current network event missing related field
resourceType	Resource type	string type. Follows the Content-Type field of MIME type	Current network event missing related field
optionsUsingProtocol	Protocol type	string type. Example: http.HttpProtocol.HTTP2.toString()	If value is invalid, it will be automatically obtained based on the URL
requestBody	Request content	string type	Current network event missing related field

function handleError(requestUrl: string, method: string, requestDataSizeByte: number, errorParam: Error,
      requestHeader?: Record<string, Object>) 

Parameter	Description	Parameter Constraints	Failure Result
requestUrl	Request URL (Required)	string type. Valid request address	Current network event not collected
method	Request method (Required)	string type. For non-http request methods, pass an empty string	Current network event not collected
requestDataSizeByte	Request upload data size (Required)	number type (Unit: Byte)	Current network event not collected
errorParam	Network Error (Required)	BusinessError type	Current network event not collected
requestHeader	Request header	Record<string, Object> type	Current network event missing related field

Example:

promise.then((responseData: http.HttpResponse) => {
  BonreeTrace.http.handleSuccess("Current request URL", "GET", responseData.responseCode, requestDataSize, downloadSize, responseData.performanceTiming);
}).catch((err: BusinessError) => {
  BonreeTrace.http.handleError("Current request URL", "GET", 0, err);
});

5.2 'ohos.net.webSocket'

Only need to add the BonreeTrace prefix reference before the webSocket.createWebSocket API.

import { webSocket } from '@kit.NetworkKit';
import { BonreeTrace } from '@bonree/atomic';

let webSocketInstance: webSocket.WebSocket = BonreeTrace.webSocket.createWebSocket(); // Add BonreeTrace prefix reference here

VI. Embedding Verification

Start the embedded APP and check the hilog logs. Filter for the BRSDK-Agent tag. The following logs indicate successful embedding and that data collection has started:

BRSDK-Agent   I   starting...         (Note: BRAgent integrated successfully)
BRSDK-Agent   I   Bonree token*****   (Note: BRAgent started successfully)
BRSDK-Agent   I   BRAgent connect server success (Note: BRAgent data setting successful)
BRSDK-Agent   I   BRAgent v***        (Note: *** corresponds to the BRAgent version in the current zip file name)