> ## 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 7種類：オンボーディング、連続記録、再エンゲージメント、プロモーション、バックエンドを呼び出すJourney Webhook。

このページは、1つの実在アプリを最初から最後まで追う[サンプルアプリ：OneSignalの完全な統合](https://documentation.onesignal.com/docs/ja/example-full-integration-overview.md)の一部です。アプリは**Clean Beans**という共同生活の家のための掃除当番表アプリで、Expo（React Native）とSupabaseバックエンドで構築されています。

このガイドのメッセージのほとんどは、バックエンドから1リクエストずつ送信されます。**Journey**はそれとは異なります。OneSignalダッシュボードで作成するシーケンスで、誰にいつメッセージを送り、次に何が起こるかを自ら判断します。Clean Beansは、数時間から数日にわたって進行するもの、そしてリリースなしで変更できるようにしたい文面やタイミングにJourneysを使っています。

Clean Beansでは7つのJourneyを運用しています。

| Journey | 開始タイミング | 内容 |
| - | - | - |
| [オンボーディング](#onboarding-a-sequence-with-a-goal) | アプリが`signed_up`を送信 | ウェルカムメールとアプリ内ウォークスルー、その後6日間で3回のプッシュ。最初の掃除セッションまで続く |
| [セッションリマインダー](#session-reminder-start-on-one-event-cancel-on-another) | アプリが`cleaning_session_started`を送信 | セッションが完了していなければ、3時間後にプッシュ |
| [セッション完了](#session-completed-personalize-from-the-event) | アプリが`cleaning_session_completed`を送信 | 掃除した人に、掃除したばかりの部屋の名前を入れたプッシュ |
| [部屋別プロモーション](#room-based-promos-branch-on-an-event-property) | 最近アクティブなメンバーがセッションを完了 | 2時間後に、キッチン、バスルーム、寝室ごとに異なるプッシュ |
| [連続記録マイルストーン](#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`を送信 | 翌日の夜に、5種類の文面のいずれかで警告プッシュ |
| [再エンゲージメント](#re-engagement-and-the-journey-webhook) | メンバーが7日間非アクティブ | 10日間でプッシュ、プッシュ、メール、プッシュ、その後バックエンドへWebhook |

最後のJourneyの最後にあるWebhookを除き、どのJourneyにも専用のバックエンドコードはありません。アプリの役割は、Journeysが扱える材料を渡すことです。

## アプリがJourneyに渡すもの \\

Journeyがある人について把握できるのは、送信した**カスタムイベント**、その人の**タグ**、所属する**セグメント**の3つです。データベースは読み取れません。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/ja/example-full-integration-tags-events.md)で説明しています。ほかの2つのイベントは、Journeyを開始するためだけに存在します。

`signed_up`はアカウントごとに1回だけ発生します。最初にアカウントの作成からの経過時間を確認するため、新しいスマートフォンにアプリをインストールした人が再びオンボーディングされることはありません。

```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]
>
> Journeyを開始するイベントは、`OneSignal.login()`を呼び出した後にのみ送信してください。ログイン前に送信したイベントは、これからサインインする人ではなく、匿名ユーザーに記録されます。Clean Beansは同じeffect内で`login()`の直後に`trackSignedUpOnce()`を呼び出しています。[SDKのセットアップとユーザーID](https://documentation.onesignal.com/docs/ja/example-full-integration-sdk-setup.md#tie-each-device-to-a-user)を参照してください。

## オンボーディング：目標のあるシーケンス \\

オンボーディングJourneyの目的は1つだけで、新しいメンバーに最初の掃除セッションを完了してもらうことです。それが起きた時点で、すべてが止まります。

**1. アプリがsigned\_upを送信する**

メンバーがJourneyに入ります。各メンバーが通過するのは1回だけです。

**2. ウェルカムメールとアプリ内ウォークスルーがすぐに送られる**

メールには、始めるための3つのステップが記載されています。アプリ内メッセージは、メンバーが次にアプリを開いたときに表示されます。

**3. 1日目、3日目、6日目に3回のプッシュが続く**

それぞれ、メンバー自身のタイムゾーンで10:00から19:00の時間枠を待ちます。

**4. セッションが完了すると終了する**

Journeyの終了ルールは`cleaning_session_completed`イベントです。すでにやったことを促されることはありません。

| ステップ | タイミング | メッセージ |
| - | - | - |
| メール | すぐに | "Welcome to Clean Beans"、始めるための3つのステップ付き |
| アプリ内メッセージ | 次回アプリを開いたとき（最大3日間） | ウェルカムウォークスルー |
| プッシュ1 | 1日目 | "Ready for your first clean?" |
| プッシュ2 | 3日目 | "Cleaning is easier shared"（Household画面を開く） |
| プッシュ3 | 6日目 | "Your rota is waiting" |

**ダッシュボードでの設定。** 開始ルールに**Custom Event**、イベントに`signed_up`を指定してJourneyを作成します。終了ルールでは、カスタムイベントが発生したときに終了するよう選択し、`cleaning_session_completed`を指定します。各プッシュの前に**Time Window**ステップを置き、03:00に終わる待機が03:00に送信しないようにします。

> [!TIP]
>
> まず目標を決め、それを終了ルールにしてください。目標のないシーケンスは、求めたことをすでに済ませた人にも話しかけ続けます。

## セッションリマインダー：あるイベントで開始し、別のイベントでキャンセルする \\

掃除セッションを始めたまま終えないと、その作業は記録されません。このJourneyは`cleaning_session_started`で開始し、3時間待ってからリマインダーを送ります。終了ルールは`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は1ステップだけです。[バックエンドからプッシュを送信する](https://documentation.onesignal.com/docs/ja/example-full-integration-backend-push.md#session-completed-a-push-triggered-from-the-app)で同じセッションを同居人に知らせるプッシュのように、バックエンドから送ることもできました。Journeyにしているのは、ダッシュボードで文面を変更、テスト、停止できるようにするためです。

> [!WARNING]
>
> Event Streamは、Journeyのメッセージを書かれたまま、Liquidを含んだ状態で報告します。Clean Beansの受信箱では、Webhookが展開できるようになるまで`{{ journey.first_event.properties.room_name }} cleaned`と表示されていました。[保存する前にLiquidを展開する](https://documentation.onesignal.com/docs/ja/example-full-integration-inbox.md#render-liquid-before-you-store-it)を参照してください。

## 部屋別プロモーション：イベントプロパティで分岐する \\

このJourneyは、掃除した部屋に応じて異なるメッセージを送ります。ここでは2つのことを示しています。イベントが起きるまで人を待たせること、そしてそのイベントのプロパティで分岐することです。

メンバーは、過去7日間にアクティブだった人のセグメントから入ります。最初のステップは3つのブランチを持つ**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]
>
> **2つのJourney、同じ瞬間。** マイルストーンは必ずセッションの終わりに発生し、これはセッション完了Journeyが送信するタイミングでもあります。1分の待機がなければ、2つのプッシュが同時に届きます。複数のJourneyが同じユーザー操作から始まる場合は、並べて確認してください。

## 連続記録途切れ間近：タイミング、セグメントの確認、文面の変化 \\

セッションのない日は、その日の深夜0時に連続記録が途切れます。このJourneyは、その日の夜にメンバーに警告します。7つの中で最も複雑で、各ステップがそれぞれ別の問題を解決しています。

| ステップ | 設定 | 理由 |
| - | - | - |
| 開始 | カスタムイベント`cleaning_session_completed` | セッションのたびに新しいカウントダウンが始まる |
| 待機 | 22時間 | 下記参照 |
| 時間枠 | 18:00から22:00、メンバーのタイムゾーン | セッションの翌日の夜 |
| Yes/Noブランチ | セグメント"Streak 2+ Days, Reminders On"に含まれる | 連続記録があり、リマインダーを希望する人だけ |
| Split、20%ずつの5ブランチ | 5つのプッシュテンプレートのいずれか | 夜ごとに文面が変わる |
| 終了 | カスタムイベント`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**ステップは、各人を5つのブランチのいずれかにランダムに振り分け、各ブランチには独自のテンプレートがあります。ブランチは入場のたびに選び直されるため、メンバーは夜ごとに異なる文面を目にします。

| ブランチ | タイトル |
| - | - |
| 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 Activities](https://documentation.onesignal.com/docs/ja/example-full-integration-live-activities.md)で説明しているLive Activityとしても連続記録の警告を表示します。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の開始後にセグメントに加わった人に限定されています。この制限がないと、Journeyをオンにした日にすでに非アクティブだった全員に、すぐ最初のプッシュが送られます。

### シーケンスが終わったらバックエンドに知らせる \\

掃除しないまま最後まで到達したメンバーは、4通のメッセージに反応していません。5通目が役立つ可能性は低いでしょう。代わりに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' });
}
```

そのうえで初めて、メンバーをマークし、対応できる人たちに1回だけプッシュを送ります。

```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が尊重すべき設定をそれぞれ反映してください。

## 知っておくべきこと \\

* **オーディエンスが重複するJourneyに注意してください。** Clean Beansでは一時期、同じセグメントに対して2つの再エンゲージメントJourneyが稼働しており、非アクティブなメンバー全員が両方のシーケンスの対象になっていました。セグメントに2つ目のJourneyをオンにするのは簡単ですが、気付くのは困難です。
* **JourneyのプッシュにはURLと`data.type`を設定してください。** ダッシュボードで作成したテンプレートには、どちらもデフォルトでは設定されていないため、タップしてもアプリが開くだけです。Clean BeansはすべてのJourneyテンプレートに両方を設定し、バックエンドのプッシュと同じように振り分けられるようにしています。[ディープリンクと通知のクリック](https://documentation.onesignal.com/docs/ja/example-full-integration-deep-links.md)を参照してください。
* **稼働中のJourneyは編集でき、その編集はすでに参加している人に影響する可能性があります。** Clean Beansは、稼働中のJourneyで時間枠を変更し、待機を追加しました。このような変更は慎重に行ってください。
* **Journeyのメッセージも受信箱に入ります。** ほかのプッシュと同じEvent Streamを通じて、Liquidが展開されていない状態で届きます。
* **ボタンがUniversal Linkのメールでは、クリックトラッキングをオフにしてください。** トラッキングはリンクをトラッキングドメイン経由に書き換えるため、書き換えられたリンクではアプリが開かなくなります。[通常のWebリンクからアプリを開く](https://documentation.onesignal.com/docs/ja/example-full-integration-deep-links.md#open-the-app-from-ordinary-web-links)を参照してください。

> [card] [Journeysの概要](https://documentation.onesignal.com/docs/ja/journeys-overview.md)
>
> 開始ルール、ステップ、Journeyの実行の仕組み。

> [card] [Journeyの設定](https://documentation.onesignal.com/docs/ja/journeys-settings.md)
>
> 誰が入り、終了し、再入場するか。

> [card] [Journeyのアクション](https://documentation.onesignal.com/docs/ja/journeys-actions.md)
>
> Wait、Wait Until、Yes/No、Split、Time Window。

> [card] [Journey Webhook](https://documentation.onesignal.com/docs/ja/journeys-webhook.md)
>
> Journeyのステップから自分のサーバーを呼び出します。

> [card] [カスタムイベントでパーソナライズする](https://documentation.onesignal.com/docs/ja/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.