Android SDK - Configuration Methods Reference

The Singular SDK provides a flexible configuration system through the SingularConfig class. This document outlines all available configuration options and how to use them when initializing the SDK.

withCustomSdid

SingularConfig.withCustomSdid Method

Enterprise Feature: Sets a custom Singular Device ID (SDID) and a handler to access it.

Signature

public SingularConfig withCustomSdid(String customSdid, SDIDAccessorHandler accessorHandler)

Usage Example

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withCustomSdid("custom-device-id-12345", new SDIDAccessorHandler() {
        @Override
        public void onSDIDAccessed(String sdid) {
            // Handle SDID access
            Log.d("Singular", "SDID accessed: " + sdid);
        }
    });

withCustomUserId

SingularConfig.withCustomUserId Method

Sets a custom user ID during initialization.

Signature

public SingularConfig withCustomUserId(String customUserId)

Usage Example

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withCustomUserId("user_12345");

withDDLHandler

SingularConfig.withDDLHandler Method

Sets a handler for deferred deep links.

Signature

public SingularConfig withDDLHandler(DeferredDeepLinkHandler handler)

Usage Example

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withDDLHandler(new DeferredDeepLinkHandler() {
        @Override
        public void onResolved(String resolvedLink) {
            if (resolvedLink != null) {
                // Handle the deferred deep link
                Log.d("Singular", "Deferred deep link: " + resolvedLink);
            }
        }
    });

withDDLTimeoutInSec

SingularConfig.withDDLTimeoutInSec Method

Sets the timeout for deferred deep link resolution in seconds.

Signature

public SingularConfig withDDLTimeoutInSec(long timeout)

Usage Example

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withDDLHandler(deferredDeepLinkHandler)
    .withDDLTimeoutInSec(10); // 10 seconds timeout

withESPDomains

SingularConfig.withESPDomains Method

Sets a list of ESP (Email Service Provider) domains for handling attribution from email campaigns.

Signature

public SingularConfig withESPDomains(List espDomains)

Usage Example

List<String> espDomains = new ArrayList<>();
espDomains.add("email.example.com");
espDomains.add("newsletter.example.com");

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withESPDomains(espDomains);

withFacebookAppId

SingularConfig.withFacebookAppId Method

Sets the Facebook App ID for Facebook attribution.

Signature

public SingularConfig withFacebookAppId(String facebookAppId)

Usage Example

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withFacebookAppId("123456789012345");

withFCMDeviceToken

SingularConfig.withFCMDeviceToken Method

Sets the Firebase Cloud Messaging device token during initialization.

Signature

public SingularConfig withFCMDeviceToken(String fcmDeviceToken)

Usage Example

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withFCMDeviceToken("eKh2BNP-Txy4XrjDGmw...");

withGlobalProperty

SingularConfig.withGlobalProperty Method

Sets a global property during initialization that will be included with all events.

Signature

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

Usage Example

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withGlobalProperty("app_version", "2.1.0", true)
    .withGlobalProperty("user_type", "free", true);

withIMEI

SingularConfig.withIMEI Method

Sets the device IMEI for tracking during initialization.

Signature

public SingularConfig withIMEI(String imei)

Usage Example

// Note: Requires READ_PHONE_STATE permission
String imei = null;
if (ContextCompat.checkSelfPermission(this, Manifest.permission.READ_PHONE_STATE) 
        == PackageManager.PERMISSION_GRANTED) {
    TelephonyManager telephonyManager = (TelephonyManager) getSystemService(Context.TELEPHONY_SERVICE);
    imei = telephonyManager.getDeviceId();
}

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withIMEI(imei);

withLimitAdvertisingIdentifiers

SingularConfig.withLimitAdvertisingIdentifiers Method

Limits the use of advertising identifiers during initialization.

Signature

public SingularConfig withLimitAdvertisingIdentifiers()

Usage Example

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withLimitAdvertisingIdentifiers();

withLimitDataSharing

SingularConfig.withLimitDataSharing Method

Controls whether to limit data sharing with partners and networks during initialization.

Signature

public SingularConfig withLimitDataSharing(boolean shouldLimitDataSharing)

Usage Example

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withLimitDataSharing(true);

withLogLevel

SingularConfig.withLogLevel Method

Sets the log level for SDK logs.

Signature

public SingularConfig withLogLevel(int level)

Usage Example

import android.util.Log;

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withLoggingEnabled()
    .withLogLevel(Log.VERBOSE); // Use Log.VERBOSE, Log.DEBUG, Log.INFO, Log.WARN, Log.ERROR

withLoggingEnabled

SingularConfig.withLoggingEnabled Method

Enables logging for the SDK.

Signature

public SingularConfig withLoggingEnabled()

Usage Example

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withLoggingEnabled();

withOAIDCollection

SingularConfig.withOAIDCollection Method

Enables collection of OAID (Open Anonymous Device Identifier) for Chinese devices.

Signature

public SingularConfig withOAIDCollection()

Usage Example

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withOAIDCollection();

withOpenURI

SingularConfig.withOpenURI Method

Sets the URI that opened the app for attribution.

Signature

public SingularConfig withOpenURI(Uri openUri)

Usage Example

// In your Activity's onCreate method
Uri data = getIntent().getData();
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withOpenURI(data);

withPushNotificationPayload

SingularConfig.withPushNotificationPayload Method

Sets the push notification payload and path to extract deep link from the payload.

Signature

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

Usage Example

