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

Esta guía le guiará a través de la integración del SDK de Pushwoosh para Unity en su aplicación.

Requisitos previos

Una cuenta de Pushwoosh.
Un proyecto de Pushwoosh configurado en su cuenta.
Unity 2021.3 o posterior.
Para iOS:
- Una plataforma iOS configurada para enviar notificaciones push. Recomendamos usar la Autenticación Basada en Token como el enfoque más simple.
- Establezca la Puerta de Enlace (Gateway) en Sandbox para enviar pushes a un simulador.
- Para obtener el SDK nativo de iOS con Swift Package Manager: Unity 2021.3.15 o posterior, Target minimum iOS Version establecido en 15.0 o posterior y acceso a github.com cuando Xcode compila el proyecto. Con Unity 2021.3.0–2021.3.14 o un destino de iOS inferior, el SDK se añade con CocoaPods (consulte Elija cómo se añade el SDK de iOS).
Para Android:
- Una plataforma Android configurada.
- El número de proyecto (también conocido como ID de remitente), el archivo google-services.json y el nombre del paquete de su proyecto de Firebase.
- Un proyecto de Firebase conectado a su aplicación de Android. Siga la guía de configuración de Firebase si es necesario.
Su Código de Aplicación de Pushwoosh y el Token de API de Dispositivo de Pushwoosh desde el Panel de Control de Pushwoosh.

Pasos de integración

1. Añadir el SDK de Pushwoosh para Unity

Añada lo siguiente a su Packages/manifest.json:

{
  "dependencies": {
    "com.pushwoosh.unity.core": "6.3.0",
    "com.pushwoosh.unity.android": "6.3.0",
    "com.pushwoosh.unity.ios": "6.3.0"
  },
  "scopedRegistries": [
    {
      "name": "npmjs",
      "url": "https://registry.npmjs.org",
      "scopes": ["com.pushwoosh"]
    }
  ]
}

Añada solo los paquetes de la plataforma que necesite. Por ejemplo, omita com.pushwoosh.unity.android si solo se dirige a iOS.

En Unity, vaya a Window > Package Manager > + > Add package from git URL y añada las siguientes URLs una por una:

https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.core
https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.android
https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.ios

Descargue Pushwoosh.unitypackage desde GitHub Releases e impórtelo a través de Assets > Import Package > Custom Package.

2. Instalar el External Dependency Manager

La parte de Android del SDK requiere el External Dependency Manager for Unity (EDM4U) para resolver las dependencias nativas de Android. Omita este paso si solo desarrolla para iOS.

Añada el siguiente scoped registry a su Packages/manifest.json:

{
  "scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": ["com.google.external-dependency-manager"]
    }
  ]
}

Luego añada el paquete a sus dependencias:

"com.google.external-dependency-manager": "1.2.183"

3. Elija cómo se añade el SDK de iOS

De forma predeterminada, la exportación de iOS obtiene el SDK nativo del paquete Swift Pushwoosh-XCFramework con Swift Package Manager. No necesita CocoaPods ni EDM4U para iOS, ni ejecutar pod install.

Para cambiar el origen del SDK de iOS o añadir módulos opcionales, abra Window > Pushwoosh SDK Setup en el Unity Editor:

En iOS SDK from, seleccione Swift Package Manager o CocoaPods.
Con Swift Package Manager, en Modules (Swift Package Manager only), seleccione los módulos opcionales que usa su aplicación: PushwooshLiveActivities, PushwooshInboxKit, PushwooshInApp, PushwooshVoIP, PushwooshForegroundPush, PushwooshKeychain, PushwooshGRPC, PushwooshGeozones. Los módulos se vinculan al target de la aplicación. Para usar un módulo en su propia extensión de aplicación, añádalo al target de la extensión en Xcode. Con CocoaPods, la exportación se realiza sin estos módulos.

La exportación vuelve a CocoaPods, y la consola de Unity indica el motivo, cuando se cumple cualquiera de estas condiciones:

CocoaPods está seleccionado en Window > Pushwoosh SDK Setup.
El proyecto ya tiene un pod PushwooshXCFramework, en un archivo *Dependencies.xml que lee EDM4U o en el Podfile. Para cambiar a Swift Package Manager, elimine el pod. Para Geozones, elimine el pod PushwooshXCFramework/Geozones y seleccione PushwooshGeozones en Window > Pushwoosh SDK Setup.
La versión de Unity es anterior a 2021.3.15.
Target minimum iOS Version es inferior a 15.0.

Con CocoaPods, EDM4U no es necesario. El SDK ejecuta pod install después de la exportación y genera el Podfile por sí mismo, a menos que EDM4U esté instalado y escriba el Podfile en su lugar. Si pod install falla, la consola de Unity muestra el error. Ejecute pod install en la carpeta del proyecto de Xcode exportado.

Si su entorno de compilación no puede acceder a github.com, Xcode no puede resolver el paquete Swift. Seleccione CocoaPods en Window > Pushwoosh SDK Setup para esas compilaciones.

La exportación con Swift Package Manager conserva Unity-iPhone.xcworkspace, por lo que los scripts de compilación y la CI que compilan el workspace funcionan sin cambios.

4. Inicializar el SDK

Cree un script PushNotificator.cs y adjúntelo a cualquier GameObject en la escena:

using UnityEngine;
using System.Collections.Generic;

public class PushNotificator : MonoBehaviour
{
    void Start()
    {
        Pushwoosh.ApplicationCode = "XXXXX-XXXXX";
        Pushwoosh.FcmProjectNumber = "XXXXXXXXXXXX";

        Pushwoosh.Instance.OnRegisteredForPushNotifications += (token) => {
            Debug.Log("Push token: " + token);
        };

        Pushwoosh.Instance.OnFailedToRegisteredForPushNotifications += (error) => {
            Debug.Log("Registration failed: " + error);
        };

        Pushwoosh.Instance.RegisterForPushNotifications();
    }
}

