> ## 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: uma integração completa do OneSignal

> Acompanhe um aplicativo real, o Clean Beans, para ver como push, in-app, email, SMS, Live Activities e Event Streams funcionam juntos no Expo com Supabase.

A maioria dos guias do OneSignal explica um recurso por vez. Este acompanha um único aplicativo do início ao fim e mostra como cada recurso de mensagens foi conectado, com o código que roda em produção.

O aplicativo é o **Clean Beans**, uma escala de limpeza para casas compartilhadas. Ele é construído com Expo (React Native) e usa o Supabase para banco de dados, autenticação e funções de backend. O OneSignal cuida de todas as mensagens que o aplicativo envia.

![Três telas do Clean Beans: o painel, uma sessão de limpeza e a escala semanal](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-dashboard-session-rota.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=f8fc7eac8e69faea6aece66f73c2d820)

Clean Beans: o painel, uma sessão de limpeza e a escala semanal.

## O que o Clean Beans faz \\

Uma casa adiciona seus cômodos, e o aplicativo os transforma em uma lista de tarefas de limpeza com frequências adequadas. Um gerador de escala distribui essas tarefas ao longo da semana para caber no tempo disponível de cada pessoa. Os membros fazem sessões de limpeza, marcam tarefas, mantêm sequências diárias, enviam kudos uns aos outros e competem em um ranking semanal.

A limpeza é compartilhada, recorrente e tem prazos, o que a torna adequada para quase todo tipo de mensagem: lembretes, atualizações sociais, contagens regressivas, resumos e orientações.

## Por que este guia existe \\

Use-o para responder a três perguntas:

* **Qual recurso do OneSignal serve para qual tarefa?** Cada página parte de algo que o aplicativo precisava fazer e depois mostra o recurso que faz isso.
* **Onde fica o código?** Parte do trabalho pertence ao aplicativo, parte ao seu backend e parte ao painel do OneSignal. Cada exemplo diz qual.
* **O que pode dar errado?** Os avisos e notas de cada página registram o que foi aprendido ao colocar tudo em produção. Uma configuração, `collapse_id`, foi testada e depois removida, e [Push confiável e bem comportado](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-reliable-push.md) explica por quê.

## Como ler \\

O guia é um conjunto de páginas, uma por tema. Você não precisa lê-las em ordem. [Configuração do SDK e identidade do usuário](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-sdk-setup.md) é a base de todo o resto. Depois disso, cada página é independente.

A maioria dos recursos é apresentada da mesma forma:

1. **O que o usuário vê**, geralmente com uma captura de tela.
2. **Como funciona**, como uma sequência curta de quem faz o quê.
3. **O código**, retirado do aplicativo. O título de cada bloco de código é o arquivo de onde ele vem.
4. **Configuração do painel**, quando o recurso precisa ser configurado no OneSignal.

Limites e surpresas são destacados em avisos e notas ao lado do recurso que afetam.

> [!NOTE]
>
> O código é real, mas os identificadores foram substituídos por marcadores como `YOUR_ONESIGNAL_APP_ID` e `YOUR_PROJECT_REF`. Arquivos longos foram reduzidos às linhas que importam. Uma linha contendo apenas `// ...` marca onde o código foi omitido.

## Como as peças se encaixam \\

| Onde | Do que é responsável | Exemplos |
| - | - | - |
| **O aplicativo Expo** | Tudo que precisa do dispositivo ou do usuário conectado | Inicializar o SDK, pedir permissão, identificar o usuário, tags, eventos personalizados, gatilhos de mensagens in-app, tratamento de toques |
| **O backend Supabase** | Tudo que é acionado por um agendamento ou por mudança de dados | Lembretes, pushes sociais, o email semanal, códigos SMS e convites, início de Live Activities, recebimento de webhooks do Event Stream |
| **O painel do OneSignal** | Conteúdo e segmentação que devem mudar sem uma nova versão | Mensagens in-app, o template de email, segmentos, Conversion Metrics, o Event Stream |

O **External ID** conecta os três. O Clean Beans o define como o ID de usuário do Supabase no login, para que o backend possa se dirigir a qualquer pessoa usando um ID que já armazena.

![Diagrama de arquitetura mostrando o aplicativo Expo, o backend Supabase e o painel do OneSignal](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/clean-beans-architecture.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=b6d5655991cdf5b4de0645b9d7f9cd95)

O aplicativo, o backend e o painel se comunicam com o OneSignal. O External ID os vincula a um único usuário.

## Mapa de recursos \\

