Android SDK 통합 안내서

 

NEW: 동영상 가이드

이 동영상에서 연동 프로세스를 자세히 살펴보세요. 동영상과 제공되는 아래 가이드 문서를 참고하는 것을 권장합니다.

시작하기 전에: SDK 사전 요구 사항

싱귤러 SDK 통합하기: 계획 및 사전요구 사항 단계를 따르세요.

이 단계는 모든 싱귤러 SDK 통합을 위한 전제 조건입니다.

1. 프로젝트에 SDK 추가하기

1.1 Gradle을 사용하여 SDK 추가하기

참고: Gradle 7부터 안드로이드는 프로젝트 또는 모듈 수준의 build.gradle보다 settings.gradle에 중앙 저장소 선언을 사용할 것을 권장합니다 .

  1. settings.gradle 파일에 Singular SDK 저장소를 추가합니다:

    dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
    google()
    mavenCentral()
    maven { url 'https://maven.singular.net/' }
    }
    }

    또는 이전 Gradle 버전에서는 프로젝트/build.gradle 파일에 Singular SDK 리포지토리를 추가합니다:

    repositories {
            mavenCentral()
    maven { url 'https://maven.singular.net/' } }
  2. app/build.gradle의 dependencies 목록Singular 라이브러리를 추가합니다:

    dependencies {
        implementation 'com.google.android.gms:play-services:6.5.87'
        implementation fileTree(dir: 'libs', include: ['*.jar'])
        ...
        implementation 'com.singular.sdk:singular_sdk:12.5.6'
        ...
    }

    삼성 갤럭시 스토어를 통해 앱을 배포하는 경우 삼성 갤럭시 스토어의 인스톨 리퍼러를 지원하기 위해 다음을 추가합니다:

    dependencies {
          ...
          implementation 'store.galaxy.samsung.installreferrer:samsung_galaxystore_install_referrer:4.0.0'
          ...
        }
  3. Singular SDK에 대한 전이 종속성을 비활성화한 경우 app/build.gradle에 다음을 추가합니다:

    dependencies {
    ... implementation 'com.android.installreferrer:installreferrer:2.2' implementation 'com.google.android.gms:play-services-appset:16.0.0' ... }
  4. 앱이 Google Play 서비스 API 17.0.0 이상을 구현하지 않는 경우 앱/build.gradle 파일에 다음 종속성을 추가합니다:

    dependencies {
    ...
    implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0+'
    ...
    }

참고: Gradle 1.x-2.x 사용자는 종속성을 추가할 때 "구현" 대신 "컴파일"을 사용해야 합니다.

1.2. Gradle 없이 SDK 추가하기

수동으로 SDK 다운로드
  1. 페이지 상단의 링크에서 SDK를 다운로드합니다.
  2. SDK 패키지의 압축을 풀고 Singular.aar를 Android 프로젝트의 libs 디렉터리에 있는 libs 폴더에 추가합니다. 디렉터리가 없는 경우 프로젝트 폴더(보통 <프로젝트>/앱/라이브)에 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>12.0.2</version>
</dependency>
Eclipse를 사용하여 SDK 추가하기

Eclipse AAR 플러그인을 사용할 수 있습니다: gradle-eclipse-aar-plugin

플러그인을 사용하지 않으려면 다음 단계를 따르세요:

  1. singular_sdk-12.5.6.aar의 압축을 풉니다.
  2. classes.jar의 이름을 singular_sdk-12.5.6.jar로 바꿉니다(이것이 기본 SDK jar입니다).
  3. 원하는 방식으로 프로젝트에 'com.android.installreferrer:installreferrer:2.2' 라이브러리를 추가합니다.
  4. AAR에 포함된 AndroidManifest.xml의 BIND_GET_INSTALL_REFERRER_SERVICE 권한을 AndroidManifest.xml에 복사합니다.
  5. AAR에 포함된 AndroidManifest.xml의 CHECK_LICENSE 권한을 AndroidManifest.xml에 복사합니다.
Proguard를 사용하여 SDK 추가

proguard.config 파일에 다음 코드 줄을 추가합니다:

-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
# Google 청구 라이브러리를 사용하여 '수익' 함수를 호출하는 경우 이 줄의 주석 처리를 해제하세요.
#-keep public class com.android.billingclient.** { *; }

1.3. 필수 권한 추가

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" />
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />

참고: 앱 빌드가 Android 12/API 레벨 31 이상을 대상으로 하는 경우, Google 광고 ID에 액세스할 수 있는 권한을 추가하세요:

<uses-permission android:name="com.google.android.gms.permission.AD_ID" />
키즈 SDK를 연동하는 경우 이 권한을 추가하지 마세요.

삼성 갤럭시 스토어를 통해 앱을 배포하고 안드로이드 11 이상을 대상으로 하는 경우 삼성 갤럭시 스토어의 인스톨 리퍼러를 지원하기 위해 다음을 추가합니다:

<queries>
<package android:name="com.sec.android.app.samsungapps" />
</queries>
주의: 앱에 android.permission.GET_TASKS 권한이 있는 경우, 사용자가 앱을 실제로 열기 전에 앱이 초기화될 수 있습니다. 이로 인해 싱글 SDK가 초기화되어 설치 시간이 불일치할 수 있습니다. 이 문제를 방지하려면 필요하지 않은 경우 권한을 제거하거나 코드의 다른 곳으로 Singular SDK 초기화 호출을 이동하여 사용자가 앱을 처음 연 후에만 호출되도록 하세요.

2. 기본 SDK 연동 설정

참고: 싱글 SDK를 구현할 때는 GDPR, CCPA, COPPA 등 비즈니스를 운영하는 지역에서 제정된 다양한 개인정보 보호법을 준수해야 한다는 점을 잊지 마세요. 자세한 내용은 SDK 옵트인 및 옵트아웃 사례를 참조하세요.

2.1. Singular 라이브러리 가져오기

싱귤러 라이브러리를 가져오려면 MainActivity 파일에 다음 가져오기를 추가합니다:

Java(MainActivity.java) Kotlin(MainActivity.kt)
import com.singular.sdk.*;

2.2. 구성객체 생성

SDK를 초기화하기 전에 SingularConfig 개체를 만들어야 합니다. 이 객체에는 다음이 포함됩니다:

  1. SDK 키 및 SDK 시크릿(키, 시크릿 확인이 필요한 경우 Singular 계정에 로그인한 후 "개발자 도구 > SDK 통합 > SDK 키"로 이동하세요).
  2. 선택 사항으로, 설정하고자 하는 SDK 환경 설정도 포함됩니다.
  3. 메타 인스톨 리퍼러 어트리뷰션 지원

    '메타 인스톨 리퍼러' 어트리뷰션을 활성화하는 데 필요한 SDK 구성입니다:

    1. 싱귤러 구성 개체에서 페이스북 앱 ID를 입력합니다.
      // META 설치 리퍼러를 활성화하려면
      config.withFacebookAppId("여기에 Facebook 앱 ID를 입력하세요.");
    앱의 Facebook 앱 ID는 어디에서 찾을 수 있나요?

