Cordova SDK - Configuration Methods Reference

Follow
Avatar
Jared Ornstead
Updated

Cordova SDK - Configuration Methods Reference

This document provides a comprehensive reference for all configuration options available in the Singular SDK for Cordova 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.

withClipboardAttribution

SingularConfig.withClipboardAttribution Method

Enables clipboard attribution for the SDK. When enabled, the SDK will check the device clipboard for attribution links during initialization.

Signature

withClipboardAttribution(): SingularConfig

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withClipboardAttribution();

withConversionValueUpdatedHandler

SingularConfig.withConversionValueUpdatedHandler Method

Sets a callback function to be called when the SKAdNetwork conversion value is updated. This is specific to iOS and allows you to react to conversion value changes.

Signature

withConversionValueUpdatedHandler(conversionValueUpdatedHandler: Function): SingularConfig

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withConversionValueUpdatedHandler(function(conversionValue) {
          console.log("Conversion value updated to:", conversionValue);
     }
);

withConversionValuesUpdatedHandler

SingularConfig.withConversionValuesUpdatedHandler Method

Sets a callback function to be called when the SKAdNetwork 4.0 conversion values are updated. This is specific to iOS 16.1+ and allows you to react to changes in fine, coarse, and lock values.

Signature

withConversionValuesUpdatedHandler(conversionValuesUpdatedHandler: Function): SingularConfig

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withConversionValuesUpdatedHandler(function(conversionValues) {
          console.log("Fine value:", conversionValues.fineValue);
          console.log("Coarse value:", conversionValues.coarseValue);
          console.log("Lock value:", conversionValues.lockValue);
     }
);

withCustomSdid

SingularConfig.withCustomSdid Method

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

Signature

withCustomSdid(customSdid: string, didSetSdidCallback: Function, sdidReceivedCallback: Function): SingularConfig

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY", "SDK SECRET")
     .withCustomSdid("custom-device-id-12345",
     function(result) {
          console.log("SDID was set successfully:", result);
     },
     function(error) {
          console.error("Failed to set SDID:", error);
     }
);

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

withCustomUserId(customUserId: string): SingularConfig

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withCustomUserId("user-123456");

withDeviceAttributionCallbackHandler

SingularConfig.withDeviceAttributionCallbackHandler Method

BETA Feature: Sets a callback function to be called when device attribution data is available. This allows you to access attribution data as soon as it's available.

Signature

withDeviceAttributionCallbackHandler(deviceAttributionCallbackHandler: Function): SingularConfig

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
.withDeviceAttributionCallbackHandler(function(attributionData) {
     console.log("Attribution data:", attributionData);
     console.log("Campaign:", attributionData.campaign);
     console.log("Source:", attributionData.source);
});

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.

Signature

withESPDomains(espDomains: string[]): SingularConfig

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
.withESPDomains([
    "mailchimp.com",
    "sendgrid.net",
    "campaign-monitor.com"
]);

withFacebookAppId

SingularConfig.withFacebookAppId Method

Sets the Facebook App ID for Facebook attribution. This allows the SDK to attribute installs and events from Facebook campaigns.

Signature

withFacebookAppId(facebookAppId: string): SingularConfig

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withFacebookAppId("123456789012345");

withGlobalProperty

SingularConfig.withGlobalProperty Method

Sets a global property during SDK initialization. This property will be sent with all events tracked by the SDK.

Signature

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

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withGlobalProperty("app_version", "1.2.3", true);

withLimitDataSharing

SingularConfig.withLimitDataSharing Method

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

Signature

withLimitDataSharing(shouldLimitDataSharing: boolean): SingularConfig

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withLimitDataSharing(true);

withLimitedIdentifiersEnabled

SingularConfig.withLimitedIdentifiersEnabled Method

Enables or disables the use of limited identifiers. This option affects how the SDK collects and uses device identifiers for tracking and attribution.

Signature

withLimitedIdentifiersEnabled(limitedIdentifiersEnabled: boolean): SingularConfig

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withLimitedIdentifiersEnabled(true);

withLogLevel

SingularConfig.withLogLevel Method

Sets the log level for the SDK. This controls the verbosity of logs generated by the SDK.

