1. 介绍

相较于简易用户关联模式只能使用 2 个业务 ID 参与用户关联,在此模式下,若您的实际业务与场景需要区别多个用户业务 ID 的实际语义,则可通过自定义业务 ID 并赋值上传参与用户关联。关于自定义业务 ID 的方式。

2. 接口介绍

2.1. 更改匿名 ID

2.1.1. 调用时机

匿名 ID 默认由神策 SDK 自动采集或生成。绝大多数场景下,您无需主动更改 匿名 ID 的值。

在鸿蒙系统下,匿名 ID 的取值默认为 UUID。若您需要自定义匿名 ID 的值,则可通过调用此接口来实现。

2.1.2. 使用准备

使用该接口前,请确保您对于神策的接口与用户关联概念有深入的了解。

2.1.3. 接口说明

identify(anonymousId: string): void,
CODE

参数名称

类型

是否必须

说明

anonymousIdString匿名用户 ID,非空字符串,需要保证唯一性,不然会影响用户关联

使用示例:

sensors.identify('your_customized_anonymous_id');
CODE

调用此接口后,神策 SDK 将会修改事件上报数据中的 “anonymous_id”、“$identity_anonymous_id” 的值。

若在未调用 用户登录 接口前,即还未对 “login_id” 和 “$identity_login_id” 赋值时(一般称这类用户为匿名状态用户)。SDK 还会同步修改 “distinct_id” 的值。

例如,调用此接口前,一个处于匿名状态的用户触发了控件点击事件($AppClick),则事件上报数据示例如下:

{
	"identities": {
		"$identity_harmony_uuid": "62d5af0c-f667-4d03-ae2f-837da2d5140e",   
        "$identity_anonymous_uuid": "62d5af0c-f667-4d03-ae2f-837da2d5140e" // SDK 默认采集的匿名 ID,默认为 UUID
    },
	"anonymous_id": "62d5af0c-f667-4d03-ae2f-837da2d5140e",   // 匿名 ID  
	"distinct_id": "62d5af0c-f667-4d03-ae2f-837da2d5140e",    // 神策用户标识 distinct_id,在匿名状态下是匿名 ID 
	"lib": {
		"$lib": "HarmonyOS",
		"$lib_method": "code",
		"$lib_version": "0.0.5",
		"$app_version": "0.0.3"
	},
	"properties": {
		"$timezone_offset": -480,
		"$screen_height": 2772,
		"$screen_width": 1344,
		"$app_id": "com.sensorsdata.sensorsdatasdk",
		"$app_name": "神策分析 SDK",
		"$app_version": "0.0.3",
		"$manufacturer": "HUAWEI",
		"$brand": "HUAWEI",
		"$model": "NOH-AN00",
		"$os_version": "2.1.7.1",
		"$network_type": "WiFi",
		"$screen_orientation": "PORTRAIT",
		"$screen_name": "Index",
		"$lib": "HarmonyOS",
		"$lib_method": "code",
		"$lib_version": "1.0.0",
		"$data_ingestion_source": [
			"HarmonyOS"
		],
		"$os": "HarmonyOS",
		"$is_first_day": true,
		"$is_first_time": false
	},
	"type": "track",
	"event": "$AppClick",
	"time": 1712825022595,
	"_track_id": 659542613
}
CODE

若此时,调用 更改匿名 ID(identify) 接口传入一个自定义的匿名 ID 值,例如 “your_customized_anonymous_id” ,则后续发生的事件数据中的匿名 ID 都会更改,事件上报数据示例如下:

