Android SDK 기본 연동

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

Android 4.0.1 (Ice Cream Sandwich) 이상

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

 

프로젝트에 SDK 추가

Gradle을 사용해서 SDK 추가하기

  • project/build.gradle 파일에 Singular SDK 리파지터리를 추가합니다.
    repositories {
              jcenter()
              maven { url 'http://maven.singular.net/' }
            }
    
  • app/build.gradle의 디펜던시 목록에 Singular 라이브러리를 추가합니다.
    dependencies {
              compile
          'com.google.android.gms:play-services:6.5.87'
              compile fileTree(dir: 'libs', include: ['*.jar'])
              compile 'com.android.support:appcompat-v7:21.0.3'
              ...
              compile 'com.singular.sdk:singular_sdk:9.2.9'
              ...
            }
  • Singular SDK의 이행적 의존성(transitive dependencies)을 비활성화한 경우, 앱의 build.gradle에 'com.android.installreferrer:installreferrer:1.0'를 추가하세요.
  • 기존에 이미 Google Play Services API 7.5 이상이 연동되지 않은 경우 앱의 build.gradle 파일에 다음 디펜던시를 추가하세요.
    compile 'com.google.android.gms:play-services-ads:10.0.1'

Gradle을 사용하지 않는 경우 SDK 추가

수동으로 SDK 다운로드
  • 본 페이지 최상단에서 SDK를 다운로드합니다.
  • SDK 패키지의 압축을 해제하고 Android 프로젝트의 libs 디렉터리의 libs 폴더에 Singular.aar를 추가하세요. 해당 폴더가 존재하지 않는 경우 libs라는 이름으로 디렉터리를 프로젝트 폴더 내에 생성하고 진행하세요. 보통 <project>/app/libs에 위치합니다.
Maven을 사용해서 SDK 추가

프로젝트의 pom.xml에 maven 리파지터리를 추가합니다.

<project ...>
<repositories>
    <repository>
      <id>singular.net</id>
      <url>http://maven.singular.net/</url>
    </repository>
 </repositories>
</project>

디펜던시 역시 추가합니다:

<dependency>
    <groupId>com.singular.sdk</groupId>
    <artifactId>singular_sdk</artifactId>
    <version>9.2.9</version>
</dependency>
Eclipse를 사용해서 SDK 추가

Eclipse AAR 플러그인(gradle-eclipse-aar-plugin)을 사용하면 보다 간편히 추가할 수 있습니다.

플러그인을 사용하지 않는 경우 다음 단계를 따르세요.

  • singular_sdk-9.2.9.aar의 압축 해제
  • classes.jarsingular_sdk-9.x.x.jar로 이름 변경(메인 SDK)
  • 원하는 방식대로 프로젝트에 'com.android.installreferrer:installreferrer:1.0' 라이브러리를 추가
  • AAR 내의 AndroidManifest.xml 파일의 BIND_GET_INSTALL_REFERRER_SERVICE 권한을 AndroidManifest.xml로 복사
  • AAR 내의 AndroidManifest.xml 파일의 CHECK_LICENSE 권한을 AndroidManifest.xml로 복사
Proguard 사용시 SDK 추가

proguard.config 파일에 다음 코드를 추가하세요.

-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }

준비 사항 설정

권한 추가

AndroidManifest.xml 파일의 <manifest> 태그 아래에 다음 권한을 추가합니다.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="BIND_GET_INSTALL_REFERRER_SERVICE" />

주의: 앱에 android.permission.GET_TASKS 권한이 추가되어 있다면 앱이 유저에 의해 실제로 열리기 전에도 앱이 초기화될 수 있습니다. 이 경우 실제 실행 전 Singular SDK가 초기화되면서 인스톨 시간에 불일치가 발생할 수 있습니다. 이러한 이슈를 방지하려면 해당 권한이 실제로 필요하지 않은 경우 이를 삭제하거나, 실제로 유저가 앱을 최초로 여는 시점 이후에 Singular SDK의 초기화가 이뤄지도록 호출 시점을 옮겨 주세요.

Singular 라이브러리 임포트

Singular 라이브러리를 임포트하려면 다음 코드를 추가하세요.

import com.singular.sdk.*;

Singular SDK 초기화

SDK 초기화 코드는 앱이 열릴 때마다 호출돼야 합니다. 이는 Singular의 어트리뷰션 기능이 동작하기 위한 전제 조건이자, Singular에 새 세션을 보내서 유저 리텐션을 계산하는 기준으로 사용됩니다.

1. SingularConfig 오브젝트 생성

SDK 초기화 전에 SingularConfig를 생성하고 다음 정보를 포함합니다.

  • 고객사의 API Key와 API Secret
  • 선택 사항으로 SDK preference를 설정할 수 있습니다.

기본 SingularConfig 오브젝트를 생성하려면 다음 코드를 사용하세요.

SingularConfig config = new SingularConfig(apiKey, secretKey)

 기본 오브젝트 대신 Singular에서 제공하는 여러 추가 기능을 설정할 수도 있습니다.

