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/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 属性

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

签名

brandedDomains: Array<string>

使用示例

// 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 属性

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

签名

clipboardAttribution: boolean

使用示例

// 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 属性

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

签名

collectOAID: boolean

使用示例

// 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 属性

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

签名

conversionValueUpdatedHandler: (conversionValue: number) => void

使用示例

// 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 属性

设置 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/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 属性

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

签名

customSdid: string

使用示例

// 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 属性

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

签名

customUserId: string

使用示例

// 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 属性

设置在全新安装后，Singular 仍会解析延迟深度链接并调用您的 singularLinkHandler 的时长。默认值为 60 秒。如果您的新手引导流程会让用户较晚到达深度链接目标页面，请调大该值；如果您宁愿丢弃过期的延迟链接而不是据此路由，请调小该值。

仅限 Android。在 iOS 上，withDDLTimeoutInSec() 只会输出一条日志，不会改变配置。iOS 上的对应功能是运行时方法 Singular.setDeferredDeepLinkTimeout()。小于或等于 0 的值会被忽略，并保留 60 秒的默认值。

签名

ddlTimeoutSec: number

使用示例

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 功能- 设置设备属性数据可用时调用的回调函数。

SingularConfig.deviceAttributionCallbackHandler 属性

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

仅包含有值的字段，因此读取前请先检查该键是否存在。大多数安装只会返回部分字段，具体包含哪些字段取决于 Singular 匹配到的触点。

键	类型	说明
`network`	string	回调触发时始终包含。未匹配到触点时为 "Organic"。
`campaign_id`	string	触点提供时包含。
`campaign_name`	string	触点提供时包含。
`subcampaign_id`	string	触点提供时包含。并非所有来源都会提供。
`subcampaign_name`	string	触点提供时包含。并非所有来源都会提供。
`creative_id`	string	触点提供时包含。并非所有来源都会提供。
`creative_name`	string	触点提供时包含。并非所有来源都会提供。
`passthrough`	string	链接附带透传值时包含。
`match_type`	string	触点提供时包含。如需取值列表，请联系 Singular。
`click_timestamp`	number	触点提供时包含。为 epoch 微秒，除以 1,000,000 可换算为秒。

签名

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

使用示例

// 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

- 设置自定义 SDID 时调用的回调。

SingularConfig.didSetSdidCallback 属性

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

签名

didSetSdidCallback: (result: string) => void

使用示例

// 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 属性

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

平台:Android 和 iOS。iOS 支持在 React Native SDK 4.3.0 中新增；此前的版本在 iOS 上会忽略此属性。请与 logLevel 搭配使用以控制详细程度。

签名

enableLogging: boolean

使用示例

// 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 属性

启用 Google 的 On-Device Measurement（ODM），并设置 SDK 在发送首次会话前等待 Google 归因令牌的秒数。默认值为 -1，表示禁用 ODM。Google Ads iOS Integrated Conversion Measurement（ICM）需要此设置。

仅限 iOS，且会延迟首次会话。SDK 会阻塞会话，直到 Google 返回归因令牌或该时间间隔结束，因此深度链接回调最多会被推迟这么多秒。ODM 还需要 Google 的 ODM SDK、-ObjC 链接器标志，以及 React Native SDK v3.9.0 或更高版本。请在初次集成时就完成配置，而不是后期再添加。

签名

enableOdmWithTimeoutInterval: number

使用示例

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 属性

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

签名

espDomains: Array<string>

使用示例

// 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 属性

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

签名

facebookAppId: string

使用示例

// 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 属性

在 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/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 属性

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

签名

limitAdvertisingIdentifiers: boolean

使用示例

// 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 属性

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

签名

limitDataSharing: boolean | null

使用示例

// 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 属性

设置 SDK 日志输出的详细程度。仅当 enableLogging 为 true 时生效。取值为 Android android.util.Log 标准常量，数值越小越详细：2 VERBOSE、3 DEBUG、4 INFO、5 WARN、6 ERROR、7 ASSERT。默认值为 6（ERROR）。

