Android SDK - 메서드 레퍼런스

Android SDK - 메서드 레퍼런스

이 종합 레퍼런스는 Android 애플리케이션용 Singular SDK에서 사용할 수 있는 모든 메서드를 문서화합니다. SDK는 초기화, 이벤트 트래킹, 매출 보고, 어트리뷰션, 데이터 개인정보 보호 준수, 구성을 위한 기능을 제공합니다. 각 메서드는 설명, 시그니처, 실용적인 사용 예시와 함께 제시되어 개발자가 Singular SDK 기능을 애플리케이션에 연동할 수 있도록 돕습니다.

adRevenue

Singular.adRevenue 메서드

상세한 광고 데이터 정보와 함께 광고 매출 이벤트를 트래킹합니다. 이 메서드를 사용하면 애플리케이션에 표시된 광고에서 발생한 매출을 보고할 수 있습니다.

시그니처

public static void adRevenue(SingularAdData adData);

사용 예시

Kotlin Java
// Create ad data object
val adData = SingularAdData("AdMob", "USD", 0.05).apply {
    withAdUnitId("ca-app-pub-123456789/1234567890")
    withAdType("Rewarded")
    withAdPlacementName("level_complete")
}

// Track ad revenue event
Singular.adRevenue(adData)

clearGlobalProperties

Singular.clearGlobalProperties 메서드

이전에 설정된 모든 전역 속성을 제거합니다. 사용자가 애플리케이션에서 로그아웃하는 경우와 같이 전역 속성을 초기화해야 할 때 유용합니다.

시그니처

public static void clearGlobalProperties();

사용 예시

Kotlin Java
// Clear all global properties
Singular.clearGlobalProperties()

createReferrerShortLink

Singular.createReferrerShortLink 메서드

공유 및 어트리뷰션에 사용할 수 있는 추천인 정보가 포함된 단축 링크를 생성합니다. 이 메서드는 사용자와 공유할 수 있는 추적 가능한 링크를 생성하여 설치와 활동을 특정 추천 소스에 어트리뷰션할 수 있도록 합니다.

시그니처

public static void createReferrerShortLink(String baseLink, String referrerName, String referrerId,
                                            JSONObject passthroughParams, ShortLinkHandler shortLinkHandler);

사용 예시

Kotlin Java
// Create a short link for referral
val passthroughParams = JSONObject().apply {
    put("channel", "sms")
    put("campaign", "summer_promo")
}

Singular.createReferrerShortLink(
    "https://sample.sng.link/B4tbm/v8fp",
    "John Doe",
    "aq239897",
    passthroughParams,
    object : ShortLinkHandler {
        override fun onSuccess(link: String) {
            println("Generated short link: $link")
            // Share the link with users
        }

        override fun onError(error: String) {
            println("Error creating short link: $error")
        }
    }
)

customRevenue

Singular.customRevenue 메서드

지정된 이벤트 이름, 통화, 금액 및 선택적 제품 정보와 함께 사용자 지정 매출 이벤트를 트래킹합니다. 이를 통해 사용자 지정 이벤트 이름으로 더 구체적인 매출 트래킹이 가능합니다.

purchase 객체를 전달할 때 SDK는 객체가 com.android.billingclient.api.Purchase 인스턴스인 경우에만 영수증, 서명, SKU 세부 정보를 추출합니다. 다른 타입은 통화와 금액만 포함된 기본 매출 이벤트로 폴백됩니다.

시그니처

public static boolean customRevenue(String eventName, String currency, double amount, Object purchase);

public static boolean customRevenue(String eventName, String currency, double amount, Object purchase,
                                    Map<String, Object> attributes);

public static boolean customRevenue(String eventName, String currency, double amount);

public static boolean customRevenue(String eventName, String currency, double amount,
                                    Map<String, Object> attributes);

public static boolean customRevenue(String eventName, String currency, double amount,
                                    String receipt, String receiptSignature);

public static boolean customRevenue(String eventName, String currency, double amount, String productSKU,
                                    String productName, String productCategory, int productQuantity,
                                    double productPrice);

public static boolean customRevenue(String eventName, JSONObject json);

사용 예시

Kotlin Java
// Track a custom revenue event
Singular.customRevenue("premium_subscription", "USD", 9.99)

// Track a custom revenue event with attributes
val attributes = mapOf(
    "product_id" to "com.app.gems_pack_small",
    "quantity" to 1
)
Singular.customRevenue("in_app_purchase", "USD", 5.99, attributes)

// Track a custom revenue event from a pre-built JSON payload
val customRevenueJson = JSONObject().apply {
    put("currency", "USD")
    put("amount", 5.99)
    put("product_id", "com.app.gems_pack_small")
}
Singular.customRevenue("in_app_purchase", customRevenueJson)

event

Singular.event 메서드

