Assinaturas

​

Visão geral

Uma Assinatura representa um canal específico pelo qual um usuário pode receber mensagens—como um endereço de email, número de telefone ou dispositivo. O OneSignal suporta quatro tipos de Assinaturas: Cada usuário pode ter múltiplas Assinaturas. Use o ID Externo para identificar o usuário em todas as Assinaturas. Na imagem acima, “userA” tem 5 Assinaturas:

1. Mobile (iOS) criada após instalar o app iOS. Chame OneSignal.login para definir o ID Externo e vincular a Assinatura ao usuário.
2. SMS criada após o número de telefone ser fornecido dentro do app iOS. Veja Assinaturas SMS abaixo para detalhes.
3. Web Push criada após se inscrever para push no website. Pode receber notificações push.
4. Email criada após o endereço de email ser fornecido. Para envio de mensagens de email.
5. Mobile (Android) criada após instalar o app Android. Pode receber notificações push, mensagens in-app e live activities.

---

​

Propriedades da Assinatura

Cada Assinatura tem as seguintes propriedades:

​

Status de assinatura

Geralmente, as Assinaturas podem receber mensagens (Subscribed) ou não podem (Unsubscribed). Os detalhes variam por canal:

---

​

notification_types

Indica a capacidade da Assinatura de receber mensagens, incluindo razões para falhas. Atualizado automaticamente via SDKs frontend ou manualmente via API. Visualizável via View User API ou Export CSV.

Definições de Notification Types.

1 ou número positivo = Subscribed.

• A Assinatura pode receber mensagens neste canal.
• Pode ser usado com a propriedade enabled se você estiver habilitando mensagens em nome do usuário. Para Assinaturas push, um token válido ainda deve ser definido para receber notificações push. Veja nossa documentação de configuração do SDK para detalhes.

0, -99 = Never Subscribed.

• A Assinatura ainda não se inscreveu no canal.

-2 = Unsubscribed.

• A Assinatura não pode receber mensagens neste canal.
• Pode ser usado com a propriedade enabled definida como false se você estiver desativando mensagens em nome do usuário. Valor recomendado ao desativar permissões de mensagem.
• Definido automaticamente quando o usuário cancela a inscrição.

-3, -5 = Android Support Library Error.Adicione ou atualize a Android Support Library do seu app.-4, -8, -11, -12 = Android Google Play Services Library Error.

• Verifique o logcat. Veja Getting a Debug Log.
• Atualize sua Google Play Services Library no seu app e verifique o logcat do app para erros do Google Play Services. Veja Getting a Debug Log.

-6 = Android Invalid Google Project Number.

• O FCMv1 Sender ID não corresponde ao original ao qual este token pertence. Verifique o logcat do app. Veja Getting a Debug Log.

-7, -9 = Android Outdated Google Play Services App

• Atualize ou habilite o app Google Play Services no dispositivo.

-10 = Not Subscribed.

• Assinatura Push desinstalou o app ou cancelou inscrição nas configurações do dispositivo.
• Web push bloqueou notificações, limpou todos os dados e workers.

-13 = iOS missing_push_capability.

• Revise a documentação de configuração do SDK para garantir que todas as etapas sejam implementadas. Veja Channel setup.

-14, -16, -17 = iOS APNS Errors.

• O dispositivo está tendo um problema ao conectar ao APNS. Verifique o guia Troubleshooting iOS e Getting a Debug Log.

-15 = iOS Simulator Error.

• O iOS Simulator requer iOS 16.4+. Use um simulador ou dispositivo diferente.

-18 = Never Prompted.

• A Assinatura nunca foi solicitada a se inscrever. Isso rastreia apenas o prompt de permissão obrigatório e não inclui mensagens in-app.

-19 = Prompted But Never Answered.

• A Assinatura foi solicitada mas não forneceu uma resposta.

-20, -21 = temp_web_record. Web, permissão pushSubscriptionchange revogada-22 = Manually Unsubscribed via dashboard.

• Permissão foi revogada.

-23, -24 = Web Service Worker Error.

• Veja Web SDK troubleshooting.

-31 = Disabled via REST API.-98 = SMS Subscription aguardando double opt-in.

---

​

Assinaturas Mobile

Assinaturas Mobile representam dispositivos iOS, Android, Huawei ou Amazon e suportam:

• Notificações push
• Mensagens in-app
• Live Activities

Elas são criadas automaticamente quando um usuário instala e abre seu app com o OneSignal SDK.

​

Atualizando Assinaturas mobile