다음 코드 예제에서는 SingularConfig를 생성하고 Singular SDK를 초기화하기 전에 일반적인 구성 옵션을 설정합니다.

다음 섹션에서는 이러한 옵션과 사용자 지정 방법에 대해 자세히 설명합니다.

Java(MainActivity.java) Kotlin(MainActivity.kt)
@Override
protected void onCreate(Bundle savedInstanceState) {
    ...
// SingularConfig 생성 SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");

// 딥링크 핸들러 설정 config.withSingularLink( getIntent(), new SingularLinkHandler() { @Override public void onResolved(SingularLinkParams params) { String deeplink = params.getDeeplink(); String passthrough = params.getPassthrough(); boolean isDeferred = params.isDeferred(); // 여기에 딥링크 처리 코드 추가 } } );

Singular.init(context, config); ... }

 

SingularConfig 메서드 참조: 사용 가능한 모든 '.with' 옵션 보기

아래 표에는 앱에 옵션과 기능을 추가하는 데 사용할 수 있는 SingularConfig 객체에 사용할 수 있는 모든 '.with' 메서드가 나열되어 있습니다.

각 기능에 대한 자세한 내용은 아래 섹션 또는 고급 옵션에서 확인할 수 있습니다.

메서드

설명

.withFacebookAppId(String facebookAppID)

페이스북 앱 ID를 구성합니다. "메타 인스톨 리퍼러" 어트리뷰션에 필요합니다.

"앱의 페이스북 앱 ID는 어디에서 찾을 수 있나요?"를 참조하세요.

.withCustomUserId(String customId)

사용자 ID를 싱귤러로 전송합니다.

.withSingularLink(getIntent(), SingularLinkHandler handler)

싱귤러 링크와 딥링킹을 활성화합니다.

.withDDLTimeoutInSec (long timeout)

앱을 처음 열었을 때 싱귤러가 디퍼드 딥링크를 검색하는 시간을 설정합니다.

.withDDLHandler (DeferredDeepLinkHandler handler)

최신 싱글 링크 대신 레거시 추적 링크를 사용한 딥링킹을 활성화합니다.

.withOpenURI(URI openURI)

인텐트에서 URI를 가져옵니다(앱이 싱글 링크가 아닌 링크를 통해 열린 경우 딥링크를 처리하기 위해).

.withGlobalProperty(String key, String value, boolean overrideExisting)

글로벌 프로퍼티를 지정된 값으로 설정합니다. 키와 값은 앱에서 전송되는 모든 이벤트/세션과 함께 Singular로 전송됩니다.

.withSessionTimeoutInSec(long timeout)

세션 타임아웃을 설정합니다.

.withFCMDeviceToken(String token)

첫 번째 세션에서 전송할 FCM 토큰을 설정합니다.

.withLoggingEnabled()

로깅을 활성화합니다.

.withLogLevel(int level)

로깅 수준을 구성합니다(기본값은 Log.ERROR).

2.3. 딥링킹 지원 추가

딥링크는 앱 내부의 특정 콘텐츠로 연결되는 링크입니다. 사용자가 앱이 설치된 기기에서 딥링크를 클릭하면 앱이 열리고 특정 제품이나 경험이 표시됩니다. 단일 추적 링크에는 딥링킹뿐만 아니라 디퍼드 딥링킹도 포함될 수 있습니다. (자세한 내용은 딥링킹 FAQ 및 단일 링크 FAQ참조)

싱글 링크를 사용하여 딥링크 활성화

앱에 딥링크를 사용하려면 싱귤러 링크 전제 조건을 참조하세요.

딥링킹 인텐트 필터 추가

Activity에서 딥링크를 지원하도록 설정하려면 다음과 같은 인텐트 필터를 안드로이드 매니페스트.xml에 추가합니다. 딥링크를 통해 열어야 하는 Activity가 두 개 이상 있는 경우 각 Activity에 대해 이 작업을 수행합니다.

참고: 인텐트는'android:host' 값으로 구성해서는 안됩니다.'android:host' 값을 사용해야 하는 경우: 앱 구성표의 싱글 앱 페이지 구성에 호스트 값을 포함하고 모든 싱귤러 딥링크에 동일한'scheme://host' 값을 사용해야 합니다.

<activity> 
    <intent-filter>
        <data android:scheme="singular-example" />
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
    </intent-filter>
</activity>

딥링크 처리

싱귤러 SDK는 트래킹 링크를 통해 앱오픈시 세부 정보를 읽을 수 있는 핸들러 메커니즘을 제공합니다. 샘플 핸들러는 위의 구성객체 생성 샘플 코드에 포함되어 있습니다.

참고: 싱귤러 링크 핸들러는 앱이 싱귤러 링크를 통해 열린 경우에만 호출됩니다(싱귤러 링크 FAQ 참조). 다른 유형의 앱 링크는 싱귤러 구성 객체를 만들 때 도메인이 supportedDomains에 포함된 경우에만 트리거됩니다. 자세한 내용은 "비싱귤러 딥 링크 처리하기"를 참조하세요.

디퍼드 딥링크 타임아웃 수정하기

기본적으로 앱이 특정 기기에서 싱귤러로 첫 번째 세션을 보내면 싱귤러 서버는 레코드에서 해당 기기와 일치하는 디퍼드 딥링크가 있는지 확인합니다(디퍼드 딥링크란 무엇인가요? 참조). 디퍼드 딥링크가 확인되면 서버는 앱으로 딥링크 정보를 다시 전송하게 됩니다. 하지만 60초 이내에 매칭되는 디퍼드 딥링크를 찾지 못하면 서버는 검색을 중지합니다.

SingularConfig 객체를 생성할 때 withDDLTimeoutInSec을 호출하여 시간 제한 값을 수정할 수 있습니다. 아래 예제에서는 시간 제한을 30초로 변경합니다:

SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");
...
config.withDDLTimeoutInSec(30);
...
Singular.init(context, config);

비싱귤러 딥링크 처리하기

싱귤러 SDK는 싱귤러가 아닌 딥링크를 지원합니다. 이는 구글 애즈와 같은 파트너의 어트리뷰션을 측정하는 데 필요합니다.

안드로이드 SDK 버전 12.1.1부터 비싱귤러 유니버설 링크가 기본적으로 지원됩니다. 새 버전의 SDK를 사용하는 경우 타사 링크를 지원하기 위해 별도의 조치가 필요하지 않습니다.

2.4. Singular 초기화하기

