언인스톨 트래킹

주의: 언인스톨 트래킹 기능은 엔터프라이즈 고객사에만 제공됩니다.

Android 앱에서 언인스톨 트래킹을 활성화하려면, 우선 언인스톨 트래킹 설정 가이드에 따라 Singular 플랫폼의 App에서 앱을 설정해야 합니다. 설정한 이후 다음 안내 사항을 진행하세요.

주의: Google은 2018년도 4월부터 GCM API를 더 이상 사용하지 않습니다. 언인스톨 트래킹에는 FCM을 사용해 주세요.

Firebase Cloud Messaging (FCM)를 사용해서 언인스톨 트래킹 활성화

1. FCM 연동:

언인스톨 트래킹을 위해서 Firebase Cloud Messaging (FCM) 플랫폼을 사용할 수 있습니다. FCM을 아직 도입하지 않았다면 Google의 Android에서 Firebase 클라우드 메시징 클라이언트 앱 설정 가이드를 따르세요.

FCM 필요 사항 (출처)

FCM 클라이언트에 Android 4.1 이상을 실행하며 Google Play 스토어 앱도 설치되어 있는 기기 또는 Google API로 Android 4.1을 실행하는 에뮬레이터가 필요합니다. Google Play 스토어를 통해서만 Android 앱을 배포하도록 제한되지는 않습니다.

지원되지 않는 버전의 Android를 사용하는 유저나 디바이스에는 Singular의 언인스톨 트래킹이 동작하지 않습니다.

2. AndroidManifest.xml 파일 업데이트:

앱의 AndroidManifest.xml 파일에 다음처럼 인텐트 필터를 추가합니다. (MyFirebaseMessagingService 부분은 Firebase 서비스를 구현한 실제 클래스 이름을 사용하세요.)

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

3. FCM 디바이스 토큰 등록 및 전송

마지막으로 FCM 디바이스 토큰을 OnCreate()에서 SingularConfig를 초기화한 이후 시점에 다음처럼 설정합니다.

Singular.setFCMDeviceToken(String fcmDeviceToken);

글로벌 프로퍼티 추가

Singular SDK로 추가 프로퍼티를 커스텀으로 정의하고 앱에서 발생하는 모든 세션과 이벤트에 포함해서 Singular 서버에 전송할 수 있습니다. 이 프로퍼티는 유저 관련, 앱 모드, 앱 상태 등 어떤 정보이든 될 수 있습니다. 프로퍼티를 설정하면 추후 리포트에서 데이터를 분류하는 디멘션으로 사용할 수 있습니다.

예를 들어 게임 앱이라면 “Level”이라는 프로퍼티를 정의하고 “0”으로 초기화할 수 있습니다. 이 경우 앱에서 보내는 세션과 이벤트에 "Level": "0"이라는 프로퍼티가 포함됩니다. 유저의 레벨이 상승하면 해당 프로퍼티를 “1”로 업데이트하는 것처럼 값은 계속 변경할 수 있습니다. 이렇게 설정하면 플레이어의 게임 레벨에 따른 세션, 이벤트 및 매출 데이터 등을 확인할 수 있습니다.

• 글로벌 프로퍼티는 최대 5개까지 설정할 수 있습니다.
• 앱 실행 간에도 최신 값이 유지되며 설정을 해제하거나 유저가 앱을 언언스톨하기 전에는 유지됩니다.
• 각 프로퍼티 이름과 값은 영문 200자까지 설정할 수 있습니다. 더 긴 이름과 값을 전달하면 200자까지만 확인됩니다.
• 글로벌 프로퍼티는 현재 Singular의 유저 레벨 이벤트 로그(어트리뷰션 로그 추출 가이드 참조)와 포스트백에서 확인할 수 있습니다. Singular의 집계 리포트 (리포팅 페이지나 리포팅 API)에서의 지원은 추후 추가될 예정입니다. 기능에 대한 질문이 있거나 글로벌 프로퍼티 지원에 관심이 있다면 담당 고객 성공 매니저와 상의하세요.

SingularConfig를 통한 글로벌 프로퍼티 설정

SingularConfig 내의 setGlobalProperty 메서드를 사용하면 SDK 초기화 이전에 글로벌 프로퍼티를 설정할 수 있습니다.

글로벌 프로퍼티와 값이 앱 실행 사이에도 유지되므로 프로퍼티가 이미 다른 값으로 설정되었을 가능성이 있습니다. SDK에 기존 프로퍼티를 신규 값으로 오버라이딩하려면 overrideExisting 파라미터를 사용하세요.

// 두 개의 글로벌 프로퍼티를 설정하고 기존의 값 오버라이딩
SingularConfig config = new SingularConfig(apiKey, secretKey)
  .withGlobalProperty(“MyProperty”, “MyValue”, true)
  .withGlobalProperty(“AnotherProperty”, “AnotherValue”, true);

