Soporte de notificaciones push

Realice un seguimiento de las interacciones de los usuarios con las notificaciones push para medir las campañas de reenganche y atribuir las conversiones con precisión mediante la integración de Firebase Cloud Messaging (FCM) con Singular SDK.

Siga las directrices de implementación que se indican a continuación para garantizar que los datos de las notificaciones se transmiten correctamente al SDK de Singular para una atribución adecuada.

Guía de implementación

Integrar el SDK de Singular

Integre el SDK de Singular en su proyecto Cordova siguiendo las instrucciones de instalación estándar, tal y como se documenta en la guía del SDK de Singular Cordova.

Configure Firebase Cloud Messaging

Configure las notificaciones push en su proyecto Cordova utilizando un plugin como @havesource/cordova-plugin-push y siga la guía de configuración de Firebase para la integración específica de la plataforma.

Configuración de iOS

Registre su aplicación iOS en Firebase y configure las capacidades de notificación push en Xcode.

1. Registrar aplicación iOS: Crea una app iOS en tu proyecto de consola Firebase.
2. Añadir archivo de configuración: Descarga GoogleService-Info.plist e inclúyelo en la carpeta de tu plataforma iOS.
3. Habilitar capacidades: En los ajustes del proyecto Xcode, habilita la capacidad de notificaciones push
4. Habilitar modos de fondo: Habilita los modos en segundo plano y marca las notificaciones remotas.

Configuración Android

Registre su aplicación Android en Firebase y añada el archivo de configuración a su proyecto.

1. Registrar aplicación Android: Crea una app Android en tu proyecto de Consola Firebase
2. Añadir archivo de configuración: Descarga google-services.json y colócalo en platforms/android/app/
3. Verificar Dependencias: Asegúrate de que el plugin Firebase está correctamente instalado y los permisos de mensajería están concedidos

Configurar rutas de enlaces push

Defina las rutas JSON donde se encuentran los enlaces de seguimiento de Singular dentro de su estructura de carga útil de notificación push para permitir un seguimiento de atribución adecuado.

Configure las rutas de los enlaces push pasando matrices de cadenas que especifiquen la ruta clave al enlace Singular en su estructura de datos de notificación. Cada ruta es una matriz que representa la estructura anidada de claves.

// Create configuration
var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

// Configure paths where Singular links appear in push payload
config.withPushNotificationsLinkPaths([
  ['sng_link'],                              // Top-level key
  ['path', 'to', 'url'],                     // Nested path
  ['rootObj', 'nestedObj', 'singularLink']   // Deep nested path
]);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(config);

Ejemplos de configuración de rutas:

• Claves simples: Utilice ['sng_link'] para las claves de nivel superior de la carga útil.
• Claves anidadas: Utilice ['rootObj', 'nestedObj', 'key'] para recorrer estructuras JSON anidadas.
• Varias rutas: Defina múltiples matrices de rutas para comprobar diferentes ubicaciones posibles para los enlaces Singular

Para obtener la documentación completa del método, consulte la referencia withPushNotificationsLinkPaths.

Gestión específica de la plataforma

Configure código específico de la plataforma para pasar datos de notificación al SDK de Singular en función del estado de la aplicación cuando los usuarios interactúan con las notificaciones push.

Gestión de notificaciones push de iOS

Aplicación en estado finalizado

Configure su AppDelegate iOS para pasar las opciones de lanzamiento a Singular SDK para el seguimiento push automático cuando la aplicación se abre desde un estado finalizado.

En su código nativo iOS dentro de AppDelegate.m, llame al siguiente método dentro de didFinishLaunchingWithOptions:

// Import at the top of the file
#import <SingularCordovaSdk/SingularCordovaSdk.h>

- (BOOL)application:(UIApplication *)application 
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    // Pass launch options to Singular for push tracking
    [SingularCordovaSdk setLaunchOptions:launchOptions];
    
    // Your other initialization code
    return YES;
}

Aplicación en segundo o primer plano

