SDK do Unreal Engine - Rastreamento de desinstalação

Documento

Rastreamento de desinstalação

Rastreie desinstalações de aplicativos para medir a retenção de usuários e otimizar campanhas de reengajamento integrando serviços de notificação por push com o SDK Singular.

Importante: o Google descontinuou as APIs do GCM em abril de 2018. Use o Firebase Cloud Messaging (FCM) para todas as implementações de rastreamento de desinstalação do Android.

Rastreamento de desinstalação do Android

Pré-requisitos

Antes de implementar o rastreamento de desinstalação em seu aplicativo Unreal Engine, configure seu aplicativo na plataforma Singular seguindo o guia Configurando o rastreamento de desinstalação do Android.


Requisitos do sistema

O rastreamento de desinstalação requer o Firebase Cloud Messaging e configurações específicas do dispositivo.

Requisitos do FCM(fonte):

  • Versão do Android: Os dispositivos devem executar o Android 4.1 (API 16) ou superior
  • Serviços do Google Play: Os dispositivos devem ter o aplicativo Google Play Store instalado
  • Suporte de emulador: São suportados emuladores Android 4.1+ com APIs do Google
  • Distribuição: As aplicações podem ser distribuídas fora da Google Play Store, continuando a suportar o controlo de desinstalações

Nota: Os utilizadores de versões do Android não suportadas ou de dispositivos sem o Google Play Services não serão rastreados para desinstalações.


Etapas de implementação

Etapa 1: Integrar o Firebase Cloud Messaging

Configure o Firebase Cloud Messaging no seu aplicativo Unreal Engine, se ainda não estiver configurado.

Siga o guia oficial do Google para Configurar um aplicativo cliente do Firebase Cloud Messaging no Android. Isso inclui:

  1. Adicionar o Firebase ao seu projeto Android
  2. Adicionar a dependência do Firebase Messaging ao seu arquivo build.gradle
  3. Configurar as definições do Firebase em google-services.json
  4. Solicitar permissões de notificação (Android 13+)

Etapa 2: Configurar o AndroidManifest.xml

Registre seu Firebase Messaging Service no manifesto do Android para receber mensagens 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: Substitua .java.MyFirebaseMessagingService pelo nome totalmente qualificado da sua classe que estende FirebaseMessagingService.


Passo 3: Registar o Token de Dispositivo FCM

Recupere o token de dispositivo FCM e envie-o para a Singular para rastrear a desinstalação usando o 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;
}

Assinatura do método:

static void SetUninstallToken(FString token);

Parâmetros:

  • token: O token do dispositivo FCM como uma cadeia de caracteres

Nota: O método SetUninstallToken deve ser chamado depois que o SDK da Singular for inicializado. O token FCM pode ser registrado a qualquer momento após a inicialização do SDK.


Etapa 4: Manipular a atualização do token

Atualize o token FCM com o Singular sempre que ele for atualizado para manter o rastreamento preciso da desinstalação.

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);
}

Melhores práticas: Os tokens FCM podem ser atualizados a qualquer momento (atualizações de aplicativos, restauração de dispositivos, etc.). Sempre manipule eventos de atualização de token para manter o Singular atualizado com o token mais recente.


Rastreamento de desinstalação do iOS

Pré-requisitos

O rastreamento de desinstalação no iOS é baseado na tecnologia do serviço de notificação por push da Apple (APNs).

Se o seu aplicativo não for compatível com notificações por push, consulte o guia da Apple para Registrar seu aplicativo com APNs.


Registar o Token de Dispositivo APNs

Passe o token do dispositivo devolvido pelos APNs utilizando o método SetUninstallToken depois de o SDK ser inicializado.

Assinatura do método:

static void SetUninstallToken(FString token);

Parâmetros:

  • token: O token do dispositivo devolvido pelas APNs como uma cadeia de caracteres hexadecimal

Formato do token: O token APNs é normalmente um dado binário na sua forma nativa, mas é necessário passá-lo ao Singular como uma representação de cadeia hexadecimal.


Exemplo de utilização

Registre o token de dispositivo APNs com o Singular para rastreamento de desinstalação do 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;
}

Exemplo de token:

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

Consistência da plataforma: O método SetUninstallToken funciona de forma idêntica para Android (FCM) e iOS (APNs). Chame-o após a inicialização do SDK em ambas as plataformas.


Recuperação de token específica da plataforma

Token FCM do Android via JNI

Acesse o token do Firebase Cloud Messaging usando JNI (Java Native Interface) no 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 implementação: O site getToken()do Firebase retorna um objeto Task que é resolvido de forma assíncrona. As implementações de produção devem usar a API de tarefas do Firebase com ouvintes de conclusão para recuperar corretamente o token.


Token de APNs do iOS via Objective-C++

Acesse o token do serviço de notificação por push da Apple usando Objective-C++ no Unreal Engine.

Abordagem de implementação: Crie um arquivo .mm (Objective-C++) separado no seu projeto do Unreal Engine para fazer a interface com as APIs de APNs do iOS. Exponha funções chamáveis do C++ que recuperam o token do dispositivo e o convertem em uma cadeia de caracteres hexadecimal.

Exemplo de implementação 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
}

Implementação assíncrona: O registo do token das APNs é assíncrono. Implemente métodos AppDelegate adequados para capturar o token quando este for recebido e, em seguida, chame SetUninstallToken.


Verificação e resolução de problemas

Verificar a implementação

Confirme se o acompanhamento da desinstalação está a funcionar corretamente.

  1. Verifique os registos: Verifique se o registro do token aparece nos logs de saída do Unreal Engine
  2. Teste a geração de tokens: Garantir que os tokens sejam gerados na primeira inicialização do aplicativo
  3. Monitorar o painel: Verifique o painel do Singular para obter dados de rastreamento de desinstalação após 24-48 horas
  4. Teste a atualização do token: Limpar os dados do aplicativo e verificar se o token é atualizado corretamente

Problemas comuns

  • Token Android não gerado: Verifique se as dependências do Firebase foram adicionadas corretamente e se o google-services.json está configurado no seu projeto Android do Unreal Engine
  • Token não atualizado: Implemente o tratamento adequado de atualização de token para FCM e APNs
  • Dados ausentes: Certifique-se de que os dispositivos atendam aos requisitos da plataforma (Android 4.1+ com Google Play Services, iOS com suporte a APNs)
  • Erro de configuração: Confirmar se o rastreamento de desinstalação está ativado nas configurações da plataforma Singular
  • Erros de JNI: Verifique se as classes do Firebase estão incluídas corretamente na compilação do Android e se as regras do ProGuard não removem as classes necessárias
  • Formato de token do iOS: Certifique-se de que o token de APNs seja convertido corretamente de dados binários para o formato de cadeia hexadecimal

Recursos adicionais: Para obter uma solução de problemas detalhada, consulte o Guia de configuração de rastreamento de desinstalação do Androide a Documentação do Firebase Cloud Messaging para Android.


Referência do método

SetUninstallToken

Registrar tokens de notificação por push (FCM para Android, APNs para iOS) com Singular para habilitar o rastreamento de desinstalação.

Propriedade Detalhes
Descrição Passa o token de dispositivo retornado de APNs (iOS) ou FCM (Android). O token é geralmente um dado binário na forma nativa, mas você precisa passá-lo como uma string.
Assinatura static void SetUninstallToken(FString token)
Parâmetros token: Token de dispositivo FCM ou APNs como uma cadeia de caracteres (formato hexadecimal para APNs)
Plataforma Android (FCM), iOS (APNs)
Tempo de execução Chamada após a inicialização do SDK

Exemplos de utilização:

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

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