Android SDK 고급 옵션

Singular Android SDK
다운로드 Singular Android SDK 9.5.0 버전
호환성

Android 4.0.1 (Ice Cream Sandwich) 이상

  • 본 SDK는 Play Store 4 버전 이상을 사용하는 디바이스의 Android 광고 ID를 사용합니다. 이하 버전의 디바이스는 Android ID를 사용합니다.
  • 최신 SDK 버전은 Android 4.0.1 이하 버전에서 테스트를 진행하지 않아 호환성이 보장되지 않습니다.
샘플 앱 베스트 프랙티스에 기반한 전체 SDK 연동 방법 확인을 위해 샘플 앱을 참조해 주세요.
연동 가이드

 

언인스톨 트래킹

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

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 파라미터를 사용하세요.

withGlobalProperty 메서드
정의 Set a global property.
메서드 withGlobalProperty(String key, String value, boolean overrideExisting)
사용예
// 두 개의 글로벌 프로퍼티를 설정하고 기존의 값 오버라이딩
SingularConfig config = new SingularConfig(apiKey, secretKey)
  .withGlobalProperty(“MyProperty”, “MyValue”, true)
  .withGlobalProperty(“AnotherProperty”, “AnotherValue”, true);

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

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

Singular.setGlobalProperty 메서드
정의

글로벌 프로퍼티를 지정한 값으로 설정.

주의:

  • 아직 존재하지 않는 프로퍼티를 설정하였으나 이미 5개의 글로벌 프로퍼티가 존재한다면 프로퍼티가 추가되지 않음
  • 프로퍼티가 이미 설정된 경우 overrideExisting 파라미터를 통해 현재 값을 오버라이드할지 결정
  • 프로퍼티가 정상 설정되면 true, 설정되지 않으면 false 값 반환
메서드 public static bool setGlobalProperty(String key, String value, boolean overrideExisting)
사용예
boolean result = Singular.setGlobalProperty(“MyProperty”, “MyValue”, true);
Singular.getGlobalProperties 메서드
정의 모든 글로벌 프로퍼티를 획득하고 맵 형태로 현재 값 반환.
메서드 public static Map<String, String> getGlobalProperties()
사용예
Map<String, String> map = Singular.getGlobalProperties();
Singular.unsetGlobalProperty 메서드
정의 하나의 글로벌 프로퍼티 삭제.
메서드 public static void unsetGlobalProperty(String key)
사용예
Singular.unsetGlobalProperty(“MyProperty”);
Singular.clearGlobalProperties 메서드
정의 모든 글로벌 프로퍼티 삭제.
메서드 public static void clearGlobalProperties()
사용예
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를 각각 호출할 수 있습니다.

Singular.onActivityResumed 메서드
정의 Singular 세션 관리를 위해 액티비티의 onResume 메서드 내에서 본 메서드 호출
메서드 public static void onActivityResumed()
사용예
@Override
protected void onResume() {
    super.onResume();
    Singular.onActivityResumed();
    .... //other code if any
}
Singular.onActivityPaused 메서드
정의 Singular 세션 관리를 위해 액티비티의 onPause 메서드 내에서 본 메서드 호출
메서드 public static void onActivityPaused()
사용예
@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 SDKHuawei 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 메서드
정의 Singular에 디바이스의 IMEI 숫자를 전송
메서드 public void setIMEI(string IMEIString)
사용예
Singular.setIMEI(IMEIString);

GDPR 규정 준수

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

Singular.trackingOptIn 메서드
정의 Singular에 유저의 트래킹 동의(옵트인)를 고지
사용예
Singular.trackingOptIn();
Singular.trackingUnder13 메서드
정의 Singular에 유저가 미성년(13세 미만)임을 고지
사용예
Singular.trackingUnder13();
Singular.stopAllTracking 메서드
정의 해당 앱에서 해당 유저를 트래킹하는 모든 행위를 중단

주의: 이 메서드를 호출하면 SDK가 비활성화되며 앱의 재시작 이후에도 상태 값이 보존됩니다. 트래킹을 재개하려면 resumeAllTracking() 메서드를 명시적으로 호출해야 합니다.

사용예
Singular.stopAllTracking();
Singular.resumeAllTracking 메서드
정의 해당 앱에서 해당 유저의 트래킹을 재개
사용예
Singular.resumeAllTracking();
Singular.isAllTrackingStopped 메서드
정의 해당 앱에서 해당 유저의 트래킹 중단 상태를 확인. StopAllTracking() 메서드를 통해 현재 트래킹이 중단되어 재개되지 않은 상태인 경우 true 값 반환
사용예
Singular.isAllTrackingStopped();

 

도움이 되었습니까?