4.3.0 新增 iOS 支持。此前的版本在 iOS 上会同时忽略 logLevel 和 enableLogging。从 4.3.0 起，iOS 桥接会将 Android 风格的值映射到原生 iOS 日志级别： 2 Verbose、3 Debug、4 Info、5 Warning、6 Error，而 7 会关闭日志。其他任何值（包括负值）都会回退为 Error。

请注意范围上限的差异：在 Android 上 7 表示 ASSERT，而在 iOS 上会完全停用日志。

签名

logLevel: number

使用示例

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 属性

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

签名

manualSkanConversionManagement: boolean

使用示例

// 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 属性

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

签名

pushNotificationsLinkPaths: Array<Array<string>>

使用示例

// 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

- 收到 SDID 时调用的回调。

SingularConfig.sdidReceivedCallback 属性

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

签名

sdidReceivedCallback: (result: string) => void

使用示例

// 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 属性

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

签名

secret: string

使用示例

// 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 属性

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

签名

sessionTimeout: number

使用示例

// 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 属性

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

签名

shortLinkResolveTimeout: number

使用示例

// 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 属性

设置Singular链接（深层链接）的回调处理程序。解析深层链接时会调用该回调，以便在应用程序中处理深层链接数据。

签名

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

使用示例

// 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 属性

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

签名

skAdNetworkEnabled: boolean

使用示例

// 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 属性

将哈希后的电子邮件地址和/或电话号码附加到 SDK 发送的第一个会话中。请赋值一个 SingularUserDetails 对象，或使用 withUserDetails() 构建器进行设置。SDK 会在设备上对明文值进行规范化并使用 SHA-256 哈希，因此原始的电子邮件地址和电话号码不会被传输。设置用户 ID 和哈希 User Details

适用版本: React Native SDK 4.3.0 及以上版本。

签名

userDetails: SingularUserDetails

使用示例

// 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 属性

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

签名

waitForTrackingAuthorizationWithTimeoutInterval: number

使用示例

// 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);

完整配置示例

完整的 SDK 配置

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

完整示例

// 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 - 配置方法参考

React Native SDK - 配置参考

apikey

SingularConfig.apikey 属性

签名

使用示例

brandedDomains

SingularConfig.brandedDomains 属性

签名

使用示例

clipboardAttribution

SingularConfig.clipboardAttribution 属性

签名

使用示例

collectOAID

SingularConfig.collectOAID 属性

签名

使用示例

conversionValueUpdatedHandler

SingularConfig.conversionValueUpdatedHandler 属性

签名

使用示例

conversionValuesUpdatedHandler

SingularConfig.conversionValuesUpdatedHandler 属性

签名

使用示例

customSdid

SingularConfig.customSdid 属性

签名

使用示例

customUserId

SingularConfig.customUserId 属性

签名

使用示例

ddlTimeoutSec

SingularConfig.ddlTimeoutSec 属性

签名

使用示例

deviceAttributionCallbackHandler

SingularConfig.deviceAttributionCallbackHandler 属性

签名

使用示例

didSetSdidCallback

SingularConfig.didSetSdidCallback 属性

签名

使用示例

enableLogging

SingularConfig.enableLogging 属性

签名

使用示例

enableOdmWithTimeoutInterval

SingularConfig.enableOdmWithTimeoutInterval 属性

签名

使用示例

espDomains

SingularConfig.espDomains 属性

签名

使用示例

facebookAppId

SingularConfig.facebookAppId 属性

签名

使用示例

globalProperties

SingularConfig.globalProperties 属性

签名

使用示例

limitAdvertisingIdentifiers

SingularConfig.limitAdvertisingIdentifiers 属性

签名

使用示例

limitDataSharing

SingularConfig.limitDataSharing 属性

签名

使用示例

logLevel

SingularConfig.logLevel 属性

签名

使用示例

manualSkanConversionManagement

SingularConfig.manualSkanConversionManagement 属性