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

# Mixpanel

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

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

* **消息事件 → Mixpanel**：跟踪所有渠道的传递、点击、失败等信息。
* **群组 → OneSignal**：将基于行为的 Mixpanel 群组同步为 OneSignal 中的定向过滤器。

<Warning>
  Mixpanel 目前不向 OneSignal 发送[自定义事件](./custom-events)。如果您需要将 Mixpanel 事件路由到 OneSignal，请使用第三方连接器，如 [Vendo](https://www.vendodata.com/use-cases/integrate-mixpanel-with-onesignal)。
</Warning>

***

## 要求

* [Mixpanel Account](https://mixpanel.com/)
* [OneSignal 付费计划](https://onesignal.com/pricing)
* 设置了外部 ID 的 OneSignal 应用。

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

***

## 设置

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

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

1. 在 OneSignal 中，导航到 **数据 > 集成 > Mixpanel** 并点击 **激活**。

<Frame caption="在 OneSignal 中启用 Mixpanel 集成">
  <img src="https://mintcdn.com/onesignal/Xl2NHJvxakrK4JbL/images/docs/f5dfbab5a6c41ae816e34401b7fa5a8624e15d43f90ad723c4c7b2166dbd66de-Screenshot_2025-03-18_at_8.15.13_AM.png?fit=max&auto=format&n=Xl2NHJvxakrK4JbL&q=85&s=4c5a9ba2e4e2a2c8b2e2b2b2376253f1" alt="OneSignal Integrations page with Mixpanel selected" width="1150" height="458" data-path="images/docs/f5dfbab5a6c41ae816e34401b7fa5a8624e15d43f90ad723c4c7b2166dbd66de-Screenshot_2025-03-18_at_8.15.13_AM.png" />
</Frame>

#### 在 Mixpanel 中

1. 找到您的 [Project Token](https://docs.mixpanel.com/docs/orgs-and-projects/managing-projects#find-your-project-tokens)，然后将其复制粘贴到 OneSignal 中。
2. 检查您的 [Data Residency](https://docs.mixpanel.com/docs/orgs-and-projects/managing-projects#project-details)。如果使用 Mixpanel 的欧盟服务器，请勾选 **仅将事件发送到 Mixpanel 的欧盟数据驻留服务器** 复选框。

#### 选择消息事件

选择您要发送到 Mixpanel 的 OneSignal 消息事件。完成后，点击**激活**。

<Frame caption="OneSignal 中的 Mixpanel 设置">
  <img src="https://mintcdn.com/onesignal/9_Q1FZLh6C0BFLq-/images/docs/bc980ae-Screenshot_2024-06-04_at_10.18.59_AM.png?fit=max&auto=format&n=9_Q1FZLh6C0BFLq-&q=85&s=b98514269a60a2144c1dc0334969e7d3" alt="OneSignal Mixpanel integration settings showing event selection" width="2216" height="1412" data-path="images/docs/bc980ae-Screenshot_2024-06-04_at_10.18.59_AM.png" />
</Frame>

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

在您的 Mixpanel **集成**中，添加 OneSignal。

<Frame caption="在 Mixpanel 中添加 OneSignal 集成">
  <img src="https://mintcdn.com/onesignal/KSCNwSpBCNSQ8xdF/images/docs/mixpanel-integration.png?fit=max&auto=format&n=KSCNwSpBCNSQ8xdF&q=85&s=b4e6bc1f405b2087b455b2942ce5aecd" alt="Mixpanel integrations catalog with OneSignal selected" width="2986" height="1300" data-path="images/docs/mixpanel-integration.png" />
</Frame>

将**连接器名称**设置为可识别的名称，如 `OneSignal - APP_NAME`，其中 `APP_NAME` 是 OneSignal 中应用的名称。

您需要在 OneSignal **设置 > [密钥和 ID](./keys-and-ids)** 中提供以下数据：

1. App ID
2. API Key

### 用户 ID 映射

<Warning>
  此步骤对于群组同步和事件跟踪正常工作至关重要。
</Warning>

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

<Frame caption="Mixpanel 用于设置 OneSignal 属性的仪表板">
  <img src="https://mintcdn.com/onesignal/56ctKxZSV4m5VEkn/images/docs/b5e818708efcc73ea8eb0cccb6542c205069b395978b8fa796af28d816b33356-Screenshot_2025-03-18_at_11.22.54_AM.png?fit=max&auto=format&n=56ctKxZSV4m5VEkn&q=85&s=c161191d039f187a20df7201d9ca71db" alt="Mixpanel OneSignal connector settings showing User ID property selection" width="864" height="900" data-path="images/docs/b5e818708efcc73ea8eb0cccb6542c205069b395978b8fa796af28d816b33356-Screenshot_2025-03-18_at_11.22.54_AM.png" />
</Frame>

验证您选择的**用户 ID 属性**在您的 Mixpanel 用户配置文件属性中可用。

<Frame caption="Mixpanel > 用户 > 用户资料属性">
  <img src="https://mintcdn.com/onesignal/YOTSrtBSoqdrJ37A/images/docs/4416681-small-Screenshot_2023-05-15_at_9.54.14_AM.png?fit=max&auto=format&n=YOTSrtBSoqdrJ37A&q=85&s=e89ad019a61077ae376fc92e1a1eb87a" alt="Mixpanel user profile properties list" width="521" height="1024" data-path="images/docs/4416681-small-Screenshot_2023-05-15_at_9.54.14_AM.png" />
</Frame>

Mixpanel 中用户配置文件属性的相同值必须与 OneSignal 中的外部 ID 匹配。

<Frame caption="OneSignal > Audience > Users > External ID">
  <img src="https://mintcdn.com/onesignal/Z6xkXGfmy814If53/images/docs/e6853b59781b29ccbd264f97925830986605ec5514d02b5435c27ec896804a89-Screenshot_2025-03-18_at_10.22.25_AM.png?fit=max&auto=format&n=Z6xkXGfmy814If53&q=85&s=9a0b4237233c0492901853d72a6b1b63" alt="OneSignal user profile showing External ID" width="2764" height="686" data-path="images/docs/e6853b59781b29ccbd264f97925830986605ec5514d02b5435c27ec896804a89-Screenshot_2025-03-18_at_10.22.25_AM.png" />
</Frame>

<Warning>
  如果您基于 Mixpanel `$distinct_id` 将用户匹配到 OneSignal，那么只有顶部值会匹配。

  在下面的示例中，只有 `890ea9b1-9024-4fb9-a92f-152ba67dd21a` 有效。它无法匹配 `109768518080488203109` 或 `$device:1880c06821f1b3-052354675cde95-1d525634-1fa400-1880c06821f1b3`。
</Warning>

<Frame caption="如果用于用户 ID 属性映射，设置 Distinct ID 时请谨慎">
  <img src="https://mintcdn.com/onesignal/Xl2NHJvxakrK4JbL/images/docs/e7b80eb-small-Screenshot_2023-05-15_at_10.07.10_AM.png?fit=max&auto=format&n=Xl2NHJvxakrK4JbL&q=85&s=ef1999c6f01a48063d98e7e2ea330052" alt="Mixpanel Distinct ID example showing multiple values" width="464" height="314" data-path="images/docs/e7b80eb-small-Screenshot_2023-05-15_at_10.07.10_AM.png" />
</Frame>

<Check>
  完成后点击**继续**。您现在应该能够将群组从 Mixpanel 导出到 OneSignal，并从 OneSignal 收集消息事件到 Mixpanel。
</Check>

***

## 将 Mixpanel 群组导出到 OneSignal

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

1. 在 Mixpanel 中，创建一个群组。
2. 点击 **选项 > 导出到... > *OneSignal 连接名称***。

<Frame caption="如何将 Mixpanel 群组导出到 OneSignal">
  <img src="https://mintcdn.com/onesignal/tNi1OgLc_p9hiq7_/images/docs/187698db55979af5f5c94d672ada1e0c8d7329d600a650e3115b77077ef99237-Screenshot_2025-03-18_at_12.04.16_PM.png?fit=max&auto=format&n=tNi1OgLc_p9hiq7_&q=85&s=fce16e4cde30d69f3b24a947cf71c937" alt="Mixpanel cohort export menu with OneSignal destination" width="2432" height="1008" data-path="images/docs/187698db55979af5f5c94d672ada1e0c8d7329d600a650e3115b77077ef99237-Screenshot_2025-03-18_at_12.04.16_PM.png" />
</Frame>

3. 选择同步频率并按 **开始同步**。

<Frame caption="Mixpanel 频率选项">
  <img src="https://mintcdn.com/onesignal/9_Q1FZLh6C0BFLq-/images/docs/c6b36cedac01d722acaa4240225ea6d10519458682f4c2844d681b8ee34b236e-Screenshot_2025-03-18_at_12.12.06_PM.png?fit=max&auto=format&n=9_Q1FZLh6C0BFLq-&q=85&s=5bb3a035bfb3bea7d78553e86ccb943b" alt="Mixpanel cohort sync frequency selection dialog" width="860" height="896" data-path="images/docs/c6b36cedac01d722acaa4240225ea6d10519458682f4c2844d681b8ee34b236e-Screenshot_2025-03-18_at_12.12.06_PM.png" />
</Frame>

### OneSignal 细分创建

同步的群组在 OneSignal 中显示为 **Mixpanel 细分过滤器**。如果满足以下条件，OneSignal 将自动为群组创建细分：

* Mixpanel 群组中的用户也在 OneSignal 中存在并具有匹配的外部 ID。
* 您不能超过 OneSignal 中的细分限制。

<Note>
  Mixpanel 要求至少有一个匹配用户才能在 OneSignal 中创建细分。细分创建后，即使群组后来没有用户，它仍会保留在 OneSignal 中。在这种情况下，细分显示为空，直到再次添加用户。
</Note>

<Frame caption="从 Mixpanel 群组创建细分">
  <img src="https://mintcdn.com/onesignal/jBdBk5XvQR5eKOks/images/docs/7b01785ad5a5f85377bdb20e664e5d5c38280cff56373d70726621569668907d-Screenshot_2025-03-18_at_12.38.47_PM.png?fit=max&auto=format&n=jBdBk5XvQR5eKOks&q=85&s=3ba94cf6588a4158a86e77c4a23c3e34" alt="OneSignal Segment builder using Mixpanel Cohort filter" width="1444" height="818" data-path="images/docs/7b01785ad5a5f85377bdb20e664e5d5c38280cff56373d70726621569668907d-Screenshot_2025-03-18_at_12.38.47_PM.png" />
</Frame>

***

## 在 Mixpanel 中追踪消息事件

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

要测试，请从 OneSignal 向自己发送消息，然后导航到 Mixpanel 中的用户配置文件页面。在活动源中，您应该看到事件填充。

<Frame caption="Mixpanel 活动源中的 OneSignal 消息事件">
  <img src="https://mintcdn.com/onesignal/9_Q1FZLh6C0BFLq-/images/docs/c344970fd85bda82f9b6bedf1700a9cbb91afd63afc9fe1e866c42e1b380770e-Screenshot_2025-03-18_at_1.59.23_PM.png?fit=max&auto=format&n=9_Q1FZLh6C0BFLq-&q=85&s=9ca542f553f6c08a15ca99d52d68be2b" alt="Mixpanel user activity feed showing OneSignal message events" width="2420" height="1654" data-path="images/docs/c344970fd85bda82f9b6bedf1700a9cbb91afd63afc9fe1e866c42e1b380770e-Screenshot_2025-03-18_at_1.59.23_PM.png" />
</Frame>

### 消息事件

| Message Event Kind (OneSignal) | Message Event Name (Mixpanel) | Event Description                   |
| ------------------------------ | ----------------------------- | ----------------------------------- |
| Push Sent                      | Message Sent                  | 推送通知成功发送                            |
| Push Received                  | Message Received              | 推送通知成功接收                            |
| Push Clicked                   | App Opened from Push          | 在设备上触摸推送通知                          |
| Push Failed                    | Push Failed                   | 推送发送失败。检查 OneSignal 中的失败消息报告        |
| Push Unsubscribed              | Push Unsubscribed             | [订阅](./subscriptions)取消订阅推送         |
|                                |                               |                                     |
| In-App Impression              | Message Sent                  | 应用内消息成功在设备上显示                       |
| In-App Clicked                 | Message Opened                | 在设备上点击应用内消息                         |
| In-App Page Displayed          | In-App Page Displayed         | 显示应用内消息页面                           |
|                                |                               |                                     |
| Email Sent                     | Message Sent                  | 电子邮件成功发送                            |
| Email Received                 | Message Received              | 收件人收到电子邮件                           |
| Email Opened                   | Message Opened                | 收件人打开电子邮件                           |
| Email Link Clicked             | App Opened from Push          | 点击电子邮件链接                            |
| Email Unsubscribed             | Email Unsubscribed            | 收件人取消订阅电子邮件                         |
| Email Reported As Spam         | Email Reported as Spam        | 收件人将电子邮件报告为垃圾邮件                     |
| Email Bounced                  | Email Bounced                 | 电子邮件因永久性错误返回发送方                     |
| Email Failed                   | Email Failed                  | 无法将电子邮件投递到收件人的收件箱                   |
| Email Suppressed               | Email Suppressed              | 电子邮件地址在您的抑制列表中。可能是退回或将您的电子邮件标记为垃圾邮件 |
|                                |                               |                                     |
| SMS Sent                       | Message Sent                  | 短信发送给收件人                            |
| SMS Failed                     | SMS Failed                    | 短信发送失败                              |
| SMS Delivered                  | Message Received              | 短信成功投递                              |
| SMS Undelivered                | SMS Undelivered               | 短信无法发送                              |

### 事件属性

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

| PROPERTY NAME        | DESCRIPTION                |
| -------------------- | -------------------------- |
| **Distinct ID**      | 与消息相关联的 external\_id       |
| **Message ID**       | 离散消息的标识符                   |
| **Message Name**     | 消息名称                       |
| **Message Title**    | 消息标题                       |
| **Message Contents** | 消息内容                       |
| **message\_type**    | 发送的消息类型，推送、应用内、电子邮件、短信     |
| **template\_id**     | 使用的消息模板（API 和旅程消息）         |
| **subscription\_id** | OneSignal 设置的设备/电子邮件/短信标识符 |
| **device\_type**     | 接收消息的设备类型                  |
| **language**         | 设备的两个字符语言代码                |
| **source**           | `onesignal`（被指示为所有事件的来源）   |

<Warning>
  Mixpanel 和 OneSignal 之间的传递计数可能不同。详情请参阅[为什么传递数据不匹配？](#why-doesnt-delivery-data-match)
</Warning>

***

## 自定义事件（第三方）

Mixpanel 集成不原生支持将自定义事件从 Mixpanel 发送到 OneSignal。与 [Amplitude](./amplitude) 不同，Mixpanel 到 OneSignal 没有内置的事件目标。

如果您需要将 Mixpanel 行为事件作为[自定义事件](./custom-events)路由到 OneSignal 以触发旅程或细分，可以使用第三方连接器，如 [Vendo](https://www.vendodata.com/use-cases/integrate-mixpanel-with-onesignal)。Vendo 将选定的 Mixpanel 事件作为自定义事件流式传输到 OneSignal，用于活动触发。

***

## 常见问题

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

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

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

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

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

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

### 未订阅用户是否从 Mixpanel 同步？

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

### 为什么传递数据不匹配？

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

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

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

要排除缺失事件：

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

### 我可以从 Mixpanel 向 OneSignal 发送自定义事件吗？

不能原生支持。Mixpanel 集成支持消息事件（OneSignal → Mixpanel）和群组同步（Mixpanel → OneSignal），但不包括内置的自定义事件目标。要将 Mixpanel 事件作为[自定义事件](./custom-events)路由到 OneSignal，请使用第三方连接器，如 [Vendo](https://www.vendodata.com/use-cases/integrate-mixpanel-with-onesignal)。

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

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

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

* User State Observer: [Mobile SDK](./mobile-sdk-reference#addobserver-user-state), [Web SDK](./web-sdk-reference#addeventlistener-user-state)
* Permission Observer: [Mobile SDK](./mobile-sdk-reference#addpermissionobserver-push), [Web SDK](./web-sdk-reference#permissionchange)

***

## 相关页面

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