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

Singular SDK 연동하기의 단계를 따르세요 :계획 및 사전 요구 사항의 단계를 따르세요.

이 단계는 모든 Singular SDK 연동을 위한 전제 조건입니다.

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

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

1. settings.gradle 파일에 Singular SDK 리포지토리를 추가합니다:

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

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

   repositories {
           mavenCentral()
           maven { url 'https://maven.singular.net/' }
       }

2. app/build.gradle의 종속성 목록에 Singular 라이브러리를 추가합니다:

   dependencies {
       ...
       implementation 'com.google.android.gms:play-services:6.5.87'
       implementation 'com.singular.sdk:singular_sdk:12.7.0'
       ...
   }

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

   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+'
        ...
   }

1.2. Gradle 없이 SDK 추가하기

<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.7.0</version>
</dependency>

-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
# Uncomment this line in case your are calling the 'revenue' function using the Google billing library
#-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" />

<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

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

<queries>
   <package android:name="com.sec.android.app.samsungapps" />
</queries>

2. 기본 SDK 연동 설정

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

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

import com.singular.sdk.*;

import com.singular.sdk.*

2.2. 구성 개체 만들기

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

1. SDK 키 및 SDK 시크릿 (검색하려면 Singular 계정에 로그인하고 개발자 도구 > SDK 연동 > SDK 키로 이동하세요).
2. 선택 사항으로 SDK 환경설정을 설정할 수 있습니다.
3. 메타 인스톨 리퍼러 어트리뷰션 지원

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

   1. Singular 구성 개체에서 Facebook 앱 ID를 입력합니다.
      

      // To enable META Install Referrer
      
      config.withFacebookAppId("INSERT YOUR FACEBOOK APP ID HERE");

   앱의 Facebook 앱 ID는 어디에서 찾을 수 있나요?

다음 코드 예제는 구성 개체를 생성하고 Singular SDK를 초기화하기 전에 공통 구성 옵션을 설정합니다.

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

@Override
protected void onCreate(Bundle savedInstanceState) {
    ...
    // Create a configuration object

    SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");

    // Set up a deep links handler

    config.withSingularLink(
        getIntent(), 
        new SingularLinkHandler() {
            @Override
            public void onResolved(SingularLinkParams params) {
                String deeplink = params.getDeeplink();
                String passthrough = params.getPassthrough();
                boolean isDeferred = params.isDeferred();

                // Add deep link handling code here

            }
        }
    );

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

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // Create a configuration object

    val config = SingularConfig("SDK KEY", "SDK SECRET")

    // Set up a deep links handler

    config.withSingularLink(
        intent
    ) { params ->
        val deeplink = params.deeplink
        val passthrough = params.passthrough
        val isDeferred = params.isDeferred

        // Add deep link handling code here

    }

    Singular.init(this, config)
    ...
}

2.3. 딥링킹 지원 추가하기

딥링크는 사용자를 앱 내의 특정 콘텐츠로 안내하는 URL입니다. 사용자가 앱이 이미 설치된 기기에서 딥링크를 탭하면 앱이 의도한 제품 페이지 또는 경험으로 바로 열립니다. Singular 추적 링크는 딥링킹과 디퍼드 딥링킹을 모두 지원합니다. 자세한 내용은 딥링킹 FAQ 및 Singular 링크 FAQ를 참조하세요.

요구 사항

1. 앱에 딥링크를 사용하려면 Singular 링크 사전 요구 사항을 완료해야 합니다.

