部署SDK

环境需求

最低支持API 11 (HarmonyOS NEXT Developer Preview2)

安装SDK

进入项目的根目录，执行以下命令

ohpm install @tingyun/sdk-core

初始化SDK

在入口Ability 的onCreate方法中初始化 SDK

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

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    tingyun.init({
      // redirect服务器地址, 在控制台设置页面获取
      redirectHost: '<Redirect服务器地址>',
      // appKey, 在控制台设置页面获取
      appKey: '<AppKey>',
      // 上下文
      context: this.context,
      // 如果使用axios, 可传入axios对象采集axios发送的网络请求
      axios: axios
    })
  }
  // ... 
}

设置用户ID（可选）

import tingyun from '@tingyun/sdk-core'

tingyun.init({
  // ...
})
// 设置应用的用户ID
tingyun.setUserId('<userId>')

权限配置

验证数据上报

嵌码完成后，启动APP，在IDE中打开Log -> HiLog菜单，选择对应的APP，查看日志，检测存在init success关键字的日志后说明数据上报成功。

SDK 配置选项

import common from '@ohos.app.ability.common'

export enum LogLevel {
  DEBUG,
  INFO,
  WARN,
  ERROR,
  NONE
}

export type RecordRule = {
  // 需要采集此参数的域名/URL配置。目标URL包含于这项配置才会采集，如果不配置本条规则会对所有URL生效
  url?: string
  // 获取全部请求头, 默认空
  reqHeaders?: string[]
  // 请求体配置, 默认空
  reqBody?: string[]
  // 获取全部返回头, 默认空
  resHeaders?: string[]
  // 返回体配置, 默认空
  resBody?: string[]
}

export type NetworkConfig = {
  // 网络请求采集开关, 默认false
  enabled?: boolean
  // 跨应用追踪开关, 默认false
  trackingEnabled?: boolean
  // 采集数据白名单
  recordConfig?: RecordRule[]
  // 采集数据黑名单
  recordBlockConfig?: RecordRule[]
  // 采集的body截断长度, 单位KB
  bodyMaxSize?: number
  // 第三方apm请求头支持
  apms?: string[]
  // trace propagators
  propagators?: string[]
}

export type CrashConfig = {
  // 崩溃采集总开关, 默认true
  enabled?: boolean
  // js崩溃采集开关, 默认true
  jsCrashEnabled?: boolean
  // cpp崩溃采集开关, 默认true
  cppCrashEnabled?: boolean
}

export type FreezeConfig = {
  // 卡死监控开关, 默认false
  enabled?: boolean
}

export type UserExperienceConfig = {
  // 总开关, 默认false
  enabled?: boolean
  // 启动用户体验开关, 默认true
  launchEnabled?: boolean
}

/**
 * 应用配置
 */
export type InitConfig = {
  // redirect服务器地址
  redirectHost: string
  // 应用appKey
  appKey: string
  // 上下文
  context: common.Context
  // 日志级别, 默认LogLevel.INFO
  logLevel?: LogLevel
  // 数据是否使用http发送数据, 默认false, 使用https发送
  httpEnabled?: boolean
  // axios对象, 需要拦截axios时需要传入
  axios?: any
  // 最大获取的栈深度
  stackDepth?: number
  // 是否使用历史数据协议上报，默认为false
  legacyDataProtocol?: boolean
  // 网络请求采集配置
  network?: NetworkConfig
  // Crash监控配置
  crash?: CrashConfig
  // AppFreeze监控配置
  freeze?: FreezeConfig
  // 用户体验配置
  ue?: UserExperienceConfig
}

注： init传入的配置为SDK初始配置，在SDK与服务端通信后会优先以服务端下发的配置为准

API 说明

SDK API 概览

import http from '@ohos.net.http'
export interface HttpRequestWrapper {
  (options: HttpRequestWrapperOptions, callback: AsyncCallback<http.HttpResponse>): void
  (options: HttpRequestWrapperOptions): Promise<http.HttpResponse>
}

export type Tingyun = {
  // 初始化SDK
  init: (options: InitConfig) => void
  // 设置用户id
  setUserId: (userId: string) => void
  // 切换会话
  startNextSession: () => void
  // http request封装
  request: HttpRequestWrapper
  // 设置纬度，经度
  setLatLon: (latitude: number, longitude: number) => void
}

网络请求

Axios

SDK支持@ohos/axios库网络请求采集。配置方式为在SDK初始化时传入axios对象，如果首次启动需要采集网络请求，需要额外打开网络请求采集开关。

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

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    tingyun.init({
      redirectHost: '<Redirect服务器地址>',
      appKey: '<AppKey>',
      context: this.context,
      // 传入axios对象
      axios: axios,
      network: {
        // 首次启动打开网络请求监控
        enabled: true
      }
    })
  }
  // ... 
}

SDK网络请求接口

SDK对系统@ohos.net.http包HttpRequest.request接口进行了封装，对外暴露了request接口。调用这个接口发送的网络请求会被SDK采集。

• 接口

import http from '@ohos.net.http';

export type HttpRequestWrapperOptions = {
  url: string
  options?: http.HttpRequestOptions
  // http.createHttp() 返回的request对象，如果不传SDK内部会创建。不传httpRequest时，SDK内部只会在用户传入callback时在用户callback执行完后同步调用httpRequest.destroy。传入httpRequest时, SDK除了调用httpRequest.request之外不会调用其他方法。如果需要调用httpRequest其他方法、自行控制destroy时机以及使用promise方式时，需要传入httpRequest
  httpRequest?: http.HttpRequest
}
export interface HttpRequestWrapper {
  (options: HttpRequestWrapperOptions, callback: AsyncCallback<http.HttpResponse>): void
  (options: HttpRequestWrapperOptions): Promise<http.HttpResponse>
}

export type Tingyun = {
  // ...
  // http request封装
  request: HttpRequestWrapper
}

• 示例

import tingyun from '@tingyun/sdk-core'

// 1. 传递URL (promise)
tingyun.request({url: 'xxx'})
  .then((res) => {
    // ...
  })
  .catch((err) => {
    // ...
  })

// 2. 传递URL (callback)
tingyun.request({url: 'xxx'}, (err, res) => {
  // ...
})

// 3. 传递URL和options (promise)
tingyun.request({url: 'xxx', options: {
  method: http.RequestMethod.POST,
  header: {
    'Content-Type': 'application/json'
  },
  extraData: {
    // ...
  }
}})
.then((res) => {
  // ...
})
.catch((err) => {
})

// 4. 传递URL和options (callback)
tingyun.request({url: 'xxx', options: {
  method: http.RequestMethod.POST,
  header: {
    'Content-Type': 'application/json'
  },
  extraData: {
    // ...
  }
}}, (err, res) => {
  // ...
})

// 5. 使用自定义请求对象
const httpRequest = http.createHttp()
tingyun.request({
  url: 'xxx', 
  httpRequest: httpRequest 
}, (err, res) => {
  // ...
})

用户ID

import tingyun from '@tingyun/sdk-core'

tingyun.setUserId('<USER_ID>')

注：SDK初始化结束之前如果多次设置用户ID，只会取最后一次设置的值

会话切换

import tingyun from '@tingyun/sdk-core'

tingyun.startNextSession()

经纬度

import tingyun from '@tingyun/sdk-core'

tingyun.setLatLon(<纬度>, <经度>)

注：

• 纬度有效值为 [-90, 90]
• 经度有效值为 [-180, 180]
• 经纬度其中之一传无效值，API调用无效

功能支持列表