React Native SDK - 配置方法参考

文档

React Native SDK - 配置参考

本文档全面介绍了用于 React Native 应用程序的 Singular SDK 中的所有配置选项。通过 SingularConfig 对象,您可以自定义 SDK 的行为,包括跟踪设置、属性选项、隐私控制等。每个配置属性都附有说明、签名和实际使用示例。

apikey

SingularConfig.apikey 属性

你的 Singular API 密钥。这是配置初始化过程中必须设置的属性。

签名

apikey: string

使用示例

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

品牌域名

SingularConfig.brandedDomains 属性

为网络到应用程序属性设置品牌域。这允许你指定为归因目的而跟踪的自定义域名。

签名

brandedDomains: Array<string>

使用示例

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

剪贴板属性

SingularConfig.clipboardAttribution 属性

启用 iOS 的剪贴板属性。启用后,SDK 将检查剪贴板中的属性数据。可使用 withClipboardAttribution() 方法启用。

签名

clipboardAttribution: boolean

使用示例

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

collectOAID

SingularConfig.collectOAID 属性

为 Android 启用 OAID(开放式匿名设备标识符)收集功能。 该功能主要用于在无法使用 Google Play 服务的中国进行跟踪。默认值为 false。

签名

collectOAID: boolean

使用示例

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

conversionValueUpdatedHandler

SingularConfig.conversionValueUpdatedHandler 属性

设置 SKAdNetwork 转换值更新时调用的回调处理程序。这对跟踪 iOS 上转换值的变化非常有用。

签名

conversionValueUpdatedHandler: (conversionValue: number) => void

使用示例

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

conversionValuesUpdatedHandler

SingularConfig.conversionValuesUpdatedHandler 属性

设置 SKAdNetwork 4.0 转换值更新时调用的回调处理程序。该回调接收精细值、粗略值和 iOS 16.1+ 的锁定状态。

签名

conversionValuesUpdatedHandler: (updatedValues: Record<string, any>) => void

使用示例

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

自定义值

企业功能--请联系您的客户成功经理为您的账户启用此功能。

SingularConfig.customSdid 属性

设置自定义 SDID(Singular 设备 ID)。这允许您提供自己的设备标识符,而不是使用 Singular 生成的标识符。

签名

customSdid: string

使用示例

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

自定义用户标识

SingularConfig.customUserId 属性

在 SDK 初始化过程中设置自定义用户 ID。这样就可以从一开始就将 Singular 数据与自己的用户识别系统关联起来。

签名

customUserId: string

使用示例

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

deviceAttributionCallbackHandler

BETA 功能- 设置设备属性数据可用时调用的回调函数。

SingularConfig.deviceAttributionCallbackHandler 属性

设置设备属性数据可用时调用的回调处理程序。这样就可以在属性数据解析后立即访问。

签名

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

使用示例

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

didSetSdidCallback

企业功能- 设置自定义 SDID 时调用的回调。

SingularConfig.didSetSdidCallback 属性

设置自定义 SDID 设置时调用的回调函数,与 customSdid 属性结合使用。

签名

didSetSdidCallback: (result: string) => void

使用示例

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

启用记录

SingularConfig.enableLogging 属性

为调试目的启用 SDK 日志。这在开发和故障排除过程中非常有用。建议在生产构建中禁用日志记录。默认值为 false。

签名

enableLogging: boolean

使用示例

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

espDomains

SingularConfig.espDomains 属性

设置用于电子邮件归因的 ESP(电子邮件服务提供商)域。 这样就可以指定哪些电子邮件域应考虑用于归因跟踪。

签名

espDomains: Array<string>

使用示例

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

facebookAppId

SingularConfig.facebookAppId 属性

为 Facebook 归因整合设置 Facebook 应用程序 ID。这使 SDK 能够跟踪 Facebook 营销活动的归因。

签名

facebookAppId: string

使用示例

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

globalProperties

SingularConfig.globalProperties 属性

在 SDK 初始化过程中设置全局属性。这些属性将与 SDK 跟踪的所有事件一起发送。

签名

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

使用示例

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

limitAdvertisingIdentifiers

SingularConfig.limitAdvertisingIdentifiers 属性

在混合受众应用程序中启用限制广告标识符模式。 该选项会影响 SDK 收集和使用设备标识符进行跟踪的方式。默认值为 false。

签名

limitAdvertisingIdentifiers: boolean

使用示例

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

limitDataSharing

SingularConfig.limitDataSharing 属性

设置初始化时的数据共享限制状态。使用此属性可根据用户同意或隐私要求限制数据共享。默认值为空。

签名

limitDataSharing: boolean | null

使用示例

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

manualSkanConversionManagement

SingularConfig.manualSkanConversionManagement 属性

启用手动 SKAdNetwork 转换值管理。启用后,您将负责手动更新转换值。默认值为 false。

签名

manualSkanConversionManagement: boolean

使用示例

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

pushNotificationsLinkPaths

SingularConfig.pushNotificationsLinkPaths 属性

配置从推送通知有效负载中提取深度链接的自定义路径。这样就可以指定深层链接在通知有效负载中的位置。

签名

pushNotificationsLinkPaths: Array<Array<string>>

使用示例

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

sdidReceivedCallback

企业功能- 收到 SDID 时调用的回调。

SingularConfig.sdidReceivedCallback 属性

设置从服务器接收 SDID 时调用的回调函数。此属性与自定义 SDID 属性结合使用。

签名

sdidReceivedCallback: (result: string) => void

使用示例

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

秘密

SingularConfig.secret 属性

你的 Singular SDK 密钥。这是配置初始化时必须设置的属性。

签名

secret: string

使用示例

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

sessionTimeout

SingularConfig.sessionTimeout 属性

设置会话超时(以秒为单位)。这决定了应用程序进入后台后用户会话的持续时间。默认值为-1(使用默认超时 60 秒)。

签名

sessionTimeout: number

使用示例

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

shortLinkResolveTimeout

SingularConfig.shortLinkResolveTimeout 属性

设置短链接解析超时(以秒为单位)。这决定了 SDK 等待短链接解析的时间。默认值为 10 秒。

签名

shortLinkResolveTimeout: number

使用示例

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

singularLinkHandler

SingularConfig.singularLinkHandler 属性

设置奇异链接(深层链接)的回调处理程序。解析深层链接时会调用该回调,以便在应用程序中处理深层链接数据。

签名

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

使用示例

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

skAdNetworkEnabled

SingularConfig.skAdNetworkEnabled 属性

启用或禁用 iOS 上的 SKAdNetwork 归属。启用后,SDK 将自动处理 SKAdNetwork 归属。默认值为 true。

签名

skAdNetworkEnabled: boolean

使用示例

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

waitForTrackingAuthorizationWithTimeoutInterval

SingularConfig.waitForTrackingAuthorizationWithTimeoutInterval 属性

设置 iOS 上等待 ATT(应用程序跟踪透明度)授权的超时间隔。SDK 最多会等待这么多秒钟,等用户回复 ATT 提示后再继续。默认值为 0(不等待)。

签名

waitForTrackingAuthorizationWithTimeoutInterval: number

使用示例

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

完整配置示例

完整的 SDK 配置

下面的示例演示了如何通过将多个配置方法连锁在一起来创建综合配置。

完整示例

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