{
    "identities": {
        "$identity_anonymous_uuid": "your_customized_anonymous_id",   
        "$identity_harmony_uuid": "204ccdb8-7fc3-4aa0-8012-72fac26518d0" // SDK 默认采集的匿名 ID,一般为 UUID
    },
    "anonymous_id": "your_customized_anonymous_id",   // 匿名 ID  
    "distinct_id": "your_customized_anonymous_id",    // 神策用户标识 distinct_id,在匿名状态下就是匿名 ID 
    "lib": {
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "0.0.5",
        "$app_version": "0.0.3"
    },
    "properties": {
        "$timezone_offset": -480,
        "$screen_height": 2772,
        "$screen_width": 1344,
        "$app_id": "com.sensorsdata.sensorsdatasdk",
        "$app_name": "神策分析 SDK",
        "$app_version": "0.0.3",
        "$manufacturer": "HUAWEI",
        "$brand": "HUAWEI",
        "$model": "NOH-AN00",
        "$os_version": "2.1.7.1",
        "$network_type": "WiFi",
        "$screen_orientation": "PORTRAIT",
        "$screen_name": "Index",
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "1.0.0",
        "$data_ingestion_source": [
            "HarmonyOS"
        ],
        "$os": "HarmonyOS",
        "$is_first_day": true,
        "$is_first_time": false
    },
    "type": "track",
    "event": "$AppClick",
    "time": 1712825022595,
    "_track_id": 659542613
}
CODE

2.2. 用户登录

2.2.1. 调用时机

当用户进行登录时,您需主动调用此接口,将用户的注册信息(一般为用户在您业务系统中的唯一身份标识)传入。

2.2.2. 使用准备

登录 ID 在神策的用户关联体系中非常重要,因此,强烈建议您在用户发生注册或登录时调用此接口来记录用户的 登录 ID。

2.2.3. 接口说明

login(loginId: string, properties?: EventProps): Promise<void>
CODE
参数名称类型是否必须说明
loginIdString用户登录 ID,非空字符串,

使用示例:

sensors.login('your_customer_id');
CODE

调用 用户登录(login) 接口后,神策 SDK 会触发神策系统预置的 “$SignUp” 事件,事件数据中会带有 “login_id” 和 “$identity_login_id”。且 “distinct_id” 的值修将被改为传入的登录 ID。

与此同时,神策 SDK 会将 “login_id” 和 “$identity_login_id” 的信息缓存在当前设备。这样后续当前设备上触发的所有事件中都会带有 “login_id” 和 “$identity_login_id” 信息。

例如,在调用 用户登录(login)  接口前,一个处于匿名状态的用户触发了控件点击事件($AppClick),事件上报信息示例如下:

{
    "identities": {
        "$identity_anonymous_uuid": "your_customized_anonymous_id",   
        "$identity_harmony_uuid": "204ccdb8-7fc3-4aa0-8012-72fac26518d0" // SDK 默认采集的匿名 ID,默认为 UUID
    },
    "anonymous_id": "your_customized_anonymous_id",   // 匿名 ID 
    "distinct_id": "your_customized_anonymous_id",    // 神策用户标识 distinct_id,在登录状态下是匿名 ID 
    "lib": {
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "0.0.5",
        "$app_version": "0.0.3"
    },
    "properties": {
        "$timezone_offset": -480,
        "$screen_height": 2772,
        "$screen_width": 1344,
        "$app_id": "com.sensorsdata.sensorsdatasdk",
        "$app_name": "神策分析 SDK",
        "$app_version": "0.0.3",
        "$manufacturer": "HUAWEI",
        "$brand": "HUAWEI",
        "$model": "NOH-AN00",
        "$os_version": "2.1.7.1",
        "$network_type": "WiFi",
        "$screen_orientation": "PORTRAIT",
        "$screen_name": "Index",
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "1.0.0",
        "$data_ingestion_source": [
            "HarmonyOS"
        ],
        "$os": "HarmonyOS",
        "$is_first_day": true,
        "$is_first_time": false
    },
    "type": "track",
    "event": "$AppClick",
    "time": 1712825022595,
    "_track_id": 659542613
}
CODE

调用  用户登录(login) 接口后,神策 SDK 会自动触发神策预置的 $SignUp 事件,记录了用户登录 ID 和其他 业务 ID 的信息。事件上报信息示例如下:

