Cordova SDK - Configuration Methods Reference

Follow
Avatar
Jared Ornstead
Updated

Cordova SDK - Configuration 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 property is presented with a description, signature, and practical usage examples.

apikey

SingularConfig.apikey Property

Your Singular API key. This is a required property that must be set during configuration initialization.

Signature

apikey: string

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('YOUR_API_KEY', 'YOUR_SECRET');

brandedDomains

SingularConfig.brandedDomains Property

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

Signature

brandedDomains: Array<string>

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET');
config.withBrandedDomains(['yourcompany.com', 'go.yourcompany.com']);

clipboardAttribution

SingularConfig.clipboardAttribution Property

Enables clipboard attribution for iOS. When enabled, the SDK will check the clipboard for attribution data.

Signature

clipboardAttribution: boolean

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withClipboardAttribution();

collectOAID

SingularConfig.collectOAID Property

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

Signature

collectOAID: boolean

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withOAIDCollection();

conversionValueUpdatedHandler

SingularConfig.conversionValueUpdatedHandler Property

Sets a callback handler that is invoked when the SKAdNetwork conversion value is updated. This is useful for tracking conversion value changes on iOS.

Signature

conversionValueUpdatedHandler: Function

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withConversionValueUpdatedHandler(function(conversionValue) {
    console.log('Conversion value updated:', conversionValue);
  });

conversionValuesUpdatedHandler

SingularConfig.conversionValuesUpdatedHandler Property

Sets a callback handler that is invoked when SKAdNetwork 4.0 conversion values are updated. This callback receives the fine value, coarse value, and lock status for iOS 16.1+.

Signature

conversionValuesUpdatedHandler: Function

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withConversionValuesUpdatedHandler(function(values) {
    console.log('Conversion values updated:', values);
  });

customSdid

Enterprise Feature - Contact your Customer Success Manager to enable this feature for your account.

SingularConfig.customSdid Property

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

customSdid: string

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withCustomSdid(
    'custom-device-id-12345',
    function(sdid) {
      console.log('SDID was set:', sdid);
    },
    function(sdid) {
      console.log('SDID received:', sdid);
    }
  );

customUserId

SingularConfig.customUserId Property

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

customUserId: string

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withCustomUserId('user123456');

deviceAttributionCallbackHandler

BETA Feature - Sets a callback function to be called when device attribution data is available.

SingularConfig.deviceAttributionCallbackHandler Property

Sets a callback handler that is invoked when device attribution data is available. This allows you to access attribution data as soon as it's resolved.

Signature

deviceAttributionCallbackHandler: Function

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withDeviceAttributionCallbackHandler(function(attributes) {
    console.log('Attribution data received:', attributes);
    var campaign = attributes.campaign;
    var source = attributes.source;
  });

didSetSdidCallback

Enterprise Feature - Callback that is invoked when a custom SDID is set.

SingularConfig.didSetSdidCallback Property

Sets a callback function to be called when the custom SDID has been set. This is used in conjunction with the customSdid property.

Signature

didSetSdidCallback: Function

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withCustomSdid(
    'custom-device-id',
    function(result) {
      console.log('SDID was set:', result);
    },
    function(result) {
      console.log('SDID received:', result);
    }
  );

enableLogging

SingularConfig.enableLogging Property

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

Signature

enableLogging: boolean

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withLoggingEnabled();

enableOdmWithTimeoutInterval

SingularConfig.enableOdmWithTimeoutInterval Property

Enables On-Device Measurement with a specified timeout interval. This feature allows for privacy-focused measurement. Default value is -1 (disabled).

Signature

enableOdmWithTimeoutInterval: number

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withEnableOdmWithTimeoutInterval(30);

espDomains

SingularConfig.espDomains Property

Sets ESP (Email Service Provider) domains for email-based attribution. This allows you to track attribution from email campaigns.

Signature

espDomains: Array<string>

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withESPDomains(['email.example.com', 'mail.company.com']);

facebookAppId

SingularConfig.facebookAppId Property

Sets the Facebook App ID for Facebook attribution integration. This enables deep integration with Facebook's attribution system.

Signature

facebookAppId: string

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withFacebookAppId('1234567890123456');

globalProperties

SingularConfig.globalProperties Property

Sets global properties during initialization that will be sent with all subsequent events. This is useful for tracking persistent user attributes or application state.

Signature

globalProperties: Object

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withGlobalProperty('user_tier', 'premium', true)
  .withGlobalProperty('region', 'north_america', true);

limitAdvertisingIdentifiers

SingularConfig.limitAdvertisingIdentifiers Property

Controls whether advertising identifiers (IDFA/GAID) should be limited. Use this to comply with privacy preferences and regulations. Default value is false.

Signature