싱귤러 SDK는 앱을 열 때마다 초기화해야 합니다. 이는 모든 싱귤러 어트리뷰션 기능의 전제 조건이며, 새 사용자 세션을 싱귤러로 전송합니다(세션은 사용자 리텐션을 계산하는 데 사용됨).

싱귤러를 초기화하려면 다음 코드를 사용합니다:

Singular.init(context, config);
파라미터 설명
Context context 애플리케이션 클래스에서 컨텍스트로 값 또는 getApplicationContext() 를 전달할 수 있습니다. 액티비티 내부에서 애플리케이션 컨텍스트를 가져오려면 currentActivity.getApplicationContext()를 호출합니다.
SingularConfig config 이전 단계에서 생성한 SingularConfig 객체입니다.

init 메서드는 앱의 모든 지점에서 호출할 수 있지만 이벤트가 보고되기 전에 호출되어야 합니다. Main Activity의 onCreate와 딥링크로 직접 열리게 될 모든 Activity에서 init을 호출하는 것이 좋습니다.

참고: 딥링크로 열리게 될 모든 Activity 내부에서 Singular를 초기화해야 합니다(딥링크 구현하기 참조). 따라서 애플리케이션의 onCreate에서 Singular를 초기화하지 않는 것이 좋습니다. Singular를 애플리케이션 수준에서 초기화한 다음 활동 내에서 다시 초기화하면 Singular 데이터베이스에서 세션이 중복됩니다.

2.5. 싱귤러에 사용자 ID 보내기(선택 사항)

싱귤러 SDK 방법을 사용하여 내부 사용자 ID를 싱귤러에 전송할 수 있습니다.

참고: 싱귤러의 크로스 디바이스 솔루션을 사용하는 경우, 모든 플랫폼에서 사용자 ID를 수집해야 합니다.

  • 사용자 ID는 모든 식별자가 될 수 있으며 PII(개인 식별 정보)를 노출해서는 안됩니다. 예를 들어 사용자의 이메일 주소, 사용자 이름 또는 전화번호를 사용해서는 안 됩니다. 싱귤러는 퍼스트 파티 데이터에만 고유한 해시값을 사용할 것을 권장합니다.
  • 또한 Singular에 전달되는 사용자 ID 값은 모든 플랫폼(웹/모바일/PC/콘솔/오프라인)에서 캡처한 내부 사용자 ID와 동일해야 합니다.
  • Singular는 사용자 수준 내보내기, ETL 및 내부 BI 포스트백(구성된 경우)에 사용자 ID를 포함합니다. 사용자 ID는 퍼스트 파티 데이터이며, Singular는 이를 다른 당사자와 공유하지 않습니다.
  • 싱귤러 SDK 메서드로 설정한 사용자 ID 값은 unsetCustomUserId 메서드를 사용하여 설정 해제하거나 앱을 제거할 때까지 지속됩니다. 앱을 닫거나 다시 시작해도 사용자 ID는 설정이 해제되지 않습니다.

사용자 ID를 설정하려면 setCustomUserId 메서드를 사용합니다. 설정을 해제하려면(예: 사용자가 계정에서 '로그아웃'하는 경우) unsetCustomUserId 를 호출하세요.

참고: 여러 사용자가 하나의 디바이스를 사용하는 경우 로그인 및 로그아웃할 때마다 사용자 ID를 설정하고 설정 해제하는 로그아웃 플로우를 구현하는 것이 좋습니다.

앱이 열릴 때 사용자 ID를 이미 알고 있는 경우 Singular SDK를 초기화하기 전에 setCustomUserId을  호출하세요. 이렇게 하면 싱귤러가 첫 번째 세션부터 사용자 ID를 가질 수 있습니다. 그러나 일반적으로 사용자가 등록하거나 로그인을 수행할 때까지 사용자 ID를 사용할 수 없습니다. 이 경우 등록 흐름이 완료된 후 setCustomUserId 을 호출하세요.

Singular.setCustomUserID 메서드
설명 사용자 ID를 Singular로 보냅니다.
서명 public void setCustomUserId(문자열 customUserId)
사용 예제
Singular.setCustomUserId("custom_user_id");
Singular.unsetCustomUserID 메서드
설명 Singular로 전송된 사용자 ID를 설정 해제합니다.
서명 public void unsetCustomUserId()
사용 예시
Singular.unsetCustomUserId();
선택 사항입니다: 커스텀 사용자 ID 장치 매핑

중요: 이 고급 엔터프라이즈 기능은 예외적인 경우에만 사용할 수 있습니다.이 기능을 구현하기 전에 싱귤러의 솔루션 엔지니어와 상담하세요.

싱귤러는 서버 간 연동을 통해 추가 모바일 이벤트 추적 데이터를 수신할 수 있습니다. 이 기능을 활용하려면 사용자 ID를 Singular의 모바일 디바이스 추적 식별자에 매핑해야 합니다.

참고: 이 메서드는 싱귤러 SDK를 초기화한 후 또는 사용자 ID를 확보한 후 바로 호출하세요.

Singular.setDeviceCustomUserId 메서드
설명 사용자 지정 사용자 ID를 로그인과 동일하게 설정하고 Singular의 추적 식별자에 매핑합니다.
서명 public void setDeviceCustomUserId(string customUserId)
사용 예시
Singular.setDeviceCustomUserId("custom_user_id");

2.6. Global Properties 구현하기(선택 사항)

싱귤러 SDK를 사용하면 앱에서 전송되는 모든 세션 및 이벤트와 함께 싱귤러 서버로 전송할 추가 사용자 지정 프로퍼티를 정의할 수 있습니다. 이러한 속성은 사용자, 앱 모드 또는 상태 등 원하는 모든 정보를 나타낼 수 있습니다. 이 속성을 설정하면 보고서 차원(Dimension)으로 사용할 수 있으며, 이를 사용하여 데이터를 세분화할 수 있습니다.

예를 들어, 게임 앱이 있는 경우 '레벨'이라는 속성을 정의하고 처음에는 '0'으로 설정할 수 있습니다. 앱에서 전송되는 모든 세션과 이벤트는 "Level": "0". 사용자가 레벨을 올리면 이 속성을 "1"로 재설정하는 등의 방식으로 재설정합니다. 그러면 세션, 이벤트 수, 수익 데이터를 포함한 보고서를 사용자 레벨별로 세분화하여 얻을 수 있습니다.

  • Global Properties는 최대 5개까지 정의할 수 있습니다.
  • 해당 프로퍼티는 설정 해제하거나 사용자가 앱을 제거할 때까지 앱 실행시 (사용자가 지정한 최신 값으로) 유지됩니다.
  • 각 프로퍼티 이름과 값은 최대 200자까지 입력할 수 있습니다. 더 긴 속성 이름이나 값을 전달하면 200자로 잘립니다.
  • Global Properties는 사용자 수준 내보내기(Export Logs)포스트백에서 액세스하고 사용할 수 있습니다. 향후 집계 리포팅 지원이 추가될 예정입니다. 궁금한 점이 있거나 글로벌 프로퍼티 지원 업데이트에 관심이 있는 경우 Singular 고객 성공 관리자에게 알려주세요!

