앱 삭제 추적
앱 제거를 추적하여 사용자 리텐션을 측정하고 푸시 알림 서비스를 Singular SDK와 연동하여 리인게이지먼트 캠페인을 최적화하세요.
중요: 구글은 2018년 4월에 GCM API를 더 이상 사용하지 않습니다. 모든 안드로이드 앱 제거 추적 구현에는 Firebase 클라우드 메시징(FCM)을 사용하세요.
Android 제거 추적
전제 조건
언리얼 엔진 앱에서 앱 삭제 추적을 구현하기 전에, Android 앱 삭제 트래킹 설정 가이드에 따라 Singular 플랫폼에서 앱을 구성하세요.
시스템 요구 사항
제거 추적을 사용하려면 Firebase 클라우드 메시징과 특정 디바이스 구성이 필요합니다.
FCM 요구사항(소스):
- Android 버전: 기기는 Android 4.1(API 16) 이상을 실행해야 합니다.
- Google Play 서비스: 기기에 Google Play 스토어 앱이 설치되어 있어야 합니다.
- 에뮬레이터 지원: Google API가 포함된 Android 4.1 이상 에뮬레이터가 지원됩니다.
- 배포: 앱 제거 추적을 지원하면서 Google Play 스토어 외부에 앱을 배포할 수 있습니다.
참고: 지원되지 않는 Android 버전 또는 Google Play 서비스가 없는 기기를 사용하는 사용자는 제거 추적이 되지 않습니다.
구현 단계
1단계: Firebase 클라우드 메시징 연동하기
아직 구성하지 않은 경우 언리얼 엔진 앱에서 Firebase 클라우드 메시징을 설정합니다.
Google의 공식 가이드에 따라 Android에서 Firebase 클라우드 메시징 클라이언트 앱을 설정하세요. 여기에는 다음이 포함됩니다:
- 안드로이드 프로젝트에 파이어베이스 추가하기
- 빌드.gradle 파일에 Firebase 메시징 종속성을 추가합니다.
- google-services.json에서 Firebase 설정 구성하기
- 알림 권한 요청(Android 13 이상)
2단계: 안드로이드 매니페스트.xml 구성하기
FCM 메시지를 수신하려면 Android 매니페스트에 Firebase 메시징 서비스를 등록하세요.
<service
android:name=".java.MyFirebaseMessagingService"
android:exported="false">
<intent-filter>
<action android:name="com.google.firebase.MESSAGING_EVENT" />
</intent-filter>
</service>
중요: .java.MyFirebaseMessagingService 을 FirebaseMessagingService 을 확장하는 정규화된 클래스 이름으로 바꾸세요.
3단계: FCM 장치 토큰 등록
FCM 디바이스 토큰을 검색하여 SetUninstallToken 메서드를 사용하여 제거 추적을 위해 Singular로 전송합니다.
// 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;
}
메서드 서명:
static void SetUninstallToken(FString token);
매개변수:
- 토큰: 문자열 형태의 FCM 장치 토큰
참고: SetUninstallToken 메서드는 Singular SDK가 초기화된 후에 호출해야 합니다. FCM 토큰은 SDK 초기화 후 언제든지 등록할 수 있습니다.
4단계: 토큰 새로 고침 처리
정확한 제거 추적을 유지하기 위해 새로 고침할 때마다 Singular로 FCM 토큰을 업데이트합니다.
// 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);
}
모범 사례: FCM 토큰은 언제든지 새로 고칠 수 있습니다(앱 업데이트, 디바이스 복원 등). 항상 토큰 새로고침 이벤트를 처리하여 Singular가 최신 토큰으로 업데이트되도록 하세요.
iOS 앱 제거 추적
전제 조건
iOS의 앱 제거 추적은 Apple 푸시 알림 서비스(APN) 기술을 기반으로 합니다.
앱이 푸시 알림을 지원하지 않는 경우, Apple의 APN에 앱 등록하기 가이드를 참조하세요.
APNs 디바이스 토큰 등록하기
SDK가 초기화된 후 SetUninstallToken 메서드를 사용하여 APN에서 반환된 디바이스 토큰을 전달합니다.
메서드 서명:
static void SetUninstallToken(FString token);
파라미터:
- 토큰: APN에서 16진수 문자열로 반환된 디바이스 토큰입니다.
토큰 형식: APNs 토큰은 일반적으로 기본 형식의 바이너리 데이터이지만 16진수 문자열 표현으로 Singular에 전달해야 합니다.
사용 예
iOS 제거 추적을 위해 Singular에 APNs 디바이스 토큰을 등록합니다.
// 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;
}
토큰 예시:
// Pass the APNs token as a hex-string
USingularSDKBPLibrary::SetUninstallToken(TEXT("ba85ab31a7c7f5c2f012587f29fb0e596d4b67e7b7b2838fa1a8582c1f7dbdee"));
플랫폼 일관성: SetUninstallToken 메서드는 안드로이드(FCM)와 iOS(APN) 모두에서 동일하게 작동합니다. 두 플랫폼 모두에서 SDK 초기화 후 호출하세요.
플랫폼별 토큰 검색
JNI를 통한 안드로이드 FCM 토큰
언리얼 엔진의 JNI(Java Native Interface)를 사용하여 Firebase 클라우드 메시징 토큰에 액세스합니다.
#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
구현 참고: Firebase의 getToken()은 비동기적으로 확인되는 태스크 오브젝트를 반환합니다. 프로덕션 구현에서는 완료 리스너와 함께 파이어베이스의 태스크 API를 사용하여 토큰을 올바르게 검색해야 합니다.
Objective-C++를 통한 iOS APN 토큰
언리얼 엔진에서 Objective-C++를 사용하여 Apple 푸시 알림 서비스 토큰에 액세스하세요.
구현 방법: 언리얼 엔진 프로젝트에 별도의 .mm(Objective-C++) 파일을 생성하여 iOS APNs API와 인터페이스합니다. 디바이스 토큰을 검색하고 16진수 문자열로 변환하는 C++ 호출 가능 함수를 노출합니다.
오브젝티브-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
}
비동기 구현: APN 토큰 등록은 비동기식입니다. 토큰을 수신할 때 토큰을 캡처한 다음 SetUninstallToken 을 호출할 수 있도록 적절한 AppDelegate 메서드를 구현하세요.
검증 및 문제 해결
구현 확인
제거 추적이 올바르게 작동하는지 확인합니다.
- 로그를 확인합니다: 언리얼 엔진 출력 로그에 토큰 등록이 나타나는지 확인합니다.
- 토큰 생성을 테스트합니다: 첫 앱 실행 시 토큰이 생성되는지 확인합니다.
- 대시보드 모니터링: 대시보드 모니터링: 24-48시간 후 Singular 대시보드에서 제거 추적 데이터를 확인합니다.
- 테스트 토큰 새로고침: 앱 데이터를 지우고 토큰 업데이트가 올바르게 이루어졌는지 확인합니다.
일반적인 문제
- 안드로이드 토큰이 생성되지 않았습니다: 언리얼 엔진 안드로이드 프로젝트에 Firebase 종속성이 올바르게 추가되고 google-services.json이 구성되었는지 확인합니다.
- 토큰이 업데이트되지 않습니다: FCM 및 APN 모두에 대해 적절한 토큰 새로고침 처리를 구현합니다.
- 누락된 데이터: 디바이스가 플랫폼 요구사항을 충족하는지 확인합니다(Android 4.1+, Google Play 서비스, iOS, APNs 지원).
- 구성 오류: Singular 플랫폼 설정에서 제거 추적이 활성화되어 있는지 확인합니다.
- JNI 오류: Firebase 클래스가 Android 빌드에 올바르게 포함되어 있고 ProGuard 규칙이 필요한 클래스를 제거하지 않는지 확인합니다.
- iOS 토큰 형식: APN 토큰이 바이너리 데이터에서 16진수 문자열 형식으로 올바르게 변환되었는지 확인합니다.
추가 리소스: 자세한 문제 해결 방법은 Android 제거 추적 설정 가이드및 Android용 Firebase 클라우드 메시징 설명서를 참조하세요.
메서드 참조
SetUninstallToken
제거 추적을 사용하도록 푸시 알림 토큰(Android의 경우 FCM, iOS의 경우 APN)을 Singular에 등록합니다.
| 속성 | 세부 정보 |
|---|---|
| 설명 | APN(iOS) 또는 FCM(Android)에서 반환된 디바이스 토큰을 전달합니다. 토큰은 일반적으로 기본 형식의 바이너리 데이터이지만 문자열로 전달해야 합니다. |
| 서명 |
static void SetUninstallToken(FString token)
|
| 파라미터 | 토큰: 문자열 형태의 FCM 또는 APNs 장치 토큰(APN의 경우 16진수 형식) |
| 플랫폼 | 안드로이드(FCM), iOS(APN) |
| 타이밍 | SDK 초기화 후 호출 |
사용 예시:
// Android FCM token
FString FCMToken = TEXT("eXaMpLeToKeN123456789abcdef");
USingularSDKBPLibrary::SetUninstallToken(FCMToken);
// iOS APNs token (hex-string format)
FString APNsToken = TEXT("ba85ab31a7c7f5c2f012587f29fb0e596d4b67e7b7b2838fa1a8582c1f7dbdee");
USingularSDKBPLibrary::SetUninstallToken(APNsToken);