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 Unity siguiendo las instrucciones de instalación estándar documentadas en la guía del SDK de Singular Unity.

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 notificaciones push.

Configure las rutas de los enlaces push utilizando cadenas delimitadas por barras diagonales que especifiquen la ruta clave al enlace de Singular en su estructura de datos de notificación.

// Configure push link paths in SDK initialization
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .WithPushNotificationsLinkPaths(new List<string> 
    {
        "sng_link",                                    // Top-level key
        "path/to/url",                                 // Nested path
        "rootObj/nestedObj/singularLink"               // Deep nested path
    });

SingularSDK.InitializeSingularSDK();

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: Definir múltiples cadenas de ruta para comprobar diferentes ubicaciones posibles para los enlaces Singular

Manejo Específico de Plataforma

Manejo de Notificaciones Push iOS

Estado finalizado (aplicación no en ejecución)

No se requiere ninguna acción manual para las aplicaciones de iOS en estado finalizado. La integración de Singular iOS gestiona automáticamente el seguimiento de notificaciones push mediante SingularAppController.

Estado de fondo (aplicación ejecutándose en segundo plano)

Cuando se recibe una notificación mientras la aplicación está en segundo plano, utilice HandlePushNotification() para pasar los datos push al SDK.

using UnityEngine;
using Singular;
using Firebase.Messaging;
using System.Collections.Generic;

public class PushNotificationHandler : MonoBehaviour
{
    void Start()
    {
        // Subscribe to Firebase message received event
        Firebase.Messaging.FirebaseMessaging.MessageReceived += OnMessageReceived;
    }

    private void OnMessageReceived(object sender, MessageReceivedEventArgs e)
    {
        Debug.Log("Received Firebase push notification");

        // Extract notification data
        var pushDataDictionary = new Dictionary<string, string>(e.Message.Data);

        // Pass notification data to Singular SDK
        SingularSDK.HandlePushNotification(pushDataDictionary);

        // Your additional notification handling logic
        DisplayNotification(e.Message);
    }
}

Gestión de notificaciones push en Android

Manejo Automático (Recomendado)

Asegúrese de que su actividad principal de Unity extienda SingularUnityActivitypara la gestión automática de notificaciones push tanto en segundo plano como en estado finalizado.

import com.singular.unitybridge.SingularUnityActivity;

public class MessagingUnityPlayerActivity extends SingularUnityActivity {
    // Your custom activity logic here

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // Your initialization code
    }
}

Ejemplo de integración con Firebase

Si necesita una lógica de gestión de mensajes Firebase personalizada, implemente una escucha y reenvíe los datos de notificación a Singular.

using UnityEngine;
using Singular;
using Firebase.Messaging;
using System.Collections.Generic;

public class AndroidPushHandler : MonoBehaviour
{
    void Start()
    {
        // Subscribe to Firebase messaging events
        Firebase.Messaging.FirebaseMessaging.MessageReceived += OnMessageReceived;
        Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;
    }

    private void OnMessageReceived(object sender, MessageReceivedEventArgs e)
    {
        Debug.Log("Received a new Firebase message");

        // Convert message data to dictionary
        var pushDataDictionary = new Dictionary<string, string>(e.Message.Data);

        // Forward to Singular SDK for attribution
        SingularSDK.HandlePushNotification(pushDataDictionary);

        // Your custom handling logic
        ProcessNotificationContent(e.Message);
    }

    private void OnTokenReceived(object sender, TokenReceivedEventArgs token)
    {
        Debug.Log($"FCM Token received: {token.Token}");

        // Store or use token as needed
        // Note: Singular automatically handles token registration
    }

    private void ProcessNotificationContent(FirebaseMessage message)
    {
        // Your custom notification display or routing logic
        string title = message.Notification?.Title ?? "Notification";
        string body = message.Notification?.Body ?? "";

        Debug.Log($"Notification: {title} - {body}");
    }
}

Guía de validación

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

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=com.yourcompany.app
&s=1740905574084
&sdk=Singular/Unity-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.

// Configure ESP domains for wrapped Singular links
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .WithESPDomains(new List<string> { "sl.esp.link", "custom.domain.com" });

SingularSDK.InitializeSingularSDK();

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 SetSingularLinkHandler, 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 gestiona automáticamente las notificaciones de estado finalizado, mientras que Android requiere ampliar SingularUnityActivity para la gestión automática