Android SDK - Configuration Reference

This document provides a comprehensive reference for all configuration options available in the Singular SDK for Android applications. The SingularConfig object allows you to customize the SDK's behavior, including tracking settings, attribution options, privacy controls, and more. Each configuration method is presented with a description, signature, and practical usage examples.

Complete Configuration Example

Comprehensive SDK Configuration

The following example demonstrates how to create a comprehensive configuration by chaining multiple configuration methods together.

Complete Example

// 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")

// Initialize the SDK
Singular.init(context, config)

// 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");

// Initialize the SDK
Singular.init(context, config);

Constructor

SingularConfig Constructor

Initializes a new SingularConfig object with your API key and secret. This is the first step in configuring the Singular SDK.

Signature

public SingularConfig(String apiKey, String secret);

Usage Example

// Create configuration object
val config = SingularConfig("SDK KEY", "YOUR_SECRET")

// Create configuration object
SingularConfig config = new SingularConfig("SDK KEY", "YOUR_SECRET");

withBrandedDomains

SingularConfig.withBrandedDomains Method

Sets branded domains for web-to-app attribution. This allows you to specify custom domains that should be tracked for attribution purposes.

Calling this method replaces any previously set branded domains. Pass the complete list in a single call rather than chaining multiple calls.

Signature

public SingularConfig withBrandedDomains(List<String> brandedDomains);

Usage Example

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

Enterprise Feature: Sets a custom SDID (Singular Device ID). This allows you to provide your own device identifier instead of using the one generated by Singular.

Signature

public SingularConfig withCustomSdid(String customSdid, SDIDAccessorHandler accessorHandler);

Usage Example

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

Sets a custom user ID during SDK initialization. This allows you to associate Singular data with your own user identification system from the start.

Signature

public SingularConfig withCustomUserId(String customUserId);

Usage Example

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

Sets the ESP (Email Service Provider) domains for email attribution. This allows you to specify which email domains should be considered for attribution.

Calling this method replaces any previously set ESP domains. Pass the complete list in a single call rather than chaining multiple calls.

Signature

public SingularConfig withESPDomains(List<String> espDomains);

Usage Example

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

Sets the Facebook App ID for Facebook attribution integration. This enables the SDK to track Facebook campaign attribution.

Signature

public SingularConfig withFacebookAppId(String facebookAppId);

Usage Example

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

Sets the FCM (Firebase Cloud Messaging) device token at initialization. This enables push notification tracking and uninstall detection from the start.

The call is ignored if the token is null or empty. Only invoke this method once you have a valid FCM token.

Signature

public SingularConfig withFCMDeviceToken(String fcmDeviceToken);

Usage Example

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

Sets a global property during SDK initialization. This property will be sent with all events tracked by the SDK. This is a configuration method that allows for chained configuration.

The SDK supports a maximum of 5 global properties. Additional calls beyond this limit are silently ignored.

Signature

public SingularConfig withGlobalProperty(String key, String value, boolean overrideExisting);

Usage Example

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

Sets the device IMEI for tracking at initialization. This is useful in regions where IMEI tracking is allowed and preferred.

Signature

public SingularConfig withIMEI(String imei);

Usage Example

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

Enables limited advertising identifiers mode in mixed audience apps. This option affects how the SDK collects and uses device identifiers for tracking.

Signature

public SingularConfig withLimitAdvertisingIdentifiers();

Usage Example

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

Sets the data sharing limitation status at initialization. Use this method to limit data sharing based on user consent or privacy requirements.

Signature

public SingularConfig withLimitDataSharing(boolean shouldLimitDataSharing);

Usage Example

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

Sets the log level for SDK logging. Available levels are:

NONE = -1
VERBOSE = Log.VERBOSE (Android constant, numeric value 2)
DEBUG = Log.DEBUG (3)
INFO = Log.INFO (4)
WARNING = Log.WARN (5)
ERROR = Log.ERROR (6)

The default log level is Log.ERROR. Logging must also be enabled via withLoggingEnabled() for any output to be emitted.

Signature

public SingularConfig withLogLevel(int level);

Usage Example

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 Method

Enables SDK logging. This is useful for debugging and troubleshooting during development. It's recommended to disable logging in production builds.

Signature

public SingularConfig withLoggingEnabled();

