> ## 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: enviar push a partir do seu backend

> Seis notificações push enviadas a partir de Supabase Edge Functions com a API Create message: em um agendamento, a partir do aplicativo e a partir de um gatilho do banco de dados.

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.

A maioria das notificações do Clean Beans é enviada pelo backend, porque elas dependem de um agendamento ou de algo que outra pessoa fez. Todas chamam o mesmo endpoint, [Create message](https://documentation.onesignal.com/reference/create-message.md), e direcionam as pessoas pelo External ID.

| Push | Enviado quando | Gatilho |
| - | - | - |
| Resumo diário | No horário escolhido pelo usuário, se houver tarefas pendentes | Agendamento por hora |
| Lembrete de tarefas atrasadas | Seis horas após o resumo, se ainda houver tarefas atrasadas | Agendamento por hora |
| Lembrete de limpeza | Uma hora antes da janela de limpeza do usuário | Agendamento por hora |
| Sessão concluída | Um colega de casa termina a limpeza | Chamada a partir do aplicativo |
| Kudos | Um colega de casa envia kudos | Chamada a partir do aplicativo |
| Entrada aprovada | Um administrador aprova uma solicitação de entrada | Gatilho do banco de dados |

![Notificações push do 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)

Um exemplo de alguns dos pushes que o Clean Beans envia.

## Envios agendados que respeitam fusos horários \\

As pessoas escolhem o horário em que querem receber o lembrete diário. O Clean Beans não agenda um job por usuário. Ele executa um job a cada hora e pergunta: "para quem é esse horário agora?"

**1. Um agendamento do banco de dados chama uma função a cada hora**

O `pg_cron` faz uma solicitação HTTP para uma Supabase Edge Function. A chave de serviço de que ele precisa é lida do Supabase Vault, então ela nunca aparece no SQL.

**2. A função encontra os usuários cujo horário local corresponde**

Ela carrega todos que têm esse lembrete ativado, converte o horário atual para o fuso horário de cada usuário e mantém aqueles cujo horário escolhido é agora.

**3. Ela verifica se há algo a dizer**

Um usuário sem nada pendente não recebe push.

**4. Ela chama o OneSignal uma vez por usuário**

Cada push tem seu próprio conteúdo, então cada um é uma solicitação separada.

O agendamento:

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

A correspondência de fuso horário:

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

O envio:

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

Os campos `...DELIVERY.daily_digest`, `idempotency_key` e de badge são explicados em [Push confiável e bem comportado](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-reliable-push.md). O campo `data.type` é como o aplicativo sabe qual tela abrir quando o push é tocado. Consulte [Deep links e cliques em notificações](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-deep-links.md).

O título e o corpo são montados a partir das tarefas, então o push diz algo específico.

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

## O lembrete de tarefas atrasadas: um segundo aviso, diferente \\

O lembrete de tarefas atrasadas reutiliza o mesmo padrão com duas mudanças. Ele dispara seis horas após o horário do resumo do usuário e conta apenas as tarefas que estão de fato atrasadas.

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

O job dele roda na meia hora, então nunca concorre com o job do resumo no início da hora. O texto também é diferente. Um segundo lembrete que repete o primeiro é 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 };
}
```

## O lembrete de limpeza: uma solicitação para muitas pessoas \\

O lembrete de limpeza diz a mesma coisa para todos, então não precisa de uma solicitação por pessoa. A função reúne todos os IDs de usuários elegíveis e os envia em 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]
>
> Envie uma solicitação por pessoa quando o conteúdo for diferente. Envie uma solicitação para muitas pessoas quando ele for idêntico. Menos solicitações significam menos pontos de falha e menos risco de ultrapassar os limites de taxa.

## Sessão concluída: um push acionado a partir do aplicativo \\

Quando alguém termina uma sessão de limpeza, o resto da casa fica sabendo. O aplicativo não pode enviar esse push sozinho, porque não deve guardar uma API key. Ele chama uma função de backend, e a função envia o 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,
  },
});
```

A solicitação diz o que foi limpo, mas não quem limpou. A função identifica quem está chamando pelo token de login, verifica se a pessoa é membro ativo da casa e obtém o nome e o avatar dela a partir do perfil. Consulte [Verificar quem está chamando](#check-who-is-calling).

Depois, ela encontra os outros membros da casa e remove quem desativou esse 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);
```

Ela envia um único push para todos eles. O avatar de feijão de quem enviou é anexado como imagem, usando um campo diferente 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
}
```

![Uma notificação push expandida mostrando uma imagem de avatar de feijão](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-rich-push.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=07c38920b20cb73093805ca9961841e3)

Um push de sessão concluída, expandido para mostrar o avatar de quem enviou.

## Kudos: de uma pessoa para outra \\

Os kudos funcionam da mesma forma, com um único destinatário. Na tela de atividade, um membro toca em **Send Kudos** na sessão de um colega de casa, escolhe uma mensagem, e o aplicativo chama a função `send-kudos`.

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

Escolhendo uma mensagem de kudos para a sessão de limpeza de um colega 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 || '',
  },
};
```

## Entrada aprovada: um push acionado pelo banco de dados \\

Quem pede para entrar em uma casa aguarda a aprovação de um administrador. Quando isso acontece, a linha de membro muda de `pending` para `active`. Um gatilho do banco de dados nessa mudança chama uma função, e a função avisa a pessoa de que ela entrou.

Colocar o gatilho no banco de dados significa que o push é enviado independentemente de como a aprovação acontece, e o aplicativo não precisa de código para isso.

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

A função não confia no que recebe. Ela lê a associação novamente e só envia se a aprovação for real e recente.

```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]
>
> Uma função que envia mensagens sob demanda é algo que outras pessoas podem tentar chamar. Verifique os fatos no seu próprio banco de dados antes de enviar, como esta faz, e nunca aceite conteúdo de mensagem ou destinatários de um chamador que você não verificou.

## Verificar quem está chamando \\

O Supabase verifica se uma solicitação para uma edge function tem um token válido, mas o token de um usuário conectado é tão válido quanto o do agendador. Sem uma verificação adicional, qualquer usuário poderia acionar o resumo diário para todos ou enviar um push em nome de outra pessoa. Por isso, cada função decide por si mesma quem pode chamá-la.

| Funções | Quem pode chamar | Verificação |
| - | - | - |
| Envios agendados e o gatilho do banco de dados | Somente o agendador | O token deve ser a chave service role |
| Sessão concluída, kudos | Um usuário conectado, em seu próprio nome | O remetente vem do token, nunca do corpo da solicitação |

As funções agendadas começam com uma linha:

```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]
>
> A verificação de função depende de o Supabase já ter verificado a assinatura do token. Implante essas funções com a verificação de JWT ativada, que é o padrão. Nunca as implante com `--no-verify-jwt`.

As funções chamadas a partir do aplicativo identificam o remetente pelo token e depois verificam se o remetente pode alcançar o destinatário. Kudos só podem ir para alguém que compartilha uma casa com o remetente, e o nome mostrado no push é lido do perfil do remetente.

```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 Create message](https://documentation.onesignal.com/reference/create-message.md)
>
> Segmentação, conteúdo e agendamento para todos os canais.

> [card] [Rich media](https://documentation.onesignal.com/docs/pt-BR/rich-media.md)
>
> Imagens em notificações push em cada plataforma.


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