초기화 이후 글로벌 프로퍼티 설정

앱 실행 중 언제든 다음 메서드를 통해 글로벌 프로퍼티의 설정, 설정 해제 및 값 획득이 가능합니다.

boolean result = Singular.setGlobalProperty(“MyProperty”, “MyValue”, true);

Map<String, String> map = Singular.getGlobalProperties();

Singular.unsetGlobalProperty(“MyProperty”);

Singular.clearGlobalProperties();

이전 디바이스에서 인스톨 리퍼러 수집

주의: Google은 install_referrer 브로드캐스트 사용을 중단했습니다. 자세한 내용은 다음 Android 개발자 블로그를 확인하세요: Still Using InstallBroadcast? Switch to the Play Referrer API by March 1, 2020

인스톨 리퍼러는 어트리뷰션을 판정하는 Singular의 가장 강력한 도구입니다. 또한 프러드 시도를 탐지하고 분석하는 것에도 도움이 됩니다. 인스톨 리퍼러는 Google Play Store가 제공하는 식별자로 사용자가 앱을 인스톨하기 전 클릭한 광고를 알 수 있도록 합니다.

Google Play Store 최신 버전을 사용하는 디바이스에서는 Singular SDK가 내부에 연동된 최신 Google Play Referrer API를 통해 인스톨 리퍼러 값을 자동으로 수집합니다.

혹시 이전 버전을 사용하는 디바이스에서 인스톨 리퍼러를 수집하고자 한다면 다음 단계를 따르세요.

기존 인스톨 리퍼러 리시버가 있는 경우

이미 앱 내에 Android에서 INSTALL_REFERRER를 받도록 BroadcastReceiver가 구현되었을 수도 있습니다.

이 경우 해당 BroadcastReceiver의 onReceive 메서드에서 다음 코드를 추가하세요.

new SingularInstallReceiver().onReceive(context, intent);

예를 들어 기존의 리시버가 MyCustomInstallReceiver라는 이름이라면 다음과 같은 형태가 됩니다.

public class MyCustomInstallReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        // Pass install referrer information on to Singular
        new SingularInstallReceiver().onReceive(context, intent);
        // ...
    }
}

다른 인스톨 리퍼러 리시버가 없는 경우

앱 내에 다른 인스톨 리시버가 없는 경우 Singusr SDK가 리시버를 등록할 수 있도록 manifest 파일의 <application> 태그 아래에 다음 코드를 추가하세요.

<receiver android:exported="true" android:name="com.singular.sdk.SingularInstallReceiver">
    <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER" />
    </intent-filter>
</receiver>

세션 관리

Android API 14 (Ice Cream Sandwich) 이상에서는 Singular SDK가 자동으로 세션을 관리할 수 있습니다. 따라서 앱의 minSdkVersion가 14 이상이라면 세션 관리를 위해 추가적인 설정을 하지 않아도 됩니다.

세션 타임아웃 수정

기본적으로 앱이 포그라운드로 되돌아오기 전 백그라운드에서 60초 이상 머무른 경우, Singular SDK는 새로운 세션을 등록합니다.

이 기본 타임아웃 값은 SDK를 초기화하기 전 SingularConfig 오브젝트의 withSessionTimeoutInSec(<timeout in seconds>)를 사용해서 변경할 수 있습니다.

다음 예제를 참조하세요.

// 세션 타임 아웃을 120초로 설정
SingularConfig config = new SingularConfig(apiKey, secretKey)
.withSessionTimeoutInSec(120); 

수동 세션 관리

앱의 minSdkVersion가 14 미만이라면 세션 처리 메서드, onActivityPaused와 onActivityPaused를 사용해서 각 액티비티마다 수동으로 세션을 관리해야 합니다.

주의: 공통으로 사용하는 기본 커스텀 액티비티 클래스가 있고 다른 모든 액티비티가 이로부터 파생되는 경우 공통 액티비티의 onResume와 onPause 메서드에서 onActivityResumed와 onActivityPaused를 각각 호출할 수 있습니다.

@Override
protected void onResume() {
    super.onResume();
    Singular.onActivityResumed();
    .... //other code if any
}

@Override
protected void onPause() {
    super.onPause();
    Singular.onActivityPaused();
    .... //other code if any
}

JavaScript 인터페이스 사용

앱 내의 javaScript 코드에서 Singular를 호출해야 하는 경우 JavaScript 인터페이스를 사용할 수 있습니다.

예를 들어 JavaScript 인터페이스를 설정한다면 다음처럼 JavaScript 코드에서 Singular에 이벤트를 전송할 수 있습니다.

SingularInterface.event('event');
SingularInterface.event('test',
   JSON.stringify({"a1":"bar", "a2":"boo", "a3":"baz"}));

이 인터페이스는 다음과 같은 SDK 메서드를 지원합니다.

• setCustomUserID
• unsetCustomUserID
• event
• revenue

JavaScript 인터페이스 활성화

