> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 别名

> 了解如何在 OneSignal 中使用自定义别名，通过您自己的唯一标识符跨不同平台和设备识别和跟踪用户。别名有助于统一来自多个来源的用户数据，对于集成、用户数据管理和事务性消息传递至关重要。

自定义别名允许您为 OneSignal 中的用户分配自定义键值标识符，从而使用您自己的内部 ID 实现跨平台用户跟踪和识别。

<Warning>
  **重要**：您必须在使用自定义别名**之前**设置一个 [External ID](./users)。

  OneSignal 使用唯一的 `onesignal_id` 来识别用户。此 ID 只有在具有相同 `external_id` 的情况下才能在 [订阅](./subscriptions) 之间保持一致。

  自定义别名**不会**将订阅链接在一起——它们依赖于 `external_id` 才能正常工作。没有它，别名将无法跨设备或平台与同一用户关联。
</Warning>

***

## 什么是自定义别名？

自定义别名是一个 `键 : 值` 对，其中：

* `alias_label`（键）是所有用户的一致静态标识符（例如，`facebook_id`、`firebase_id`、`crm_user_id`）。
* `alias_id`（值）是该标签的特定用户 ID（例如，`facebook_id: 3453443`、`firebase_id: test3555`）。

这允许您将 OneSignal 用户记录链接到来自其他平台或数据库的标识符。

***

## 为什么使用别名？

1. 跨多个平台和数据库识别用户。
2. 使用 [Create Message REST API](/reference/create-message) 发送有针对性的事务性消息。
3. 通过用户 REST API 获取、更新或删除用户。

***

## 如何设置别名

您可以使用 OneSignal SDK 或通过 REST API 设置别名。

### 使用 SDK

在您的应用中按照以下步骤操作：

1. 设置 External ID
   调用 `OneSignal.login(externalId)` 来关联用户记录。

2. 设置自定义别名
   使用 `OneSignal.User.addAlias(label, id)` 添加单个别名，或使用 `OneSignal.User.addAliases({ label1: id1, label2: id2 })` 设置多个别名。

3. 注销（可选）
   使用 `OneSignal.logout()` 移除该设备或会话的 external ID 和任何关联别名。

**Example**:

```javascript theme={null}
OneSignal.login("user_123");

OneSignal.User.addAliases({
  facebook_id: "3453443",
  firebase_id: "test3555"
});

// Later, when the user logs out
OneSignal.logout();
```

***

### 使用 REST API

要通过 API 设置自定义别名，请使用 [Create Alias](/reference/create-alias) 端点。此方法通常用于后端系统进行服务器端用户管理。

**Example Request**:

```json theme={null}
POST /aliases
{
  "subscription_id": "abc123",
  "aliases": {
    "facebook_id": "3453443",
    "crm_user_id": "XYZ789"
  }
}
```

***

## 最佳实践

* 在分配任何别名之前，始终设置 `external_id`。
* 使用稳定、描述性的标签（例如，`crm_user_id`、`legacy_user_id`）以避免团队间的混淆。
* 避免使用敏感信息（如电子邮件地址或电话号码）作为别名值。
* 在设备注销或用户切换事件时使用 `logout()` 清理别名。

***

<Check>
  自定义别名教程完成！
  下一步：

  * 如果您还没有，请查看我们的 [用户](./users) 和 [订阅](./subscriptions) 文档。
  * 探索我们的 [REST API](/reference/create-alias) 文档，了解通过 API 使用别名的更多详细信息。
  * 设置 [集成](./integrations) 以跨系统同步用户数据。
</Check>

***