// In your Activity that handles push notifications
Intent intent = getIntent();
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withPushNotificationPayload(intent, new String[]{"singular_link"}, new String[]{"data", "deeplink"});

withSdidAccessorHandler

SingularConfig.withSdidAccessorHandler Method

Enterprise Feature: Sets a handler to access the Singular Device ID (SDID).

Signature

public SingularConfig withSdidAccessorHandler(SDIDAccessorHandler accessorHandler)

Usage Example

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withSdidAccessorHandler(new SDIDAccessorHandler() {
        @Override
        public void onSDIDAccessed(String sdid) {
            // Handle SDID access
            Log.d("Singular", "SDID accessed: " + sdid);
        }
    });

withSessionTimeoutInSec

SingularConfig.withSessionTimeoutInSec Method

Sets the session timeout in seconds.

Signature

public SingularConfig withSessionTimeoutInSec(long timeout)

Usage Example

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withSessionTimeoutInSec(60); // 60 seconds timeout

withSingularDeviceAttribution

SingularConfig.withSingularDeviceAttribution Method

BETA Feature: Sets a handler function to receive device attribution data when it becomes available.

Signature

public SingularConfig withSingularDeviceAttribution(SingularDeviceAttributionHandler handler)

Usage Example

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withSingularDeviceAttribution(new SingularDeviceAttributionHandler() {
        @Override
        public void onDeviceAttributionInfoReceived(Map deviceAttributionData) {
            // Handle device attribution data
            if (deviceAttributionData != null) {
                for (Object key : deviceAttributionData.keySet()) {
                    Log.d("Singular", key + ": " + deviceAttributionData.get(key));
                }
            }
        }
    });

withSingularLink

SingularConfig.withSingularLink Method

Sets up Singular Links handling with a callback for resolved links.

Signature

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

Usage Example

// In your Activity's onCreate method
Intent intent = getIntent();
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withSingularLink(intent, new SingularLinkHandler() {
        @Override
        public void onResolved(SingularLinkParams params) {
            if (params != null) {
                // Handle the deep link
                String deeplink = params.getDeeplink();
                if (deeplink != null) {
                    Log.d("Singular", "Deep link: " + deeplink);
                    // Navigate to the appropriate screen
                }
                
                // Get passthrough parameters
                String passthrough = params.getPassthrough();
                if (passthrough != null) {
                    Log.d("Singular", "Passthrough: " + passthrough);
                }
                
                // Check if this is a deferred deep link
                boolean isDeferred = params.isDeferred();
                Log.d("Singular", "Is deferred: " + isDeferred);
            }
        }
    }, 10); // 10 seconds timeout

Complete Configuration Example

Chaining Multiple Configuration Options

Here's a complete example showing how to chain multiple configuration options together when initializing the Singular SDK.

Usage Example

import android.app.Activity;
import android.content.Intent;
import android.net.Uri;
import android.os.Bundle;
import android.util.Log;

import com.singular.sdk.Singular;
import com.singular.sdk.SingularConfig;
import com.singular.sdk.SingularLinkHandler;
import com.singular.sdk.SingularLinkParams;
import com.singular.sdk.SingularDeviceAttributionHandler;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;

public class MainActivity extends Activity {
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        
        // Get the intent that started this activity
        Intent intent = getIntent();
        
        // Initialize Singular SDK with advanced configuration
        SingularConfig config = new SingularConfig("YOUR_API_KEY", "YOUR_SECRET")
            // Enable logging for debugging
            .withLoggingEnabled()
            .withLogLevel(Log.DEBUG)
            
            // Set custom user ID if available
            .withCustomUserId("user_12345")
            
            // Configure session timeout
            .withSessionTimeoutInSec(60)
            
            // Set global properties for all events
            .withGlobalProperty("app_version", "2.1.0", true)
            .withGlobalProperty("user_type", "premium", true)
            
            // Handle deep links
            .withSingularLink(intent, new SingularLinkHandler() {
                @Override
                public void onResolved(SingularLinkParams params) {
                    if (params != null) {
                        String deeplink = params.getDeeplink();
                        if (deeplink != null) {
                            Log.d("Singular", "Deep link: " + deeplink);
                            // Navigate based on deep link
                        }
                    }
                }
            }, 10)
            
            // Handle deferred deep links
            .withDDLHandler(new DeferredDeepLinkHandler() {
                @Override
                public void onResolved(String resolvedLink) {
                    if (resolvedLink != null) {
                        Log.d("Singular", "Deferred deep link: " + resolvedLink);
                        // Handle deferred deep link
                    }
                }
            })
            .withDDLTimeoutInSec(5)
            
            // Get device attribution data
            .withSingularDeviceAttribution(new SingularDeviceAttributionHandler() {
                @Override
                public void onDeviceAttributionInfoReceived(Map deviceAttributionData) {
                    if (deviceAttributionData != null) {
                        for (Object key : deviceAttributionData.keySet()) {
                            Log.d("Singular", key + ": " + deviceAttributionData.get(key));
                        }
                    }
                }
            })
            
            // Facebook attribution
            .withFacebookAppId("123456789012345")
            
            // Configure data sharing limitations for privacy
            .withLimitDataSharing(true)
            .withLimitAdvertisingIdentifiers();
        
        // Initialize the SDK with the configuration
        Singular.init(this, config);
    }
    
    @Override
    protected void onResume() {
        super.onResume();
        Singular.onActivityResumed();
    }
    
    @Override
    protected void onPause() {
        super.onPause();
        Singular.onActivityPaused();
    }
}