SingularConfig를 통해 Global Properties 설정하기

SDK를 초기화하기 전에 withGlobalProperty 메서드를 사용하여 SingularConfig를 통해 글로벌 프로퍼티를 설정할 수 있습니다.

글로벌 프로퍼티와 해당 값은 앱 실행 간에 유지되므로 설정하려는 프로퍼티가 이미 다른 값으로 설정되어 있을 수 있다는 점에 유의하세요. 기존 프로퍼티를 새 값으로 재정의할지 여부를 SDK에 알려주려면 overrideExisting 파라미터를 사용하세요.

withGlobalProperty 메서드
설명 글로벌 프로퍼티를 설정합니다.
시그니처 withGlobalProperty(String key, String value, boolean overrideExisting)
사용 예제
// 두 개의 전역 프로퍼티를 설정하고 기존 값을 재정의합니다.
SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET")
  .withGlobalProperty(“MyProperty”, “MyValue”, true)
  .withGlobalProperty(“AnotherProperty”, “AnotherValue”, true);

초기화 후 Global Properties 설정

다음 메서드를 사용하여 앱 실행 중 언제든지 글로벌 프로퍼티를 설정, 설정 해제 및 검색할 수 있습니다.

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();

3. 이벤트 및 수익 추적

3.1. 이벤트 추적(비수익)

싱귤러는 인앱 이벤트에 대한 데이터를 수집하여 캠페인의 성과를 분석하고 KPI를 측정할 수 있습니다. 예를 들어, 게임 앱에서 사용자 로그인, 등록, 튜토리얼 완료 또는 레벨 업에 대한 데이터를 수집할 수있습니다.

표준 이벤트와 어트리뷰트란 무엇인가요?

싱귤러는 다양한 표준 이벤트를 지원합니다. 일반적으로 사용되는 이러한 이벤트는 보고 및 최적화를 위해 애드 네트워크에서 지원하는경우가 많습니다. 또 다른 장점은 표준 이벤트 이름을 사용하면 수동으로 정의할 필요 없이 자동으로 인식하여 이벤트 목록에 추가한다는 것입니다. 가능하면 표준 이벤트를 사용하는 것을 권장합니다.

싱귤러로 전송되는 이벤트 목록(함께 제공되는 속성 포함)은 UA/마케팅/비즈니스 팀에서 조직의 마케팅 KPI를 기반으로 작성해야 합니다. 비즈니스 팀은 인앱 이벤트 추적 방법 가이드를 따를 수 있습니다.

추적하는 각 이벤트마다 다양한 어트리뷰트를 전달할 수 있습니다. 이벤트별 권장 표준 어트리뷰트를 참조하세요.

이벤트 전송

코드에서 이벤트JSON 또는 이벤트 메서드를 사용하여 싱귤러에 이벤트를 전송합니다(가독성을 위해 이벤트JSON을 권장합니다).

  • 표준 이벤트명을 사용할 경우, 안드로이드 SDK: 표준 이벤트 및 속성 목록을 사용하세요(예: sngTutorialComplete). 아래 코드 예시를 참조하세요.
  • 사용자 지정 이벤트(Singular의 표준 이벤트 대신 고객사에서 지정하는 별도의 이벤트명)을 전송하는 경우 제한 사항을 참고하여 원하는 이벤트명을 사용하세요.
Singular.eventJSON 메서드
설명 JSONObject 형식의 추가 정보와 함께 사용자 이벤트를 Singular에 보고합니다.
시그니처

Singular.eventJSON(String name, JSONObject args)

참고: 'args'는 하나 이상의 키-값 쌍을 포함하는 JSONObject입니다. 키는 문자열이고 값은 JSONObject 값으로 허용되는 모든 유형이 될 수 있습니다.
사용 예시
Java(MainActivity.java) Kotlin(MainActivity.kt)
// 예 1: 권장 표준 속성과 함께 표준 이벤트 sng_tutorial_complete를 전송합니다.
JSONObject att = new JSONObject();
att.put(Attributes.sngAttrContent.toString(), <TUTORIAL NAME>);
att.put(Attributes.sngAttrContentId.toString(), <CONTENT ID>);
att.put(Attributes.sngAttrContentType.toString(), <TYPE OF CONTENT>);
att.put(Attributes.sngAttrSuccess.toString(), <LOGIN SUCCESS VALUE>);
Singular.eventJSON(Events.sngTutorialComplete.toString(), att);
// 예 2: 사용자 지정 속성을 사용하여 "bonus_points_earned"라는 이름의 사용자 지정 이벤트 보내기 JSONObject att = new JSONObject();
att.put("Points", 500); Singular.eventJSON("Bonus Points Earned", att);
Singular.event 메서드
설명 추가 정보를 포함하거나 포함하지 않고 사용자 이벤트를 Singular에 보고합니다.
시그니처

Singular.event(String eventName)
Singular.event(String eventName, Object... args)

참고: 'args'는 하나 이상의 키-값 쌍입니다(아래 예 참조). 키는 문자열이고 값은 JSONObject 값으로 허용되는 모든 유형(예: JSONObject, JSONArray, 문자열, 부울, 정수, 롱, 더블 또는 NULL)이 될 수 있습니다.

'args' 목록에는 짝수 개의 요소가 포함되어야 하며, 그렇지 않으면 Singular에 의해 이벤트가 거부됩니다.

사용 예시
Java(MainActivity.java) Kotlin(MainActivity.kt)
// 예 1: 권장 표준 속성과 함께 표준 이벤트 sng_tutorial_complete를 전송합니다.
Singular.event(Events.sngTutorialComplete.toString(),
  Attributes.sngAttrContent.toString(), <TUTORIAL NAME>,
  Attributes.sngAttrContentId.toString(), <CONTENT ID>,
  Attributes.sngAttrContentType.toString(), <TYPE OF CONTENT>,
  Attributes.sngAttrSuccess.toString(), <SUCCESS>
);

// 예 2: 속성 없이 표준 이벤트 "구독"(sng_subscribe)을 전송합니다.
Singular.event(Events.sngSubscribe.toString());

// 예 3: 사용자 지정 속성과 함께 "bonus_points_earned"라는 이름의 사용자 지정 이벤트를 보냅니다. Singular.event("Bonus Points Earned", "Points", 500);

참고:

  • 타사 파트너 및 분석 솔루션을 사용하려는 경우 타사 파트너 및 분석 솔루션과의 호환성을 보장하기 위해 이벤트 이름과 속성을 영어로 전달할 것을 적극 권장합니다.
  • 이벤트 이름은 32자로 제한됩니다. ASCII가 아닌 문자로 된 문자열은 UTF-8로 변환한 후 32바이트 미만이어야 합니다.
  • 속성 및 값은 500 ASCII 문자로 제한됩니다.