Signature

withLogLevel(level: string): SingularConfig

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withLogLevel("verbose");

withLoggingEnabled

SingularConfig.withLoggingEnabled Method

Enables detailed logging for the SDK. When enabled, the SDK will output detailed logs that can help with debugging.

Signature

withLoggingEnabled(): SingularConfig

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withLoggingEnabled();

withManualSkanConversionManagement

SingularConfig.withManualSkanConversionManagement Method

Enables manual management of SKAdNetwork conversion values. When enabled, the SDK will not automatically update conversion values, allowing you to control them manually.

Signature

withManualSkanConversionManagement(): SingularConfig

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withManualSkanConversionManagement();

withOAIDCollection

SingularConfig.withOAIDCollection Method

Enables collection of OAID (Open Anonymous Device Identifier) on supported Android devices. This is an alternative identifier used in some regions, particularly in China.

Signature

withOAIDCollection(): SingularConfig

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withOAIDCollection();

withPushNotificationsLinkPaths

SingularConfig.withPushNotificationsLinkPaths Method

Sets the paths to look for deep links in push notification payloads. This helps the SDK find and process attribution links in push notifications.

Signature

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

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
.withPushNotificationsLinkPaths([
    ["data", "deeplink"],
    ["notification", "data", "url"],
    ["custom", "link"]
]);

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.

Signature

withSessionTimeoutInSec(sessionTimeout: number): SingularConfig

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withSessionTimeoutInSec(120); // 2 minutes

withShortLinkResolveTimeout

SingularConfig.withShortLinkResolveTimeout Method

Sets the timeout in seconds for resolving short links. This determines how long the SDK will wait for a short link to resolve before continuing with initialization.

Signature

withShortLinkResolveTimeout(shortLinkResolveTimeout: number): SingularConfig

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withShortLinkResolveTimeout(15); // 130 seconds

withSingularLink

SingularConfig.withSingularLink Method

Sets a callback function to handle deep links processed by Singular. This allows your app to respond to deep links used in attribution.

Signature

withSingularLink(singularLinkHandler: Function): SingularConfig

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
.withSingularLink(function(data) {
    var deeplink = data.deeplink;
    var passthrough = data.passthrough;
    var isDeferred = data.isDeferred;
    
    console.log("Deep link received:", deeplink);
    
    if (deeplink) {
        // Handle the deep link, e.g., navigate to a specific screen
        navigateToScreen(deeplink);
    }
});

withSkAdNetworkEnabled

SingularConfig.withSkAdNetworkEnabled Method

Enables or disables SKAdNetwork support. This is specific to iOS and controls whether the SDK will use Apple's SKAdNetwork for attribution.

Signature

withSkAdNetworkEnabled(skAdNetworkEnabled: boolean): SingularConfig

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withSkAdNetworkEnabled(true);

withWaitForTrackingAuthorizationWithTimeoutInterval

SingularConfig.withWaitForTrackingAuthorizationWithTimeoutInterval Method

Sets the timeout interval in seconds to wait for the user's tracking authorization response on iOS 14+. This determines how long the SDK will wait for the ATT prompt response before continuing with initialization.

Signature

withWaitForTrackingAuthorizationWithTimeoutInterval(waitForTrackingAuthorizationWithTimeoutInterval: number): SingularConfig

Usage Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withWaitForTrackingAuthorizationWithTimeoutInterval(30); // 30 seconds

Complete Configuration Example

Chaining Multiple Configuration Options

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

Complete Example

javascript
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig("SDK KEY","SDK SECRET")
     .withWaitForTrackingAuthorizationWithTimeoutInterval(30)    
     .withCustomUserId("user-123456")
     .withGlobalProperty("key_1", "value1", true)     
     .withLimitDataSharing(false)
     .withFacebookAppId("123456789012345"); 
     .withSingularLink(function(data) {
          var deeplink = data.deeplink;
          var passthrough = data.passthrough;
          var isDeferred = data.isDeferred;
          console.log("Deep link received:", deeplink);

          if (deeplink) {
               // Handle the deep link
               navigateToScreen(deeplink);
          }
     })
    
// Initialize the SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);