Android SDK - 구성 레퍼런스

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

전체 구성 예시

포괄적인 SDK 구성

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

전체 예시

// 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")

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

// Create comprehensive configuration
SingularConfig config = new 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(getIntent().getData())
    .withSingularLink(getIntent(), new SingularLinkHandler() {
        @Override
        public void onResolved(SingularLinkParams params) {
            if (params.getDeeplink() != null) {
                System.out.println("Deep link: " + params.getDeeplink());
                handleDeepLink(params.getDeeplink());
            }
        }
    }, 10)

    // Attribution callback
    .withSingularDeviceAttribution(new SingularDeviceAttributionHandler() {
        @Override
        public void onDeviceAttributionInfoReceived(Map<String, Object> attributionData) {
            System.out.println("Attribution: " + attributionData);
        }
    })

    // Push notifications
    .withFCMDeviceToken(fcmToken)

    // Privacy settings
    .withLimitDataSharing(false)

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

    // Facebook integration
    .withFacebookAppId("YOUR_FACEBOOK_APP_ID");

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

Constructor

SingularConfig Constructor

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

시그니처

public SingularConfig(String apiKey, String secret);

사용 예시

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

// Create configuration object
SingularConfig config = new SingularConfig("SDK KEY", "YOUR_SECRET");

withBrandedDomains

SingularConfig.withBrandedDomains 메서드

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

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

시그니처

public SingularConfig withBrandedDomains(List<String> brandedDomains);

사용 예시

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

// Set branded domains for web-to-app attribution
List<String> brandedDomains = Arrays.asList("yourcompany.com", "go.yourcompany.com");
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withBrandedDomains(brandedDomains);

withCustomSdid

SingularConfig.withCustomSdid 메서드

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

시그니처

public SingularConfig withCustomSdid(String customSdid, SDIDAccessorHandler accessorHandler);

사용 예시

// 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
        }
    })

// Set custom SDID with callback
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withCustomSdid("custom-device-id-12345", new SDIDAccessorHandler() {
        @Override
        public void didSetSdid(String result) {
            System.out.println("SDID was set: " + result);
            // Perform any actions needed after SDID is set
        }

        @Override
        public void sdidReceived(String result) {
            System.out.println("SDID received: " + result);
            // Existing SDID returned by the SDK
        }
    });

withCustomUserId

SingularConfig.withCustomUserId 메서드

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

시그니처

public SingularConfig withCustomUserId(String customUserId);

사용 예시

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

// Set custom user ID at initialization
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withCustomUserId("user_123456");

withESPDomains

SingularConfig.withESPDomains 메서드

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

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

시그니처

public SingularConfig withESPDomains(List<String> espDomains);

사용 예시

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

// Set ESP domains for email attribution
List<String> espDomains = Arrays.asList("mailchimp.com", "sendgrid.net", "campaign-monitor.com");
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withESPDomains(espDomains);

withFacebookAppId

SingularConfig.withFacebookAppId 메서드

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

시그니처

public SingularConfig withFacebookAppId(String facebookAppId);

사용 예시

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

// Set Facebook App ID
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withFacebookAppId("YOUR_FACEBOOK_APP_ID");

withFCMDeviceToken

SingularConfig.withFCMDeviceToken 메서드

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

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

시그니처

public SingularConfig withFCMDeviceToken(String fcmDeviceToken);

사용 예시

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

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

withGlobalProperty

SingularConfig.withGlobalProperty 메서드

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

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

시그니처

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

사용 예시

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

// Add global properties at initialization
SingularConfig config = new 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);

사용 예시

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

// Set device IMEI at initialization
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withIMEI("123456789012345");

withLimitAdvertisingIdentifiers

SingularConfig.withLimitAdvertisingIdentifiers 메서드

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

시그니처

public SingularConfig withLimitAdvertisingIdentifiers();

사용 예시

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

// Enable limited identifiers mode
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withLimitAdvertisingIdentifiers();

withLimitDataSharing

SingularConfig.withLimitDataSharing 메서드

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

시그니처

public SingularConfig withLimitDataSharing(boolean shouldLimitDataSharing);

사용 예시

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

// Enable limited data sharing at initialization
SingularConfig config = new 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);

사용 예시

import android.util.Log

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

import android.util.Log;

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

withLoggingEnabled

SingularConfig.withLoggingEnabled 메서드

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

시그니처

public SingularConfig withLoggingEnabled();

사용 예시

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

// Enable logging for debug builds
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withLoggingEnabled();

withOAIDCollection

SingularConfig.withOAIDCollection 메서드

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

시그니처

public SingularConfig withOAIDCollection();

사용 예시

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

// Enable OAID collection for China
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withOAIDCollection();

withOpenURI

SingularConfig.withOpenURI 메서드

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

시그니처

public SingularConfig withOpenURI(Uri openUri);

사용 예시

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

// In your Activity's onCreate or onNewIntent
Uri uri = getIntent().getData();
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withOpenURI(uri);

withPushNotificationPayload

SingularConfig.withPushNotificationPayload 메서드

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

시그니처

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

사용 예시

// 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")
    )

