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

# サンプルアプリ：custom_dataを使った週次メール

> サンプルアプリClean Beansがcustom_dataとLiquidで受信者ごとにパーソナライズした週次レポートメールを送信する方法と、Data Feedsとの比較。

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

毎週日曜日、各世帯にその週のまとめメールが届きます。セッション数、タスク数、掃除時間、ランキング、そして各メンバー自身の数字です。

![Clean Beansの週次レポートメール](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-email.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=386b96883e6b7af79d0406d4095f73c7)

週次レポート：世帯の合計、あなた自身の1週間、ランキング。

興味深い課題はパーソナライズです。世帯の全員が同じランキングを見ますが、各自には自分の名前と統計が表示される必要があります。1人ずつリクエストを送っても実現できますが、もっと良い方法があります。

## 世帯ごとに1回のリクエストで、1人ずつパーソナライズする \\

関数は世帯ごとに**1回**だけリクエストを送ります。External IDをキーにした`users`オブジェクトを含め、すべてのデータを`custom_data`で渡します。テンプレートは、表示対象の人に合ったエントリを選び出します。

```typescript supabase/functions/weekly-report/index.ts theme={null}
const customData = {
  household_name: householdNames[householdId] || 'Your Household',
  week_label: weekLabel,
  household_sessions: String(householdSessions.length),
  household_tasks: String(totalTasks),
  household_mins: String(totalMins),
  top_room: topRoom,
  leaderboard,
  users,
};

    // ...

const onesignalPayload: Record<string, unknown> = {
  app_id: ONESIGNAL_APP_ID,
  template_id: ONESIGNAL_WEEKLY_TEMPLATE_ID,
  include_aliases: {
    external_id: externalIds,
  },
  target_channel: 'email',
  custom_data: customData,
};
```

テンプレートでは、1行のLiquidで現在の受信者のデータを選択します。

```liquid email-templates/weekly-report.html theme={null}
{% assign user = message.custom_data.users[subscription.external_id] %}
{% assign lb = message.custom_data.leaderboard %}
```

以降、`user`にはその人の統計が入り、`message.custom_data`から直接読み取るものは世帯で共通になります。

```liquid email-templates/weekly-report.html theme={null}
Hey {{ user.name | default: "there" }}! 👋
Here's how <strong>{{ message.custom_data.household_name | default: "your household" }}</strong> did this week.

{% for member in lb %}
  {% if forloop.index == 1 %}🥇{% elsif forloop.index == 2 %}🥈{% elsif forloop.index == 3 %}🥉{% else %}{{ forloop.index }}{% endif %}
  {{ member.name }}{% if member.name == user.name %} (you){% endif %}
{% endfor %}
```

> [!NOTE]
>
> 2つ目のLiquidの例は、テーブルのマークアップを省いてロジックだけを示すため、テンプレートを簡略化したものです。

## サイズの上限内に収める \\

メールの`custom_data`の上限は10 KBです。大きな世帯では超える可能性があるため、関数はペイロードのサイズを測り、必要に応じてランキングを削ります。

```typescript supabase/functions/weekly-report/index.ts theme={null}
// Check payload size (10KB limit for email)
const payloadSize = new TextEncoder().encode(JSON.stringify(customData)).length;
if (payloadSize > 10000) {
  console.warn(`Household ${householdId} custom_data is ${payloadSize} bytes (over 10KB limit). Trimming leaderboard.`);
  customData.leaderboard = customData.leaderboard.slice(0, 5);
}
```

## スケジュールと設定 \\

毎週のスケジュールが、毎週日曜日の09:00 UTCに関数を呼び出します。プッシュのリマインダーと同じ`pg_cron`のパターンで、式は`0 9 * * 0`です。**Weekly Email Summary**をオンにしているユーザーだけが対象になります。

**ダッシュボードの設定。** **Messages > Templates**でメールテンプレートを作成し、HTMLを貼り付け、テンプレートIDをバックエンドのシークレットにコピーします。`custom_data`はテンプレートでのみ機能するため、`template_id`は必須です。

## 代替手段：Data Feeds \\

人ごとのデータをメールに入れる方法はもう1つあり、Clean Beansはそれを使わないことにしました。アプリによってはこちらのほうが適しているため、理解しておく価値があります。

`custom_data`では、送信時にバックエンドがデータをOneSignalに**プッシュ**します。**Data Feed**では、各メールが送信される時点でOneSignalがAPIからデータを**プル**します。送信自体はバックエンドではなくJourneyが開始します。

> [!NOTE]
>
> この項の例は説明用です。Data Feedで週次レポートを作った場合の姿を示したもので、アプリから抜粋したものではありません。

週次レポートを作った場合は次のようになります。

