HarmonyOS NEXT 部署

基调听云用户体验监控 SDK Harmony端集成部署说明

环境需求

最低支持: HarmonyOS开发者版本（即API版本）5.0.0(API 12 Release)

安装SDK

远程安装

进入工程根目录，执行以下命令

ohpm install @tingyun/sdk-core

如果需要安装指定版本的SDK, 可手动指定版本（<version>为具体的版本号）

ohpm install @tingyun/sdk-core@<version>

内网仓库安装

内网环境用户建议将涉及到的har包上传至企业内网仓库后，通过内网仓库完成安装操作

在听云控制台管理-下载中心-App端-Harmony中下载最新SDK，解压下载的zip，将tingyun-core_version.har上传至企业内网仓库进入工程根目录，执行以下命令

ohpm install @tingyun/sdk-core

如果需要安装指定版本的插件, 可手动指定版本（<version>为具体的版本号）

ohpm install @tingyun/sdk-core@<version>

确认项目适配字节码格式HAR包

SDK HAR包为字节码格式, 需要将工程级build-profile.json5中useNormalizedOHMUrl设置为true

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

权限配置

权限名称	用途	是否必须
ohos.permission.INTERNET	SDK发送数据。不配置SDK无法启动	是
ohos.permission.GET_NETWORK_INFO	获取网络连接信息。配置后可以获取网络类型和连接方式信息	否
ohos.permission.STORE_PERSISTENT_DATA	存储设备ID。配置后SDK可以更准确的获取到设备ID	否

初始化SDK

在entry类型模块AbilityStage的onCreate方法中初始化SDK

import tingyun from '@tingyun/sdk-core'

export default class MyAbilityStage extends AbilityStage {
  onCreate(): void {
    tingyun.init({
      // redirect服务器地址, 在控制台设置页面获取
      redirectHost: '<Redirect服务器地址>',
      // appKey, 在控制台设置页面获取
      appKey: '<AppKey>',
      // 上下文
      context: this.context
    })
  }
}

注:

从1.7.0版本开始，tingyun.init返回值类型由Promise<void>改为void，避免误用await导致阻塞应用启动流程。如果历史代码中存在await调用，IDE会提示无效，请及时移除
SDK内部启动流程为异步，部分API需要等待SDK启动完成后才能调用。如需在SDK启动后执行逻辑，请参考SDK启动状态管理章节

延迟调用 init 时的 context 传入建议

如果业务需要延迟调用 tingyun.init，建议传入 UIAbilityContext。

SDK 在收到 UIAbilityContext 后，会尝试恢复当前已存在的 UI 容器，从而支持后续用户体验监控（页面、操作）及视图采集等能力尽量正常工作。若传入的不是 UIAbilityContext，SDK 将无法感知当前 UI 状态，上述能力可能受影响。

注意：init 调用前已发生的监控数据无法回溯采集，例如初始化前的网络请求、页面行为、用户操作等。

可选设置

配置首次启动模块开关

默认情况下，SDK首次启动仅开启崩溃数据采集，其他功能模块需要与服务端交互后开启。如需在首次启动时就启用其他功能模块，可以在tingyun.init时手动配置对应模块的开启状态。

示例:

import tingyun from '@tingyun/sdk-core'

tingyun.init({
  // 其他配置...
  network: {
    // 打开网络请求采集
    enabled: true
  },
  ue: {
    // 打开用户体验数据采集，包括启动、页面、操作采集
    enabled: true
  },
  webview: {
    // 打开webview数据采集
    enabled: true
  }
})

更多配置选项请参考API文档中的"SDK配置选项"章节

网络请求采集

SDK支持多种网络请求数据采集方式，其中Axios和RCP需要进行相应配置。

Axios

SDK支持@ohos/axios库，主要包括两种配置方式：

在tingyun.init时传入axios实例：

import tingyun from '@tingyun/sdk-core'
import axios from '@ohos/axios'

tingyun.init({
  // 其他配置...
  // 传入axios实例对象
  axios: axios
})

使用tingyun.registerAxiosInstance注册axios实例（可通过多次调用注册多个）：

import tingyun from '@tingyun/sdk-core'
import { axiosInstance } from './your-axios-config'

