HarmonyOS NEXT Deployment

Environmental Requirements

Minimum support: API 12 Release

Install SDK

Enter the project root directory and execute the following command

ohpm install @tingyun/sdk-core

If you need to install the specified version of the SDK, you can manually specify the version (<version> the specific version number)

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

Confirm the project to adapt to the bytecode format HAR package

The SDK HAR package is in bytecode format, and the engineering level needs to be build-profile.json5 middle useNormalizedOHMUrl set to true

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

Permission configuration

Permission Name	Usage	Is it necessary
ohos.permission.INTERNET	SDK sends data. Cannot start without configuring the SDK	yes
ohos.permission.GET_NETWORK_INFO	Get network connection information. After configuration, you can obtain network type and connection method information.	no
ohos.permission.STORE_PERSISTENT_DATA	Storage device ID. After configuration, the SDK can obtain the device ID more accurately	no

Initialize the SDK

AbilityStage in entry type module onCreate initialize SDK in the method

import tingyun from '@tingyun/sdk-core'

export default class MyAbilityStage extends AbilityStage {
  onCreate(): void {
    tingyun.init({
            // redirect server address, obtained on the console settings page
            redirectHost: '<Redirect server address>',
            // appKey, obtained on the console settings page
            appKey: '<AppKey>',
            // context
            context: this.context
    })
  }
}

Optional settings

Configure the first start module switch

By default, the SDK starts for the first time and only enables crash data collection, and other functional modules need to interact with the server before turning on it. If you need to enable other functional modules at the first startup, you can tingyun.init manually configure the opening status of the corresponding module.

Example:

import tingyun from '@tingyun/sdk-core'

tingyun.init({
  // Other configuration...
  network: {
    // Enable network request collection
    enabled: true
  },
  ue: {
    // Enable user experience data collection, including startup, page, and operation data collection
    enabled: true
  },
  webview: {
    // Enable webview data collection
    enabled: true
  }
})

For more configuration options, please refer to the "SDK Configuration Options" section in the API documentation.

Network request collection

The SDK supports multiple network request data collection methods, among which Axios and RCP need to be configured accordingly.

Axios

SDK support @ohos/axios the library mainly includes two configuration methods:

1. exist tingyun.init when passing in an axios instance:

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

tingyun.init({
  // Other configuration...
  // Pass in the axios instance object
  axios: axios
})

2. use tingyun.registerAxiosInstance register an axios instance (multiple calls can be registered with multiple calls):

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

tingyun.registerAxiosInstance(axiosInstance)

RCP

RCP data collection needs to be called createSession when adding the interceptor provided by the SDK:

import tingyun from '@tingyun/sdk-core'

const session = rcp.createSession({
  // Other configuration...
  // Add interceptor
  interceptors: [new tingyun.RCPInterceptor()]
})

First start of acquisition configuration

To collect network request data at first startup, you need to tingyun.init when enabling network request collection:

import tingyun from '@tingyun/sdk-core'

tingyun.init({
  // Other configuration...
  network: {
    enabled: true
  }
})

User experience monitoring

User experience monitoring includes startup monitoring, page monitoring and operation monitoring.

Start monitoring configuration

To collect the first startup data, you need to tingyun.init turn on user experience monitoring:

import tingyun from '@tingyun/sdk-core'

tingyun.init({
  // Other configuration...
  ue: {
    enabled: true
  }
})

Page and operation monitoring configuration

Page and operation monitoring requires use tingyun.registerUIContext API registration UIContext.

Example:

import tingyun from '@tingyun/sdk-core'

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', (err, data) => {

      // Get the main window of the current UIAbility
      windowStage.getMainWindow((err: BusinessError, data) => {
        const uiContext = data.getUIContext()
        
        // Register the UIContext of the current window
        tingyun.registerUIContext(uiContext)
      })
    });
  }
}

Set user ID

import tingyun from '@tingyun/sdk-core'

// Set the user ID (<userId> is the specific user ID)
tingyun.setUserId('<userId>')

Webview data collection

Webview data collection mainly includes two operations:

1. use tingyun.registerWebviewController register a webview controller
2. use tingyun.getWebScriptItem get monitoring scripts and inject them into webview

Example:

import tingyun from '@tingyun/sdk-core'

Web({ src: '<URL>', controller: this.controller })
  // Ensure both javascriptAccess and domStorageAccess are enabled
  .javaScriptAccess(true)
  .domStorageAccess(true)
  .onControllerAttached(() => {
    // Register the webview controller in the onControllerAttached callback
    tingyun.registerWebviewController(this.controller)
  })
  // Inject the JS code required for monitoring
  .javaScriptOnDocumentStart([tingyun.getWebScriptItem()])

Enable national encryption

The SDK supports the use of national encryption to send data, which can be sent through tingyun.init settings encEnabled: true the configuration is enabled, and the platform server also needs to enable the national encryption function simultaneously.

import tingyun from '@tingyun/sdk-core'

tingyun.init({
  // Other configuration...
  // Enable national security encryption
  encEnabled: true
})

Embed code verification

After the embed code is completed, start the APP, open the Log -> HiLog menu in the IDE, select the corresponding APP, view the log, and search for the tag as Tingyun log, if it exists init success keyword log description embedding successfully