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) o el servicio de notificaciones push de Apple (APN) 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 de Unreal Engine siguiendo las instrucciones de instalación estándar documentadas en la guía del SDK de Singular para Unreal Engine.

Registre el token push

Registre su token de notificación push con Singular para habilitar el seguimiento de desinstalación y la atribución push.

// Register push token for uninstall tracking
void UYourGameInstance::OnPushTokenReceived(const FString& Token)
{
    // Pass the FCM or APNs token to Singular
    USingularSDKBPLibrary::SetUninstallToken(Token);
    UE_LOG(LogTemp, Log, TEXT("Push token registered: %s"), *Token);
}

Firma del método:

static void SetUninstallToken(FString token);

Gestión específica de la plataforma

Gestión de notificaciones push de iOS

Configuración de rutas de notificaciones push

Para las implementaciones de iOS, configure las rutas JSON donde se encuentran los enlaces de seguimiento de Singular dentro de su estructura de carga útil de notificación push durante la inicialización del SDK.

// iOS: Configure push notification link paths in initialization
// Note: This is typically configured through the iOS native bridge
// The Singular SDK de iOS automatically handles push tracking when configured

// Example configuration in iOS native code (Objective-C):
// SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"API_KEY" andSecret:@"API_SECRET"];
// config.singularLinksHandler = ^(SingularLinkParams * _Nonnull params) {
//     // Handle deep link from push notification
// };
// [Singular start:config];

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

No se requiere ninguna acción manual para las aplicaciones iOS en estado finalizado. La integración de Singular iOS gestiona automáticamente el seguimiento push cuando los usuarios tocan las notificaciones mientras la aplicación no se está ejecutando.

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

Cuando se recibe una notificación mientras la aplicación está en segundo plano, el SDK de iOS procesa automáticamente los datos de la notificación. No se requiere código C++ adicional más allá del registro inicial del token.

Manejo de notificaciones push en Android

Integración de Firebase Cloud Messaging

Para las implementaciones de Android, integre Firebase Cloud Messaging (FCM) y reenvíe los tokens push al SDK de Singular para su seguimiento.

// Android: Register FCM token with Singular
void UYourGameInstance::OnFirebaseTokenReceived(const FString& FcmToken)
{
    // Register the FCM token for uninstall tracking
    USingularSDKBPLibrary::SetUninstallToken(FcmToken);
    UE_LOG(LogTemp, Log, TEXT("FCM token registered with Singular: %s"), *FcmToken);
}

Manejo de datos de notificaciones push

Cuando los usuarios tocan notificaciones push que contienen enlaces de seguimiento de Singular, asegúrese de que los datos de la notificación se pasan al gestor de enlaces profundos de su aplicación para una atribución adecuada.

// Handle notification tap event
void UYourGameInstance::OnNotificationTapped(const FString& NotificationData)
{
    // Parse notification data for Singular links
    // Example: Extract "sng_link" or custom key from notification payload

    // If notification contains a Singular tracking link, it will be
    // automatically processed by the SDK's deep link handler

    UE_LOG(LogTemp, Log, TEXT("Notification tapped: %s"), *NotificationData);

    // Route user to appropriate content
    ProcessNotificationDeepLink(NotificationData);
}

void UYourGameInstance::ProcessNotificationDeepLink(const FString& LinkData)
{
    // Your custom deep link routing logic
    if (LinkData.Contains(TEXT("article")))
    {
        // Navigate to article
        OpenArticleScreen();
    }
    else if (LinkData.Contains(TEXT("promotion")))
    {
        // Navigate to promotion
        OpenPromotionScreen();
    }
}

Guía de validación

Verificación del registro de tokens push

Confirme que los tokens de notificación push están correctamente registrados en Singular comprobando los registros del SDK durante la inicialización de la aplicación.

// Enable SDK logging to verify token registration
bool Success = USingularSDKBPLibrary::Initialize(
    TEXT("YOUR_SDK_KEY"),
    TEXT("YOUR_SDK_SECRET"),
    60,                      // Session timeout
    TEXT(""),                // Custom user ID
    true,                    // Enable SKAdNetwork
    false,                   // Manual SKAN management
    0,                       // Wait for tracking authorization
    false,                   // OAID collection
    true,                    // Enable logging for debugging
    5,                       // Verbose log level
    false,                   // Clipboard attribution
    TEXT(""),                // Facebook App ID
    TEXT("")                 // Custom SDID
);

// After receiving push token
FString PushToken = GetPushNotificationToken();
USingularSDKBPLibrary::SetUninstallToken(PushToken);

// Check logs for confirmation:
// "Push token registered successfully" or similar message

Verificación de la atribución en el panel

Utilice el panel de Singular para verificar que las interacciones de las notificaciones push se rastrean correctamente.

• Campañas de reenganche: Comprueba la sección Re-engagement en tu panel de control para ver el rendimiento de la campaña de notificaciones push.
• Datos a nivel de usuario: Exporte los datos a nivel de usuario para verificar que los puntos de contacto de las notificaciones push se están registrando con la atribución correcta.
• Eventos de conversión: Confirme que los eventos desencadenados después de los toques de notificaciones push se atribuyen a la campaña correcta.