인터페이스를 활성화하려면 액티비티에 다음처럼 코드를 추가합니다. 다음은 "myWebView"라는 이름의 웹뷰를 사용할 때의 예제입니다.

SingularJSInterface singularJSInterfaceInstance = new SingularJSInterface(this);
singularJSInterfaceInstance.setWebViewId(R.id.webview);
myWebView.addjavascriptInterface(singularJSInterfaceInstance, "SingularInterface");

주의:

• 하나 이상의 웹뷰를 사용하는 경우 각각의 웹뷰에 위 단계를 진행해주세요.
• 애플리케이션의 onCreate 메서드에 해당 코드를 삽입하는 것을 권장합니다.

onCreate 메서드는 다음과 같은 형태가 됩니다.

public void onCreate (Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.main);
      WebView myWebView = (WebView) this.findViewById(R.id.webview);
      WebSettings webSettings = myWebView.getSettings();
      webSettings.setjavaScriptEnabled(true);
      myWebView.loadUrl("file:///android_asset/index.html");
      SingularConfig config = new SingularConfig(apiKey, secret);
      Singular.init(this, config);
      SingularJSInterface singularJSInterfaceInstance = 
          new SingularJSInterface(this);
      singularJSInterfaceInstance.setWebViewId(R.id.webview);
      myWebView.addjavascriptInterface(singularJSInterfaceInstance,
          "SingularInterface");
}

OAID (Open Advertising ID) 수집

Google Play를 사용하지 않는 국가의 경우, Android 디바이스에 GAID, 혹은 Singular에서는 AIFA라고 부르는 Google 광고 ID가 존재하지 않습니다. 대신 해당 디바이스는 OAID (Open Advertising Identifier)라는 다른 ID를 가지고 있을 수 있고 이 경우 디바이스에서 발생하는 세션과 이벤트 추적에 활용할 수 있습니다.

OAID는 현재 Huawei와 모바일 시큐리티 얼라이언스(MSA)에 속한 브랜드에서 사용할 수 있습니다.

앱에서 OAID를 수집하기 위해서는 우선 MSA SDK와 Huawei OAID SDK를 연동해야 합니다. 모든 제공 플랫폼에서 OAID를 수집하기 위해서는 두 SDK 모두를 연동해야 합니다.

다음으로, Singular 초기화 전 withOAIDCollection 메서드를 호출하여 트래킹에 OAID를 사용함을 Singular SDK에 알려야 합니다.

SingularConfig config = new SingularConfig("apikey","secret")
.withOAIDCollection();
Singular.init(context, config);

Singular SDK는 OAID가 있는지 여부와 ID를 수집하는데 사용할 OAID SDK를 자동으로 감지합니다.

IMEI 숫자 수집

Google Play를 사용하지 않는 국가에서 앱을 서비스하는 경우 디바이스에 Google 광고 ID가 없을 수 있습니다. 이 경우 디바이스 IMEI (International Mobile Equipment Identity)를 수집하는 방법을 안내드립니다.

주의: Google Play 서비스를 사용하는 경우라면 Google Play 서비스 규약 상 IMEI 숫자의 수집은 해당 규약을 위배하므로 수집하지 말아야 합니다.

IMEI 숫자를 수집하려면 다음 단계를 따르세요.

• android.permission.READ_PHONE_STATE 권한을 앱의 AndroidManifest.xml 파일에 추가합니다.
• <uses-permission android:name="android.permission.READ_PHONE_STATE"/>
• 디바이스의 IMEI 숫자를 가져오기 위해 다음 코드를 추가합니다.

TelephonyManager telephonyManager = (TelephonyManager)getSystemService(Context.TELEPHONY_SERVICE);

String imei = null;
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    imei = telephonyManager.getImei();
} else {
    imei = telephonyManager.getDeviceId();
}

IMEI 숫자를 Singular에 보내려면 다음 메서드 중 하나를 택하여 사용하세요.

• 권장: 다음 예제를 참조하여 Singular SDK 초기화 전에 withIMEI를 사용해서 SingularConfig에 IMEI 숫자를 설정합니다. 이렇게 설정하면 가장 최초의 세션부터 Singular에 IMEI를 전송할 수 있습니다.

  SingularConfig config = new SingularConfig("apikey","secret").withIMEI("537769845792516");
  Singular.init(context, config);

• SDK 초기화 이후의 시점에서 IMEI 숫자를 설정하려는 경우 setIMEI를 호출하세요.

Singular.setIMEI(IMEIString);

GDPR 규정 준수

Singular SDK는 고객사가 GDPR 규정을 준수하고 사용자의 트래킹 동의 및 비동의 사항을 Singular에 알리는데 필요한 여러 메서드를 제공합니다.

Singular.trackingOptIn();

Singular.trackingUnder13();

Singular.stopAllTracking();

Singular.resumeAllTracking();

Singular.isAllTrackingStopped();