Unity SDK - 추적 제거

문서

앱 삭제 추적

앱 제거를 추적하여 사용자 리텐션을 측정하고 푸시 알림 서비스를 Singular SDK와 연동하여 리인게이지먼트 캠페인을 최적화하세요.

중요: 구글은 2018년 4월에 GCM API를 더 이상 사용하지 않습니다. 모든 안드로이드 앱 제거 추적 구현에는 Firebase 클라우드 메시징(FCM)을 사용하세요.

Android 제거 추적

전제 조건

Unity 앱에서 앱 제거 추적을 구현하기 전에 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 클라우드 메시징 연동하기

아직 구성하지 않은 경우 Unity 앱에서 Firebase 클라우드 메시징을 설정합니다.

Google의 공식 가이드인 Unity용 Firebase 클라우드 메시징 설정 가이드를 따르세요. 여기에는 다음이 포함됩니다:

  1. Unity 프로젝트에 Firebase 추가
  2. Firebase 메시징 Unity 패키지 임포트
  3. Android용 Firebase 설정 구성
  4. 알림 권한 요청(Android 13 이상)

2단계: AndroidManifest.xml 구성하기

FCM 메시지를 수신하려면 Android 매니페스트에 Firebase 메시징 서비스를 등록합니다.

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 장치 토큰 등록

SDK 초기화 전에 제거 추적을 위해 FCM 디바이스 토큰을 검색하여 Singular로 전송합니다.

C#
using UnityEngine;
using Singular;
using Firebase.Messaging;
using System.Threading.Tasks;

public class UninstallTrackingManager : MonoBehaviour
{
    async void Start()
    {
        // Initialize Firebase
        await InitializeFirebase();

        // Get FCM token and register it with Singular
        await RegisterFCMToken();

        // Initialize Singular SDK after registering the token
        SingularSDK.InitializeSingularSDK();
    }

    private async Task InitializeFirebase()
    {
        var dependencyStatus = await Firebase.FirebaseApp.CheckAndFixDependenciesAsync();

        if (dependencyStatus == Firebase.DependencyStatus.Available)
        {
            Debug.Log("Firebase is ready");
        }
        else
        {
            Debug.LogError($"Could not resolve Firebase dependencies: {dependencyStatus}");
        }
    }

    private async Task RegisterFCMToken()
    {
        try
        {
            // Get FCM token
            string token = await Firebase.Messaging.FirebaseMessaging.GetTokenAsync();

            if (!string.IsNullOrEmpty(token))
            {
                // Register token with Singular BEFORE SDK initialization
                SingularSDK.RegisterTokenForUninstall(token);
                Debug.Log($"FCM token registered with Singular: {token}");
            }
            else
            {
                Debug.LogWarning("FCM token is empty");
            }
        }
        catch (System.Exception ex)
        {
            Debug.LogError($"Error getting FCM token: {ex.Message}");
        }
    }
}

중요: RegisterTokenForUninstall()메서드는SingularSDK.InitializeSingularSDK()전에 호출되어야 합니다. 초기화 후에 토큰을 등록하면 제거 추적이 활성화되지 않습니다.


4단계: 토큰 새로 고침 처리

정확한 제거 추적을 유지하려면 새로 고침할 때마다 FCM 토큰을 Singular로 업데이트하세요.

C#
using UnityEngine;
using Singular;
using Firebase.Messaging;

public class FCMTokenRefreshHandler : MonoBehaviour
{
    void Start()
    {
        // Subscribe to token refresh event
        Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;
    }

    void OnDestroy()
    {
        // Unsubscribe when destroyed
        Firebase.Messaging.FirebaseMessaging.TokenReceived -= OnTokenReceived;
    }

    private void OnTokenReceived(object sender, Firebase.Messaging.TokenReceivedEventArgs e)
    {
        Debug.Log($"New FCM token received: {e.Token}");

        // Update token with Singular
        SingularSDK.RegisterTokenForUninstall(e.Token);

        // Also send token to your server if needed
        SendTokenToServer(e.Token);
    }

    private void SendTokenToServer(string token)
    {
        // Implement your server communication logic here
        Debug.Log($"Sending token to server: {token}");
    }
}

모범 사례: FCM 토큰은 언제든지 새로 고칠 수 있습니다(앱 업데이트, 디바이스 복원 등). 항상 TokenReceived 이벤트를 구독하여 Singular를 최신 토큰으로 업데이트하세요.


