本文为您介绍 HarmonyOS 端为您提供的一系列API，您可以结合埋点规划调用对应API进行埋点。

init

• 作用：对SDK实例进行初始化设置，依赖ability的context，因此调用时机适合在onCreate生命周期里。

• 定义：init(context: common.Context, initConfig: InitConfig): void

• 参数：

  参数名	类型	必填	说明
  context	common.Context	是	ability的context
  initConfig	InitConfig	是	SDK内部实现管理初始化配置的类

• 示例：

  class EntryAbility extends UIAbility {
      onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
          // 创建新的 AppLog 实例
          let appLog = new AppLog()
          // 鸿蒙 sdk channel 作为可选参数
          let config = new InitConfig('yourAppId', 'yourChannel')
            // 是否打开日志
            .setLogEnabled(true)
            // 假如是上报到云原生，就可以设置上报地址为云原生域名
            .setUri(createByDomain('https://gator.volces.com'))
            
          // init sdk 传入配置，init 之后可以
          appLog.init(this.context, config)
          
          // ...
      }    
      // ...
  }
  

start

• 作用：让SDK实例开始真正准备执行事件上报，调用时机在init之后。
• 定义：start(): void
• 示例：

  class EntryAbility extends UIAbility {
      onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
          // 创建新的 AppLog 实例
          // ...
          // init sdk 传入配置，init 之后可以
          appLog.init(context, config)
          
          // 鸿蒙 SDK 需要手动调用 start 才开始采集敏感信息与发送请求
          appLog.start()
      }    
      // ...
  }
  

event

• 作用：上报事件，在初始化之后设置才能调用。

• 定义：event(eventName: string, params?: EventRecord): void

• 参数：

  参数名	类型	必填	说明
  eventName	string	是	事件名称，不能为nil或空字符串
  params	EventRecord = Record<string, number	string	boolean

• 示例：

  // 示例：上报事件 event_name，该事件不包含属性
  // 置于业务逻辑对应位置
  appLog.event('event_name')
  
  // 示例：上报事件 event_name，该事件包含两个属性
  // 一个 string 类型的属性，属性名为 key_string，属性值为 value_string
  // 一个 int 类型的属性，属性名为 key_int，属性值为 10
  // 置于业务逻辑对应位置
  appLog.event('event_name', {
    'key_string': 'value_string',
    'key_int': 10
  })
  

setHeaderInfo

• 作用：设置自定义的公共属性（非持久化）。

• 定义：setHeaderInfo(key: string, value: ObjectValue): void

• 参数：

  参数名	类型	必填	说明
  key	string	是	自定义公共属性名
  value	ObjectValue = number	string	boolean

• 示例：

  /*
   * 示例：设置自定义的公共属性，属性名为 key_public，属性值为 value_public
   * 关于自定义 “公共属性” 请注意：
   * 1. 上报机制是随着每一次日志发送进行提交，默认的日志发送频率是 1 分钟，
   *    所以如果在一分钟内连续修改自定义公共属性，按照日志发送前的最后一次修改为准；
   * 2. 不推荐高频次修改，如每秒修改一次。
   */
  appLog.setHeaderInfo('key_public', 'value_public')
  

removeHeaderInfo

• 作用：移除自定义的公共属性。

• 定义：removeHeaderInfo(key: string): void

• 参数：

  参数名	类型	必填	说明
  key	string	是	自定义上报key

• 示例：

  // 示例：移除属性名为 key_public 的公共属性
  appLog.removeHeaderInfo('key_public')
  

topicReceiver

• 作用：SDK内部实现了一套订阅发布机制，如果希望订阅SDK内部一些特定的事件，需要先调用topicReceiver获得实例的TopicReceiver对象。

• 定义：topicReceiver(): TopicReceiver | null

• 返回值：

  类型	说明
  TopicReceiver	TopicReceiver类实现了订阅发布的机制，大概如下 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 }

• 示例：

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

InitConfig是用来专门管理SDK初始化配置的类，提供一系列方法来设置初始化配置项。

InitConfig

• 作用：实例化一个管理初始化配置项对象。

• 定义：constructor(appId: string, channel?: string)

• 参数：

  参数名	类型	必填	说明
  appId	string	是	应用id
  channel	string	否	通道，由业务自己设置

• 示例：

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

setLogEnabled

• 作用：是否打开SDK运行日志。

• 定义：setLogEnabled(logEnabled: boolean): InitConfig

• 参数：

  参数名	类型	必填	说明
  logEnabled	boolean	是	是否打开SDK运行日志。

• 示例：

  let config = new InitConfig('yourAppId', 'yourChannel')
    // 是否打开日志
    .setLogEnabled(true)
  