Utilice el método handlePushNotification() para pasar datos push al SDK cuando la aplicación recibe notificaciones en los estados de fondo o primer plano.

Llame al siguiente método en el código JavaScript donde se gestiona la notificación push:

// Handle push notification when app is in background or foreground
document.addEventListener('deviceready', initializePushHandling, false);

function initializePushHandling() {
  // Initialize push plugin
  var push = PushNotification.init({
    android: {},
    ios: {
      alert: true,
      badge: true,
      sound: true
    }
  });
  
  // Handle notification when app is in foreground or background
  push.on('notification', function(data) {
    console.log('Push notification received:', data);
    
    // Pass notification data to Singular
    cordova.plugins.SingularCordovaSdk.handlePushNotification(data.additionalData);
    
    // Your custom notification handling logic
    handleNotificationNavigation(data);
  });
}

function handleNotificationNavigation(data) {
  // Navigate to appropriate screen based on notification data
  if (data.additionalData && data.additionalData.route) {
    console.log('Navigating to:', data.additionalData.route);
    // Your navigation logic
  }
}

Para obtener la documentación completa del método, consulte la referencia handlePushNotification.

Gestión de notificaciones push de Android

Aplicación en estado finalizado

No se requiere ninguna acción para las aplicaciones Android en estado finalizado. La capa puente de Cordova gestiona este escenario automáticamente cuando los usuarios tocan las notificaciones.

Aplicación en segundo o primer plano

Configure su Android MainActivity para pasar notificaciones al SDK de Singular cuando la aplicación esté en segundo o primer plano.

En la actividad principal de Cordova (por ejemplo, MainActivity.java), anule onNewIntent:

// Add imports at the top
import android.content.Intent;
import singular_cordova_sdk.SingularCordovaSdk;

// Add to MainActivity class
@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    
    // Pass intent to Singular for push tracking
    SingularCordovaSdk.handleNewIntent(intent);
}

Además, implemente la gestión de mensajes push en su código JavaScript utilizando el mismo enfoque mostrado anteriormente para la gestión en primer y segundo plano de iOS.

Guía de validación

Compruebe que el seguimiento de las notificaciones push funciona correctamente inspeccionando las llamadas de inicio de sesión de Singular SDK y supervisando los datos de atribución.

Verificación de la carga útil en la sesión de inicio

Comprobación de los parámetros de llamada a la API

Confirme que los enlaces de notificaciones push se pasan correctamente a Singular inspeccionando la llamada a la API de inicio de sesión.

Singular SDK incluye la carga útil de la notificación push en el parámetro singular_link en la solicitud de inicio de sesión cuando los usuarios tocan las notificaciones.

Ejemplo de solicitud de inicio de sesión:

https://sdk-api-v1.singular.net/api/v1/start?
a=<SDK-Key>
&singular_link=https://singularassist2.sng.link/C4nw9/r1m0?_dl=singular%3A%2F%2Ftest&_smtype=3
&i=net.singular.singularsampleapp
&install_time=1740905507036
&s=1740905574084
&sdk=Singular/v12.6.2
&singular_install_id=2dc5dfc2-a2a8-484a-aad1-fed6cb7a3023
&u=75f7b911-5a77-597d-8892-56f5e0e210ff

Configuración avanzada

Implemente funciones avanzadas de notificación push, incluida la configuración del dominio ESP y el enrutamiento dinámico de enlaces profundos para escenarios de notificación complejos.

Configuración del dominio ESP

Configuración de dominios externos

Configure dominios externos si envuelve enlaces Singular dentro de dominios de proveedor de servicios de correo electrónico (ESP) o de terceros.

// Create configuration
var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

// Configure ESP domains for wrapped Singular links
config.withESPDomains(['sl.esp.link', 'custom.domain.com']);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(config);

Para obtener la documentación completa del método, consulte la referencia withESPDomains.

Enrutamiento dinámico de enlaces profundos