2. Singular 링크 핸들러 구현

   Singular 링크 핸들러는 Singular 추적 링크에서 딥링크(_dl), 디퍼드 딥링크(_ddl), 패스스루(_p ) 파라미터를 검색하는 콜백 메커니즘을 제공합니다. 이러한 매개변수는 앱이 열릴 때(이미 설치된 경우) 또는 앱이 설치된 후에 전달됩니다.

   ---

   Singular 컨피규레이션 개체 업데이트

   들어오는 딥링크 및 디퍼드 딥링크 데이터를 처리하기 위해 SDK 초기화 중에 SingularLinkHandler 콜백을 SingularConfig 객체에 추가합니다.

   테스트 목적으로 로그가 인라인으로 추가됩니다.

   JavaKotlin

   // Call SingularLinkHandler
   
   config.withSingularLink(getIntent(), new SingularLinkHandler() {
           @Override
           public void onResolved(SingularLinkParams params) {
               Log.d("Singular", "SingularLinkHandler");
               String deeplink = params.getDeeplink();
               String passthrough = params.getPassthrough();
               boolean isDeferred = params.isDeferred();
   
               // Add deep link handling code here
   
               Log.d("SingularLink", "Deeplink: " + deeplink);
               Log.d("SingularLink", "Passthrough: " + passthrough);
               Log.d("SingularLink", "Is Deferred: " + isDeferred);
           }
       }
   );

   // Call SingularLinkHandler
   
   config.withSingularLink(intent) { singularLinkParams ->
      Log.d("Singular", "SingularLinkHandler")
      val deeplink = singularLinkParams.deeplink
      val passthrough = singularLinkParams.passthrough
      val isDeferred = singularLinkParams.isDeferred
   
      // Add deep link handling code here
   
      Log.d("Singular", "Deeplink: $deeplink")
      Log.d("Singular", "Passthrough: $passthrough")
      Log.d("Singular", "isDeferred: $isDeferred")
   }

   참고: Singular링크 핸들러는 앱이 Singular 링크를 통해 열릴 때만 트리거됩니다. 자세한 내용은 (싱귤래러 링크 FAQ를 참조하세요)를 참조하세요.

   Singular링크 핸들러 동작에 대한 참고 사항:

   #

   Singular링크 핸들러 동작에 대한 참고 사항:

   • 새로 설치할 경우 앱이 실행될 때 열기 URL이 없습니다. 따라서 Singular는 마지막 터치(클릭)에 대한 어트리뷰션을 완료하고 추적 링크에 딥링크 또는 디퍼드 딥링크(DDL) 값이 포함되어 있는지 확인해야 합니다. 이 프로세스는 Singular SDK가 첫 번째 세션을 Singular 서버로 전송할 때 발생합니다. 해당되는 경우 딥링크 값은 deeplink 매개변수의 SDK의 SingularLinkHandler에 반환됩니다.

     이 시나리오를 테스트하려면 다음과 같이 하세요:

     1. 기기에서 앱을 제거합니다(현재 설치되어 있는 경우).
     2. Google 광고 ID(GAID)를 재설정합니다.
     3. 기기에서 DDL이 구성된 Singular 추적 링크를 클릭합니다.
     4. 앱을 설치하고 엽니다.

     어트리뷰션이 성공적으로 완료되고 DDL 값이 앱에 전달됩니다.

   • 추적 링크에 패스스루(_p ) 파라미터가 포함된 경우, Singular링크핸들러의 패스스루 파라미터에 해당 데이터가 포함됩니다. 이는 앱 클릭에서 추가 데이터를 캡처하는 데 유용합니다.
   • 앱이 이미 설치되어 있는 경우 Singular 링크를 클릭하면 앱이 열립니다. Singular는 이를 위해 안드로이드 앱 링크 기술을 사용합니다. 안드로이드 OS는 전체 Singular 추적 링크가 포함된 오픈 URL을 제공합니다. SDK 초기화 중에 Singular SDK는 안드로이드 인텐트를 파싱하고 딥링크 및 패스스루 값을 추출한 후 SingularLinkHandler를 통해 이를 반환합니다.

고급 옵션

config.withDDLTimeoutInSec(30);

.withDDLTimeoutInSec(30)

2.4. Singular 초기화하기

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

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

Singular.init(context, config);

Singular.init(context, config)

init 메서드는 앱의 어느 지점에서나 호출할 수 있지만 이벤트가 보고되기 전에 호출해야 합니다. 메인 활동의 onCreate 메서드뿐만 아니라 딥링크를 통해 직접 열리는 모든 활동에서 init 메서드를 호출하는 것이 좋습니다.

2.5. Singular에 사용자 ID 보내기(선택 사항)

Singular SDK 메소드를 사용하여 내부 사용자 ID를 Singular로 보낼 수 있습니다.

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

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

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

Singular.setCustomUserId("custom_user_id");

Singular.unsetCustomUserId();

Singular.setDeviceCustomUserId("custom_user_id");

2.6. 글로벌 속성 구현하기(선택 사항)

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

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

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

SingularConfig를 통해 글로벌 속성 설정하기

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

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

// Set two global properties and override any existing values

SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET")
  .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();

3. 이벤트 및 구매 추적

3.1. 이벤트 추적 (비구매)

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

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

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

Singular로 전송되는 이벤트 목록(첨부된 속성 포함)은 UA/마케팅/비즈니스 팀에서 조직의 마케팅 KPI에 따라 작성해야 합니다. 비즈니스 팀은 인앱 이벤트 추적 방법의 가이드를 따를 수 있습니다: Singular 어트리뷰션 고객을 위한 가이드.

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

이벤트 전송

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

• 표준 이벤트의 경우 이벤트의 Android 이름을 Android SDK의 표준 이벤트 및 속성 목록에 표시된 대로 사용합니다(예: sngTutorialComplete). 아래 코드 예시를 참조하세요.
• 사용자 지정 이벤트(조직에서 측정하려는 이벤트 중 Singular의 표준 이벤트와 일치하지 않는 이벤트)를 전송하는 경우 제한 사항을 준수하는 원하는 문자열을 사용하세요.

// Example 1:

// Send the standard event sng_tutorial_complete with the

// recommended standard attributes


JSONObject att = new JSONObject();
try {
    att.put(Attributes.sngAttrContent.toString(), "Telugu");
    att.put(Attributes.sngAttrContentId.toString(), 32);
    att.put(Attributes.sngAttrContentType.toString(), "video");
    att.put(Attributes.sngAttrSuccess.toString(), 92);
} catch (JSONException e) {
    e.printStackTrace(); // Or log the exception


}
Singular.eventJSON(Events.sngTutorialComplete.toString(), att);

// Example 2:

// Send a custom event named "bonus_points_earned" with custom attributes

JSONObject att = new JSONObject();
try {
    att.put("Points", 500);
    att.put("score", 650);
} catch (JSONException e) {
    e.printStackTrace(); // Or log the exception


}
Singular.eventJSON("Bonus Points Earned", att);

// Example 1:

// Send the standard event sng_tutorial_complete with the

// recommended standard attributes


val att = JSONObject().apply {
    put(Attributes.sngAttrContent.toString(), "Telugu")
    put(Attributes.sngAttrContentId.toString(), 32)
    put(Attributes.sngAttrContentType.toString(), "video")
    put(Attributes.sngAttrSuccess.toString(), 75)
}
Singular.eventJSON(Events.sngTutorialComplete.toString(), att)

// Example 2:

// Send a custom event named "bonus_points_earned" with custom attributes

val att = JSONObject().apply {
    put("Points", 500)
    put("score",650)
}
Singular.eventJSON("Bonus Points Earned", att)

// Example 1:

// Send the standard event "Subscribe" (sng_subscribe) without any attributes

Singular.event(Events.sngSubscribe.toString());

// Example 2:

// Send the standard event "sng_tutorial_complete" with the 

//recommended standard attributes
Singular.event(Events.sngTutorialComplete.toString(),
    Attributes.sngAttrContent.toString(), "Spanish",
    Attributes.sngAttrContentId.toString(), 52,
    Attributes.sngAttrContentType.toString(), "video",
    Attributes.sngAttrSuccess.toString(), 46
);

// Example 3:

// Send a custom event named "SignUp" without any custom attributes

Singular.event("SignUp");

// Example 4:

// Send a custom event named "bonus_points_earned" with a custom attribute

Singular.event("Bonus Points Earned", "Points", 500);

// Example 1:

// Send the standard event "Subscribe" (sng_subscribe) with no attributes

Singular.event(Events.sngSubscribe.toString())

// Example 2:

// Send the standard event sng_tutorial_complete with the

// recommended standard attributes

Singular.event(Events.sngTutorialComplete.toString(),
    Attributes.sngAttrContent.toString(), "Telugu",
    Attributes.sngAttrContentId.toString(), "32",
    Attributes.sngAttrContentType.toString(), "video",
    Attributes.sngAttrSuccess.toString(), "yes"
)

// Example 3:

// Send a custom event named "SignUp" with no custom attributes

Singular.event("SignUp")

// Example 4:

// Send a custom event named "bonus_points_earned" with a custom attribute

Singular.event("Bonus Points Earned", "Points", 500)

3.2. 구매 추적