Atualize as propriedades de Assinatura Mobile usando o OneSignal mobile SDK.

• Solicitar permissões push e observar mudanças de permissão/Assinatura
• Fazer login de usuários para definir ID Externo e Aliases
• Adicionar Tags
• Definir Idioma

Você pode atualizar tags, idioma e algumas outras propriedades via recurso CSV Import. Assinaturas Mobile também podem ser criadas e atualizadas via APIs Users e Subscriptions, mas o mobile SDK é recomendado para a maioria dos casos de uso.

​

Tratamento de desinstalações, cancelamentos e tokens push inválidos

Assinaturas Mobile param de receber notificações push se o usuário:

• Desinstalar o app
• Desabilitar push nas configurações do dispositivo e nunca reabrir o app
• Token push expirar

Nesses casos, o status da Assinatura será definido como Unsubscribed ao enviar notificações push. Veja abaixo Quando os status de assinatura push são atualizados? para mais detalhes.

• Se o usuário reinstalar o app no mesmo dispositivo ou em um novo dispositivo, uma nova Assinatura será criada e ele precisará se reinscrever para receber mensagens.
• Se o usuário reabilitar push nas configurações do dispositivo, o status da Assinatura será definido como Subscribed e um token push será atualizado quando ele abrir o app.
• Se o token push expirar, o status da Assinatura e o novo token push serão atualizados quando o usuário abrir o app no mesmo dispositivo.

Rastreie mudanças via:

• Event Streams - detectar cancelamentos ao enviar push
• Relatórios de push - detectar cancelamentos ao enviar push
• Use o listener de mudança de Assinatura do SDK - detectar cancelamentos quando o usuário desabilita push nas configurações do dispositivo e depois abre o app

---

​

Assinaturas Web push

Assinaturas Web push estão vinculadas a um dispositivo específico, navegador e perfil do navegador. Um usuário que se inscreve no Chrome desktop não receberá push no Chrome mobile a menos que também se inscreva no seu website a partir daquele dispositivo móvel—criando uma Assinatura web push separada. Novas Assinaturas web push são criadas nestes cenários:

• O usuário se inscreve no seu website clicando em “Permitir” no prompt de permissão nativo em nível de sistema do navegador. Isso gera um token push único e ID de Assinatura.
• O usuário limpa dados do navegador (histórico, cache, cookies, armazenamento local) e revisita seu site. Isso resulta na criação de um novo ID de Assinatura único.

​

Atualizando Assinaturas web push

Atualize as propriedades de Assinatura web push usando o OneSignal web SDK.

• Solicitar permissões push e observar mudanças de permissão/Assinatura
• Fazer login de usuários para definir ID Externo e Aliases
• Adicionar Tags
• Definir Idioma

Você pode atualizar tags, idioma e algumas outras propriedades via recurso CSV Import. Assinaturas Web push não podem ser criadas via REST API. Você pode atualizá-las com as APIs Users e Subscriptions, mas o web SDK é recomendado para a maioria dos casos de uso.

​

Tratamento de cancelamentos e tokens push inválidos

Assinaturas Web push param de receber notificações push se o usuário:

• Limpar dados do navegador (histórico, cache, cookies, armazenamento local)
• Desabilitar push nas configurações do sistema do navegador
• Token push expirar

Nesses casos, o status da Assinatura será definido como Unsubscribed ao enviar notificações push. Veja abaixo Quando os status de assinatura push são atualizados? para mais detalhes.

• Se o usuário retornar ao site após limpar dados do navegador, uma nova Assinatura será criada e ele será automaticamente reinscrito para receber mensagens se você tiver auto-resubscribe habilitado.
• Se o usuário reabilitar push nas configurações do navegador, o status da Assinatura será definido como Subscribed quando ele retornar ao site.
• Se o token push expirar, o status da Assinatura e o novo token push serão atualizados quando o usuário retornar ao site.

Rastreie mudanças via:

• Event Streams - detectar cancelamentos ao enviar push
• Relatórios de push - detectar cancelamentos ao enviar push
• Use o listener de mudança de Assinatura do SDK - detectar cancelamentos quando o usuário desabilita push e depois retorna ao site

---

​

Assinaturas Email

Assinaturas Email são baseadas no endereço de email e usadas apenas para entrega de email. Isso é diferente de definir uma Tag. Crie Assinaturas Email via:

