React Native SDK - Configuration Reference

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';

const config: SingularConfig = {apikey: 'YOUR_API_KEY', secret: 'YOUR_SECRET'}

import { SingularConfig } from 'singular-react-native';

const 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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';

const config: SingularConfig = {
  apikey: 'YOUR_API_KEY',
  secret: 'YOUR_SECRET',
  brandedDomains: ['yourcompany.com', 'go.yourcompany.com']
};

import { SingularConfig } from 'singular-react-native';

const config = new SingularConfig('API_KEY', 'SECRET');
config.brandedDomains = ['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. This is enabled using the withClipboardAttribution() method.

Signature

clipboardAttribution: boolean

Usage Example

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  clipboardAttribution: true // This property enables clipboard attribution
};

import { SingularConfig } from 'singular-react-native';

const 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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  collectOAID: true // Enables OAID Collection
};

import { SingularConfig } from 'singular-react-native';

const 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: (conversionValue: number) => void

Usage Example

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import { NativeEventEmitter } from 'react-native';

const emitter = new NativeEventEmitter(NativeSingular);

emitter.addListener("ConversionValueUpdatedHandler", (conversionValue) => {
  console.log('conversion value updated to:', conversionValue);
});

import { SingularConfig } from 'singular-react-native';

const config = new SingularConfig('API_KEY', 'SECRET')
  .withConversionValueUpdatedHandler((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: (updatedValues: Record<string, any>) => void

Usage Example

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import { NativeEventEmitter } from 'react-native';

const emitter = new NativeEventEmitter(NativeSingular);

emitter.addListener("ConversionValuesUpdatedHandler", (values) => {
  console.log('Conversion values updated:', values);
});

import { SingularConfig } from 'singular-react-native';

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

customSdid

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';
import { NativeEventEmitter } from 'react-native';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  customSdid: 'custom-device-id-12345'
};

const emitter = new NativeEventEmitter(NativeSingular);

emitter.addListener('DidSetSdidCallback', (result) => {
  console.log('SDID was set:', result);
});

emitter.addListener('SdidReceivedCallback', (result) => {
  console.log('SDID received:', result);
});

import { SingularConfig } from 'singular-react-native';

const config = new SingularConfig('API_KEY', 'SECRET')
  .withCustomSdid(
    'custom-device-id-12345',
    (sdid) => {
      console.log('SDID was set:', sdid);
    },
    (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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  customUserId: 'user123456'
};

import { SingularConfig } from 'singular-react-native';

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

ddlTimeoutSec

SingularConfig.ddlTimeoutSec Property

Sets how long after a fresh install Singular will still resolve a deferred deep link and invoke your singularLinkHandler . The default is 60 seconds. Raise it if your onboarding flow means users reach the deep-linked screen late; lower it if you would rather drop a stale deferred link than route on it.

Android only. On iOS withDDLTimeoutInSec() logs a message and leaves the configuration unchanged. The iOS equivalent is the runtime method Singular.setDeferredDeepLinkTimeout() . A value of 0 or less is ignored and the 60-second default is kept.

Signature

ddlTimeoutSec: number

Usage Example

import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  ddlTimeoutSec: 120 // seconds
};

import { SingularConfig } from 'singular-react-native';

const config = new SingularConfig('API_KEY', 'SECRET')
  .withDDLTimeoutInSec(120);

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.

Only fields that have a value are included, so check for a key before reading it. Most installs return a subset — which fields are present depends on the touchpoint Singular matched.

Key	Type	Notes
`network`	string	Always present when the callback fires. "Organic" when no touchpoint was matched.
`campaign_id`	string	Present when the touchpoint provides it.
`campaign_name`	string	Present when the touchpoint provides it.
`subcampaign_id`	string	Present when the touchpoint provides it. Not available from every source.
`subcampaign_name`	string	Present when the touchpoint provides it. Not available from every source.
`creative_id`	string	Present when the touchpoint provides it. Not available from every source.
`creative_name`	string	Present when the touchpoint provides it. Not available from every source.
`passthrough`	string	Present when passthrough values were attached to the link.
`match_type`	string	Present when the touchpoint provides it. Contact Singular if you need the value set.
`click_timestamp`	number	Present when the touchpoint provides it. Epoch microseconds — divide by 1,000,000 for seconds.

Signature

deviceAttributionCallbackHandler: (attributes: Record<string, any>) => void

Usage Example

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';
import { NativeEventEmitter } from 'react-native';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET'
};