Usage Example

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

Enables OAID (Open Anonymous Device Identifier) collection. This is primarily used for tracking in China where Google Play Services are not available.

Signature

public SingularConfig withOAIDCollection();

Usage Example

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

Sets the URI that opened the app. This is used for deep link attribution and should be set when the app is opened via a deep link.

Signature

public SingularConfig withOpenURI(Uri openUri);

Usage Example

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

Sets the push notification payload for attribution. This allows the SDK to process push notification data during initialization.

Signature

public SingularConfig withPushNotificationPayload(Intent intent, String[] ... pushNotificationLinkPath);

Usage Example

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

Enterprise Feature: Sets a callback function to be called when the SDID (Singular Device ID) is received. This allows you to access the SDID as soon as it's available.

Signature

public SingularConfig withSdidAccessorHandler(SDIDAccessorHandler accessorHandler);

Usage Example

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

Sets the session timeout in seconds. This determines how long a user session lasts after the app goes to the background. Default value is 60 seconds.

Signature

public SingularConfig withSessionTimeoutInSec(long timeout);

Usage Example

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

BETA Feature: Sets a callback function to be invoked when device attribution data is available from the /start response. The callback is fired on a background thread, so dispatch any UI work to the main thread.

Key	Type	Notes
`network`	String	Attribution source. "organic" for non-attributed installs.
`campaign_id`	String	Present only when attributed.
`campaign_name`	String	Present only when attributed.
`click_timestamp`	Long (epoch microseconds)	Present only when attributed. Divide by 1,000,000 for seconds.

The callback is only invoked when the /start response contains an attribution_info object. For organic installs, only network is populated.

Signature

public SingularConfig withSingularDeviceAttribution(SingularDeviceAttributionHandler handler);

Usage Example

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

Configures Singular Links (deep links) for attribution. This method sets up the handler for processing deep links and the timeout for short link resolution.

When the shortlinkTimeoutSec argument is omitted, the SDK uses a default of 10 seconds. When the intent action is ACTION_VIEW, the SDK also marks the session as opened with a deep link.

Signatures

public SingularConfig withSingularLink(Intent intent, SingularLinkHandler handler);

public SingularConfig withSingularLink(Intent intent, SingularLinkHandler handler, 
                                       long shortlinkTimeoutSec);

Usage Example

// 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);

Android SDK - Configuration Methods Reference

Android SDK - Configuration Reference

Complete Configuration Example

Comprehensive SDK Configuration

Complete Example

Constructor

SingularConfig Constructor

Signature

Usage Example

withBrandedDomains

SingularConfig.withBrandedDomains Method

Signature

Usage Example

withCustomSdid

SingularConfig.withCustomSdid Method

Signature

Usage Example

withCustomUserId

SingularConfig.withCustomUserId Method

Signature

Usage Example

withESPDomains

SingularConfig.withESPDomains Method

Signature

Usage Example

withFacebookAppId

SingularConfig.withFacebookAppId Method

Signature

Usage Example

withFCMDeviceToken

SingularConfig.withFCMDeviceToken Method

Signature

Usage Example

withGlobalProperty

SingularConfig.withGlobalProperty Method

Signature

Usage Example

withIMEI

SingularConfig.withIMEI Method

Signature

Usage Example

withLimitAdvertisingIdentifiers

SingularConfig.withLimitAdvertisingIdentifiers Method

Signature

Usage Example

withLimitDataSharing

SingularConfig.withLimitDataSharing Method

Signature

Usage Example

withLogLevel

SingularConfig.withLogLevel Method

Signature

Usage Example

withLoggingEnabled

SingularConfig.withLoggingEnabled Method

Signature

Usage Example

withOAIDCollection

SingularConfig.withOAIDCollection Method

Signature

Usage Example

withOpenURI

SingularConfig.withOpenURI Method

Signature

Usage Example

withPushNotificationPayload

SingularConfig.withPushNotificationPayload Method

Signature

Usage Example

withSdidAccessorHandler

SingularConfig.withSdidAccessorHandler Method

Signature

Usage Example

withSessionTimeoutInSec

SingularConfig.withSessionTimeoutInSec Method

Signature

Usage Example

withSingularDeviceAttribution

SingularConfig.withSingularDeviceAttribution Method

Signature