Guia de integração básica do SDK do Cordova

Esta seção contém informações sobre como integrar o SDK do Pushwoosh para Cordova em seu aplicativo.

Pré-requisitos

Para integrar o SDK do Pushwoosh para Cordova em seu aplicativo, você precisará do seguinte:

Requisitos

• Uma conta Pushwoosh.
• Um projeto Pushwoosh configurado em 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.
  • Defina o Gateway como Sandbox para enviar pushes para um simulador.
• Para integração com Android:
  • Uma plataforma Android configurada
  • O número do projeto (também conhecido como ID do remetente), o arquivo google-services.json e o nome do pacote 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 Código de Aplicação Pushwoosh e o Token da API de Dispositivo Pushwoosh do Painel de Controle Pushwoosh para o seu aplicativo.

Passos de integração

1. Adicione a Dependência do SDK do Pushwoosh para Cordova

Adicione a dependência do SDK do Pushwoosh para Cordova ao seu projeto:

cordova plugin add pushwoosh-cordova-plugin

2. Inicialização do SDK do Cordova

No componente raiz do seu arquivo index.js, adicione o seguinte código dentro do manipulador de eventos deviceready. Siga os passos na ordem exata:

index.js

document.addEventListener('deviceready', function() {
    var pushwoosh = cordova.require("pushwoosh-cordova-plugin.PushNotification");

    // 1. Register notification callbacks before initialization
    document.addEventListener('push-receive', function(event) {
        var notification = event.notification;
        console.log("Push received: " + JSON.stringify(notification));
    });

    document.addEventListener('push-notification', function(event) {
        var notification = event.notification;
        console.log("Push opened: " + JSON.stringify(notification));
    });

    // 2. Initialize Pushwoosh
    pushwoosh.onDeviceReady({
        appid: "__YOUR_APP_ID__",
        projectid: "__YOUR_FCM_SENDER_ID__"
    });

    // 3. Register the device to receive push notifications
    pushwoosh.registerDevice(
        function(status) {
            var pushToken = status.pushToken;
            // Handle successful registration
        },
        function(status) {
            // Handle registration error
        }
    );
}, false);

Onde:

• __YOUR_APP_ID__ é o código de aplicação do Painel de Controle Pushwoosh.
• __YOUR_FCM_SENDER_ID__ é o número do projeto Firebase do Console do Firebase.

A ordem de inicialização é importante

A sequência de inicialização deve seguir a ordem exata mostrada acima:

1. Registre os ouvintes de eventos primeiro (push-receive, push-notification)
2. Depois chame onDeviceReady()
3. Depois chame registerDevice()

Alterar esta ordem pode causar os seguintes problemas:

• Ouvintes de eventos registrados após onDeviceReady(): Se o aplicativo foi iniciado ao tocar em uma notificação push (inicialização a frio), onDeviceReady() entrega imediatamente o payload da notificação de inicialização para o JavaScript. Se seus ouvintes ainda não estiverem registrados nesse ponto, a notificação de inicialização é perdida sem chance de recuperação.
• registerDevice() chamado antes de onDeviceReady(): O SDK nativo pode não estar configurado corretamente com seu App ID e Sender ID ainda, o que pode fazer com que o registro do dispositivo falhe silenciosamente ou retorne um erro.
• Ouvintes de eventos registrados após registerDevice(): Qualquer notificação push que chegue e seja processada antes que seus ouvintes estejam no lugar será despachada como um evento DOM e silenciosamente descartada, pois não há mecanismo de repetição no plugin.

O plugin não enfileira ou armazena em buffer eventos perdidos do lado do JavaScript. Eventos DOM disparados por document.dispatchEvent() são entregues apenas aos ouvintes que já estão registrados no momento do despacho.

3. Configuração Nativa do iOS

3.1 Capacidades

Para habilitar as Notificações Push em seu projeto, você precisa adicionar certas capacidades.

Na seção Signing & Capabilities, adicione as seguintes capacidades:

• Push Notifications
• Background Modes. Após adicionar esta capacidade, marque a caixa para Remote notifications.

Se você pretende usar Notificações Sensíveis ao Tempo (iOS 15+), adicione também a capacidade Time Sensitive Notifications.

3.2 Info.plist

No seu Runner/Info.plist, defina a chave __PUSHWOOSH_DEVICE_API_TOKEN__ para o Token da API de Dispositivo Pushwoosh:

info.plist

<key>Pushwoosh_API_TOKEN</key>
<string>__PUSHWOOSH_DEVICE_API_TOKEN__</string>

