Android SDK - 구성 메서드 레퍼런스

Android SDK - 구성 레퍼런스

이 문서는 Android 애플리케이션용 Singular SDK에서 사용할 수 있는 모든 구성 옵션에 대한 종합적인 레퍼런스를 제공합니다. SingularConfig 객체를 사용하면 트래킹 설정, 어트리뷰션 옵션, 개인정보 보호 제어 등을 포함한 SDK 동작을 사용자 지정할 수 있습니다. 각 구성 메서드는 설명, 시그니처, 실용적인 사용 예시와 함께 제시됩니다.

전체 구성 예시

포괄적인 SDK 구성

다음 예시는 여러 구성 메서드를 체이닝하여 포괄적인 구성을 만드는 방법을 보여줍니다.

전체 예시

Kotlin Java
// User details are hashed by the SDK before they are sent
val userDetails = SingularUserDetails()
userDetails.setEmail("user@example.com")
userDetails.setPhoneNumber("+15551234567")

// Create comprehensive configuration
val config = SingularConfig("SDK KEY", "YOUR_SECRET")
    // Basic options
    .withSessionTimeoutInSec(120)
    .withLoggingEnabled()
    .withLogLevel(Log.VERBOSE)

    // User identification
    .withCustomUserId("user_123456")

    // Global properties
    .withGlobalProperty("app_version", "1.2.3", true)
    .withGlobalProperty("user_type", "premium", true)

    // Deep links
    .withOpenURI(intent.data)
    .withSingularLink(intent, { params ->
        params.deeplink?.let { deeplink ->
            println("Deep link: $deeplink")
            handleDeepLink(deeplink)
        }
    }, 10)

    // Attribution callback
    .withSingularDeviceAttribution { attributionData ->
        println("Attribution: $attributionData")
    }

    // Push notifications
    .withFCMDeviceToken(fcmToken)

    // Privacy settings
    .withLimitDataSharing(false)

    // Email attribution
    .withESPDomains(listOf("mailchimp.com", "sendgrid.net"))

    // Facebook integration
    .withFacebookAppId("YOUR_FACEBOOK_APP_ID")

    // User details
    .withUserDetails(userDetails)

// Initialize the SDK
Singular.init(context, config)

Constructor

SingularConfig Constructor

API 키와 시크릿으로 새 SingularConfig 객체를 초기화합니다. Singular SDK를 구성하는 첫 번째 단계입니다.

시그니처

public SingularConfig(String apiKey, String secret);

사용 예시

Kotlin Java
// Create configuration object
val config = SingularConfig("SDK KEY", "YOUR_SECRET")

withBrandedDomains

SingularConfig.withBrandedDomains 메서드

웹-앱 어트리뷰션을 위한 브랜드 도메인을 설정합니다. 어트리뷰션 목적으로 추적해야 하는 사용자 지정 도메인을 지정할 수 있습니다.

이 메서드를 호출하면 이전에 설정된 모든 브랜드 도메인이 대체됩니다. 여러 번 체이닝하지 말고 Singular 호출로 전체 목록을 전달하세요.

시그니처

public SingularConfig withBrandedDomains(List<String> brandedDomains);

사용 예시

Kotlin Java
// Set branded domains for web-to-app attribution
val brandedDomains = listOf("yourcompany.com", "go.yourcompany.com")
val config = SingularConfig("API_KEY", "SECRET")
    .withBrandedDomains(brandedDomains)

withCustomSdid

SingularConfig.withCustomSdid 메서드

사용자 지정 SDID(Singular Device ID)를 설정합니다. Singular에서 생성한 기기 식별자 대신 자체 기기 식별자를 제공할 수 있습니다.

시그니처

public SingularConfig withCustomSdid(String customSdid, SDIDAccessorHandler accessorHandler);

사용 예시

Kotlin Java
// Set custom SDID with callback
val config = SingularConfig("API_KEY", "SECRET")
    .withCustomSdid("custom-device-id-12345", object : SDIDAccessorHandler {
        override fun didSetSdid(result: String) {
            println("SDID was set: $result")
            // Perform any actions needed after SDID is set
        }

        override fun sdidReceived(result: String) {
            println("SDID received: $result")
            // Existing SDID returned by the SDK
        }
    })

withCustomUserId

SingularConfig.withCustomUserId 메서드

SDK 초기화 중에 사용자 지정 유저 ID를 설정합니다. 이를 통해 처음부터 Singular 데이터를 자체 사용자 식별 시스템과 연결할 수 있습니다.

시그니처

public SingularConfig withCustomUserId(String customUserId);

사용 예시

Kotlin Java
// Set custom user ID at initialization
val config = SingularConfig("API_KEY", "SECRET")
    .withCustomUserId("user_123456")

withESPDomains

SingularConfig.withESPDomains 메서드

