# 基于 API 的入口

<Aside type="caution" icon="setting" title="需要开发者协助">
 您需要开发团队的帮助来设置基于 API 的入口旅程。请与他们分享本指南。
</Aside>

## 工作原理

基于 API 的入口允许您在特定业务事件发生时立即启动客户旅程。要开始一个营销活动，您必须发送一个特殊的 API 请求。

以下是基于 API 的入口的一些用例：

* 通知客户产品何时补货
* 告诉用户热门产品的价格已下降
* 通知订阅者新的播客剧集已发布

与常规事件不同，所有这些业务事件都可能发生在应用之外。例如，产品的可用性只能在外部数据库中检查。这时，基于 API 的入口就派上用场了：您可以设置在应用外部发生某些变化时（例如，在您的外部数据库中）发送请求以启动旅程。

<img src="/shared-33.webp" alt="旅程画布上的基于 API 的入口元素"/>

其工作方式如下：

1. 创建一个带有基于 API 的入口的旅程。在入口设置中，您将找到启动旅程的请求模板。
2. 使用 [细分语言](/zh/developer/api-reference/segmentation-filters-api/segmentation-language) 向请求添加细分条件。您还可以向请求添加内容占位符，以根据上下文更改消息内容。
3. 如果需要，可以自动化该请求。例如，有关价格变化的信息可以立即从数据库发送到 webhook。一旦发生这种情况，webhook 应自动发送请求以启动旅程。如果您不需要自动化，也可以手动发送请求。

您可以无限次地发送请求来更改细分条件或消息内容。

有关更多详细信息，请遵循以下说明。

## 设置带有基于 API 的入口的旅程

1. 创建一个带有基于 API 的入口的旅程：

<video src="/journey-elements-api-based-entry-1.webm" title="创建一个新旅程并选择基于 API 的入口" autoplay loop muted playsinline />

2. 双击基于 API 的入口步骤。入口配置窗口将打开。

3. 您可以通过使用内容占位符，在每次启动旅程时修改推送和电子邮件内容。每个占位符的值都可以在请求中更改。如果您不需要此选项，可以跳过此步骤。

> 例如，您正在创建一个旅程，以在新的播客剧集发布时通知订阅者。使用内容占位符，您可以在每次启动旅程时更改播客标题。

首先，在基于 API 的入口设置窗口中添加占位符名称。您可以使用任何方便您的名称。

<img src="/journey-elements-api-based-entry-2.webp" alt="在基于 API 的入口设置窗口中添加内容占位符名称"/>

现在，创建一个[推送预设](/zh/product/content/push-presets)或[电子邮件内容](/zh/product/content/email-content/)，并将占位符插入到您想要修改的文本位置。根据您的需求，占位符必须是以下格式之一：

* `{placeholder_name|format_modifier|}` – 如果在启动营销活动时未指定占位符的值，用户将在其位置看到空白。
* `{placeholder_name|format_modifier}` – 如果未指定占位符的值，并且之前也未分配给用户（如果您使用标签作为占位符），则不会发送消息。

<details>

<summary>格式修饰符</summary>

* **CapitalizeFirst** – 将占位符值中的第一个字母大写
* **CapitalizeAllFirst** – 将占位符值中所有单词的首字母大写
* **UPPERCASE** – 将所有字母切换为大写
* **lowercase** – 将所有字母切换为小写
* **regular** – 完全按照请求中指定的方式插入占位符值

</details>

<img src="/journey-elements-api-based-entry-3.webp" alt="将占位符插入推送预设以实现动态内容"/>

<Aside type="tip">
您也可以使用[现有的标签](/zh/product/audience-data-and-segmentation/user-data-tags/)名称代替占位符名称。在这种情况下，您必须配置用请求中指定的值覆盖此标签值，如下所述。
</Aside>

在您的旅程中配置推送或电子邮件元素时，选择创建的预设并打开 **使用事件属性个性化消息** 选项。

选择您想在启动旅程时在请求中修改的占位符。选择 **基于 API 的入口** 作为来源，并选择占位符名称作为动态属性：

<video src="/journey-elements-api-based-entry-4.webm" title="使用来自基于 API 的入口的事件属性个性化消息" autoplay loop muted playsinline />

单击 **应用** 以保存更改。

4. 在入口配置窗口中，复制请求模板以进行修改：

<img src="/journey-elements-api-based-entry-5.webp" alt="从基于 API 的入口配置窗口复制请求模板"/>
<Aside> 
要通过 API 启动旅程，您必须在 Authorization 标头中包含一个有效的授权令牌。

**必需的标头格式**

  ```http
  Authorization: Api <your_api_token>
  ```
  **示例**

  ```http
  Authorization: Api c8dc6435-xxxxxxxxxxxxxxx
  ```
  
 </Aside>


5. 使用[细分语言](/zh/developer/api-reference/segmentation-filters-api/segmentation-language)向 `"filter"` 参数添加受众过滤器，或从您的细分中[复制细分语言](/zh/product/audience-data-and-segmentation/segmentation/#copy-segment-logic)。请提前设置必要的[标签](/zh/product/audience-data-and-segmentation/user-data-tags/tags)。

例如，要定位将 _Socks_ 商品添加到其 _Wishlist_ 的用户，`"filter"` 值必须如下所示：

`"filter": "A(\"12345-12345\") * "T(\"Wishlist\", EQ, \"Socks\")"`

在此示例中，您必须在您的应用中配置一个 _Wishlist_ 标签。

<Aside type="note">
您的应用程序代码会自动以 `A(\"12345-12345\")` 的格式添加到 `"filter"` 参数中。请勿删除或修改它。

另外，请记住，在 JSON 查询中，引号 ("") 和反斜杠 (\\) 应使用反斜杠 (\\) 进行转义。
</Aside>

<Aside type="tip">
您还可以通过在 `"hwids"` 参数中传递 HWID 数组或在 `"users"` 参数中传递用户 ID 数组来直接定位特定设备或用户，而不是使用过滤器：

```json
"users": ["user_id_1", "user_id_2", ...],
"hwids": ["hwid_1", "hwid_2", ...]
```
</Aside>

6. 如果您设置了占位符，请将所需内容指定为其值：

<img src="/journey-elements-api-based-entry-6.webp" alt="在 API 请求中指定占位符值以启动旅程"/>


7. 如果您计划频繁重启您的营销活动，并且不希望同一用户多次进入旅程，请设置[营销活动入口限制](/zh/product/customer-journey/journey-settings#campaign-entry-limit)。

> 例如，您创建了一个营销活动，以通知用户特定产品的降价信息。您希望通过发送几个具有不同受众过滤器的请求来重新启动几次旅程。在这种情况下，您可以添加营销活动入口限制，这样通知就不会重复发送给匹配多个过滤器的用户。

8. 如果您希望每当某个业务事件发生时就启动一个旅程，请使用 webhook 自动化请求。一旦事件发生，webhook 应自动发送请求以启动旅程。

如果您不需要自动化，也可以手动发送请求。

<Aside type="note">
* 如果您在发送新请求时更改了细分条件，这不会影响已经进入旅程的用户。
* 如果您在发送新请求时更改了消息内容，所有用户都将收到新版本的消息（包括那些已经进入旅程但尚未收到此消息的用户）。
</Aside>