This article introduces a series of APIs provided by HarmonyOS for you. You can call the corresponding API in combination with event tracking planning for event tracking.

init #

• Function: Initialize the SDK instance, depending on the ability context, so the call timing is suitable for the onCreate life cycle.

• Definition: nit (context: common. Context, initConfig: InitConfig): void

• Parameters:

  Parameter name	Type	Required	Explain
  context	common.Context	Yes	Ability context
  initConfig	InitConfig	Yes	SDK internal implementation manages initialization configuration classes

• Example:

  class EntryAbility extends UIAbility {
      onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
          Create a new AppLog instance
          let appLog = new AppLog()
          //Hongmeng sdk channel as optional parameter
          let config = new InitConfig('yourAppId', 'yourChannel')
            //whether to open the log
            .setLogEnabled(true)
            //If it is reported to cloud native, you can set the reporting address to cloud native domain name
            .setUri(createByDomain('https://gator.volces.com'))
            
          //init sdk pass in the configuration, after init you can
          appLog.init(this.context, config)
          
          // ...
      }    
      // ...
  }
  

start #

• Function: Let the SDK instance start to really prepare to perform event reporting, and the calling time is after init.
• Definition: start (): void
• Example:

  class EntryAbility extends UIAbility {
      onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
          Create a new AppLog instance
          // ...
          //init sdk pass in the configuration, after init you can
          appLog.init(context, config)
          
          //Hongmeng SDK needs to manually call start to start collecting sensitive information and sending requests
          appLog.start()
      }    
      // ...
  }
  

event #

• Function: Report the event, it can only be called after initialization.

• Definition: event (eventName: string, params?: EventRecord): void

• Parameters:

  Parameter name	Type	Required	Explain
  eventName	string	Yes	Event name, cannot be nil or empty string
  params	EventRecord = Record<string, number	string	boolean

• Example:

  //Example: Report event event_name, the event does not contain properties
  //placed in the corresponding position of business logic
  appLog.event('event_name')
  
  //Example: Report event event_name, the event contains two properties
  //A property of type string, the property name is key_string, and the property value is value_string
  //a property of type int, the property name key_int, the property value is 10
  //placed in the corresponding position of business logic
  appLog.event('event_name', {
    'key_string': 'value_string',
    'key_int': 10
  })
  

setHeaderInfo #

• Role: Set custom public properties (non-persistent).

• Definition: setHeaderInfo (key: string, value: ObjectValue): void

• Parameters:

  Parameter name	Type	Required	Explain
  key	string	Yes	custom public property name
  value	ObjectValue = number	string	boolean

• Example:

  /*
   * Example: Set a custom public property with the property name key_public and the property value value_public
   * Please note about customizing "public properties":
   * 1. The reporting mechanism is to submit with each log sending. The default log sending frequency is 1 minute.
   Therefore, if you modify the custom public properties continuously within one minute, the last modification before the log is sent shall prevail;
   * 2. High-frequency modifications are not recommended, such as once per second.
   */
  appLog.setHeaderInfo('key_public', 'value_public')
  

removeHeaderInfo #

• What: Removes custom public properties.

• Definition: emoveHeaderInfo (key: string): void

• Parameters:

  Parameter name	Type	Required	Explain
  key	string	Yes	Custom report key

• Example:

  //Example: Remove a public property named key_public
  appLog.removeHeaderInfo('key_public')
  

topicReceiver #

• Function: SDK implements a set of subscription publishing mechanism. If you want to subscribe to some specific events inside SDK, you need to call topicReceiver to get the TopicReceiver object of the instance first.

• Definition: topicReceiver (): TopicReceiver | null

• Return value:

  Type

  Explain

  TopicReceiver

  The TopicReceiver class implements the mechanism of subscription publishing, which is roughly as follows TopicReceiver { abstract on(type: Topic, hook: DispatcherCallback): void abstract once(type: Topic, hook: DispatcherCallback): void abstract stickyOn(type: Topic, hook: DispatcherCallback): void abstract stickyOnce(type: Topic, hook: DispatcherCallback): void abstract off(type: Topic, hook?: DispatcherCallback): void }

• Example:

  appLog.topicReceiver().on(Topic.ABTestConfigReady, (_) => {
      // ...
  })
  

InitConfig is a class that specializes in managing SDK initialization configuration, providing a series of methods to set initialization configuration items.

InitConfig #

• Role: Instantiates an administrative initialization configuration item object.

• Definition: constructor (appId: string, channel?: string)

• Parameters:

  Parameter name	Type	Required	Explain
  appId	string	Yes	App ID
  channel	string	No	Channel, set by the business itself

• Example:

  let config = new InitConfig('yourAppId', 'yourChannel')
  

setLogEnabled #

• Function: Whether to open the SDK run log.

• Definition: setLogEnabled (logEnabled: boolean): InitConfig

• Parameters:

  Parameter name	Type	Required	Explain
  logEnabled	boolean	Yes	Whether to open the SDK run log.