3.2. 수익 추적

싱귤러는 앱을 통해 얻은 수익에 대한 데이터를 수집하여 캠페인의 성과와 ROI를 분석하는 데 도움을 줄 수 있습니다.싱귤러는 보고서, 로그 내보내기 및 포스트백에서 데이터를 사용할수 있도록 합니다.

Purchase 오브젝트를 사용하여 수익 추적

싱귤러에 수익 이벤트를 보고할 때는 청구 라이브러리에서 받은 Purchase 객체를 전달하는 것이 좋습니다. 여기에는 두 가지 장점이 있습니다:

  1. 싱귤러는 거래의 모든 세부 정보를 가져와서 싱귤러 보고서를 더욱 풍부하게 만듭니다.
  2. 싱귤러는 구글로부터 거래 영수증(Purchase Receipt)을 받아 인앱 사기 방지와 관련하여 거래의 유효성을 검사하는 데 사용할 수 있습니다.

알림:

  • 2023년 8월 2일부터 모든 신규 앱은 청구 라이브러리 버전 5 이상을 사용해야 합니다. 2023년 11월 1일까지 기존 앱에 대한 모든 업데이트는 청구 라이브러리 버전 5 이상을 사용해야 합니다. 자세히 알아보세요.
  • 앱이 Android 14 이상을 대상으로 하는 경우 PBL 5.2.1 또는 PBL 6.0.1 이상으로 업데이트해야 합니다.

이벤트를 보고하려면 revenuecustomRevenue 메서드를 사용합니다. CustomRevenue를 사용하면 사용자 지정 이벤트 이름을 전달할 수 있으므로 다양한 유형의 수익 이벤트별로 분류된 단일 보고서에서 수익을 볼 수 있습니다.

참고: 다른 통화로 보고된 모든 수익은 Singular 계정에 설정된 대로 조직의 기본 통화로 자동 변환됩니다.

Singular.revenue 메서드
설명 선택적 추가 정보와 함께 수익 이벤트를 Singular로 보냅니다.
서명

Singular.revenue(String currency, double amount, Object purchase)

참고:

  • 객체를 전달할 때는 구매유형이어야 하며, 그렇지 않으면 영수증 정보가 Singular에 포함되지 않습니다.
  • 통화를 "USD", "EUR" 또는 "INR"과 같은 3글자 ISO 4217 통화 코드로 전달합니다.
사용 예시
// Google 청구 라이브러리에서 수신한 구매 개체 + Singular에 수익 이벤트를 보냅니다.
Singular.revenue("USD", 5.50, purchase);
Singular.customRevenue 메서드
설명 이벤트 이름 및 추가 정보(선택 사항)와 함께 수익 이벤트를 Singular로 보냅니다.
서명

Singular.customRevenue(String eventName, String currency, double amount, Object purchase)

참고:

  • 객체를 전달할 때는 구매유형이어야 하며, 그렇지 않으면 영수증 정보가 Singular에 포함되지 않습니다.
  • 통화를 "USD", "EUR" 또는 "INR"과 같은 세 글자 ISO 4217 통화 코드로 전달합니다.
사용 예
// 이벤트 이름과 구매 개체를 전달하여 Singular에 수익 이벤트를 보냅니다.
Singular.customRevenue("MyCustomRevenue", "USD", 
5.50, purchase);

Purchase 오브젝트 없이 수익 측정

위에서 설명한 방식으로 수익 이벤트를 보고하는 것이 가장 좋지만, 구매 개체를 전달하지 않고 수익customRevenue를 사용할 수도 있습니다. 대신 거래의 통화와 금액, 선택적 제품 세부 정보를 전달하면 됩니다.

이 방법으로 수익 이벤트를 보고할 때 Singular는 구매 영수증을 가져오지 않으며 거래의 유효성을 검사할 수 없다는 점에 유의하세요.

자세히 보기...
Singular.revenue 메서드(구매 개체 제외)

설명

선택적 추가 정보와 함께 수익 이벤트를 Singular에 보냅니다.

시그니처

Singular.revenue(String currency, double amount, String productSKU, String productName, String productCategory, int productQuantity, double productPrice)

Singular.revenue(String currency, double amount)

참고: 통화는 "USD", "EUR" 또는 "INR"과 같은 3글자 ISO 4217 통화 코드로 전달합니다.

사용 예시

// 제품 세부 정보가 포함된 수익 이벤트를 Singular로 보내기
Singular.revenue("EUR", 5.00, "SKU1928375", 
"Reservation Fee", "Fee" , 1, 5.00); // 제품 세부 정보 없이 싱귤러에 수익 이벤트 보내기 Singular.revenue("USD", 5.50);
Singular.customRevenue 메서드(구매 개체 제외)
설명 이벤트 이름 및 추가 정보(선택 사항)와 함께 수익 이벤트를 Singular로 보냅니다.
서명

Singular.customRevenue(String eventName, String currency, double amount, String productSKU, String productName, String productCategory, int productQuantity, double productPrice)
Singular.customRevenue(String currency, double amount)

참고: 통화는 "USD", "EUR" 또는 "INR"과 같은 3글자 ISO 4217 통화 코드로 전달합니다.

사용 예시
// 이벤트 이름과 제품 세부 정보가 포함된 수익 이벤트를 Singular로 보내기
Singular.customRevenue("MyCustomRevenue", "EUR", 5.00, 
"SKU1928375", "Reservation Fee", "Fee" , 1, 5.00); // 이벤트 이름과 함께 수익 이벤트를 Singular로 보내기 Singular.customRevenue("MyCustomRevenue", "USD", 5.50);

3.3. 하이브리드 이벤트 추적(고급)

싱귤러는 앱에 연동된 싱귤러 SDK를 통해 모든 이벤트와 구매을 전송할 것을 권장합니다. 그러나 Singular는 다른 소스에서 이벤트와 구매을 수집할 수 있습니다.

싱귤러 SDK에서 전송되지 않은 모든 이벤트는 싱귤러의 서버 간 이벤트 문서 요구사항을 준수해야 하며, 이벤트의 정확한 어트리뷰션을 위해 일치하는 기기 식별자를 제공해야 합니다.

중요:

서버 간 이벤트 요청에 사용된 디바이스 식별자가 Singular에서 일치하는 디바이스 식별자가 없는 경우 불일치가 발생할 수 있습니다. 다음과 같은 가능성에 유의하세요:

  • 이벤트 요청이 앱 세션에서 싱귤러 SDK가 디바이스 식별자를 기록하기 '전에' 수신된 경우, 이벤트 요청은 알 수 없는 디바이스에 대한 '첫 번째 세션'으로 간주되며, 싱귤러는 해당 디바이스를 오가닉 어트리뷰션으로 어트리뷰션합니다.
  • 싱귤러 SDK가 디바이스 식별자를 기록했지만, 싱귤러 SDK 식별자가 서버 간 이벤트 요청에 지정된 디바이스 식별자와 다른 경우, 이벤트는 잘못 어트리뷰션됩니다.

