Auto-tracking

Last updated 10/03/2026

The OpenHarmony SDK supports auto-tracking of events such as install, start, and end.

1. Introduction

AE provides APIs for collecting data automatically. You can choose which data to collect automatically based on your business needs.

The following auto-tracked event types are currently supported:

1. Install event: Records the installation of the APP
2. Start event: Includes opening the APP and opening the APP from the background
3. End event: Includes closing the APP and the APP moving to the background
4. View event: The user views a page (Ability) in the APP
5. Click event: The user clicks a control in the APP
6. Crash event: Records crash information when the APP crashes (native-layer crashes aren't supported yet)

The following sections describe how each type of data is collected

2. Enable auto-tracking

Call enableAutoTrack to enable auto-tracking:

//APP install event TDAutoTrackEventType.APP_INSTALL
//APP start event TDAutoTrackEventType.APP_START
//APP end event TDAutoTrackEventType.APP_END
//APP view page event TDAutoTrackEventType.APP_VIEW_SCREEN
//APP control click event TDAutoTrackEventType.APP_CLICK
//APP crash event TDAutoTrackEventType.APP_CRASH
TDAnalytics.enableAutoTrack(context,TDAutoTrackEventType.APP_START | TDAutoTrackEventType.APP_INSTALL | TDAutoTrackEventType.APP_END | TDAutoTrackEventType.APP_VIEW_SCREEN | TDAutoTrackEventType.APP_CLICK | TDAutoTrackEventType.APP_CRASH)

note

Call enableAutoTrack on the main thread. If you need to initialize the SDK in a worker thread, refer to the following code

const workerInstance = new worker.ThreadWorker("./workers/worker.ets");
TDAnalytics.enableAutoTrack(this.context,
  TDAutoTrackEventType.APP_START | TDAutoTrackEventType.APP_INSTALL | TDAutoTrackEventType.APP_END |
  TDAutoTrackEventType.APP_VIEW_SCREEN | TDAutoTrackEventType.APP_CRASH |
  TDAutoTrackEventType.APP_CLICK,
  (command: string, params: Object, appId?: string) => {
    //The auto-tracked events to be triggered are passed out through this callback; send the messages to the worker thread for processing
    workerInstance.postMessage({
      type: command,
      params: params
    })
  })

const workerPort = worker.workerPort;

workerPort.onmessage = (d: MessageEvents): void => {
  if (d.data.type === 'track') {
    TDAnalytics.track(d.data.params);
  } else if (d.data.type === 'timeEvent') {
    TDAnalytics.timeEvent(d.data.params);
  } else if (d.data.type === 'flush') {
    TDAnalytics.flush()
  }
}

3. Details

3.1 Install event

The APP install event records the actual installation of the APP and is reported when the APP starts. The event trigger time is the time of the first start after the APP is installed. Upgrading the APP doesn't trigger the install event, but deleting and reinstalling the APP reports an install event.

• Event name: ta_app_install

3.2 Start event

The APP start event is triggered when the user opens the APP or wakes the APP from the background. Details of the event are as follows:

• Event name: ta_app_start
• Preset property: #resume_from_background, Boolean, indicates whether the APP was opened by the user or woken from the background. true means it was woken from the background, and false means it was opened directly.
• Triggered by the onApplicationForeground callback in ApplicationStateChangeCallback

3.3 End event

The APP end event is triggered when the user closes the APP or moves the APP to the background. Details of the event are as follows:

• Event name: ta_app_end
• Preset property: #duration, number, indicates the duration of this APP visit (from start to end), in seconds.
• Triggered by the onApplicationBackground callback in ApplicationStateChangeCallback

3.4 View page event

The APP view page event is triggered when the user views a page (Ability). Details of the event are as follows:

• Event name: ta_app_view
• Preset properties:

#screen_name, string, the simple class name of the Ability

• Custom page data

  • Switching pages with router

  router.pushUrl({
    url: 'pages/PageOne', params: {
      'ta_data_tag': {
        'key1': 'value1',
        'key2': 234,
        'ignore': true
      }
    }
  })
  //ta_data_tag is the custom parameter
  //When ignore is true, the view event of this page is ignored

  • Switching pages with navigation

  interface UserLoginParam {
    // Business custom parameter
    customParams?: string
    //Custom parameters appended to the view event of the target page
    ta_data_tag?: ThinkingDataPageParams
  }
  
  interface ThinkingDataPageParams {
    key1: string
    key2: number,
    ignore?:boolean
  }
  
  let paramData: UserLoginParam = { customParams: 'AAA', ta_data_tag: { key1: 'xxx', key2: 18,ignore:true } }
  this.navPathStack.pushPath({
    name: 'NavDestinationTitle' + item,
    param: paramData
  });
  
  //ta_data_tag is the custom parameter
  //When ignore is true, the view event of this page is ignored

3.5 Click event

The APP control click event is triggered when the user clicks a control (view)

• Event name: ta_app_click

• Preset properties:

  #screen_name, string, the package name.class name of the Activity that the control belongs to

  #element_type, string, the type of the control

  #element_id, string, the ID of the control

• Custom parameters

Button("Button", { type: ButtonType.Normal, stateEffect: true })
  .width('30%')
  .customProperty("ta_data_tag", {
    'key1': 10,
    'key2': 'this is a string',
    'ignore':false
  })
  .onClick(() => {
    
  })
//ta_data_tag is the custom parameter
//When ignore is true, the click event of this element is ignored

3.6 Crash event

When an uncaught exception occurs in the APP, an APP crash event is reported

• Event name: ta_app_crash
• Preset property: #app_crashed_reason, string, records the stack trace at the time of the crash
• Listened for through onUnhandledException of ErrorObserver. Collection of native crashes isn't supported yet.