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

# 示例应用：Journeys

> Clean Beans 示例应用中的七个 Journeys：新用户引导、连续记录、重新参与、推广，以及一个调用后端的 Journey Webhook。

本页面是[示例应用：完整的 OneSignal 集成](https://documentation.onesignal.com/docs/cn/example-full-integration-overview.md)的一部分，该指南从头到尾跟随一个真实应用。这个应用是 **Clean Beans**，一款面向合租家庭的打扫值日表应用，使用 Expo（React Native）和 Supabase 后端构建。

本指南中的大多数消息都由后端发送，每次一个请求。**Journey** 则不同。它是在 OneSignal 仪表板中构建的序列，会自行决定给谁发消息、何时发送以及接下来发生什么。Clean Beans 将 Journeys 用于需要持续数小时或数天的流程，以及无需发布新版本即可更改的文案和时间安排。

Clean Beans 运行七个 Journeys。

| Journey | 何时开始 | 作用 |
| - | - | - |
| [新用户引导](#onboarding-a-sequence-with-a-goal) | 应用发送 `signed_up` | 欢迎邮件和应用内引导，然后在六天内发送三条推送，直到第一次打扫会话 |
| [会话提醒](#session-reminder-start-on-one-event-cancel-on-another) | 应用发送 `cleaning_session_started` | 三小时后发送一条推送，除非会话已完成 |
| [会话完成](#session-completed-personalize-from-the-event) | 应用发送 `cleaning_session_completed` | 向打扫者发送一条推送，写明他们刚打扫的房间 |
| [按房间推广](#room-based-promos-branch-on-an-event-property) | 近期活跃的成员完成一次会话 | 两小时后针对厨房、浴室或卧室发送不同的推送 |
| [连续记录里程碑](#streak-milestone-an-event-with-a-number) | 应用发送 `streak_milestone` | 一条庆祝 3、7、14、30 天及以上的推送 |
| [连续记录即将中断](#streak-about-to-break-timing-a-segment-check-and-varied-copy) | 应用发送 `cleaning_session_completed` | 第二天晚上发送一条警告推送，使用五种措辞之一 |
| [重新参与](#re-engagement-and-the-journey-webhook) | 成员已七天未活跃 | 在十天内依次发送推送、推送、邮件、推送，然后向后端发送 Webhook |

除了最后一个 Journey 末尾的 Webhook 之外，它们都没有自己的后端代码。应用的工作是给 Journeys 提供可以使用的信息。

## 应用为 Journey 提供哪些信息 \\

Journey 能看到一个人的三类信息：他们发送的**自定义事件**、他们的**标签**，以及他们所属的**细分**。它无法读取您的数据库。Journey 需要响应的任何内容都必须以这些形式之一到达。

| 信号 | 类型 | 何时发送 | 使用者 |
| - | - | - | - |
| `signed_up` | 自定义事件 | 新账户首次登录 | 新用户引导（进入） |
| `cleaning_session_started` | 自定义事件 | 打扫会话开始 | 会话提醒（进入） |
| `cleaning_session_completed` | 自定义事件，带 `room_name` | 打扫会话结束 | 会话完成、按房间推广、连续记录即将中断（进入）。新用户引导、会话提醒、重新参与（退出） |
| `streak_milestone` | 自定义事件，带 `streak_count` | 一次会话让连续记录达到里程碑 | 连续记录里程碑（进入） |
| `user_name`、`household_name`、`streak_count` | 标签 | 登录、会话结束、编辑个人资料 | 个性化消息文本 |
| `streak_reminders` | 标签 | 登录时，以及保存通知设置时 | 连续记录即将中断（可以发给谁） |

会话事件在[标签、自定义事件和 Conversion Metrics](https://documentation.onesignal.com/docs/cn/example-full-integration-tags-events.md) 中介绍。另外两个事件仅用于启动 Journey。

`signed_up` 每个账户只触发一次。应用会先检查账户的创建时间，这样在新手机上安装应用的人不会再次经历新用户引导。

```typescript src/lib/onesignalSync.ts theme={null}
const accountAgeMs = Date.now() - new Date(profile.created_at).getTime();
if (accountAgeMs <= NEW_SIGN_UP_WINDOW_MS) {
  const ctx = await getEventContext();
  if (!ctx) return;

  OneSignal.User.trackEvent('signed_up', {
    external_id: ctx.external_id,
    user_name: ctx.user_name,
    household_name: ctx.household_name,
  });
  console.log('[onesignalSync] Custom event: signed_up');
}

await AsyncStorage.setItem(flagKey, '1');
```

`streak_milestone` 以数字形式携带连续记录的天数，以便消息显示它。

```typescript src/lib/onesignalSync.ts theme={null}
OneSignal.User.trackEvent('streak_milestone', {
  external_id: ctx.external_id,
  user_name: ctx.user_name,
  household_name: ctx.household_name,
  streak_count: streak,
});
```

> [!WARNING]
>
> 只有在调用 `OneSignal.login()` 之后才发送会启动 Journey 的事件。登录前发送的事件会记录到匿名用户上，而不是即将登录的那个人。Clean Beans 在同一个 effect 中紧接着 `login()` 调用 `trackSignedUpOnce()`。请参阅 [SDK 设置和用户身份](https://documentation.onesignal.com/docs/cn/example-full-integration-sdk-setup.md#tie-each-device-to-a-user)。

## 新用户引导：有目标的序列 \\

新用户引导 Journey 只有一个目标：让新成员完成第一次打扫会话。一旦达成，其中的一切都会停止。

**1. 应用发送 signed\_up**

成员进入 Journey。每位成员只经历一次。

**2. 立即发送欢迎邮件和应用内引导**

邮件列出三个入门步骤。应用内消息会在成员下次打开应用时显示。

**3. 在第 1、3、6 天发送三条推送**

每条推送都会等待成员所在时区 10:00 到 19:00 的时间窗口。

**4. 完成一次会话即结束**

Journey 的退出规则是 `cleaning_session_completed` 事件。不会有人被催促去做他们已经做过的事。

| 步骤 | 时间 | 消息 |
| - | - | - |
| 邮件 | 立即 | "Welcome to Clean Beans"，包含三个入门步骤 |
| 应用内消息 | 下次打开应用时，最多三天 | 欢迎引导 |
| 推送 1 | 第 1 天 | "Ready for your first clean?" |
| 推送 2 | 第 3 天 | "Cleaning is easier shared"（打开 Household 界面） |
| 推送 3 | 第 6 天 | "Your rota is waiting" |

**仪表板设置。** 创建 Journey 时，将 **Custom Event** 设为进入规则，并将 `signed_up` 设为事件。在退出规则中，选择在发生自定义事件时退出，并选择 `cleaning_session_completed`。在每条推送前放置一个 **Time Window** 步骤，这样在 03:00 结束的等待不会在 03:00 发送。

> [!TIP]
>
> 先确定目标，并把它设为退出规则。没有目标的序列会继续打扰已经完成了它所要求之事的人。

## 会话提醒：由一个事件开始，由另一个事件取消 \\

如果有人开始了打扫会话却一直没有完成，他们的工作就不会被记录。这个 Journey 在 `cleaning_session_started` 时开始，等待三小时后发送提醒。它的退出规则是 `cleaning_session_completed`，因此完成会话就会取消提醒。

| 步骤 | 设置 |
| - | - |
| 进入 | 自定义事件 `cleaning_session_started` |
| 等待 | 3 小时 |
| 时间窗口 | 08:00 到 21:00，成员所在时区 |
| 推送 | "What happened? It looks like you started a cleaning session and didn't finish it." |
| 退出 | 自定义事件 `cleaning_session_completed` |

这种开始与取消的组合是最简单且实用的 Journey。同样的结构也适用于被放弃的购物车、未填完的注册表单或从未发送的草稿。

> [!NOTE]
>
> **检查时间窗口的边界。** 窗口最初在 18:00 关闭。16:00 开始的会话会在 19:00 等待结束，发现窗口已关闭，于是在第二天早上 08:00 收到 "you didn't finish"。现在窗口在 21:00 关闭。当一条消息只在当天才有意义时，请检查刚好在窗口关闭后到达的人会遇到什么情况。

## 会话完成：根据事件进行个性化 \\

会话结束时，打扫者会收到一条写明房间的简短确认。房间不是标签，而是来自启动 Journey 的事件。

```text Push template: Cleaning Session Completed theme={null}
{{ journey.first_event.properties.room_name }} cleaned ✅

Great work cleaning the {{ journey.first_event.properties.room_name }} {{ user_name | default: 'cleaner' }}! Keep up the hard work!
```

`journey.first_event.properties` 读取进入事件的属性。单独的 `user_name` 读取标签，`default` 过滤器覆盖缺少该标签的人。

这个 Journey 只有一个步骤。它本可以由后端发送，就像[从后端发送推送](https://documentation.onesignal.com/docs/cn/example-full-integration-backend-push.md#session-completed-a-push-triggered-from-the-app)中告知室友同一会话的推送那样。之所以用 Journey，是因为这样可以在仪表板中更改、测试或关闭文案。

> [!WARNING]
>
> Event Stream 报告的 Journey 消息是其原始写法，其中仍包含 Liquid。在 Webhook 学会渲染它之前，Clean Beans 收件箱一直显示 `{{ journey.first_event.properties.room_name }} cleaned`。请参阅[存储前先渲染 Liquid](https://documentation.onesignal.com/docs/cn/example-full-integration-inbox.md#render-liquid-before-you-store-it)。

## 按房间推广：根据事件属性分支 \\

这个 Journey 会根据打扫的房间发送不同的消息。它展示了两点：让人们等待直到某个事件发生，以及根据该事件的属性进行分支。

成员从过去七天内活跃的人组成的细分进入。第一步是带三个分支的 **Wait Until**。每个分支等待带有特定 `room_name` 的 `cleaning_session_completed`。

| 分支条件 | 接下来 |
| - | - |
| `room_name` 为 `Kitchen` | 等待 2 小时，时间窗口 08:00 到 20:00，厨房推送 |
| `room_name` 为 `Bathroom` | 等待 2 小时，时间窗口 08:00 到 20:00，浴室推送 |
| `room_name` 为 `Bedroom` | 等待 2 小时，时间窗口 08:00 到 20:00，卧室推送 |

其他房间的会话不匹配任何分支，成员会继续等待。30 分钟后允许重新进入，因此 Journey 会响应每一次新会话。

> [!NOTE]
>
> 这个 Journey 中的推送宣传的是虚构的清洁产品，只用于展示这种模式。它们也是应用通知设置未覆盖的营销消息，在真实应用中需要为此做好设计。请参阅 [Journeys 看不到的内容](#what-journeys-cannot-see)。

## 连续记录里程碑：带数字的事件 \\

由应用判断连续记录何时达到里程碑，因为它刚刚保存了新的连续记录。它会发送带有天数的 `streak_milestone`，其余工作由 Journey 完成。

```text Push template: Streak - Milestone reached theme={null}
🔥 {{ journey.first_event.properties.streak_count }}-day streak!

Nice work, {{ user_name | default: 'you' }}. That's {{ journey.first_event.properties.streak_count }} days in a row. Keep it going tomorrow.
```

| 步骤 | 设置 |
| - | - |
| 进入 | 自定义事件 `streak_milestone` |
| 等待 | 1 分钟 |
| 推送 | 上面的模板 |

> [!NOTE]
>
> **两个 Journeys，同一时刻。** 里程碑总是在会话结束时出现，而这也是会话完成 Journey 发送推送的时刻。如果没有一分钟的等待，两条推送会同时到达。当多个 Journeys 由同一个用户操作启动时，请把它们放在一起检查。

## 连续记录即将中断：时机、细分检查和多样化文案 \\

任何一天没有会话，连续记录都会在午夜结束。这个 Journey 会在当晚提醒成员。它是七个 Journeys 中最复杂的一个，每个步骤都解决一个不同的问题。

| 步骤 | 设置 | 原因 |
| - | - | - |
| 进入 | 自定义事件 `cleaning_session_completed` | 每次会话都会开始新的倒计时 |
| 等待 | 22 小时 | 见下文 |
| 时间窗口 | 18:00 到 22:00，成员所在时区 | 会话后第二天的晚上 |
| Yes/No 分支 | 在细分 "Streak 2+ Days, Reminders On" 中 | 只针对有连续记录且希望收到提醒的人 |
| Split，5 个各占 20% 的分支 | 五个推送模板之一 | 每晚的措辞都不同 |
| 退出 | 自定义事件 `cleaning_session_completed` | 他们又打扫了，警告已不再成立 |

**落在正确的晚上。** 无论最后一次会话在几点，警告都应在其后的那个晚上发送。等待 22 小时再接 18:00 到 22:00 的窗口，总能落在那里。08:00 的会话会在第二天 06:00 到达窗口步骤，并一直等待到 18:00。23:00 的会话会在第二天 21:00 到达，并立即发送。

**遵守 Journey 看不到的设置。** Clean Beans 的通知设置中有一个 "Streak reminders" 开关，存储在数据库中。应用将其镜像为标签。

```typescript src/lib/onesignalSync.ts theme={null}
// Mirrors the "Streak reminders" setting, so a Journey can respect it.
// Journeys cannot read the app's database, only tags.
streak_reminders:
  profile.notifications_enabled !== false && profile.push_streak_reminders !== false ? 'on' : 'off',
```

该细分要求 `streak_count` 大于 1 且 `streak_reminders` 等于 `on`。使用旧版本的成员根本没有 `streak_reminders` 标签，因此不在该细分中，也不会收到警告。

**变换文案。** 每晚都是同一句话，很容易被忽视。**Split** 步骤会随机把每个人分配到五个分支之一，每个分支都有自己的模板。每次有人进入时都会重新选择分支，因此成员在不同的晚上会看到不同的措辞。

| 分支 | 标题 |
| - | - |
| A | Your streak ends at midnight |
| B | Don't let your streak slip away |
| C | Still time to clean today |
| D | One task saves your streak |
| E | Midnight is coming for your streak ⏰ |

> [!NOTE]
>
> Clean Beans 还会以 Live Activity 的形式显示连续记录警告，详见 [Live Activities](https://documentation.onesignal.com/docs/cn/example-full-integration-live-activities.md)。开启了 Live Activities 的成员会同时收到两者。推送覆盖 Android 用户以及关闭了 Live Activities 的用户。

## 重新参与和 Journey Webhook \\

最后一个 Journey 处理不再打开应用的成员。它是唯一仅从细分进入的 Journey，也是唯一调用后端的 Journey。

| 步骤 | 时间 | 消息 |
| - | - | - |
| 进入 | 成员加入 "Inactive 7+ Days" 细分 | 仅新进入者 |
| 推送 1 | 下一个 10:00 到 19:00 窗口 | "It's been a while" |
| 推送 2 | 2 天后 | 每周排行榜 |
| 邮件 | 3 天后 | "We saved your spot" |
| 推送 3 | 3 天后 | "A fresh start" |
| Webhook | 2 天后 | 告诉后端该成员已流失 |
| 退出 | 自定义事件 `cleaning_session_completed` | 他们回来了 |

30 天后允许重新进入。进入仅限于在 Journey 启动后加入该细分的人。否则，在开启当天已经不活跃的所有人都会立即收到第一条推送。

### 在序列结束时通知您的后端 \\

走到最后仍未打扫的成员已经没有回应四条消息，第五条也不太可能有用。Clean Beans 改为通知家庭。一个 **Webhook** 步骤会调用后端函数，该函数将成员标记为不活跃，并通知家庭的所有者和管理员。

**仪表板设置。** 使用以下设置创建一个 Journey Webhook，并在 Journey 的最后一步中选择它。

```json Journey webhook theme={null}
{
  "method": "POST",
  "url": "https://YOUR_PROJECT_REF.supabase.co/functions/v1/journey-webhook",
  "headers": {
    "Content-Type": "application/json",
    "X-Webhook-Secret": "YOUR_SHARED_SECRET"
  },
  "body": {
    "event": "member_lapsed",
    "external_id": "{{ user.external_id }}"
  }
}
```

该函数首先检查密钥。由于 OneSignal 不会发送 Supabase 令牌，该函数部署时没有启用 Supabase 的令牌检查，因此共享密钥是该端点与公共互联网之间唯一的屏障。

```typescript supabase/functions/journey-webhook/index.ts theme={null}
const secret = req.headers.get('X-Webhook-Secret') ?? '';
if (!JOURNEY_WEBHOOK_SECRET || secret !== JOURNEY_WEBHOOK_SECRET) {
  return new Response('Unauthorized', { status: 401 });
}
```

然后它会自行核实这一说法。Journey 说该成员不活跃，但 Journey 只知道应用会话和事件。数据库才知道他们是否打扫过。

```typescript supabase/functions/journey-webhook/index.ts theme={null}
const since = new Date(Date.now() - RECENT_ACTIVITY_DAYS * 24 * 60 * 60 * 1000).toISOString();
const { count: recentSessions } = await supabase
  .from('cleaning_sessions')
  .select('id', { count: 'exact', head: true })
  .eq('user_id', userId)
  .gte('completed_at', since);

if ((recentSessions ?? 0) > 0) {
  return jsonResponse({ skipped: true, reason: 'recently_active' });
}

// Already flagged: a retried or repeated webhook does nothing more
if (profile.lapsed_at) {
  return jsonResponse({ skipped: true, reason: 'already_lapsed' });
}
```

只有这时，它才会标记该成员，并向能够采取行动的人发送一条推送。

```typescript supabase/functions/journey-webhook/index.ts theme={null}
const onesignalPayload: Record<string, unknown> = {
  app_id: ONESIGNAL_APP_ID,
  include_aliases: { external_id: recipientIds },
  target_channel: 'push',
  ...DELIVERY.member_lapsed,
  headings: { en: `${memberName} has gone quiet` },
  contents: { en: `${memberName} hasn't cleaned in a while. A friendly nudge might help.` },
  url: 'cleaning-rota:///household',
  data: { type: 'member_lapsed', memberId: userId, memberName },
};
```

该标记会自动清除。成员下次完成会话时，数据库触发器会将其移除，因此应用无需记得去做这件事。

> [!TIP]
>
> Webhook 步骤可以完成消息步骤做不到的任何事：更新记录、创建支持工单、把某人添加到另一个系统的列表中。像对待任何其他外部调用一样对待该请求。检查密钥、核实事实，并让重复请求无害。

## Journeys 看不到的内容 \\

本指南中后端的每次发送都会在发送前检查成员的通知设置。Journey 无法做到这一点，因为这些设置存储在应用的数据库中。

| Journey 需要知道 | Clean Beans 如何告诉它 |
| - | - |
| 刚刚发生了某件事 | 自定义事件 |
| 关于这个人的某个事实 | 标签 |
| 一组人 | 由标签或活动构建的细分 |
| 是否应该停止 | 基于自定义事件的退出规则 |
| 存储在您数据库中的设置 | 镜像该设置的标签，以及要求该标签的细分 |

只有连续记录警告有镜像的设置。其他 Journey 推送会发给所有为该应用开启推送通知的人。如果您的应用有按类型划分的通知设置，请镜像每个 Journey 应遵守的设置。

## 注意事项 \\

* **留意共享受众的 Journeys。** Clean Beans 曾短暂有两个重新参与 Journeys 同时在同一个细分上运行，导致每位不活跃成员都排进了两个序列。在一个细分上开启第二个 Journey 很容易，却很难察觉。
* **为 Journey 推送设置 URL 和 `data.type`。** 在仪表板中创建的模板默认两者都没有，因此点击只会打开应用。Clean Beans 在每个 Journey 模板上都设置了这两项，使它们像后端推送一样路由。请参阅[深度链接和通知点击](https://documentation.onesignal.com/docs/cn/example-full-integration-deep-links.md)。
* **活跃的 Journey 可以编辑，而编辑可能影响已经在其中的人。** Clean Beans 曾在运行中的 Journeys 上更改时间窗口并添加等待。请审慎进行此类更改。
* **Journey 消息会计入收件箱。** 它们与其他推送通过同一个 Event Stream 到达，其中的 Liquid 未被渲染。
* **对按钮为 Universal Link 的邮件关闭点击跟踪。** 跟踪会改写链接，使其经过跟踪域名，而被改写的链接将无法再打开应用。请参阅[通过普通网页链接打开应用](https://documentation.onesignal.com/docs/cn/example-full-integration-deep-links.md#open-the-app-from-ordinary-web-links)。

> [card] [Journeys 概览](https://documentation.onesignal.com/docs/cn/journeys-overview.md)
>
> 进入规则、步骤以及 Journey 的运行方式。

> [card] [Journey 设置](https://documentation.onesignal.com/docs/cn/journeys-settings.md)
>
> 谁进入、退出和重新进入。

> [card] [Journey 操作](https://documentation.onesignal.com/docs/cn/journeys-actions.md)
>
> Wait、Wait Until、Yes/No、Split 和 Time Window。

> [card] [Journey Webhook](https://documentation.onesignal.com/docs/cn/journeys-webhook.md)
>
> 从 Journey 步骤调用您自己的服务器。

> [card] [使用自定义事件进行个性化](https://documentation.onesignal.com/docs/cn/personalization-custom-event.md)
>
> 在 Journey 消息中使用事件属性。

> [card] [事件驱动的 Journeys](https://documentation.onesignal.com/docs/en/event-driven-journeys.md)
>
> 设计响应用户行为的 Journeys。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.