• Example:

  let config = new InitConfig('yourAppId', 'yourChannel')
    //whether to open the log
    .setLogEnabled(true)
  

setUri #

• Function: Set the reporting domain name.

• Definition: setUri (uri: URiConfig): InitConfig

• Parameters:

  Parameter name	Type	Required	Explain
  uri	URiConfig	Yes	The value of URI is a domain name. The SDK provides createByDomain to assist in processing domain names, generating a series of request addresses that need to be used internally, including event reporting request addresses, activation request addresses, etc.

• Example:

  let config = new InitConfig('yourAppId', 'yourChannel')
    //Set the domain name, through createByDomain can help generate a series of internal request addresses
    .setUri(createByDomain("https://gator.volces.com"))
  

setOaidEnabled #

• Function: oaid acquisition switch.

• Definition: setOaidEnabled (enabled: boolean): InitConfig

• Parameters:

  Parameter name	Type	Required	Explain
  enabled	boolean	Yes	OAID acquisition switch.

• Example:

  let config = new InitConfig('yourAppId', 'yourChannel')
    //Open to get oaid.
    .setOaidEnabled(true)
  

setOperatorInfoEnabled #

• Function: operator information collection switch.

• Definition: setOperatorInfoEnabled (enabled: boolean): InitConfig

• Parameters:

  Parameter name	Type	Required	Explain
  enabled	boolean	Yes	Operator information collection switch.

• Example:

  let config = new InitConfig('yourAppId', 'yourChannel')
    //Open to get oaid.
    .setOperatorInfoEnabled(true)
  

User information plug-in, set up and get user information, such as user_unique_id. The way to obtain user information plug-ins is as follows:

appLog.user()

setUserUniqueID #

• Role: Set user_unique_id field.

• Definition: setUserUniqueID (uuid: string | null, uuidType?: string | null): void

• Parameters:

  Parameter name	Type	Required	Explain
  uuid	string	null	Yes, null.
  uuidType	string	null	No When the value is not null, the SDK sets the value to the internally maintained user_unique_id_type field; similarly, when null, the SDK will empty the value of the user_unique_id_type field;

• Example:

  //Set UUID
  appLog.user()?.setUserUniqueID("your_uuid")
  
  //If you have multi-caliber requirements, you can see the settings below.
  //Set UUID + UUIDType
  appLog.user()?.setUserUniqueID("your_uuid", "your_uuid_type")
  //The setUserUniqueID (uuid) of the single parameter is equivalent to the setUserUniqueID (uuid, lastuuidType) of the double parameter, but the uuidType is not available by default. If you want to empty the uuidType after setting it, you need to set it extra:
  appLog.user()?.setUserUniqueID("your_uuid", null)
  
  //Log out of UUID
  appLog.user()?.setUserUniqueID(null)
  
  //If you have multi-caliber requirements, you can see the settings below.
  //Logout UUID + UUIDType
  appLog.user()?.setUserUniqueID(null, null)
  

getUserUniqueID #

• Role: Get the value of the user_unique_id field maintained internally by the SDK.
• Definition: getUserUniqueID (): string | null
• Example:

  //Get the current UUID
  const uuid = appLog.user()?.getUserUniqueID()
  

getUserUniqueIDType #

• Role: Get the value of the user_unique_id_type field maintained internally by the SDK.
• Definition: getUserUniqueIDType (): string | null
• Example:

  //Get the current UUIDType
  const uuidType = appLog.user()?.getUserUniqueIDType()
  

The SDK provides AB test capabilities, providing AB test plugin, which contains a series of methods: getAbConfig, getAbSdkVersion, getAllAbTestConfigs. The way to get AB test plugin is as follows:

appLog.abTest()

getAbConfig #

• Function: Get AB test configuration value.

• Definition: getAbConfig < T > (key: string, defaultValue: T): T

• Parameters:

  Parameter name	Type	Required	Explain
  key	NSString	Yes	AB test configured key
  defaultValue	T extends **** string	boolean	number

• Example:

  //It is recommended to trigger the experiment every time after obtaining the latest AB
  appLog.topicReceiver().on(Topic.ABTestConfigReady, (_) => {
      appLog.abTest()?.getAbConfig("ab_key", defaultValue)
  })
  

getAbSdkVersion #

• Function: Get the vids of the exposed AB test configuration.
• Definition: getAbSdkVersion (): string
• Example:

  appLog.abTest()?.getAbSdkVersion()
  

getAllAbTestConfigs #

• Role: Get all configuration items for AB test.

• Definition: getAllAbTestConfigs (): Record < string, ABTestItem >

• Return value:

  Type	Explain
  Record<string, ABTestItem>	similar value { "ab": { "val": "访问页面 A", "vid": "1" }, "ba": { "val": "对照版", "vid": "2" }, "tt": { "val": true, "vid": "3" } }