{
    "identities": {
        "$identity_anonymous_uuid": "your_customized_anonymous_id",   
        "$identity_harmony_uuid": "204ccdb8-7fc3-4aa0-8012-72fac26518d0",  // SDK 默认采集的匿名 ID,默认为 UUID
        "$identity_login_id": "your_customer_id"
    },
    "anonymous_id": "your_customized_anonymous_id",   // 匿名 ID 
	"login_id":	"your_customer_id",
    "distinct_id": "your_customer_id",    // 神策用户标识 distinct_id,在登录状态下是登录 ID 
    "lib": {
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "0.0.5",
        "$app_version": "0.0.3"
    },
    "properties": {
        "$timezone_offset": -480,
        "$screen_height": 2772,
        "$screen_width": 1344,
        "$app_id": "com.sensorsdata.sensorsdatasdk",
        "$app_name": "神策分析 SDK",
        "$app_version": "0.0.3",
        "$manufacturer": "HUAWEI",
        "$brand": "HUAWEI",
        "$model": "NOH-AN00",
        "$os_version": "2.1.7.1",
        "$network_type": "WiFi",
        "$screen_orientation": "PORTRAIT",
        "$screen_name": "Index",
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "1.0.0",
        "$data_ingestion_source": [
            "HarmonyOS"
        ],
        "$os": "HarmonyOS",
        "$is_first_day": true,
        "$is_first_time": false
    },
    "type": "track_signup",
    "event": "$SignUp ",
    "time": 1712825022595,
    "_track_id": 659542613
}
CODE

如前文所诉,神策 SDK 将在当前设备缓存 ”login_id“ 和 “$identity_login_id” 的信息。因此 后续在此设备上触发的所有事件都会带上  ”login_id“ 和 “$identity_login_id” 的信息。

若此时用户在当前设备上又触发了控件点击事件($AppClick),则事件数据示例如下:

{
    "identities": {
        "$identity_anonymous_uuid": "your_customized_anonymous_id",   
        "$identity_harmony_uuid": "204ccdb8-7fc3-4aa0-8012-72fac26518d0" // SDK 默认采集的匿名 ID,默认为 UUID
        "$identity_login_id": "your_customer_id" 
    },
    "anonymous_id": "your_customized_anonymous_id",   // 匿名 ID
  	"login_id":	"your_customer_id", 				  // 登录 ID
    "distinct_id": "your_customer_id",    // 神策用户标识 distinct_id,在登录状态下是匿名 ID
    "lib": {
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "0.0.5",
        "$app_version": "0.0.3"
    },
    "properties": {
        "$timezone_offset": -480,
        "$screen_height": 2772,
        "$screen_width": 1344,
        "$app_id": "com.sensorsdata.sensorsdatasdk",
        "$app_name": "神策分析 SDK",
        "$app_version": "0.0.3",
        "$manufacturer": "HUAWEI",
        "$brand": "HUAWEI",
        "$model": "NOH-AN00",
        "$os_version": "2.1.7.1",
        "$network_type": "WiFi",
        "$screen_orientation": "PORTRAIT",
        "$screen_name": "Index",
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "1.0.0",
        "$data_ingestion_source": [
            "HarmonyOS"
        ],
        "$os": "HarmonyOS",
        "$is_first_day": true,
        "$is_first_time": false
    },
    "type": "track",
    "event": "$AppClick",
    "time": 1712825022595,
    "_track_id": 659542613
}
CODE


2.3. 绑定业务 ID

2.3.1. 调用时机

该接口用于为您自定义的业务 ID 进行赋值。当您的系统获取到或用户填写了对应业务 ID 的值时,您可通过调用此接口,将对应业务 ID 的值传入。

例如,业务需要使用用户的邮箱进行用户关联。则可在用户完成邮箱验证后,通过调用此接口,将邮箱信息传入 $identity_email 中。

2.3.2. 使用准备

  • 使用该接口前,请确保您对于神策的接口与用户关联概念有深入的了解。
  • 神策系统中的字段遵循先声明后上报的规则。因此,若您需要使用自定义业务 ID 进行用户关联时,请确保您已在神策系统中完成了您所需的业务 ID 的定义。

2.3.3. 接口说明

bind(name: string, value: string)
CODE

参数名称

类型

是否必须

说明

keyString需要绑定的业务 ID 的 key,例如我们可以绑定一个 identify_email 的 key
valueString需要绑定的业务 ID 的 value

使用示例:

sensors.bind("identity_customized_business_id", "your_customized_binding_business_value")
CODE

调用 绑定业务 ID(bind) 接口后,神策 SDK 会触发神策预置的 “$BindID” 事件,并在该事件数据中记录接口调用时传入的业务 ID 的信息。同时 神策 SDK 会将接口中传入的业务 ID 信息缓存到当前设备,后续触发的所有事件都将携带此业务 ID 相关信息。