지정된 이름과 선택적 사용자 지정 속성으로 이벤트를 트래킹합니다. 애플리케이션 내에서 사용자 작업과 인게이지먼트를 트래킹하려면 이러한 메서드를 사용하세요.

varargs 오버로드는 키/값 쌍을 예상하므로 args에는 짝수 개의 요소가 포함되어야 합니다. 홀수 개일 경우 이벤트를 보내지 않고 false를 반환합니다.

시그니처

public static boolean event(String name);

public static boolean event(String name, String extra);

public static boolean event(String name, Object... args);

사용 예시

Kotlin Java
// Track a simple event
Singular.event("level_completed")

// Track an event with variable arguments
Singular.event("level_completed",
    "level_id", 5,
    "score", 12500,
    "time_spent", 120,
    "difficulty", "medium"
)

eventJSON

Singular.eventJSON 메서드

사용자 지정 속성을 포함하는 JSON 객체로 이벤트를 트래킹합니다. 이 메서드는 복잡한 이벤트 데이터 구조에 대해 더 큰 유연성을 제공합니다.

시그니처

public static boolean eventJSON(String name, final JSONObject json);

사용 예시

Kotlin Java
// Track an event with JSON object
val eventData = JSONObject().apply {
    put("level_id", 5)
    put("score", 12500)
    put("time_spent", 120)
    put("difficulty", "medium")
}
Singular.eventJSON("level_completed", eventData)

getGlobalProperties

Singular.getGlobalProperties 메서드

현재 설정된 모든 전역 속성을 가져옵니다. 이 메서드는 SDK에 설정된 모든 전역 속성을 포함하는 맵을 반환합니다.

시그니처

public static Map<String, String> getGlobalProperties();

사용 예시

Kotlin Java
// Get all global properties
val properties = Singular.getGlobalProperties()
println("Global properties: $properties")

getLimitDataSharing

Singular.getLimitDataSharing 메서드

현재 데이터 공유 제한 상태를 가져옵니다. 이 메서드는 데이터 공유가 현재 제한되어 있는지 여부를 나타내는 부울 값을 반환합니다.

SDK가 초기화되지 않은 경우 SingularConfig.withLimitDataSharing을 통해 이전에 설정한 값과 무관하게 false를 반환합니다. 사용자가 옵트인했다는 증거가 아니라 컨텍스트에서 false를 확인하세요.

시그니처

public static boolean getLimitDataSharing();

사용 예시

Kotlin Java
// Check if data sharing is limited
val isLimited = Singular.getLimitDataSharing()
if (isLimited) {
    println("Data sharing is currently limited")
}

getSessionId

Singular.getSessionId 메서드

현재 세션 ID를 반환합니다. 이를 통해 동일한 세션 내의 이벤트를 추적하고 상호 연관시킬 수 있습니다.

SDK가 초기화되지 않은 경우 Constants.INVALID를 반환합니다. 이 값을 사용하기 전에 항상 Singular.init()을 호출하세요.

시그니처

public static long getSessionId();

사용 예시

Kotlin Java
// Get the current session ID
val sessionId = Singular.getSessionId()
println("Current session ID: $sessionId")

init

Singular.init 메서드

제공된 API 키와 시크릿으로, 또는 구성 객체로 Singular SDK를 초기화합니다. Singular SDK를 사용하려면 가장 먼저 이 메서드를 호출해야 합니다.

시그니처

public static boolean init(final Context context, final String apiKey, final String secret);

public static boolean init(final Context context, final SingularConfig config);

사용 예시

Kotlin Java
// Simple initialization with API key and secret
Singular.init(context, "SDK KEY", "YOUR_SECRET")

// Initialize with configuration object
val config = SingularConfig("SDK KEY", "YOUR_SECRET")
    .withCustomUserId("user_123456")
    .withSessionTimeoutInSec(60)

Singular.init(context, config)

isAllTrackingStopped

Singular.isAllTrackingStopped 메서드

모든 트래킹이 현재 중지되어 있는지 확인합니다. 이 메서드는 트래킹이 현재 중지되었는지 여부를 나타내는 부울 값을 반환합니다.

SDK가 초기화되지 않은 경우 false를 반환합니다. false를 "활발히 트래킹 중"이 아니라 "중지되지 않았거나 초기화되지 않음"으로 해석하세요.

시그니처

public static boolean isAllTrackingStopped();

사용 예시

Kotlin Java
// Check if tracking is stopped
if (Singular.isAllTrackingStopped()) {
    println("Tracking is currently stopped")
}

limitDataSharing

Singular.limitDataSharing 메서드

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

시그니처

public static void limitDataSharing(boolean shouldLimitDataSharing);

사용 예시

Kotlin Java
// To limit data sharing (e.g., when user opts out)
Singular.limitDataSharing(true)

