1. 概览

在简易用户关联中，神策会通过匿名 ID 和登录 ID 来标识访问 App 的用户。并根据上报事件中携带的信息，将用户的匿名 ID 与登录 ID 进行关联，从而将用户登录前后的行为数据串联起来。

匿名 ID（anonymous_id）默认由神策 SDK 通过自动采集或生成；登录 ID （login_id）需要您通过主动调用登录接口进行记录；
匿名 ID 和登录 ID 会被 SDK 持久化存储，并随着每次事件一并上报。

例如，一个用户首次打开 App，此时触发了一个启动事件（$AppStart），此事件除了包含事件相关的属性信息外，还会携带一个匿名 ID（默认为 UUID ）：

{
	"identities": {
		"$identity_harmony_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": "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": "$AppStart",
	"time": 1712825022595,
	"_track_id": 659542613
}

CODE

2. 接口介绍

2.1. 更改匿名 ID

2.1.1. 调用时机

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

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

2.1.2. 使用准备

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

2.1.3. 接口说明

identify(anonymous_id: string)

CODE

参数名称	类型	是否必须	说明
anonymous_id	String	是	匿名用户 ID，非空字符串，需要保证唯一性，不然会影响用户关联

使用示例：

sensors.identify('your_customized_anonymous_id');

CODE

调用此接口后后续的事件数据中的匿名 ID 都会更改，事件示例如下：

{
    "identities": {
        "$identity_harmony_uuid": "your_customized_anonymous_id"   // 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": "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": "$AppStart",
    "time": 1712825022595,
    "_track_id": 659542613
}

CODE

2.2. 用户登录

2.2.1. 调用时机

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

2.2.2. 使用准备

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

2.2.3. 接口说明

login(id: string, properties?: EventProps): Promise<void>

CODE

参数名称	类型	是否必须	说明
loginId	String	是	用户登录 ID，非空字符串，

使用示例：

sensors.login('your_customer_id');

CODE

调用此接口后，SDK 会自动触发神策预置的 $SignUp 事件（），事件上报信息示例如下：

{
    "identities": {
        "$identity_harmony_uuid": "your_customized_anonymous_id"   // SDK 默认采集的匿名 ID，默认为 UUID
		"$identity_login_id": "your_customer_id"
    },
    "anonymous_id": "your_customized_anonymous_id",   // 匿名 ID 
    "distinct_id": "your_customer_id",    // 神策用户标识 distinct_id，在登录状态下是登录 ID
	"login_id": "your_customer_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_signup",
    "event": "$SignUp",
    "time": 1712825022595,
    "_track_id": 659542613
}

CODE

2.3. 用户登出

2.3.1. 调用时机

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

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

2.3.2. 使用准备

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

2.3.3. 接口说明

void logout()

CODE

使用示例：

sensors.logout()

CODE

调用此接口后，SDK 会将持久化存储中 login_id 信息删除，且不会触发任何神策系统的预置事件。后续该设备上，用户产生的事件，在上报时将不再带有 login_id 信息。

此时，事件数据中的 distinct_id 的值将和 anonymous_id 相同。

例如，用户登录后触发了一个控件点击事件 “$AppClick”，此时的事件示例如下：

{
    "identities": {
        "$identity_harmony_uuid": "your_customized_anonymous_id"   // SDK 默认采集的匿名 ID，默认为 UUID
		"$identity_login_id": "your_customer_id"
    },
    "anonymous_id": "your_customized_anonymous_id",   // 匿名 ID 
    "distinct_id": "your_customer_id",    // 神策用户标识 distinct_id，在登录状态下是登录 ID 
	"login_id": "your_customer_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

调用 用户登出(logout) 接口后，用户在当前设备上进行了控件点击，触发了 “$AppClick” 事件，此时事件示例如下：

{
    "identities": {
        "$identity_harmony_uuid": "your_customized_anonymous_id"   // 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": "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