> ## 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: enviar push desde tu backend

> Seis notificaciones push enviadas desde Supabase Edge Functions con la API de creación de mensajes, de forma programada, desde la app y desde un disparador de base de datos.

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.

La mayoría de las notificaciones de Clean Beans las envía el backend, porque dependen de una programación o de algo que ha hecho otra persona. Todas llaman al mismo endpoint, [Create message](https://documentation.onesignal.com/reference/create-message.md), y se dirigen a las personas por External ID.

| Push | Se envía cuando | Disparador |
| - | - | - |
| Resumen diario | A la hora elegida por el usuario, si hay tareas pendientes | Programación cada hora |
| Recordatorio de tareas vencidas | Seis horas después del resumen, si sigue habiendo tareas vencidas | Programación cada hora |
| Recordatorio de limpieza | Una hora antes de la franja de limpieza del usuario | Programación cada hora |
| Sesión completada | Un compañero de casa termina de limpiar | Llamada desde la app |
| Kudos | Un compañero de casa envía kudos | Llamada desde la app |
| Unión aprobada | Un administrador aprueba una solicitud de unión | Disparador de base de datos |

![Notificaciones push de Clean Beans](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-push-examples.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=f26bc81be159fba77a9873e119ccb19e)

Un ejemplo de algunos de los push que envía Clean Beans.

## Envíos programados que respetan las zonas horarias \\

Las personas eligen la hora a la que quieren su recordatorio diario. Clean Beans no programa un trabajo por usuario. Ejecuta un trabajo cada hora y se pregunta: "¿para quién es esa hora ahora mismo?"

**1. Una programación de la base de datos llama a una función cada hora**

`pg_cron` hace una solicitud HTTP a una Supabase Edge Function. La clave de servicio que necesita se lee de Supabase Vault, así que nunca aparece en el SQL.

**2. La función busca a los usuarios cuya hora local coincide**

Carga a todas las personas que tienen ese recordatorio activado, convierte la hora actual a la zona horaria de cada usuario y se queda con aquellos cuya hora elegida es ahora.

**3. Comprueba que hay algo que decir**

Un usuario sin nada pendiente no recibe ningún push.

**4. Llama a OneSignal una vez por usuario**

Cada push tiene su propio contenido, así que cada uno es una solicitud independiente.

La programación:

```sql supabase/migrations/006_cron_daily_digest.sql theme={null}
select cron.schedule(
  'send-daily-digest',          -- job name
  '0 * * * *',                  -- every hour at :00
  $$
  select
    net.http_post(
      url := 'https://YOUR_PROJECT_REF.supabase.co/functions/v1/send-daily-digest',
      headers := jsonb_build_object(
        'Content-Type', 'application/json',
        'Authorization', 'Bearer ' || (select decrypted_secret from vault.decrypted_secrets where name = 'service_role_key')
      ),
      body := '{}'::jsonb
    );
  $$
);
```

La coincidencia de zona horaria:

```typescript supabase/functions/send-daily-digest/index.ts theme={null}
for (const profile of profiles) {
  try {
    // Get current hour in user's timezone
    const localHour = parseInt(
      now.toLocaleString('en-US', {
        timeZone: profile.timezone || 'UTC',
        hour: 'numeric',
        hour12: false,
      }),
      10
    );

    if (localHour === profile.notification_hour) {
      eligibleUsers.push({
        id: profile.id,
        householdId: profile.household_id,
        localDate: localDate(now, profile.timezone || 'UTC'),
      });
    }
  } catch {
    // Invalid timezone — skip this user
    console.warn(`Invalid timezone for user ${profile.id}: ${profile.timezone}`);
  }
}
```

El envío:

```typescript supabase/functions/send-daily-digest/index.ts theme={null}
const onesignalPayload = {
  app_id: ONESIGNAL_APP_ID,
  // One digest per user per local day: a retried or duplicated cron
  // run reuses this key and OneSignal will not send it twice.
  idempotency_key: await idempotencyKey('daily_digest', digest.userId, digest.localDate),
  include_aliases: {
    external_id: [digest.userId],
  },
  target_channel: 'push',
  ...DELIVERY.daily_digest,
  headings: { en: heading },
  contents: { en: body },
  url: 'cleaning-rota:///(tabs)/clean',
  // App icon badge = number of tasks due. The OneSignal SDK clears the
  // badge automatically the next time the app is opened.
  ios_badgeType: 'SetTo',
  ios_badgeCount: digest.tasks.length,
  // Action buttons, revealed by expanding the notification
  buttons: TASK_BUTTONS,
  data: { type: 'daily_digest', taskCount: String(digest.tasks.length) },
};

const res = await fetch('https://api.onesignal.com/notifications', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Key ${ONESIGNAL_REST_API_KEY}`,
  },
  body: JSON.stringify(onesignalPayload),
});
```

Los campos `...DELIVERY.daily_digest`, `idempotency_key` y de insignia se explican en [Push fiable y bien comportado](https://documentation.onesignal.com/docs/es/example-full-integration-reliable-push.md). El campo `data.type` es la forma en que la app sabe qué pantalla abrir cuando se toca el push. Consulta [Deep links y clics en notificaciones](https://documentation.onesignal.com/docs/es/example-full-integration-deep-links.md).

El título y el cuerpo se construyen a partir de las tareas, así que el push dice algo concreto.

```typescript supabase/functions/send-daily-digest/index.ts theme={null}
function buildDigestContent(tasks: TaskRow[]): { heading: string; body: string } {
  const count = tasks.length;
  const heading = count === 1
    ? '1 cleaning task due today'
    : `${count} cleaning tasks due today`;

  // Collect unique room names
  const rooms = [...new Set(tasks.map(t => t.room_name))];

  let body: string;
  if (rooms.length === 1) {
    body = `Your ${rooms[0]} needs some attention!`;
  } else if (rooms.length === 2) {
    body = `Your ${rooms[0]} and ${rooms[1]} need some attention!`;
  } else {
    const last = rooms.pop()!;
    body = `Your ${rooms.join(', ')}, and ${last} need some attention!`;
  }

  return { heading, body };
}
```

## El recordatorio de tareas vencidas: un segundo aviso, diferente \\

El recordatorio de tareas vencidas reutiliza el mismo patrón con dos cambios. Se dispara seis horas después de la hora del resumen del usuario y solo cuenta las tareas que están realmente vencidas.

```typescript supabase/functions/send-overdue-reminders/index.ts theme={null}
// Overdue hour wraps around midnight
const overdueHour = (profile.notification_hour + OVERDUE_OFFSET_HOURS) % 24;

