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

# Aplicativo de exemplo: email semanal com custom_data

> Como o aplicativo de exemplo Clean Beans envia um relatório semanal por email personalizado para cada destinatário com custom_data e Liquid, e como isso se compara aos Data Feeds.

Esta página faz parte de [Aplicativo de exemplo: uma integração completa do OneSignal](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-overview.md), que acompanha um aplicativo real do início ao fim. O aplicativo é o **Clean Beans**, uma escala de limpeza para casas compartilhadas, construído com Expo (React Native) e um backend Supabase.

Todo domingo, cada casa recebe um email com o resumo da semana: sessões, tarefas, minutos, um ranking e os números de cada pessoa.

![O email do relatório semanal do Clean Beans](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-email.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=386b96883e6b7af79d0406d4095f73c7)

O relatório semanal: totais da casa, sua própria semana e o ranking.

O problema interessante é a personalização. Todos de uma casa veem o mesmo ranking, mas cada pessoa deve ver o próprio nome e as próprias estatísticas. Enviar uma solicitação por pessoa funcionaria, mas há uma forma melhor.

## Uma solicitação por casa, personalizada por pessoa \\

A função envia **uma** solicitação por casa. Ela passa todos os dados em `custom_data`, incluindo um objeto `users` indexado pelo External ID. O template então escolhe a entrada certa para a pessoa para quem está sendo renderizado.

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

No template, uma linha de Liquid seleciona os dados do destinatário atual.

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

A partir daí, `user` contém as estatísticas dessa pessoa, e tudo o que é lido diretamente de `message.custom_data` é compartilhado pela casa.

```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]
>
> O segundo exemplo de Liquid foi simplificado a partir do template para mostrar a lógica sem a marcação da tabela.

## Ficar dentro do limite de tamanho \\

O `custom_data` para email é limitado a 10 KB. Uma casa grande poderia ultrapassar isso, então a função mede o payload e reduz o ranking se necessário.

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

## Agendamento e preferências \\

Um agendamento semanal chama a função todo domingo às 09:00 UTC, usando o mesmo padrão de `pg_cron` dos lembretes push, com a expressão `0 9 * * 0`. Só são incluídos os usuários com **Weekly Email Summary** ativado.

**Configuração do painel.** Em **Messages > Templates**, crie um template de email, cole o HTML e copie o ID do template para os segredos do seu backend. O `custom_data` só funciona com um template, então `template_id` é obrigatório.

## A alternativa: Data Feeds \\

Há uma segunda forma de colocar dados por pessoa em um email, e o Clean Beans optou por não usá-la. Vale a pena entendê-la, porque para alguns aplicativos ela é a melhor opção.

Com `custom_data`, seu backend **envia** os dados ao OneSignal no momento do envio. Com um **Data Feed**, o OneSignal **busca** os dados na sua API no momento em que cada email é enviado. O envio em si é iniciado por uma Journey, não pelo seu backend.

> [!NOTE]
>
> Os exemplos desta subseção são ilustrativos. Eles mostram como o relatório semanal teria sido criado com um Data Feed. Não foram retirados do aplicativo.

Veja como o relatório semanal teria funcionado.

**1. Expor um endpoint que retorna a semana de uma pessoa**

Uma função de backend recebe um ID de usuário e retorna em JSON as estatísticas desse usuário e o ranking da casa dele.

```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. Criar o Data Feed no painel**

Em **Settings > Data feeds**, dê um alias ao feed e aponte-o para o endpoint. A URL e os cabeçalhos aceitam Liquid, então o External ID do destinatário pode ser passado.

```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. Anexar o feed ao template de email e ler a partir dele**

No template, os valores vêm de `data_feed`, seguido do alias.

```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. Enviar a partir de uma Journey recorrente**

Uma Journey com uma janela de horário no domingo de manhã como primeira etapa, e uma regra de reentrada, envia o template toda semana. Nenhum código de agendamento ou envio fica no seu backend.

### Qual usar \\

| | `custom_data` (o que o Clean Beans usa) | Data Feeds |
| - | - | - |
| Quem inicia o envio | Seu backend, chamando a API | Uma Journey no painel |
| Quando os dados são lidos | Quando seu backend monta a solicitação | Quando cada mensagem é enviada |
| Solicitações para uma casa de quatro pessoas | Uma solicitação ao OneSignal | Quatro chamadas do OneSignal à sua API |
| Canais | Push, email e SMS | Email e SMS, somente dentro de Journeys |
| Limite de tamanho | 10 KB para email | Respostas de até cerca de 50 KB são recomendadas |
| Se os dados estiverem faltando | Seu código decide o que fazer | Esse destinatário não recebe mensagem |
| Mudar o agendamento ou o fluxo | Uma mudança no backend | Uma mudança no painel |
| Exposição da sua API | Nada é exposto | Um endpoint público que você precisa proteger e manter rápido |

**Escolha `custom_data` quando seu backend já é quem decide enviar.** Esse é o caso do relatório semanal. O backend roda em um agendamento, sabe quais casas deram opt-in e tem todos os números em mãos, então passar os dados não custa nada a mais. Uma solicitação cobre uma casa inteira, não há endpoint a proteger e uma falha aparece nos seus próprios logs. O preço é que o momento e o público ficam no código, e o payload tem um limite de tamanho fixo.

**Escolha um Data Feed quando o envio pertence a uma Journey.** Uma Journey decide sozinha quando enviar uma mensagem a alguém, dias depois de um evento ou quando uma condição de espera é atendida, e seu backend não está lá para fornecer os dados nesse momento. Um Data Feed preenche essa lacuna, e permite que quem cuida das mensagens mude o agendamento, adicione uma ramificação ou teste variantes sem um deploy. O preço é que sua API é chamada uma vez por destinatário e deve responder em cerca de um quarto de segundo, cada template só pode usar um feed e uma chamada com falha significa que a pessoa silenciosamente não recebe nada.

Para o Clean Beans, os fatores decisivos foram simples. O backend já tinha os dados e o agendamento, o ranking é compartilhado por uma casa, então uma solicitação é muito mais barata do que uma chamada por pessoa, e as preferências ficam armazenadas no banco de dados do aplicativo, onde o backend pode verificá-las diretamente.

> [card] [Personalizar com custom\_data](https://documentation.onesignal.com/docs/pt-BR/personalization-api-custom-data.md)
>
> Limites de tamanho e padrões de acesso com Liquid.

> [card] [Data feeds](https://documentation.onesignal.com/docs/pt-BR/data-feeds.md)
>
> Traga dados em tempo real para emails e SMS de Journeys.

> [card] [Usar a sintaxe Liquid](https://documentation.onesignal.com/docs/pt-BR/using-liquid-syntax.md)
>
> Filtros, loops e condições.


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