const emitter = new NativeEventEmitter(NativeSingular);

emitter.addListener('DeviceAttributionCallbackHandler', (attributes) => {
  console.log('Attribution data received:', attributes);
  const campaign = attributes.campaign;
  const source = attributes.source;
});

import { SingularConfig } from 'singular-react-native';

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

didSetSdidCallback

- 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: (result: string) => void

Usage Example

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';
import { NativeEventEmitter } from 'react-native';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  customSdid: 'custom-device-id'
};

const emitter = new NativeEventEmitter(NativeSingular);

emitter.addListener('DidSetSdidCallback', (result) => {
  console.log('SDID was set:', result);
});

emitter.addListener('SdidReceivedCallback', (result) => {
  console.log('SDID received:', result);
});

import { SingularConfig } from 'singular-react-native';

const config = new SingularConfig('API_KEY', 'SECRET')
  .withCustomSdid(
    'custom-device-id',
    (result) => {
      console.log('SDID was set:', result);
    },
    (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.

Platform: Android and iOS. iOS support was added in React Native SDK 4.3.0; earlier versions ignored this property on iOS. Pair it with logLevel to control verbosity.

Signature

enableLogging: boolean

Usage Example

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  enableLogging: true
};

import { SingularConfig } from 'singular-react-native';

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

enableOdmWithTimeoutInterval

SingularConfig.enableOdmWithTimeoutInterval Property

Enables Google's On-Device Measurement (ODM) and sets how many seconds the SDK will wait for Google's attribution token before sending the first session. The default is -1 , which disables ODM. This is required for Google Ads iOS Integrated Conversion Measurement (ICM).

iOS only, and it delays the first session. The SDK blocks the session until Google returns an attribution token or the interval elapses, so deep link callbacks are deferred by up to this many seconds. ODM also requires Google's ODM SDK, the -ObjC linker flag, and React Native SDK v3.9.0 or later. Configure it during your initial integration rather than adding it later.

Signature

enableOdmWithTimeoutInterval: number

Usage Example

import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  enableOdmWithTimeoutInterval: 10 // seconds
};

import { SingularConfig } from 'singular-react-native';

const config = new SingularConfig('API_KEY', 'SECRET')
  .withEnableOdmWithTimeoutInterval(10);

espDomains

SingularConfig.espDomains Property

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

Signature

espDomains: Array<string>

Usage Example

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  espDomains: ['mailchimp.com', 'sendgrid.net', 'campaign-monitor.com']
};

import { SingularConfig } from 'singular-react-native';

const config = new SingularConfig('API_KEY', 'SECRET')
  .withEspDomains(['mailchimp.com', 'sendgrid.net', 'campaign-monitor.com']);

facebookAppId

SingularConfig.facebookAppId Property

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

Signature

facebookAppId: string

Usage Example

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  facebookAppId: 'YOUR_FACEBOOK_APP_ID'
};

import { SingularConfig } from 'singular-react-native';

const config = new SingularConfig('API_KEY', 'SECRET')
  .withFacebookAppId('YOUR_FACEBOOK_APP_ID');

globalProperties

SingularConfig.globalProperties Property

Sets global properties during SDK initialization. These properties will be sent with all events tracked by the SDK.

Signature

globalProperties: Record<string, { Key: string; Value: any; OverrideExisting: boolean }>

Usage Example

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  globalProperties: {
    prop1: {
      Key: "app_version",
      Value: "1.2.3",
      OverrideExisting: true
    },
    prop2: {
      Key: "user_type",
      Value: "free",
      OverrideExisting: true
    }
  }
};