例如,调用 绑定业务 ID(bind) 接口前,用户触发了一个按钮点击事件($AppClick)时,事件示例数据如下:

{
    "identities": {
        "$identity_anonymous_uuid": "your_customized_anonymous_id",   
        "$identity_harmony_uuid": "204ccdb8-7fc3-4aa0-8012-72fac26518d0" // SDK 默认采集的匿名 ID,默认为 UUID
    },
    "anonymous_id": "your_customized_anonymous_id",   // 匿名 ID  
    "distinct_id": "your_customized_anonymous_id",    // 神策用户标识 distinct_id,在匿名状态下是匿名 ID 
    "lib": {
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "0.0.5",
        "$app_version": "0.0.3"
    },
    "properties": {
        "$timezone_offset": -480,
        "$screen_height": 2772,
        "$screen_width": 1344,
        "$app_id": "com.sensorsdata.sensorsdatasdk",
        "$app_name": "神策分析 SDK",
        "$app_version": "0.0.3",
        "$manufacturer": "HUAWEI",
        "$brand": "HUAWEI",
        "$model": "NOH-AN00",
        "$os_version": "2.1.7.1",
        "$network_type": "WiFi",
        "$screen_orientation": "PORTRAIT",
        "$screen_name": "Index",
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "1.0.0",
        "$data_ingestion_source": [
            "HarmonyOS"
        ],
        "$os": "HarmonyOS",
        "$is_first_day": true,
        "$is_first_time": false
    },
    "type": "track",
    "event": "$AppClick",
    "time": 1712825022595,
    "_track_id": 659542613
}
CODE

此时,调用 绑定业务 ID(bind) 接口,会触发神策预置的 “$BindID” 事件,事件信息中会记录接口中传入的业务 ID 的相关信息,事件数据信息示例如下:

{
    "identities": {
        "$identity_anonymous_uuid": "your_customized_anonymous_id",   
        "$identity_harmony_uuid": "204ccdb8-7fc3-4aa0-8012-72fac26518d0",   // SDK 默认采集的匿名 ID,默认为 UUID
        "identity_customized_business_id": "your_customized_binding_business_value"  // 通过调用 bind(绑定业务 ID)接口设置业务 ID
    },
    "anonymous_id": "your_customized_anonymous_id",   // 匿名 ID  
    "distinct_id": "your_customized_anonymous_id",    // 神策用户标识 distinct_id,在匿名状态下是匿名 ID 
    "lib": {
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "0.0.5",
        "$app_version": "0.0.3"
    },
    "properties": {
        "$timezone_offset": -480,
        "$screen_height": 2772,
        "$screen_width": 1344,
        "$app_id": "com.sensorsdata.sensorsdatasdk",
        "$app_name": "神策分析 SDK",
        "$app_version": "0.0.3",
        "$manufacturer": "HUAWEI",
        "$brand": "HUAWEI",
        "$model": "NOH-AN00",
        "$os_version": "2.1.7.1",
        "$network_type": "WiFi",
        "$screen_orientation": "PORTRAIT",
        "$screen_name": "Index",
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "1.0.0",
        "$data_ingestion_source": [
            "HarmonyOS"
        ],
        "$os": "HarmonyOS",
        "$is_first_day": true,
        "$is_first_time": false
    },
    "type": "track_id_bind",
    "event": "$BindID",
    "time": 1712825022595,
    "_track_id": 659542613
}
CODE

如前文所述,神策 SDK 会在 绑定业务 ID(bind) 接口被调用后,将接口中的业务 ID 信息缓存在本地,这样续触发的所有事件都会带上此次接口携带的业务 ID 信息。

例如,此时用户又在当前设备上触发了一个按钮点击事件($AppClick)时,则事件数据示例如下:

