SDK de Unreal Engine - Seguimiento de la desinstalación

Documento

Seguimiento de desinstalaciones

Realiza un seguimiento de las desinstalaciones de apps para medir la retención de usuarios y optimizar las campañas de reenganche integrando servicios de notificaciones push con Singular SDK.

Importante: Google dejó obsoletas las API de GCM en abril de 2018. Utiliza Firebase Cloud Messaging (FCM) para todas las implementaciones de seguimiento de desinstalación de Android.

Seguimiento de desinstalación de Android

Requisitos previos

Antes de implementar el seguimiento de desinstalación en tu app de Unreal Engine, configura tu app en la plataforma Singular siguiendo la guía Configuración del seguimiento de desinstalación de Android.


Requisitos del sistema

El seguimiento de desinstalaciones requiere Firebase Cloud Messaging y configuraciones de dispositivo específicas.

Requisitos de FCM(fuente):

  • Versión de Android: Los dispositivos deben ejecutar Android 4.1 (API 16) o superior
  • Servicios de Google Play: Los dispositivos deben tener instalada la aplicación Google Play Store
  • Compatibilidad con emuladores: Se admiten emuladores de Android 4.1+ con API de Google
  • Distribución: Las aplicaciones se pueden distribuir fuera de Google Play Store sin dejar de admitir el seguimiento de desinstalaciones.

Nota: no se realizará el seguimiento de las desinstalaciones de los usuarios que utilicen versiones de Android no compatibles o dispositivos sin Google Play Services.


Pasos de implementación

Paso 1: Integrar Firebase Cloud Messaging

Configure Firebase Cloud Messaging en su aplicación Unreal Engine si aún no lo está.

Siga la guía oficial de Google para configurar una aplicación cliente de Firebase Cloud Messaging en Android, que incluye:

  1. Añadir Firebase a tu proyecto Android
  2. Añadir la dependencia de Firebase Messaging a tu archivo build.gradle
  3. Configurar los ajustes de Firebase en google-services.json
  4. Solicitar permisos de notificación (Android 13+)

Paso 2: Configurar AndroidManifest.xml

Registra tu servicio de mensajería Firebase en el manifiesto de Android para recibir mensajes FCM.

AndroidManifest.xml
<service 
    android:name=".java.MyFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

Importante: Sustituya .java.MyFirebaseMessagingService por el nombre completo de su clase que extienda FirebaseMessagingService.


Paso 3: Registrar el token de dispositivo FCM

Recupere el token de dispositivo FCM y envíelo a Singular para el seguimiento de la desinstalación mediante el método SetUninstallToken.

C++
// After initializing Singular SDK, register the FCM token
void AYourGameMode::RegisterFCMToken()
{
    // Get FCM token from Firebase Messaging
    // This assumes you have Firebase integrated and can retrieve the token
    FString FCMToken = GetFirebaseCloudMessagingToken();

    if (!FCMToken.IsEmpty())
    {
        // Register token with Singular
        USingularSDKBPLibrary::SetUninstallToken(FCMToken);
        UE_LOG(LogTemp, Log, TEXT("FCM token registered with Singular: %s"), *FCMToken);
    }
    else
    {
        UE_LOG(LogTemp, Warning, TEXT("FCM token is empty"));
    }
}

// Example helper method to get FCM token (platform-specific implementation required)
FString AYourGameMode::GetFirebaseCloudMessagingToken()
{
    FString Token;

    #if PLATFORM_ANDROID
    // Use JNI to call Firebase Messaging getToken() method
    // This requires platform-specific code to access Firebase SDK
    if (JNIEnv* Env = FAndroidApplication::GetJavaEnv())
    {
        // Implement JNI call to Firebase Messaging getToken()
        // Example: Token = CallFirebaseGetToken(Env);
        UE_LOG(LogTemp, Log, TEXT("Retrieving FCM token via JNI"));
    }
    #endif

    return Token;
}

Firma del método:

static void SetUninstallToken(FString token);

Parámetros:

  • Token: El token de dispositivo FCM como cadena

Nota: El método SetUninstallToken debe invocarse después de inicializar Singular SDK. El token FCM puede registrarse en cualquier momento tras la inicialización del SDK.


Paso 4: Actualización del token

Actualice el token FCM con Singular cada vez que se actualice para mantener un seguimiento preciso de la desinstalación.

C++
// Handle FCM token refresh
void AYourGameMode::OnFCMTokenRefresh(const FString& NewToken)
{
    UE_LOG(LogTemp, Log, TEXT("FCM token refreshed: %s"), *NewToken);

    // Update token with Singular
    USingularSDKBPLibrary::SetUninstallToken(NewToken);

    // Also send token to your server if needed
    SendTokenToServer(NewToken);
}

void AYourGameMode::SendTokenToServer(const FString& Token)
{
    // Implement your server communication logic here
    UE_LOG(LogTemp, Log, TEXT("Sending token to server: %s"), *Token);
}

