Cordova SDK - 추적 제거

팔로우
Avatar
Jared Ornstead
Updated
문서

앱 삭제 추적

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

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

개요

제거 추적 작동 방식

앱 제거 추적은 Singular에 푸시 알림 토큰을 등록하여 앱 제거를 모니터링합니다. 디바이스가 더 이상 푸시 알림에 응답하지 않으면 Singular는 해당 앱을 제거된 것으로 식별합니다.

  • Android: Firebase 클라우드 메시징(FCM) 토큰을 사용하여 제거를 감지합니다.
  • iOS: Apple 푸시 알림 서비스(APN) 토큰을 사용하여 앱 제거를 감지합니다.
  • 데이터 정확도: 시간 경과에 따른 사용자 리텐션 및 참여도에 대한 인사이트를 제공합니다.

안드로이드 앱 제거 추적

전제 조건

안드로이드 앱 제거 추적을 구현하기 전에 안드로이드 앱 제거 추적 설정 가이드에 따라 Singular 플랫폼에서 앱을 구성하세요.

요구 사항

  • Android 버전: 기기는 Android 4.1(API 16) 이상을 실행해야 합니다.
  • Google Play 서비스: 기기에 Google Play 스토어 앱이 설치되어 있어야 합니다.
  • 파이어베이스 설정: 프로젝트에서 Firebase 클라우드 메시징을 구성해야 합니다.
  • 권한: 안드로이드 13 이상은 명시적 알림 권한이 필요합니다.

구현 단계

1단계: Firebase 플러그인 설치

푸시 알림 지원을 위해 Cordova 프로젝트에 Firebase 플러그인을 추가합니다. cordova-plugin-firebase-messaging 플러그인을 사용하는 것이 좋습니다.

bash 
cordova plugin add cordova-plugin-firebase-messaging

자세한 Firebase 설정 지침은 플러그인 설명서를 참조하세요.

2단계: Firebase 구성

Android용 Cordova 프로젝트에 Firebase 구성 파일을 추가합니다.

  1. Firebase 콘솔 프로젝트에 Android 앱을 등록합니다.
  2. google-services.json 을 다운로드하여 프로젝트 루트 또는 platforms/android/app/에 배치합니다.
  3. 플러그인 설치 중에 프로젝트에 Firebase 메시징 종속성이 추가되었는지 확인합니다.

3단계: 알림 권한 요청

FCM 토큰을 가져오기 전에 사용자에게 알림 권한을 요청합니다(Android 13 이상에 필요).

JavaScript 
document.addEventListener('deviceready', initializeApp, false);

function initializeApp() {
  if (device.platform === 'Android') {
    // Request notification permission (Android 13+)
    requestAndroidNotificationPermission();
  }
}

function requestAndroidNotificationPermission() {
  // Check Android version
  if (device.version >= 13) {
    cordova.plugins.permissions.requestPermission(
      cordova.plugins.permissions.POST_NOTIFICATIONS,
      function(status) {
        if (status.hasPermission) {
          console.log('Notification permission granted');
          retrieveAndRegisterFCMToken();
        } else {
          console.warn('Notification permission denied - uninstall tracking unavailable');
        }
      },
      function(error) {
        console.error('Permission request error:', error);
      }
    );
  } else {
    // Android 12 and below automatically have permission
    retrieveAndRegisterFCMToken();
  }
}

참고: 권한을 요청하려면 코도바 플러그인 및 안드로이드 권한 플러그인을 설치하세요: 

cordova plugin add cordova-plugin-android-permissions

4단계: FCM 토큰 검색 및 등록하기

권한이 부여된 후 setUninstallToken() 메서드를 사용하여 FCM 디바이스 토큰을 가져와 Singular에 등록합니다.

JavaScript 
function retrieveAndRegisterFCMToken() {
  // Get FCM token
  cordova.plugins.firebase.messaging.getToken().then(function(token) {
    if (token) {
      console.log('FCM token retrieved:', token);
      
      // Register token with Singular for uninstall tracking
      cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
      
      console.log('FCM token registered with Singular');
    } else {
      console.warn('No FCM token available');
    }
  }).catch(function(error) {
    console.error('Error retrieving FCM token:', error);
  });
}

전체 메서드 설명서는 setUninstallToken 참조를 참조하세요.

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

