HarmonyOS 應用事件打點開發指導

簡介

傳統的日誌系統裡匯聚了整個裝置上所有程式執行的過程流水日誌，難以識別其中的關鍵資訊。因此，應用開發者需要一種資料打點機制，用來評估如訪問數、日活、使用者操作習慣以及影響使用者使用的關鍵因素等關鍵資訊。

HiAppEvent 是在系統層面為應用開發者提供的一種事件打點機制，用於幫助應用記錄在執行過程中發生的故障資訊、統計資訊、安全資訊、使用者行為資訊，以支撐開發者分析應用的執行情況。

基本概念

●  打點

記錄由使用者操作引起的變化，提供業務資料資訊，以供開發、產品、運維分析。

事件設計規範

●  事件領域：用於標識事件的領域，建議設定為業務模組名稱，以便於區分不同的業務模組。

●  事件名稱：用於指定事件的名稱，建議設定為具體的業務名稱，以便於描述實際的業務意義。

●  事件型別：用於指定事件的型別，支援以下四種型別事件：行為事件：用於記錄使用者日常操作行為的事件，例如按鈕點選、介面跳轉等行為。

○  故障事件：用於定位和分析應用故障的事件，例如介面卡頓、掉網掉話等異常。

○  統計事件：用於統計和度量應用關鍵行為的事件，例如對使用時長、訪問數等的統計。

○  安全事件：用於記錄涉及應用安全行為的事件，例如密碼修改、使用者授權等行為。

●  事件引數：用於指定事件的引數，每個事件可以包含一組引數，建議設定為事件屬性或事件發生上下文資訊，以便於描述事件的詳細資訊。

介面說明

應用事件打點介面由 hiAppEvent 模組提供，API 介面的具體使用說明（引數使用限制、具體取值範圍等）請參考 應用事件打點API文件 。

打點介面功能介紹：

訂閱介面功能介紹：

開發步驟

以實現對使用者點選按鈕行為的事件打點及訂閱為例，說明開發步驟。

1.  新建一個 ArkTS 應用工程，編輯工程中的“entry > src > main > ets > entryability > EntryAbility.ts” 檔案，在 onCreate 函式中新增對使用者點選按鈕事件的訂閱，完整示例程式碼如下：

import hilog 
from 
'@ohos.hilog';

import 
UIAbility 
from 
'@ohos.app.ability.UIAbility';

import 
Window 
from 
'@ohos.window'

import hiAppEvent 
from 
'@ohos.hiviewdfx.hiAppEvent'




export 
default 
class 
EntryAbility 
extends 
UIAbility {
    
onCreate(
want, launchParam) {
        hilog.
isLoggable(
0x0000, 
'testTag', hilog.
LogLevel.
INFO);
        hilog.
info(
0x0000, 
'testTag', 
'%{public}s', 
'Ability onCreate');
        hilog.
info(
0x0000, 
'testTag', 
'%{public}s', 
'want param:' + 
JSON.
stringify(want) ?? 
'');
        hilog.
info(
0x0000, 
'testTag', 
'%{public}s', 
'launchParam:' + 
JSON.
stringify(launchParam) ?? 
'');
        hiAppEvent.
addWatcher({
            
// 開發者可以自定義觀察者名稱，系統會使用名稱來標識不同的觀察者
            
name: 
"watcher1",
            
// 開發者可以訂閱感興趣的應用事件，此處是訂閱了按鈕事件
            
appEventFilters: [{ 
domain: 
"button" }],
            
// 開發者可以設定訂閱回撥觸發的條件，此處是設定為事件打點數量滿足1個
            
triggerCondition: { 
row: 
1 },
            
// 開發者可以自行實現訂閱回撥函式，以便對訂閱獲取到的事件打點資料進行自定義處理
            
onTrigger: 
function (
curRow, curSize, holder) {
                
// 返回的holder物件為null，表示訂閱過程發生異常，因此在記錄錯誤日誌後直接返回
                
if (holder == 
null) {
                    hilog.
error(
0x0000, 
'testTag', 
"HiAppEvent holder is null")
                    
return
                }
                
let eventPkg = 
null
                
// 根據設定閾值大小（預設為512KB）去獲取訂閱事件包，直到將訂閱資料全部取出
                
// 返回的事件包物件為null，表示當前訂閱資料已被全部取出，此次訂閱回撥觸發結束
                
while ((eventPkg = holder.
takeNext()) != 
null) {
                    
// 開發者可以對事件包中的事件打點資料進行自定義處理，此處是將事件打點資料列印在日誌中
                    hilog.
info(
0x0000, 
'testTag', 
`HiAppEvent eventPkg.packageId=%{public}d`, eventPkg.
packageId)
                    hilog.
info(
0x0000, 
'testTag', 
`HiAppEvent eventPkg.row=%{public}d`, eventPkg.
row)
                    hilog.
info(
0x0000, 
'testTag', 
`HiAppEvent eventPkg.size=%{public}d`, eventPkg.
size)
                    
for (
const eventInfo 
of eventPkg.
data) {
                        hilog.
info(
0x0000, 
'testTag', 
`HiAppEvent eventPkg.info=%{public}s`, eventInfo)
                    }
                }
            }
        })
    }
}

2.  編輯工程中的“entry > src > main > ets > pages > Index.ets” 檔案，新增一個按鈕並在其 onClick 函式中進行事件打點，以記錄按鈕點選事件，完整示例程式碼如下：

import hiAppEvent 
from 
'@ohos.hiviewdfx.hiAppEvent'

import hilog 
from 
'@ohos.hilog'




@Entry

@Component
struct 
Index {
  
@State 
message: 
string = 
'Hello World'
  
build() {
    
Row() {
      
Column() {
        
Text(
this.
message)
          .
fontSize(
50)
          .
fontWeight(
FontWeight.
Bold)
        
Button(
"writeTest").
onClick(
()=>{
          
// 在按鈕點選函式中進行事件打點，以記錄按鈕點選事件
          hiAppEvent.
write({
            
// 事件領域定義
            
domain: 
"button",
            
// 事件名稱定義
            
name: 
"click",
            
// 事件型別定義
            
eventType: hiAppEvent.
EventType.
BEHAVIOR,
            
// 事件引數定義
            
params: { 
click_time: 
100 }
          }).
then(
() => {
            hilog.
info(
0x0000, 
'testTag', 
`HiAppEvent success to write event`)
          }).
catch(
(
err) => {
            hilog.
error(
0x0000, 
'testTag', 
`HiAppEvent err.code: 
${err.code}, err.message: 
${err.message}`)
          })
        })
      }
      .
width(
'100%')
    }
    .
height(
'100%')
  }
}

3.  點選 IDE 介面中的執行按鈕，執行應用工程，然後在應用介面中點選按鈕“writeTest”，觸發一次按鈕點選事件打點。

4.  最終，可以在 Log 視窗看到按鈕點選事件打點成功的日誌，以及觸發訂閱回撥後對打點事件資料的處理日誌：

HiAppEvent success to write event



HiAppEvent eventPkg.packageId=0
HiAppEvent eventPkg.row=1
HiAppEvent eventPkg.size=124
HiAppEvent eventPkg.info={
"domain_":
"button",
"name_":
"click",
"type_":4,
"time_":1670268234523,
"tz_":
"+0800",
"pid_":3295,
"tid_