Guia de integração básica do módulo Mendix

Este guia explica como adicionar o módulo Pushwoosh a um aplicativo móvel nativo Mendix existente, desde a instalação a partir do Marketplace até o recebimento de uma notificação em um dispositivo.

Pré-requisitos

Para integrar o módulo Pushwoosh em seu aplicativo, você precisará do seguinte:

Requisitos

• Uma conta Pushwoosh.
• Um projeto Pushwoosh configurado na sua conta.
• Para integração com iOS:
  • Uma plataforma iOS configurada para enviar notificações push. Recomendamos usar a configuração de Autenticação Baseada em Token como a abordagem mais simples.
  • Durante a configuração, defina o Gateway como Sandbox para enviar pushes para um simulador.
• Para integração com Android:
  • Uma plataforma Android configurada
  • O arquivo google-services.json e o package name do seu projeto Firebase.
  • Um projeto Firebase conectado ao seu aplicativo Android. Siga o guia de configuração do Firebase se necessário.
• O seu Pushwoosh Application Code e o Token da API de Dispositivo Pushwoosh do Painel de Controle da Pushwoosh para o seu aplicativo.

O Device API Token na lista acima não é necessário para este módulo. O widget utiliza o Application Code e nada mais.

Você também precisará do seguinte:

• Mendix Studio Pro 11.12.3 ou mais recente. O pacote do módulo é construído com essa versão, e o Studio Pro não consegue abrir um pacote produzido por uma versão mais recente que a sua.
• Um perfil de navegação móvel nativo em seu aplicativo.
• Xcode ou Android Studio para produzir a compilação nativa. O aplicativo Make It Native não pode executar este módulo, pois não contém código nativo de terceiros.

1. Instale o módulo a partir do Marketplace

No Studio Pro, clique no ícone do Marketplace no canto superior direito, pesquise por Pushwoosh e clique em Download. O Studio Pro adiciona um módulo chamado Pushwoosh ao seu aplicativo.

Não há mais nada a instalar. As bibliotecas nativas vêm do npm durante a compilação nativa, fixadas na versão exata com a qual o módulo foi testado.

2. Adicione o widget de eventos Pushwoosh à sua página inicial

O widget Pushwoosh events inicia o SDK e transforma notificações push em eventos de nanoflow. Ele não renderiza nada, então coloque-o uma vez, na página que carrega primeiro no perfil de navegação móvel nativo.

1. Abra a página inicial do seu perfil de navegação móvel nativo.
2. Arraste o widget Pushwoosh events para a página. Ele está na categoria Pushwoosh da caixa de ferramentas.
3. Defina a propriedade Application Code para o Application Code do seu aplicativo no Painel de Controle da Pushwoosh. Ele se parece com XXXXX-XXXXX.

Deixe Register on load ativado para registrar o dispositivo assim que o aplicativo abrir. Desative-o se preferir solicitar permissão para notificações mais tarde, em um ponto do aplicativo onde a solicitação faça mais sentido para o usuário. Veja Registre o dispositivo abaixo.

3. Configure a compilação nativa

O Pushwoosh substitui as notificações push integradas de um aplicativo Mendix em vez de funcionar ao lado delas. No Native Mobile Builder, defina as capacidades da seguinte forma:

• Push notifications: desativado.
• Firebase Android: ativado, para que o google-services.json ainda seja reconhecido.

Dois serviços de notificação registrados para o evento com.google.firebase.MESSAGING_EVENT se sobrepõem, e as notificações param de chegar. No Android, o FCM Sender ID vem do google-services.json; ele não é passado para o módulo.

No iOS, adicione a capacidade de Push Notifications ao projeto Xcode gerado em Signing & Capabilities, e envie sua chave APNs para o Painel de Controle da Pushwoosh, conforme descrito no guia de configuração da plataforma iOS.

Compilando no macOS

O Studio Pro para Mac não possui o Native Mobile Builder. Configure o modelo nativo com a ferramenta de linha de comando @mendix/native-mobile-toolkit, e depois compile os projetos iOS e Android gerados localmente com Xcode e Gradle.

4. Registre o dispositivo

Um dispositivo recebe notificações somente após ser registrado no Pushwoosh. Existem duas maneiras de registrar, e você precisa de uma delas.