{
    "identities": {
        "$identity_anonymous_uuid": "your_customized_anonymous_id",   
        "$identity_harmony_uuid": "204ccdb8-7fc3-4aa0-8012-72fac26518d0", // SDK 默认采集的匿名 ID,默认为 UUID
        "identity_customized_business_id": "your_customized_binding_business_value"  // 调用 bind(绑定业务 ID)后,该 ID 会缓存在本地
    },
    "anonymous_id": "your_customized_anonymous_id",   // 匿名 ID  
    "distinct_id": "your_customized_anonymous_id",    // 神策用户标识 distinct_id,在匿名状态下是匿名 ID 
    "lib": {
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "0.0.5",
        "$app_version": "0.0.3"
    },
    "properties": {
        "$timezone_offset": -480,
        "$screen_height": 2772,
        "$screen_width": 1344,
        "$app_id": "com.sensorsdata.sensorsdatasdk",
        "$app_name": "神策分析 SDK",
        "$app_version": "0.0.3",
        "$manufacturer": "HUAWEI",
        "$brand": "HUAWEI",
        "$model": "NOH-AN00",
        "$os_version": "2.1.7.1",
        "$network_type": "WiFi",
        "$screen_orientation": "PORTRAIT",
        "$screen_name": "Index",
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "1.0.0",
        "$data_ingestion_source": [
            "HarmonyOS"
        ],
        "$os": "HarmonyOS",
        "$is_first_day": true,
        "$is_first_time": false
    },
    "type": "track",
    "event": "$AppClick",
    "time": 1712825022595,
    "_track_id": 659542613
}
CODE

2.4. 解绑业务 ID

2.4.1. 调用时机

解绑接口可将指定的业务 ID 下的值从对应的用户属性中移除。一般可在用户已有业务 ID 值不再使用,且需要更换时使用。比如更换绑定的手机号或邮箱账号。

需要注意的是此接口为高阶能力,且 对于性能影响较大 ,强烈建议您在使用前认真细阅使用准备章节中的内容。

2.4.2. 使用准备

  • 使用该接口前,请确保您对于神策的接口与用户关联概念有深入的了解。
  • 该接口能力,仅在动态可变关联策略下可用。您可进入神策系统,数据接入 → 用户表 → 配置用户关联 页面查看您当前正在使用的用户关联策略。
  • 该接口 对于性能有着非常大的影响,且 高度依赖解绑事件的上报时序,故在一些极端情况下,会发生数据不及预期的情况,故在使用该接口前建议同神策工作人员进行详细评估。

2.4.3. 接口说明

unbind(name: string, value: string)
CODE

参数名称

类型

是否必须

说明

keyString需要解绑的业务 ID 的 key,比如之前绑定邮箱的 key 是 “identify_email”,现在需要解绑,需输入 “identify_email”
valueString需要解绑的业务 ID 的 value

使用示例:

sensors.unbind("phone", '12345');
CODE

调用 解绑业务 ID(unbind) 接口后,神策 SDK 会触发神策预置的 “$UnbindID” 事件,事件中将记录 解绑业务 ID 接口中所传入的业务 ID 相关信息。同时神策 SDK 会将本地缓存中对应的业务 ID 信息删除,后续触发的事件数据中将不再带有相应的业务 ID 信息。

例如,调用 解绑业务 ID(unbind) 前,用户触发了一个按钮点击事件($AppClick)时,事件示例数据如下:

{
    "identities": {
        "$identity_anonymous_uuid": "your_customized_anonymous_id",   
        "$identity_harmony_uuid": "204ccdb8-7fc3-4aa0-8012-72fac26518d0",  // SDK 默认采集的匿名 ID,默认为 UUID
        "identity_customized_business_id": "your_customized_binding_business_value"  // 调用 bind(绑定业务 ID)后,该 ID 会缓存在本地
    },
    "anonymous_id": "your_customized_anonymous_id",   // 匿名 ID  
    "distinct_id": "your_customized_anonymous_id",    // 神策用户标识 distinct_id,在匿名状态下是匿名 ID 
    "lib": {
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "1.0.0",
        "$app_version": "0.0.3"
    },
    "properties": {
        "$timezone_offset": -480,
        "$screen_height": 2772,
        "$screen_width": 1344,
        "$app_id": "com.sensorsdata.sensorsdatasdk",
        "$app_name": "神策分析 SDK",
        "$app_version": "0.0.3",
        "$manufacturer": "HUAWEI",
        "$brand": "HUAWEI",
        "$model": "NOH-AN00",
        "$os_version": "2.1.7.1",
        "$network_type": "WiFi",
        "$screen_orientation": "PORTRAIT",
        "$screen_name": "Index",
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "1.0.0",
        "$data_ingestion_source": [
            "HarmonyOS"
        ],
        "$os": "HarmonyOS",
        "$is_first_day": true,
        "$is_first_time": false
    },
    "type": "track",
    "event": "$AppClick",
    "time": 1712825022595,
    "_track_id": 659542613
}
CODE

