Android SDK - 구성 레퍼런스
이 문서는 Android 애플리케이션용 Singular SDK에서 사용할 수 있는 모든 구성 옵션에 대한 종합적인 레퍼런스를 제공합니다. SingularConfig 객체를 사용하면 트래킹 설정, 어트리뷰션 옵션, 개인정보 보호 제어 등을 포함한 SDK 동작을 사용자 지정할 수 있습니다. 각 구성 메서드는 설명, 시그니처, 실용적인 사용 예시와 함께 제시됩니다.
전체 구성 예시
포괄적인 SDK 구성
다음 예시는 여러 구성 메서드를 체이닝하여 포괄적인 구성을 만드는 방법을 보여줍니다.
전체 예시
// 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)
// User details are hashed by the SDK before they are sent
SingularUserDetails userDetails = new SingularUserDetails();
userDetails.setEmail("user@example.com");
userDetails.setPhoneNumber("+15551234567");
// 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")
// User details
.withUserDetails(userDetails);
// 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 작업은 메인 스레드로 디스패치하세요.
값이 있는 필드만 포함되므로 값을 읽기 전에 키의 존재 여부를 확인하세요. 대부분의 설치에서는 일부 필드만 반환되며, 어떤 필드가 포함되는지는 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);
사용 예시
// 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);
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);
사용 예시
// Attach user details at initialization
val userDetails = SingularUserDetails()
userDetails.setEmail("user@example.com")
userDetails.setPhoneNumber("+15551234567")
val config = SingularConfig("API_KEY", "SECRET")
.withUserDetails(userDetails)
// Attach user details at initialization
SingularUserDetails userDetails = new SingularUserDetails();
userDetails.setEmail("user@example.com");
userDetails.setPhoneNumber("+15551234567");
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withUserDetails(userDetails);