Android SDK - 메서드 레퍼런스
이 종합 레퍼런스는 Android 애플리케이션용 Singular SDK에서 사용할 수 있는 모든 메서드를 문서화합니다. SDK는 초기화, 이벤트 트래킹, 매출 보고, 어트리뷰션, 데이터 개인정보 보호 준수, 구성을 위한 기능을 제공합니다. 각 메서드는 설명, 시그니처, 실용적인 사용 예시와 함께 제시되어 개발자가 Singular SDK 기능을 애플리케이션에 연동할 수 있도록 돕습니다.
adRevenue
Singular.adRevenue 메서드
상세한 광고 데이터 정보와 함께 광고 매출 이벤트를 트래킹합니다. 이 메서드를 사용하면 애플리케이션에 표시된 광고에서 발생한 매출을 보고할 수 있습니다.
시그니처
public static void adRevenue(SingularAdData adData);
사용 예시
// 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)
// Create ad data object
SingularAdData adData = new SingularAdData("AdMob", "USD", 0.05)
.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();
사용 예시
// Clear all global properties
Singular.clearGlobalProperties()
// Clear all global properties
Singular.clearGlobalProperties();
createReferrerShortLink
Singular.createReferrerShortLink 메서드
공유 및 어트리뷰션에 사용할 수 있는 추천인 정보가 포함된 단축 링크를 생성합니다. 이 메서드는 사용자와 공유할 수 있는 추적 가능한 링크를 생성하여 설치와 활동을 특정 추천 소스에 어트리뷰션할 수 있도록 합니다.
시그니처
public static void createReferrerShortLink(String baseLink, String referrerName, String referrerId,
JSONObject passthroughParams, ShortLinkHandler shortLinkHandler);
사용 예시
// 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")
}
}
)
// Create a short link for referral
try {
JSONObject passthroughParams = new JSONObject();
passthroughParams.put("channel", "sms");
passthroughParams.put("campaign", "summer_promo");
Singular.createReferrerShortLink(
"https://sample.sng.link/B4tbm/v8fp",
"John Doe",
"aq239897",
passthroughParams,
new ShortLinkHandler() {
@Override
public void onSuccess(String link) {
System.out.println("Generated short link: " + link);
// Share the link with users
}
@Override
public void onError(String error) {
System.out.println("Error creating short link: " + error);
}
}
);
} catch (JSONException e) {
e.printStackTrace();
}
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);
사용 예시
// 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)
// Track a custom revenue event
Singular.customRevenue("premium_subscription", "USD", 9.99);
// Track a custom revenue event with attributes
Map<String, Object> attributes = new HashMap<>();
attributes.put("product_id", "com.app.gems_pack_small");
attributes.put("quantity", 1);
Singular.customRevenue("in_app_purchase", "USD", 5.99, attributes);
// Track a custom revenue event from a pre-built JSON payload
try {
JSONObject customRevenueJson = new JSONObject();
customRevenueJson.put("currency", "USD");
customRevenueJson.put("amount", 5.99);
customRevenueJson.put("product_id", "com.app.gems_pack_small");
Singular.customRevenue("in_app_purchase", customRevenueJson);
} catch (JSONException e) {
e.printStackTrace();
}
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);
사용 예시
// 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"
)
// 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);
사용 예시
// 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)
// Track an event with JSON object
try {
JSONObject eventData = new JSONObject();
eventData.put("level_id", 5);
eventData.put("score", 12500);
eventData.put("time_spent", 120);
eventData.put("difficulty", "medium");
Singular.eventJSON("level_completed", eventData);
} catch (JSONException e) {
e.printStackTrace();
}
getGlobalProperties
Singular.getGlobalProperties 메서드
현재 설정된 모든 전역 속성을 가져옵니다. 이 메서드는 SDK에 설정된 모든 전역 속성을 포함하는 맵을 반환합니다.
시그니처
public static Map<String, String> getGlobalProperties();
사용 예시
// Get all global properties
val properties = Singular.getGlobalProperties()
println("Global properties: $properties")
// Get all global properties
Map<String, String> properties = Singular.getGlobalProperties();
System.out.println("Global properties: " + properties);
getLimitDataSharing
Singular.getLimitDataSharing 메서드
현재 데이터 공유 제한 상태를 가져옵니다. 이 메서드는 데이터 공유가 현재 제한되어 있는지 여부를 나타내는 부울 값을 반환합니다.
SDK가 초기화되지 않은 경우
SingularConfig.withLimitDataSharing을 통해 이전에 설정한 값과 무관하게
false를 반환합니다. 사용자가 옵트인했다는 증거가 아니라 컨텍스트에서
false를 확인하세요.
시그니처
public static boolean getLimitDataSharing();
사용 예시
// Check if data sharing is limited
val isLimited = Singular.getLimitDataSharing()
if (isLimited) {
println("Data sharing is currently limited")
}
// Check if data sharing is limited
boolean isLimited = Singular.getLimitDataSharing();
if (isLimited) {
System.out.println("Data sharing is currently limited");
}
getSessionId
Singular.getSessionId 메서드
현재 세션 ID를 반환합니다. 이를 통해 동일한 세션 내의 이벤트를 추적하고 상호 연관시킬 수 있습니다.
SDK가 초기화되지 않은 경우
Constants.INVALID를 반환합니다. 이 값을 사용하기 전에 항상
Singular.init()을 호출하세요.
시그니처
public static long getSessionId();
사용 예시
// Get the current session ID
val sessionId = Singular.getSessionId()
println("Current session ID: $sessionId")
// Get the current session ID
long sessionId = Singular.getSessionId();
System.out.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);
사용 예시
// 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)
// Simple initialization with API key and secret
Singular.init(context, "SDK KEY", "YOUR_SECRET");
// Initialize with configuration object
SingularConfig config = new SingularConfig("SDK KEY", "YOUR_SECRET")
.withCustomUserId("user_123456")
.withSessionTimeoutInSec(60);
Singular.init(context, config);
isAllTrackingStopped
Singular.isAllTrackingStopped 메서드
모든 트래킹이 현재 중지되어 있는지 확인합니다. 이 메서드는 트래킹이 현재 중지되었는지 여부를 나타내는 부울 값을 반환합니다.
SDK가 초기화되지 않은 경우
false를 반환합니다.
false를 "활발히 트래킹 중"이 아니라 "중지되지 않았거나 초기화되지 않음"으로 해석하세요.
시그니처
public static boolean isAllTrackingStopped();
사용 예시
// Check if tracking is stopped
if (Singular.isAllTrackingStopped()) {
println("Tracking is currently stopped")
}
// Check if tracking is stopped
if (Singular.isAllTrackingStopped()) {
System.out.println("Tracking is currently stopped");
}
limitDataSharing
Singular.limitDataSharing 메서드
데이터 공유 제한 상태를 설정합니다. 사용자 동의 또는 개인정보 보호 요구사항에 따라 데이터 공유를 제한하려면 이 메서드를 사용하세요.
시그니처
public static void limitDataSharing(boolean shouldLimitDataSharing);
사용 예시
// 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)
// 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();
사용 예시
override fun onPause() {
super.onPause()
Singular.onActivityPaused()
}
@Override
protected void onPause() {
super.onPause();
Singular.onActivityPaused();
}
onActivityResumed
Singular.onActivityResumed 메서드
액티비티가 재개될 때 SDK에 알립니다. 세션 라이프사이클을 추적하기 위해 액티비티의 onResume() 메서드에서 호출해야 합니다.
시그니처
public static void onActivityResumed();
사용 예시
override fun onResume() {
super.onResume()
Singular.onActivityResumed()
}
@Override
protected void onResume() {
super.onResume();
Singular.onActivityResumed();
}
resumeAllTracking
Singular.resumeAllTracking 메서드
이전에 중지된 모든 트래킹 활동을 재개합니다. 트래킹이 중지된 후 다시 활성화하려면 이 메서드를 사용하세요.
시그니처
public static void resumeAllTracking();
사용 예시
// Resume tracking when user opts back in
Singular.resumeAllTracking()
// 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);
사용 예시
// 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)
// Track revenue with currency and amount
Singular.revenue("USD", 9.99);
// Track revenue with additional attributes
Map<String, Object> attributes = new HashMap<>();
attributes.put("product_id", "premium_gems");
attributes.put("quantity", 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
try {
JSONObject revenueJson = new JSONObject();
revenueJson.put("currency", "USD");
revenueJson.put("amount", 9.99);
revenueJson.put("product_id", "premium_gems");
Singular.revenue(revenueJson);
} catch (JSONException e) {
e.printStackTrace();
}
setCustomUserId
Singular.setCustomUserId 메서드
현재 유저에 대한 사용자 지정 유저 ID를 설정합니다. 이를 통해 Singular 데이터를 자체 사용자 식별 시스템과 연결할 수 있습니다.
시그니처
public static void setCustomUserId(String customUserId);
사용 예시
// Set custom user ID after user logs in
Singular.setCustomUserId("user_123456")
// Set custom user ID after user logs in
Singular.setCustomUserId("user_123456");
setDeviceCustomUserId
지원 중단된 기능: setCustomUserId를 대신 사용하세요.
Singular.setDeviceCustomUserId 메서드
디바이스 레벨에서 사용자 지정 유저 ID를 설정합니다. 이를 통해 Singular 데이터를 디바이스 레벨에서 자체 사용자 식별 시스템과 연결할 수 있습니다.
시그니처
public static void setDeviceCustomUserId(String customUserId);
사용 예시
// Set device-level custom user ID
Singular.setDeviceCustomUserId("device_user_123456")
// 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);
사용 예시
// In your Firebase Messaging Service
override fun onNewToken(token: String) {
super.onNewToken(token)
Singular.setFCMDeviceToken(token)
}
// In your Firebase Messaging Service
@Override
public void onNewToken(String token) {
super.onNewToken(token);
Singular.setFCMDeviceToken(token);
}
setGCMDeviceToken
지원 중단된 기능: setFCMDeviceToken을 대신 사용하세요.
Singular.setGCMDeviceToken 메서드
GCM(Google Cloud Messaging) 디바이스 토큰을 설정합니다. 이 메서드는 지원이 중단되었습니다. Firebase Cloud Messaging의 경우 setFCMDeviceToken을 대신 사용하세요.
시그니처
public static void setGCMDeviceToken(String gcmDeviceToken);
사용 예시
// Deprecated - use setFCMDeviceToken instead
Singular.setGCMDeviceToken(token)
// 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);
사용 예시
// Set a global property
val success = Singular.setGlobalProperty("user_tier", "premium", true)
if (success) {
println("Global property set successfully")
}
// Set a global property
boolean success = Singular.setGlobalProperty("user_tier", "premium", true);
if (success) {
System.out.println("Global property set successfully");
}
setIMEI
Singular.setIMEI 메서드
트래킹용 디바이스 IMEI를 설정합니다. IMEI 트래킹이 허용되고 선호되는 지역에서 유용합니다.
시그니처
public static void setIMEI(String imei);
사용 예시
// Set device IMEI
Singular.setIMEI("123456789012345")
// Set device IMEI
Singular.setIMEI("123456789012345");
setLimitAdvertisingIdentifiers
Singular.setLimitAdvertisingIdentifiers 메서드
혼합 잠재고객 앱에서 광고 식별자 사용을 활성화하거나 비활성화합니다. 이 옵션은 SDK가 트래킹용 디바이스 식별자를 수집하고 사용하는 방식에 영향을 줍니다.
시그니처
public static void setLimitAdvertisingIdentifiers(boolean enabled);
사용 예시
// Enable limited identifiers mode
Singular.setLimitAdvertisingIdentifiers(true)
// Enable limited identifiers mode
Singular.setLimitAdvertisingIdentifiers(true);
setWrapperNameAndVersion
Singular.setWrapperNameAndVersion 메서드
래퍼(예: Unity, React Native)를 통해 SDK를 사용할 때 래퍼 이름과 버전을 설정합니다. 이는 어떤 래퍼 프레임워크가 사용되고 있는지 식별하는 데 도움이 됩니다.
시그니처
public static void setWrapperNameAndVersion(final String wrapper, final String version);
사용 예시
// Set wrapper information
Singular.setWrapperNameAndVersion("Unity", "1.2.3")
// Set wrapper information
Singular.setWrapperNameAndVersion("Unity", "1.2.3");
stopAllTracking
Singular.stopAllTracking 메서드
모든 트래킹 활동을 중지합니다. 사용자가 옵트아웃하거나 개인정보 보호 규정 준수를 위해 트래킹을 비활성화하려면 이 메서드를 사용하세요.
시그니처
public static void stopAllTracking();
사용 예시
// Stop tracking when user opts out
Singular.stopAllTracking()
// Stop tracking when user opts out
Singular.stopAllTracking();
trackingOptIn
Singular.trackingOptIn 메서드
사용자가 트래킹에 옵트인했음을 나타냅니다. 사용자가 트래킹 및 데이터 수집에 명시적으로 동의했을 때 이 메서드를 호출하세요.
시그니처
public static void trackingOptIn();
사용 예시
// User has opted in to tracking
Singular.trackingOptIn()
// User has opted in to tracking
Singular.trackingOptIn();
trackingUnder13
Singular.trackingUnder13 메서드
유저가 13세 미만임을 나타냅니다. 13세 미만 유저에 대한 COPPA 및 기타 규정을 준수하려면 이 메서드를 호출하세요.
시그니처
public static void trackingUnder13();
사용 예시
// Notify Singular the user is under 13 years old
Singular.trackingUnder13()
// Notify Singular the user is under 13 years old
Singular.trackingUnder13();
unsetCustomUserId
Singular.unsetCustomUserId 메서드
이전에 설정된 사용자 지정 유저 ID를 제거합니다. 유저가 로그아웃하거나 현재 유저 ID와 이벤트를 더 이상 연결하지 않으려는 경우 이 메서드를 호출하세요.
시그니처
public static void unsetCustomUserId();
사용 예시
// Clear custom user ID when user logs out
Singular.unsetCustomUserId()
// Clear custom user ID when user logs out
Singular.unsetCustomUserId();
unsetGlobalProperty
Singular.unsetGlobalProperty 메서드
이전에 설정된 전역 속성을 제거합니다. 특정 전역 속성이 더 이상 이벤트와 함께 전송되는 것을 원치 않을 때 이 메서드를 호출하세요.
시그니처
public static void unsetGlobalProperty(String key);
사용 예시
// Remove a global property
Singular.unsetGlobalProperty("user_tier")
// Remove a global property
Singular.unsetGlobalProperty("user_tier");