Migrando para o OneSignal

• Desenvolvedores implementando o SDK OneSignal
• Profissionais de marketing gerenciando campanhas e análises

​

Pré-requisitos

• Configure uma conta em OneSignal
• Convide sua equipe

​

Passos de migração

​

1. Audite sua configuração de mensagens atual

• As plataformas que você suporta: iOS, Android, Web, email, SMS, etc.
• O código que manipula eventos de push e mensagens in-app:
  • Exibição em primeiro plano e manipulação de cliques
  • Uso de deep link para push, email, etc.
  • Manipulação de token push e payload
• Como você está coletando endereços de email, números de telefone, tokens push, etc.
• Domínios de email e propriedade de DNS
• Remetentes SMS e mecanismos de opt-in

• Os tipos de mensagens que você envia (transacionais, marketing, etc.) e os templates para cada um
• Como você segmenta e direciona usuários
• As análises ou métricas de conversão que você rastreia

​

2. Mapeie sua terminologia para o OneSignal

​

3. Adicione o SDK OneSignal (desenvolvedores)

• login — Define o External ID para identificar um usuário entre dispositivos e canais.
• addEmail — Cria uma subscription de email a partir de um endereço coletado no seu aplicativo ou site.
• addSms — Cria uma subscription de SMS a partir de um número de telefone coletado no seu aplicativo ou site.

​

4. Remova sua implementação legada

• Migração limpa — Remova completamente o SDK antigo e substitua-o pelo OneSignal em um único lançamento de aplicativo. Esta é a abordagem recomendada.
• Migração em fases — Mantenha ambos os SDKs temporariamente, enviando de cada provedor para grupos de usuários diferentes com base na versão do aplicativo. Use isso somente se não for possível remover o SDK antigo em um único lançamento.

​

Conflitos e formato de token push

• Obtenha o identificador de token push do dispositivo usando nosso SDK Mobile Frontend
• Obtenha o identificador do dispositivo usando nossa API View user

​

Conflito com o Firebase Messaging SDK

• Remova os receivers legados do Firebase do AndroidManifest.xml.
• Não chame FirebaseMessaging.getToken() ou FirebaseMessaging.deleteToken().
• Certifique-se de que o OneSignal seja o único SDK gerenciando o ciclo de vida do token push.

​

Manipulação de payload push

​

Migração em fases (apenas aplicativos mobile)

• Deixe o OneSignal gerenciar tokens push exclusivamente. Compartilhe o token com seu sistema antigo se necessário (consulte Conflitos de token push acima).
• Atualize os filtros de payload para que seu SDK legado ignore os pushes do OneSignal (consulte Manipulação de payload push acima).
• Envie do seu provedor antigo para usuários na versão antiga do aplicativo e do OneSignal para usuários na versão mais recente.
• Defina uma data de corte clara e um plano de eliminação gradual.

​

5. Migração de web push

1. Remova o código do SDK legado e os arquivos de Service Worker do seu site.
2. Adicione o trecho a seguir para cancelar o registro do Service Worker antigo. Substitua sw.js pelo nome do arquivo de Service Worker do seu provedor legado.

if ('serviceWorker' in navigator) {
  navigator.serviceWorker.getRegistrations().then(function(registrations) {
    for (let registration of registrations) {
      if (registration.active.scriptURL.includes("sw.js")) {
        registration.unregister();
      }
    }
  });
}

​

Migrando entre aplicativos OneSignal

• Subscriptions de web push não podem ser transferidas diretamente entre aplicativos. Cada subscription está vinculada tanto ao domínio (origin) do seu site quanto ao OneSignal App ID.
• Para migrar, atualize o código de inicialização do OneSignal no seu site para usar o appId do App B:

OneSignal.init({
  appId: "YOUR_APP_B_ID",
});

• Quando um usuário revisita seu site, a permissão push existente do navegador permitirá que o OneSignal os registre silenciosamente no App B.
• Nenhum novo prompt de permissão será exibido, mas os usuários devem visitar seu site pelo menos uma vez para que a subscription seja criada no App B.
• Assinantes continuarão a aparecer no App A até se tornarem inativos.

​

6. Configuração de email e SMS

​

7. Importar usuários existentes (opcional)

​

Considerações de plataforma

• Endereços de email devem ser de usuários ativos e válidos. Não importe endereços de email que nunca clicaram ou abriram emails antes.
• Números de telefone devem estar em um formato específico e os usuários devem ter consentido em receber SMS.
• Subscriptions iOS podem começar a receber notificações push imediatamente após a importação. Recursos como rastreamento de cliques de notificação e entregas confirmadas requerem que nosso SDK esteja ativo no dispositivo.
• Subscriptions Android/Huawei/Amazon devem ter nosso SDK ativo no dispositivo para receber notificações, seja através de uma atualização automática ou manual.
• Subscriptions web não podem ser importadas. Se você seguir o descrito acima em Migração de web push, a subscription de web push será criada e o token push obtido via nosso SDK quando o usuário retornar ao site.