하이브리드 이벤트 추적 가이드

내부 서버에서 이벤트 보내기

싱귤러는 서버에서 수익에 대한 데이터를 수집하여 캠페인의 성과와 ROI를 분석하는 데 도움을 줄 수 있습니다.

요구사항:

  • 인앱 등록 또는 로그인 이벤트에서 디바이스 식별자를 캡처하여 전달하고 이 데이터를 서버의 사용자 ID와 함께 저장하세요. 디바이스 식별자는 사용자에 따라 변경될 수 있으므로 사용자가 앱 세션을 생성할 때 식별자를 업데이트해야 합니다. 이렇게 하면 서버 측 이벤트가 올바른 디바이스에 어트리뷰션되도록 보장할 수 있습니다.
  • 서버 측 이벤트는 플랫폼별로 다르므로 디바이스 플랫폼과 일치하는 디바이스 식별자(예: iOS 디바이스의 경우 IDFA 또는 IDFV)로만 전송해야 합니다.
  • 싱귤러 내부 BI 포스트백 메커니즘을 사용하여 이벤트를 내부 엔드포인트로 실시간으로 푸시하여 서버 측의 데이터 집합을 업데이트할 수 있습니다. 내부 BI 포스트백 FAQ를 참조하세요.
  • 자세한 내용은 서버 간 통합 가이드의 "수익 추적" 섹션을 검토하세요.
수익 제공업체에서 이벤트 보내기
RevenueCat 또는 adapty와 같은 타사 제공업체는 구매 및 구독 수익을Singular에 제공할 수 있습니다.

이러한 파트너를 활성화하는 방법에 대한 자세한 내용은 아래 링크를 참조하세요.

세그먼트에서 이벤트 보내기

세그먼트에서 싱귤러 SDK와 병행하여 싱귤러에 이벤트를 보내려면 세그먼트에 "클라우드 모드" 대상을 추가해야 합니다. 상세한 가이드내용은 여기에서 확인하세요.

4. 고급 옵션

4.1. 짧은 리퍼러 링크 생성

참고: 이 기능은 SDK 버전 12.1.1 이상에서 사용할 수 있습니다. 짧은 링크는 일단 생성되면 30일 동안 활성 상태로 유지됩니다.

짧은 링크를 사용하면 매개변수로 가득 찬 긴 단일 링크를 공유하기에 편리한 더 짧고 안전한 링크로 변환할수 있습니다.

일반적으로 앱 사용자가 친구와 공유하여 앱을 사용하도록 초대할 수 있도록 짧은 링크를 동적으로 생성하는 것이 좋습니다.

짧은 링크를 만들려면 다음이 필요합니다:

  • 앱 다운로드로 연결되는 싱귤러 링크 ( 싱귤러 링크 FAQ 참조).
  • 링크에 동적으로 추가하려는 모든 파라미터 (옵션 목록은 트래킹 링크 파라미터 목록 참조).
  • 링크를 공유한 사용자의 새 앱 설치를 추적할 수 있도록 하려면 추천 사용자의 이름과 ID를 입력합니다.

아래 예제에서와 같이 짧은 링크를 생성하려면 createReferrerShortLink 메서드를 사용합니다.

Java(MainActivity.java) Kotlin(MainActivity.kt)
// JSON 객체를 생성하여 단수 링크에 매개변수를 추가합니다(링크 URL에 매개변수가 아직 없는 경우).
JSONObject params = new JSONObject();       
try {
      params.put("channel","sms");
      params.put("another parameter","parameter value");
} catch (JSONException e) {
      e.printStackTrace();
}