Práctica recomendada: Los tokens FCM pueden actualizarse en cualquier momento (actualizaciones de la aplicación, restauración del dispositivo, etc.). Gestione siempre los eventos de actualización del token para mantener Singular actualizado con el token más reciente.


Seguimiento de la desinstalación de iOS

Requisitos previos

El seguimiento de desinstalaciones en iOS se basa en la tecnología del servicio de notificaciones push de Apple (APN).

Si su aplicación no es compatible con las notificaciones push, consulte la guía de Apple para Registrar su aplicación con APNs.


Registro del token de dispositivo APNs

Pase el token de dispositivo devuelto por APNs mediante el método SetUninstallToken una vez inicializado el SDK.

Firma del método:

static void SetUninstallToken(FString token);

Parámetros:

  • Token: El token de dispositivo devuelto desde APNs como una cadena hexadecimal.

Formato del token: El token de APNs suele ser un dato binario en su forma nativa, pero debe pasarlo a Singular como una representación de cadena hexadecimal.


Ejemplo de uso

Registre el token de dispositivo APNs con Singular para el seguimiento de desinstalación de iOS.

C++
// Register APNs token with Singular
void AYourGameMode::RegisterAPNsToken()
{
    #if PLATFORM_IOS
    // Get APNs device token (platform-specific implementation required)
    FString APNsToken = GetAPNsDeviceToken();

    if (!APNsToken.IsEmpty())
    {
        // Pass the token as a hex-string to Singular
        USingularSDKBPLibrary::SetUninstallToken(APNsToken);
        UE_LOG(LogTemp, Log, TEXT("APNs token registered: %s"), *APNsToken);
    }
    else
    {
        UE_LOG(LogTemp, Warning, TEXT("Failed to get APNs device token"));
    }
    #endif
}

// Example helper method to get APNs token (platform-specific implementation required)
FString AYourGameMode::GetAPNsDeviceToken()
{
    FString Token;

    #if PLATFORM_IOS
    // Use Objective-C++ to access APNs token
    // This requires platform-specific code in a .mm file
    // Example: Token = GetIOSDeviceToken();
    UE_LOG(LogTemp, Log, TEXT("Retrieving APNs token"));
    #endif

    return Token;
}

Ejemplo de token:

// Pass the APNs token as a hex-string
USingularSDKBPLibrary::SetUninstallToken(TEXT("ba85ab31a7c7f5c2f012587f29fb0e596d4b67e7b7b2838fa1a8582c1f7dbdee"));

Consistencia de plataforma: El método SetUninstallToken funciona de forma idéntica tanto para Android (FCM) como para iOS (APNs). Llámelo después de la inicialización del SDK en ambas plataformas.


Recuperación de token específica de la plataforma

Token FCM de Android a través de JNI

Acceda al token de Firebase Cloud Messaging utilizando JNI (Java Native Interface) en Unreal Engine.

C++
#if PLATFORM_ANDROID
#include "Android/AndroidJNI.h"
#include "Android/AndroidApplication.h"

FString AYourGameMode::GetFirebaseCloudMessagingToken()
{
    FString Token;

    if (JNIEnv* Env = FAndroidApplication::GetJavaEnv())
    {
        // Get FirebaseMessaging class
        jclass FirebaseMessagingClass = FAndroidApplication::FindJavaClass(
            "com/google/firebase/messaging/FirebaseMessaging"
        );

        if (FirebaseMessagingClass != nullptr)
        {
            // Get getInstance() method
            jmethodID GetInstanceMethod = Env->GetStaticMethodID(
                FirebaseMessagingClass,
                "getInstance",
                "()Lcom/google/firebase/messaging/FirebaseMessaging;"
            );

            // Call getInstance()
            jobject FirebaseMessagingInstance = Env->CallStaticObjectMethod(
                FirebaseMessagingClass,
                GetInstanceMethod
            );

            if (FirebaseMessagingInstance != nullptr)
            {
                // Get getToken() method
                jmethodID GetTokenMethod = Env->GetMethodID(
                    FirebaseMessagingClass,
                    "getToken",
                    "()Lcom/google/android/gms/tasks/Task;"
                );

                // Note: getToken() returns a Task, so you need to implement
                // async handling or use addOnCompleteListener
                // This is a simplified example - production code requires
                // proper Task handling

                UE_LOG(LogTemp, Log, TEXT("FCM token retrieval initiated"));
            }

            Env->DeleteLocalRef(FirebaseMessagingClass);
        }
    }

    return Token;
}
#endif

Nota de implementación: getToken()de Firebase devuelve un objeto Task que se resuelve de forma asíncrona. Las implementaciones de producción deben utilizar la API de tareas de Firebase con escuchadores de finalización para recuperar correctamente el token.


Token de APNs de iOS a través de Objective-C