Configuración avanzada

Estructura personalizada de la carga útil de notificación

Estructure sus cargas útiles de notificaciones push para incluir parámetros de seguimiento de Singular junto con sus datos personalizados.

Estructura de carga útil recomendada (JSON):

{
  "notification": {
    "title": "Special Offer!",
    "body": "Get 50% off today only"
  },
  "data": {
    "sng_link": "https://yourapp.sng.link/Abc12?_dl=myapp://promo",
    "campaign_id": "summer_sale_2025",
    "promo_code": "SAVE50",
    "deep_link": "myapp://promo/summer"
  }
}

Elementos clave:

• sng_link: El enlace de seguimiento de Singular para la atribución (necesario para el seguimiento push).
• campaign_id: Su identificador interno de campaña para referencia.
• deep_link: El enlace profundo personalizado de tu aplicación para el enrutamiento de contenido.
• Datos personalizados: Cualquier dato adicional que necesite tu app (códigos promocionales, segmentos de usuarios, etc.).

Implementación de enrutamiento de enlaces profundos

Implemente un gestor de enlaces profundos centralizado para dirigir a los usuarios a contenidos específicos cuando pulsen las notificaciones push.

// Centralized deep link handler
class UDeepLinkHandler : public UObject
{
public:
    void HandleDeepLink(const FString& DeepLink)
    {
        // Parse the deep link URL
        if (DeepLink.StartsWith(TEXT("myapp://article/")))
        {
            FString ArticleId = ExtractArticleId(DeepLink);
            NavigateToArticle(ArticleId);
        }
        else if (DeepLink.StartsWith(TEXT("myapp://promo/")))
        {
            FString PromoId = ExtractPromoId(DeepLink);
            NavigateToPromotion(PromoId);
        }
        else if (DeepLink.StartsWith(TEXT("myapp://profile")))
        {
            NavigateToUserProfile();
        }
        else
        {
            // Default: Navigate to home screen
            NavigateToHome();
        }
    }

private:
    FString ExtractArticleId(const FString& Url)
    {
        // Extract article ID from URL
        FString ArticleId;
        Url.Split(TEXT("article/"), nullptr, &ArticleId);
        return ArticleId;
    }

    FString ExtractPromoId(const FString& Url)
    {
        // Extract promo ID from URL
        FString PromoId;
        Url.Split(TEXT("promo/"), nullptr, &PromoId);
        return PromoId;
    }

    void NavigateToArticle(const FString& ArticleId)
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to article: %s"), *ArticleId);
        // Your navigation logic
    }

    void NavigateToPromotion(const FString& PromoId)
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to promotion: %s"), *PromoId);
        // Your navigation logic
    }

    void NavigateToUserProfile()
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to user profile"));
        // Your navigation logic
    }

    void NavigateToHome()
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to home screen"));
        // Your navigation logic
    }
};

Consideraciones importantes

Notas de implementación

• Momento de registro del token: Registre el token push con Singular tan pronto como esté disponible desde FCM o APNs, idealmente durante o inmediatamente después de la inicialización del SDK.
• Flujo de atribución: Cuando los usuarios tocan notificaciones que contienen enlaces de Singular, el SDK procesa automáticamente los datos de atribución durante el evento de inicio de sesión. No es necesaria ninguna manipulación manual para el seguimiento de atribuciones.
• Gestión de enlaces profundos: Aunque Singular gestiona la atribución automáticamente, debe implementar una lógica de enrutamiento de enlaces profundos personalizada para dirigir a los usuarios al contenido correcto de la aplicación.
• Coherencia de la carga útil: Utilice nombres clave coherentes (por ejemplo, "sng_link") en todas las campañas de notificaciones push para garantizar un seguimiento fiable.
• Diferencias de plataforma: iOS y Android gestionan las notificaciones push de forma diferente a nivel de sistema. Asegúrese de que su implementación tiene en cuenta el comportamiento específico de cada plataforma.
• Seguimiento de la desinstalación: El token push también se utiliza para el seguimiento de desinstalación. Singular envía notificaciones push silenciosas para detectar aplicaciones desinstaladas, proporcionando información valiosa sobre la retención.

Privacidad y permisos

Garantice el cumplimiento de los requisitos de la plataforma y las normas de privacidad del usuario al implementar las notificaciones push.

• Permisos de iOS: Los usuarios deben conceder permiso para recibir notificaciones push. Solicite el permiso en el momento adecuado en el flujo de su aplicación, no inmediatamente en el primer lanzamiento.
• Permisos para Android: A partir de Android 13 (nivel de API 33), las aplicaciones deben solicitar el permiso POST_NOTIFICATIONS para enviar notificaciones.
• Consentimiento del usuario: Respete las preferencias del usuario para recibir comunicaciones de marketing. Proporcione mecanismos claros de exclusión en la configuración de su aplicación.
• Privacidad de los datos: Evite incluir información de identificación personal en las notificaciones push. Utilice ID de usuario u otros identificadores no PII.