| O que o aplicativo precisava | Recurso do OneSignal | Página |
| - | - | - |
| Saber a quem pertence cada dispositivo | External ID, Subscription de email | [Configuração do SDK e identidade do usuário](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-sdk-setup.md) |
| Personalizar e segmentar | Tags, eventos personalizados, Conversion Metrics | [Tags, eventos personalizados e Conversion Metrics](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-tags-events.md) |
| Lembrar as pessoas das tarefas | API Create message a partir de funções agendadas | [Enviar push a partir do seu backend](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-backend-push.md) |
| Contar aos colegas de casa o que aconteceu | API Create message a partir de eventos do aplicativo e do banco de dados | [Enviar push a partir do seu backend](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-backend-push.md) |
| Nunca enviar um lembrete duas vezes | Chaves de idempotência | [Push confiável e bem comportado](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-reliable-push.md) |
| Fazer cada push se comportar de forma adequada | Expiração, agrupamento, níveis de interrupção, badges | [Push confiável e bem comportado](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-reliable-push.md) |
| Abrir a tela certa a partir de um toque ou link | Listener de clique, deep links, Universal Links | [Deep links e cliques em notificações](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-deep-links.md) |
| Permitir agir diretamente a partir de uma notificação | Botões de ação, entrega agendada | [Deep links e cliques em notificações](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-deep-links.md) |
| Orientar e incentivar as pessoas dentro do aplicativo | Mensagens in-app com gatilhos e HTML personalizado | [Mensagens in-app](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-in-app-messages.md) |
| Enviar um resumo semanal | Template de email com `custom_data` | [Email semanal com custom\_data](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-weekly-email.md) |
| Comprovar que um número de telefone pertence ao usuário | SMS para um número de telefone bruto, Subscription de SMS | [SMS: códigos de verificação e convites](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-sms.md) |
| Convidar pessoas que não têm o aplicativo | SMS e email para contatos brutos | [SMS: códigos de verificação e convites](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-sms.md) |
| Mostrar uma contagem regressiva na tela de bloqueio | Live Activities | [Live Activities](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-live-activities.md) |
| Manter um histórico de notificações no aplicativo | Event Streams | [Caixa de entrada de notificações com Event Streams](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-inbox.md) |
| Manter as configurações do aplicativo alinhadas com os cancelamentos | Event Streams (eventos de email) | [Caixa de entrada de notificações com Event Streams](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-inbox.md) |

## O que você precisa \\

