元服务

SDK 的所有 API 暂不支持在 TaskPool、Worker，以及 NAPI/C++ 创建的原生线程中调用。

集成

一、预置Bonree SDK环境

拷贝atomic-signed.har到工程级目录中的hars文件夹

二、添加atomic-signed.har

2.1 在工程的oh-package.json5中`dependencies`字段增加har包依赖 `"@bonree/atomic": "file:./hars/atomic-signed.har"`

配置示例如下：

{
  "modelVersion": "5.0.0",
  "description": "Please describe the basic information.",
  "dependencies": {
    "@bonree/atomic": "file:./hars/atomic-signed.har" // 这里要添加配置,用于引用元服务SDK 
  },
  "devDependencies": {
    "@ohos/hypium": "1.0.18",
    "@ohos/hamock": "1.0.0"
  }
}

2.2 使用ohmurl新的拼接和解析方式

将工程级build-profile.json5中的useNormalizedOHMUrl修改为true, 若没有该配置项请手动添加。

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

三、Sync & Rebuid 项目

第一步:

点击右上角的 [ Sync Now ]

若未出现，可使用 DevEco Studio 快捷键解决，选择 Run 'ohpm install'

第二步:

Rebuild项目，确保配置生效。

接入

一、配置授权信息

检查应用程序module.json5配置文件，尽量确保已引入如下授权：

//下列权限都是必要权限，详情可参阅《隐私政策》中权限说明部分:
ohos.permission.INTERNET	        发送网络数据
ohos.permission.GET_NETWORK_INFO	获取网络状态信息

二、初始化SDK

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

请在入口entry moudle自定义AbilityStage中的onCreate函数中，添加如下代码：

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

样例代码：

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地址#>")
      .start(this.context.getApplicationContext());
  }
}

三、视图/启动数据采集

重要说明:

1.暂不支持子窗口中的视图数据采集，子窗口中的视图忽略本步骤。

2.使用uiObserver.off()和UIObserver.off()系列接口时务必传入callback，若off时不传callback会取消掉所有的注册，导致SDK数据采集异常。

4.1 Ability 数据采集

在UIAbility的子类声明上添加 @BonreeTrace.InjectAbility 装饰器

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 数据采集

在AbilityStage的子类声明上添加 @BonreeTrace.InjectStage 装饰器

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

@BonreeTrace.InjectStage
export default class EntryAbilityStage extends AbilityStage {

  onCreate() {
  }

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

4.3 UI页面/Page 数据采集

在所有@Entry装饰的自定义组件下面添加 BonreeTrace.InjectPage(Index) 接口调用并传入当前结构, Page生命周期( aboutToAppear,onPageShow,onPageHide,aboutToDisappear)函数尽量复写,否则影响快照数据采集和性能准确性

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

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

  aboutToAppear(): void {
  }

  onPageShow(): void {
  }

  onPageHide(): void {
  }

  aboutToDisappear(): void {
  }
}

BonreeTrace.InjectPage(Index)

五、网络采集

目前支持采集框架 ohos.net.http，ohos.net.webSocket，当采集对应网络框架时，需要使用 BonreeTrace 引用这些框架类，各网络框架API使用同官网文档，如下是每个网络采集示例。

**5.1 'ohos.net.http' **

重要说明: http共有两种方案, 属于互斥方案, 当您集成时只能二选一

方案一（推荐）:

仅需要在http.createHttpAPI前添加BonreeTrace开头引用。

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

let httpRequest = BonreeTrace.http.createHttp(); // 这里要添加 BonreeTrace 开头引用
let options: http.HttpRequestOptions = {};
let promise = httpRequest.request(
   'request url', options
);
promise.then((responseData: http.HttpResponse) => {
}).catch((err: BusinessError) => {
})

方案二:

第一步（可选配置）：端对端的全链路打通需要在请求头中插入Bonree的自定义业务请求头，如不需要全链路业务可跳过此步骤。

