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

# App de ejemplo: email semanal con custom_data

> Cómo la app de ejemplo Clean Beans envía un informe semanal por email personalizado para cada destinatario con custom_data y Liquid, y cómo se compara con Data Feeds.

Esta página forma parte de [App de ejemplo: una integración completa de OneSignal](https://documentation.onesignal.com/docs/es/example-full-integration-overview.md), que sigue una app real de principio a fin. La app es **Clean Beans**, un turno de limpieza para hogares compartidos, creada con Expo (React Native) y un backend de Supabase.

Cada domingo, cada hogar recibe un email que resume su semana: sesiones, tareas, minutos, una clasificación y las cifras de cada persona.

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

El informe semanal: totales del hogar, tu propia semana y la clasificación.

El problema interesante es la personalización. Todas las personas de un hogar ven la misma clasificación, pero cada una debería ver su propio nombre y sus estadísticas. Enviar una solicitud por persona funcionaría, pero hay una forma mejor.

## Una solicitud por hogar, personalizada para cada persona \\

La función envía **una** solicitud por hogar. Pasa todos los datos en `custom_data`, incluido un objeto `users` indexado por External ID. Después, la plantilla selecciona la entrada correcta para la persona para la que se está generando.

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

En la plantilla, una línea de Liquid selecciona los datos del destinatario actual.

```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 de ahí, `user` contiene las estadísticas de esta persona, y todo lo que se lee directamente de `message.custom_data` es compartido por el hogar.

```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]
>
> El segundo ejemplo de Liquid está simplificado a partir de la plantilla para mostrar la lógica sin el marcado de la tabla.

## Mantenerse dentro del límite de tamaño \\

El `custom_data` para email está limitado a 10 KB. Un hogar grande podría superarlo, así que la función mide el payload y recorta la clasificación si es necesario.

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

## Programación y preferencias \\

Una programación semanal llama a la función cada domingo a las 09:00 UTC, con el mismo patrón de `pg_cron` que los recordatorios push y la expresión `0 9 * * 0`. Solo se incluyen los usuarios que tienen activado **Weekly Email Summary**.

**Configuración del panel.** En **Mensajes > Plantillas**, crea una plantilla de email, pega el HTML y copia el ID de la plantilla en los secretos de tu backend. `custom_data` solo funciona con una plantilla, así que `template_id` es obligatorio.

## La alternativa: Data Feeds \\

Hay una segunda forma de incluir datos por persona en un email, y Clean Beans decidió no usarla. Merece la pena entenderla, porque para algunas apps es la opción más adecuada.

Con `custom_data`, tu backend **envía** los datos a OneSignal cuando hace el envío. Con un **Data Feed**, OneSignal **obtiene** los datos de tu API en el momento en que se envía cada email. El envío en sí lo inicia un Journey, no tu backend.

> [!NOTE]
>
> Los ejemplos de esta subsección son ilustrativos. Muestran cómo se habría creado el informe semanal con un Data Feed. No están tomados de la app.

Así es como habría funcionado el informe semanal.

**1. Exponer un endpoint que devuelva la semana de una persona**

Una función del backend recibe un ID de usuario y devuelve las estadísticas de ese usuario y la clasificación de su hogar en 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. Crear el Data Feed en el panel**

En **Configuración > Data feeds**, asigna un alias al feed y apúntalo al endpoint. La URL y las cabeceras aceptan Liquid, así que se puede pasar el External ID del destinatario.

```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. Adjuntar el feed a la plantilla de email y leer de él**

En la plantilla, los valores proceden de `data_feed`, seguido del 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. Enviarlo desde un Journey recurrente**

Un Journey con una franja horaria del domingo por la mañana como primer paso, y una regla de reentrada, envía la plantilla cada semana. No hay código de programación ni de envío en tu backend.

### Cuál usar \\

| | `custom_data` (lo que usa Clean Beans) | Data Feeds |
| - | - | - |
| Quién inicia el envío | Tu backend, llamando a la API | Un Journey en el panel |
| Cuándo se leen los datos | Cuando tu backend crea la solicitud | Cuando se envía cada mensaje |
| Solicitudes para un hogar de cuatro personas | Una solicitud a OneSignal | Cuatro llamadas de OneSignal a tu API |
| Canales | Push, email y SMS | Email y SMS, solo dentro de Journeys |
| Límite de tamaño | 10 KB para email | Se recomiendan respuestas de hasta unos 50 KB |
| Si faltan los datos | Tu código decide qué hacer | Ese destinatario no recibe ningún mensaje |
| Cambiar la programación o el flujo | Un cambio en el backend | Un cambio en el panel |
| Exposición de tu API | No se expone nada | Un endpoint público que debes proteger y mantener rápido |

**Elige `custom_data` cuando tu backend ya es quien decide enviar.** Ese es el caso del informe semanal. El backend se ejecuta de forma programada, sabe qué hogares han dado su consentimiento y tiene todas las cifras a mano, así que pasar los datos no cuesta nada más. Una solicitud cubre todo un hogar, no hay ningún endpoint que proteger y un fallo aparece en tus propios registros. El precio es que el momento y la audiencia viven en el código, y el payload tiene un límite de tamaño fijo.

**Elige un Data Feed cuando el envío pertenece a un Journey.** Un Journey decide por sí mismo cuándo enviar un mensaje a alguien, días después de un evento o una vez que se cumple una condición de espera, y tu backend no está ahí para aportar los datos en ese momento. Un Data Feed cubre ese hueco, y permite que quienes gestionan la mensajería cambien la programación, añadan una rama o prueben variantes sin un despliegue. El precio es que se llama a tu API una vez por destinatario y debería responder en aproximadamente un cuarto de segundo, cada plantilla solo puede usar un feed y una llamada fallida significa que esa persona no recibe nada, sin aviso.

Para Clean Beans, los factores decisivos fueron sencillos. El backend ya tenía los datos y la programación, la clasificación la comparte un hogar, así que una solicitud es mucho más barata que una llamada por persona, y las preferencias se guardan en la base de datos de la app, donde el backend puede comprobarlas directamente.

> [card] [Personalizar con custom\_data](https://documentation.onesignal.com/docs/es/personalization-api-custom-data.md)
>
> Límites de tamaño y patrones de acceso con Liquid.

> [card] [Data feeds](https://documentation.onesignal.com/docs/es/data-feeds.md)
>
> Incorpora datos en tiempo real a emails y SMS de Journeys.

> [card] [Usar la sintaxis Liquid](https://documentation.onesignal.com/docs/es/using-liquid-syntax.md)
>
> Filtros, bucles y condiciones.


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