* Um app do OneSignal com push configurado para iOS e Android, e com email e SMS configurados. Consulte [Configuração de canais](https://documentation.onesignal.com/docs/pt-BR/channel-setup.md).
* Um aplicativo Expo compilado com EAS Build. O SDK do OneSignal precisa de código nativo, então o Expo Go não é suficiente. Consulte [Configuração do SDK Expo](https://documentation.onesignal.com/docs/pt-BR/react-native-expo-sdk-setup.md).
* Seu App ID e uma App API key. Consulte [Chaves e IDs](https://documentation.onesignal.com/docs/pt-BR/keys-and-ids.md).
* Um backend que possa executar código em um agendamento e em resposta a solicitações. O Clean Beans usa Supabase Edge Functions com `pg_cron`. Os mesmos padrões se aplicam a qualquer backend.

## Princípios que se mostraram válidos \\

* **Defina o External ID primeiro.** Quase todos os recursos aqui dependem dele. Use um ID que seu backend já armazena.
* **Coloque cada tarefa onde ela pertence.** O aplicativo cuida do dispositivo e do usuário conectado. O backend cuida dos agendamentos e das mudanças de dados. O painel guarda tudo o que você quer mudar sem uma nova versão.
* **Verifique antes de enviar.** Todo envio do backend verifica as preferências do usuário e confirma que há algo que vale a pena dizer.
* **Torne os envios agendados repetíveis.** Uma chave de idempotência construída a partir do tipo, do destinatário e da data transforma uma nova tentativa em uma operação sem efeito.
* **Roteie por tipo, não por URL.** Um campo `data.type` mantém as notificações antigas funcionando quando as telas mudam.
* **Verifique o que os chamadores informam.** Uma função que envia mensagens deve primeiro confirmar os fatos no seu próprio banco de dados.

## Todos os recursos em resumo \\

| Recurso | Canal | Gatilho | Executa em | Arquivo principal |
| - | - | - | - | - |
| Inicialização do SDK e permissão | Push | Abertura do aplicativo | Aplicativo | `app/_layout.tsx` |
| Identidade do usuário | Todos | Login e logout | Aplicativo | `app/_layout.tsx` |
| Subscription de email | Email | Login | Aplicativo | `src/lib/onesignalSync.ts` |
| Opt-in e preferências | Push, email | Tela de configurações | Aplicativo e banco de dados | `app/notification-settings.tsx` |
| Tags | Todos | Login, sessão, edição de perfil | Aplicativo | `src/lib/onesignalSync.ts` |
| Eventos personalizados | Todos | Início e fim da sessão | Aplicativo | `src/lib/onesignalSync.ts` |
| Conversion Metrics | Todos | Fim da sessão | Painel | |
| Resumo diário | Push | Agendamento por hora | Backend | `supabase/functions/send-daily-digest/` |
| Lembrete de tarefas atrasadas | Push | Agendamento por hora | Backend | `supabase/functions/send-overdue-reminders/` |
| Lembrete de limpeza | Push | Agendamento por hora | Backend | `supabase/functions/send-cleaning-reminder/` |
| Sessão concluída | Push | Chamada a partir do aplicativo | Backend | `supabase/functions/session-completed/` |
| Kudos | Push | Chamada a partir do aplicativo | Backend | `supabase/functions/send-kudos/` |
| Entrada aprovada | Push | Gatilho do banco de dados | Backend | `supabase/functions/join-approved/` |
| Envios idempotentes | Push, email | Todo envio agendado | Backend | `supabase/functions/_shared/idempotency.ts` |
| Perfis de entrega | Push | Todo push | Backend | `supabase/functions/_shared/delivery.ts` |
| Badges | Push | Pushes de tarefas | Backend | `supabase/functions/send-daily-digest/` |
| Roteamento de toques | Push | Toque em um push | Aplicativo | `app/_layout.tsx` |
| Botões de ação | Push | Toque em um botão do push | Backend e aplicativo | `supabase/functions/_shared/buttons.ts`, `src/lib/pushActions.ts` |
| Lembrete adiado | Push | Botão de adiar | Backend | `supabase/functions/snooze-reminder/` |
| Reescrita de links | Links | Aplicativo aberto a partir de uma URL | Aplicativo | `app/+native-intent.tsx` |
| Universal Links e App Links | Links | Toque em um link web | Aplicativo e site | `app.json`, `website/.well-known/` |
| Sobreposições de ajuda e tutoriais guiados | In-app | Botão de ajuda | Aplicativo e painel | `src/components/HelpButton.tsx` |
| Pré-solicitação de permissão de push | In-app | Público do painel | Painel | `docs/iam-html/push-permission-prompt.html` |
| Aviso de atualização do aplicativo | In-app | Versão antiga do aplicativo | Painel | `docs/iam-html/app-update-prompt.html` |
| Pedido de avaliação | In-app | Marco de sequência | Aplicativo e painel | `src/lib/reviewPrompt.ts` |
| Relatório semanal | Email | Agendamento semanal | Backend e painel | `supabase/functions/weekly-report/` |
| Subscription de SMS | SMS | Número de telefone verificado, login | Aplicativo | `src/lib/phone.ts` |
| Código de verificação de telefone | SMS | Chamada a partir do aplicativo | Backend | `supabase/functions/send-otp/`, `supabase/functions/verify-otp/` |
| Convite para a casa | SMS, email | Chamada a partir do aplicativo | Backend | `supabase/functions/send-invite/` |
| Alerta de sequência | Live Activity | Agendamento por hora | Backend e widget | `supabase/functions/streak-warning/` |
| Lembrete de limpeza | Live Activity | Agendamento por hora | Backend e widget | `supabase/functions/cleaning-activity/` |
| Caixa de entrada de notificações | Event Streams | Todo push enviado ou clicado | Backend e aplicativo | `supabase/functions/inbox-webhook/` |
| Sincronização de preferências de email | Event Streams | Email cancelado, rejeitado ou marcado como spam | Backend | `supabase/functions/inbox-webhook/` |

## Segredos \\

As funções de backend os leem do seu ambiente. Nenhum deles é incluído no aplicativo.

```bash theme={null}
supabase secrets set ONESIGNAL_APP_ID=YOUR_ONESIGNAL_APP_ID
supabase secrets set ONESIGNAL_REST_API_KEY=YOUR_APP_API_KEY
supabase secrets set ONESIGNAL_WEEKLY_TEMPLATE_ID=YOUR_EMAIL_TEMPLATE_ID
supabase secrets set INBOX_WEBHOOK_SECRET=YOUR_SHARED_SECRET
supabase secrets set OTP_HASH_SECRET=A_LONG_RANDOM_STRING    # key for hashing SMS verification codes

# Optional
supabase secrets set ONESIGNAL_SMS_FROM=YOUR_SMS_SENDER      # if no default sender is set in the dashboard
```

> [!WARNING]
>
> Sua App API key pode enviar mensagens para todos os usuários. Mantenha-a no seu backend. O aplicativo precisa apenas do App ID.


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