HarmonyOS SDK（Beta版）

注意事项

环境说明

当前saas、私有化环境暂不支持鸿蒙作为单独渠道，需配置 compatible 兼容模式字段为 true，设置后 platform 会以 and 安卓 上报。

版本说明

当前 HarmonyOS SDK 为 Bate 版，鸿蒙系统暂无正式版推出，本 SDK 基于鸿蒙 Developer Beta 版本开发，后续会随华为系统的更新与正式版发布持续迭代，当前功能适配非完整版本。

暂不支持多线程 / 多进程，鸿蒙系统比较特殊，采取线程间进程隔离，需额外适配方案。

1. 集成SDK

诸葛 HarmonyOS SDK 要求最低接入的鸿蒙版本为 API 12 及以上。

1.1 获取SDK

您需要联系诸葛技术支持获取 zhugeio.har 文件，该文件为鸿蒙 SDK 的离线包。

1.2 添加 zhugeioSDK 到项目中

将zhugeio.har文件，放到主工程目录entry的libs目录下，然后在DevEco Studio的Termial窗口中切换到需要引入本地模块源码的模块，即entry模块下，执行如下命令进行安装，该命令会在该模块下的oh-package.json5中自动添加依赖。

cd path/to/your/project/entry
ohpm install path/to/zhugeiosdk/zhugeio.har

看到如下输出即代表成功引入

install completed in 0s 84ms

1.3添加所需权限

在entry的module.json5文件中，添加如下权限:

{
  "module": {
    ...
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET",
        "reason": "$string:internet_permission"
      },
      {
        "name": "ohos.permission.GET_NETWORK_INFO",
        "reason": "$string:internet_permission"
      }
    ]
  }
}

权限说明

2. 初始化SDK

说明

建议您在用户同意您App中的隐私政策后，再进行 SDK 初始化。

2.1 获取 APPKEY

在开始集成前，首先拥有一个应用/主体，进行SDK集成前，您需要获取对应应用/主体的App Key信息。

您可以在「应用管理」->「主体管理」->「设置」中可查看您的App Key

2.2 获取数据上送地址

私有化部署版本需要获取数据上送地址。 如您不清楚此地址，请联系您的项目经理或技术支持。

2.3 初始化 SDK

鸿蒙将 startWithConfig 与 agreePrivacy 完全分离。

• startWithConfig 之后才可以调用 SDK 的各种方法，SDK 不支持 startWithConfig 之前进行埋点。
• agreePrivacy 之后才开始采集及上报数据，调用前触发的埋点将会丢弃处理。
• 如果创建了 AbilityStage ，可以将 startWithConfig 放在 AbilityStage 的 onCreate 中，可以在这里初始化 SDK，然后在隐私弹窗后再调用 agreePrivacy。

使用ZhugeioConfig实体类来定义信息，然后使用该参数初始化SDK：

import {Zhugeio, ZhugeioConfig } from 'zhugeio';

// 创建实例
let config = new ZhugeioConfig()
config.appKey = "appkey"
config.appChannel = "appchannel"
// 设置上报地址(默认为saas地址)
config.setServerUrl("https://su.zhugeio.com")
// 开启兼容模式（当前必须开启兼容模式）
config.compatible = true
let sdk = Zhugeio.getInstance()
sdk.startWithConfig(this.context,config)

// 用户同意隐私后调用该方法
Zhugeio.agreePrivacy()

Zhugeio.getInstance() 该方法返回Zhugeio SDK全局默认的实例对象，若无多主体需要，下方的所有接口均可通过该方法返回的实例调用。

参数说明：

上述三个参数为SDK必须的参数，不能为空。

2.3.1 ZhugeioConfig 参数选项

ZhugeioConfig是SDK初始化的配置参数载体，各项功能开关及自定义选项均通过该参数来传递，可选配置项有:

2.4 多实例初始化（可选，多主体/多实例 场景）

调用new Zhugeio()来获得一个新的SDK实例。然后针对每一个实例，定义上方的ZhugeioConfig，然后通过ZhugeioConfig来初始化对应的实例

