鸿蒙原生埋点 SDK

SDK 简介

GrowingIO OpenHarmony/HarmonyOS SDK 自动采集用户访问事件,并支持手动调用相应埋点 APIs 采集埋点事件。

  • 支持 HarmonyOS 4.0.0 - HarmonyOS NEXT

  • 支持 OpenHarmony API Level 10 - 12

准备条件

获取项目ID,获取方法请参考"项目管理 > 项目概览 > 查看项目基本信息"。

集成文档

通过 ohpm 中心仓集成

ohpm install @growingio/analytics

通过本地 har 集成

或者,您也可以通过本地 har 集成 首先请联系您的专属项目经理或技术支持,获取最新 SDK har 静态共享包下载地址并下载,再执行以下命令:

ohpm install <您所下载的 har 文件路径>

配置权限

在 module.json5 中配置所需权限:

"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET"
  },
  {
    "name": "ohos.permission.GET_NETWORK_INFO"
  }
]

初始化

在 AbilityStage 的 onCreate 方法中初始化 SDK (Stage 模型):

import AbilityStage from '@ohos.app.ability.AbilityStage'
import type Want from '@ohos.app.ability.Want'
import { GrowingAnalytics, GrowingConfig } from '@growingio/analytics'

// Entry类型的module对应配置的srcEntry
export default class MyAbilityStage extends AbilityStage {
  onCreate(): void {
    // 应用的HAP在首次加载的时,为该Module初始化操作
    this.startAnalytics()
  }
  onAcceptWant(want: Want): string {
    // 仅specified模式下触发
    return 'MyAbilityStage'
  }

  async startAnalytics() {
    let config = new GrowingConfig().SaaS(
      'Your AccountId',
      'Your UrlScheme'
    )
    await GrowingAnalytics.start(this.context, config)
  }
}

注意:如若需要,可在用户同意隐私协议之后,再进行初始化 SDK

其他初始化配置项见下表,在 start 方法调用前通过config.<配置项> = 对应值进行配置:

数据采集 API

初始化是否成功

static isInitializedSuccessfully(): boolean

返回是否初始化成功

let success = GrowingAnalytics.isInitializedSuccessfully()

数据采集开关

static setDataCollectionEnabled(enabled: boolean)

打开或关闭数据采集

GrowingAnalytics.setDataCollectionEnabled(true)

设置登录用户 ID

static setLoginUserId(userId: string)

当用户登录之后调用,设置登录用户 ID 如果您的 App 每次用户升级版本时无需重新登录的话,为防止用户本地缓存被清除导致的无法被识别为登录用户,建议在用户每次升级 App 版本后初次访问时重新调用 setLoginUserId 方法

参数说明

示例

GrowingAnalytics.setLoginUserId('user')

清除登录用户 ID

static cleanLoginUserId()

当用户登出之后调用,清除已经设置的登录用户ID

GrowingAnalytics.cleanLoginUserId()

设置用户的地理位置

static setLocation(latitude: number, longitude: number)

设置用户当前的地理位置,基于WGS-84坐标

参数说明

示例

const latitude: number = 30.0
const longitude: number = 120.0
GrowingAnalytics.setLocation(latitude, longitude)

清除用户的地理位置

static cleanLocation()

清除用户当前的地理位置

GrowingAnalytics.cleanLocation()

设置埋点事件

static track(eventName: string, attributes: { [key: string]: string | number | boolean | string[] | number[] | boolean[] } = {})

发送一个埋点事件;注意:在添加发送的埋点事件代码之前,需在分析云平台事件管理界面创建埋点事件以及关联事件属性

参数说明

示例

GrowingAnalytics.track('buyProduct1')

GrowingAnalytics.track('buyProduct2', {
  'name': 'apple',
  'money': 1000,
  'num': 100,
  'from': ['sichuan', 'guizhou', 'hunan']
})

事件计时器

static async trackTimerStart(eventName: string): Promise<string>

初始化一个事件计时器,参数为计时事件的事件名称,返回值为该事件计时器唯一标识

static async trackTimerPause(timerId: string)

暂停事件计时器,参数为 trackTimer 返回的唯一标识

static async trackTimerResume(timerId: string)

恢复事件计时器,参数为 trackTimer 返回的唯一标识