이메일 어트리뷰션을 위한 ESP(이메일 서비스 제공업체) 도메인을 설정합니다. 어트리뷰션 대상으로 고려해야 할 이메일 도메인을 지정할 수 있습니다.

이 메서드를 호출하면 이전에 설정된 모든 ESP 도메인이 대체됩니다. 여러 번 체이닝하지 말고 Singular 호출로 전체 목록을 전달하세요.

시그니처

public SingularConfig withESPDomains(List<String> espDomains);

사용 예시

Kotlin Java
// Set ESP domains for email attribution
val espDomains = listOf("mailchimp.com", "sendgrid.net", "campaign-monitor.com")
val config = SingularConfig("API_KEY", "SECRET")
    .withESPDomains(espDomains)

withFacebookAppId

SingularConfig.withFacebookAppId 메서드

Facebook 어트리뷰션 연동을 위한 Facebook App ID를 설정합니다. 이를 통해 SDK가 Facebook 캠페인 어트리뷰션을 추적할 수 있습니다.

시그니처

public SingularConfig withFacebookAppId(String facebookAppId);

사용 예시

Kotlin Java
// Set Facebook App ID
val config = SingularConfig("API_KEY", "SECRET")
    .withFacebookAppId("YOUR_FACEBOOK_APP_ID")

withFCMDeviceToken

SingularConfig.withFCMDeviceToken 메서드

초기화 시 FCM(Firebase Cloud Messaging) 기기 토큰을 설정합니다. 이를 통해 처음부터 푸시 알림 추적과 앱 삭제 감지를 활성화할 수 있습니다.

토큰이 null이거나 비어 있으면 호출이 무시됩니다. 유효한 FCM 토큰이 있을 때만 이 메서드를 호출하세요.

시그니처

public SingularConfig withFCMDeviceToken(String fcmDeviceToken);

사용 예시

Kotlin Java
// Set FCM token at initialization if available
val config = SingularConfig("API_KEY", "SECRET")
    .withFCMDeviceToken(fcmToken)

withGlobalProperty

SingularConfig.withGlobalProperty 메서드

SDK 초기화 중에 전역 속성을 설정합니다. 이 속성은 SDK가 추적하는 모든 이벤트와 함께 전송됩니다. 체이닝 방식으로 구성할 수 있는 메서드입니다.

SDK는 최대 5개의 전역 속성을 지원합니다. 이 한도를 초과하는 호출은 자동으로 무시됩니다.

시그니처

public SingularConfig withGlobalProperty(String key, String value, boolean overrideExisting);

사용 예시

Kotlin Java
// Add global properties at initialization
val config = SingularConfig("API_KEY", "SECRET")
    .withGlobalProperty("app_version", "1.2.3", true)
    .withGlobalProperty("user_type", "free", true)

withIMEI

SingularConfig.withIMEI 메서드

초기화 시 추적용 기기 IMEI를 설정합니다. IMEI 추적이 허용되고 선호되는 지역에서 유용합니다.

시그니처

public SingularConfig withIMEI(String imei);

사용 예시

Kotlin Java
// Set device IMEI at initialization
val config = SingularConfig("API_KEY", "SECRET")
    .withIMEI("123456789012345")

withLimitAdvertisingIdentifiers

SingularConfig.withLimitAdvertisingIdentifiers 메서드

혼합 잠재고객 앱에서 광고 식별자 제한 모드를 활성화합니다. 이 옵션은 SDK가 추적용 기기 식별자를 수집하고 사용하는 방식에 영향을 줍니다.

시그니처

public SingularConfig withLimitAdvertisingIdentifiers();

사용 예시

Kotlin Java
// Enable limited identifiers mode
val config = SingularConfig("API_KEY", "SECRET")
    .withLimitAdvertisingIdentifiers()

withLimitDataSharing

SingularConfig.withLimitDataSharing 메서드

초기화 시 데이터 공유 제한 상태를 설정합니다. 사용자 동의 또는 개인정보 보호 요구사항에 따라 데이터 공유를 제한하려면 이 메서드를 사용하세요.

시그니처

public SingularConfig withLimitDataSharing(boolean shouldLimitDataSharing);

사용 예시

Kotlin Java
// Enable limited data sharing at initialization
val config = SingularConfig("API_KEY", "SECRET")
    .withLimitDataSharing(true)

withLogLevel

SingularConfig.withLogLevel 메서드

SDK 로깅의 로그 레벨을 설정합니다. 사용 가능한 레벨은 다음과 같습니다:

  • NONE = -1

  • VERBOSE = Log.VERBOSE (Android 상수, 숫자 값 2)

  • DEBUG = Log.DEBUG (3)

  • INFO = Log.INFO (4)

  • WARNING = Log.WARN (5)

  • ERROR = Log.ERROR (6)

