Guía de integración básica del SDK de Capacitor

Esta sección contiene información sobre cómo integrar el SDK de Capacitor de Pushwoosh en su aplicación.

Requisitos previos

Para integrar el SDK de Capacitor de Pushwoosh en su aplicación, necesitará lo siguiente:

Una cuenta de Pushwoosh.
Un proyecto de Pushwoosh configurado en su cuenta.
Para la integración con iOS:
- Una plataforma iOS configurada para enviar notificaciones push. Recomendamos usar la configuración de autenticación basada en token como el enfoque más simple.
- Establezca el Gateway en Sandbox para enviar pushes a un simulador.
- Para añadir el plugin con Swift Package Manager: Capacitor 7 u 8. Para migrar un proyecto de CocoaPods a Swift Package Manager: @capacitor/cli 7.4.0 o posterior.
Para la integración con Android:
- Una plataforma Android configurada
- El archivo google-services.json y el package name de su proyecto de Firebase.
- Un proyecto de Firebase conectado a su aplicación Android. Siga la guía de configuración de Firebase si es necesario.
Su Pushwoosh Application Code y el Token de API de Dispositivo de Pushwoosh del Panel de Control de Pushwoosh para su aplicación.

Pasos de integración

1. Añadir la dependencia del SDK de Capacitor de Pushwoosh

Añada la dependencia del SDK de Capacitor de Pushwoosh a su proyecto:

npm install pushwoosh-capacitor-plugin

Sincronice la configuración de Capacitor:

npx cap sync

1.1 Elegir el gestor de paquetes de iOS

npx cap sync instala la parte de iOS del plugin con el gestor de paquetes que usa su proyecto de Capacitor: Swift Package Manager o CocoaPods. Ambos incluyen la misma versión del SDK nativo de Pushwoosh y de Inbox UI. Swift Package Manager es compatible con Capacitor 7 y Capacitor 8.

Un proyecto existente conserva su gestor de paquetes: si existe ios/App/CapApp-SPM, la CLI de Capacitor usa Swift Package Manager; de lo contrario, CocoaPods. Para una nueva plataforma iOS:

Capacitor 8
Capacitor 7

Capacitor 8 crea un proyecto de Swift Package Manager de forma predeterminada:

npx cap add ios

Para usar CocoaPods en su lugar, ejecute npx cap add ios --packagemanager CocoaPods.

Capacitor 7 crea un proyecto de CocoaPods de forma predeterminada. Para usar Swift Package Manager, ejecute:

npx cap add ios --packagemanager SPM

El comando crea el proyecto y luego se detiene con un error ENOENT ... Podfile al intentar ejecutar pod install. El proyecto se crea correctamente. Complete la configuración con:

npx cap sync ios

Con Swift Package Manager, la CLI de Capacitor añade el plugin a ios/App/CapApp-SPM, y el plugin incorpora el SDK de iOS de Pushwoosh e Inbox UI. No añada el SDK de Pushwoosh a la aplicación una segunda vez, ni como pod ni como paquete con una versión diferente.

2. Inicialización del SDK de Capacitor

En su archivo principal de JavaScript, importe e inicialice el SDK de Pushwoosh:

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

// Initialize the SDK
Pushwoosh.onDeviceReady({
    appid: "__YOUR_APP_CODE__"
});

// Register for push notifications
Pushwoosh.registerDevice()
    .then(result => {
        console.log("Push token:", result.pushToken);
        // Handle successful registration
    })
    .catch(error => {
        console.error("Failed to register device:", error);
        // Handle registration error
    });

Donde:

__YOUR_APP_CODE__ es el código de la aplicación del Panel de Control de Pushwoosh.

3. Configuración nativa de iOS

3.1 Capacidades

Para habilitar las Notificaciones Push en su proyecto, necesita añadir ciertas capacidades.

En la sección Signing & Capabilities, añada las siguientes capacidades:

Push Notifications
Background Modes. Después de añadir esta capacidad, marque la casilla para Remote notifications.

Si tiene la intención de usar Notificaciones Sensibles al Tiempo (iOS 15+), añada también la capacidad de Time Sensitive Notifications.

3.2 Info.plist

En su ios/App/App/Info.plist establezca la clave __PUSHWOOSH_DEVICE_API_TOKEN__ con el Token de API de Dispositivo de Pushwoosh:

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

3.3 Seguimiento de la entrega de mensajes