Registrar ao carregar. Deixe a propriedade Register on load do widget ativada. O dispositivo se registra assim que o widget carrega, e no iOS o prompt de permissão do sistema aparece nesse momento.

Registrar a partir de um nanoflow. Desative Register on load e chame a ação RegisterForPushNotifications a partir de um nanoflow seu, por exemplo, depois que o usuário fizer login ou aceitar uma tela de consentimento. A ação retorna o push token como uma string.

Para interromper a entrega para um dispositivo, chame UnregisterForPushNotifications.

5. Gerencie uma notificação que chega enquanto o aplicativo está aberto

Quando uma notificação chega enquanto o aplicativo está em primeiro plano, o widget escreve a notificação nos atributos que você aponta para ele e, em seguida, aciona o nanoflow em On push received.

1. Defina Message para um atributo de string que recebe o texto da notificação.
2. Defina Payload para um atributo de string que recebe o payload completo como JSON.
3. Defina On push received para um nanoflow que reage a ele, por exemplo, um que mostra uma mensagem ou atualiza uma lista.

Os atributos são preenchidos antes que o nanoflow seja executado, para que o nanoflow possa lê-los imediatamente.

6. Gerencie uma notificação aberta e um deep link

Quando o usuário toca em uma notificação, o widget aciona o nanoflow em On push opened, com os mesmos atributos Message e Payload preenchidos.

Se a notificação contiver um deep link, o widget também escreve o link no atributo definido em Deep link e aciona o nanoflow em On deep link. Esse nanoflow é executado além de On push opened, então use-o para rotear o usuário para a página para a qual o link aponta.

7. Identifique o usuário e defina tags

Tags são o que transforma uma transmissão em uma mensagem direcionada. Chame SetTags de qualquer nanoflow com um objeto JSON como seu parâmetro:

'{"Language":"en","Plan":"pro","Level":7}'

Aspas em expressões Mendix

Uma string em uma expressão Mendix é escrita entre aspas simples, para que o JSON dentro dela mantenha suas aspas duplas sem escape. Escrever "" ou \" dentro da expressão produz uma string que a ação não consegue analisar.

Chame SetUserId com seu próprio identificador de usuário para associar o dispositivo a uma pessoa em vez de a um dispositivo. Todos os dispositivos registrados sob o mesmo ID de usuário podem então ser alcançados com uma única mensagem.

8. Publique eventos

Eventos impulsionam campanhas acionadas e mensagens no aplicativo. Chame PostEvent com o nome do evento e, opcionalmente, um objeto JSON de atributos:

'{"product":"Coffee grinder","price":129}'

O nome do evento deve corresponder ao evento configurado no Painel de Controle da Pushwoosh.

9. Envie uma notificação de teste

Registre o dispositivo como um dispositivo de teste e envie uma mensagem para ele a partir do Painel de Controle da Pushwoosh. Consulte Teste sua integração para ver os passos.

Uma notificação que chega enquanto o aplicativo está aberto é mostrada pelo sistema como um alerta, e o nanoflow On push received também é executado. Para suprimir o alerta do sistema e gerenciar a notificação apenas no nanoflow, chame SetShowForegroundAlert com false. Essa ação funciona apenas no iOS.

10. Verifique a integração quando nada chegar

Siga estes passos em ordem quando o dispositivo não receber notificações:

1. Confirme que o aplicativo é um aplicativo de desenvolvedor personalizado ou uma compilação nativa real. O aplicativo Make It Native não contém o módulo, então toda ação do Pushwoosh falha silenciosamente nele.
2. Confirme as capacidades da compilação nativa: Push notifications desativado, Firebase Android ativado.
3. Confirme que o dispositivo está registrado. Chame GetPushToken e verifique se ele retorna um token em vez de uma string vazia.
4. Confirme que a plataforma está configurada no Painel de Controle da Pushwoosh, com a chave APNs enviada para iOS e a chave do servidor Firebase para Android.

Se o dispositivo ainda não estiver acessível, chame GetHwid e abra um ticket de suporte com esse identificador.

Próximos passos

• Referência de ações do módulo - as propriedades do widget e as ações JavaScript, com parâmetros e valores de retorno
• FAQ do Mendix - as perguntas que surgem durante a primeira integração