기본 로그 레벨은 Log.ERROR입니다. 로그 출력이 발생하려면 withLoggingEnabled()를 통해 로깅도 활성화해야 합니다.

시그니처

public SingularConfig withLogLevel(int level);

사용 예시

Kotlin Java
import android.util.Log

// Set verbose logging for detailed debugging
val config = SingularConfig("API_KEY", "SECRET")
    .withLoggingEnabled()
    .withLogLevel(Log.VERBOSE)

withLoggingEnabled

SingularConfig.withLoggingEnabled 메서드

SDK 로깅을 활성화합니다. 개발 중 디버깅과 문제 해결에 유용합니다. 프로덕션 빌드에서는 로깅을 비활성화하는 것이 좋습니다.

시그니처

public SingularConfig withLoggingEnabled();

사용 예시

Kotlin Java
// Enable logging for debug builds
val config = SingularConfig("API_KEY", "SECRET")
    .withLoggingEnabled()

withOAIDCollection

SingularConfig.withOAIDCollection 메서드

OAID(Open Anonymous Device Identifier) 수집을 활성화합니다. 주로 Google Play Services를 사용할 수 없는 중국에서 추적용으로 사용됩니다.

시그니처

public SingularConfig withOAIDCollection();

사용 예시

Kotlin Java
// Enable OAID collection for China
val config = SingularConfig("API_KEY", "SECRET")
    .withOAIDCollection()

withOpenURI

SingularConfig.withOpenURI 메서드

앱을 열었던 URI를 설정합니다. 딥링크 어트리뷰션에 사용되며 앱이 딥링크를 통해 열렸을 때 설정해야 합니다.

시그니처

public SingularConfig withOpenURI(Uri openUri);

사용 예시

Kotlin Java
// In your Activity's onCreate or onNewIntent
val uri = intent.data
val config = SingularConfig("API_KEY", "SECRET")
    .withOpenURI(uri)

withPushNotificationPayload

SingularConfig.withPushNotificationPayload 메서드

어트리뷰션을 위한 푸시 알림 페이로드를 설정합니다. 이를 통해 SDK가 초기화 중에 푸시 알림 데이터를 처리할 수 있습니다.

시그니처

public SingularConfig withPushNotificationPayload(Intent intent, String[] ... pushNotificationLinkPath);

사용 예시

Kotlin Java
// Set push notification payload with custom link paths
val config = SingularConfig("API_KEY", "SECRET")
    .withPushNotificationPayload(
        intent,
        arrayOf("data", "deeplink"),
        arrayOf("notification", "data", "url"),
        arrayOf("custom", "link")
    )

withSdidAccessorHandler

SingularConfig.withSdidAccessorHandler 메서드

SDID(Singular Device ID)를 받았을 때 호출될 콜백 함수를 설정합니다. 이를 통해 SDID가 사용 가능해지면 즉시 액세스할 수 있습니다.

시그니처

public SingularConfig withSdidAccessorHandler(SDIDAccessorHandler accessorHandler);

사용 예시

Kotlin Java
// Set callback for when SDID is received
val config = SingularConfig("API_KEY", "SECRET")
    .withSdidAccessorHandler(object : SDIDAccessorHandler {
        override fun didSetSdid(result: String) {
            println("SDID was set: $result")
        }

        override fun sdidReceived(result: String) {
            println("SDID received: $result")
            // Store or use the SDID as needed
            storeDeviceIdentifier(result)
        }
    })

withSessionTimeoutInSec

SingularConfig.withSessionTimeoutInSec 메서드

세션 타임아웃을 초 단위로 설정합니다. 앱이 백그라운드로 전환된 후 사용자 세션이 얼마나 지속될지 결정합니다. 기본값은 60초입니다.

시그니처

public SingularConfig withSessionTimeoutInSec(long timeout);

사용 예시

Kotlin Java
// Set session timeout to 2 minutes
val config = SingularConfig("API_KEY", "SECRET")
    .withSessionTimeoutInSec(120)

withSingularDeviceAttribution

SingularConfig.withSingularDeviceAttribution 메서드

BETA 기능: /start 응답에서 기기 어트리뷰션 데이터가 사용 가능해졌을 때 호출될 콜백 함수를 설정합니다. 콜백은 백그라운드 스레드에서 실행되므로 UI 작업은 메인 스레드로 디스패치하세요.

값이 있는 필드만 포함되므로 값을 읽기 전에 키의 존재 여부를 확인하세요. 대부분의 설치에서는 일부 필드만 반환되며, 어떤 필드가 포함되는지는 Singular이 매칭한 터치포인트에 따라 달라집니다.

