Skip to main content
Use este guia para entender e controlar o que acontece com suas notificações push depois que elas são exibidas em um dispositivo: o que clicar e dispensar fazem, quando o Android reexibe notificações, como os badges permanecem sincronizados e quais ferramentas do SDK permitem gerenciar a bandeja a partir do código do seu app. Esta página cobre push móvel (Android e iOS). Para o comportamento de web push, consulte Comportamento de notificações web push.

​
Ciclo de vida da notificação na bandeja

Cada notificação do OneSignal exibida em um dispositivo é rastreada pelo SDK. O que acontece em seguida determina se ela pode reaparecer:
No Android, sempre limpe notificações com os métodos do SDK do OneSignal em vez do NotificationManager.cancel() ou cancelAll() nativos do Android. Notificações canceladas com as APIs nativas não são marcadas como dispensadas, então o SDK as restaura na próxima vez que o app reiniciar.

​
Comportamento de clique e dispensa

Clicar em uma notificação abre seu app (ou a URL de lançamento da notificação), remove a notificação da bandeja e dispara o callback addClickListener() com o payload da notificação e o ID do botão de ação clicado. Se a notificação clicada pertence a um grupo, o SDK atualiza ou remove o resumo do grupo. Notificações clicadas nunca são restauradas. Dispensar uma notificação (deslizá-la para fora ou tocar em Limpar tudo na bandeja) a marca como dispensada e atualiza a contagem do badge e qualquer resumo de grupo. Notificações dispensadas nunca são restauradas. O SDK não fornece um listener de dispensa; a dispensa é rastreada internamente. Notificações exibidas enquanto seu app está em primeiro plano passam primeiro pelo listener de ciclo de vida em primeiro plano, onde você pode impedir a exibição.

​
Notificações restauradas (Android)

O Android pode remover notificações à força sem ação do usuário: na reinicialização do dispositivo, atualização do app e encerramento forçado (incluindo gerenciadores de bateria agressivos em alguns dispositivos). O SDK do Android reexibe (restaura) automaticamente as notificações afetadas na próxima vez que o app inicia a frio, para que mensagens entregues que o usuário nunca viu ou dispensou não sejam perdidas. Notificações restauradas reaparecem silenciosamente na categoria Restored de baixa importância. Apenas notificações que não foram clicadas ou dispensadas, que estão dentro do seu TTL e que foram recebidas nos últimos 7 dias são restauradas, até 49 notificações. As regras de elegibilidade completas e os controles estão em Notificações restauradas (Android). Para reduzir restaurações, use um ttl mais curto ao enviar ou limpe notificações consumidas com os métodos do SDK abaixo. O iOS não tem comportamento de restauração.

​
Comportamento do badge

No iOS, os badges são definidos pelo payload da notificação (ios_badgeType e ios_badgeCount) e requerem um App Group para que a extensão de serviço possa atualizar as contagens com precisão. Por padrão, o SDK limpa o badge quando o app abre. No Android, o badge do ícone do app reflete o número de notificações OneSignal ativas na bandeja e é gerenciado através de categorias de notificação. O SDK atualiza a contagem automaticamente quando notificações são exibidas, dispensadas, clicadas ou limpas, e a redefine para 0 quando você chama clearAllNotifications(). Configuração, opções por plataforma e solução de problemas são abordadas em Badges.

​
Limpando notificações programaticamente

Limpe notificações quando seu conteúdo tiver sido consumido no seu app, não em eventos de ciclo de vida do app. Os padrões comuns:
  • Sincronização de conteúdo consumido: o usuário abre a tela para a qual as notificações apontam (uma caixa de entrada, central de mensagens ou feed de atividades), então as notificações agora são redundantes. Limpe todas elas, ou use os métodos direcionados se apenas parte do conteúdo foi consumida.
  • Logout: limpe tudo para que as notificações do usuário anterior não fiquem visíveis para o próximo usuário.
Evite limpar a cada abertura ou retorno ao primeiro plano do app para “manter a bandeja limpa”. As notificações na bandeja impulsionam o reengajamento, e limpá-las remove esse ponto de entrada. Se você está gerenciando o acúmulo de notificações, use collapse_id ao enviar para substituir notificações em vez de empilhá-las, ou um TTL mais curto para expirar as não entregues.

​
clearAllNotifications()