limitAdvertisingIdentifiers: boolean

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withLimitAdvertisingIdentifiers(true);

limitDataSharing

SingularConfig.limitDataSharing Property

Sets the data sharing limitation status during initialization. Use this to comply with privacy regulations by limiting what data is shared with third parties. Default value is null.

Signature

limitDataSharing: boolean

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withLimitDataSharing(true);

logLevel

SingularConfig.logLevel Property

Sets the SDK log level for more granular control over logging output. This allows you to specify the verbosity of SDK logs.

Signature

logLevel: number

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withLogLevel(3); // Set appropriate log level

manualSkanConversionManagement

SingularConfig.manualSkanConversionManagement Property

Enables manual SKAdNetwork conversion value management. When enabled, you must manually update conversion values instead of relying on automatic updates. Default value is false.

Signature

manualSkanConversionManagement: boolean

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withManualSkanConversionManagement();

pushNotificationsLinkPaths

SingularConfig.pushNotificationsLinkPaths Property

Configures custom paths for extracting deep links from push notification payloads. This allows you to specify where in the notification payload the deep link is located.

Signature

pushNotificationsLinkPaths: Array<Array<string>>

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withPushNotificationsLinkPaths([
    ['data', 'deeplink'],
    ['notification', 'data', 'url'],
    ['custom', 'link']
  ]);

sdidReceivedCallback

Enterprise Feature - Callback that is invoked when the SDID is received.

SingularConfig.sdidReceivedCallback Property

Sets a callback function to be called when the SDID is received from the server. This is used in conjunction with the customSdid property.

Signature

sdidReceivedCallback: Function

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withCustomSdid(
    'custom-device-id',
    function(result) { console.log('SDID set:', result); },
    function(result) { console.log('SDID received:', result); }
  );

secret

SingularConfig.secret Property

Your Singular SDK secret. This is a required property that must be set during configuration initialization.

Signature

secret: string

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('YOUR_API_KEY', 'YOUR_SECRET');

sessionTimeout

SingularConfig.sessionTimeout Property

Sets the session timeout in seconds. This determines how long a user session lasts after the app goes to the background. Default value is -1 (uses default timeout of 60 seconds).

Signature

sessionTimeout: number

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withSessionTimeoutInSec(120); // 2 minutes

shortLinkResolveTimeout

SingularConfig.shortLinkResolveTimeout Property

Sets the timeout in seconds for short link resolution. This determines how long the SDK will wait for a short link to resolve. Default value is 10 seconds.

Signature

shortLinkResolveTimeout: number

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withShortLinkResolveTimeout(15);

singularLinkHandler

SingularConfig.singularLinkHandler Property

Sets a callback handler for Singular Links (deep links). This callback is invoked when the app is opened via a Singular Link, allowing you to handle deep linking logic.

Signature

singularLinkHandler: Function

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withSingularLink(function(singularLinkParams) {
    console.log('Deep link opened:', singularLinkParams);
    var deeplink = singularLinkParams.deeplink;
    var passthrough = singularLinkParams.passthrough;
    // Handle navigation based on deep link data
  });

skAdNetworkEnabled

SingularConfig.skAdNetworkEnabled Property

Enables or disables SKAdNetwork support for iOS. When enabled, the SDK will automatically handle SKAdNetwork attribution. Default value is true.

Signature

skAdNetworkEnabled: boolean

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withSkAdNetworkEnabled(true);

waitForTrackingAuthorizationWithTimeoutInterval

SingularConfig.waitForTrackingAuthorizationWithTimeoutInterval Property

Sets the timeout interval to wait for iOS ATT (App Tracking Transparency) authorization before initializing the SDK. This is useful for iOS 14+ to ensure tracking permission is requested before SDK initialization. Default value is 0 (no wait).

Signature

waitForTrackingAuthorizationWithTimeoutInterval: number

Usage Example

JavaScript 
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

var config = new SingularConfig('API_KEY', 'SECRET')
  .withWaitForTrackingAuthorizationWithTimeoutInterval(60); // Wait up to 60 seconds

Complete Configuration Example

Here is a comprehensive example showing how to configure the Singular SDK with multiple options:

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

// Create configuration with API key and secret
var config = new SingularConfig('YOUR_API_KEY', 'YOUR_SECRET')
  .withCustomUserId('user123456')
  .withSessionTimeoutInSec(120)
  .withLoggingEnabled()
  .withSingularLink(function(params) {
    console.log('Deep link:', params.deeplink);
  })
  .withConversionValueUpdatedHandler(function(value) {
    console.log('Conversion value:', value);
  })
  .withGlobalProperty('user_tier', 'premium', true)
  .withGlobalProperty('app_version', '2.1.0', true)
  .withShortLinkResolveTimeout(15);

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