Singular는 인앱 구매(IAP), 구독, 맞춤 구매에서 발생한 구매 이벤트를 캡처하여 캠페인 성과와 광고 투자 구매률(ROAS)을 측정합니다. 구매 데이터는 세 가지 주요 채널을 통해 제공됩니다:

• Singular 대시보드의 대화형 보고서
• 사용자 지정 분석을 위한 상세 내보내기 로그 및 ETL 데이터 대상
• 외부 플랫폼에 대한 실시간 포스트백

이러한 포괄적인 구매 추적 기능을 통해 마케팅 비용 및 캠페인 최적화에 대한 데이터 기반 의사결정을 내릴 수 있으며, 데이터 소비 및 분석 방식에 유연성을 제공합니다.

요구 사항

모범 사례

구매 추적 구현

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

Singular.revenue("USD", 5.50, purchase);

Singular.revenue("USD", 5.50, purchase)

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

Singular.customRevenue("MyCustomRevenue", "USD", 5.50, purchase);

Singular.customRevenue("MyCustomRevenue", "USD", 5.50, purchase)

Singular.revenue(String currency, double amount)

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

Singular.revenue(String currency, double amount, Map<String, Object> attributes)

Singular.revenue("USD", 5.50);

Singular.revenue("EUR", 5.00, "SKU1928375", "Reservation Fee", "Fee" , 1, 5.00);

Map<string, object="Object"> attributes = new HashMap<>();
attributes.put("product_id", "com.app.premium");
attributes.put("transaction_id", "T12345");
attributes.put("quantity", 1);
attributes.put("is_trial", false);

// Call the revenue method

Singular.revenue("USD", 9.99, attributes);

Singular.revenue("USD", 5.50)

Singular.revenue("EUR", 5.00, "SKU1928375", "Reservation Fee", "Fee" , 1, 5.00)

val attributes = mutableMapOf<String, Any>().apply {
    put("product_id", "com.app.premium")
    put("transaction_id", "T12345")
    put("quantity", 1)
    put("is_trial", false)
}

// Call the revenue method

Singular.revenue("USD", 9.99, attributes)

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

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

Singular.customRevenue(String eventName, String currency, double amount, Map<String, Object> attributes)

Singular.customRevenue("MyCustomRevenue", "USD", 5.50);

Singular.customRevenue("MyCustomRevenue", "EUR", 5.00, "SKU1928375", "Reservation Fee", "Fee" , 1, 5.00);

Map<string, object="Object"> attributes = new HashMap<>();
attributes.put("product_id", "com.app.premium");
attributes.put("transaction_id", "T12345");
attributes.put("quantity", 1);
attributes.put("is_trial", false);

// Call the revenue method

Singular.customRevenue("MyCustomRevenue", "USD", 9.99, attributes);

Singular.customRevenue("MyCustomRevenue", "USD", 5.50)

Singular.customRevenue("MyCustomRevenue", "EUR", 5.00, "SKU1928375", "Reservation Fee", "Fee" , 1, 5.00)

val attributes = mutableMapOf<String, Any>().apply {
    put("product_id", "com.app.premium")
    put("transaction_id", "T12345")
    put("quantity", 1)
    put("is_trial", false)
}

// Call the revenue method

Singular.customRevenue("MyCustomRevenue", "USD", 9.99, attributes)
        

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

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

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

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

4. 고급 옵션

4.1. 짧은 리퍼러 링크 생성

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

짧은 링크를 사용하면 매개변수로 채워진 긴 Singular 링크를 공유하기에 편리한 더 짧고 안전한 링크로 변환할 수 있습니다.

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

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

• 앱 다운로드로 연결되는 Singular 링크 ( Singular 링크 FAQ 참조).
• 링크에 동적으로 추가하려는 모든 매개변수 (옵션 목록은 링크 매개변수 추적 참조).
• 링크를 공유한 사용자의 새 앱 설치를 다시 추적하려면 추천 사용자의 이름과 ID를 입력합니다.

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

// Create a JSON object to add parameters to the Singular Link (if they don't exist in the link URL yet)

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", // The original Singular Link URL

  "Referrer Name",
  "Referrer ID",
  params,
  new ShortLinkHandler() { 
    @Override
      public void onSuccess(final String shortLinkURL) {
        view.post(new Runnable() {
          @Override
          public void run() {
            // Add your share logic here

          }   
        });
      }

    @Override
    public void onError(final String error) {  
      view.post(new Runnable() {    
        @Override
        public void run() { 
          // Logic to retry/abort/modify the params passed to 

          // the function, based on the cause of the error

        }
      });
    }
});

