> ## 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: push confiável e bem comportado

> Como o aplicativo de exemplo Clean Beans evita pushes duplicados com chaves de idempotência, ajusta a entrega para cada tipo de push e define badges no ícone do aplicativo.

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.

Fazer um push chegar é o primeiro passo. Esta página trata das decisões menores que tornam os pushes confiáveis: nunca enviar o mesmo duas vezes, deixar os desatualizados expirarem e fazer cada tipo se comportar de um jeito adequado.

## Nunca enviar o mesmo lembrete duas vezes \\

Jobs agendados são executados novamente. Um job também pode rodar duas vezes por engano. Sem proteção, cada repetição envia outro push.

O `idempotency_key` do OneSignal resolve isso. Se duas solicitações tiverem a mesma chave, a segunda não é enviada. A chave precisa ser um UUID, e o OneSignal a guarda por 30 dias.

Uma função agendada não tem onde guardar uma chave aleatória entre execuções, então o Clean Beans deriva a chave do que o envio é: seu tipo, seu destinatário e sua data. O mesmo envio sempre gera a mesma chave.

```typescript supabase/functions/_shared/idempotency.ts theme={null}
/** Name-based UUID (version 5) per RFC 9562. */
export async function uuidV5(name: string, namespace: string): Promise<string> {
  const ns = uuidToBytes(namespace);
  const nameBytes = new TextEncoder().encode(name);
  const input = new Uint8Array(ns.length + nameBytes.length);
  input.set(ns);
  input.set(nameBytes, ns.length);

  const digest = new Uint8Array(await crypto.subtle.digest('SHA-1', input));
  const bytes = digest.slice(0, 16);
  bytes[6] = (bytes[6] & 0x0f) | 0x50; // version 5
  bytes[8] = (bytes[8] & 0x3f) | 0x80; // RFC variant

  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
}

export function idempotencyKey(...parts: string[]): Promise<string> {
  return uuidV5(parts.join(':'), CLEAN_BEANS_NAMESPACE);
}
```

| Push | A chave é montada a partir de | Resultado |
| - | - | - |
| Resumo diário | tipo, ID do usuário, data local do usuário | Um resumo por usuário por dia |
| Lembrete de tarefas atrasadas | tipo, ID do usuário, data local do usuário | Um lembrete por usuário por dia |
| Lembrete de limpeza | tipo, a hora, os IDs dos destinatários ordenados | Um lembrete por lote por execução horária |
| Email semanal | tipo, ID da casa, data da execução | Um email por casa por execução |
| Entrada aprovada | tipo, ID do usuário, ID da casa, horário da aprovação | Um push por aprovação |

Em um envio em lote, a chave cobre o lote inteiro.

```typescript supabase/functions/send-cleaning-reminder/index.ts theme={null}
const batchKey = await idempotencyKey(
  'upcoming_cleaning',
  utcHourSlot(now),
  [...batch].sort().join(','),
);
```

> [!NOTE]
>
> As chaves de idempotência funcionam nos endpoints Create message e Create custom events. As solicitações de Live Activity não as aceitam. Elas são identificadas pelo `activity_id`.

## Dar a cada tipo de push seu próprio comportamento \\

Um lembrete de limpeza que chega duas horas atrasado é pior do que nenhum lembrete. Kudos são bons de receber, mas nunca urgentes. O Clean Beans descreve essas diferenças uma única vez, em um conjunto de perfis de entrega, e aplica o perfil certo a cada solicitação.

```typescript supabase/functions/_shared/delivery.ts theme={null}
export const DELIVERY: Record<
  'daily_digest' | 'overdue_reminder' | 'upcoming_cleaning' | 'session_completed' | 'kudos' | 'join_approved' | 'member_lapsed',
  DeliveryProfile
> = {
  // Morning digest. Expires after 6h — by then the overdue nudge has taken
  // over. Grouped with the nudge under the same thread.
  daily_digest: {
    ttl: 6 * HOUR,
    thread_id: 'tasks',
    android_group: 'tasks',
    ios_interruption_level: 'active',
    ios_relevance_score: 0.6,
  },

  // Afternoon nudge. Arrives as its own alert, grouped with the digest.
  overdue_reminder: {
    ttl: 6 * HOUR,
    thread_id: 'tasks',
    android_group: 'tasks',
    ios_interruption_level: 'active',
    ios_relevance_score: 0.8,
  },

  // "Cleaning time in 1 hour". Only meaningful until the window starts,
  // so it expires after 1h. Time-sensitive: it is tied to a time the user
  // scheduled themselves, so it may break through Focus modes.
  upcoming_cleaning: {
    ttl: 1 * HOUR,
    thread_id: 'schedule',
    android_group: 'schedule',
    ios_interruption_level: 'time_sensitive',
    ios_relevance_score: 0.9,
  },

  // ...
};
```

