基础 API 介绍（HarmonyOS）

用户关联

用户关联是为了对用户进行唯一标识，提高用户行为分析的准确性。目前神策提供了简易用户关联和全域用户关联分为用于支撑不同的业务场景。

• 简易用户关联（IDM 2.0）
• 全域用户关联（IDM 3.0）

用户属性

• 关于事件属性和用户属性的区别，请参考数据模型
• 用户属性的命名约束，请参考数据格式

设置用户属性

setProfile() 方法可以设置用户属性，同一个 key 多次设置时，value 值会进行覆盖替换：

sensors.setProfile({email:'xxx@xx'});

记录初次设定的用户属性

setOnceProfile() 方法可以设置用户属性，如果属性不存在则设置，存在就不设置。

sensors.setOnceProfile({email:'xxx@xx'});

数值类型的属性

对于数值型的用户属性，可以使用 incrementProfile() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如：

// 表示 navClick 递减
sensors.incrementProfile({'navClick': -1});
// 表示 navClick 递增2
sensors.incrementProfile({'navClick': 2});
// 直接传入一个属性名，表示递增1
sensors.incrementProfile('navClick');

列表类型的属性

对于用户喜爱的电影、用户点评过的餐厅等属性，可以记录列表型属性，例如：

//给 category 增加两个值
sensors.appendProfile({category: ['玉米','白菜']});
//给 category 增加一个值
sensors.appendProfile({category: '玉米'});

需要注意的是，列表型属性中的元素必须为 String 类型。关于列表型限制请见数据格式。

属性取消

如果需要取消已设置的某个用户属性，可以调用 unsetProfile() 进行取消：

//删除 email 和 location 属性
sensors.unsetProfile(['email','location']);
//删除 email 属性
sensors.unsetProfile('email');

埋点事件采集

在 SDK 初始化完成之后，您可以通过以下接口进行数据埋点。

代码埋点追踪事件

SDK 初始化后，可以通过 track() 方法追踪用户行为事件，并为事件添加自定义属性。

sensors.track('MyEvent',{prop1:'value1'});

事件名和事件属性的格式规范，请参考数据格式。

埋点事件采集时长属性

可以通过计时器统计事件的持续时间。首先，在事件开始时调用 trackTimerStart("Event") ，该方法并不会真正发送事件；在事件结束时，调用 trackTimerEnd("Event", properties)，SDK 会触发 "Event" 事件，并自动将事件持续时间记录在事件属性 "$event_duration" 中。例如记录用户浏览商品页面的时间：

// 进入商品页面
// 调用 trackTimerStart("ViewProduct") 标记事件启动时间
let timer = sensors.trackTimerStart("ViewProduct");

// ... 用户浏览商品

// 离开商品页

// 在属性中记录商品 ID
// 调用 track，记录 ViewProduct 事件，并在属性 event_duration 中记录用户浏览商品的时间   	         
sensors.trackTimerEnd(timer, {productId:'value1'});

注意务必确保 trackTimerStart 和 trackTimerEnd 接口配对使用, trackTimerEnd 调用后再次调用时间不再累计，以第一次调用 trackTimerEnd 时 $event_duration 值再次发送统计事件。

统计事件时长支持暂停和恢复，通过调用 trackTimerPause 和 trackTimerResume 来分别实现暂停和恢复。

同名事件交叉的时长统计

SDK 支持同名事件交叉的时长统计，开发者需要保存 trackTimerStart() 的返回值，以便后续针对性地进行暂停、恢复或停止。

// 开始第一个事件计时
let timer1 = sensors.trackTimerStart("testTimer");

// 开始第二个事件计时
let timer2 = sensors.trackTimerStart("testTimer");

//如果需要暂停第一个事件计时 
sensors.trackTimerPause(timer1);

//如果需要恢复第一个事件计时 
sensors.trackTimerResume(timer1);