// 普通注册（等待网络开关初始化完成）
tingyun.registerAxiosInstance(axiosInstance)

// 立即注册（不等待网络开关初始化完成）
// 使用场景：当用户需要控制拦截器注入时机，希望提前注入听云拦截器以确保拦截器执行顺序时，可以使用此选项
tingyun.registerAxiosInstance(axiosInstance, { immediate: true })

RCP

RCP数据采集需要在调用createSession时加入SDK提供的拦截器：

import tingyun from '@tingyun/sdk-core'

const session = rcp.createSession({
  // 其他配置...
  // 加入拦截器
  interceptors: [new tingyun.RCPInterceptor()]
})

首次启动采集配置

如需采集首次启动时的网络请求数据，需要在tingyun.init时开启网络请求采集：

import tingyun from '@tingyun/sdk-core'

tingyun.init({
  // 其他配置...
  network: {
    enabled: true
  }
})

用户体验监控

用户体验监控包括启动监控、页面监控和操作监控。

启动监控配置

如需采集首次启动数据，需要在tingyun.init时开启用户体验监控：

import tingyun from '@tingyun/sdk-core'

tingyun.init({
  // 其他配置...
  ue: {
    enabled: true
  }
})

页面和操作监控配置

页面和操作监控已支持自动采集，无需手动调用 API。

设置用户ID

import tingyun from '@tingyun/sdk-core'

// 设置用户ID（<userId>为具体的用户ID）
tingyun.setUserId('<userId>')

Webview数据采集

Webview数据采集主要包括两个操作：

使用tingyun.registerWebviewController注册webview控制器
使用tingyun.getWebScriptItem获取监控脚本并注入到webview中

示例：

import tingyun from '@tingyun/sdk-core'

Web({ src: '<URL>', controller: this.controller })
  // 确保javaScriptAccess和domStorageAccess都是开启状态
  .javaScriptAccess(true)
  .domStorageAccess(true)
  .onControllerAttached(() => {
    // 在onControllerAttached回调中注册webview控制器
    tingyun.registerWebviewController(this.controller)
  })
  // 注入监控所需的JS代码
  .javaScriptOnDocumentStart([tingyun.getWebScriptItem()])

启用国密加密

SDK支持使用国密加密方式发送数据，可通过在tingyun.init时设置encEnabled: true配置开启，平台服务端也需要同步开启国密加密功能。

import tingyun from '@tingyun/sdk-core'

tingyun.init({
  // 其他配置...
  // 启用国密加密
  encEnabled: true
})

隐私配置

SDK支持对公共信息采集进行精细化控制，以满足不同应用的隐私合规要求。通过common配置项，可以控制以下设备信息的采集：

操作系统版本 (osVersionEnabled)
设备厂商 (manufacturerEnabled)
设备型号 (manufacturerModelEnabled)
运营商信息 (carrierEnabled)
屏幕分辨率 (displayResolutionEnabled)

默认情况下，所有信息采集均为开启状态。如需关闭特定信息的采集，可在初始化时配置：

tingyun.init({
  // ...其他配置
  common: {
    osVersionEnabled: false,          // 不采集操作系统版本
    manufacturerEnabled: false,      // 不采集设备厂商
    manufacturerModelEnabled: false,  // 不采集设备型号
    carrierEnabled: false,            // 不采集运营商信息
    displayResolutionEnabled: false   // 不采集屏幕分辨率
  }
})

注意：关闭某些信息采集可能会影响部分监控功能的完整性。

嵌码验证

嵌码完成后，启动APP，在IDE中打开Log -> HiLog菜单，选择对应的APP，查看日志，搜索tag为Tingyun的日志，如果存在init success关键字的日志说明嵌码成功

HarmonyOS NEXT 部署

环境需求​

安装SDK​

远程安装​

内网仓库安装​

确认项目适配字节码格式HAR包​

权限配置​

初始化SDK​

延迟调用 init 时的 context 传入建议​

可选设置​

配置首次启动模块开关​

网络请求采集​

Axios​

RCP​

首次启动采集配置​

用户体验监控​

启动监控配置​

页面和操作监控配置​

设置用户ID​

Webview数据采集​

启用国密加密​

隐私配置​

嵌码验证​