setUri

• 作用：设置上报域名。

• 定义：setUri(uri: URiConfig): InitConfig

• 参数：

  参数名	类型	必填	说明
  uri	URiConfig	是	uri的值是一个域名。 SDK提供createByDomain来辅助处理域名，生成一系列内部需要使用的请求地址，其中包含事件上报请求地址、激活请求地址等。

• 示例：

  let config = new InitConfig('yourAppId', 'yourChannel')
    // 设置域名，通过createByDomain可以帮助生成一系列内部请求地址
    .setUri(createByDomain("https://gator.volces.com"))
  

setOaidEnabled

• 作用：oaid 采集开关。

• 定义：setOaidEnabled(enabled: boolean): InitConfig

• 参数：

  参数名	类型	必填	说明
  enabled	boolean	是	oaid 采集开关。

• 示例：

  let config = new InitConfig('yourAppId', 'yourChannel')
    // 开启获取oaid
    .setOaidEnabled(true)
  

setOperatorInfoEnabled

• 作用：运营商信息采集开关。

• 定义：setOperatorInfoEnabled(enabled: boolean): InitConfig

• 参数：

  参数名	类型	必填	说明
  enabled	boolean	是	运营商信息采集开关。

• 示例：

  let config = new InitConfig('yourAppId', 'yourChannel')
    // 开启获取oaid
    .setOperatorInfoEnabled(true)
  

用户信息插件，设置与获取用户信息，如 user_unique_id。获取用户信息插件的方式如下：

appLog.user()

setUserUniqueID

• 作用：设置user_unique_id字段。

• 定义：setUserUniqueID(uuid: string | null, uuidType?: string | null): void

• 参数：

  参数名	类型	必填	说明
  uuid	string	null	是，可null
  uuidType	string	null	否 当值不为null时，SDK将该值设置给内部维护的user_unique_id_type字段；同理当为null时，SDK将清空user_unique_id_type字段的值；

• 示例：

  // 设置 UUID
  appLog.user()?.setUserUniqueID("your_uuid")
  
  // 如果有多口径需求可以看下面的设置
  // 设置 UUID + UUIDType
  appLog.user()?.setUserUniqueID("your_uuid", "your_uuid_type")
  // 单参数的 setUserUniqueID(uuid) 等效于 双参数的 setUserUniqueID(uuid, lastuuidType) 只是默认情况下 uuidType 没有，如果设置过 uuidType 想要清空，需要额外设置:
  appLog.user()?.setUserUniqueID("your_uuid", null)
  
  // 登出 UUID
  appLog.user()?.setUserUniqueID(null)
  
  // 如果有多口径需求可以看下面的设置
  // 登出 UUID + UUIDType
  appLog.user()?.setUserUniqueID(null, null)
  

getUserUniqueID

• 作用：获取SDK内部维护的user_unique_id字段的值。
• 定义：getUserUniqueID(): string | null
• 示例：

  // 获取当前 UUID
  const uuid = appLog.user()?.getUserUniqueID()
  

getUserUniqueIDType

• 作用：获取SDK内部维护的user_unique_id_type字段的值。
• 定义：getUserUniqueIDType(): string | null
• 示例：

  // 获取当前 UUIDType
  const uuidType = appLog.user()?.getUserUniqueIDType()
  

SDK提供AB实验能力，提供了AB实验插件，该插件包含一系列的方法：getAbConfig、getAbSdkVersion、getAllAbTestConfigs。获取AB实验插件的方式如下：

appLog.abTest()

getAbConfig

• 作用：获取AB实验的配置值。

• 定义：getAbConfig(key: string, defaultValue: T): T

• 参数：

  参数名	类型	必填	说明
  key	NSString	是	AB实验配置的key
  defaultValue	T extends **** string	boolean	number

• 示例：

  // 建议每次在获取最新 AB 后触发实验
  appLog.topicReceiver().on(Topic.ABTestConfigReady, (_) => {
      appLog.abTest()?.getAbConfig("ab_key", defaultValue)
  })
  

getAbSdkVersion

• 作用：获取已曝光的AB实验配置的vids。
• 定义：getAbSdkVersion(): string
• 示例：

  appLog.abTest()?.getAbSdkVersion()
  

getAllAbTestConfigs

• 作用：获取AB实验的所有配置项。

• 定义：getAllAbTestConfigs(): Record<string, ABTestItem>

• 返回值：

  类型	说明
  Record<string, ABTestItem>	值类似 { "ab": { "val": "访问页面 A", "vid": "1" }, "ba": { "val": "对照版", "vid": "2" }, "tt": { "val": true, "vid": "3" } }