import { SingularConfig } from 'singular-react-native';

const config = new SingularConfig('API_KEY', 'SECRET')
  .withGlobalProperty('app_version', '1.2.3', true)
  .withGlobalProperty('user_type', 'premium', true);

limitAdvertisingIdentifiers

SingularConfig.limitAdvertisingIdentifiers Property

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

Signature

limitAdvertisingIdentifiers: boolean

Usage Example

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  limitAdvertisingIdentifiers: true
};

import { SingularConfig } from 'singular-react-native';

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

limitDataSharing

SingularConfig.limitDataSharing Property

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

Signature

limitDataSharing: boolean | null

Usage Example

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  limitDataSharing: true
};

import { SingularConfig } from 'singular-react-native';

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

logLevel

SingularConfig.logLevel Property

Sets how verbose the SDK log output is. It only has an effect when enableLogging is true . Values are the standard Android android.util.Log constants, where a lower number is more verbose: 2 VERBOSE, 3 DEBUG, 4 INFO, 5 WARN, 6 ERROR, 7 ASSERT. The default is 6 (ERROR).

iOS support added in 4.3.0. Earlier versions ignored both logLevel and enableLogging on iOS. From 4.3.0 the iOS bridge maps the Android-style value onto the native iOS log level: 2 Verbose, 3 Debug, 4 Info, 5 Warning, 6 Error, and 7 turns logging off. Any other value, including a negative one, falls back to Error.

Note the difference at the top of the range: on Android 7 is ASSERT, while on iOS it disables logging entirely.

Signature

logLevel: number

Usage Example

import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  enableLogging: true,
  logLevel: 3 // DEBUG
};

import { SingularConfig } from 'singular-react-native';

const config = new SingularConfig('API_KEY', 'SECRET')
  .withLoggingEnabled()
  .withLogLevel(3); // DEBUG

manualSkanConversionManagement

SingularConfig.manualSkanConversionManagement Property

Enables manual SKAdNetwork conversion value management. When enabled, you are responsible for updating conversion values manually. Default value is false.

Signature

manualSkanConversionManagement: boolean

Usage Example

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  manualSkanConversionManagement: true
};

import { SingularConfig } from 'singular-react-native';

const 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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  pushNotificationsLinkPaths: [
    ['data', 'deeplink'],
    ['notification', 'data', 'url'],
    ['custom', 'link']
  ]
};

import { SingularConfig } from 'singular-react-native';

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

sdidReceivedCallback

- 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: (result: string) => void

Usage Example

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';
import { NativeEventEmitter } from 'react-native';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  customSdid: 'custom-device-id'
};

const emitter = new NativeEventEmitter(NativeSingular);

emitter.addListener('DidSetSdidCallback', (result) => {
  console.log('SDID set:', result);
});

emitter.addListener('SdidReceivedCallback', (result) => {
  console.log('SDID received:', result);
});

import { SingularConfig } from 'singular-react-native';

const config = new SingularConfig('API_KEY', 'SECRET')
  .withCustomSdid(
    'custom-device-id',
    (result) => { console.log('SDID set:', result); },
    (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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';
import { NativeEventEmitter } from 'react-native';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET'
};

import { SingularConfig } from 'singular-react-native';

const 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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';
import { NativeEventEmitter } from 'react-native';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  sessionTimeout: 120 // 2 minutes
};

import { SingularConfig } from 'singular-react-native';

const 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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';
import { NativeEventEmitter } from 'react-native';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  shortLinkResolveTimeout: 15
};

import { SingularConfig } from 'singular-react-native';

const 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 a deep link is resolved, allowing you to handle the deep link data in your application.

Signature

singularLinkHandler: (params: Record<string, any>) => void

Usage Example

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';
import { NativeEventEmitter } from 'react-native';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  // No singularLink callback in config for TurboModule!
};

const emitter = new NativeEventEmitter(NativeSingular);

