> ## 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/ko/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)

주간 보고서: 가구 합계, 나의 한 주, 순위표.

흥미로운 과제는 개인화입니다. 가구의 모든 사람이 같은 순위표를 보지만, 각자 자신의 이름과 통계를 봐야 합니다. 사람마다 요청을 하나씩 보내도 되지만 더 좋은 방법이 있습니다.

## 가구당 요청 하나, 사람마다 개인화 \\

함수는 가구마다 요청을 **하나**만 보냅니다. 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,
};
```

템플릿에서는 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**에서 피드에 별칭을 지정하고 엔드포인트를 가리키게 하세요. 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`를 선택하세요.** 주간 보고서가 그런 경우입니다. 백엔드는 일정에 따라 실행되고, 어떤 가구가 동의했는지 알고, 모든 수치를 가지고 있으므로 데이터를 넘기는 데 추가 비용이 들지 않습니다. 요청 하나로 가구 전체를 처리하고, 보호할 엔드포인트가 없으며, 실패는 자체 로그에 나타납니다. 대신 시점과 대상이 코드에 있고, 페이로드에는 고정된 크기 제한이 있습니다.

**전송이 Journey에 속한다면 Data Feed를 선택하세요.** Journey는 이벤트 며칠 후나 대기 조건이 충족된 때처럼 메시지를 보낼 시점을 스스로 결정하며, 그 순간 백엔드가 데이터를 제공할 수 없습니다. Data Feed는 이 빈틈을 메우고, 메시징 담당자가 배포 없이 일정을 바꾸거나 분기를 추가하거나 변형을 테스트할 수 있게 해줍니다. 대신 API가 수신자마다 한 번씩 호출되어 약 0.25초 안에 응답해야 하고, 템플릿마다 피드를 하나만 사용할 수 있으며, 호출이 실패하면 그 사람은 아무것도 받지 못하고 알림도 없습니다.

Clean Beans의 결정 요인은 간단했습니다. 백엔드에 이미 데이터와 일정이 있었고, 순위표는 가구가 공유하므로 사람마다 호출하는 것보다 요청 하나가 훨씬 저렴했으며, 설정은 앱의 데이터베이스에 저장되어 백엔드가 직접 확인할 수 있었습니다.

> [card] [custom\_data로 개인화하기](https://documentation.onesignal.com/docs/ko/personalization-api-custom-data.md)
>
> 크기 제한과 Liquid 접근 패턴.

> [card] [Data feeds](https://documentation.onesignal.com/docs/ko/data-feeds.md)
>
> Journey 이메일과 SMS에 실시간 데이터 가져오기.

> [card] [Liquid 구문 사용하기](https://documentation.onesignal.com/docs/ko/using-liquid-syntax.md)
>
> 필터, 반복문, 조건문.


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