• Example:

  appLog.topicReceiver()?.on(Topic.ABTestConfigReady, (abTestConfig) => {
    hilog.info(0x0000, 'AppLogH', `AppLog abtest config ready:  ${JSON.stringify(abTestConfig)}`)
  })
  /*abTestConfig format:Is the specific experimental configuration{    "ab": {        "Val": "Visit page A",        "vid": "1"    },    "ba": {        "Val": "Comparison",        "vid": "2"    },    "tt": {        "val": true,        "vid": "3"    }}*/
  

Provides the ability to set user properties and provides a series of methods: profileSet, profileSetOnce, profileUnset, profileIncrement, profileAppend. The way to get the user properties plug-in is as follows:

appLog.profile()

set #

• Function: Set user properties, overwrite if they exist, and create if they don't exist.

• Definition: set (profile: EventRecord): void

• Parameters:

  Parameter name	Type	Required	Explain
  profile	EventRecord = Record<string, number	string	boolean

• Example:

  appLog.profile()?.set({
    "set1": "value",
    "set2": "value"
  })
  

setOnce #

• Function: Set user properties, do not set if they exist, create if they do not exist, suitable for first-time related user properties, such as first access time. Unlike the set interface, if a profile has been successfully set through the setOnce interface, it is invalid to call the setOnce interface again on the profile.

• Definition: setOnce (profile: EventRecord): void

• Parameters:

  Parameter name	Type	Required	Explain
  profile	EventRecord = Record<string, number	string	boolean

• Example:

  appLog.profile()?.setOnce({
    "setOnce": "value"
  })
  

increment #

• Function: Set the properties of the numeric type to accumulate.

• Definition: increment (profile: ProfileIncrementType): void

• Parameters:

  Parameter name	Type	Required	Explain
  profile	ProfileIncrementType = Record<string, number>	Yes	Can only increment integers (can be negative integers). If a floating-point number is passed in, the SDK will ignore it.

• Example:

  appLog.profile()?.increment({
    "increment": 1
  })
  

append #

• Function: Set the user properties of the collection type, which can be continuously added to the collection.

• Definition: append (profile: ProfileAppendType): void

• Parameters:

  Parameter name	Type	Required	Explain
  profile	ProfileAppendType = Record<string, number	string>	Yes

• Example:

  appLog.profile()?.append({
    "appendStr": "1",
    "appendNum": 1
  })
  

unset #

• Function: Delete the user's attributes.

• Definition: unset (profileKey: string): void

• Parameters:

  Parameter name	Type	Required	Explain
  profileKey	NSString	Yes	The name of the profile to unset

• Example:

  appLog.profile()?.unset("set2")
  

Since: 1.3.3 -rc3, this function depends on system capabilities, and similar lists such as LazyList are not supported for the time being.

Provides the ability to set component exposure acquisition, providing some methods: observeByNodeId, disposeByNodeId. The way to obtain the component exposure plug-in is as follows:

appLog.exposure()

observeByNodeId #

• Role: Monitor element exposure by component ID.

• Definition: observeByNodeId (id: string, context: UIContext, data?: ExposureData)

• Parameters:

  Parameter name	Type	Required	Explain
  id	string	Yes	Component ID
  context	UIContext	Yes	Ability context
  data	ExposureData	No	The ExposureData type is roughly as follows interface ExposureData { //Customizable exposure event name eventName?: string //Custom exposure event properties can be added properties?: EventRecord //Independent exposure configuration config?: ExposureConfig }

• Example:

  //You need to add an ID to the component.
  Button('Test', { stateEffect: true, type: ButtonType.Capsule })
    .id("test_btn"))
  
  //Please start monitoring after the page is built. If the input is too early and the corresponding component cannot be found through NodeId, the exposure cannot be processed.
  //Start exposure monitoring, and pass the ID to the SDK during exposure to determine which component's exposure needs to be monitored
  appLog.exposure()?.observeByNodeId("test_btn", this.getUIContext(), {
      //Optional, default is "$bav2b_exposure"
      eventName: "custom_exposure",
      //Optional, custom exposure event properties
      properties: {
          "test": "test"
      },
      //Optional, exposure configuration, effective exposure area and exposure event callback
      //Effective exposure area: The ratio of the display area of the effectively exposed View, the default is 0, and the value is 0-1.
      //Exposure event callback: When an exposure event is triggered, the callback will carry properties related to the current exposure event, which can be customized and appended, and supports filtering
      config: {
          exposureCallback: (param) => {
            //Support adding custom properties to callbacks
            //true keep exposure events
            return true
          }
      }
  })
  

disposeByNodeId #

• Function: Turn off the exposure of the corresponding component.

• Definition: disposeByNodeId (id: string): void

• Parameters:

  Parameter name	Type	Required	Explain
  id	string	Yes	Component ID

• Example:

  Discontinue exposure monitoring when appropriate, such as leaving the page or other logic
  appLog.exposure()?.disposeByNodeId("test_btn")