Reemplace:

XXXXX-XXXXX con su Código de Aplicación de Pushwoosh.
XXXXXXXXXXXX con su número de proyecto de Firebase (solo para Android).

5. Configuración nativa de iOS

5.1 Capacidades (Capabilities)

Después de compilar el proyecto de iOS desde Unity, abra el proyecto de Xcode generado y añada las siguientes capacidades en Signing & Capabilities:

Push Notifications
Background Modes con Remote notifications marcado

Para Notificaciones Sensibles al Tiempo (iOS 15+), añada también la capacidad Time Sensitive Notifications.

5.2 Info.plist

Añada el Token de API de Dispositivo de Pushwoosh a su Info.plist:

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

5.3 Seguimiento de la entrega de mensajes

Añada un objetivo de Extensión de Servicio de Notificación (Notification Service Extension) a su proyecto de Xcode. Esto es necesario para un seguimiento preciso de la entrega y para Rich Media en iOS.

Siga la guía nativa para añadir el objetivo de la extensión.

6. Configuración nativa de Android

6.1 Añadir el archivo de configuración de Firebase

Coloque el archivo google-services.json en el directorio Assets de su proyecto de Unity.

6.2 Añadir metadatos de Pushwoosh

Añada el Token de API de Dispositivo de Pushwoosh a su Assets/Plugins/Android/AndroidManifest.xml dentro de la etiqueta <application>:

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

7. Ejecutar el proyecto

Compile y ejecute el proyecto en su plataforma de destino.
Conceda permiso para las notificaciones push cuando se le solicite.
Vaya al Panel de Control de Pushwoosh y envíe una notificación push.

Integración extendida

En esta etapa, puede enviar y recibir notificaciones push. Las secciones a continuación cubren la funcionalidad principal del SDK.

Escuchadores de eventos de notificaciones push

El SDK proporciona dos escuchadores de eventos para manejar las notificaciones push:

OnPushNotificationsReceived — se activa cuando llega una notificación push
OnPushNotificationsOpened — se activa cuando un usuario toca una notificación

Configure estos escuchadores durante la inicialización del SDK:

void Start()
{
    Pushwoosh.ApplicationCode = "XXXXX-XXXXX";
    Pushwoosh.FcmProjectNumber = "XXXXXXXXXXXX";

    Pushwoosh.Instance.OnPushNotificationsReceived += (payload) => {
        Debug.Log("Push received: " + payload);
    };

    Pushwoosh.Instance.OnPushNotificationsOpened += (payload) => {
        Debug.Log("Push opened: " + payload);
    };

    Pushwoosh.Instance.RegisterForPushNotifications();
}

Configuración de usuario

Personalice las notificaciones push identificando a los usuarios y estableciendo sus propiedades:

// Establecer el ID de usuario para el seguimiento entre dispositivos
Pushwoosh.Instance.SetUserId("user-123");

// Establecer el correo electrónico del usuario
Pushwoosh.Instance.SetEmail("user@example.com");

// Establecer usuario con ID y correo electrónico
Pushwoosh.Instance.SetUser("user-123", new List<string> { "user@example.com" });

// Establecer el idioma preferido
Pushwoosh.Instance.SetLanguage("en");

Etiquetas (Tags)

Las etiquetas (Tags) son pares clave-valor asignados a los dispositivos, lo que permite la segmentación de usuarios y la mensajería dirigida:

// Etiqueta de cadena (String)
Pushwoosh.Instance.SetStringTag("favorite_category", "electronics");

// Etiqueta de entero (Integer)
Pushwoosh.Instance.SetIntTag("purchase_count", 5);

// Etiqueta de lista (List)
Pushwoosh.Instance.SetListTag("interests", new List<object> { "sports", "music", "tech" });

// Obtener todas las etiquetas
Pushwoosh.Instance.GetTags((tags, error) => {
    if (error != null) {
        Debug.Log("Error: " + error.Message);
        return;
    }
    foreach (var tag in tags) {
        Debug.Log(tag.Key + ": " + tag.Value);
    }
});

Eventos

Rastree las acciones de los usuarios para analizar el comportamiento y activar mensajes automatizados:

// Rastrear un evento de inicio de sesión
Pushwoosh.Instance.PostEvent("login", new Dictionary<string, object> {
    { "username", "user-123" },
    { "login_type", "email" }
});

// Rastrear un evento de compra
Pushwoosh.Instance.PostEvent("purchase", new Dictionary<string, object> {
    { "product_id", "SKU-001" },
    { "price", 29.99 },
    { "currency", "USD" }
});

Preferencias de comunicación

Permita a los usuarios optar por recibir o no notificaciones push de forma programática:

// Habilitar la comunicación
Pushwoosh.Instance.SetCommunicationEnabled(true);

// Deshabilitar la comunicación
Pushwoosh.Instance.SetCommunicationEnabled(false);

// Comprobar el estado actual
bool isEnabled = Pushwoosh.Instance.IsCommunicationEnabled();

Gestión de la insignia (badge)

Controle el número de la insignia de la aplicación en las plataformas compatibles:

// Establecer la insignia a un número específico
Pushwoosh.Instance.SetBadgeNumber(3);

// Incrementar la insignia
Pushwoosh.Instance.AddBadgeNumber(1);

// Limpiar la insignia
Pushwoosh.Instance.SetBadgeNumber(0);

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.