此时调用 解绑业务 ID(unbind) 接口后,会触发神策预置的 “$UnbindID” 事件,事件中将带有 解绑业务 ID 接口中所传入的业务 ID 相关信息,神策系统接档该预置事件后,将按照事件信息,把对应业务 ID 值从相关用户的用户图谱中移除。事件数据示例如下:

{
    "identities": {
	  	"identity_customized_business_id": "your_customized_binding_business_value"  // 调用 bind(绑定业务 ID)后,该 ID 会缓存在本地
    },
    "anonymous_id": "your_customized_anonymous_id",   // 匿名 ID  
    "distinct_id": "your_customized_anonymous_id",    // 神策用户标识 distinct_id,在匿名状态下是匿名 ID 
    "lib": {
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "1.0.0",
        "$app_version": "0.0.3"
    },
    "properties": {
        "$timezone_offset": -480,
        "$screen_height": 2772,
        "$screen_width": 1344,
        "$app_id": "com.sensorsdata.sensorsdatasdk",
        "$app_name": "神策分析 SDK",
        "$app_version": "0.0.3",
        "$manufacturer": "HUAWEI",
        "$brand": "HUAWEI",
        "$model": "NOH-AN00",
        "$os_version": "2.1.7.1",
        "$network_type": "WiFi",
        "$screen_orientation": "PORTRAIT",
        "$screen_name": "Index",
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "1.0.0",
        "$data_ingestion_source": [
            "HarmonyOS"
        ],
        "$os": "HarmonyOS",
        "$is_first_day": true,
        "$is_first_time": false
    },
    "type": "track_id_unbind",
    "event": "$UnbindID", 
    "time": 1712825022595,
    "_track_id": 659542613
}
CODE

如前文所述,神策 SDK 会在 解绑业务 ID(unbind) 接口被调用后,会将本地缓存中对应的业务 ID 信息删除。从而后续用户在此设备上再触发的所有事件将不再带有调用 unbind(解绑业务 ID) 时传入的业务 ID 信息,

例如,紧接着上文调用完 解绑业务 ID(unbind) 接口后,若此时用户在当前设备触发了一个按钮点击事件($AppClick)时,则事件的示例数据如下:

{
    "identities": {
        "$identity_anonymous_id": "your_customized_anonymous_id",   
        "$identity_harmony_uuid": "204ccdb8-7fc3-4aa0-8012-72fac26518d0"  // SDK 默认采集的匿名 ID,默认为 UUID
    },
    "anonymous_id": "your_customized_anonymous_id",   // 匿名 ID  
    "distinct_id": "your_customized_anonymous_id",    // 神策用户标识 distinct_id,在匿名状态下是匿名 ID 
    "lib": {
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "0.0.5",
        "$app_version": "0.0.3"
    },
    "properties": {
        "$timezone_offset": -480,
        "$screen_height": 2772,
        "$screen_width": 1344,
        "$app_id": "com.sensorsdata.sensorsdatasdk",
        "$app_name": "神策分析 SDK",
        "$app_version": "0.0.3",
        "$manufacturer": "HUAWEI",
        "$brand": "HUAWEI",
        "$model": "NOH-AN00",
        "$os_version": "2.1.7.1",
        "$network_type": "WiFi",
        "$screen_orientation": "PORTRAIT",
        "$screen_name": "Index",
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "1.0.0",
        "$data_ingestion_source": [
            "HarmonyOS"
        ],
        "$os": "HarmonyOS",
        "$is_first_day": true,
        "$is_first_time": false
    },
    "type": "track",
    "event": "$AppClick",
    "time": 1712825022595,
    "_track_id": 659542613
}
CODE

2.5. 用户登出

2.5.1. 调用时机

此接口为高阶接口,绝大多数情况下,您无需调用此接口。

