React Native SDK - Configuration Methods Reference

Follow
Avatar
Jared Ornstead
Updated

React Native SDK Configuration Methods Reference

This reference documents the configuration methods available in the SingularConfig class. These methods use a builder pattern to create a configuration object for initializing the Singular SDK. Each method returns the SingularConfig object itself, allowing for method chaining.

withClipboardAttribution

SingularConfig.withClipboardAttribution Method

Enables clipboard-based attribution for improved tracking when deep linking is not available.

Signature

withClipboardAttribution(): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withClipboardAttribution();

withConversionValueUpdatedHandler

SingularConfig.withConversionValueUpdatedHandler Method

Sets a handler function to be called when the SKAdNetwork conversion value is updated (iOS 14+ only).

Signature

withConversionValueUpdatedHandler(handler: (value: number) => void): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withConversionValueUpdatedHandler((value) => { 
        console.log("Conversion value updated to:", value); 
        // Perform actions based on the new conversion value 
});

withConversionValuesUpdatedHandler

SingularConfig.withConversionValuesUpdatedHandler Method

Sets a handler function to be called when the SKAdNetwork 4.0 conversion values are updated (iOS 16.1+ only).

Signature

withConversionValuesUpdatedHandler(handler: (fineValue: number, coarseValue: number, lockWindow: boolean) => void): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withConversionValuesUpdatedHandler((fineValue, coarseValue, lockWindow) => { 
        console.log("Fine value:", fineValue); 
        console.log("Coarse value:", coarseValue); 
        console.log("Lock window:", lockWindow); 
        // Handle updated conversion values 
});

withCustomSdid

SingularConfig.withCustomSdid Method

Enterprise Feature: Sets a custom SDID (Singular Device ID) with callback handlers for when the ID is set and received.

Signature

withCustomSdid(customSdid: string, didSetSdidCallback: (result: string) => void, sdidReceivedCallback: (result: string) => void): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withCustomSdid(
        "custom-device-id-12345", 
        (result) => { console.log("SDID set result:", result); }, 
        (result) => { console.log("SDID received:", result); });

withCustomUserId

SingularConfig.withCustomUserId Method

Sets a custom user identifier for the current user session.

Signature

withCustomUserId(customUserId: string): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withCustomUserId("user_123456");

withDeviceAttributionCallbackHandler

SingularConfig.withDeviceAttributionCallbackHandler Method

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

Signature

withDeviceAttributionCallbackHandler(deviceAttributionCallbackHandler: (attributes: Map<string, any>) => void): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withDeviceAttributionCallbackHandler((attributes) => {
        // Process attribution data 
        console.log("Attributes:", JSON.stringify(Object.fromEntries(attributes)));
        
        // Use attribution data to customize user experience
        if (attributes.get("source") === "facebook") {
          // Show Facebook-specific welcome message
        }
});

withEspDomains

SingularConfig.withEspDomains Method

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

Signature

withEspDomains(domains: [string]): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withEspDomains([ "mailchimp.com", "sendgrid.net", "klaviyo.com" ]);

withFacebookAppId

SingularConfig.withFacebookAppId Method

Sets the Facebook App ID for improved attribution with Facebook campaigns.

Signature

withFacebookAppId(appId: string): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withFacebookAppId("123456789012345");

withGlobalProperty

SingularConfig.withGlobalProperty Method

Sets a global property that will be included with all events sent to Singular.

Signature

withGlobalProperty(key: string, value: string, overrideExisting: boolean): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withGlobalProperty("app_version", "1.2.3", true)
     .withGlobalProperty("user_tier", "premium", false);

withLimitDataSharing

SingularConfig.withLimitDataSharing Method

Configures data sharing limitations for privacy compliance (e.g., CCPA).

Signature

withLimitDataSharing(shouldLimitDataSharing: boolean): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withLimitDataSharing(true);

withLimitedIdentifiersEnabled

SingularConfig.withLimitedIdentifiersEnabled Method

Enables or disables the use of limited identifiers for privacy-focused attribution.

Signature