// To enable full data sharing (e.g., when user opts in)
Singular.limitDataSharing(false)

onActivityPaused

Singular.onActivityPaused 메서드

액티비티가 일시 중지될 때 SDK에 알립니다. 세션 라이프사이클을 추적하기 위해 액티비티의 onPause() 메서드에서 호출해야 합니다.

시그니처

public static void onActivityPaused();

사용 예시

Kotlin Java
override fun onPause() {
    super.onPause()
    Singular.onActivityPaused()
}

onActivityResumed

Singular.onActivityResumed 메서드

액티비티가 재개될 때 SDK에 알립니다. 세션 라이프사이클을 추적하기 위해 액티비티의 onResume() 메서드에서 호출해야 합니다.

시그니처

public static void onActivityResumed();

사용 예시

Kotlin Java
override fun onResume() {
    super.onResume()
    Singular.onActivityResumed()
}

resumeAllTracking

Singular.resumeAllTracking 메서드

이전에 중지된 모든 트래킹 활동을 재개합니다. 트래킹이 중지된 후 다시 활성화하려면 이 메서드를 사용하세요.

시그니처

public static void resumeAllTracking();

사용 예시

Kotlin Java
// Resume tracking when user opts back in
Singular.resumeAllTracking()

revenue

Singular.revenue 메서드

통화, 금액, 제품 세부 정보를 포함한 다양한 파라미터로 매출 이벤트를 트래킹합니다. 이를 통해 애플리케이션의 포괄적인 매출 트래킹이 가능합니다.

purchase 객체를 전달할 때 SDK는 객체가 com.android.billingclient.api.Purchase 인스턴스인 경우에만 영수증, 서명, SKU 세부 정보를 추출합니다. 다른 타입은 통화와 금액만 포함된 기본 매출 이벤트로 폴백됩니다.

시그니처

public static boolean revenue(String currency, double amount, Object purchase);

public static boolean revenue(String currency, double amount, Object purchase, Map<String, Object> attributes);

public static boolean revenue(String currency, double amount);

public static boolean revenue(String currency, double amount, Map<String, Object> attributes);

public static boolean revenue(String currency, double amount, String receipt, String receiptSignature);

public static boolean revenue(String currency, double amount, String productSKU, String productName,
                              String productCategory, int productQuantity, double productPrice);

public static boolean revenue(JSONObject json);

사용 예시

Kotlin Java
// Track revenue with currency and amount
Singular.revenue("USD", 9.99)

// Track revenue with additional attributes
val attributes = mapOf(
    "product_id" to "premium_gems",
    "quantity" to 2
)
Singular.revenue("USD", 19.98, attributes)

// Track revenue with Google Play purchase object
Singular.revenue("USD", 9.99, purchase)

// Track revenue with detailed product information
Singular.revenue("USD", 19.98,
    "SKU123456",
    "Premium Sword",
    "Weapons",
    2,
    9.99
)

// Track revenue from a pre-built JSON payload
val revenueJson = JSONObject().apply {
    put("currency", "USD")
    put("amount", 9.99)
    put("product_id", "premium_gems")
}
Singular.revenue(revenueJson)

setCustomUserId

Singular.setCustomUserId 메서드

현재 유저에 대한 사용자 지정 유저 ID를 설정합니다. 이를 통해 Singular 데이터를 자체 사용자 식별 시스템과 연결할 수 있습니다.

시그니처

public static void setCustomUserId(String customUserId);

사용 예시

Kotlin Java
// Set custom user ID after user logs in
Singular.setCustomUserId("user_123456")

setDeviceCustomUserId

지원 중단된 기능: setCustomUserId를 대신 사용하세요.

Singular.setDeviceCustomUserId 메서드

디바이스 레벨에서 사용자 지정 유저 ID를 설정합니다. 이를 통해 Singular 데이터를 디바이스 레벨에서 자체 사용자 식별 시스템과 연결할 수 있습니다.

시그니처

public static void setDeviceCustomUserId(String customUserId);

사용 예시

Kotlin Java
// Set device-level custom user ID
Singular.setDeviceCustomUserId("device_user_123456")

setFCMDeviceToken

Singular.setFCMDeviceToken 메서드

푸시 알림 및 앱 삭제 트래킹을 위한 FCM(Firebase Cloud Messaging) 디바이스 토큰을 설정합니다. FCM 토큰을 받을 때 호출해야 합니다.

시그니처

public static void setFCMDeviceToken(String fcmDeviceToken);

사용 예시

Kotlin Java
// In your Firebase Messaging Service
override fun onNewToken(token: String) {
    super.onNewToken(token)
    Singular.setFCMDeviceToken(token)
}

setGCMDeviceToken

지원 중단된 기능: setFCMDeviceToken을 대신 사용하세요.

