Android SDK - Methods Reference

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

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

Kotlin Java
// 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

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

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

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

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

Kotlin Java
// Get all global properties
val properties = Singular.getGlobalProperties()
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

Kotlin Java
// Check if data sharing is limited
val isLimited = Singular.getLimitDataSharing()
if (isLimited) {
    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

Kotlin Java
// Get the current session ID
val sessionId = Singular.getSessionId()
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

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

Kotlin Java
// Check if tracking is stopped
if (Singular.isAllTrackingStopped()) {
    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

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

Kotlin Java
override fun 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

Kotlin Java
override fun 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

Kotlin Java
// 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

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

Kotlin Java
// 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

Kotlin Java
// 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

Kotlin Java
// In your Firebase Messaging Service
override fun onNewToken(token: String) {
    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

Kotlin Java
// 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

Kotlin Java
// Set a global property
val success = Singular.setGlobalProperty("user_tier", "premium", true)
if (success) {
    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

Kotlin Java
// 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

Kotlin Java
// 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

Kotlin Java
// 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

Kotlin Java
// 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

Kotlin Java
// 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

Kotlin Java
// 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

Kotlin Java
// 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

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