// 结束第一个事件计时 
sensors.trackTimerEnd(timer1);

// 结束第二个事件计时 
sensors.trackTimerEnd(timer2);

清除统计

调用 clearTrackTimer 清除指定 timer

let timer = sensors.trackTimerStart("testTimer");
// 从内存中清除
sensors.clearTrackTimer(timer);

物品元数据上报

在神策推荐项目中，客户需要将物品元数据上报，以开展后续推荐业务的开发与维护。HarmonyOS SDK 提供了设置与删除物品元数据的方法。

item_id（物品 ID ）与 item_type （物品所属类型）共同组成了一个物品的唯一标识。所有的 item 系列方法都必须同时指定物品 ID 及物品所属类型这两个参数，来完成对物品的操作。

设置物品属性

直接设置一个物品，如果已存在则覆盖。除物品 ID 与物品所属类型外，其他物品属性需在 properties 中定义。

物品属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。

setItem(item_type,item_id,properties)

item_type：string，必选。

item_id：string，必选。

properties：object，可选。

sensors.setItem("food","2",{name:"玉米",flavour:"甜"});

删除物品属性

如果物品不可被推荐需要下线，删除该物品即可，如不存在则忽略。除物品 ID 与 物品所属类型外，不解析其他物品属性。

deleteItem(item_type,item_id)

tem_type：string，必选。

item_id：string，必选。

sensors.deleteItem("food","2");

清空本地缓存事件

为了支持 GDPR 规范，v0.1.0+ 版本 SDK 增加了 - deleteAll 方法用于清空本地缓存的所有事件：

sensors.deleteAll();

事件公共属性

设置事件静态公共属性

对于所有事件都需要添加的属性，初始化 SDK 后，可使用 -register 将属性注册为公共属性：

sensors.register({
	current_url: location.href,
	referrer: document.referrer
});

• 静态公共属性会保存在 App 本地缓存中
• 可以通过 - clearAllRegister 删除指定或所有的公共属性

设置事件动态公共属性

对于一些值会变化的公共属性，如当前游戏等级、最新金币余额等，可以注册动态公共属性。

sensors.registerApp({
  random: () => {
    return Math.random();
  }
});

上面的属性值 random 在每次事件生成的时候，都会去重新计算

• 动态公共属性，不会持久化到本地。
• 可以通过 - clearAppRegister 删除指定或所有的公共属性

SDK 加密

为了加强埋点数据的安全合规，神策分析 HarmonyOS SDK 支持对埋点数据进行加密，并以密文的形式对数据进行存储和发送。

注意

本功能需要服务端的配合，可以联系神策客户成功/项目经理协助开通服务端解密功能。HarmonyOS SDK 目前支持支持 AES-RSA 和 SM 国密类型的加密方式。

SDK 端开启加密

对于 v0.2.1 及以上版本 SDK，可以通过初始化并注册加密插件的方式，开启 SDK 埋点数据加密

import sensors, { SAAESEncryption } from '@sensorsdata/analytics';

sensors.use(SAAESEncryption, {
    pkv: 加密秘钥版本号,
    pub_key: "RSA 公钥"
}); 

参数说明：

• pkv: 加密密钥版本号，类型：number。
• pub_key: RSA 加密公钥，类型：string。

以上参数信息可以通过神策后台【数据管理】-【数据接入引导】-【客户端埋点】-【密钥管理】页面进行获取或通过该页面进行新建。

获取相关属性

{
"$is_first_day":false,
"mm333":333, // register,registerApp 传入的公共属性
"$os":"HarmonyOS",
"$timezone_offset":-480,
"$screen_height":2772,
"$screen_width":1344,
"$manufacturer":"HUAWEI",
"$brand":"HUAWEI",
"$model":"NOH-AN00",
"$os_version":"2.1.7.1",
"$app_id":"com.example.myapplication",
"$app_name":"MyApplication",
"$app_version":"1.0.0"
}