// Create a JSON object to add parameters to the Singular Link (if they don't exist in the link URL yet)

val params = JSONObject()
try {
    params.put("channel", "sms")
    params.put("another parameter", "parameter value")
} catch (e: JSONException) {
    e.printStackTrace()
}

Singular.createReferrerShortLink(
    "https://sample.sng.link/D52wc/cuvk?pcn=test",  // The original Singular Link URL

    "Referrer Name",
    "Referrer ID",
    params,
    object : ShortLinkHandler {
        override fun onSuccess(shortLinkURL: String) {
            view.post(Runnable {
                // Add your share logic here

            })
        }

        override fun onError(error: String) {
            view.post(Runnable {
                // Logic to retry/abort/modify the params passed to

                // the function, based on the cause of the error

            })
        }
    })

추가_광고_구매_어트리뷰션_지원

4.2. 광고 구매 어트리뷰션 지원 추가하기

4.3. 추적 제거

안드로이드 앱에 대해 앱 제거 추적을 사용하려면 먼저 앱 제거 추적 설정에 설명된 대로 Singular 플랫폼에서 앱을 구성합니다. 그런 다음 아래 지침을 따릅니다.

I. FCM과 연동하기:

제거를 추적하려면 Firebase 클라우드 메시징(FCM) 플랫폼의 서비스를 사용할 수 있습니다. 아직 FCM을 사용하고 있지 않다면 Google의 Android에서 Firebase 클라우드 메시징 클라이언트 앱을 설정하는 방법에 대한 지침을 따르세요.

FCM 요구 사항 ( 출처 )

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

지원되는 Android 버전에서 실행되지 않는 사용자/기기는 Singular 제거 추적 기능을 사용할 수 없습니다.

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 장치 토큰을 등록하고 전송합니다:

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

Singular.setFCMDeviceToken(String fcmDeviceToken);

4.4. 구형 기기에서 설치 리퍼러 수집하기

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

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

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

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

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

앱에 이미 안드로이드에서 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);
        // ...

    }
}

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

앱에 설치 리퍼러 리시버가 없는 경우, 매니페스트 파일의 <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(아이스크림 샌드위치) 이상의 경우, Singular SDK가 세션 관리를 자동으로 처리할 수 있습니다. 앱의 최소 SDK 버전이 14 이상인 경우 세션 관리를 위해 추가 구성이 필요하지 않습니다.

세션 시간 초과 수정

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

타임아웃 값을 변경하려면 SDK를 초기화하기 전에 SingularConfig에서 withSessionTimeoutInSec(<초 단위의 타임아웃>)을 사용합니다.

예를 들어

// Set the session timeout to 120 seconds

SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET")
.withSessionTimeoutInSec(120); 

수동 세션 관리

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

참고: 다른 모든 활동이 파생되는 사용자 지정 공통 기본 활동 클래스가 있는 경우, 공통 활동의 '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
}

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

Singular는 앱의 자바스크립트 코드 내에서 Singular를 호출하기 위해 사용할 수 있는 자바스크립트 인터페이스를 제공합니다.

예를 들어, JavaScript 인터페이스를 설정한 경우 다음과 같이 JavaScript 코드에서 Singular로 이벤트를 보낼 수 있습니다:

이벤트 예시

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 메서드는 다음과 같이 보일 수 있습니다:

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, Singular형 AIFA라고도 함)가 없습니다. 대신 기기에서 발생하는 세션 및 이벤트를 추적하는 데 사용할 수 있는 OAID(개방형 광고 식별자)라는 식별자를 제공할 수 있습니다.

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

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

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

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

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

4.8. IMEI 번호 수집

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

참고: Google Play 서비스를 사용하는 경우에는 Google Play 서비스 계약에 위배되므로 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로 전송합니다:

권장: 다음 예제에서와 같이 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(IMEIString);

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

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

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

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

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

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

// User has opted into sharing data

Singular.limitDataSharing(false);

GDPR 준수를 위한 추가 방법

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

Singular.trackingOptIn();

Singular.stopAllTracking();

Singular.resumeAllTracking();

Singular.isAllTrackingStopped();