• 示例：

  appLog.topicReceiver()?.on(Topic.ABTestConfigReady, (abTestConfig) => {
    hilog.info(0x0000, 'AppLogH', `AppLog abtest config ready:  ${JSON.stringify(abTestConfig)}`)
  })
  /*
  abTestConfig 格式：
  就是具体的实验配置
  {
      "ab": {
          "val": "访问页面 A",
          "vid": "1"
      },
      "ba": {
          "val": "对照版",
          "vid": "2"
      },
      "tt": {
          "val": true,
          "vid": "3"
      }
  }
  */
  

提供设置用户属性能力，并提供了一系列的方法：profileSet、profileSetOnce、profileUnset、profileIncrement、profileAppend。获取用户属性插件的方式如下：

appLog.profile()

set

• 作用：设置用户属性，存在则覆盖，不存在则创建。

• 定义：set(profile: EventRecord): void

• 参数：

  参数名	类型	必填	说明
  profile	EventRecord = Record<string, number	string	boolean

• 示例：

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

setOnce

• 作用：设置用户属性，存在则不设置，不存在则创建，适合首次相关的用户属性，比如首次访问时间等。与set接口不同的是：若某profile已成功通过setOnce接口设置，那么对该profile再次调用setOnce接口无效。

• 定义：setOnce(profile: EventRecord): void

• 参数：

  参数名	类型	必填	说明
  profile	EventRecord = Record<string, number	string	boolean

• 示例：

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

increment

• 作用：设置数值类型的属性，可进行累加。

• 定义：increment(profile: ProfileIncrementType): void

• 参数：

  参数名	类型	必填	说明
  profile	ProfileIncrementType = Record<string, number>	是	只能自增整数（可以为负整数）。如果传入浮点数，SDK将忽略。

• 示例：

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

append

• 作用：设置集合类型的用户属性，可持续向集合内添加。

• 定义：append(profile: ProfileAppendType): void

• 参数：

  参数名	类型	必填	说明
  profile	ProfileAppendType = Record<string, number	string>	是

• 示例：

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

unset

• 作用：删除用户的属性。

• 定义：unset(profileKey: string): void

• 参数：

  参数名	类型	必填	说明
  profileKey	NSString	是	要unset的profile的名称

• 示例：

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

该功能仅付费版支持，如有需要请联系我们，默认提供的基础版不带该功能。

提供设置组件曝光采集能力，提供了一些方法：observeByNodeId、disposeByNodeId。获取组件曝光插件的方式如下：

appLog.exposure()

observeByNodeId

• 作用：通过组件 ID 监控元素曝光。

• 定义：observeByNodeId(id: string, context: UIContext, data?: ExposureData)

• 参数：

  参数名	类型	必填	说明
  id	string	是	组件 ID
  context	UIContext	是	ability的context
  data	ExposureData	否	ExposureData类型大概如下 interface ExposureData { // 可自定义曝光事件名称 eventName?: string // 可添加自定义曝光事件属性 properties?: EventRecord // 独立曝光配置 config?: ExposureConfig }

• 示例：

  //  需要给组件添加 ID
  Button('Test', { stateEffect: true, type: ButtonType.Capsule })
    .id("test_btn"))
  
  //  请在页面 build 后开始监控，如果传入过早，无法通过 NodeId 找到对应组件，就无法处理曝光
  //  开始曝光监控，曝光时给 SDK 传给 ID，来确定需要监控哪个组件的曝光
  appLog.exposure()?.observeByNodeId("test_btn", this.getUIContext(), {
      //  Optional，默认为 "$bav2b_exposure"
      eventName: "custom_exposure",
      //  Optional，自定义曝光事件属性
      properties: {
          "test": "test"
      },
      //  Optional, 曝光配置，有效曝光面积和曝光事件回调
      //  有效曝光面积: 有效曝光的 View 显示面积的比例，默认是 0，取值 0-1
      //  曝光事件回调: 触发曝光事件时回调，会携带当前曝光事件相关属性，可以进行自定义追加以及支持过滤
      config: {
          exposureCallback: (param) => {
            //  支持在回调中添加自定义属性
            //  true 保留曝光事件
            return true
          }
      }
  })
  

disposeByNodeId

• 作用：关闭对应组件的曝光。

• 定义：disposeByNodeId(id: string): void

• 参数：

  参数名	类型	必填	说明
  id	string	是	组件 ID

• 示例：

  //  在适当实际停止曝光监控，如离开页面或者其他逻辑
  appLog.exposure()?.disposeByNodeId("test_btn")