정확한 제거 추적을 유지하기 위해 새로 고침할 때마다 Singular로 FCM 토큰을 업데이트합니다.

JavaScript 
document.addEventListener('deviceready', setupTokenRefreshListener, false);

function setupTokenRefreshListener() {
  if (device.platform === 'Android') {
    // Listen for FCM token refresh events
    cordova.plugins.firebase.messaging.onTokenRefresh(function(token) {
      console.log('FCM token refreshed:', token);
      
      // Update Singular with new token
      cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
    });
  }
}

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

iOS 앱 제거 추적

전제 조건

iOS 앱 제거 추적 설정 가이드에 따라 Singular 플랫폼에서 iOS 앱을 구성합니다.

iOS의 앱 제거 추적은 Apple 푸시 알림 서비스(APN) 기술을 사용합니다. 앱이 푸시 알림을 지원하지 않는 경우 Apple의 APN에 앱 등록하기 가이드를 참조하세요.

구현 단계

1단계: iOS 알림 권한 요청

사용자에게 알림 권한을 요청하고 APNS 디바이스 토큰을 검색합니다.

JavaScript 
document.addEventListener('deviceready', initializeIOSTracking, false);

function initializeIOSTracking() {
  if (device.platform === 'iOS') {
    requestIOSNotificationPermission();
  }
}

function requestIOSNotificationPermission() {
  // Request iOS notification authorization
  cordova.plugins.firebase.messaging.requestPermission({
    forceShow: true
  }).then(function(hasPermission) {
    if (hasPermission) {
      console.log('iOS notification permission granted');
      retrieveAndRegisterAPNSToken();
    } else {
      console.warn('iOS notification permission denied - uninstall tracking unavailable');
    }
  }).catch(function(error) {
    console.error('Error requesting iOS notification permission:', error);
  });
}

2단계: APNS 토큰 검색 및 등록하기

권한이 부여된 후 APNS 디바이스 토큰을 가져와 setUninstallToken() 방법을 사용하여 Singular에 등록합니다.

JavaScript 
function retrieveAndRegisterAPNSToken() {
  // Get APNS token (iOS)
  cordova.plugins.firebase.messaging.getToken().then(function(token) {
    if (token) {
      console.log('APNS token retrieved:', token);
      
      // Register token with Singular for uninstall tracking
      cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
      
      console.log('APNS token registered with Singular');
    } else {
      console.warn('No APNS token available');
    }
  }).catch(function(error) {
    console.error('Error retrieving APNS token:', error);
  });
}

토큰 형식: Firebase 메시징에서 검색한 APNS 토큰은 이미 Singular에 맞게 올바르게 포맷되어 있습니다. 추가 변환이 필요하지 않습니다.

3단계: 토큰 새로 고침 처리(iOS)

앱 수명 주기 동안 변경되는 경우 APNS 토큰을 Singular로 업데이트합니다.

JavaScript 
document.addEventListener('deviceready', setupIOSTokenRefreshListener, false);

function setupIOSTokenRefreshListener() {
  if (device.platform === 'iOS') {
    // Listen for APNS token refresh events
    cordova.plugins.firebase.messaging.onTokenRefresh(function(token) {
      console.log('APNS token refreshed:', token);
      
      // Update Singular with new token
      cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
    });
  }
}

완벽한 크로스 플랫폼 구현

연동 제거 추적 설정

적절한 오류 처리 및 토큰 새로 고침 로직을 통해 Android 및 iOS 플랫폼 모두에 대한 제거 추적을 구현하세요.

JavaScript 
document.addEventListener('deviceready', initializeUninstallTracking, false);

function initializeUninstallTracking() {
  console.log('Initializing uninstall tracking for:', device.platform);
  
  // Setup token refresh listener for both platforms
  setupTokenRefreshListener();
  
  // Platform-specific initialization
  if (device.platform === 'Android') {
    setupAndroidUninstallTracking();
  } else if (device.platform === 'iOS') {
    setupIOSUninstallTracking();
  }
}

function setupAndroidUninstallTracking() {
  // Check Android version for permission requirements
  if (device.version >= 13) {
    // Request notification permission for Android 13+
    cordova.plugins.permissions.requestPermission(
      cordova.plugins.permissions.POST_NOTIFICATIONS,
      function(status) {
        if (status.hasPermission) {
          retrieveAndRegisterToken();
        } else {
          console.warn('Android notification permission denied');
        }
      },
      function(error) {
        console.error('Permission request error:', error);
      }
    );
  } else {
    // Android 12 and below - permission not required
    retrieveAndRegisterToken();
  }
}