Acceso al token del servicio Apple Push Notification mediante Objective-C++ en Unreal Engine.

Método de implementación: Cree un archivo .mm (Objective-C++) independiente en su proyecto Unreal Engine para interactuar con las API de APNs de iOS. Exponga funciones de C++ a las que se pueda llamar que recuperen el token del dispositivo y lo conviertan en una cadena hexadecimal.

Ejemplo de implementación en Objective-C++ (YourProject_IOS.mm):

Objective-C++
// YourProject_IOS.mm
#import <Foundation/Foundation.h>
#import <UIKit/UIKit.h>
#import <UserNotifications/UserNotifications.h>

// Convert NSData to hex string
NSString* ConvertTokenToHexString(NSData* deviceToken)
{
    const unsigned char* bytes = (const unsigned char*)[deviceToken bytes];
    NSMutableString* hexString = [NSMutableString string];

    for (NSUInteger i = 0; i < [deviceToken length]; i++)
    {
        [hexString appendFormat:@"%02x", bytes[i]];
    }

    return hexString;
}

// C++ callable function to get APNs token
extern "C" const char* GetIOSAPNsToken()
{
    UIApplication* app = [UIApplication sharedApplication];

    // Request notification authorization
    UNUserNotificationCenter* center = [UNUserNotificationCenter currentNotificationCenter];
    [center requestAuthorizationWithOptions:(UNAuthorizationOptionAlert | 
                                             UNAuthorizationOptionSound | 
                                             UNAuthorizationOptionBadge)
                          completionHandler:^(BOOL granted, NSError* error)
    {
        if (granted)
        {
            dispatch_async(dispatch_get_main_queue(), ^{
                [app registerForRemoteNotifications];
            });
        }
    }];

    // Note: The actual token is received in application:didRegisterForRemoteNotificationsWithDeviceToken:
    // You need to implement an AppDelegate to capture this

    return nullptr; // Token is received asynchronously
}

Implementación asíncrona: El registro de tokens APNs es asíncrono. Implemente métodos AppDelegate adecuados para capturar el token cuando se reciba y, a continuación, llame a SetUninstallToken.


Verificación y resolución de problemas

Verificación de la implementación

Confirme que el seguimiento de la desinstalación funciona correctamente.

  1. Compruebe los registros: Compruebe que el registro del token aparece en los registros de salida de Unreal Engine.
  2. Compruebe la generación de tokens: Asegúrese de que los tokens se generan en el primer lanzamiento de la aplicación.
  3. Supervise el panel de control: Compruebe los datos de seguimiento de desinstalación del panel de Singular transcurridas 24-48 horas.
  4. Prueba de actualización de tokens: Borre los datos de la aplicación y compruebe que los tokens se actualizan correctamente

Problemas comunes

  • Token Android no generado: Compruebe que las dependencias de Firebase se han añadido correctamente y que google-services.json está configurado en su proyecto Android de Unreal Engine.
  • Token no actualizado: Implemente una gestión adecuada de la actualización de tokens para FCM y APN.
  • Faltan datos: Asegúrese de que los dispositivos cumplen los requisitos de la plataforma (Android 4.1+ con Google Play Services, iOS compatible con APN).
  • Error de configuración: Confirmar que el seguimiento de desinstalación está habilitado en la configuración de la plataforma Singular
  • Errores JNI: Compruebe que las clases de Firebase se incluyen correctamente en la compilación de Android y que las reglas de ProGuard no eliminan las clases necesarias.
  • Formato de token de iOS: Asegúrese de que el token APNs se convierte correctamente de datos binarios a formato de cadena hexadecimal.

Recursos adicionales: Para obtener información detallada sobre la solución de problemas, consulte la Guía de configuración del seguimiento de desinstalación de Androidy la documentación de Firebase Cloud Messaging para Android.


Referencia del método

SetUninstallToken

Registra tokens de notificación push (FCM para Android, APNs para iOS) con Singular para habilitar el seguimiento de desinstalación.

Propiedad Detalles
Descripción Pasa el token de dispositivo devuelto por APNs (iOS) o FCM (Android). El token suele ser un dato binario en su forma nativa, pero es necesario pasarlo como cadena.
Firma static void SetUninstallToken(FString token)
Parámetros token: FCM o APNs token de dispositivo como una cadena (formato hexadecimal para APNs).
Plataforma Android (FCM), iOS (APNs)
Temporización Llamada tras la inicialización del SDK

Ejemplos de uso:

C++
// Android FCM token
FString FCMToken = TEXT("eXaMpLeToKeN123456789abcdef");
USingularSDKBPLibrary::SetUninstallToken(FCMToken);

// iOS APNs token (hex-string format)
FString APNsToken = TEXT("ba85ab31a7c7f5c2f012587f29fb0e596d4b67e7b7b2838fa1a8582c1f7dbdee");
USingularSDKBPLibrary::SetUninstallToken(APNsToken);