> ## 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.

# Amplitude

> 将 OneSignal 与 Amplitude 集成，同步行为群体、跟踪消息事件，并跨推送、电子邮件、短信和应用内渠道定向用户。

将 OneSignal 与 [Amplitude](https://amplitude.com) 集成，实现跨推送、应用内、电子邮件和短信的实时行为定向。此应用级集成支持三种数据流：

* **消息事件 → Amplitude**：跟踪所有渠道的交付、点击、失败等。
* **自定义事件 → OneSignal**：将 Amplitude 事件发送到 OneSignal 以触发旅程或细分。
* **群体 → OneSignal**：将基于行为的 Amplitude 群体同步为 OneSignal 中的定向筛选器。

***

## 要求

* [Amplitude 账户](https://amplitude.com/pricing)
* [OneSignal 付费套餐](https://onesignal.com/pricing)
* 已设置 [用户](./users) 和外部 ID 的 OneSignal 应用。

<Warning>
  此集成不会创建用户。它通过匹配标识符将 Amplitude 中的用户映射到 OneSignal 中的现有用户。
</Warning>

***

## 设置

### 将 Amplitude 添加到 OneSignal（出站）

将 OneSignal 消息事件发送到您的 Amplitude 项目中。

1. 在 OneSignal 中，导航到**数据 > 集成 > 目录**并选择 **Amplitude**。
2. 点击**设置**，然后打开**出站**选项卡。
3. 输入您的 Amplitude API 令牌，选择要发送的消息事件，然后点击**保存**。

#### 在 Amplitude 中

1. 找到您项目的 API 密钥，然后复制粘贴到 OneSignal 中。
2. 如果使用 Amplitude 的欧盟服务器，请勾选**仅向 Amplitude 的欧盟居留端点发送事件**。您可以通过 Amplitude URL 验证这一点。如果您看到 `eu.amplitude.com`，则您正在使用 Amplitude 的欧盟服务器。

### 将 OneSignal 添加到 Amplitude（入站）

在您的 Amplitude 目标中，搜索 **OneSignal**。

<Frame caption="在 Amplitude 中添加 OneSignal 目标">
  <img src="https://mintcdn.com/onesignal/TbJ7SH8gAntayRJq/images/integrations/amplitude-destination.png?fit=max&auto=format&n=TbJ7SH8gAntayRJq&q=85&s=fe7b7967e5e219556a6356915b0238fa" alt="已选择 OneSignal 的 Amplitude 目标目录" width="2288" height="1168" data-path="images/integrations/amplitude-destination.png" />
</Frame>

Amplitude 在目录中提供两种 OneSignal 目标类型：

* **群体**：从 Amplitude 向 OneSignal 同步群体。
* **事件用户属性**：从 Amplitude 向 OneSignal 发送自定义事件。

<Note>
  如果您计划同时使用群体同步和自定义事件，请添加两个 OneSignal 目标。每个目标在 Amplitude 中单独配置，因此您需要为每个目标输入 OneSignal 凭据。
</Note>

### 用户 ID 映射

OneSignal 中的\*\*[外部 ID](./users)\*\* 必须与您选择的 Amplitude 用户属性（例如 `user_id`）匹配。验证此属性在两个系统中均已填充——群体同步和事件跟踪依赖于精确匹配。

#### 附加属性

您可以包含额外属性，这些属性将附加到 OneSignal 中的[自定义事件](./custom-events)。这对于条件事件处理非常有用。

<Check>
  完成后点击**保存**。现在您应该能够将群体和自定义事件从 Amplitude 导出到 OneSignal，并从 OneSignal 收集消息事件到 Amplitude。
</Check>

***

## 测试自定义事件

1. 在 Amplitude > OneSignal 事件目标中，点击"测试连接"按钮。

<Frame caption="Amplitude > OneSignal 事件目标">
  <img src="https://mintcdn.com/onesignal/yt4lRKoquAlWvRvF/images/integrations/amplitude-test-connection.png?fit=max&auto=format&n=yt4lRKoquAlWvRvF&q=85&s=8202b1ee8513456d78777425db4a7753" alt="已高亮显示测试连接按钮的 Amplitude 事件目标页面" width="1970" height="1160" data-path="images/integrations/amplitude-test-connection.png" />
</Frame>

2. 确保负载中的 `"user_id"` 设置为 OneSignal 应用中现有用户的外部 ID。
3. 点击**发送测试事件**按钮。
4. 响应框应保持为空，您应该看到 `"OneSignal 已成功接收测试事件。"`

<Frame caption="响应示例">
  <img src="https://mintcdn.com/onesignal/yt4lRKoquAlWvRvF/images/integrations/amplitude-test-connection-response.png?fit=max&auto=format&n=yt4lRKoquAlWvRvF&q=85&s=14b5824d639a748252a36315bc491383" alt="显示确认消息的成功测试事件响应" width="2438" height="1500" data-path="images/integrations/amplitude-test-connection-response.png" />
</Frame>

5. 在 OneSignal 中，导航到**数据 > 自定义事件**，验证测试事件出现在列表中。

<Frame caption="OneSignal 中的自定义事件">
  <img src="https://mintcdn.com/onesignal/yt4lRKoquAlWvRvF/images/integrations/onesignal-custom-event.png?fit=max&auto=format&n=yt4lRKoquAlWvRvF&q=85&s=18c287884737e192fde2da0e28d65676" alt="显示来自 Amplitude 的测试事件的 OneSignal 自定义事件列表" width="2736" height="1032" data-path="images/integrations/onesignal-custom-event.png" />
</Frame>

<Warning>
  如果测试失败或事件未出现在 OneSignal 中，请验证您的 OneSignal 应用 ID 和 REST API 密钥已在 Amplitude 中正确输入，您的应用已配置[自定义事件](./custom-events)，且 `"user_id"` 与您的 OneSignal 应用中现有用户的外部 ID 匹配。
</Warning>

## 将 Amplitude 群体导出到 OneSignal

使用上面配置的匹配外部 ID 将 Amplitude 群体同步到 OneSignal。导出**不会创建用户**——每个用户必须已在 OneSignal 中存在。

1. 在 Amplitude 中，创建一个群体。请参阅 [Amplitude 的群体文档](https://amplitude.com/docs/analytics/behavioral-cohorts)。
2. 点击**同步**并选择 **OneSignal** 作为目标。
3. 选择同步频率。

<Frame caption="为 Amplitude 群体与 OneSignal 设置同步节奏">
  <img src="https://mintcdn.com/onesignal/yt4lRKoquAlWvRvF/images/integrations/amplitude-sync-cadence.png?fit=max&auto=format&n=yt4lRKoquAlWvRvF&q=85&s=9ba4b69273f73ccdd1f095c2a3ede63c" alt="显示 OneSignal 目标频率选项的 Amplitude 群体同步设置" width="602" height="499" data-path="images/integrations/amplitude-sync-cadence.png" />
</Frame>

### OneSignal 细分创建

同步的群体在 OneSignal 中显示为 **Amplitude 细分筛选器**。如果满足以下条件，OneSignal 将自动为该群体创建细分：

* Amplitude 群体中的用户在 OneSignal 中也存在并具有匹配的外部 ID。
* 您未超过 OneSignal 中的细分限制。

<Frame caption="从 Amplitude 群体创建细分">
  <img src="https://mintcdn.com/onesignal/jFWn5xzleD8du3j6/images/docs/526a986-Screenshot_2023-09-22_at_7.01.09_PM.png?fit=max&auto=format&n=jFWn5xzleD8du3j6&q=85&s=e5de1d6896a542a980b9840a05200586" alt="使用 Amplitude 群体筛选器的 OneSignal 细分构建器" width="1622" height="878" data-path="images/docs/526a986-Screenshot_2023-09-22_at_7.01.09_PM.png" />
</Frame>

***

## 在 Amplitude 中跟踪消息事件

OneSignal 实时向 Amplitude 发送以下消息事件。在**数据 > 集成 > Amplitude > 出站**中选择要发送的事件。

| Message Event Kind (OneSignal) | Message Event Name (Amplitude)                                | Event Description              |
| ------------------------------ | ------------------------------------------------------------- | ------------------------------ |
| Push Sent                      | \[OneSignal] Push Sent                                        | 推送通知成功发送。                      |
| Push Received                  | \[OneSignal] Push confirmed receipt                           | 推送通知成功接收                       |
| Push Clicked                   | \[OneSignal] Push Clicked                                     | 推送通知在设备上被触摸                    |
| Push Failed                    | \[OneSignal] Push Failed                                      | 推送发送失败。请检查 OneSignal 中的失败消息报告。 |
| Push Unsubscribed              | \[OneSignal] Push Unsubscribed                                | [订阅](./subscriptions) 取消了推送订阅。 |
| In-App Impression              | \[OneSignal] IAM Displayed                                    | 应用内消息成功在设备上显示                  |
| In-App Clicked                 | \[OneSignal] IAM Clicked                                      | 应用内消息在设备上被点击                   |
| In-App Page Displayed          | \[OneSignal] IAM Page Displayed                               | 应用内消息页面已显示                     |
| Email Sent                     | \[Onesignal] Email Delivered                                  | 电子邮件成功发送                       |
| Email Received                 | \[OneSignal] Email confirmed receipt                          | 收件人收到电子邮件                      |
| Email Opened                   | \[OneSignal] Email Opened                                     | 收件人打开电子邮件                      |
| Email Link Clicked             | \[OneSignal] Email Clicked                                    | 电子邮件链接被点击                      |
| Email Unsubscribed             | \[OneSignal] Email Unsubscribed                               | 收件人取消订阅电子邮件                    |
| Email Reported As Spam         | \[OneSignal] Email Reported As SPAM                           | 收件人将电子邮件报告为垃圾邮件                |
| Email Bounced                  | \[OneSignal] Email Hard Bounced                               | 由于永久错误，电子邮件退回给发件人              |
| Email Failed                   | \[OneSignal] Email Failed delivery                            | 无法将电子邮件送达到收件人的收件箱              |
| Email Suppressed               | \[OneSignal] Email Not delivering to suppressed email address | 电子邮件未送达，因为收件人已屏蔽发送该邮件的邮箱地址     |
| SMS Sent                       | \[OneSignal] SMS Sent                                         | 短信发送给收件人                       |
| SMS Failed                     | \[OneSignal] SMS Failed delivery                              | 短信发送失败                         |
| SMS Delivered                  | \[OneSignal] SMS Confirmed deliveery                          | 短信成功送达                         |
| SMS Undelivered                | \[OneSignal] SMS Undelivered                                  | 无法发送短信。                        |

### 事件属性

从 OneSignal 发送到 Amplitude 的每个事件都包含以下属性：

| PROPERTY NAME        | DESCRIPTION                                             |
| -------------------- | ------------------------------------------------------- |
| **Distinct ID**      | The external\_id associated with the message            |
| **Message ID**       | 单个消息的标识符                                                |
| **Message Name**     | 消息名称                                                    |
| **Message Title**    | 消息标题                                                    |
| **Message Contents** | 消息内容                                                    |
| **message\_type**    | 发送的消息类型：推送、应用内、电子邮件、短信                                  |
| **template\_id**     | 使用的消息模板（API 和旅程消息）                                      |
| **subscription\_id** | OneSignal 设置的设备/电子邮件/短信标识符                              |
| **device\_type**     | 接收消息的设备类型                                               |
| **language**         | 设备的两字符语言代码                                              |
| **source**           | `onesignal` (is indicated as the source for all events) |

<Warning>
  Amplitude 和 OneSignal 之间的交付计数可能存在差异。请参阅[为什么交付数据不匹配？](#why-doesnt-delivery-data-match)了解详情。
</Warning>

***

## 常见问题

### 为什么我的群体和细分数量不匹配？

1. **缺失或不匹配的外部 ID**
   只有具有匹配的 OneSignal 外部 ID 和 Amplitude 用户 ID 的用户才会被包括。此集成不会创建用户或订阅。

2. **未订阅用户**
   OneSignal 细分只显示已订阅[订阅](./subscriptions)的数量。未订阅的订阅可用于旅程或应用内消息。

例如，如果 Amplitude 群体有 10 个用户，但 OneSignal 细分显示 8 个订阅，缺失的 2 个用户可能：

* 在 OneSignal 中不存在或具有错误的外部 ID。
* 具有未订阅的订阅。

要验证，请检查 OneSignal 中的**受众 > 用户**选项卡，查看用户是否存在并具有活跃的订阅。

### 未订阅的用户会从 Amplitude 同步吗？

是的，但目前它们被排除在 OneSignal 细分数量之外。如果他们具有其他[订阅](./subscriptions)或其订阅类型支持，您仍然可以通过旅程或应用内消息向他们发送消息。

### 为什么交付数据不匹配？

单个用户可能具有多个[订阅](./subscriptions)（推送设备、电子邮件地址、电话号码）。每个订阅都会生成自己的交付事件。例如：

* 1 个用户 = 2 个 Android + 1 个 iOS + 2 个 Web = 5 个推送订阅
* 1 条推送消息 = 最多 5 个发送/接收/点击事件

使用事件属性中的 `subscription_id` 来追踪确切的来源。

要排除缺失事件的故障：

* 确保在识别用户时调用 `OneSignal.login` 来设置外部 ID。
* 验证 `OneSignal.logout` 未删除外部 ID。
* 检查可能更改外部 ID 的 API 请求或 CSV 上传。

### 我们如何发送用户/订阅事件？

用户和订阅级别的事件（例如，授予权限、用户登录/注销）不会自动发送。

OneSignal SDK 具有事件监听器，可用于追踪这些事件以便您发送到 Amplitude：

* 用户状态观察者：[Mobile SDK](./mobile-sdk-reference#addobserver-user-state)、[Web SDK](./web-sdk-reference#addeventlistener-user-state)
* 权限观察者：[Mobile SDK](./mobile-sdk-reference#addpermissionobserver-push)、[Web SDK](./web-sdk-reference#permissionchange)

### 为什么 OneSignal 订阅 ID 作为 device\_id 添加到 Amplitude？

Amplitude 期望使用 `device_id` 进行去重。OneSignal 使用 `subscription_id` 来实现此功能，它会自动映射到 `device_id`。

有关更多信息，请参阅 [Amplitude 的文档](https://amplitude.com/docs/apis/analytics/http-v2#event-deduplication)。

***

## 相关页面

<Columns cols={2}>
  <Card title="分析概览" icon="chart-line" href="./analytics-overview">
    OneSignal 分析、交付指标和事件跟踪概览。
  </Card>

  <Card title="自定义事件" icon="bolt" href="./custom-events">
    跟踪用户操作以触发旅程或支持分析。
  </Card>
</Columns>

***

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>