API重要说明: 自定义业务请求头是根据URL规则返回，每条网络请求自定义头都需要重新获取赋值，非同一个requestUrl的API调用结果严禁复用!

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

参数	说明	参数限制	失败结果
requestUrl	请求URL(必要)	string类型。有效请求地址	当次获取无效

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

let httpRequest = http.createHttp();
let customHeaders: Record<string, string> = {};
// 这里要添加 获取端到端请求头，若您没有端到端业务，可跳过
BonreeTrace.http.getInsertHeaderMap("本次请求的URL")?.forEach((value, key) => {
  customHeaders[key] = value;
})
let options: http.HttpRequestOptions = {
  header: customHeaders,
};
let promise = httpRequest.request("本次请求的URL", options);

第二步（必要配置）：采集正常/异常网络数据

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)

参数	说明	参数限制	失败结果
requestUrl	请求URL(必要)	string类型。有效请求地址	当次网络事件不采集
method	请求方法(必要)	string类型。非http请求方法，传空字符串即可	当次网络事件不采集
responseCode	响应码(必要)	number类型	当次网络事件不采集
requestDataSizeByte	请求上传数据大小(必要)	number类型(单位Byte)	当次网络事件不采集
downloadSizeByte	下载大小(必要)	number类型(单位Byte)	当次网络事件不采集
timing	HTTP 请求各个阶段所花费的时间(必要)	http.PerformanceTiming类型	当次网络事件不采集
remoteAddressIP	目标地址IP	string类型	当次网络事件缺失相关字段
requestHeader	请求header	`Record<string, Object>类型`	当次网络事件缺失相关字段
responseHeader	响应header	`Record<string, Object>类型`	当次网络事件缺失相关字段
resourceType	资源类型	string类型。遵循MIME类型的Content-Type字段	当次网络事件缺失相关字段
optionsUsingProtocol	协议类型	string类型。示例：http.HttpProtocol.HTTP2.toString()	值无效则会根据url自动获取
requestBody	请求内容	string类型	当次网络事件缺失相关字段

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

参数	说明	参数限制	失败结果
requestUrl	请求URL(必要)	string类型。有效请求地址	当次网络事件不采集
method	请求方法(必要)	string类型。非http请求方法，传空字符串即可	当次网络事件不采集
requestDataSizeByte	请求上传数据大小(必要)	number类型(单位Byte)	当次网络事件不采集
errorParam	网络Error错误(必要)	BusinessError类型	当次网络事件不采集
requestHeader	请求header	`Record<string, Object>类型`	当次网络事件缺失相关字段

示例如下:

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

**5.2 'ohos.net.webSocket' **

仅需要在webSocket.createWebSocketAPI前添加BonreeTrace开头引用。

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

let webSocketInstance: webSocket.WebSocket = BonreeTrace.webSocket.createWebSocket(); // 这里要添加 BonreeTrace 开头引用

六、嵌码验证

启动已嵌码的APP，查看hilog日志，搜索过滤BRSDK-Agent标签，出现如下log则表示嵌码成功且数据开始采集：

BRSDK-Agent   I   starting...         （注：BRAgent 集成成功）
BRSDK-Agent   I   Bonree token*****   （注：BRAgent 启动成功）
BRSDK-Agent   I   BRAgent connect server success （注：BRAgent 数据设置成功）
BRSDK-Agent   I   BRAgent v***        （注： ***为当前zip包文件名后所对应的BRAgent版本）

注意：建议您嵌码完成后，立即到平台安装部署/规则配置/数据采集/终端应用配置采集规则，避免平台数据和您预期不一致。

集成​

一、预置Bonree SDK环境​

二、添加atomic-signed.har​

2.1 在工程的oh-package.json5中dependencies字段增加har包依赖 "@bonree/atomic": "file:./hars/atomic-signed.har"​

2.2 使用ohmurl新的拼接和解析方式​

三、Sync & Rebuid 项目​

接入​

一、配置授权信息​

二、初始化SDK​

三、视图/启动数据采集​

五、网络采集​

六、嵌码验证​

集成