Debe añadir un objetivo de Extensión de Servicio de Notificación a su proyecto. Esto es esencial para un seguimiento preciso de la entrega y para características como Rich Media en iOS.

Siga los pasos de la guía nativa para añadir el objetivo de la extensión y el código de Pushwoosh necesario dentro de ella. Añada el SDK de Pushwoosh al target de la extensión según su gestor de paquetes:

CocoaPods: siga el paso Dependencias para la Notification Service Extension (solo CocoaPods) de la guía nativa. En ios/App/Podfile, añada pod 'PushwooshXCFramework' sin versión al target de la extensión, para que se resuelva a la versión que usa el plugin, y luego ejecute npx cap sync ios.
Swift Package Manager: omita el paso de dependencias de CocoaPods de la guía nativa. Añada usted mismo el SDK al target de la extensión en Xcode, porque el target no hereda las dependencias del plugin:
1. Abra el target de la extensión > General > Frameworks and Libraries.
2. Añada el producto PushwooshFramework del paquete Pushwoosh-XCFramework. Use la versión que ya figura en Package.resolved.
Si migró desde CocoaPods, asegúrese de que la extensión ya no obtenga PushwooshXCFramework como pod, para que la aplicación no incluya el SDK dos veces.

Luego, añada import PushwooshFramework en el código de la extensión. El target App no necesita nada más, ya que obtiene el SDK de Pushwoosh a través del plugin.

4. Configuración nativa de Android

4.1 Instalar dependencias

Asegúrese de que las dependencias y plugins requeridos se añadan a sus scripts de Gradle:

Añada el plugin de Google Services Gradle a las dependencias de su build.gradle a nivel de proyecto:

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

Aplique el plugin en su archivo build.gradle a nivel de aplicación:

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

4.2 Añadir archivo de configuración de Firebase

Coloque el archivo google-services.json en la carpeta android/app de su directorio de proyecto.

4.3 Añadir metadatos de Pushwoosh

En su main/AndroidManifest.xml añada el Token de API de Dispositivo de Pushwoosh dentro de la etiqueta <application>:

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

Importante: Asegúrese de dar al token acceso a la aplicación correcta en su Panel de Control de Pushwoosh. Aprenda más

5. Ejecutar el proyecto

Compile y ejecute el proyecto.
Vaya al Panel de Control de Pushwoosh y envíe una notificación push.
Debería ver la notificación en la aplicación.

Integración extendida

En esta etapa, ya ha integrado el SDK y puede enviar y recibir notificaciones push. Ahora, exploremos la funcionalidad principal

Listeners de eventos de notificaciones push

En el SDK de Capacitor de Pushwoosh hay dos métodos de callback para manejar las notificaciones push:

pushReceivedCallback se activa cuando se recibe una notificación push
pushOpenedCallback se activa cuando un usuario abre una notificación

Debe configurar estos callbacks justo después de la inicialización del SDK:

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

// Set up push received callback
await Pushwoosh.pushReceivedCallback((notification, err) => {
    if (err) {
        console.error("Failed to process received notification:", err);
    } else {
        console.log("Push received:", JSON.stringify(notification));
        // Handle the received notification
    }
});

// Set up push opened callback
await Pushwoosh.pushOpenedCallback((notification, err) => {
    if (err) {
        console.error("Failed to process opened notification:", err);
    } else {
        console.log("Push opened:", JSON.stringify(notification));
        // Handle the opened notification
    }
});

Configuración de usuario

Al centrarse en el comportamiento y las preferencias individuales de los usuarios, puede ofrecer contenido personalizado, lo que conduce a una mayor satisfacción y lealtad del usuario

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

class Registration {
  async afterUserLogin(user) {

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

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

Etiquetas (Tags)

Las etiquetas (Tags) son pares clave-valor asignados a usuarios o dispositivos, que permiten la segmentación basada en atributos como preferencias o comportamiento, lo que posibilita la mensajería dirigida.

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

class UpdateUser {
 async afterUserUpdateProfile(user) {

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

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

Eventos

Los eventos son acciones u ocurrencias específicas del usuario dentro de la aplicación que se pueden rastrear para analizar el comportamiento y activar los mensajes o acciones correspondientes

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

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()
    });
  }
}

Solución de problemas

Si un push no se entrega, busque el código de error de su plataforma en Errores de envío para ver qué significa y cómo solucionarlo.

Si encuentra algún problema durante el proceso de integración, consulte la sección de soporte y comunidad.