3.3 Rastreamento de entrega de mensagens

Você deve adicionar um alvo de Extensão de Serviço de Notificação (Notification Service Extension) ao seu projeto. Isso é essencial para o rastreamento preciso da entrega e para recursos como Rich Media no iOS.

Siga os passos do guia nativo para adicionar o alvo da extensão e o código Pushwoosh necessário dentro dele.

4. Configuração Nativa do Android

4.1 Instalar dependências

Certifique-se de que as dependências e plugins necessários sejam adicionados aos seus scripts Gradle:

Adicione o plugin Google Services Gradle às dependências do seu build.gradle de nível de projeto:

android/build.gradle

buildscript {
  dependencies {
    classpath 'com.google.gms:google-services:4.3.15'
  }
}

Aplique o plugin no seu arquivo build.gradle de nível de aplicativo:

app/build.gradle

apply plugin: 'com.google.gms.google-services'

4.2 Adicionar arquivo de configuração do Firebase

Coloque o arquivo google-services.json na pasta android/app no diretório do seu projeto.

4.3 Adicionar metadados do Pushwoosh

No seu main/AndroidManifest.xml, adicione o Token da API de Dispositivo Pushwoosh dentro da tag <application>:

AndroidManifest.xml

<meta-data android:name="com.pushwoosh.apitoken" android:value="__YOUR_DEVICE_API_TOKEN__" />

Importante: Certifique-se de dar ao token acesso ao aplicativo correto no seu Painel de Controle Pushwoosh. Saiba mais

5. Execute o Projeto

1. Compile e execute o projeto.
2. Vá para o Painel de Controle Pushwoosh e envie uma notificação push.
3. Você deve ver a notificação no aplicativo.

Integração estendida

Neste estágio, você já integrou o SDK e pode enviar e receber notificações push. Agora, vamos explorar a funcionalidade principal

Ouvintes de eventos de notificação push

No SDK do Pushwoosh, existem dois ouvintes de eventos, projetados para lidar com notificações push:

• O evento push-receive é acionado quando uma notificação push é recebida enquanto o aplicativo está em primeiro plano
• O evento push-notification é acionado quando um usuário abre uma notificação

Esses ouvintes de eventos devem ser registrados antes de chamar onDeviceReady(), como mostrado no passo de inicialização acima. Você pode personalizar a lógica do manipulador para atender às suas necessidades:

index.js

// Register before onDeviceReady()
document.addEventListener('push-receive', function(event) {
    var message = event.notification.message;
    var payload = event.notification.userdata;
    console.log("Push received: " + message);
    // Add your custom logic here
});

document.addEventListener('push-notification', function(event) {
    var message = event.notification.message;
    var payload = event.notification.userdata;
    console.log("Push accepted: " + message);
    // Add your custom logic here (e.g., navigate to a specific screen)
});

Configuração do usuário

Ao focar no comportamento e nas preferências individuais do usuário, você pode entregar conteúdo personalizado, levando a um aumento da satisfação e lealdade do usuário

class Registration {
  afterUserLogin(user) {

    // Set user ID
    pushwoosh.setUserId(user.getId());

    // Setting additional user information as tags for Pushwoosh
    pushwoosh.setTags({
      "age": user.getAge(),
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }
}

Tags

Tags são pares de chave-valor atribuídos a usuários ou dispositivos, permitindo a segmentação com base em atributos como preferências ou comportamento, possibilitando o envio de mensagens direcionadas.

class UpdateUser {
  afterUserUpdateProfile(user) {

    // Set list of favorite categories
    pushwoosh.setTags({
      "favorite_categories": user.getFavoriteCategoriesList()
    });

    // Set payment information
    pushwoosh.setTags({
      "is_subscribed": user.isSubscribed(),
      "payment_status": user.getPaymentStatus(),
      "billing_address": user.getBillingAddress()
    });
  }
}

Eventos

Eventos são ações ou ocorrências específicas do usuário dentro do aplicativo que podem ser rastreadas para analisar o comportamento e acionar mensagens ou ações correspondentes

class Registration {

  // Track login event
  afterUserLogin(user) {
    pushwoosh.postEvent("login", {
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }

  // Track purchase event
  afterUserPurchase(product) {
    pushwoosh.postEvent("purchase", {
      "product_id": product.getId(),
      "product_name": product.getName(),
      "price": product.getPrice(),
      "quantity": product.getQuantity()
    });
  }
}

Solução de problemas

Se você encontrar algum problema durante o processo de integração, consulte a seção de suporte e comunidade.