Singular.createReferrerShortLink (
  "https://sample.sng.link/D52wc/cuvk?pcn=test", // 원본 싱귤러 링크 URL
  "Referrer Name",
  "Referrer ID",
  params,
  new ShortLinkHandler() { 
    @Override
      public void onSuccess(final String shortLinkURL) {
        view.post(new Runnable() {
          @Override
          public void run() {
            // 여기에 공유 로직을 추가하세요.
          }   
        });
      }

@Override public void onError(final String error) { view.post(new Runnable() { @Override public void run() { // 오류의 원인에 따라 함수에 전달된 파라미터를 다시 시도/중단/수정하는 로직입니다. } }); } });

4.2. 광고 수익 어트리뷰션 지원 추가

참고: 버전 11.0.0부터 싱귤러는 싱귤러 SDK를 통해 광고 수익 어트리뷰션을 설정할 수 있는 옵션을 추가했습니다. 기존 방식(API 호출 사용)으로 광고 수익 어트리뷰션을 설정할 수 있는 옵션이 여전히 제공되며, 이 경우 앱에서 싱귤러 SDK를 업데이트할 필요가 없습니다.

싱귤러 SDK에서 광고 수익 어트리뷰션 지원을 추가하려면 다음과 같이 하세요:

  1. 싱귤러 SDK를 최신 버전으로 업데이트합니다.
  2. 광고 수익 데이터에 사용하는 미디에이션 플랫폼에 따라 적절한 코드 스니펫을 싱귤러 SDK 통합에 추가합니다.

참고: 통화를 3글자 ISO 4217 통화 코드(예: 'USD', 'EUR', 'INR')로 전달하세요.

AdMob
  1. 참고: 이 기능은 애드몹 계정에서 활성화해야 합니다.

    참조 https://support.google.com/admob/answer/11322405#getstarted

KotlinJava
var mRewardedAd: RewardedAd? = null

override fun onAdLoaded(rewardedAd: RewardedAd) {
   mRewardedAd = rewardedAd
   mRewardedAd?.setOnPaidEventListener(object : OnPaidEventListener {
      override fun onPaidEvent(adValue: AdValue) {
         val impressionData: AdValue = adValue
         val data = SingularAdData(
            "AdMob",
            impressionData.currencyCode,
            impressionData.valueMicros / 1000000.0)
         Singular.adRevenue(data)
      }
  })
}
AppLovinMax
  1. AppLovin MAX의 이벤트인 onMessageReceived에서수신된 객체를 검색합니다.
KotlinJava
val message: AppLovinCommunicatorMessage? = null 
val adData: Bundle? = message?.messageData

adData?.let { bundle -
    val data = SingularAdData(
        "AppLovin",
        "USD",
        bundle.getDouble("revenue", 0.0)
    )
    Singular.adRevenue(data)
}
IronSource
  1. IronSource의 이벤트 OnImpressionSuccess에서수신한 객체를 검색합니다.
  2. IronSource에서 ARM SDK 포스트백 플래그가 켜져 있는지 확인합니다.
  3. 참조https://developers.is.com/ironsource-mobile/general/ad-revenue-measurement-postbacks/#step-1
KotlinJava
val impressionData: ImpressionData? = null

impressionData?.let { data -
    val singularAdData = SingularAdData(
        "IronSource",
        "USD",
        data.revenue)
    Singular.adRevenue(singularAdData)
}
TradPlus
  1. 인상 델리게이트설정
  2. 트레이드플러스 광고 노출 콜백에 단수 추가하기
KotlinJava
TradPlusSdk.setGlobalImpressionListener(
object : GlobalImpressionManager.GlobalImpressionListener { override fun onImpressionSuccess(tpAdInfo: TPAdInfo?) { if (tpAdInfo == null) return val revenue = tpAdInfo.ecpm.toDouble() / 1000 val data = SingularAdData(
"TradPlus",
"USD",
revenue) Singular.adRevenue(data) } })
기타(일반)
  1. 관련 데이터로 SingularAdData 개체를 초기화합니다.
  2. 데이터를 Singular에 보고
KotlinJava
val data = SingularAdData(
"YOUR_AD_PLATFORM",
"커런시 코드",
9.90)
Singular.adRevenue(data)

4.3. 언인스톨 트래킹

Android 앱에 대해 언인스톨 트래킹을 사용 설정하려면 먼저 언인스톨 트래킹 설정에 설명된 대로 싱귤러 플랫폼 설정을 추가한 다음 아래 지침을 따르세요.

참고: Google은 2018년 4월 이후 GCM API를 더 이상 지원하지 않습니다. 아래 설명과 같이 언인스톨 트래킹을 위해 Firebase 클라우드 메시징(FCM)을 사용하세요.

I. FCM과 통합하기:

언인스톨 트래킹을 사용하려면 Firebase 클라우드 메시징(FCM) 플랫폼의 서비스를 연동해야 합니다. 아직 FCM을 사용하고 있지 않다면 Android에서 Firebase 클라우드 메시징 클라이언트 앱을 설정하는 방법에 대한 Google의 지침을 따르세요.

FCM 요구 사항 ( 출처 )

FCM 클라이언트를 사용하려면 Android 4.1 이상을 실행하는 기기에 Google Play 스토어 앱이 설치되어 있거나 Google API를 사용하여 Android 4.1을 실행하는 에뮬레이터가 필요합니다. Google Play 스토어를 통해서만 Android 앱을 배포할 수 있는 것은 아닙니다.

사용자기기가 해당 Android 버전에서 실행되지 않는 경우 싱귤러 언인스톨 트래킹을 사용할 수 없습니다.

II. 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>

III. FCM Device Token을 등록하고 전송합니다:

마지막으로, 다음과 같이 OnCreate()에서 SingularConfig가 초기화된 후 FCM Device Token을 설정합니다:

Singular.setFCMDeviceToken(String fcmDeviceToken);

4.4. 구형 기기에서 인스톨 리퍼러 수집하기

참고: Google은 install_referrer 인텐트 브로드캐스트를 더 이상 사용하지 않습니다. 참조: 아직도 인스톨브로드캐스트를 사용하시나요? 2020년 3월 1일까지 플레이 리퍼러 API로 전환하기

인스톨 리퍼러는 싱귤러가 사기 시도를 감지하고 분석하는 데 도움을 줄 뿐만 아니라 어트리뷰션을 결정하는 가장 정확한 도구로 사용자가 앱을 설치하기 전에 클릭한 광고를 가리키는 구글 플레이 스토어에서 제공하는 식별자입니다.

최신 버전의 구글 플레이 스토어가 설치된 기기에서는 싱귤러 SDK가 자동으로 인스톨 리퍼러 값을 수집합니다(싱귤러는 최신 구글 플레이 리퍼러 API와 통합되어 있기 때문입니다).

구형 기기에서 인스톨 리퍼러를 수집하려면 다음과 같이 하세요:

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

앱에 이미 안드로이드에서 INSTALL_REFERRER를 수신하는 브로드캐스트 리시버가 있을 가능성이 높습니다.

그렇다면 브로드캐스트 리시버의 onReceive 메서드에 다음 줄을 추가하면 됩니다:

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

예를 들어 기존 리시버의 이름이 MyCustomInstallReceiver인 경우 다음과 같이 표시되어야 합니다:

public class MyCustomInstallReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        // 설치 리퍼러 정보를 싱귤러에 전달합니다.
        new SingularInstallReceiver().onReceive(context, intent);
        // ...
    }
}

다른 설치 리퍼러 리시버가 없는 경우:

앱에 인스톨 리퍼러 리시버가 없는 경우, 매니페스트 파일의 <application> 태그에 다음을 추가하여 Singular SDK가 유일한 리시버를 등록하도록 할 수 있습니다:

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

4.5. 세션 관리

안드로이드 API 14(아이스크림 샌드위치) 이상의 경우, 싱귤러 SDK는 세션 관리를 자동으로 처리할 수 있습니다. 앱의 최소 버전이 14 이상인 경우 세션 관리를 위한 추가 구성이 필요하지 않습니다.

세션 타임아웃 변경

기본적으로 앱이 백그라운드에서 60초 이상 실행된 후 포그라운드로 돌아오면 SDK는 새 세션을 등록합니다.

시간 제한 값을 변경하려면 SDK를 초기화하기 전에 SingularConfig에서 withSessionTimeoutInSec(<초 단위의 시간 제한>)을 사용합니다.

예를 들어

// 세션 시간 제한을 120초로 설정
SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET")
.withSessionTimeoutInSec(120); 

수동 세션 관리

앱의 최소 버전이 14 미만인 경우, 각 활동에서 Singular SDK의 두 가지 세션 처리 메서드인 onActivityPausedonActivityResumed를 호출하여 세션을 수동으로 관리해야 합니다.

참고: 다른 모든 활동이 파생되는 사용자 지정 공통 main activity 클래스가 있는 경우, Activity의 'onResume 및 onPause 메서드'에서 onActivityResumed 및 onActivityPaused를 호출할 수 있습니다.

Singular.onActivityResumed 메서드
설명 Activity의 onResume 메서드 내에서 이 메서드를 호출하여 싱귤러 세션을 관리합니다.
서명 public static void onActivityResumed()
사용 예시
@Override
protected void onResume() {
    super.onResume();
    Singular.onActivityResumed();
    .... //기타 코드가 있는 경우
}
Singular.onActivityPaused 메서드
설명 액티비티의 onPause 메서드 내에서 이 메서드를 호출하여 싱귤러 세션을 관리합니다.
서명 public static void onActivityPaused()
사용 예시
@Override
protected void onPause() {
    super.onPause();
    Singular.onActivityPaused();
    .... //기타 코드가 있는 경우
}

4.6. 자바스크립트 인터페이스 사용

싱귤러는 앱의 자바스크립트 코드 내에서 싱귤러 네이티브SDK를 호출하는 데 사용할 수 있는 자바스크립트 인터페이스를 제공합니다.

예를 들어, 자바스크립트 인터페이스를 설정하면 다음과 같이 자바스크립트 코드에서 싱귤러로 이벤트를 보낼 수 있습니다:

이벤트 예시

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

이 인터페이스는 다음 SDK 메서드를 지원합니다:

  • setCustomUserID
  • unsetCustomUserID
  • event
  • revenue

자바스크립트 인터페이스를 활성화하려면 기본 활동에 다음 코드 줄을 추가하세요. 여기서 '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("SDK KEY", "SDK SECRET");
    Singular.init(this, config);
    SingularJSInterface singularJSInterfaceInstance = 
        new SingularJSInterface(this);
    singularJSInterfaceInstance.setWebViewId(R.id.webview);
    myWebView.addjavascriptInterface(singularJSInterfaceInstance,
        "SingularInterface");
}

4.7. OAID(오픈 광고 ID) 수집하기

구글 플레이를 사용하지 않는 국가의 경우, 안드로이드 기기에는 구글 광고 ID(GAID, 단수형 AIFA라고도 함)가 없습니다. 대신 기기에서 발생하는 세션과 이벤트를 추적하는 데 사용할 수 있는 OAID(개방형 광고 식별자)라는 식별자를 제공할 수 있습니다.

OAID는 현재 화웨이와 모바일 보안 연합(MSA)에 소속된 브랜드에서 제공하는 디바이스에서 제공됩니다.

앱에서 OAID를 수집하려면 먼저 MSA SDK와 Huawei OAID SDK를 통합해야 합니다. 두 SDK를 모두 통합해야 OAID를 제공하는 모든 플랫폼에서 수집할 수 있습니다.

그런 다음 싱귤러 SDK가 추적에 OAID를 사용하도록 하려면 싱귤러를 초기화하기 전에 구성 개체에서 withOAIDCollection에 대한 호출을 추가하세요.

SingularConfig config = new SingularConfig("SDK KEY","SDK SECRET")
    .withOAIDCollection();
Singular.init(context, config);

그러면 싱귤러 SDK가 디바이스에 OAID가 있는지 여부와 식별자를 수집하는 데 사용해야 하는 OAID SDK를 자동으로 감지합니다.

4.8. IMEI 번호 수집

앱이 구글 플레이를 사용하지 않는 국가에서 제공되는 경우, 기기에는 구글 광고 ID가 없습니다. 이 경우 대신 기기 IMEI(국제 모바일 기기 식별 번호)를 수집할 수 있습니다.

참고: 구글 플레이 서비스를 사용하는 경우, 구글 플레이 서비스 계약을 위반하는 것이므로 IMEI 번호를 수집해서는 안 됩니다.

IMEI 번호를 수집하려면 다음과 같이 하세요:

앱의 AndroidManifest.xml 파일에 android.permission.READ_PHONE_STATE 권한을 추가합니다:

<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 SDK를 초기화하기 전에 withIMEI를 사용하여 SingularConfig에서 IMEI 번호를 설정합니다. 이렇게 하면 첫 번째 세션부터 Singular에서 IMEI 번호를 사용할 수 있습니다.

SingularConfig config = new SingularConfig("SDK KEY","SDK SECRET")
.withIMEI("537769845792516"); Singular.init(context, config);

SDK 초기화 후 코드의 어느 지점에서든 IMEI 번호를 설정하려면 setIMEI를 호출하세요.

Singular.setIMEI 메서드
설명 디바이스의 IMEI 번호를 Singular로 전송합니다.
서명 public void setIMEI(string IMEIString)
사용 예제
Singular.setIMEI(IMEIString);

4.9. 데이터 개인정보 보호법 준수

Singular는 개인정보 보호 기능을 제공하여 GDPR 및 CCPA(캘리포니아 소비자 개인정보 보호법)와 같은 소비자 개인정보 보호법을 준수하는 파트너와 협력할 수 있도록 지원합니다. 이러한 파트너는 최종 사용자가 개인 정보 공유에 동의했는지 여부를 통보받기를 원합니다.

사용자에게 정보 공유에 대한 동의를 요청하는 방법을 구현한 경우, limitDataSharing 메서드를 사용하여 사용자의 선택 사항을 Singular에 알려주세요:

사용자가 정보 공유에 동의(옵트인)했음을 표시하려면 Singular.limitDataSharing(false )를 사용합니다.

사용자가 동의하지 않은 경우 Singular.limitDataSharing(true )를 사용합니다.

싱귤러는'사용자 개인정보 포스트백'에서 제한데이터공유를 사용할 뿐만 아니라 관련 규정을 준수하기 위해 이 정보를 필요로 하는 파트너에게 전달합니다. 자세한 내용은"사용자 개인정보 및 데이터 공유 제한"을 참조하세요.

참고: 이 방법의 사용은 선택 사항이지만, 사용자가 옵트인했음을 구체적으로 고지한 경우에만 파트너가 싱귤러와 공유하는 어트리뷰션 정보가 있을 수 있습니다.

Singular.limitDataSharing 메서드
서명 Singular.limitDataSharing(booleanshouldLimitDataSharing)
설명 개인 데이터 공유에 대한 사용자 동의(옵트인)를 Singular에 알립니다.
사용 예시
// 사용자가 데이터 공유에 동의했습니다.
Singular.limitDataSharing(false);

GDPR 준수를 위한 추가 방법

싱귤러 SDK는 GDPR 정책을 준수하고 추적에 대한 사용자 동의 또는 비동의를 싱귤러에 알리는 데 도움이 되는 몇 가지 메서드를 제공합니다.

Singular.trackingOptIn 메서드
설명 추적에 대한 사용자 동의(옵트인)를 Singular에 알립니다.
사용 예시
Singular.trackingOptIn();
Singular.stopAllTracking 메서드
설명

이 앱에서 이 사용자에 대한 모든 추적 활동을 중지합니다.

참고: 이 메서드를 호출하면 앱이 재시작된 후에도 SDK가 효과적으로 비활성화됩니다(상태는 지속됨). 추적을 다시 활성화하는 유일한 방법은 resumeAllTracking()을 호출하는 것입니다.
사용 예시
Singular.stopAllTracking();
Singular.resumeAllTracking 메서드
설명 이 앱에서 이 사용자에 대한 추적을 재개합니다.
사용 예시
Singular.resumeAllTracking();
Singular.isAllTrackingStopped 메서드
설명 이 앱에서 이 사용자의 추적 상태를 확인합니다. StopAllTracking()을 사용하여 추적을 중지하고 다시 시작하지 않은 경우 true를 반환합니다.
사용 예시
Singular.isAllTrackingStopped();