> ## 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 的比较。

本页面是[示例应用：完整的 OneSignal 集成](https://documentation.onesignal.com/docs/cn/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)

每周报告：家庭总计、您自己的一周和排行榜。

有意思的问题在于个性化。家庭中的每个人看到的是同一个排行榜，但每个人都应该看到自己的名字和数据。为每个人发送一个请求也可以，但有更好的办法。

## 每个家庭一个请求，按人个性化 \\

函数为每个家庭只发送**一个**请求。它通过 `custom_data` 传递所有数据，其中包括一个以 External ID 为键的 `users` 对象。模板随后会为当前渲染的收件人挑选出对应的条目。

```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,
};
```

在模板中，一行 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]
>
> 第二个 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 \\

还有第二种方式可以把按人区分的数据放进邮件，Clean Beans 选择了不使用它。这种方式值得了解，因为对于某些应用来说它更合适。

使用 `custom_data` 时，后端在发送时把数据**推送**给 OneSignal。使用 **Data Feed** 时，OneSignal 会在发送每封邮件的那一刻从您的 API **拉取**数据。发送本身由 Journey 而不是后端发起。

> [!NOTE]
>
> 本小节中的示例仅用于说明。它们展示了如果用 Data Feed 构建每周报告会是什么样子，并非取自该应用。

以下是每周报告在这种方式下的工作过程。

**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** 中为该 feed 设置别名，并将其指向该端点。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. 将 feed 关联到邮件模板并从中读取**

在模板中，值来自 `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 |
| 何时读取数据 | 后端构建请求时 | 每条消息发送时 |
| 四口之家需要的请求数 | 向 OneSignal 发送一个请求 | OneSignal 调用您的 API 四次 |
| 渠道 | 推送、邮件和短信 | 邮件和短信，仅限 Journeys 内 |
| 大小限制 | 邮件 10 KB | 建议响应不超过约 50 KB |
| 数据缺失时 | 由您的代码决定如何处理 | 该收件人收不到消息 |
| 更改计划或流程 | 修改后端 | 在仪表板中修改 |
| API 暴露情况 | 不暴露任何内容 | 一个需要保护并保持快速响应的公共端点 |

**当后端已经是决定发送的一方时，选择 `custom_data`。** 每周报告正是这种情况。后端按计划运行，知道哪些家庭选择了接收，手上也有所有数据，因此顺带传递数据没有额外成本。一个请求就能覆盖整个家庭，没有需要保护的端点，失败也会显示在您自己的日志中。代价是时机和受众写在代码里，而且负载有固定的大小限制。

**当发送属于某个 Journey 时，选择 Data Feed。** Journey 会自行决定何时给某人发消息，例如在某个事件发生几天后或满足等待条件时，而此时后端并不在场提供数据。Data Feed 弥补了这一空缺，也让负责消息的团队无需部署即可更改计划、添加分支或测试变体。代价是每个收件人都会调用一次您的 API，响应时间应在约四分之一秒内，每个模板只能使用一个 feed，并且调用失败意味着此人什么也收不到，也不会有任何提示。

对 Clean Beans 来说，决定因素很简单。后端已经拥有数据和计划，排行榜由整个家庭共享，因此一个请求远比每人一次调用便宜，而且偏好存储在应用的数据库中，后端可以直接检查。

> [card] [使用 custom\_data 进行个性化](https://documentation.onesignal.com/docs/cn/personalization-api-custom-data.md)
>
> 大小限制和 Liquid 访问方式。

> [card] [Data feeds](https://documentation.onesignal.com/docs/cn/data-feeds.md)
>
> 将实时数据引入 Journey 邮件和短信。

> [card] [使用 Liquid 语法](https://documentation.onesignal.com/docs/cn/using-liquid-syntax.md)
>
> 过滤器、循环和条件。


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