如果同一台设备上,先后会登录多个账号,且希望账号 A 退出登录后的所有行为信息都归属于后面登录的账号 B。那么基于神策 SDK 会持久化记录用户业务 ID 的设计。此时您可在账号 A 退出登录时可先调用 用户登出(logout) 接口,然后再调用 重新生成匿名 ID 为匿名 ID 赋予新的值,随后在账号 B 登录时主动调用 用户登录 接口来实现。

2.5.2. 使用准备

  • 此接口为高阶接口,需要配合多个接口,并按照特定的顺序调用,才可产生正确效果。因此建议您在使用前,对于神策的接口与用户关联概念有深入的了解,并对于你的业务场景有深入的了解后再进行使用。

2.5.3. 接口说明

logout()
CODE

使用示例:

sensors.logout();
CODE

调用 用户登出(logout) 接口后,神策 SDK 会将缓存在当前设备中的 “login_id” 、 “$identity_login_id” 及绑定的其他业务 ID 信息删除,且不会触发任何神策系统的预置事件。直到再次调用 用户登录(login) 绑定业务 ID(bind) 接口前,用户在当前设备上所触发的事件,在上报时将不再带有 “login_id”、“$identity_login_id” 及其他绑定的业务 ID 信息。

例如,一个登录后的用户触发了一个按钮点击事件($AppClick)时,事件示例数据如下:

{
    "identities": {
        "$identity_anonymous_id": "your_customized_anonymous_id",   
	  	"$identity_login_id": "your_customer_id",
	   	"identity_customized_business_id": "your_customized_binding_business_value",  // 调用 bind(绑定业务 ID)后,该 ID 会缓存在本地 
        "$identity_harmony_uuid": "204ccdb8-7fc3-4aa0-8012-72fac26518d0" // SDK 默认采集的匿名 ID,默认为 UUID
     },
    "anonymous_id": "your_customized_anonymous_id",   // 匿名 ID
  	"login_id":	"your_customer_id", 				  // 登录 ID
    "distinct_id": "your_customized_anonymous_id",    // 神策用户标识 distinct_id,在登录状态下是匿名 ID
    "lib": {
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "0.0.5",
        "$app_version": "0.0.3"
    },
    "properties": {
        "$timezone_offset": -480,
        "$screen_height": 2772,
        "$screen_width": 1344,
        "$app_id": "com.sensorsdata.sensorsdatasdk",
        "$app_name": "神策分析 SDK",
        "$app_version": "0.0.3",
        "$manufacturer": "HUAWEI",
        "$brand": "HUAWEI",
        "$model": "NOH-AN00",
        "$os_version": "2.1.7.1",
        "$network_type": "WiFi",
        "$screen_orientation": "PORTRAIT",
        "$screen_name": "Index",
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "1.0.0",
        "$data_ingestion_source": [
            "HarmonyOS"
        ],
        "$os": "HarmonyOS",
        "$is_first_day": true,
        "$is_first_time": false
    },
    "type": "track",
    "event": "$AppClick",
    "time": 1712825022595,
    "_track_id": 659542613
}
CODE

在调用 用户登出(logout) 接口,神策 SDK 会将缓存在本地的 “login_id” 、 “$identity_login_id” 、"identity_customized_business_id" 信息清除。

若此时,用户在当前设备上有进行了浏览,触发了一个按钮点击事件($AppClick)时,则事件数据示例如下:

{
    "identities": {
        "$identity_anonymous_id": "your_customized_anonymous_id",   
        "$identity_harmony_uuid": "204ccdb8-7fc3-4aa0-8012-72fac26518d0" // SDK 默认采集的匿名 ID,默认为 UUID
    },
    "anonymous_id": "your_customized_anonymous_id",   // 匿名 ID
    "distinct_id": "your_customized_anonymous_id",    // 神策用户标识 distinct_id,在登录状态下是匿名 ID
    "lib": {
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "0.0.5",
        "$app_version": "0.0.3"
    },
    "properties": {
        "$timezone_offset": -480,
        "$screen_height": 2772,
        "$screen_width": 1344,
        "$app_id": "com.sensorsdata.sensorsdatasdk",
        "$app_name": "神策分析 SDK",
        "$app_version": "0.0.3",
        "$manufacturer": "HUAWEI",
        "$brand": "HUAWEI",
        "$model": "NOH-AN00",
        "$os_version": "2.1.7.1",
        "$network_type": "WiFi",
        "$screen_orientation": "PORTRAIT",
        "$screen_name": "Index",
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "1.0.0",
        "$data_ingestion_source": [
            "HarmonyOS"
        ],
        "$os": "HarmonyOS",
        "$is_first_day": true,
        "$is_first_time": false
    },
    "type": "track",
    "event": "$AppClick",
    "time": 1712825022595,
    "_track_id": 659542613
}
CODE