Múltiples acciones desde una única notificación

Implemente múltiples destinos de enlaces profundos desde una única notificación configurando un enlace de seguimiento Singular con redireccionamientos dinámicos.

Ejemplo de uso: Una notificación de noticias de última hora con múltiples opciones de acción

• Leer últimas noticias: newsapp://article?id=12345
• Temas de actualidad: newsapp://trending
• Deportes: newsapp://sports

En lugar de crear varios enlaces de seguimiento, utilice un enlace Singular y anule las redirecciones dinámicamente en función de la selección del usuario. Consulte Modificación de redireccionamientos en enlaces de seguimiento singularespara obtener detalles sobre la implementación.

// Handle multiple deep link options from single notification
function handleNotificationWithActions(notificationData) {
  // Extract action selection from notification data
  var selectedAction = notificationData.action;
  var singularLink = notificationData.sng_link;
  
  // Route based on action
  switch (selectedAction) {
    case 'read_news':
      navigateToArticle(notificationData.article_id);
      break;
    case 'trending':
      navigateToTrending();
      break;
    case 'sports':
      navigateToSports();
      break;
    default:
      navigateToHome();
  }
  
  // Pass notification to Singular for attribution
  cordova.plugins.SingularCordovaSdk.handlePushNotification(notificationData);
}

function navigateToArticle(articleId) {
  console.log('Navigating to article:', articleId);
  // Your navigation logic
}

function navigateToTrending() {
  console.log('Navigating to trending');
  // Your navigation logic
}

function navigateToSports() {
  console.log('Navigating to sports');
  // Your navigation logic
}

function navigateToHome() {
  console.log('Navigating to home');
  // Your navigation logic
}

Consideraciones importantes

Comprenda los detalles clave de implementación y las limitaciones al integrar el seguimiento de notificaciones push con Singular SDK.

Notas de implementación

Comportamientos clave y limitaciones

• Sin controlador de devolución de llamada: A diferencia de withSingularLink, la función de notificaciones push no proporciona retrollamadas de carga útil. Debe implementar su propia lógica de enlace profundo para dirigir a los usuarios a contenidos específicos dentro de su aplicación basándose en los datos de la notificación.
• Flujo de atribución: Cuando los usuarios tocan las notificaciones, Singular recupera la carga útil y la incluye en el evento de inicio de sesión activado por Singular.init(config). El backend procesa estos datos para atribuir el punto de contacto de la notificación push y registrar el seguimiento del reenganche.
• Restricciones de dominio: Por defecto, sólo se permiten dominios de enlace Singular (sng.link) de la página Gestionar enlaces. Configure dominios ESP explícitamente para enlaces envueltos utilizando withESPDomains()
• Diferencias entre plataformas: iOS requiere la configuración de AppDelegate para la gestión del estado finalizado, mientras que Android lo gestiona automáticamente a través del módulo puente para escenarios de estado finalizado.
• Configuración de rutas: El SDK busca enlaces singulares utilizando las rutas definidas en withPushNotificationsLinkPaths(). Asegúrese de que la estructura de la carga útil de la notificación coincida con las rutas configuradas para una extracción correcta del enlace.

Recomendaciones para las pruebas

1. Pruebe todos los estados de la aplicación: Compruebe que el seguimiento push funciona correctamente cuando la aplicación está terminada, en segundo plano y en primer plano.
2. Validar la estructura de la carga útil: Confirme que la carga útil de la notificación incluye enlaces singulares en las rutas configuradas.
3. Compruebe las llamadas de inicio de sesión: Utilice herramientas de supervisión de red para verificar que el parámetro singular_link aparece en las solicitudes de inicio de sesión.
4. Supervise la atribución: Compruebe la consola de Singular SDK para confirmar que las notificaciones push se atribuyen correctamente en los datos de su campaña.
5. Pruebe los enlaces profundos: Verifica que los usuarios son dirigidos correctamente al contenido deseado cuando tocan diferentes tipos de notificaciones.