| Push | Mantido para um dispositivo offline | Agrupado em | Nível de interrupção do iOS | Relevância |
| - | - | - | - | - |
| Resumo diário | 6 horas | `tasks` | Active | 0.6 |
| Lembrete de tarefas atrasadas | 6 horas | `tasks` | Active | 0.8 |
| Lembrete de limpeza | 1 hora | `schedule` | Time Sensitive | 0.9 |
| Sessão concluída | 24 horas | `household` | Active | 0.4 |
| Kudos | 3 dias | `household` | Passive | 0.7 |
| Entrada aprovada | 3 dias | `household` | Active | 0.8 |

O perfil `member_lapsed` na lista de tipos pertence a um push enviado a partir de um webhook de Journey, que este guia não aborda.

O que cada configuração faz:

* **`ttl`** é o tempo que um push fica guardado para um dispositivo offline. O lembrete de limpeza diz "em 1 hora", então ele é descartado após uma hora.
* **`thread_id`** e **`android_group`** agrupam pushes relacionados na lista de notificações.
* **`ios_interruption_level`** controla o quão insistente um push é. `time_sensitive` pode passar pelos modos de Foco. `passive` chega silenciosamente.
* **`ios_relevance_score`** ordena os pushes no resumo de notificações do iOS. O Clean Beans reserva `1.0` para mensagens críticas e não envia nenhuma.

**Configuração do aplicativo.** O iOS só respeita `time_sensitive` se o aplicativo declarar a capability.

```json app.json theme={null}
{
  "expo": {
    "ios": {
      "entitlements": {
        "com.apple.developer.usernotifications.time-sensitive": true
      }
    }
  }
}
```

> [!WARNING]
>
> **Uma lição aprendida: `collapse_id`.** O Clean Beans deu primeiro o mesmo `collapse_id` ao resumo e ao lembrete de tarefas atrasadas, para que o lembrete substituísse o resumo. No iOS, um push que substitui outro ainda presente na lista de notificações é trocado no lugar, sem banner e sem som. O lembrete passava despercebido, o que anulava seu propósito, então a configuração foi removida. Use `collapse_id` somente quando quiser uma atualização silenciosa, como um placar ao vivo.

## Mostrar um número no ícone do aplicativo \\

Os dois pushes de tarefas definem o badge do ícone do aplicativo com o número do título.

```typescript supabase/functions/send-overdue-reminders/index.ts theme={null}
// App icon badge = number of overdue tasks. The OneSignal SDK clears the
// badge automatically the next time the app is opened.
ios_badgeType: 'SetTo',
ios_badgeCount: taskCount,
```

![O ícone do aplicativo Clean Beans com um número no badge](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-badge.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=08c9bc46b557e4e15819cd0ec42488cf)

O badge do ícone do aplicativo mostra quantas tarefas estão atrasadas.

É usado `SetTo`, não `Increase`, porque o badge é uma contagem de tarefas, e não de notificações não lidas. O lembrete da tarde substitui o número da manhã.

> [!NOTE]
>
> O SDK do OneSignal limpa o badge automaticamente sempre que o aplicativo é aberto, então o aplicativo não precisa de código para redefini-lo. Um push que chega com o aplicativo aberto nunca mostra seu badge. O Android não tem um badge numérico que possa ser definido pela API.

> [card] [Solicitações idempotentes](https://documentation.onesignal.com/reference/idempotent-notification-requests.md)
>
> Como as chaves funcionam e quanto tempo duram.

> [card] [Níveis de interrupção](https://documentation.onesignal.com/docs/pt-BR/ios-focus-modes-and-interruption-levels.md)
>
> Modos de Foco e os quatro níveis.

> [card] [Badges](https://documentation.onesignal.com/docs/pt-BR/badges.md)
>
> Comportamento dos badges em cada plataforma.


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