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:
- Adicionar o Firebase ao seu projeto Android
- Adicionar a dependência do Firebase Messaging ao seu arquivo build.gradle
- Configurar as definições do Firebase em google-services.json
- 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.
<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.
// 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.
// 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.
// 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.
#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):
// 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.
- Verifique os registos: Verifique se o registro do token aparece nos logs de saída do Unreal Engine
- Teste a geração de tokens: Garantir que os tokens sejam gerados na primeira inicialização do aplicativo
- Monitorar o painel: Verifique o painel do Singular para obter dados de rastreamento de desinstalação após 24-48 horas
- 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:
// Android FCM token
FString FCMToken = TEXT("eXaMpLeToKeN123456789abcdef");
USingularSDKBPLibrary::SetUninstallToken(FCMToken);
// iOS APNs token (hex-string format)
FString APNsToken = TEXT("ba85ab31a7c7f5c2f012587f29fb0e596d4b67e7b7b2838fa1a8582c1f7dbdee");
USingularSDKBPLibrary::SetUninstallToken(APNsToken);