if (localHour === overdueHour) {
  eligibleUsers.push({
    id: profile.id,
    householdId: profile.household_id,
    localDate: localDate(now, profile.timezone || 'UTC'),
  });
}
```

Su trabajo se ejecuta a la media hora, así que nunca compite con el trabajo del resumen al inicio de la hora. El texto también es diferente. Un segundo recordatorio que repite el primero es fácil de ignorar.

```typescript supabase/functions/send-overdue-reminders/index.ts theme={null}
function buildOverdueContent(tasks: TaskRow[]): { heading: string; body: string } {
  const count = tasks.length;
  const heading = count === 1
    ? '1 overdue task still waiting'
    : `${count} overdue tasks still waiting`;

  const rooms = [...new Set(tasks.map((t) => t.room_name))];

  let body: string;
  if (rooms.length === 1) {
    body = `Your ${rooms[0]} still needs some love today!`;
  } else if (rooms.length === 2) {
    body = `Your ${rooms[0]} and ${rooms[1]} still need some love today!`;
  } else {
    const last = rooms.pop()!;
    body = `Your ${rooms.join(', ')}, and ${last} still need some love today!`;
  }

  return { heading, body };
}
```

## El recordatorio de limpieza: una solicitud para muchas personas \\

El recordatorio de limpieza dice lo mismo a todo el mundo, así que no necesita una solicitud por persona. La función recopila todos los IDs de usuario que cumplen los requisitos y los envía en lotes.

```typescript supabase/functions/send-cleaning-reminder/index.ts theme={null}
const batchSize = 2000;
for (let i = 0; i < eligibleUserIds.length; i += batchSize) {
  const batch = eligibleUserIds.slice(i, i + batchSize);

  // One reminder per batch of recipients per hourly cron slot: a retried
  // or duplicated run in the same hour reuses this key and OneSignal
  // will not send it twice.
  const batchKey = await idempotencyKey(
    'upcoming_cleaning',
    utcHourSlot(now),
    [...batch].sort().join(','),
  );

  const onesignalPayload = {
    app_id: ONESIGNAL_APP_ID,
    idempotency_key: batchKey,
    include_aliases: {
      external_id: batch,
    },
    target_channel: 'push',
    ...DELIVERY.upcoming_cleaning,
    headings: { en: 'Cleaning time in 1 hour' },
    contents: {
      en: 'Your cleaning window starts soon. Ready to get things sparkling?',
    },
    url: 'cleaning-rota:///(tabs)/clean',
    data: { type: 'upcoming_cleaning' },
  };
```

> [!TIP]
>
> Envía una solicitud por persona cuando el contenido sea diferente. Envía una solicitud para muchas personas cuando sea idéntico. Menos solicitudes significan menos cosas que pueden fallar y menos riesgo de superar los límites de frecuencia.

## Sesión completada: un push disparado desde la app \\

Cuando alguien termina una sesión de limpieza, el resto del hogar se entera. La app no puede enviar ese push por sí misma, porque no debe contener una API key. Llama a una función del backend y la función envía el push.

```typescript src/lib/database.ts theme={null}
const { error } = await supabase.functions.invoke('session-completed', {
  body: {
    householdId,
    roomName: params.roomName,
    tasksCompleted: params.tasksCompleted,
    estimatedMins: params.estimatedMins,
  },
});
```

La solicitud dice qué se ha limpiado, pero no quién lo ha limpiado. La función obtiene quién llama a partir de su token de inicio de sesión, comprueba que es un miembro activo del hogar y toma su nombre y su avatar de su perfil. Consulta [Comprobar quién llama](#check-who-is-calling).

Después busca a los demás miembros del hogar y elimina a quien tenga desactivado este tipo de push.

```typescript supabase/functions/session-completed/index.ts theme={null}
// ── 1. Look up other active household members ──

const { data: members, error: memberErr } = await supabase
  .from('household_members')
  .select('user_id')
  .eq('household_id', householdId)
  .eq('status', 'active')
  .neq('user_id', userId);

    // ...

const { data: profiles, error: profileErr } = await supabase
  .from('profiles')
  .select('id, notifications_enabled, push_cleaning_done')
  .in('id', recipientIds)
  .eq('notifications_enabled', true)
  .eq('push_cleaning_done', true);
```

Envía un único push a todos ellos. El avatar de judía de quien lo envía se adjunta como imagen, usando un campo distinto para cada plataforma.

```typescript supabase/functions/session-completed/index.ts theme={null}
const onesignalPayload: Record<string, unknown> = {
  app_id: ONESIGNAL_APP_ID,
  include_aliases: {
    external_id: enabledIds,
  },
  target_channel: 'push',
  ...DELIVERY.session_completed,
  headings: { en: heading },
  contents: { en: body },
  url: 'cleaning-rota:///activity',
  data: {
    type: 'session_completed',
    roomName,
    userName,
    tasksCompleted: String(tasksCompleted),
    // Who cleaned: lets the "Send kudos" button reply to the right person
    ...(isRealUser ? { cleanerId: userId } : {}),
  },
  // "Send kudos" needs a real person to send to
  ...(isRealUser ? { buttons: SESSION_BUTTONS } : {}),
};

// Attach avatar image for rich push notifications
if (avatarImageUrl) {
  onesignalPayload.big_picture = avatarImageUrl;          // Android
  onesignalPayload.ios_attachments = { avatar: avatarImageUrl }; // iOS
}
```

![Una notificación push expandida que muestra una imagen de avatar de judía](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-rich-push.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=07c38920b20cb73093805ca9961841e3)

Un push de sesión completada, expandido para mostrar el avatar de quien lo envía.

## Kudos: de una persona a otra \\

Los kudos funcionan igual, con un solo destinatario. En la pantalla de actividad, un miembro toca **Send Kudos** en la sesión de un compañero de casa, elige un mensaje y la app llama a la función `send-kudos`.

![La hoja inferior de kudos con mensajes predefinidos](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-kudos.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=83ec608d61e91c74f16bcb65d8757927)

Elegir un mensaje de kudos para la sesión de limpieza de un compañero de casa.

```typescript supabase/functions/send-kudos/index.ts theme={null}
const heading = `Kudos from ${senderName}!`;
const body = message;

    // ...

const onesignalPayload: Record<string, unknown> = {
  app_id: ONESIGNAL_APP_ID,
  include_aliases: {
    external_id: [recipientUserId],
  },
  target_channel: 'push',
  ...DELIVERY.kudos,
  headings: { en: heading },
  contents: { en: body },
  url: 'cleaning-rota:///activity',
  data: {
    type: 'kudos',
    senderName,
    roomName: roomName || '',
  },
};
```

## Unión aprobada: un push disparado por la base de datos \\

Quien pide unirse a un hogar espera a que un administrador lo apruebe. Cuando eso ocurre, su fila de membresía cambia de `pending` a `active`. Un disparador de base de datos sobre ese cambio llama a una función, y la función le avisa de que ya forma parte del hogar.

Poner el disparador en la base de datos significa que el push se envía sea cual sea la forma en que se produce la aprobación, y la app no necesita código para ello.

```sql supabase/migrations/027_join_approved_trigger.sql theme={null}
create trigger trg_notify_join_approved
  after update of status on public.household_members
  for each row
  when (old.status = 'pending' and new.status = 'active')
  execute function public.notify_join_approved();
```

La función no se fía de lo que le dicen. Vuelve a leer la membresía y solo envía si la aprobación es real y reciente.

```typescript supabase/functions/join-approved/index.ts theme={null}
// ── 1. Confirm the membership really was approved, and recently ──

const { data: membership, error: memberErr } = await supabase
  .from('household_members')
  .select('status, joined_at, households(name)')
  .eq('user_id', userId)
  .eq('household_id', householdId)
  .maybeSingle();

if (memberErr) throw memberErr;

if (!membership || membership.status !== 'active' || !membership.joined_at) {
  return jsonResponse({ sent: 0, message: 'No active membership found' });
}

const joinedAt = new Date(membership.joined_at).getTime();
if (Date.now() - joinedAt > RECENT_APPROVAL_MS) {
  return jsonResponse({ sent: 0, message: 'Membership was not approved recently' });
}
```

> [!WARNING]
>
> Una función que envía mensajes bajo petición es algo que otras personas pueden intentar llamar. Comprueba los datos en tu propia base de datos antes de enviar, como hace esta, y nunca aceptes contenido de mensajes ni destinatarios de alguien que llama y que no has verificado.

## Comprobar quién llama \\

Supabase verifica que una solicitud a una edge function lleve un token válido, pero el token de un usuario que ha iniciado sesión es tan válido como el del programador de tareas. Sin una comprobación adicional, cualquier usuario podría disparar el resumen diario para todo el mundo o enviar un push en nombre de otra persona. Por eso cada función decide por sí misma quién puede llamarla.

| Funciones | Quién puede llamar | Comprobación |
| - | - | - |
| Envíos programados y el disparador de base de datos | Solo el programador de tareas | El token debe ser la clave de service role |
| Sesión completada, kudos | Un usuario que ha iniciado sesión, en su propio nombre | El remitente sale del token, nunca del cuerpo de la solicitud |

Las funciones programadas empiezan con una línea:

```typescript supabase/functions/send-daily-digest/index.ts theme={null}
// Only the scheduler (service role) may run this
const denied = requireServiceRole(req);
if (denied) return denied;
```

```typescript supabase/functions/_shared/auth.ts theme={null}
export function isServiceRoleRequest(req: Request): boolean {
  const token = bearerToken(req);
  if (!token) return false;
  if (token === Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')) return true;

  try {
    const part = token.split('.')[1] ?? '';
    const base64 = part.replace(/-/g, '+').replace(/_/g, '/');
    const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);
    const claims = JSON.parse(atob(padded));
    return claims?.role === 'service_role';
  } catch {
    return false;
  }
}
```

> [!WARNING]
>
> La comprobación del rol depende de que Supabase ya haya verificado la firma del token. Despliega estas funciones con la verificación de JWT activada, que es la opción predeterminada. Nunca las despliegues con `--no-verify-jwt`.

Las funciones llamadas desde la app identifican al remitente a partir del token y luego comprueban que el remitente puede llegar al destinatario. Los kudos solo pueden ir a alguien que comparte hogar con el remitente, y el nombre que aparece en el push se lee del perfil del remitente.

```typescript supabase/functions/send-kudos/index.ts theme={null}
const caller = await authenticateUser(req, supabase);
if (caller instanceof Response) return caller;

// ...

// Sender and recipient must be active members of the same household
const { data: memberships, error: memberErr } = await supabase
  .from('household_members')
  .select('user_id, household_id')
  .in('user_id', [caller.id, recipientUserId])
  .eq('status', 'active');

if (memberErr) throw memberErr;

const callerHouseholds = new Set(
  (memberships ?? []).filter((m) => m.user_id === caller.id).map((m) => m.household_id),
);
const sharesHousehold = (memberships ?? []).some(
  (m) => m.user_id === recipientUserId && callerHouseholds.has(m.household_id),
);

if (!sharesHousehold) {
  return jsonResponse({ error: 'forbidden', message: 'You can only send kudos to members of your household.' }, 403);
}
```

> [card] [API de creación de mensajes](https://documentation.onesignal.com/reference/create-message.md)
>
> Segmentación, contenido y programación para todos los canales.

> [card] [Rich media](https://documentation.onesignal.com/docs/es/rich-media.md)
>
> Imágenes en notificaciones push en cada plataforma.


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