Singular.setGCMDeviceToken 메서드

GCM(Google Cloud Messaging) 디바이스 토큰을 설정합니다. 이 메서드는 지원이 중단되었습니다. Firebase Cloud Messaging의 경우 setFCMDeviceToken을 대신 사용하세요.

시그니처

public static void setGCMDeviceToken(String gcmDeviceToken);

사용 예시

Kotlin Java
// Deprecated - use setFCMDeviceToken instead
Singular.setGCMDeviceToken(token)

setGlobalProperty

Singular.setGlobalProperty 메서드

모든 이벤트와 함께 전송될 전역 속성을 설정합니다. 이를 통해 매번 지정하지 않아도 모든 이벤트에 일관된 속성을 추가할 수 있습니다.

키가 null이거나 비어 있는 경우, SDK가 초기화되지 않은 경우, 또는 SDK가 이미 최대 5개의 전역 속성을 보유하고 있는 경우 false를 반환합니다. 속성이 저장되었다고 가정하기 전에 반환값을 확인하세요.

시그니처

public static boolean setGlobalProperty(final String key, final String value,
                                        final boolean overrideExisting);

사용 예시

Kotlin Java
// Set a global property
val success = Singular.setGlobalProperty("user_tier", "premium", true)
if (success) {
    println("Global property set successfully")
}

setIMEI

Singular.setIMEI 메서드

트래킹용 디바이스 IMEI를 설정합니다. IMEI 트래킹이 허용되고 선호되는 지역에서 유용합니다.

시그니처

public static void setIMEI(String imei);

사용 예시

Kotlin Java
// Set device IMEI
Singular.setIMEI("123456789012345")

setLimitAdvertisingIdentifiers

Singular.setLimitAdvertisingIdentifiers 메서드

혼합 잠재고객 앱에서 광고 식별자 사용을 활성화하거나 비활성화합니다. 이 옵션은 SDK가 트래킹용 디바이스 식별자를 수집하고 사용하는 방식에 영향을 줍니다.

시그니처

public static void setLimitAdvertisingIdentifiers(boolean enabled);

사용 예시

Kotlin Java
// Enable limited identifiers mode
Singular.setLimitAdvertisingIdentifiers(true)

setWrapperNameAndVersion

Singular.setWrapperNameAndVersion 메서드

래퍼(예: Unity, React Native)를 통해 SDK를 사용할 때 래퍼 이름과 버전을 설정합니다. 이는 어떤 래퍼 프레임워크가 사용되고 있는지 식별하는 데 도움이 됩니다.

시그니처

public static void setWrapperNameAndVersion(final String wrapper, final String version);

사용 예시

Kotlin Java
// Set wrapper information
Singular.setWrapperNameAndVersion("Unity", "1.2.3")

stopAllTracking

Singular.stopAllTracking 메서드

모든 트래킹 활동을 중지합니다. 사용자가 옵트아웃하거나 개인정보 보호 규정 준수를 위해 트래킹을 비활성화하려면 이 메서드를 사용하세요.

시그니처

public static void stopAllTracking();

사용 예시

Kotlin Java
// Stop tracking when user opts out
Singular.stopAllTracking()

trackingOptIn

Singular.trackingOptIn 메서드

사용자가 트래킹에 옵트인했음을 나타냅니다. 사용자가 트래킹 및 데이터 수집에 명시적으로 동의했을 때 이 메서드를 호출하세요.

시그니처

public static void trackingOptIn();

사용 예시

Kotlin Java
// User has opted in to tracking
Singular.trackingOptIn()

trackingUnder13

Singular.trackingUnder13 메서드

유저가 13세 미만임을 나타냅니다. 13세 미만 유저에 대한 COPPA 및 기타 규정을 준수하려면 이 메서드를 호출하세요.

시그니처

public static void trackingUnder13();

사용 예시

Kotlin Java
// Notify Singular the user is under 13 years old
Singular.trackingUnder13()

unsetCustomUserId

Singular.unsetCustomUserId 메서드

이전에 설정된 사용자 지정 유저 ID를 제거합니다. 유저가 로그아웃하거나 현재 유저 ID와 이벤트를 더 이상 연결하지 않으려는 경우 이 메서드를 호출하세요.

시그니처

public static void unsetCustomUserId();

사용 예시

Kotlin Java
// Clear custom user ID when user logs out
Singular.unsetCustomUserId()

unsetGlobalProperty

Singular.unsetGlobalProperty 메서드

이전에 설정된 전역 속성을 제거합니다. 특정 전역 속성이 더 이상 이벤트와 함께 전송되는 것을 원치 않을 때 이 메서드를 호출하세요.

시그니처

public static void unsetGlobalProperty(String key);

사용 예시

Kotlin Java
// Remove a global property
Singular.unsetGlobalProperty("user_tier")