應用打點

本模塊提供了應用事件打點能力，包括對打點數據的落盤，以及對打點功能的管理配置。

說明： 本模塊首批接口從API version 7開始支持。后續版本的新增接口，采用上角標單獨標記接口的起始版本。 開發前請熟悉鴻蒙開發指導文檔 ：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

導入模塊

import hiAppEvent from '@ohos.hiAppEvent';

hiAppEvent.write

write(eventName: string, eventType: EventType, keyValues: object, callback: AsyncCallback): void

應用事件打點方法，將事件寫入到當天的事件文件中，可接收類型為Json對象的事件參數，使用callback方式作為異步回調。

系統能力： SystemCapability.HiviewDFX.HiAppEvent

參數：

參數名	類型	必填	說明
eventName	string	是	應用事件名稱。由開發者自定義。事件名稱在48個字符以內，有效的字符是0-9、a-z、下劃線，只能以字母開頭。
eventType	[EventType]	是	應用事件類型。
keyValues	object	是	事件參數鍵值對，如果是變長參數類型，則依次輸入事件的參數名與參數值。如果是Json對象類型，則Json對象的key是事件的參數名，value是事件的參數值。 - key類型只能為string，value類型只能為string、number、boolean、Array（數組數據類型只能為string、number、boolean）。 - 事件的參數個數必須小于等于32。 - 參數名在16個字符以內，有效的字符是0-9、a-z、下劃線，只能以字母開頭，不能以下劃線結尾。 - string類型參數值在8*1024個字符內。 - Array類型參數值的元素個數必須在100個以內，超出時會進行截斷處理。
callback	AsyncCallback	否	回調函數，可以在回調函數中處理接口返回值。 - 返回值為0表示事件校驗成功，事件正常異步寫入事件文件； - 大于0表示事件校驗存在異常參數，在忽略異常參數后將事件異步寫入事件文件； - 小于0表示事件校驗失敗，不將事件寫入事件文件。

示例：

hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str_data":"strValue"}, (err, value) = > {
    if (err) {
        // 事件寫入異常：事件存在異常參數時忽略異常參數后繼續寫入，或者事件校驗失敗時不執行寫入
        console.error(`failed to write event because ${err.code}`);
        return;
    }

    // 事件寫入正常
    console.log(`success to write event: ${value}`);
});

hiAppEvent.write

write(eventName: string, eventType: EventType, keyValues: object): Promise

應用事件打點方法，將事件寫入到當天的事件文件中，可接收類型為Json對象的事件參數，使用promise方式作為異步回調。

系統能力： SystemCapability.HiviewDFX.HiAppEvent

參數：

參數名	類型	必填	說明
eventName	string	是	應用事件名稱。由開發者自定義。事件名稱在48個字符以內，有效的字符是0-9、a-z、下劃線，只能以字母開頭。
eventType	[EventType]	是	應用事件類型。
keyValues	object	是	事件參數鍵值對，如果是變長參數類型，則依次輸入事件的參數名與參數值。如果是Json對象類型，則Json對象的key是事件的參數名，value是事件的參數值。 - key類型只能為string，value類型只能為string、number、boolean、Array（數組數據類型只能為string、number、boolean）。 - 事件的參數個數必須小于等于32。 - 參數名在16個字符以內，有效的字符是0-9、a-z、下劃線，只能以字母開頭，不能以下劃線結尾。 - string類型參數值在8*1024個字符內。 - Array類型參數值的元素個數必須在100個以內，超出時會進行截斷處理。

返回值：

類型	說明
Promise	Promise實例，可以在其then()、catch()方法中分別對事件寫入成功、寫入異常的情況進行回調處理。

示例：

hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str_data":"strValue"})
    .then((value) = > {
        // 事件寫入正常
        console.log(`success to write event: ${value}`);
    }).catch((err) = > {
        // 事件寫入異常：事件存在異常參數時忽略異常參數后繼續寫入，或者事件校驗失敗時不執行寫入
        console.error(`failed to write event because ${err.code}`);
    });

hiAppEvent.configure

configure(config: ConfigOption): boolean

應用事件打點配置方法，可用于配置打點開關、文件目錄存儲限額大小等功能。

系統能力： SystemCapability.HiviewDFX.HiAppEvent

參數：

參數名	類型	必填	說明
config	[ConfigOption]	是	應用事件打點配置項對象。

返回值：

類型	說明
boolean	配置結果，true 表示配置成功，false 表示配置失敗。

示例：

// 配置應用事件打點功能開關
hiAppEvent.configure({
    disable: true
});

// 配置事件文件目錄存儲限額大小
hiAppEvent.configure({
    maxStorage: '100M'
});

ConfigOption

此接口提供了應用打點的配置選項。

系統能力： 以下各項對應的系統能力均為SystemCapability.HiviewDFX.HiAppEvent。

參數名	類型	必填	說明
disable	boolean	否	應用打點功能開關。配置值為true表示關閉打點功能，false表示不關閉打點功能。
maxStorage	string	否	打點數據本地存儲文件所在目錄的配額大小，默認限額為“10M”。所在目錄大小超出限額后會對目錄進行清理操作，會按從舊到新的順序逐個刪除打點數據文件，直到目錄大小不超出限額時停止。

EventType

事件類型枚舉。

系統能力： 以下各項對應的系統能力均為SystemCapability.HiviewDFX.HiAppEvent。

名稱	默認值	說明
FAULT	1	故障類型事件。
STATISTIC	2	統計類型事件。
SECURITY	3	安全類型事件。
BEHAVIOR	4	行為類型事件。

Event

此接口提供了所有預定義事件的事件名稱常量。

系統能力： 以下各項對應的系統能力均為SystemCapability.HiviewDFX.HiAppEvent。

名稱	參數類型	可讀	可寫	說明
USER_LOGIN	string	是	否	用戶登錄事件。
USER_LOGOUT	string	是	否	用戶登出事件。
DISTRIBUTED_SERVICE_START	string	是	否	分布式服務啟動事件。`HarmonyOS與OpenHarmony鴻蒙文檔籽料：mau123789是v直接拿`

搜狗高速瀏覽器截圖20240326151547.png

Param

此接口提供了所有預定義參數的參數名稱常量。

系統能力： 以下各項對應的系統能力均為SystemCapability.HiviewDFX.HiAppEvent。

名稱	參數類型	可讀	可寫	說明
USER_ID	string	是	否	用戶自定義ID。
DISTRIBUTED_SERVICE_NAME	string	是	否	分布式服務名稱。
DISTRIBUTED_SERVICE_INSTANCE_ID	string	是	否	分布式服務實例ID。