アンリアル エンジン SDK - アンインストール追跡

ドキュメント

アンインストール追跡

プッシュ通知サービスをSingular SDKと統合することで、アプリのアンインストールを追跡し、ユーザーのリテンションを測定し、リエンゲージメントキャンペーンを最適化します。

重要:Google は 2018 年 4 月に GCM API を廃止しました。 Android のアンインストールトラッキングの実装にはすべて Firebase Cloud Messaging (FCM) を使用してください。

Android アンインストールトラッキング

前提条件

アンリアル エンジン アプリにアンインストール トラッキングを実装する前に、「Setting Up Android Uninstall Tracking」のガイドに従って、Singular プラットフォームでアプリを設定してください。


システム要件

アンインストール トラッキングには、Firebase Cloud Messaging と特定のデバイス設定が必要です。

FCM の要件(ソース):

  • Android バージョン:Android 4.1 (API 16) 以降を実行しているデバイスが必要です。
  • Google Play サービス:Google Playストアアプリがインストールされている必要があります。
  • エミュレータのサポート:Google APIを搭載したAndroid 4.1以上のエミュレータに対応しています。
  • 配布:アンインストール追跡をサポートしながら、Google Play ストア以外でもアプリを配布できます。

注意:サポートされていない Android バージョンまたは Google Play サービスを利用していないデバイスのユーザーは、アンインストールを追跡されません。


実装ステップ

ステップ 1: Firebase Cloud Messaging の統合

まだ設定されていない場合は、アンリアル エンジン アプリで Firebase Cloud Messaging を設定します。

Google の公式ガイドに従ってAndroid で Firebase Cloud Messaging クライアントアプリをセットアップします。 これには以下が含まれます:

  1. Android プロジェクトに Firebase を追加します。
  2. build.gradle ファイルに Firebase Messaging 依存関係を追加します。
  3. google-services.json で Firebase の設定を行う。
  4. 通知パーミッションのリクエスト(Android 13以上)

ステップ2: AndroidManifest.xmlの設定

FCM メッセージを受信するために、Android マニフェストに Firebase Messaging Service を登録します。

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

重要 .java.MyFirebaseMessagingServiceFirebaseMessagingService を継承するクラスの完全修飾名に置き換えてください。


ステップ 3: FCM デバイストークンの登録

FCM デバイストークンを取得し、SetUninstallToken メソッドを使用してアンインストール追跡用に Singular に送信します。

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

メソッドの署名

static void SetUninstallToken(FString token);

パラメータ

  • トークン:文字列としてのFCMデバイストークン

注: SetUninstallToken メソッドは、Singular SDK が初期化された後に呼び出す必要があります。FCMトークンはSDK初期化後いつでも登録できます。


ステップ4:トークンの更新処理

FCMトークンが更新されるたびにSingularでトークンを更新し、正確なアンインストールトラッキングを維持します。

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

ベストプラクティスです:FCMトークンはいつでもリフレッシュできます(アプリのアップデート、デバイスの復元など)。トークンの更新イベントを常に処理し、Singularを最新のトークンに更新してください。


iOSのアンインストールトラッキング

前提条件

iOS のアンインストールトラッキングは、Apple Push Notification service (APNs) テクノロジーに基づいています。

アプリがプッシュ通知に対応していない場合は、Apple の「APNs にアプリを登録する」ガイドを参照してください。


APNsデバイストークンの登録

SDK が初期化された後、SetUninstallToken メソッドを使用して APNs から返されたデバイストークンを渡します。

メソッドのシグネチャ

static void SetUninstallToken(FString token);

パラメータ

  • トークンAPNsから返されたデバイストークンを16進文字列で指定します。

トークンのフォーマット:APNsトークンは通常バイナリデータですが、16進文字列表現としてSingularに渡す必要があります。


使用例

iOSのアンインストール追跡のために、APNsデバイストークンをSingularに登録します。

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

トークンの例

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

プラットフォームの一貫性: SetUninstallToken メソッドは Android (FCM) と iOS (APNs) の両方で同じように動作します。両プラットフォームのSDK初期化後に呼び出してください。


プラットフォーム固有のトークン取得

JNI 経由の Android FCM トークン

Unreal Engine で JNI (Java Native Interface) を使用して Firebase Cloud Messaging トークンにアクセスします。

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

実装上の注意:Firebase のgetToken()は、非同期に解決する Task オブジェクトを返します。本番実装では、Firebase の Task API と完了リスナーを使用して、トークンを適切に取得する必要があります。


Objective-C++ による iOS APN トークン

Unreal Engine で Objective-C++ を使用して Apple Push Notification サービス トークンにアクセスします。

実装方法:iOS APNs API とインターフェイスするために、Unreal Engine プロジェクト内に別の .mm (Objective-C++) ファイルを作成します。 デバイス トークンを取得し、16 進文字列に変換する C++ 呼び出し可能関数を公開します。

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
}

非同期実装:APNのトークン登録は非同期です。適切なAppDelegateメソッドを実装して、トークンを受信したときにキャプチャし、SetUninstallToken を呼び出します。


検証とトラブルシューティング

実装の検証

アンインストールトラッキングが正しく動作していることを確認する。

  1. ログを確認する:トークン登録がアンリアル エンジンの出力ログに表示されることを確認します。
  2. トークン生成のテスト:最初のアプリ起動時にトークンが生成されることを確認します。
  3. ダッシュボードを監視する:24~48時間後のアンインストール追跡データをSingularダッシュボードで確認します。
  4. トークン更新のテスト:アプリのデータを消去し、トークンが正しく更新されることを確認する

よくある問題

  • Android トークンが生成されない:Firebase の依存関係が正しく追加され、Unreal Engine Android プロジェクトで google-services.json が設定されていることを確認してください。
  • トークンが更新されない:FCMとAPNの両方に対して、適切なトークン更新処理を実装してください。
  • データの欠落:デバイスがプラットフォーム要件 (Android 4.1+ with Google Play Services、iOS with APNs support) を満たしていることを確認してください。
  • 設定エラー:Singularプラットフォーム設定でアンインストールトラッキングが有効になっていることを確認する
  • JNIエラー:FirebaseのクラスがAndroidのビルドに適切に含まれており、ProGuardのルールが必要なクラスを除去していないことを確認する。
  • iOSトークン形式:APN トークンがバイナリデータから 16 進文字列形式に正しく変換されていることを確認する。

その他のリソース詳細なトラブルシューティングについては、Android Uninstall Tracking Setup GuideおよびFirebase Cloud Messaging for Android Documentation を参照してください。


メソッドリファレンス

SetUninstallToken

プッシュ通知トークン(Android は FCM、iOS は APN)を Singular に登録し、アンインストール追跡を有効にします。

プロパティ 詳細
説明 APNs(iOS)またはFCM(Android)から返されたデバイストークンを渡します。 トークンは通常ネイティブ形式のバイナリデータですが、文字列として渡す必要があります。
シグネチャ static void SetUninstallToken(FString token)
パラメータ トークン:FCMまたはAPNsのデバイストークン(文字列)(APNsの場合は16進数形式
プラットフォーム Android (FCM), iOS (APNs)
タイミング SDK初期化後のコール

使用例

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

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