유형 참고
network String 콜백이 호출될 때 항상 포함됩니다. 터치포인트가 매칭되지 않은 경우 "Organic"입니다.
campaign_id String 터치포인트가 제공하는 경우 포함됩니다.
campaign_name String 터치포인트가 제공하는 경우 포함됩니다.
subcampaign_id String 터치포인트가 제공하는 경우 포함됩니다. 모든 소스에서 제공되지는 않습니다.
subcampaign_name String 터치포인트가 제공하는 경우 포함됩니다. 모든 소스에서 제공되지는 않습니다.
creative_id String 터치포인트가 제공하는 경우 포함됩니다. 모든 소스에서 제공되지는 않습니다.
creative_name String 터치포인트가 제공하는 경우 포함됩니다. 모든 소스에서 제공되지는 않습니다.
passthrough String 링크에 패스스루 값이 첨부된 경우 포함됩니다.
match_type String 터치포인트가 제공하는 경우 포함됩니다. 값 목록이 필요하면 Singular에 문의하세요.
click_timestamp Long 터치포인트가 제공하는 경우 포함됩니다. epoch 마이크로초이며, 초 단위로 변환하려면 1,000,000으로 나누세요.

콜백은 /start 응답이 attribution_info 객체를 포함할 때만 호출됩니다. 자연량 설치의 경우 network만 채워집니다.

시그니처

public SingularConfig withSingularDeviceAttribution(SingularDeviceAttributionHandler handler);

사용 예시

Kotlin Java
// Set device attribution callback
val config = SingularConfig("API_KEY", "SECRET")
      .withSingularDeviceAttribution { attributionData ->
          println("Attribution data received: $attributionData")

          val source         = attributionData["network"]        as? String
          val campaignName   = attributionData["campaign_name"]  as? String
          val campaignId     = attributionData["campaign_id"]    as? String
          val clickTimestamp = attributionData["click_timestamp"]?.toString()?.toLongOrNull()

          campaignName?.let { showCampaignSpecificContent(it) }
      }

withSingularLink

SingularConfig.withSingularLink 메서드

어트리뷰션을 위한 Singular Links(딥링크)를 구성합니다. 이 메서드는 딥링크 처리를 위한 핸들러와 단축 링크 해석을 위한 타임아웃을 설정합니다.

shortlinkTimeoutSec 인수가 생략되면 SDK는 기본값 10초를 사용합니다. 인텐트 액션이 ACTION_VIEW인 경우 SDK는 세션을 딥링크로 열린 것으로 표시합니다.

시그니처

public SingularConfig withSingularLink(Intent intent, SingularLinkHandler handler);

public SingularConfig withSingularLink(Intent intent, SingularLinkHandler handler,
                                       long shortlinkTimeoutSec);

사용 예시

Kotlin Java
// Set Singular Links handler
val config = SingularConfig("API_KEY", "SECRET")
    .withSingularLink(intent, { params ->
        // Check if we have a deep link
        params.deeplink?.let { deeplink ->
            println("Deep link received: $deeplink")
            // Navigate based on the deep link
            navigateToScreen(deeplink)
        }

        // Check if this is a deferred deep link
        if (params.isDeferred) {
            println("This is a deferred deep link")
        }

        // Access passthrough parameters
        params.passthrough?.let { passthrough ->
            println("Passthrough data: $passthrough")
        }
    }, 10)

withUserDetails

SingularConfig.withUserDetails 메서드

초기화 시 User Details(이메일 주소 및 전화번호)를 연결하여 첫 번째 세션부터 전송되도록 합니다. Singular.init를 호출하기 전에 SingularUserDetails 객체를 전달하세요. SDK는 값이 디바이스를 떠나기 전에 정규화하고 SHA-256으로 해싱하므로, 원본 이메일 주소와 전화번호는 전송되지 않습니다.

Android SDK 버전 12.16.0 이상에서 사용할 수 있습니다. 전체 setter 목록, 검증 규칙, 런타임 setUserDetails / clearUserDetails 메서드는 유저 ID 및 해시된 User Details 설정을 참조하세요.

참고: 여기에서 설정한 값은 디바이스에 암호화되어 저장되며 clearUserDetails를 호출할 때까지 앱 실행 간에 유지됩니다. 이후 실행에서 이 메서드를 다시 호출해도 이전에 저장된 값은 삭제되지 않습니다.

중요: 이 메서드는 Kids SDK 버전에서는 사용할 수 없습니다. 또한 Limit Data Sharing이 활성화된 동안에는 User Details 페이로드가 모든 요청에서 제외됩니다.

시그니처

public SingularConfig withUserDetails(SingularUserDetails userDetails);

사용 예시

Kotlin Java
// Attach user details at initialization
val userDetails = SingularUserDetails()
userDetails.setEmail("user@example.com")
userDetails.setPhoneNumber("+15551234567")

val config = SingularConfig("API_KEY", "SECRET")
    .withUserDetails(userDetails)