static async trackTimerEnd(timerId: string, attributes: { [key: string]: string | number | boolean | string[] | number[] | boolean[] } = {})

停止事件计时器,参数为 trackTimer 返回的唯一标识。调用该接口会自动触发删除定时器。

static removeTimer(timerId: string)

删除事件计时器,参数为 trackTimer 返回的唯一标识。 该接口会将标识为 timerId 的计时器置为空。调用停止计时器接口,会自动触发该接口。注意移除时不论计时器处于什么状态,都不会发送事件。

static clearTrackTimer()

清除所有已经注册的事件计时器。 存在所有计时器需要清除时调用。注意移除时不论计时器处于什么状态,都不会发送事件。

参数说明

示例

let timerId = await GrowingAnalytics.trackTimerStart('eventName')
GrowingAnalytics.trackTimerPause(timerId)
GrowingAnalytics.trackTimerResume(timerId)
GrowingAnalytics.trackTimerEnd(timerId)
GrowingAnalytics.trackTimerEnd(timerId, {
  'property': 'value',
  'property2': 100
})
GrowingAnalytics.removeTimer(timerId)
GrowingAnalytics.clearTrackTimer()

注意:

endTimer 时发送 CUSTOM 事件上报数据:

  • eventName 埋点事件标识符(trackTimerStart 传入)

  • attributes 用户自定义事件属性(trackTimerEnd 传入)

  • event_duration 事件时长 (SDK 内部根据 timerId 自动计算获取 ) > event_duration 按照秒上报,小数点精度保证到毫秒 > event_duration 变量及其值会自动添加在 attributes 中 > event_duration 时间统计不会计算后台时间

  • eventName 对应的埋点事件需要在平台中绑定标识符为 event_duration, 且类型为小数的事件属性

设置登录用户属性

static setLoginUserAttributes(attributes: { [key: string]: string | number | boolean | string[] | number[] | boolean[] })

以登录用户的身份定义登录用户属性,用于用户信息相关分析

参数说明

示例

GrowingAnalytics.setLoginUserAttributes({
  'name': 'ben',
  'age': 30
})

获取设备 ID

static getDeviceId(): string

获取设备 id,又称为匿名用户 id,SDK 自动生成用来定义唯一设备

let deviceId = GrowingAnalytics.getDeviceId()

事件通用属性

static setGeneralProps(props: { [key: string]: string | number | boolean | string[] | number[] | boolean[] })

为所有事件设置通用属性,多次调用,相同字段的新值将覆盖旧值;需在分析云平台事件管理界面关联事件属性

static removeGeneralProps(keys: string[])

移除指定字段的事件通用属性

static clearGeneralProps()

移除所有事件通用属性

static setDynamicGeneralProps(generator: () => { [key: string]: string | number | boolean | string[] | number[] | boolean[] })

设置动态通用属性

参数说明

示例

// 设置通用属性
GrowingAnalytics.setGeneralProps({
  'prop1': 10,
  'prop2': 'name',
  'prop3': [1, 2, 3],
  'prop4': ['a', 'b', 'c'],
  'name': 'banana'
})
// 清除指定字段的通用属性
GrowingAnalytics.removeGeneralProps(['prop1', 'prop2', 'prop3'])
// 清除通用属性
GrowingAnalytics.clearGeneralProps()
// 设置动态通用属性
GrowingAnalytics.setDynamicGeneralProps(() => {
  return {'dynamicProp' : Util.formatDate(new Date()) }
})
// 清除动态通用属性
GrowingAnalytics.setDynamicGeneralProps(() => ({}))

Hybrid 打通

static createHybridProxy(controller: webview.WebviewController): {
object: object;
name: string;
methodList: Array<string>;
controller: WebviewController;
} | undefined

在 webView 控件中注入 hybrid 实现打通 (javaScriptAccess 和 domStorageAccess 需同时设置为 true):

let url = 'https://www.example.com'
Web({ src: url, controller: this.controller})
  .javaScriptAccess(true)
  .domStorageAccess(true)
  .javaScriptProxy(GrowingAnalytics.createHybridProxy(this.controller))

对应的 H5 页面需要集成 Web JS SDK 以及 App 内嵌页打通插件才能生效

最后更新于