import {Zhugeio, ZhugeioConfig } from 'zhugeio';

// 创建实例
let config = new ZhugeioConfig()
config.appKey = "appkey"
config.appChannel = "appchannel"
// 开始兼容模式（当前必须开启兼容模式）
config.compatible = true
let zg_user = new Zhugeio()
zg_user.startWithConfig(this.context,config)      

// 用户同意隐私后调用该方法
Zhugeio.agreePrivacy()

2.5 隐私弹窗处理

在用户同意您App中的隐私政策后，调用 agreePrivacy() 接口，开始采集及上报数据，在调用之前不会进行任何数据的采集及上报。

// 注意：此处需要使用 Zhugeio 类调用，全局生效
Zhugeio.agreePrivacy()

调用此方法后隐私协议同意状态数据存储在应用缓存中，如缓存被清理，需重新调用 agreePrivacy() 接口。

2.6 开启日志

若需开启或关闭诸葛相关的日志，请在初始化之前调用如下接口

Zhugeio.setLogEnable(enable:boolean);// 注意：此处需要使用 Zhugeio 类调用，全局生效

3. 埋点采集

以下接口，对应的SDK实例，均需初始化过才可使用

注意：下面调用方法是基于 sdk.xxx 进行调用，其中 sdk 为初始化后的SDK实例对象，参考 2.3 章节。

3.1 识别用户

为了保持对用户的跟踪，你需要为他们记录一个识别码，你可以使用用户id、email等唯一值来作为用户的识别码。另外，你可以在跟踪用户的时候， 记录用户更多的属性信息，便于你更了解你的用户：

sdk.identify(uid:string, prop?: HashMap<string, object>);

参数说明：

代码示例：

//定义用户识别码
let userid = user.getUserId();
//定义用户属性
let personObject = new HashMap<string,Object>()
personObject.set("avatar", "http://tp4.sinaimg.cn/5716173917/1")
personObject.set("name", "张三");personObject.put("gender", "男")
personObject.set("等级", 90)
//标识用户
sdk.identify(userid, personObject)

3.2 自定义事件

在你希望记录用户行为的位置，自定义事件，调用如下代码：

sdk.track(eventName: string, prop?: HashMap<string, Object>)

参数说明：

代码示例：

//定义与事件相关的属性信息  
let eventObject = new HashMap<string,Object>()
eventObject.set("分类", "手机")
eventObject.set("名称", "iPhone6 plus 64g")
//数值型属性不要带引号
eventObject.set("价格",  5888)
//记录事件
sdk.track("购买",  eventObject)

注意： 在添加事件属性时，需注意事件属性类型。如果事件属性类型为「数值型属性」，需要在上传数据时修改数据类型为「数值型」，并且在诸葛io后台埋点管理中修改为「数值型」。

3.3 事件时长统计

若你希望统计一个事件发生的时长，比如视频的播放，页面的停留，那么可以调用如下接口来进行：

sdk.startTrack(eventName: string)

说明：调用startTrack()来开始一个事件的统计，eventName为一个事件的名称

sdk.endTrack(eventName: string, prop?: HashMap<string, object>)

说明：调用endTrack()来记录事件的持续时长。调用endTrack()之前，相同eventName的事件必须已经调用过startTrack()，否则这个接口并不会产生任何事件。

代码示例：

//视频播放开始
sdk.startTrack("观看视频")
//视频观看结束
let pro = new HashMap<string,Object>()
pro.put("名称","非诚勿扰")
pro.put("期数","2016-11-02")
sdk.endTrack("观看视频",pro)

注意： startTrack()与endTrack()必须成对出现（eventName一致），单独调用一个接口是无效的。

更新记录

v1.0.1

发布时间：2024-08-27

• 增加隐私协议合规处理方法 agreePrivacy(注意：v1.0.0升级后，需在客户同意隐私协议后调用此方法，否则无法采集数据)

Zhugeio.agreePrivacy()

v1.0.0

发布时间：2024-08-12

• 初始化版本
• 采集用户信息
• 采集自定义事件
• 采集事件时长