emitter.addListener('SingularLinkHandler', (params) => {
  if (params.deeplink) {
    console.log('Deep link received:', params.deeplink);
    // Navigate to the appropriate screen
  }
  if (params.passthrough) {
    console.log('Passthrough data:', params.passthrough);
  }
});

import { SingularConfig } from 'singular-react-native';

const config = new SingularConfig('API_KEY', 'SECRET')
  .withSingularLink((params) => {
    if (params.deeplink) {
      console.log('Deep link received:', params.deeplink);
      // Navigate to the appropriate screen
    }
    if (params.passthrough) {
      console.log('Passthrough data:', params.passthrough);
    }
  });

skAdNetworkEnabled

SingularConfig.skAdNetworkEnabled Property

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

Signature

skAdNetworkEnabled: boolean

Usage Example

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  skAdNetworkEnabled: true
};

import { SingularConfig } from 'singular-react-native';

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

userDetails

SingularConfig.userDetails Property

Attaches a hashed email address and/or phone number to the first session the SDK sends. Assign a SingularUserDetails object, or set it with the withUserDetails() builder. The SDK normalizes and SHA-256 hashes cleartext values on the device, so the raw email address and phone number are never transmitted. See Setting a User ID and Hashed User Details for the full API and the validation rules.

Availability: React Native SDK version 4.3.0 and above.

Signature

userDetails: SingularUserDetails

Usage Example

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';
const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  userDetails: {
    email: 'user@example.com',
    phoneNumber: '+15551234567'
  }
};

import { SingularConfig, SingularUserDetails } from 'singular-react-native';
const userDetails = new SingularUserDetails()
  .setEmail('user@example.com')
  .setPhoneNumber('+15551234567');
const config = new SingularConfig('API_KEY', 'SECRET')
  .withUserDetails(userDetails);

waitForTrackingAuthorizationWithTimeoutInterval

SingularConfig.waitForTrackingAuthorizationWithTimeoutInterval Property

Sets a timeout interval for waiting for ATT (App Tracking Transparency) authorization on iOS. The SDK will wait up to this many seconds for the user to respond to the ATT prompt before continuing. Default value is 0 (no wait).

Signature

waitForTrackingAuthorizationWithTimeoutInterval: number

Usage Example

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  waitForTrackingAuthorizationWithTimeoutInterval: 300
};

import { SingularConfig } from 'singular-react-native';

const config = new SingularConfig('API_KEY', 'SECRET')
  .withWaitForTrackingAuthorizationWithTimeoutInterval(300);

Complete Configuration Example

Comprehensive SDK Configuration

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

Complete Example

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';
import { NativeEventEmitter } from 'react-native';

// Create comprehensive configuration
const config: SingularConfig = {
  apikey: 'YOUR_API_KEY',
  secret: 'YOUR_SECRET',

  // Basic options
  sessionTimeout: 120,
  enableLogging: true,

  // User identification
  customUserId: 'user123456',

  // Global properties
  globalProperties: {
    app_version: {
      Key: 'app_version',
      Value: '1.2.3',
      OverrideExisting: true
    },
    user_type: {
      Key: 'user_type',
      Value: 'premium',
      OverrideExisting: true
    }
  },

  // Privacy settings
  limitDataSharing: false,

  // Email attribution
  espDomains: ['mailchimp.com', 'sendgrid.net'],

  // Facebook integration
  facebookAppId: 'YOUR_FACEBOOK_APP_ID',

  // SKAdNetwork (iOS)
  skAdNetworkEnabled: true,
  waitForTrackingAuthorizationWithTimeoutInterval: 300,

  // Push notifications
  pushNotificationsLinkPaths: [
    ['data', 'deeplink'],
    ['notification', 'data', 'url']
  ],

  // Branded domains
  brandedDomains: ['yourcompany.com', 'go.yourcompany.com'],
};

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

// Use event emitter for all callbacks/handlers
const emitter = new NativeEventEmitter(NativeSingular);

// Singular Link (deep links)
emitter.addListener('SingularLinkHandler', (params) => {
  if (params.deeplink) {
    console.log('Deep link:', params.deeplink);
    // Handle deep link navigation
  }
  if (params.passthrough) {
    console.log('Passthrough data:', params.passthrough);
  }
});

