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

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

Pré-requisitos

Para integrar o SDK do Capacitor da Pushwoosh 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 adicionar o plugin com o Swift Package Manager: Capacitor 7 ou 8. Para migrar um projeto CocoaPods para o Swift Package Manager: @capacitor/cli 7.4.0 ou posterior.
• 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 de API de Dispositivo Pushwoosh do Painel de Controle da Pushwoosh para o seu aplicativo.

Passos de integração

1. Adicionar Dependência do SDK do Capacitor da Pushwoosh

Adicione a dependência do SDK do Capacitor da Pushwoosh ao seu projeto:

npm install pushwoosh-capacitor-plugin

Sincronize a configuração do Capacitor:

npx cap sync

1.1 Escolha o gerenciador de pacotes do iOS

O npx cap sync instala a parte iOS do plugin com o gerenciador de pacotes que seu projeto Capacitor usa: Swift Package Manager ou CocoaPods. Ambos fornecem a mesma versão do SDK nativo da Pushwoosh e da Inbox UI. O Swift Package Manager é compatível com o Capacitor 7 e o Capacitor 8.

Um projeto existente mantém seu gerenciador de pacotes: se ios/App/CapApp-SPM existir, a CLI do Capacitor usa o Swift Package Manager; caso contrário, o CocoaPods. Para uma nova plataforma iOS:

Capacitor 8

O Capacitor 8 cria um projeto Swift Package Manager por padrão:

npx cap add ios

Para usar o CocoaPods, execute npx cap add ios --packagemanager CocoaPods.

Capacitor 7

O Capacitor 7 cria um projeto CocoaPods por padrão. Para usar o Swift Package Manager, execute:

npx cap add ios --packagemanager SPM

O comando cria o projeto e depois para com um erro ENOENT ... Podfile ao tentar executar pod install. O projeto é criado corretamente. Conclua a configuração com:

npx cap sync ios

Com o Swift Package Manager, a CLI do Capacitor adiciona o plugin a ios/App/CapApp-SPM, e o plugin traz o SDK iOS da Pushwoosh e a Inbox UI. Não adicione o SDK da Pushwoosh ao app uma segunda vez, nem como pod nem como pacote com uma versão diferente.

Descontinuação do CocoaPods

O CocoaPods trunk se tornará somente leitura em 2 de dezembro de 2026, e a Pushwoosh está migrando o SDK iOS para o Swift Package Manager. As versões do plugin lançadas após essa data usarão apenas o pacote Swift. Até lá, o pod install e o build do Xcode de um projeto CocoaPods exibem um aviso sobre isso. O aviso não afeta o build.

Para migrar um projeto CocoaPods existente, execute npx cap spm-migration-assistant e, em seguida, siga a etapa manual do Xcode indicada no link. O comando requer @capacitor/cli 7.4.0 ou posterior.

2. Inicialização do SDK do Capacitor

No seu arquivo JavaScript principal, importe e inicialize o SDK da Pushwoosh:

index.js

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

// Inicialize o SDK
Pushwoosh.onDeviceReady({
    appid: "__YOUR_APP_CODE__"
});

// Registre-se para notificações push
Pushwoosh.registerDevice()
    .then(result => {
        console.log("Push token:", result.pushToken);
        // Lidar com o registro bem-sucedido
    })
    .catch(error => {
        console.error("Failed to register device:", error);
        // Lidar com o erro de registro
    });

Onde:

• __YOUR_APP_CODE__ é o código do aplicativo do Painel de Controle da Pushwoosh.

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 ios/App/App/Info.plist, defina a chave __PUSHWOOSH_DEVICE_API_TOKEN__ para o Token de 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 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. Adicione o SDK da Pushwoosh ao target da extensão de acordo com seu gerenciador de pacotes:

• CocoaPods: siga a etapa Dependências para a Notification Service Extension (apenas CocoaPods) do guia nativo. Em ios/App/Podfile, adicione pod 'PushwooshXCFramework' sem versão ao target da extensão, para que ele seja resolvido para a versão que o plugin usa, e depois execute npx cap sync ios.

• Swift Package Manager: pule a etapa de dependências do CocoaPods do guia nativo. Adicione você mesmo o SDK ao target da extensão no Xcode, porque o target não herda as dependências do plugin:

  1. Abra o target da extensão > General > Frameworks and Libraries.
  2. Adicione o produto PushwooshFramework do pacote Pushwoosh-XCFramework. Use a versão que já está em Package.resolved.

  Se você migrou do CocoaPods, verifique se a extensão não recebe mais PushwooshXCFramework como pod, para que o app não inclua o SDK duas vezes.

Em seguida, adicione import PushwooshFramework no código da extensão. O target App não precisa de mais nada, pois recebe o SDK da Pushwoosh por meio do plugin.

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 do diretório do seu projeto.

4.3 Adicionar metadados da Pushwoosh

No seu main/AndroidManifest.xml, adicione o Token de 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 da Pushwoosh. Saiba mais

5. Executar o Projeto

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

Integração estendida

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

Listeners de eventos de notificação push

No SDK do Capacitor da Pushwoosh, existem dois métodos de callback para lidar com notificações push:

• pushReceivedCallback é acionado quando uma notificação push é recebida
• pushOpenedCallback é acionado quando um usuário abre uma notificação

Você deve configurar esses callbacks logo após a inicialização do SDK:

index.js

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

// Configurar callback de push recebido
await Pushwoosh.pushReceivedCallback((notification, err) => {
    if (err) {
        console.error("Failed to process received notification:", err);
    } else {
        console.log("Push received:", JSON.stringify(notification));
        // Lidar com a notificação recebida
    }
});

// Configurar callback de push aberto
await Pushwoosh.pushOpenedCallback((notification, err) => {
    if (err) {
        console.error("Failed to process opened notification:", err);
    } else {
        console.log("Push opened:", JSON.stringify(notification));
        // Lidar com a notificação aberta
    }
});

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.

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

class Registration {
  async afterUserLogin(user) {

    // Definir ID do usuário
    Pushwoosh.setUserId(user.getId);

    // Definindo informações adicionais do usuário como tags para a Pushwoosh
    await 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.

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

class UpdateUser {
 async afterUserUpdateProfile(user) {

    // Definir lista de categorias favoritas
    await Pushwoosh.setTags({
      "favorite_categories": user.getFavoriteCategoriesList()
    });

    // Definir informações de pagamento
    await 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.

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

class Registration {

  // Rastrear evento de login
  afterUserLogin(user) {
    Pushwoosh.postEvent("login", {
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }

  // Rastrear evento de compra
  afterUserPurchase(product) {
    Pushwoosh.postEvent("purchase", {
      "product_id": product.getId(),
      "product_name": product.getName(),
      "price": product.getPrice(),
      "quantity": product.getQuantity()
    });
  }
}

Solução de problemas

Se um push não for entregue, encontre o código de erro da sua plataforma em Erros de envio para ver o que ele significa e como corrigi-lo.

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