function setupIOSUninstallTracking() {
  // Request iOS notification authorization
  cordova.plugins.firebase.messaging.requestPermission({
    forceShow: true
  }).then(function(hasPermission) {
    if (hasPermission) {
      retrieveAndRegisterToken();
    } else {
      console.warn('iOS notification permission denied');
    }
  }).catch(function(error) {
    console.error('Error requesting iOS permission:', error);
  });
}

function retrieveAndRegisterToken() {
  // Get push notification token (FCM for Android, APNS for iOS)
  cordova.plugins.firebase.messaging.getToken()
    .then(function(token) {
      if (token) {
        console.log('Token retrieved for ' + device.platform + ':', token);
        
        // Register token with Singular
        cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
        
        console.log('Token registered with Singular successfully');
      } else {
        console.warn('No token available for ' + device.platform);
      }
    })
    .catch(function(error) {
      console.error('Error retrieving token:', error);
    });
}

function setupTokenRefreshListener() {
  // Listen for token refresh events on both platforms
  cordova.plugins.firebase.messaging.onTokenRefresh(function(token) {
    console.log('Token refreshed for ' + device.platform + ':', token);
    
    // Update Singular with new token
    cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
  });
}

검증 및 문제 해결

구현 확인

프로덕션에 배포하기 전에 제거 추적이 올바르게 작동하는지 확인하세요.

  1. 로그를 확인합니다: 콘솔 로그에 토큰 등록이 올바른 형식으로 표시되는지 확인합니다.
  2. 토큰 생성 테스트: 권한 부여 후 앱을 처음 실행할 때 토큰이 생성되는지 확인합니다.
  3. 대시보드 모니터링: 대시보드 모니터링: 24-48시간 후 Singular 대시보드에서 제거 추적 데이터를 확인합니다.
  4. 토큰 새로 고침 테스트: 앱 재실행 시 앱 데이터를 지우고 토큰 업데이트가 올바르게 수행되는지 확인합니다.

일반적인 문제

  • 토큰이 생성되지 않음: Firebase 플러그인이 올바르게 설치되어 있고 Cordova 프로젝트에 Firebase가 구성되어 있는지 확인합니다.
  • 권한이 거부되었습니다: 사용자가 알림 권한을 부여했는지 확인(Android 13 이상 및 모든 iOS 버전에 필요)
  • 토큰이 업데이트되지 않음: 두 플랫폼 모두에 대해 onTokenRefresh 이벤트를 구독했는지 확인하세요.
  • 누락된 데이터: 디바이스가 플랫폼 요구 사항을 충족하는지 확인합니다(Android 4.1+의 경우 Google Play 서비스, iOS의 경우 APN 지원).
  • 구성 오류: 앱의 Singular 플랫폼 설정에서 앱 제거 추적이 활성화되어 있는지 확인합니다.
  • 파이어베이스 설정: Android의 경우 google-services.json 이 올바른 위치에 있는지 확인하세요. iOS의 경우 GoogleService-Info.plist 이 Xcode 프로젝트에 추가되었는지 확인합니다.

추가 리소스: 자세한 문제 해결 방법은 Android 제거 추적 설정 가이드, iOS 제거 추적 설정 가이드 및 Firebase 메시징 플러그인 문서를 참조하세요.

모범 사례

  • 권한을 일찍 요청하세요: 온보딩 중 또는 사용자 값이 설정될 때 알림 권한을 요청하세요.
  • 거부를 정중하게 처리하세요: 권한이 거부된 경우 명확한 메시지를 제공하고 사용자에게 이점을 설명하세요.
  • 두 플랫폼 모두 테스트: 두 플랫폼 모두 테스트: 서로 다른 OS 버전의 Android와 iOS 모두에서 구현이 작동하는지 확인
  • 토큰 새로 고침 모니터링: 토큰 업데이트를 자동으로 처리하기 위해 항상 토큰 새로 고침 리스너를 구현하세요.
  • 디버깅을 위한 로그: 개발 중 상세 로깅을 활성화하여 토큰 생성 및 등록을 추적합니다.