# Segment 集成

<Aside type="caution" icon="setting" title="需要开发者协助">
 您需要开发团队的帮助来设置此集成。请与他们分享本指南。
</Aside>


[Segment](https://segment.com/) 是一个客户数据平台，可简化用户数据收集并帮助您有效利用这些数据。如果您将客户数据存储在 Segment 中，只需点击几下即可设置与 Pushwoosh 的集成。

集成设置完成后，Segment 会将以下数据发送到 Pushwoosh：

*   用户属性：姓名、设备、偏好、位置、行为等。Pushwoosh 会将这些数据保存为每个用户的[标签](/zh/product/audience-data-and-segmentation/user-data-tags/tags/)及其值。
*   事件：每个 Segment 事件都将传输到 Pushwoosh，并以相同的名称保存为 [Pushwoosh 事件](/zh/product/audience-data-and-segmentation/events/)。Pushwoosh 还会获取每个用户触发了哪些事件的信息。

使用 Segment 数据，您可以在 Pushwoosh 中通过无缝通信跟进您的受众。以下是利用这两个平台强大功能的两个示例：

**1. 基于用户行为数据创建定向营销活动。** 使用来自 Segment 的事件数据，在 Pushwoosh 中根据特定的用户行为构建精确的用户细分。

例如，Segment 会将有关 _SubscribedToOffers_ 事件的数据发送到 Pushwoosh。您可以在 Pushwoosh 中构建一个由已订阅特别优惠的用户组成的用户细分：

<img src="/integrations-segment-integration-1.webp" alt="基于 SubscribedToOffers 事件的用户细分"/>

然后，您可以为订阅了您优惠的用户创建包含促销信息和折扣的引人入胜的客户旅程：

<img src="/integrations-segment-integration-2.webp" alt="为订阅者设计的包含促销信息的客户旅程"/>

**2. 基于来自 Segment 的用户属性进行消息个性化。** 您可以利用从 Segment 获取的用户属性来修改推送通知、应用内消息和电子邮件的内容。这将使您能够建立相关且高转化率的通信。

例如，Segment 会将 _searched_product_ 属性值发送到 Pushwoosh。您可以创建一个推送预设，为用户之前搜索过的类别的产品提供折扣：

<img src="/integrations-segment-integration-3.webp" alt="包含产品类别动态内容的推送预设"/>

每个用户都将收到一条推送，为他们之前浏览过的确切产品类别提供折扣。例如，搜索过运动鞋的用户将看到此消息：

<img src="/integrations-segment-integration-4.webp" alt="运动鞋类别推送通知示例" width="375"/>

## 集成概述

### 集成类型

*   **目标 (Destination)**：数据从 Segment 发送到 Pushwoosh。
*   **源 (Source)**：数据从 Pushwoosh 发送到 Segment。

### 先决条件

在 Pushwoosh 和 Segment 中均拥有付费帐户

### 同步实体

**源**

*   推送统计

**目标**

*   设备
*   标签

### 用例

**跟踪通知**

发送推送通知并跟踪其状态，包括它们是否已成功发送和送达。

**事件分析**

分析用户触发的事件，例如推送通知或电子邮件送达，并确保这些事件在 Segment 中被准确记录。

**用户管理**

注册和管理用户信息，包括为用户添加相关属性的标签或在需要时删除用户。

## 设置集成

<Aside type="note">
在设置与 Segment 的集成之前，请确保已集成 [Pushwoosh SDK](/zh/developer/first-steps/integrate-pushwoosh-sdk)。
</Aside>

### 配置目标

1.  [在 Segment 界面中](https://app.segment.com/login/)，导航至 **Connections** → **Destinations**，然后点击 **Add Destination**。

2.  搜索 **Pushwoosh** 并选择它。

3.  选择您想要连接到该目标的源。

4.  转到目标设置：

<img src="/integrations-segment-integration-5.webp" alt="Segment 中的目标设置"/>

5.  输入 **Pushwoosh API 密钥**和**应用程序代码**。确保 **Enable Destination** 开关已打开。之后，点击 **Save Changes**。

<details>

<summary>在哪里可以找到 API 密钥和应用程序代码？</summary>

您可以在 **Settings** → **API Access** 部分找到 API 密钥：

<img src="/integrations-segment-integration-6.webp" alt="Pushwoosh 设置中的 API 访问部分" data-size="original"/>

应用程序代码可以在 Pushwoosh 界面的左上角，项目名称的正下方找到：

<img src="/integrations-segment-integration-7.webp" alt="Pushwoosh 界面中的应用程序代码" data-size="original"/>

</details>

6.  转到 **Mappings** 选项卡，并确保 **Create or Update User Profile** 和 **Track Events** 选项已启用：

<img src="/integrations-segment-integration-8.webp" alt="包含“创建或更新用户个人资料”选项的映射选项卡"/>

验证从源到 Pushwoosh 目标的事件字段映射非常重要，以确保您的事件得到正确处理。

如果事件不包含 _**device_platform**_ 字段或该字段不正确，您的事件将被忽略。此外，如果事件既不包含 _**userId**_ 也不包含 _**deviceId**_，它也将被忽略。

为确保您的映射配置正确，请转到 **Pushwoosh as Destination > Settings**。

<img src="/integrations-segment-integration-9.webp" alt="用于映射配置的目标设置"/>

然后，选择 **Mapping** 选项卡，并为 **Track Events** 方法点击 **Edit Mapping**。

<img src="/integrations-segment-integration-10.webp" alt="“跟踪事件”方法的编辑映射"/>

接下来，确保您的事件到发送给 Pushwoosh 的事件的映射是正确的，并且 **Device Platform** 和 **External User ID**（或 **Device ID**）字段已正确匹配。

<img src="/integrations-segment-integration-11.webp" alt="包含设备平台和外部用户 ID 的事件映射"/>

您的事件可能与上面提供的示例不同。但是，关键是为发送到 Pushwoosh 的事件匹配平台和设备的数据传输。

如果集成配置正确，Pushwoosh 将开始从 Segment 接收事件和用户属性。基于这些数据，您可以创建高度定向的[客户旅程](/zh/product/customer-journey/pushwoosh-journey-overview)并[个性化](/zh/product/personalization/dynamic-content/)您的推送通知、应用内消息和电子邮件。

### 配置源

1.  在您的工作区的 [Sources catalog 页面](https://app.segment.com/goto-my-workspace/sources/catalog)上，点击 **Add Source**。
2.  在 Sources Catalog 中搜索“**Pushwoosh**”，选择 Pushwoosh，然后点击 **Add Source**。
3.  在下一个屏幕上，为源命名并配置任何其他设置。

<Aside type="note">
该名称在 Segment 应用中用作标签，Segment 会在您的仓库中创建一个相关的模式名称。名称可以是任何内容，但 Pushwoosh 建议使用能反映源本身并区分您的环境的名称（例如：Pushwoosh\_Prod、Pushwoosh\_Staging、Pushwoosh\_Dev）。
</Aside>

4.  点击 **Add Source** 以保存您的设置。
5.  从 Segment UI 复制 **Write key**。
6.  登录您的 Pushwoosh 帐户，然后选择您要连接的应用程序。
7.  导航至 **Settings > 3rd party integration > Segment**，点击 **Configure 按钮**，然后输入来自您 Segment 工作区的 **Write key**。
8.  在 **Events** 字段中，使用 `,` 分隔符列出您想要导出的事件，或者如果您想导出所有事件，则将该字段留空，然后点击 **Apply**。

#### 流

Pushwoosh 使用 Segment 流源组件来发送 Segment 事件数据。它使用服务器端 `track` 方法向 Segment 发送数据。这些事件随后在任何接受服务器端事件的目标中可用，并在您的数据仓库的模式中可用。

默认情况下，Pushwoosh 将 Pushwoosh User ID 作为 Segment `userId` 属性传递。如果没有关联的 User ID，Pushwoosh 将传递 HWID 作为 Segment `anonymousId`。

#### 事件

下表列出了 Pushwoosh 发送到 Segment 的事件。这些事件在您的仓库中显示为表格，在其他目标中显示为常规事件。

| 事件名称 | 描述 |
| ------------------ | ----------------------------------------------- |
| 邮件已发送 | 邮件已成功发送 |
| 推送已发送 | 推送通知已成功发送 |
| 短信已发送 | 短信已发送给收件人 |
| 推送已打开 | 推送通知已被打开 |
| 邮件已打开 | 邮件通知已被打开 |
| 邮件已送达 | 邮件已成功送达 |
| 推送已送达 | 推送通知已成功送达 |
| 短信已送达 | 短信已成功送达 |
| 短信未送达 | 短信发送失败 |
| 邮件退回 | 由于永久性错误，邮件被退回给发件人 |
| 邮件已退订 | 点击了邮件退订链接 |

#### 事件属性

下表列出了上述事件中包含的属性。

| 属性名称 | 描述 |
| --------------- | --------------------------------------------------------- |
| `message_type` | 包含消息类型（推送、邮件、应用内或短信） |
| `campaign_code` | 消息活动的唯一标识符 |
| `device_type` | 设备类型 |

#### 添加目标

现在您的源已设置好，您可以将其与目标连接。

登录到您的下游工具，检查您的事件是否按预期显示，以及它们是否包含您期望的所有属性。如果您的事件和属性没有出现，请检查事件交付，并参考每个工具的目标文档进行故障排除。

如果事件到达 Segment 的方式有任何问题，请[联系我们的支持团队](mailto:support@pushwoosh.com)。

## 集成如何工作

1.  **推送通知启动**：客户端通过 Pushwoosh 界面启动推送通知过程。
2.  **事件生成**：Pushwoosh 后端处理推送通知请求并生成一个事件。此事件随后被发送到由 Pushwoosh 管理的名为 `channels-tracking-log` 的 Kafka 主题。
3.  **事件消费**：Segment 集成服务持续监听 `channels-tracking-log` Kafka 主题，并在事件到达时消费它们。
4.  **事件处理**：被消费的事件由 Segment 集成服务处理，该服务将它们转换为 Segment Track Events。
5.  **事件传输**：处理后的 Segment Track Events 随后被发送到 Segment 后端进行进一步处理和分析。

## 如何知道集成是否正常工作？

#### 目标

##### track-user

转到您的 **Pushwoosh 帐户 > 您连接的应用程序 > Audience > User Explorer**。找到您的用户/设备并检查 Segment 发送的标签。

##### post-event

转到您的 **Pushwoosh 帐户 > 您连接的应用程序 > Audience > Events**。选择事件，点击三点菜单，然后选择 Event Statistics。确保事件已被计数。

##### delete-user

转到您的 **PW 帐户 > 您连接的应用程序 > Audience > User Explorer**。确保用户/设备不存在。

#### 源

使用[源调试器](https://segment.com/docs/connections/sources/debugger/)来检测从 Pushwoosh 发送到 Segment 的事件。

## 故障排除

### 检查集成状态

要解决 Pushwoosh 集成的问题，请首先验证以下内容：

**目标**

*   **Track-User**：在 Pushwoosh 的 `Audience > User Explorer` 下验证用户/设备信息和标签。
*   **Post-Event**：通过检查事件统计信息，确保事件在 Pushwoosh 中被计数。
*   **Delete-User**：确认用户/设备在 Pushwoosh 中已不存在。

**源**

使用位于 [Segment Debugger](https://segment.com/docs/connections/sources/debugger/) 的源调试器来检查来自 Pushwoosh 的事件是否已正确发送到 Segment。

### 事件不匹配

如果事件在 Segment 中未正确显示，请确保 Pushwoosh 事件已根据提供的映射规则正确映射到 Segment Track Events。

### 身份验证问题

验证对 Pushwoosh 和 Segment 的请求中是否使用了正确的身份验证令牌或 API 密钥。

### 数据流问题

确认 Pushwoosh 和 Segment 之间的数据流没有中断，并且 Kafka 主题正在被正确监控。

## 常见问题解答

### 从 Pushwoosh 发送到 Segment 的事件类型有哪些？

**推送已发送、邮件已发送、短信已发送、推送已送达、邮件已送达、短信已送达**和**邮件退回**等保留事件会被发送到 Segment。

### 如何验证事件是否已正确发送到 Segment？

使用 Segment 源调试器检查从 Pushwoosh 发送的事件，并在您的 Pushwoosh 帐户中查看事件统计信息，以确保它们被正确计数。

### 如果集成遇到问题，我该怎么办？

通过在 Pushwoosh 中验证用户/设备信息、事件计数和用户删除情况来检查集成状态。此外，请确保使用了正确的身份验证令牌，并且数据流没有中断。

### 集成中如何处理用户和设备信息？

用户和设备信息，包括属性和标签，会根据来自 Segment 的请求在 Pushwoosh 中注册或更新。请注意，默认标签不会在 Pushwoosh 中自动创建。

### 在哪里可以找到集成的详细文档？

详细文档可在 Segment 和 Pushwoosh 集成手册以及它们各自的 API 文档中找到。