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

Integra el SDK de Singular en tu proyecto React Native siguiendo las instrucciones de instalación estándar documentadas en la guía Singular SDK de React Native.

Configurar Firebase Cloud Messaging

Instala los paquetes de Firebase y configura los ajustes específicos de la plataforma para el soporte de notificaciones push.

Instalar paquetes Firebase

Añade las dependencias de React Native Firebase para la funcionalidad central y el soporte de mensajería.

npm install @react-native-firebase/app
npm install @react-native-firebase/messaging

Configuración de iOS

Registra tu app iOS en Firebase y configura las capacidades de notificaciones push en Xcode.

1. Registrar iOS App: Crea una app iOS en tu proyecto Firebase Console.
2. Añadir archivo de configuración: Descarga GoogleService-Info.plist y añádelo a tu proyecto Xcode.
3. Habilitar capacidades: En la configuración del proyecto Xcode, habilite la capacidad de notificaciones push
4. Habilitar modos de fondo: Habilita Background Modes y marca Remote notifications

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 android/app/
3. Verificar Dependencias: Asegúrate de que las dependencias de mensajería de Firebase están añadidas y los permisos 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.

Configure las rutas de 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.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

const config: SingularConfig = {
  apikey: 'YOUR_SDK_KEY',
  secret: 'YOUR_SDK_SECRET',
  pushNotificationsLinkPaths: [
    ['sng_link'],                            // Top-level key
    ['path', 'to', 'url'],                   // Nested path
    ['rootObj', 'nestedObj', 'singularLink'] // Deep nested path
  ]
};

NativeSingular.init(config);

import { Singular, SingularConfig } from 'singular-react-native';

const config = new SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
)
  .withPushNotificationsLinkPaths([
    ['sng_link'],                              // Top-level key
    ['path', 'to', 'url'],                     // Nested path
    ['rootObj', 'nestedObj', 'singularLink']   // Deep nested path
  ]);

Singular.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.

Manipulación específica de la plataforma

Gestión de notificaciones push de iOS

Aplicación en estado finalizado

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

En AppDelegate, añada lo siguiente dentro de didFinishLaunchingWithOptions:

// Import at the top of the file
import Singular

func application(
  _ application: UIApplication,
  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
) -> Bool {
  let delegate = ReactNativeDelegate()
  let factory = RCTReactNativeFactory(delegate: delegate)
  delegate.dependencyProvider = RCTAppDependencyProvider()

  reactNativeDelegate = delegate
  reactNativeFactory = factory

  window = UIWindow(frame: UIScreen.main.bounds)

  if let singularBridge = NSClassFromString("SingularBridge") {
    let selector = NSSelectorFromString("startSessionWithLaunchOptions:")
    if singularBridge.responds(to: selector) {
      singularBridge.perform(selector, with: launchOptions, afterDelay: 1)
    }
  }

  factory.startReactNative(
    withModuleName: "YourAppName", // Update with your App Name
    in: window,
    launchOptions: launchOptions
  )

  return true
}

// Import at the top of the file
#import <Singular-React-Native/SingularBridge.h>