1. Método addEmail do SDK ou prompt de email - use esses métodos após chamar OneSignal.login para definir o ID Externo e vincular a Assinatura ao usuário.
2. API Create user ou API Create email
3. Importador CSV do Dashboard ou adicionar endereços de email manualmente

​

Gerenciando Assinaturas email

Vincular a um usuário Certifique-se de definir o external_id ao criar Assinaturas de Email para vinculá-las a um User.

• Usando o SDK, chame o método login antes de chamar addEmail para definir o external_id e vincular a Assinatura de email ao usuário.
• Usando o Importador CSV ou REST API, defina o identificador external_id com o email.

Status de assinatura Assinaturas de Email recém-criadas serão automaticamente definidas como Subscribed a menos que especificado de outra forma. Assinaturas Email podem ficar unsubscribed quando:

• Ao enviar emails, o usuário opta por sair via Link de cancelamento de inscrição
• Definir enabled como false via API
• Usar o dashboard para cancelar inscrição da Assinatura via botão de opções Assinaturas Email podem ficar resubscribed via:
• Definir enabled como true via API
• Usar o dashboard para inscrever a Assinatura via botão de opções

Se um usuário cancelar inscrição de emails, você pode mantê-lo como unsubscribed mas enviar-lhe emails importantes enviando para emails com inscrição cancelada.

---

​

Assinaturas SMS

Assinaturas SMS estão vinculadas a números de telefone formatados em E.164 (por exemplo, +14155551234). Crie Assinaturas SMS via:

1. Método addSms do SDK ou prompt SMS — chame OneSignal.login primeiro para definir o ID Externo e vincular a Assinatura ao usuário.
2. API Create user ou Create SMS
3. Importador CSV do Dashboard

​

Gerenciando Assinaturas SMS

Vincular a um usuário Defina o external_id ao criar Assinaturas SMS para vinculá-las a um User.

• Usando o SDK, chame o método login antes de chamar addSms para definir o external_id e vincular a Assinatura SMS ao usuário.
• Usando o Importador CSV ou REST API, defina o identificador external_id com o número de telefone.

Status de assinatura Assinaturas SMS recém-criadas são automaticamente definidas como Subscribed a menos que especificado de outra forma. Assinaturas SMS podem ficar unsubscribed quando:

• O usuário responde com “STOP” ou outra palavra-chave de opt-out
• Você define enabled como false via API
• Você cancela a inscrição da Assinatura no dashboard via botão de opções

Assinaturas SMS podem ficar resubscribed quando:

• O usuário responde com “START” ou outra palavra-chave de opt-in
• Você define enabled como true via API
• Você reinscreve a Assinatura no dashboard via botão de opções

---

​

Importando ou migrando Assinaturas

Importe tokens push, endereços de email e números de telefone de outro provedor usando:

• API Create user
• API Create Subscription

---

​

Deletar Assinaturas

Assinaturas podem ser deletadas para:

• Privacidade de dados
• Limpeza de registros inativos

---

​

FAQ

​

Quando os status de assinatura push são atualizados?

Os status de assinatura push são atualizados por dois mecanismos: 1. Quando o usuário abre seu app ou site O OneSignal SDK verifica se o token push é válido e se as permissões de notificação ainda estão concedidas, e então atualiza o status da assinatura imediatamente. Por exemplo, se um usuário desabilitar notificações push nas configurações do dispositivo e depois reabrir seu app, o SDK detecta a mudança e marca a assinatura como Unsubscribed imediatamente. Você pode capturar essas mudanças com o Subscription Observer do SDK (mobile | web) para sincronizar o status com seu próprio banco de dados. 2. Quando você envia notificações push Se um usuário desinstalar seu app, limpar dados do navegador ou desabilitar push e nunca retornar, o OneSignal não pode detectar a mudança até que você envie uma notificação. O serviço push (FCM, APNs, HMS) reporta o token como inválido e o OneSignal marca a assinatura como Unsubscribed. Essa detecção tipicamente leva 2 ou mais mensagens porque o serviço push não rejeita imediatamente um token inválido: Use Event Streams para detectar cancelamentos em tempo real ao enviar mensagens.

​

Se um usuário desligar notificações nas configurações do dispositivo e nunca abrir o app novamente, o que acontece?

A assinatura permanece marcada como Subscribed no OneSignal até que você envie uma notificação para aquele dispositivo. Após 2 ou mais tentativas de envio, o serviço push reporta o token como inválido e o OneSignal marca a assinatura como Unsubscribed. Veja Quando os status de assinatura push são atualizados? acima para a sequência completa.

---

​

Páginas relacionadas