// Set push notification payload with custom link paths
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withPushNotificationPayload(
        intent,
        new String[]{"data", "deeplink"},
        new String[]{"notification", "data", "url"},
        new String[]{"custom", "link"}
    );

withSdidAccessorHandler

SingularConfig.withSdidAccessorHandler 메서드

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

시그니처

public SingularConfig withSdidAccessorHandler(SDIDAccessorHandler accessorHandler);

사용 예시

// 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)
        }
    })

// Set callback for when SDID is received
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withSdidAccessorHandler(new SDIDAccessorHandler() {
        @Override
        public void didSetSdid(String result) {
            System.out.println("SDID was set: " + result);
        }

        @Override
        public void sdidReceived(String result) {
            System.out.println("SDID received: " + result);
            // Store or use the SDID as needed
            storeDeviceIdentifier(result);
        }
    });

withSessionTimeoutInSec

SingularConfig.withSessionTimeoutInSec 메서드

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

시그니처

public SingularConfig withSessionTimeoutInSec(long timeout);

사용 예시

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

// Set session timeout to 2 minutes
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withSessionTimeoutInSec(120);

withSingularDeviceAttribution

SingularConfig.withSingularDeviceAttribution 메서드

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

키	타입	비고
`network`	String	어트리뷰션 소스. "organic" 은 어트리뷰션되지 않은 설치를 의미합니다.
`campaign_id`	String	어트리뷰션된 경우에만 존재합니다.
`campaign_name`	String	어트리뷰션된 경우에만 존재합니다.
`click_timestamp`	Long (epoch 마이크로초)	어트리뷰션된 경우에만 존재합니다. 초 단위로 변환하려면 1,000,000으로 나누세요.

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

시그니처

public SingularConfig withSingularDeviceAttribution(SingularDeviceAttributionHandler handler);

사용 예시

// 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) }
      }

// Set device attribution callback
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
  .withSingularDeviceAttribution(new SingularDeviceAttributionHandler() {
    @Override
    public void onDeviceAttributionInfoReceived(Map<String, Object> attributionData) {
      Log.d("Singular", "Attribution data received: " + attributionData);
      String source        = (String) attributionData.get("network");
      String campaignName  = (String) attributionData.get("campaign_name");
      String campaignId    = (String) attributionData.get("campaign_id");
      Object clickTsObj    = attributionData.get("click_timestamp");
      Long   clickTimestamp = clickTsObj != null
          ? Long.parseLong(clickTsObj.toString())
          : null;
      if (campaignName != null) {
          showCampaignSpecificContent(campaignName);
      }
    }
});

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

사용 예시

// 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)

// Set Singular Links handler
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withSingularLink(intent, new SingularLinkHandler() {
        @Override
        public void onResolved(SingularLinkParams params) {
            // Check if we have a deep link
            if (params.getDeeplink() != null) {
                System.out.println("Deep link received: " + params.getDeeplink());
                // Navigate based on the deep link
                navigateToScreen(params.getDeeplink());
            }

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

            // Access passthrough parameters
            if (params.getPassthrough() != null) {
                System.out.println("Passthrough data: " + params.getPassthrough());
            }
        }
    }, 10);

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

Android SDK - 구성 레퍼런스

전체 구성 예시

포괄적인 SDK 구성

전체 예시

Constructor

SingularConfig Constructor

시그니처

사용 예시

withBrandedDomains

SingularConfig.withBrandedDomains 메서드

시그니처

사용 예시

withCustomSdid

SingularConfig.withCustomSdid 메서드

시그니처

사용 예시

withCustomUserId

SingularConfig.withCustomUserId 메서드

시그니처

사용 예시

withESPDomains

SingularConfig.withESPDomains 메서드

시그니처

사용 예시

withFacebookAppId

SingularConfig.withFacebookAppId 메서드

시그니처

사용 예시

withFCMDeviceToken

SingularConfig.withFCMDeviceToken 메서드

시그니처

사용 예시

withGlobalProperty

SingularConfig.withGlobalProperty 메서드

시그니처

사용 예시

withIMEI

SingularConfig.withIMEI 메서드

시그니처

사용 예시

withLimitAdvertisingIdentifiers

SingularConfig.withLimitAdvertisingIdentifiers 메서드

시그니처

사용 예시

withLimitDataSharing

SingularConfig.withLimitDataSharing 메서드

시그니처

사용 예시

withLogLevel

SingularConfig.withLogLevel 메서드

시그니처

사용 예시

withLoggingEnabled

SingularConfig.withLoggingEnabled 메서드

시그니처

사용 예시

withOAIDCollection

SingularConfig.withOAIDCollection 메서드

시그니처

사용 예시

withOpenURI

SingularConfig.withOpenURI 메서드

시그니처

사용 예시

withPushNotificationPayload

SingularConfig.withPushNotificationPayload 메서드

시그니처

사용 예시

withSdidAccessorHandler

SingularConfig.withSdidAccessorHandler 메서드

시그니처

사용 예시

withSessionTimeoutInSec

SingularConfig.withSessionTimeoutInSec 메서드

시그니처

사용 예시

withSingularDeviceAttribution

SingularConfig.withSingularDeviceAttribution 메서드

시그니처