설정을 추가하려면 다음 예제처럼 SingularConfig 오브젝트에 ".with" 메서드를 사용하세요.

// 유저 ID를 포함하도록 설정합니다
// 또한 세션 타임아웃을 120초로 설정합니다.
SingularConfig config = new SingularConfig(apiKey, secretKey)
    .withCustomUserId(UserId)
    .withSessionTimeoutInSec(120)

더 많은 설정 사항에 대해서는 아래 항목을 참고하세요.

SingularConfig 메서드 레퍼런스

".with" 메서드로 추가할 수 있는 전체 목록입니다.

메서드 정의 참조
.withCustomUserId(String customId) Singular에 유저 ID를 전송 유저 ID 설정
.withSingularLink(getIntent(), SingularLinkHandler handler)

Singular 링크로 딥링크 활성화

딥링크 구현
.withDDLTimeoutInSec (long timeout) 앱이 최초 실행된 경우 Singular가 디퍼드 딥링크를 검색하는 시간 길이 설정
.withDDLHandler (DeferredDeepLinkHandler handler) 신규 Singular 링크 대신 레가시 트래킹 링크로 딥링크 활성화
.withOpenURI (URI openURI) 인텐트에서 URL를 가져오기 (Singular의 링크가 아닌 링크를 통해 앱이 열린 경우 딥링크 처리)  
.withSessionTimeoutInSec (long timeout) 세션 타임아웃 설정 세션 타임아웃 수정
.withLoggingEnabled () 로그 활성화  
.withLogLevel (int level) 로그 레벨 설정(기본값은 Log.ERROR)  

2. Singular 초기화

SingularConfig 오브젝트를 생성했다면 init 메서드를 사용해서 Singular를 초기화하고 config 오브젝트를 전달합니다.

메인 액티비티와 딥링크로 직접 열리는 모든 액티비티의 onCreate에서 init을 호출하기를 권장합니다.

주의:

  • Init 메서드는 앱 내의 어떤 지점에서도 불릴 수 있지만 반드시 이벤트를 전송하기 전에 호출돼야 합니다.
  • 딥링크로 열리는 모든 액티비티에서 Singular를 초기화해야 합니다. (자세한 사항은 딥링크 연동 항목을 참조하세요.) 즉, 애플리케이션의 onCreate에서의 호출은 권장하지 않습니다. 애플리케이션 레벨에서 Singular가 초기화된 다음 액티비티에서도 초기화되면 Singular 데이터베이스에 중복 세션으로 기록될 수 있습니다.
Singular.init 메서드
정의 SingularConfig 오브젝트에 설정된 옵션과 함께 SDK 초기화
메서드
public static boolean init(Context context, SingularConfig config)
주의:
  • 애플리케이션 클래스에서 this 혹은 getApplicationContext()를 컨텍스트 파라미터로 넘길 수 있습니다.
  • 액티비티 내에서 애플리케이션 컨텍스트를 받으려면 currentActivity.getApplicationContext()를 호출하세요.
사용예
@Override
protected void onCreate (Bundle savedInstanceState) {
    ...
    Singular.init(context, config);
    ...
}

선택 사항: 유저 ID 설정

Singular SDK를 사용하여 앱에서 Singular로 유저 ID를 전달할 수 있습니다. 유저 ID는 유저네임, 이메일 주소, 랜덤 생성 문자열 등 유저를 식별하는 어떤 값이라도 가능합니다. Singular로 전달한 유저 ID는 유저레벨 데이터를 추출하거나 고객사가 내부 BI 포스트백을 설정한 경우 포스트백 내의 데이터 형태로 전달될 수 있습니다.

유저 ID는 두 가지 방법 중 하나를 택하여 Singular로 전송할 수 있습니다.

  • 권장 사항: 앱이 실행되는 시점에 유저 ID를 파악할 수 있는 경우 SDK 초기화 전에 SingularConfig에 유저 ID를 설정하세요. 이 경우 최초의 세션부터 유저 ID를 Singular에 보낼 수 있습니다.
    SingularConfig config = new SingularConfig("apikey","secret")
        .withCustomUserId("custom_user_id");
    Singular.init(context, config);

유저 ID는 UnsetCustomUserId 호출을 통해 설정을 해제하거나 앱이 삭제되기 전까지 유지됩니다. 앱을 닫거나 재시작하는 것으로는 유저 ID 설정이 해제되지 않습니다.

일반적으로 유저가 서비스에 로그인하는 시점에 setCustomUserId를 호출하고 유저 로그아웃 시점에 unsetCustomUserId를 사용하는 경우가 많습니다.

Singular.setCustomUserID 메서드
정의 Singular에 유저 ID 전송
메서드
public void setCustomUserId(string customUserId)
사용예
Singular.setCustomUserId("custom_user_id");
Singular.unsetCustomUserID 메서드
정의 마지막 CustomUserId 호출에서 Singular로 전송된 유저 ID를 해제
메서드
public void unsetCustomUserId()
사용예
Singular.unsetCustomUserId();

 

도움이 되었습니까?
0명 중 0명이 도움이 되었다고 했습니다.