Remove as notificações do seu app da bandeja e redefine a contagem do badge para 0. No Android, isso remove apenas notificações criadas pelo OneSignal e as marca como dispensadas para que não sejam restauradas. No iOS, isso remove todas as notificações entregues do seu app, incluindo notificações locais e pushes de outros provedores. Consulte a referência completa do método.
Se você limpa na abertura do app para evitar notificações restauradas, restrinja a chamada ao Android em apps multiplataforma. No iOS ela também remove notificações locais e pushes de outros provedores.

​
removeNotification() e removeGroupedNotifications() (Android)

Remova uma única notificação pelo seu ID de notificação Android, ou todas as notificações de um grupo pela sua chave de grupo. Notificações removidas são marcadas como dispensadas e não são restauradas. Use esses métodos quando apenas parte do conteúdo da bandeja foi consumida, como uma conversa entre várias. Consulte a referência do método.

​
Dispensar notificações automaticamente após um intervalo

Não existe um parâmetro de envio que remova uma notificação exibida após um determinado tempo. O que é possível difere por plataforma:
  • Android 8.0 (API 26) e mais recentes: defina um timeout em uma extensão de serviço de notificação usando setTimeoutAfter(). O Android remove a notificação da aba quando o timeout expira. Em dispositivos abaixo da API 26, a chamada é ignorada e a notificação permanece até que o usuário interaja com ela.
  • iOS: não suportado. O iOS não tem forma de expirar automaticamente uma notificação entregue. As opções mais próximas são substituí-la por uma notificação mais recente via collapse_id, ou removê-la de uma Notification Service Extension com o removeDeliveredNotifications(withIdentifiers:) da Apple quando um push posterior chegar.
Para tornar o timeout por mensagem em vez de fixo no código, envie a duração em additionalData e leia-a do evento na sua extensão de serviço.
Uma notificação removida por setTimeoutAfter() é dispensada pelo sistema, então o SDK do OneSignal não a restaura. Não confunda isso com o ttl, que controla por quanto tempo uma mensagem não entregue aguarda um dispositivo offline e nunca remove uma notificação exibida.

​
Personalizando notificações com extensões de serviço

As extensões de serviço são executadas antes de uma notificação ser exibida, permitindo modificar sua aparência, receber dados em segundo plano ou impedir a exibição completamente:
  • No Android, implemente INotificationServiceExtension e use setExtender() para alterar as opções do NotificationCompat, ou chame event.preventDefault() para suprimir a exibição.
  • No iOS, use uma UNNotificationServiceExtension (a OneSignalNotificationServiceExtension criada durante a configuração) para mídia rica, incrementos de badge e entrega confirmada.
No Android, sua extensão de serviço também é executada para notificações restauradas. Efeitos colaterais em onNotificationReceived (chamadas de analytics, requisições de API, gravações em banco de dados) são executados novamente quando as notificações são restauradas, e alterações do extender como setChannelId() também se aplicam às restaurações, o que pode fazê-las alertar de forma sonora. Projete sua extensão para que as opções de alerta se apliquem apenas a notificações recém-entregues.

​
FAQ

​
Por que notificações antigas reaparecem quando o app abre no Android?

O SDK do Android restaura notificações que foram removidas à força da bandeja, como após uma reinicialização do dispositivo, atualização do app ou encerramento forçado. Notificações que o usuário dispensou ou clicou não são restauradas. Consulte Notificações restauradas (Android) para as regras de elegibilidade e os controles.

​
O TTL remove uma notificação da bandeja depois que ele expira?

Não. O TTL controla por quanto tempo uma mensagem não entregue aguarda um dispositivo offline, e no Android ele também limita quais notificações podem ser restauradas. Ele nunca remove uma notificação já exibida na bandeja. Para remover notificações exibidas, use os métodos de limpeza. Para removê-las após um determinado tempo no Android, consulte Dispensar notificações automaticamente após um intervalo.

​
Posso limpar o badge sem limpar a bandeja?

Sim no iOS: o badge é limpo automaticamente quando o app abre (a menos que esteja desabilitado), deixando o conteúdo da bandeja intacto. No Android, o badge reflete as notificações ativas na bandeja, então ele não pode ser definido independentemente delas. Consulte Badges.

​
Existe um listener para quando um usuário dispensa uma notificação?

Não. O SDK rastreia a dispensa internamente para evitar restaurar notificações dispensadas, mas não expõe um evento de dispensa. O listener de clique cobre apenas cliques.

Referência do SDK móvel

Referência completa para métodos e listeners de notificação.

Payload OSNotification

Campos do payload e regras de notificações restauradas.

Extensões de serviço móvel

Intercepte e personalize notificações antes da exibição.