React Native SDK - 配置参考
本文档全面介绍了用于 React Native 应用程序的 Singular SDK 中的所有配置选项。通过 SingularConfig 对象,您可以自定义 SDK 的行为,包括跟踪设置、属性选项、隐私控制等。每个配置属性都附有说明、签名和实际使用示例。
apikey
SingularConfig.apikey 属性
你的 Singular API 密钥。这是配置初始化过程中必须设置的属性。
签名
apikey: string
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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');
品牌域名
SingularConfig.brandedDomains 属性
为网络到应用程序属性设置品牌域。这允许你指定为归因目的而跟踪的自定义域名。
签名
brandedDomains: Array<string>
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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'];
剪贴板属性
SingularConfig.clipboardAttribution 属性
启用 iOS 的剪贴板属性。启用后,SDK 将检查剪贴板中的属性数据。可使用 withClipboardAttribution() 方法启用。
签名
clipboardAttribution: boolean
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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 属性
为 Android 启用 OAID(开放式匿名设备标识符)收集功能。 该功能主要用于在无法使用 Google Play 服务的中国进行跟踪。默认值为 false。
签名
collectOAID: boolean
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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 属性
设置 SKAdNetwork 转换值更新时调用的回调处理程序。这对跟踪 iOS 上转换值的变化非常有用。
签名
conversionValueUpdatedHandler: (conversionValue: number) => void
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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 属性
设置 SKAdNetwork 4.0 转换值更新时调用的回调处理程序。该回调接收精细值、粗略值和 iOS 16.1+ 的锁定状态。
签名
conversionValuesUpdatedHandler: (updatedValues: Record<string, any>) => void
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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);
});
自定义值
企业功能--请联系您的客户成功经理为您的账户启用此功能。
SingularConfig.customSdid 属性
设置自定义 SDID(Singular 设备 ID)。这允许您提供自己的设备标识符,而不是使用 Singular 生成的标识符。
签名
customSdid: string
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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);
}
);
自定义用户标识
SingularConfig.customUserId 属性
在 SDK 初始化过程中设置自定义用户 ID。这样就可以从一开始就将 Singular 数据与自己的用户识别系统关联起来。
签名
customUserId: string
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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 功能- 设置设备属性数据可用时调用的回调函数。
SingularConfig.deviceAttributionCallbackHandler 属性
设置设备属性数据可用时调用的回调处理程序。这样就可以在属性数据解析后立即访问。
签名
deviceAttributionCallbackHandler: (attributes: Record<string, any>) => void
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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
企业功能- 设置自定义 SDID 时调用的回调。
SingularConfig.didSetSdidCallback 属性
设置自定义 SDID 设置时调用的回调函数,与 customSdid 属性结合使用。
签名
didSetSdidCallback: (result: string) => void
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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);
}
);
启用记录
SingularConfig.enableLogging 属性
为调试目的启用 SDK 日志。这在开发和故障排除过程中非常有用。建议在生产构建中禁用日志记录。默认值为 false。
签名
enableLogging: boolean
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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 属性
设置用于电子邮件归因的 ESP(电子邮件服务提供商)域。 这样就可以指定哪些电子邮件域应考虑用于归因跟踪。
签名
espDomains: Array<string>
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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 属性
为 Facebook 归因整合设置 Facebook 应用程序 ID。这使 SDK 能够跟踪 Facebook 营销活动的归因。
签名
facebookAppId: string
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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 属性
在 SDK 初始化过程中设置全局属性。这些属性将与 SDK 跟踪的所有事件一起发送。
签名
globalProperties: Record<string, { Key: string; Value: any; OverrideExisting: boolean }>
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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 属性
在混合受众应用程序中启用限制广告标识符模式。 该选项会影响 SDK 收集和使用设备标识符进行跟踪的方式。默认值为 false。
签名
limitAdvertisingIdentifiers: boolean
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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 属性
设置初始化时的数据共享限制状态。使用此属性可根据用户同意或隐私要求限制数据共享。默认值为空。
签名
limitDataSharing: boolean | null
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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 属性
启用手动 SKAdNetwork 转换值管理。启用后,您将负责手动更新转换值。默认值为 false。
签名
manualSkanConversionManagement: boolean
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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 属性
配置从推送通知有效负载中提取深度链接的自定义路径。这样就可以指定深层链接在通知有效负载中的位置。
签名
pushNotificationsLinkPaths: Array<Array<string>>
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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
企业功能- 收到 SDID 时调用的回调。
SingularConfig.sdidReceivedCallback 属性
设置从服务器接收 SDID 时调用的回调函数。此属性与自定义 SDID 属性结合使用。
签名
sdidReceivedCallback: (result: string) => void
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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); }
);
秘密
SingularConfig.secret 属性
你的 Singular SDK 密钥。这是配置初始化时必须设置的属性。
签名
secret: string
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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 属性
设置会话超时(以秒为单位)。这决定了应用程序进入后台后用户会话的持续时间。默认值为-1(使用默认超时 60 秒)。
签名
sessionTimeout: number
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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 属性
设置短链接解析超时(以秒为单位)。这决定了 SDK 等待短链接解析的时间。默认值为 10 秒。
签名
shortLinkResolveTimeout: number
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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 属性
设置奇异链接(深层链接)的回调处理程序。解析深层链接时会调用该回调,以便在应用程序中处理深层链接数据。
签名
singularLinkHandler: (params: Record<string, any>) => void
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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 属性
启用或禁用 iOS 上的 SKAdNetwork 归属。启用后,SDK 将自动处理 SKAdNetwork 归属。默认值为 true。
签名
skAdNetworkEnabled: boolean
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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 属性
设置 iOS 上等待 ATT(应用程序跟踪透明度)授权的超时间隔。SDK 最多会等待这么多秒钟,等用户回复 ATT 提示后再继续。默认值为 0(不等待)。
签名
waitForTrackingAuthorizationWithTimeoutInterval: number
使用示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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);
完整配置示例
完整的 SDK 配置
下面的示例演示了如何通过将多个配置方法连锁在一起来创建综合配置。
完整示例
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
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);