- (BOOL)application:(UIApplication *)application 
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // Pass launch options to Singular for push tracking
    [SingularBridge startSessionWithLaunchOptions: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.

// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useEffect } from 'react';
import NativeSingular from 'singular-react-native/jsNativeSingular';
import messaging from '@react-native-firebase/messaging';

export default function App() {
  useEffect(() => {
    // Handle foreground messages
    const unsubscribeBackground = messaging().onMessage(handleForegroundMessage);

    // Handle messages that opened the app from background
    messaging().onNotificationOpenedApp(handleBackgroundMessage);

    return () => {
      unsubscribeBackground();
    };
  }, []);

  function handleForegroundMessage(remoteMessage) {
    console.log('Foreground message received:', remoteMessage);

    // Pass notification data to Singular
    if (remoteMessage.data) {
      NativeSingular.handlePushNotification(remoteMessage.data);
    }

    // Your custom notification handling
    displayLocalNotification(remoteMessage);
  }

  function handleBackgroundMessage(remoteMessage) {
    console.log('Background message opened app:', remoteMessage);

    // Pass notification data to Singular
    if (remoteMessage.data) {
      NativeSingular.handlePushNotification(remoteMessage.data);
    }

    // Navigate to appropriate screen
    navigateFromNotification(remoteMessage);
  }

  function displayLocalNotification(remoteMessage) {
    // Your notification display logic
    console.log('Displaying notification:', remoteMessage.notification?.title);
  }

  function navigateFromNotification(remoteMessage) {
    // Your navigation logic based on notification data
    const route = remoteMessage.data?.route;
    console.log('Navigating to:', route);
  }

  return (
    // Your app components
    null
  );
}

import React, { useEffect } from 'react';
import { Singular } from 'singular-react-native';
import messaging from '@react-native-firebase/messaging';

export default function App() {
  useEffect(() => {
    // Handle background messages
    const unsubscribeBackground = messaging().onMessage(handleForegroundMessage);

    // Handle messages that opened the app from background
    messaging().onNotificationOpenedApp(handleBackgroundMessage);

    return () => {
      unsubscribeBackground();
    };
  }, []);

  function handleForegroundMessage(remoteMessage) {
    console.log('Foreground message received:', remoteMessage);

    // Pass notification data to Singular
    if (remoteMessage.data) {
      Singular.handlePushNotification(remoteMessage.data);
    }

    // Your custom notification handling
    displayLocalNotification(remoteMessage);
  }

  function handleBackgroundMessage(remoteMessage) {
    console.log('Background message opened app:', remoteMessage);

    // Pass notification data to Singular
    if (remoteMessage.data) {
      Singular.handlePushNotification(remoteMessage.data);
    }

    // Navigate to appropriate screen
    navigateFromNotification(remoteMessage);
  }

  function displayLocalNotification(remoteMessage) {
    // Your notification display logic
    console.log('Displaying notification:', remoteMessage.notification?.title);
  }

  function navigateFromNotification(remoteMessage) {
    // Your navigation logic based on notification data
    const route = remoteMessage.data?.route;
    console.log('Navigating to:', route);
  }

  return (
    // Your app components
  );
}

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

Manejo de notificaciones push en Android

Aplicación en estado finalizado

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

Aplicación en segundo o primer plano

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

En su MainActivity (por ejemplo, MainActivity.java o MainActivity.kt), anule onNewIntent:

// Add imports at the top
import android.content.Intent;
import net.singular.react_native.SingularBridgeModule;

// Add to MainActivity class
@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);

    // Pass intent to Singular for push tracking
    SingularBridgeModule.onNewIntent(intent);
}

// Add imports at the top
import android.content.Intent
import net.singular.react_native.SingularBridgeModule

// Add to MainActivity class
override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)

    // Pass intent to Singular for push tracking
    SingularBridgeModule.onNewIntent(intent)
}

Además, implemente el manejo de mensajes Firebase en su código React Native utilizando el mismo enfoque mostrado anteriormente para el manejo de fondo/primer plano de iOS.

Guía de validación

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

Confirme que los enlaces de notificación 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.sampleapp
&s=1740905574084
&sdk=Singular/React-Native-v1.0.0

Configuración avanzada

Configuración de dominios ESP

Configure dominios externos si envuelve enlaces de Singular dentro de dominios de proveedores de servicios de correo electrónico (ESP) u otros dominios de terceros.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Configure ESP domains for wrapped Singular links
const config: SingularConfig = {
  apikey: 'YOUR_SDK_KEY',
  secret: 'YOUR_SDK_SECRET',
  espDomains: ['sl.esp.link', 'custom.domain.com']
};

NativeSingular.init(config);

import { Singular, SingularConfig } from 'singular-react-native';

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

Singular.init(config);

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

Enrutamiento dinámico de enlaces profundos

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.

Consideraciones importantes

Notas de implementación

• Sin controlador de devolución de llamada: A diferencia de withSingularLink, la función de notificación push no proporciona devoluciones de llamada de carga. Implemente su propia lógica de enlace profundo para dirigir a los usuarios a contenido específico dentro de su aplicació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 la inicialización del SDK. 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 singulares (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 el estado finalizado, mientras que Android lo gestiona automáticamente a través del módulo puente.