**1. 1人分の1週間を返すエンドポイントを公開する**

バックエンド関数がユーザーIDを受け取り、そのユーザーの統計と世帯のランキングをJSONで返します。

```json Response from your API theme={null}
{
  "name": "George",
  "household_name": "The Smiths",
  "week_label": "Nov 10 – Nov 16",
  "sessions": 5,
  "tasks": 19,
  "mins": 63,
  "streak": 24,
  "leaderboard": [
    { "name": "George", "sessions": 5, "mins": 63 },
    { "name": "Jonny", "sessions": 4, "mins": 52 }
  ]
}
```

**2. ダッシュボードでData Feedを作成する**

**Settings > Data feeds**でフィードにエイリアスを付け、エンドポイントを指定します。URLとヘッダーではLiquidを使えるため、受信者のExternal IDを渡せます。

```text Data Feed configuration theme={null}
Alias:   weekly
Method:  GET
URL:     https://YOUR_PROJECT_REF.supabase.co/functions/v1/weekly-stats?user_id={{ external_id }}
Headers: { "Authorization": "Bearer YOUR_FEED_SECRET" }
```

**3. フィードをメールテンプレートに紐付けて読み取る**

テンプレートでは、値は`data_feed`の後にエイリアスを続けて取得します。

```liquid Email template theme={null}
Hey {{ data_feed.weekly.name | default: "there" }}!
Here's how {{ data_feed.weekly.household_name }} did this week.

{% for member in data_feed.weekly.leaderboard %}
  {{ member.name }}: {{ member.sessions }} sessions
{% endfor %}
```

**4. 繰り返し実行されるJourneyから送信する**

最初のステップに日曜朝の時間枠を置き、再エントリールールを設定したJourneyが、毎週テンプレートを送信します。スケジュールや送信のコードはバックエンドに一切ありません。

### どちらを使うか \\

| | `custom_data`（Clean Beansが使用） | Data Feeds |
| - | - | - |
| 送信を開始する主体 | バックエンドがAPIを呼び出す | ダッシュボードのJourney |
| データを読み取るタイミング | バックエンドがリクエストを組み立てるとき | 各メッセージが送信されるとき |
| 4人世帯の場合のリクエスト数 | OneSignalへ1回 | OneSignalからAPIへ4回 |
| チャネル | プッシュ、メール、SMS | メールとSMS（Journey内のみ） |
| サイズの上限 | メールは10 KB | 約50 KBまでのレスポンスを推奨 |
| データがない場合 | コード側で対処を決める | その受信者にはメッセージが届かない |
| スケジュールやフローの変更 | バックエンドの変更 | ダッシュボードでの変更 |
| APIの公開範囲 | 何も公開しない | 保護し高速に保つ必要がある公開エンドポイント |

**バックエンドがすでに送信を決めている場合は`custom_data`を選びます。** 週次レポートがまさにそうです。バックエンドはスケジュールで動き、どの世帯がオプトインしているかを把握し、すべての数字を手元に持っているため、データを渡す追加コストはありません。1回のリクエストで世帯全体をカバーでき、保護すべきエンドポイントはなく、失敗は自分のログに表示されます。その代わり、タイミングとオーディエンスはコードで管理することになり、ペイロードには固定のサイズ上限があります。

**送信がJourneyに属する場合はData Feedを選びます。** Journeyは、イベントの数日後や待機条件を満たしたときなど、メッセージを送るタイミングを自ら判断します。その時点でバックエンドがデータを提供することはできません。Data Feedはこの隙間を埋め、メッセージングの担当者がデプロイなしでスケジュールの変更、分岐の追加、バリエーションのテストを行えるようにします。その代わり、APIは受信者ごとに1回呼び出され、約0.25秒以内に応答する必要があります。また、各テンプレートで使えるフィードは1つだけで、呼び出しに失敗するとその人には何も届かず、通知もされません。

Clean Beansの決め手はシンプルでした。バックエンドにはすでにデータとスケジュールがあり、ランキングは世帯で共有されるため1人ずつ呼び出すより1回のリクエストのほうがはるかに安く、設定はアプリのデータベースに保存されていてバックエンドが直接確認できるからです。

> [card] [custom\_dataでパーソナライズする](https://documentation.onesignal.com/docs/ja/personalization-api-custom-data.md)
>
> サイズの上限とLiquidでのアクセス方法。

> [card] [Data feeds](https://documentation.onesignal.com/docs/ja/data-feeds.md)
>
> JourneyのメールとSMSにライブデータを取り込む。

> [card] [Liquid構文の使い方](https://documentation.onesignal.com/docs/ja/using-liquid-syntax.md)
>
> フィルター、ループ、条件。


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