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

# Segment (Twilio)

> 将 OneSignal 与 Twilio Segment 集成，用于用户数据和消息事件。

<Frame caption="OneSignal Segment 集成概述">
  <img src="https://mintcdn.com/onesignal/6v_cVPknFpo5qSVB/images/docs/0fe35d2-onesignal-segment-integration_1.png?fit=max&auto=format&n=6v_cVPknFpo5qSVB&q=85&s=f70d1f0b0ea879b548b634bb253ecacf" width="1280" height="720" data-path="images/docs/0fe35d2-onesignal-segment-integration_1.png" />
</Frame>

## 概述

OneSignal + Segment 集成允许您：

* 将用户特征和事件从 Segment 发送到 OneSignal，以丰富用户资料、增强细分和触发消息。
* 将消息投递和参与事件从 OneSignal 发送到 Segment，用于集中分析和数据仓储。

这种双向设置支持所有主要的 OneSignal 渠道：推送、应用内、邮件和短信。

***

## 要求

* Growth、Professional 或 Enterprise [OneSignal 账户](https://onesignal.com/pricing)
* Segment 管理员权限
* 要发送数据的 OneSignal [Mobile SDK](./mobile-sdk-setup) 和/或 [Web SDK](./web-push-setup)。仅使用[邮件](./email-setup)或[短信](./sms-setup)的集成不需要 SDK
* OneSignal 属性：[外部 ID](./users)，映射到 Segment.com 的 `userId`

***

## 设置

### 1. 设置 OneSignal

使用现有的应用或在 OneSignal 仪表板中创建一个新的应用。然后设置您首选的渠道：

* [Web Push Setup](./web-push-setup)
* [Mobile Push Setup](./mobile-sdk-setup)
* [SMS Setup](./sms-setup)
* [Email Setup](./email-setup)

### 2. 将 Segment 连接到 OneSignal

在 OneSignal 仪表板中，转到**数据 > 集成**并在 Segment.com 卡片中点击**激活**。然后继续进行设置选项。

#### 数据输入

对 OneSignal 的“数据输入”允许您从 Segment.com 账户向 OneSignal 发送 [OneSignal 细分](./segmentation)、[标签](./add-user-data-tags) 和[自定义事件](./custom-events)。在 OneSignal 仪表板中的 Segment.com 设置页面的*数据输入*部分下点击**认证**。

<Note>
  自定义事件目前处于测试版。
  To request access, contact `support@onesignal.com` with:

  * Your company name
  * Your OneSignal Organization ID
  * The App ID(s) you want to enable
</Note>

<Warning>
  一旦启用追踪自定义事件，Segment.com 集成将同时发送数据标签和事件，因此您无需更新任何引用数据标签的现有模板。
</Warning>

<Frame caption="数据输入认证设置">
  <img src="https://mintcdn.com/onesignal/YOTSrtBSoqdrJ37A/images/docs/48031e3-Data_in.png?fit=max&auto=format&n=YOTSrtBSoqdrJ37A&q=85&s=3985a85e39ed139234cf81b3f29a0290" width="1182" height="428" data-path="images/docs/48031e3-Data_in.png" />
</Frame>

点击认证后，将打开 Segment.com 网页，提示您登录 Segment.com 账户。然后将提示您从 Segment.com 账户配置新的数据目标。

<Frame caption="Segment 设置配置屏幕">
  <img src="https://mintcdn.com/onesignal/0qspEXXeJ8zJbkJ-/images/docs/85c6577-segment_set_up.png?fit=max&auto=format&n=0qspEXXeJ8zJbkJ-&q=85&s=a8a554790d8c80595116aca43093627b" width="898" height="916" data-path="images/docs/85c6577-segment_set_up.png" />
</Frame>

#### 数据输出

启用对 Segment.com 的“数据输出”会将生成的消息事件同步回您的 Segment.com 账户。这些消息事件是通过在 OneSignal 平台上向用户发送消息而生成的。关于可以生成的事件类型以及它们带有的属性的更多详情，可以在[下面](./segment-onesignal-integration#message-events)找到。

首先，您需要从 Segment.com 账户中将 OneSignal 添加为源。您可以通过在 Segment Connections Catalogue 中导航到 [OneSignal Source listing](https://segment.com/docs/connections/sources/catalog/cloud-apps/onesignal/) 来完成此操作。

从那里，您可以在 OneSignal 仪表板上添加您的 Segment.com API 令牌。请在 OneSignal 仪表板中导航到**数据 > 集成 > Segment** 来添加 Segment API 密钥。

<Frame caption="数据输出 API 密钥配置">
  <img src="https://mintcdn.com/onesignal/6tscVAtiSqz353kV/images/docs/9d8eb5f-data_out_3.png?fit=max&auto=format&n=6tscVAtiSqz353kV&q=85&s=56098282da219dd7eb274b183b271362" width="1604" height="1052" data-path="images/docs/9d8eb5f-data_out_3.png" />
</Frame>

设置 API 密钥后，请确保检查您在 Segment.com 中的数据政策设置，以确定是否需要将事件发送到 Segment 的 EU 居留端点。

完成所有这些设置后，您可以根据您在 OneSignal 中使用的渠道选择要同步到 Segment 账户的事件。

### 3. 在 Segment 中添加 OneSignal 目标

在 **Segment.com 仪表板 > 目标**中，您应该看到 **OneSignal**。如果没有，请将 OneSignal 添加为新目标。

启用 OneSignal 目标，您应该已经看到您的 OneSignal API 密钥和应用 ID

<Frame caption="Segment 中的 OneSignal 目标配置">
  <img src="https://mintcdn.com/onesignal/56ctKxZSV4m5VEkn/images/docs/b191d42-turn-on-configuration-in-segment.png?fit=max&auto=format&n=56ctKxZSV4m5VEkn&q=85&s=aebe97a4fbfe4775b502b2c3186ff5fb" width="2046" height="946" data-path="images/docs/b191d42-turn-on-configuration-in-segment.png" />
</Frame>

如果未设置 API 密钥和应用 ID，请导航到 [OneSignal 仪表板](https://app.onesignal.com/apps/)，选择应用，并转到**设置 > 密钥和 ID**。将“应用 ID”和“API 密钥”复制粘贴到 Segment.com。

#### 多个 Segment.com 源

如果您有多个源，您可以利用 [Segment 的 **Personas > Spaces** 功能](https://segment.com/docs/personas/#personas-spaces)将多个源绑定到一个目标。

### 4. 从 Segment 向 OneSignal 发送数据

OneSignal 存储渠道级别的记录：推送/IAM、邮件和短信。这些记录必须已在 OneSignal 中创建，您还必须在 OneSignal 中设置[外部 ID](./users)别名，以匹配 Segment.com 发送的 `userID` 字段。

<Warning>
  没有 **Segment 用户 ID \<--> OneSignal 外部 ID** 映射的记录将被丢弃。
</Warning>

## 用户特征或属性

您可以在 Segment 中聚合每个客户接触点的数据，然后实时将这些用户属性作为[数据标签](./add-user-data-tags)发送到 OneSignal。

**注意**：OneSignal 不能接受嵌套对象或数组作为用户属性。

[Identify](https://segment.com/docs/connections/spec/identify) - 使用 *Segment 的 Identify 调用*发送的用户特征或属性在 OneSignal 中存储为数据标签。例如：

<Frame caption="用户 identify 调用示例">
  <img src="https://mintcdn.com/onesignal/ciRrThfP6xMpI7GY/images/docs/0209647-Screenshot_2024-05-08_at_11.44.24_AM.png?fit=max&auto=format&n=ciRrThfP6xMpI7GY&q=85&s=423258a2b318e017771eb7a0586a88d9" width="2360" height="632" data-path="images/docs/0209647-Screenshot_2024-05-08_at_11.44.24_AM.png" />
</Frame>

[Track](https://segment.com/docs/connections/spec/track/) - 对于使用 *Segment 的 Track 调用*发送的事件和相关属性，OneSignal 将将所有*事件属性*存储为数据标签，但在存储标签时*丢弃\*\*事件名称*。如果您希望在数据标签中保留*事件名称*，您可以在将属性发送到 OneSignal 之前将事件名称附加到属性中。例如：

<CodeGroup>
  ```javascript track example theme={null}
  let timestampInSeconds = Int(NSDate().timeIntervalSince1970).toString()//convert to string since Segment adds decimals to end
  //name will be dropped and only properties will be sent to OneSignal as tag "last opened: timestampInSeconds"
  analytics.track(
    name: "iOS App Last Opened",
    properties: ["last opened": timestampInSeconds]
  )
  ```
</CodeGroup>

<Frame caption="Track 调用属性示例">
  <img src="https://mintcdn.com/onesignal/4HyuQPBpu-4xjmQC/images/docs/ce2b574-Screenshot_2024-05-08_at_11.49.34_AM.png?fit=max&auto=format&n=4HyuQPBpu-4xjmQC&q=85&s=0a32647a69bae9078fa785b6df4a7d24" width="2360" height="632" data-path="images/docs/ce2b574-Screenshot_2024-05-08_at_11.49.34_AM.png" />
</Frame>

<Frame caption="用户特征和属性界面">
  <img src="https://mintcdn.com/onesignal/jFWn5xzleD8du3j6/images/docs/565e212-user-traits-or-properties.png?fit=max&auto=format&n=jFWn5xzleD8du3j6&q=85&s=a18d3a422c087b32ce05d702b51b2e6b" width="1773" height="1209" data-path="images/docs/565e212-user-traits-or-properties.png" />
</Frame>

## Personas 受众和计算特征

[Persona 受众](https://segment.com/docs/personas/)自动作为 [OneSignal 中的细分](./segmentation)显示。

计算特征作为 OneSignal 用户记录上的[数据标签](./add-user-data-tags)进行更新。

**受众**

<Frame caption="Persona 受众和计算特征界面">
  <img src="https://mintcdn.com/onesignal/9_Q1FZLh6C0BFLq-/images/docs/c494a4b-persona-audience-or-computed-traits.png?fit=max&auto=format&n=9_Q1FZLh6C0BFLq-&q=85&s=2a858790b04fbcbc6676e894efd3254b" width="1773" height="1209" data-path="images/docs/c494a4b-persona-audience-or-computed-traits.png" />
</Frame>

使用 Segment 的 [Track 调用](https://segment.com/docs/connections/spec/track/)发送的受众将使用*受众名称*创建 OneSignal 细分。

使用 Segment 的 [Identify 调用](https://segment.com/docs/connections/spec/identify/)发送的受众将：

* 使用*受众名称*创建 OneSignal 细分
* 在所有匹配的用户记录上添加数据标签（如果 Identify 调用中有额外属性）。

<Frame caption="从 Segment 在 OneSignal 中创建的细分">
  <img src="https://mintcdn.com/onesignal/Z6xkXGfmy814If53/images/docs/e5ad7f4-segments-in-onesignal.png?fit=max&auto=format&n=Z6xkXGfmy814If53&q=85&s=21e0f73a8bf21f50311b1c6e11535c51" width="1773" height="1209" data-path="images/docs/e5ad7f4-segments-in-onesignal.png" />
</Frame>

当用户进入或退出受众时，Identify 和 Track 调用会自动发送到 OneSignal。

**计算特征** Personas 计算特征作为[数据标签](./add-user-data-tags)存储在 OneSignal 用户记录上，无论是作为 Identify 调用还是 Track 调用传递给 OneSignal。然后您可以使用这些数据标签手动创建 OneSignal 细分并自动化您的消息工作流。

***

## 消息事件

## 事件类型

这些是 OneSignal 发送到 Segment 的消息事件类型

| MessageEvent Kind             | Event Description |
| ----------------------------- | ----------------- |
| Push Sent                     | 推送通知成功发送          |
| Push Received                 | 推送通知成功接收          |
| Push Clicked                  | 在设备上点击推送通知        |
| In-App Message Displayed      | 应用内消息在设备上成功显示     |
| In-App Message Clicked        | 在设备上点击应用内消息       |
| In-App Message Page Displayed | 显示应用内消息页面         |
| Email Sent                    | 邮件成功发送            |
| Email Opened                  | 收件人打开邮件           |
| Email Unsubscribed            | 收件人取消订阅邮件         |
| Email Received                | 收件人接收邮件           |
| Email Reported As Spam        | 收件人举报邮件为垃圾邮件      |
| Email Bounced                 | 由于永久性错误邮件被返回给发送者  |
| Email Failed                  | 无法将邮件投递到收件人的收件箱   |
| SMS Sent                      | 短信发送给收件人          |
| SMS Delivered                 | 短信成功投递            |
| SMS Failed                    | 短信发送失败            |

### 事件属性

这些是从 OneSignal 发送到 Segment.com 的事件中存在的属性

| PROPERTY NAME       | DESCRIPTION              |
| ------------------- | ------------------------ |
| `userId`            | 与消息关联的 `external_id`     |
| `anonymousId`       | `subscription_id`        |
| `messageId`         | 离散消息的标识符                 |
| `campaign_id`       | 与 `messageId` 相同的值       |
| `message_name`      | 消息名称                     |
| `message_title`     | 消息标题                     |
| `message_contents`  | 消息内容                     |
|                     |                          |
| `subscription_type` | 消息通过的渠道                  |
| `template_id`       | 使用的消息模板                  |
| `subscription_id`.  | OneSignal 设置的设备/邮件/短信标识符 |
| `device_type`       | 接收消息的设备类型                |
| `language`          | 设备的两个字符语言代码              |
| `message_type`      | 发送的消息类型：推送、应用内、邮件、短信     |

## 常见问题

### 我们如何传递订阅事件？

订阅事件目前不会自动发送。这可以通过 OneSignal SDK 订阅观察者方法来完成。有关更多详情，请参阅[订阅跟踪](./analytics-overview#subscription-tracking)。

### 在 OneSignal 中管理 Segment 的保留和自定义用户属性

* 所有 Segment 的用户特征都作为数据标签发送到 OneSignal。OneSignal 上允许的数据标签数量取决于您的 OneSignal 价格计划。超过授权数量的标签将被丢弃。
* OneSignal 始终为匹配的用户更新 firstName 和 lastName 属性。所有其他特征按先到先得的原则添加/更新。*firstName* 和 *lastName* 标签存储为 "first\_name" 和 "last\_name"。
* 使用空白/空值发送到 OneSignal 的用户属性从 OneSignal 用户记录中被删除。这样做是为了确保您不超过数据标签限制。

***