文档反馈
问问助手本文为您介绍 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, numberstring
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
= numberstring
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, numberstring
boolean
示例：
appLog.profile()?.set({ "set1": "value", "set2": "value" })
setOnce
作用：设置用户属性，存在则不设置，不存在则创建，适合首次相关的用户属性，比如首次访问时间等。与set接口不同的是：若某profile已成功通过setOnce接口设置，那么对该profile再次调用setOnce接口无效。
定义：setOnce(profile: EventRecord): void
参数：
参数名
类型
必填
说明
profile
EventRecord
= Record<string, numberstring
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, numberstring>
是
示例：
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")