​

Passos de importação

1. Revise os documentos de Users e Subscriptions.
2. Exporte dados de usuários de teste do seu sistema antigo.
3. Formate os dados para a API Create user do OneSignal.
4. Importe usuários de teste primeiro. Após a verificação, repita o processo para os usuários restantes antes do lançamento.

​

8. Testar a migração

1. Habilite o Debug Logging no SDK OneSignal.
2. Teste em dispositivos reais para todas as plataformas (Android, iOS, Web, etc.).
3. Verifique o tratamento de notificações em primeiro plano e em segundo plano.

• Envie notificações de teste do OneSignal para usuários importados antes de adicionar o SDK OneSignal.
  • Você deve receber o push no iOS, mas não obterá entrega confirmada ou análises de cliques.
  • Você pode receber o push no Android se tiver outro SDK push e ainda não implementou os requisitos de Manipulação de payload. A notificação provavelmente estará com dados faltando e não funcionará como esperado quando clicada.
• Envie notificações de teste do OneSignal para usuários importados depois de adicionar o SDK OneSignal.
  • Você deve receber o push em Android e iOS junto com entrega confirmada e análises de cliques.
• Teste o comportamento de notificação com o aplicativo em diferentes estados.
• Verifique se deep links e ações personalizadas funcionam corretamente.

• Envie de ambos, seu provedor atual e o OneSignal.
• Verifique se há notificações duplicadas.
• Verifique se as notificações de cada provedor são exibidas corretamente.
• Teste cenários de login/logout de usuário.

​

Checklist de pré-lançamento

• Crie um plano de mensagens para incentivar atualizações do aplicativo
• Considere usar push e mensagens in-app do seu sistema antigo para lembrar gentilmente os usuários a atualizarem.

• Verifique se as análises de push e mensagens in-app estão funcionando como esperado.
  • Eventos de clique e entrega confirmada são rastreados em Android e iOS.
• Verifique se eventos de clique e eventos recebidos em primeiro plano são tratados corretamente para mensagens enviadas de ambos os provedores.
• Se estiver importando usuários, exporte usuários Android e iOS que estiveram ativos em seu aplicativo nos últimos 270 dias para evitar a importação de tokens expirados. Consulte FCM Expired Token FAQ para detalhes.

​

Lance seu aplicativo/site

• A maioria dos usuários terá seus aplicativos atualizados automaticamente para a versão mais recente.
• Quando os usuários abrirem seu aplicativo atualizado, eles não serão solicitados a se inscrever em notificações push se as permissões já foram concedidas — seja através dos prompts de permissão necessários ou das configurações de notificação do aplicativo.

• Os usuários serão criados automaticamente no OneSignal quando abrirem a versão atualizada do aplicativo. Eles não serão solicitados para push se já estiverem inscritos anteriormente.
• Você precisará esperar que eles abram o aplicativo atualizado antes de poder enviar mensagens para eles.
• Continue enviando notificações e mensagens in-app do provedor push anterior por alguns dias até que usuários suficientes apareçam no OneSignal. Envie alertas adicionais pedindo que atualizem o aplicativo para a versão mais recente.

​

Monitorar resultados

• Monitore taxas de erro e crashes após a implantação.
• Fique atento a invalidações inesperadas de token.
• Verifique análises de integração do SDK.

• Marque a data de lançamento do aplicativo e confirme com seus desenvolvedores qual caminho de migração foi adotado (limpa ou em fases) e se os usuários foram importados.
• Na sua plataforma anterior, crie um segmento de usuários que ainda não atualizaram para a nova versão do aplicativo. Continue enviando do seu provedor antigo para esse grupo, incentivando-os a atualizar.
• Pare de enviar do provedor anterior assim que as contagens de assinantes se estabilizarem no OneSignal.
• Se estiver seguindo uma migração em fases, remova o SDK do provedor antigo no próximo lançamento do aplicativo após a data de corte.

​

Perguntas frequentes

​

Posso executar o OneSignal junto com meu provedor push atual?

​

Posso importar assinantes de web push?

​

Preciso solicitar permissão de push novamente após a migração?

​

É necessário aquecimento de email?

​

Posso obter um endereço IP dedicado?

​

Por quanto tempo devo continuar enviando do meu provedor antigo?