iOS 앱 제거 추적

전제 조건

iOS의 앱 제거 추적은 Apple 푸시 알림 서비스(APN) 기술을 기반으로 합니다.

앱이 푸시 알림을 지원하지 않는 경우, Apple의 APN에 앱 등록하기 가이드를 참조하세요.


APNS 디바이스 토큰 등록하기

SDK가 초기화된 후 RegisterTokenForUninstall 메서드를 사용하여 APN에서 반환된 디바이스 토큰을 전달합니다.

메소드 서명:

public static void RegisterTokenForUninstall(string APNSToken)

파라미터:

  • APNSToken: APN에서 16진수 문자열로 반환된 디바이스 토큰입니다.

토큰 형식: APNS 토큰은 일반적으로 기본 형식의 바이너리 데이터이지만 16진수 문자열 표현으로 Singular에 전달해야 합니다.


사용 예

iOS 제거 추적을 위해 Singular에 APNS 디바이스 토큰을 등록합니다.

C#
using UnityEngine;
using Singular;

#if UNITY_IOS
using Unity.Notifications.iOS;
#endif

public class iOSUninstallTracking : MonoBehaviour
{
    void Start()
    {
        #if UNITY_IOS
        // Initialize Singular SDK first
        SingularSDK.InitializeSingularSDK();

        // Request notification authorization
        RequestNotificationAuthorization();
        #endif
    }

    #if UNITY_IOS
    private void RequestNotificationAuthorization()
    {
        var authorizationOption = AuthorizationOption.Alert | 
                                  AuthorizationOption.Badge | 
                                  AuthorizationOption.Sound;

        using (var req = new AuthorizationRequest(authorizationOption, true))
        {
            while (!req.IsFinished)
            {
                // Wait for authorization
            }

            string deviceToken = req.DeviceToken;

            if (!string.IsNullOrEmpty(deviceToken))
            {
                // Convert device token to hex string and register with Singular
                SingularSDK.RegisterTokenForUninstall(deviceToken);
                Debug.Log($"APNS token registered: {deviceToken}");
            }
            else
            {
                Debug.LogWarning("Failed to get APNS device token");
            }
        }
    }
    #endif
}

토큰 예시:

// Pass the APNS token as a hex-string
SingularSDK.RegisterTokenForUninstall("ba85ab31a7c7f5c2f012587f29fb0e596d4b67e7b7b2838fa1a8582c1f7dbdee");

플랫폼 차이: SDK 초기화 전에 토큰을 등록해야 하는 안드로이드와 달리, iOS 토큰은 SDK 초기화 후에등록해야 합니다.


검증 및 문제 해결

구현 확인

제거 추적이 올바르게 작동하는지 확인합니다.

  1. 로그를 확인합니다: Unity 콘솔 로그에 토큰 등록이 표시되는지 확인합니다.
  2. 토큰 생성을 테스트합니다: 첫 번째 앱 실행 시 토큰이 생성되는지 확인합니다.
  3. 대시보드 모니터링: 24-48시간 후 Singular 대시보드에서 제거 추적 데이터를 확인합니다.
  4. 토큰 새로고침 테스트: 앱 데이터를 지우고 토큰 업데이트가 올바르게 이루어졌는지 확인합니다.

일반적인 문제

  • 안드로이드 토큰이 생성되지 않았습니다: Firebase 종속성이 올바르게 추가되고 Unity 프로젝트에 Firebase가 구성되어 있는지 확인합니다.
  • 토큰이 업데이트되지 않습니다: Android의 경우 TokenReceived 이벤트에 가입했는지 또는 iOS의 경우 APN 콜백을 올바르게 처리했는지 확인합니다.
  • 누락된 데이터: 디바이스가 플랫폼 요구 사항을 충족하는지 확인합니다(Android 4.1+(Google Play 서비스 포함), iOS(APNs 지원)).
  • 구성 오류: Singular 플랫폼 설정에서 제거 추적이 활성화되어 있는지 확인합니다.
  • 초기화 순서: Android의 경우 RegisterTokenForUninstall()InitializeSingularSDK()보다 먼저 호출되는지 확인합니다.

추가 리소스: 자세한 문제 해결 방법은 Android 제거 추적 설정 가이드Unity용 Firebase 클라우드 메시징 문서를 참조하세요.