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';
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';
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';
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';
const config: SingularConfig = {
apikey: 'API_KEY',
secret: 'SECRET',
oaidCollection: 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
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
// 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);
});
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';
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');
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
// 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;
});
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
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
// 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);
});
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.
Signature
enableLogging: boolean
Usage Example
// 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
};
import { SingularConfig } from 'singular-react-native';
const config = new SingularConfig('API_KEY', 'SECRET')
.withLoggingEnabled();
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';
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';
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';
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';
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';
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);
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';
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';
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
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
// 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);
});
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 { 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 { NativeEventEmitter } from 'react-native';
const config: SingularConfig = {
apikey: 'API_KEY',
secret: 'SECRET',
sessionTimeoutInSec: 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 { 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 { 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';
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);
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';
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 { 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);
});
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);