React Native SDK - Configuration Methods Reference

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

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

const config: SingularConfig = {apikey: 'YOUR_API_KEY', secret: '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

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

const config: SingularConfig = {
  apikey: 'YOUR_API_KEY',
  secret: 'YOUR_SECRET',
  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

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

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

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

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

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

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

New ArchitectureOld Architecture
// 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);
});

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

New ArchitectureOld Architecture
// 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);
});

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

New ArchitectureOld Architecture
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular 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);
});

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

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

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  customUserId: '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: (attributes: Record<string, any>) => void

Usage Example

New ArchitectureOld Architecture
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular 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;
});

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

Usage Example

New ArchitectureOld Architecture
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular 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);
});

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

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

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

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

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

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  espDomains: ['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

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

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  facebookAppId: '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

New ArchitectureOld Architecture
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular 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
    }
  }
};

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

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

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  limitAdvertisingIdentifiers: 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

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

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

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

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

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

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

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

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  pushNotificationsLinkPaths: [
    ['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: (result: string) => void

Usage Example

New ArchitectureOld Architecture
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular 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);
});

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

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

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: '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

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

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  sessionTimeoutInSec: 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

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

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  shortLinkResolveTimeout: 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

New ArchitectureOld Architecture
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular 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);
  }
});

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

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

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

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

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

const config: SingularConfig = {
  apikey: 'API_KEY',
  secret: 'SECRET',
  waitForTrackingAuthorizationWithTimeoutInterval: 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

New ArchitectureOld Architecture
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular 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
  sessionTimeoutInSec: 120,
  loggingEnabled: 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);
});