2.6. 重新设置匿名 ID

2.6.1. 调用时机

此接口为高阶接口,绝大多数情况下,您无需调用此接口。

此接口一般配合 退出登录 接口使用,旨在当设备上有多个不同用户登录时,实现用户 A 退出登录后所触发的事件都归属于后面登录的账号 B。

2.6.2. 使用准备

  • 此接口并非常用接口,使用前请确保对接口的功能已有深入的了解。
  • Harmony SDK 版本号 >= v0.0.5。
  • 当前用户需要在匿名(登出)状态下,即未调用 用户登录 接口前,或调用 用户登出 接口后。如果当前用户在登录状态下,调用此接口没有任何作用。

2.6.3. 接口说明

resetAnonymousIdentity(identity?: string)
CODE
参数名称类型是否必须说明
identityNSString

匿名用户 ID,可以不传,若传值,需为非空字符串,且长度 <= 8192,另外,需要保证唯一性,不然会影响用户关联。

若不传参数,SDK 内部会生成一个 uuid(util.generateRandomUUID)的值来作为新的匿名 ID

使用示例:

sensors.resetAnonymousIdentity("your_new_anonymous_id")
CODE

在用户匿名状态下调用此接口后,神策 SDK 会将 “anonymous_id”、“distinct_id”、“$identity_anonymous_id”、“$identity_harmony_uuid” 修改为接口调用时传入的值(如果不传,神策 SDK 内部会自动生成一个 uuid 的值来设置)。

例如,我们原先的匿名 ID 已经修改为 “your_customized_anonymous_id”,调用 resetAnonymousIdentity(重新设置匿名 ID) 接口之前的事件数据如下:

{
    "anonymous_id": "your_customized_anonymous_id",
    "distinct_id": "your_customized_anonymous_id",
    "event": "SampleEvent",
    "time": 1710407424987,
    "type": "track",
    "identities": {
        "$identity_anonymous_id": "your_customized_anonymous_id",    //修改后的匿名 ID
        "$identity_harmony_uuid": "204ccdb8-7fc3-4aa0-8012-72fac26518d0"     //SDK 默认采集
    },
    "lib": {
        "$lib_version": "0.0.5",
        "$lib": "HarmonyOS",
        "$app_version": "1.0.0",
        "$lib_method": "code"
    },
    "properties": {
        "$os": "HarmonyOS",
        "$app_version": "1.0.0",
        "$lib_method": "code",
        "$lib_version": "0.0.5",
        "$os_version": "2.1.7.1",
        "$lib": "HarmonyOS",
        "$manufacturer": "HUAWEI"
    }
}
CODE

此时,调用 resetAnonymousIdentity(重新设置匿名 ID) 接口,并在接口中传入所需设置的新的匿名 ID 的值:“your_new_anonymous_id”, 则此时触发新的事件(SampleEvent)时,事件数据示例如下:

{
    "anonymous_id": "your_new_anonymous_id",
    "distinct_id": "your_new_anonymous_id",
    "event": "SampleEvent",
    "time": 1710407424987,
    "type": "track",
    "identities": {
        "$identity_anonymous_id": "your_new_anonymous_id",    //修改后的匿名 ID
        "$identity_harmony_uuid": "your_new_anonymous_id"     //SDK 默认采集
    },
    "lib": {
        "$lib_version": "0.0.5",
        "$lib": "HarmonyOS",
        "$app_version": "1.0.0",
        "$lib_method": "code"
    },
    "properties": {
        "$os": "HarmonyOS",
        "$app_version": "1.0.0",
        "$lib_method": "code",
        "$lib_version": "0.0.5",
        "$os_version": "2.1.7.1",
        "$lib": "HarmonyOS",
        "$manufacturer": "HUAWEI"
    }
}
CODE