Android SDK - Methods Reference
This comprehensive reference documents all available methods in the Singular SDK for Android applications. The SDK provides functionality for initialization, event tracking, revenue reporting, attribution, data privacy compliance, and configuration. Each method is presented with a description, signature, and practical usage examples to help developers integrate Singular's SDK capabilities into their applications.
adRevenue
Singular.adRevenue Method
Tracks ad revenue events with detailed ad data information. This method allows you to report revenue generated from ads displayed in your application.
Signature
public static void adRevenue(SingularAdData adData);
Usage Example
// 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 Method
Removes all previously set global properties. This is useful when you need to reset the global properties, for example when a user logs out of your application.
Signature
public static void clearGlobalProperties();
Usage Example
// Clear all global properties
Singular.clearGlobalProperties()
// Clear all global properties
Singular.clearGlobalProperties();
createReferrerShortLink
Singular.createReferrerShortLink Method
Creates a short link with referrer information that can be used for sharing and attribution. This method generates trackable links that can be shared with users, allowing you to attribute installs and activities to specific referral sources.
Signature
public static void createReferrerShortLink(String baseLink, String referrerName, String referrerId,
JSONObject passthroughParams, ShortLinkHandler shortLinkHandler);
Usage Example
// 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 Methods
Tracks custom revenue events with a specified event name, currency, amount, and optional product information. This allows for more specific revenue tracking with custom event names.
When passing a
purchase object, the SDK only extracts
receipt, signature, and SKU details if it is a
com.android.billingclient.api.Purchase
instance. Other types fall back to a basic revenue event with only
currency and amount.
Signatures
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);
Usage Example
// 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 Methods
Tracks events with the specified name and optional custom attributes. Use these methods to track user actions and engagement within your application.
The varargs overload expects key/value pairs, so
args must contain an even number of
elements. An odd count causes the call to return
false without sending the event.
Signatures
public static boolean event(String name);
public static boolean event(String name, String extra);
public static boolean event(String name, Object... args);
Usage Example
// 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 Method
Tracks events with a JSON object containing custom attributes. This method provides more flexibility for complex event data structures.
Signature
public static boolean eventJSON(String name, final JSONObject json);
Usage Example
// 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 Method
Retrieves all currently set global properties. This method returns a map containing all global properties that have been set for the SDK.
Signature
public static Map<String, String> getGlobalProperties();
Usage Example
// 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 Method
Retrieves the current data sharing limitation status. This method returns a boolean indicating whether data sharing is currently limited.
Returns
false if the SDK has not been
initialized, regardless of any value previously set via
SingularConfig.withLimitDataSharing.
Always check
false in context, not as proof that
the user opted in.
Signature
public static boolean getLimitDataSharing();
Usage Example
// 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 Method
Returns the current session ID. This can be used to track and correlate events within the same session.
Returns
Constants.INVALID if the SDK has not
been initialized. Always call
Singular.init() before relying on this
value.
Signature
public static long getSessionId();
Usage Example
// 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 Method
Initializes the Singular SDK with the provided API key and secret, or with a configuration object. This is the first method you should call to start using the Singular SDK.
Signatures
public static boolean init(final Context context, final String apiKey, final String secret);
public static boolean init(final Context context, final SingularConfig config);
Usage Example
// 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 Method
Checks if all tracking is currently stopped. This method returns a boolean indicating whether tracking is currently stopped.
Returns
false if the SDK has not been
initialized. Treat
false as "not stopped or not
initialized" rather than "actively tracking."
Signature
public static boolean isAllTrackingStopped();
Usage Example
// 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 Method
Sets the data sharing limitation status. Use this method to limit data sharing based on user consent or privacy requirements.
Signature
public static void limitDataSharing(boolean shouldLimitDataSharing);
Usage Example
// 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 Method
Notifies the SDK when an activity is paused. This should be called from the onPause() method of your activities to track session lifecycle.
Signature
public static void onActivityPaused();
Usage Example
override fun onPause() {
super.onPause()
Singular.onActivityPaused()
}
@Override
protected void onPause() {
super.onPause();
Singular.onActivityPaused();
}
onActivityResumed
Singular.onActivityResumed Method
Notifies the SDK when an activity is resumed. This should be called from the onResume() method of your activities to track session lifecycle.
Signature
public static void onActivityResumed();
Usage Example
override fun onResume() {
super.onResume()
Singular.onActivityResumed()
}
@Override
protected void onResume() {
super.onResume();
Singular.onActivityResumed();
}
resumeAllTracking
Singular.resumeAllTracking Method
Resumes all tracking activities that were previously stopped. Use this method to re-enable tracking after it has been stopped.
Signature
public static void resumeAllTracking();
Usage Example
// Resume tracking when user opts back in
Singular.resumeAllTracking()
// Resume tracking when user opts back in
Singular.resumeAllTracking();
revenue
Singular.revenue Methods
Tracks revenue events with various parameters including currency, amount, and product details. This allows comprehensive revenue tracking for your application.
When passing a
purchase object, the SDK only extracts
receipt, signature, and SKU details if it is a
com.android.billingclient.api.Purchase
instance. Other types fall back to a basic revenue event with only
currency and amount.
Signatures
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);
Usage Example
// 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 Method
Sets a custom user ID for the current user. This allows you to associate Singular data with your own user identification system.
Signature
public static void setCustomUserId(String customUserId);
Usage Example
// 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
Deprecated feature: Use setCustomUserId instead.
Singular.setDeviceCustomUserId Method
Sets a custom user ID at the device level. This allows you to associate Singular data with your own user identification system at the device level.
Signature
public static void setDeviceCustomUserId(String customUserId);
Usage Example
// 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 Method
Sets the FCM (Firebase Cloud Messaging) device token for push notifications and uninstall tracking. This should be called when you receive the FCM token.
Signature
public static void setFCMDeviceToken(String fcmDeviceToken);
Usage Example
// 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
Deprecated feature: Use setFCMDeviceToken instead.
Singular.setGCMDeviceToken Method
Sets the GCM (Google Cloud Messaging) device token. This method is deprecated; use setFCMDeviceToken instead for Firebase Cloud Messaging.
Signature
public static void setGCMDeviceToken(String gcmDeviceToken);
Usage Example
// Deprecated - use setFCMDeviceToken instead
Singular.setGCMDeviceToken(token)
// Deprecated - use setFCMDeviceToken instead
Singular.setGCMDeviceToken(token);
setGlobalProperty
Singular.setGlobalProperty Method
Sets a global property that will be sent with all events. This allows you to add consistent attributes to all events without specifying them each time.
Returns
false if the key is null or empty,
if the SDK is not initialized, or if the SDK already holds the maximum
of 5 global properties. Inspect the return value before assuming the
property was stored.
Signature
public static boolean setGlobalProperty(final String key, final String value,
final boolean overrideExisting);
Usage Example
// 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 Method
Sets the device IMEI for tracking. This is useful in regions where IMEI tracking is allowed and preferred.
Signature
public static void setIMEI(String imei);
Usage Example
// Set device IMEI
Singular.setIMEI("123456789012345")
// Set device IMEI
Singular.setIMEI("123456789012345");
setLimitAdvertisingIdentifiers
Singular.setLimitAdvertisingIdentifiers Method
Enables or disables the use of advertising identifiers in mixed audience apps. This option affects how the SDK collects and uses device identifiers for tracking.
Signature
public static void setLimitAdvertisingIdentifiers(boolean enabled);
Usage Example
// Enable limited identifiers mode
Singular.setLimitAdvertisingIdentifiers(true)
// Enable limited identifiers mode
Singular.setLimitAdvertisingIdentifiers(true);
setWrapperNameAndVersion
Singular.setWrapperNameAndVersion Method
Sets the wrapper name and version when using the SDK through a wrapper (e.g., Unity, React Native). This helps identify which wrapper framework is being used.
Signature
public static void setWrapperNameAndVersion(final String wrapper, final String version);
Usage Example
// Set wrapper information
Singular.setWrapperNameAndVersion("Unity", "1.2.3")
// Set wrapper information
Singular.setWrapperNameAndVersion("Unity", "1.2.3");
stopAllTracking
Singular.stopAllTracking Method
Stops all tracking activities. Use this method to disable tracking when users opt out or for privacy compliance.
Signature
public static void stopAllTracking();
Usage Example
// Stop tracking when user opts out
Singular.stopAllTracking()
// Stop tracking when user opts out
Singular.stopAllTracking();
trackingOptIn
Singular.trackingOptIn Method
Indicates that the user has opted in to tracking. Call this method when the user explicitly consents to tracking and data collection.
Signature
public static void trackingOptIn();
Usage Example
// User has opted in to tracking
Singular.trackingOptIn()
// User has opted in to tracking
Singular.trackingOptIn();
trackingUnder13
Singular.trackingUnder13 Method
Indicates that the user is under 13 years old. Call this method to comply with COPPA and other regulations for users under 13 years old.
Signature
public static void trackingUnder13();
Usage Example
// 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 Method
Removes the previously set custom user ID. Call this method when the user logs out or when you no longer want to associate events with the current user ID.
Signature
public static void unsetCustomUserId();
Usage Example
// Clear custom user ID when user logs out
Singular.unsetCustomUserId()
// Clear custom user ID when user logs out
Singular.unsetCustomUserId();
unsetGlobalProperty
Singular.unsetGlobalProperty Method
Removes a previously set global property. Call this method when you no longer want a specific global property to be sent with events.
Signature
public static void unsetGlobalProperty(String key);
Usage Example
// Remove a global property
Singular.unsetGlobalProperty("user_tier")
// Remove a global property
Singular.unsetGlobalProperty("user_tier");