# 连接内容

连接内容是 [Liquid 模板](/zh/product/personalization/liquid-templates/)中的一项功能，允许您直接在电子邮件或推送通知消息中动态检索和使用来自外部源（如 Web 服务）的数据。此功能通过从指定 URL 获取 JSON 数据并将其保存到可在内容中使用的变量中，从而实现实时个性化。

## 主要用例

-   **产品推荐**：显示为每个用户量身定制的个性化产品列表。

-   **促销代码**：插入由后端服务生成的唯一促销代码。

## 先决条件

*   要使用连接内容，您必须拥有自己的后端服务，该服务根据 **User ID、HWID 或自定义标签**生成并提供所需的数据（例如，促销代码、产品推荐）。然后，Pushwoosh 在发送消息之前获取此数据。

## 分步实施指南

<Aside type="caution" icon="setting" title="需要开发者协助">
您需要开发团队的帮助才能使用连接内容。与他们分享本指南以开始使用。
</Aside>

### 步骤 1. 设置后端服务

后端服务应：

*   接受包含用户特定参数（例如，`userId`）的请求。连接内容支持 `UserID`、`HWID` 或您在项目中设置的任何自定义标签。
*   返回包含所需数据的 JSON 响应。然后，此内容可以动态插入到消息中。

<Aside type="note" title="工作原理"> 

后端服务充当数据提供者，通过用户特定的信息响应 HTTP 请求。

1.  Pushwoosh 向您的后端发送请求，将用户特定的标识符作为查询参数传递。
2.  您的后端处理请求并检索所请求的数据。
3.  您的后端返回一个 JSON 响应。
4.  在发送消息之前，Pushwoosh 从后端服务获取 JSON 响应，并在消息内容中动态使用返回的值（例如，`code`）。

**响应示例**

```
{ "code": "SPECIALOFFERFORUSER12345" }
```
</Aside>



### 步骤 2. 在 Pushwoosh 中创建带有连接内容的预设
 
1.  在 [推送](/zh/product/content/push-presets/) 或 [电子邮件内容编辑器](/zh/product/content/email-content/drag-and-drop-email-editor/) 中，将连接内容语法插入到消息字段中。

**示例** 

```
{% connected_content http://your-backend-url.com?userId={{ ${userid} }} :save result %}  
```
**语法分解**
|  |  |
| ----- | ----- |
| `connected_content` | 从指定的后端 URL 获取 JSON 数据。 |
|    `http://your-backend-url.com` | 以 JSON 格式返回所需数据的后端端点。 |
| `userId={{ ${userid} }}` | 一个动态查询参数，用于将用户 ID 传递给后端。在 `connected_content` 内，请将变量包裹在 `${}` 中。在消息文本中，请写 `{{userid}}`，不带 `${}`。 |
| `:save result` | 将获取的 JSON 响应存储在 result 变量中，以供在 Liquid 模板中使用。 |

![插入连接内容语法](/connectedcontent.webp)

**身份验证（可选）**

如果您的后端服务需要身份验证，您可以在连接内容请求中包含 API 密钥或令牌，以确保安全访问。

```
{% connected_content http://your-backend-url.com?userId={{ ${userid} }}&auth=YOUR_API_KEY :save result %}  
```

您还可以使用可选的 `:headers` 参数（一个包含标头名称和值的 JSON 对象）将身份验证（或任何其他）数据作为 HTTP 标头发送。

```
{% connected_content http://your-backend-url.com?userId={{ ${userid} }} :headers {"Authorization": "Bearer YOUR_TOKEN", "X-Api-Key": "YOUR_API_KEY"} :save result %}  
```
|  |  |
| ----- | ----- |
| `:headers {...}` | 随请求发送的 HTTP 标头的 JSON 对象，例如 `Authorization: Bearer <token>`。 |

<Aside type="caution" title="仅限静态值">
`${}` 个性化变量仅在 URL 内部有效。`:headers` 内部的值是静态的，不会被插值。
</Aside>

<Aside type="danger" title="请勿将凭据放入 URL">
对于 API 密钥和令牌，请优先使用 `:headers` 而不是 URL 查询参数（例如 `&auth=YOUR_API_KEY`）：如果获取失败，请求 URL 会被写入日志，从而暴露放置在那里的密钥。`:headers` 内部的值永远不会被记录。

连接内容还要求为您的帐户启用 Liquid 内容模板。如果未启用，整个 `connected_content` 标签（包括其中的任何密钥）将作为文字文本发送给每个收件人，而不是被呈现。如果您不确定您的帐户是否已启用此功能，请联系 [Pushwoosh 支持](https://help.pushwoosh.com/hc/en-us/requests/new)。
</Aside>

**在连接内容中使用标签**

要包含标签值，请以相同的 `{{ ${tag_name} }}` 形式将其作为查询参数添加到 URL 中。如果在 `connected_content` 标签内写成 `{{ tag_name }}`，发送的值将为空。

```
{% connected_content http://your-backend-url.com?userId={{ ${userid} }}&lang={{ ${Language} }} :save result %} 
```

2.  接下来，添加包含**检索到的数据**的消息文本，如下所示：

```

嘿，{{userid}}，获取您的个人促销代码 - {{result.code}} 
```

![添加带有**检索到的数据**的消息文本](/connectedcontent-1.webp)

3.  在最终确定消息内容并配置预设设置后，保存它以便在营销活动中重复使用。

<video src="/connectedcontent-2.webm" title="发送带有连接内容的消息" autoplay loop muted playsinline />

### 步骤 3. 使用配置的预设发送消息

使用 [一次性推送](/zh/product/messaging-channels/push-notifications/send-push-notifications/one-time-push/#how-to-send-a-push-notification-using-the-one-time-push-form) 或 [电子邮件表单](/zh/product/messaging-channels/emails/sending-emails/send-one-time-emails/) 或 [customer journey](/zh/product/customer-journey/pushwoosh-journey-overview/) 发送带有此预设的消息。

<Aside type="caution" title="重要提示">
如果服务返回的状态不是 HTTP 200 OK，则不会发送电子邮件或推送通知。这确保了您的通信仅在成功检索到必要数据时才会发出。
</Aside>