// Attribution callback
emitter.addListener('DeviceAttributionCallbackHandler', (attributionData) => {
  console.log('Attribution:', attributionData);
});

// SDID callbacks (if needed)
emitter.addListener('DidSetSdidCallback', (result) => {
  console.log('SDID set:', result);
});
emitter.addListener('SdidReceivedCallback', (result) => {
  console.log('SDID received:', result);
});

import { Singular, SingularConfig } from 'singular-react-native';

// Create comprehensive configuration
const config = new SingularConfig('YOUR_API_KEY', 'YOUR_SECRET')
  // Basic options
  .withSessionTimeoutInSec(120)
  .withLoggingEnabled()
  
  // User identification
  .withCustomUserId('user123456')
  
  // Global properties
  .withGlobalProperty('app_version', '1.2.3', true)
  .withGlobalProperty('user_type', 'premium', true)
  
  // Deep links
  .withSingularLink((params) => {
    if (params.deeplink) {
      console.log('Deep link:', params.deeplink);
      // Handle deep link navigation
    }
  })
  .withShortLinkResolveTimeout(10)
  
  // Attribution callback
  .withDeviceAttributionCallbackHandler((attributionData) => {
    console.log('Attribution:', attributionData);
  })
  
  // Privacy settings
  .withLimitDataSharing(false)
  
  // Email attribution
  .withEspDomains(['mailchimp.com', 'sendgrid.net'])
  
  // Facebook integration
  .withFacebookAppId('YOUR_FACEBOOK_APP_ID')
  
  // SKAdNetwork (iOS)
  .withSkAdNetworkEnabled(true)
  .withWaitForTrackingAuthorizationWithTimeoutInterval(30)
  
  // Push notifications
  .withPushNotificationsLinkPaths([
    ['data', 'deeplink'],
    ['notification', 'data', 'url']
  ])
  
  // Branded domains
  .withBrandedDomains(['yourcompany.com', 'go.yourcompany.com']);

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

React Native SDK - Configuration Methods Reference

React Native SDK - Configuration Reference

apikey

SingularConfig.apikey Property

Signature

Usage Example

brandedDomains

SingularConfig.brandedDomains Property

Signature

Usage Example

clipboardAttribution

SingularConfig.clipboardAttribution Property

Signature

Usage Example

collectOAID

SingularConfig.collectOAID Property

Signature

Usage Example

conversionValueUpdatedHandler

SingularConfig.conversionValueUpdatedHandler Property

Signature

Usage Example

conversionValuesUpdatedHandler

SingularConfig.conversionValuesUpdatedHandler Property

Signature

Usage Example

customSdid

SingularConfig.customSdid Property

Signature

Usage Example

customUserId

SingularConfig.customUserId Property

Signature

Usage Example

ddlTimeoutSec

SingularConfig.ddlTimeoutSec Property

Signature

Usage Example

deviceAttributionCallbackHandler

SingularConfig.deviceAttributionCallbackHandler Property

Signature

Usage Example

didSetSdidCallback

SingularConfig.didSetSdidCallback Property

Signature

Usage Example

enableLogging

SingularConfig.enableLogging Property

Signature

Usage Example

enableOdmWithTimeoutInterval

SingularConfig.enableOdmWithTimeoutInterval Property

Signature

Usage Example

espDomains

SingularConfig.espDomains Property

Signature

Usage Example

facebookAppId

SingularConfig.facebookAppId Property

Signature

Usage Example

globalProperties

SingularConfig.globalProperties Property

Signature

Usage Example

limitAdvertisingIdentifiers

SingularConfig.limitAdvertisingIdentifiers Property

Signature

Usage Example

limitDataSharing

SingularConfig.limitDataSharing Property

Signature

Usage Example

logLevel

SingularConfig.logLevel Property

Signature

Usage Example

manualSkanConversionManagement

SingularConfig.manualSkanConversionManagement Property