withLimitedIdentifiersEnabled(limitedIdentifiersEnabled: boolean): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withLimitedIdentifiersEnabled(true);

withLogLevel

SingularConfig.withLogLevel Method

Sets the logging level for the Singular SDK.

Signature

withLogLevel(level: number): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withLogLevel(3);

withLoggingEnabled

SingularConfig.withLoggingEnabled Method

Enables detailed logging for debugging purposes.

Signature

withLoggingEnabled(): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withLoggingEnabled();

withManualSkanConversionManagement

SingularConfig.withManualSkanConversionManagement Method

Enables manual management of SKAdNetwork conversions (iOS only).

Signature

withManualSkanConversionManagement(): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withManualSkanConversionManagement();

withOAIDCollection

SingularConfig.withOAIDCollection Method

Enables collection of OAID for attribution on Chinese Android devices.

Signature

withOAIDCollection(): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withOAIDCollection();

withPushNotificationsLinkPaths

SingularConfig.withPushNotificationsLinkPaths Method

Configures the paths in push notification payloads where Singular links may be found.

Signature

withPushNotificationsLinkPaths(pushNotificationsLinkPaths: [[string]]): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withPushNotificationsLinkPaths([ 
        ["data", "singular_link"], 
        ["custom", "tracking_url"] 
        ]);

withSessionTimeoutInSec

SingularConfig.withSessionTimeoutInSec Method

Sets the session timeout duration in seconds.

Signature

withSessionTimeoutInSec(sessionTimeout: number): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withSessionTimeoutInSec(60);

withShortLinkResolveTimeout

SingularConfig.withShortLinkResolveTimeout Method

Sets the timeout in seconds for resolving short links.

Signature

withShortLinkResolveTimeout(shortLinkResolveTimeout: number): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withShortLinkResolveTimeout(10);

withSingularLink

SingularConfig.withSingularLink Method

Configures a handler for processing Singular deep links when users open the app through a tracking link.

Signature

withSingularLink(handler: (params: SingularLinkParams) => void): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withSingularLink(singularLinkParams => { 
          const deeplink = singularLinkParams.deeplink; 
          const passthrough = singularLinkParams.passthrough; 
          const isDeferred = singularLinkParams.isDeferred;

          // Add your deep link handling logic here
          if (deeplink && deeplink.includes('product')) {
               // Navigate to product page
               console.log("Navigating to product from deeplink:", deeplink);
          }

          // Use passthrough data if available
          if (passthrough) {
               console.log("Passthrough data:", passthrough);
          }

          // Check if this was a deferred deep link
          if (isDeferred) {
               console.log("This was a deferred deep link");
          }
});

withSkAdNetworkEnabled

SingularConfig.withSkAdNetworkEnabled Method

Enables or disables SKAdNetwork support for iOS 14+ attribution.

Signature

withSkAdNetworkEnabled(enabled: boolean): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withSkAdNetworkEnabled(true);

withWaitForTrackingAuthorizationWithTimeoutInterval

SingularConfig.withWaitForTrackingAuthorizationWithTimeoutInterval Method

Sets a timeout interval (in seconds) to wait for user's tracking authorization response (iOS 14+ only).

Signature

withWaitForTrackingAuthorizationWithTimeoutInterval(interval: number): SingularConfig

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withWaitForTrackingAuthorizationWithTimeoutInterval(30);

Complete Configuration Example

Chaining Multiple Configuration Methods

Example showing how to chain multiple configuration methods together.

Usage Example

typescript
const config = new SingularConfig("SDK KEY", "SDK SECRET")
     .withWaitForTrackingAuthorizationWithTimeoutInterval(30)
     .withCustomUserId("user_123456")
     .withGlobalProperty("key_1", "value1", true)
     .withLimitDataSharing(false)
     .withFacebookAppId("123456789012345");
     .withSingularLink((params) = {
        // Handle deep link parameters 
        if (params.deeplink) { 
             console.log("Deep link received:", params.deeplink); 
        } 
     })

// Initialize Singular with the configuration
Singular.init(config);