Migrando para 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.)
  • Templates para essas mensagens
• Como você está segmentando e direcionando usuários.
• As análises ou métricas de conversão que você rastreia.

​

2. Conceitos principais do OneSignal

• Users - Identificados via External ID. Users são compostos de propriedades (tags, dados de sessão, etc.) e subscriptions (push, email, SMS).
• Subscriptions - Refere-se a como um usuário pode receber mensagens. Existem 4 tipos de subscriptions:
  • Mobile: Pode receber notificações push, mensagens in-app e Live Activities.
  • Web push: Pode receber notificações web push.
  • Email: Pode receber notificações de email.
  • SMS: Pode receber notificações SMS.
• Segments - Um grupo de usuários que compartilham propriedades comuns.
• Tags - Uma propriedade de usuário personalizada.
• Custom Events - Uma ação que um usuário realiza.

​

3. Adicione o SDK OneSignal (desenvolvedores)

​

Identifique usuários com External ID

• SDK Mobile
• SDK Web

​

Colete novos emails e números de telefone

• Email subscriptions: use o método addEmail no nosso SDK Mobile e SDK Web
• SMS subscriptions: use o método addSms no nosso SDK Mobile e SDK Web

​

4. Remova sua implementação legada

​

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

• Formato de token APNS Push iOS: 64 caracteres, apenas caracteres hexadecimais (0-9,a-f). deviceToken.map {String(format: "%02x", $0)}.joined()
• Formato de token FCM Push Android: Tipicamente 163 caracteres, caracteres alfanuméricos, pode conter hífens, dois pontos e underscores.

​

Manipulação de payload push

​

Migração em fases (apenas aplicativos mobile)

• Não deixe vários SDKs gerarem tokens push. Deixe o OneSignal lidar com isso e compartilhe o token com seu sistema antigo, se necessário.
  • Use SDK Frontend ou API View user
• Atualize filtros de payload para que seu SDK legado não processe pushes OneSignal.
  • OneSignal usa uma chave "custom" em seu rawPayload (docs).
  • Verifique esta chave em NotificationCompat (Android).
• Decida qual provedor manipula quais tipos de notificações.
• Defina uma data de corte clara e construa um plano de eliminação gradual para sistemas legados.
  • Crie um template de notificação para cada tipo de notificação que você envia.
  • Configure seu provedor antigo para enviar mensagens para usuários na versão antiga do seu aplicativo e OneSignal para enviar mensagens para usuários na versão mais recente do seu aplicativo.
  • Crie segmentos para direcionar grupos específicos de usuários.

​

5. Migração de web push

• Você não pode importar subscriptions de web push devido a limites de segurança do navegador. OneSignal registrará usuários quando eles retornarem.
• Você deve desregistrar seus service workers push antigos antes que o OneSignal possa assumir.

1. Remova o SDK legado: Código no site e arquivos de Service Worker.
2. Adicione este código para garantir que o Service Worker seja desregistrado.
3. Substitua sw.js pelo nome do arquivo Service Worker de terceiros.

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 OneSignal do 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 aparecerá, 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

​

É necessário aquecimento de email?

​

Posso obter um endereço IP dedicado?

​

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.
• Assinaturas 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.
• Assinaturas Android/Huawei/Amazon devem ter nosso SDK ativo no dispositivo para receber notificações, seja através de uma atualização automática ou atualização manual.
• Assinaturas web não podem ser importadas. Se você seguir o descrito acima em Migração de web push, a assinatura de web push será criada e o token push buscado via nosso SDK quando o usuário retornar ao site.

​

Passos de importação

1. Revise os documentos Users e Subscriptions para compreensão.
2. Exporte dados de usuários de teste do sistema antigo.
3. Formate os dados para a API Create user do OneSignal.
4. Importe usuários de teste e, após testes bem-sucedidos, mantenha o processo para repetir na checklist de pré-lançamento.

• token - O token push ou endereço de email ou número de telefone
• type - O tipo de assinatura: iOSPush, AndroidPush, WebPush, Email, SMS
• external_id - Um identificador único para o usuário. É recomendado ser usado para rastreamento e análises.

  {
    "identity": {
      "external_id": "user_12345"
    },
    "subscriptions": [
      {
        "type": "iOSPush",
        "token": "7abcd49d0affb7426a8f1202420e8f4e2fc4df58e49501adc383f3bd66df8636"
      },
      {
        "type": "AndroidPush",
        "token": "dQGm89TZQXiTvLsRIj_GBo:APA91bpgqFgqkP2qYvV1uW2kdK5Z3TjgCXB_1jkL6VJrgH3hoYn16MvFY19tzDE4OuSgKjYC7itbFpSJYHBfKLWt-xZYBpgCVhYn9K5neV_9-Zj7s9mOSjRUJ2IwEwVSYhR-j5ICF9WB"
      },
      {
        "type": "Email",
        "email": "test@example.com"
      },
      {
        "type": "SMS",
        "phone_number": "+1234567890"
      }
    ]
  }

​

7. Testar a migração

1. Habilite 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á faltando dados 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 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

• Construa um plano de mensagens para solicitar atualizações de 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 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.
• Comunique-se com seus desenvolvedores sobre:
  • Qual caminho de migração foi escolhido (migração Limpa ou Em fases).
  • Os usuários foram importados?
• Se seguindo uma migração Limpa:
  • Na plataforma anterior, crie um segmento ou coorte de usuários que continuam ativos. Verifique seus tempos de sessão, mensagens recebidas e eventos de clique.
  • Apenas usuários que não atualizaram o aplicativo devem continuar ativos e contidos neste grupo.
  • Continue enviando push e mensagens in-app do seu provedor anterior para esses usuários, incentivando-os gentilmente a atualizar.
  • Pare de enviar do provedor anterior até estar pronto para mover completamente para o OneSignal.
• Se seguindo uma migração Em fases:
  • Na plataforma anterior, crie um segmento ou coorte de usuários que têm a versão mais antiga do aplicativo antes do OneSignal.
  • Continue enviando push e mensagens in-app do seu provedor anterior para esses usuários de aplicativos mais antigos, incentivando-os gentilmente a atualizar.
  • Pare de enviar do provedor anterior até estar pronto para mover completamente para o OneSignal.
  • Remova o código do provedor push anterior no próximo lançamento do aplicativo.