React Native SDK - 方法参考

本综合参考文档记录了用于 React Native 应用程序的 Singular SDK 中的所有可用方法。SDK 提供了初始化、事件跟踪、收入报告、归因、数据隐私合规性和配置等功能。每个方法都附有说明、签名和实际使用示例，以帮助开发人员将 Singular SDK 功能集成到他们的 React Native 应用程序中。

adRevenue

Singular.adRevenue 方法

通过详细的广告数据信息跟踪广告收入事件。通过该方法，您可以报告应用程序中显示的广告所产生的收入，并使用各种参数对广告性能进行分类和分析。

签名

static adRevenue(adData: {
  ad_platform: string; 
  ad_currency: string; 
  ad_revenue: number; 
  [key: string]: any;
}): void

必填属性

ad_platform (字符串）：产生广告收入的广告平台（如 "AdMob"、"Facebook"、"UnityAds"）。
ad_currency (字符串）：报告广告收入的货币代码（ISO 4217 格式）（如 "美元"、"欧元"）。
ad_revenue (数字）：广告展示产生的收入金额。

可选属性

ad_unit_id (字符串）：显示广告的广告单元的唯一标识符。
ad_type (字符串）：广告的类型或格式（如 "奖励"、"插播"、"横幅"）。
ad_placement_name (字符串）：广告放置在应用程序中的名称或位置标识符（如 "level_complete"、"main_menu"）。
ad_mediation_platform (字符串）：用于提供广告的广告中介平台（如 "admob"、"ironsource"、"max"）。
ad_impression_id (字符串）：特定广告展示事件的唯一标识符。
ad_group_type (字符串）：广告组的类型或类别分类。
ad_unit_name (字符串）：分配给广告组的可读名称：分配给广告单元的可读名称。
ad_group_id (string)：与此展示相关联的广告组的唯一标识符。
ad_group_name (字符串)：广告组的可读名称。
ad_group_priority (数字）：为广告组分配的用于瀑布流排序的数字优先级。
ad_precision (字符串）：广告收入数据的精确度或准确度级别（如 "估计"、"精确"、"publisher_defined"）。
ad_placement_id (字符串）：应用程序中广告投放位置的唯一标识符。

使用示例

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

const adData = {
  ad_platform: 'AdMob',
  ad_currency: 'USD',
  ad_revenue: 0.05,
  ad_unit_id: 'ca-app-pub-1234567890123456',
  ad_type: 'Rewarded',
  ad_placement_name: 'level_complete'
};

NativeSingular.adRevenue(adData);

import { Singular } from 'singular-react-native';

// Track ad revenue event
const adData = {
  ad_platform: 'AdMob',
  ad_currency: 'USD',
  ad_revenue: 0.05,
  ad_unit_id: 'ca-app-pub-1234567890123456',
  ad_type: 'Rewarded',
  ad_placement_name: 'level_complete'
};

Singular.adRevenue(adData);

clearGlobalProperties

Singular.clearGlobalProperties 方法

删除所有先前设置的全局属性。这在需要重置全局属性时非常有用，例如当用户注销应用程序时。

签名

static clearGlobalProperties(): void

使用示例

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

// Clear all global properties
NativeSingular.clearGlobalProperties();

import { Singular } from 'singular-react-native';

// Clear all global properties
Singular.clearGlobalProperties();

clearUserDetails

Singular.clearUserDetails 方法

删除已存储的哈希 User Details。这些值会持久保存在设备上（iOS 使用 Keychain，Android 使用加密存储），因此在被清除之前会跨应用启动保留。请在注销时或用户撤回同意时调用。

适用版本: React Native SDK 4.3.0 及以上版本。此方法在 init() 之前无效，原生 SDK 会记录错误并返回。它也是从 React Native 中删除已存储 User Details 的唯一方式；向 setUserDetails() 传入空对象不会清除它们。

签名

static clearUserDetails(): void

使用示例

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
// Remove stored user details on logout
NativeSingular.clearUserDetails();

import { Singular } from 'singular-react-native';
// Remove stored user details on logout
Singular.clearUserDetails();

createReferrerShortLink

Singular.createReferrerShortLink 方法

创建带有推荐人信息的短链接，可用于共享和归因。此方法可生成可与用户共享的可跟踪链接，从而将安装和活动归因于特定的推荐来源。

签名

static createReferrerShortLink(
  baseLink: string,
  referrerName: string,
  referrerId: string,
  passthroughParams: Record<string, any>,
  completionHandler: (data: string | null, error?: string) => void
): void

使用示例

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

// Create a short link for referral
NativeSingular.createReferrerShortLink(
  'https://sample.sng.link/B4tbmv8fp',
  'John Doe',
  'aq239897',
  { channel: 'sms', campaign: 'summer_promo' },
  (result: string, error: string) => {
    if (error) {
      console.error('Short link creation failed:', error);
    } else {
      console.log('Short link created successfully:', result);
    }
  }
);

import { Singular } from 'singular-react-native';

// Create a short link for referral
Singular.createReferrerShortLink(
  'https://sample.sng.link/B4tbmv8fp',
  'John Doe',
  'aq239897',
  { channel: 'sms', campaign: 'summer_promo' },
  (link, error) => {
    if (error) {
      console.error('Error creating short link:', error);
    } else if (link) {
      console.log('Generated short link:', link);
      // Share the link with users
    }
  }
);

customRevenue

Singular.customRevenue 方法

使用指定的事件名称、货币和金额跟踪自定义收入事件。这允许使用自定义事件名称进行更具体的收入跟踪。

签名

static customRevenue(
  eventName: string,
  currency: string,
  amount: number
): void

使用示例

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

// Track a custom revenue event
NativeSingular.customRevenue('premium_subscription', 'USD', 9.99);

import { Singular } from 'singular-react-native';

// Track a custom revenue event
Singular.customRevenue('premium_subscription', 'USD', 9.99);

customRevenueWithArgs

Singular.customRevenueWithArgs 方法

使用指定的事件名称、货币、金额和附加属性跟踪自定义收入事件。这允许使用自定义参数进行更详细的收入跟踪。

签名

static customRevenueWithArgs(
  eventName: string,
  currency: string,
  amount: number,
  args: Record<string, any>
): void

使用示例

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

// Track a custom revenue event with attributes
NativeSingular.customRevenueWithArgs(
  'in_app_purchase',
  'USD',
  5.99,
  {
    product_id: 'com.app.gems_pack_small',
    quantity: 1
  }
);

import { Singular } from 'singular-react-native';

// Track a custom revenue event with attributes
Singular.customRevenueWithArgs(
  'in_app_purchase',
  'USD',
  5.99,
  {
    product_id: 'com.app.gems_pack_small',
    quantity: 1
  }
);

event

Singular.event 方法

跟踪具有指定名称的事件。使用该方法可跟踪应用程序中的用户操作和参与情况。

签名

static event(eventName: string): void

使用示例

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

// Track a simple event
NativeSingular.event('level_completed');

import { Singular } from 'singular-react-native';

// Track a simple event
Singular.event('level_completed');

eventWithArgs

Singular.eventWithArgs 方法

跟踪具有指定名称和附加自定义属性的事件。使用此方法可跟踪具有详细参数的用户操作。

签名

static eventWithArgs(
  eventName: string,
  args: Record<string, any>
): void

使用示例

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

// Track an event with additional parameters
NativeSingular.eventWithArgs('level_completed', {
  level_id: 5,
  score: 12500,
  time_spent: 120,
  difficulty: 'medium'
});

import { Singular } from 'singular-react-native';

// Track an event with additional parameters
Singular.eventWithArgs('level_completed', {
  level_id: 5,
  score: 12500,
  time_spent: 120,
  difficulty: 'medium'
});

getGlobalProperties

Singular.getGlobalProperties 方法

读取当前设置的所有全局属性。此方法返回一个承诺，该承诺解析为一个对象，其中包含已为 SDK 设置的所有全局属性。

签名

static getGlobalProperties(): SerializableObject

使用示例

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

// Get all global properties
NativeSingular.getGlobalProperties();

import { Singular } from 'singular-react-native';

// Get all global properties
Singular.getGlobalProperties();

getLimitDataSharing

Singular.getLimitDataSharing 方法

读取当前的数据共享限制状态。此方法返回一个承诺，该承诺解析为一个布尔值，表示当前数据共享是否受限。

签名

static getLimitDataSharing(): boolean

使用示例

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

// Check if data sharing is limited
NativeSingular.getLimitDataSharing();

import { Singular } from 'singular-react-native';

// Check if data sharing is limited
Singular.getLimitDataSharing();

handlePushNotification

Singular.handlePushNotification 方法

处理推送通知的有效载荷以确定属性。当应用程序收到推送通知时，应调用此方法，以便 Singular 能正确归因该通知。此方法仅适用于 iOS。

签名

static handlePushNotification(
  pushNotificationPayload: Record<string, any>
): void

使用示例

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

// Handle a received push notification (iOS only)
if (Platform.OS === 'ios') {
  const userInfo = remoteMessage.data;
  NativeSingular.handlePushNotification(userInfo);
}

import { Singular } from 'singular-react-native';
import { Platform } from 'react-native';

// Handle a received push notification (iOS only)
if (Platform.OS === 'ios') {
  const userInfo = remoteMessage.data;
  Singular.handlePushNotification(userInfo);
}

inAppPurchase

Singular.inAppPurchase 方法

向 Singular 报告收入，并在后台执行收据验证（如果启用）。购买对象应为 SingularIOSPurchase 或 SingularAndroidPurchase 类型。

签名

static inAppPurchase(
  eventName: string,
  purchase: SingularIOSPurchase | SingularAndroidPurchase
): void

SingularIOSPurchase 购买类构造函数

constructor(
  revenue: number,
  currency: string,
  productId: string,
  transactionId: string,
  receipt: string
)

SingularAndroidPurchase 购买类构造函数

constructor(
  revenue: number,
  currency: string,
  receipt: string,
  signature: string
)

使用示例

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

// iOS Example
if (Platform.OS === 'ios') {
  const iosPurchase = new SingularIOSPurchase(
    99.99,              // revenue
    'USD',              // currency
    'premium_bundle',   // productId
    'trans_12345',      // transactionId
    'base64receipt...'  // receipt
  );
  
  // Convert to plain object for TurboModule
  NativeSingular.inAppPurchase('purchase', iosPurchase.toSpecObject());
}

// Android Example
if (Platform.OS === 'android') {
  const androidPurchase = new SingularAndroidPurchase(
    99.99,                    // revenue
    'USD',                    // currency
    'purchaseDataJSON',       // receipt
    'signatureString'         // signature
  );
  
  // Convert to plain object for TurboModule
  NativeSingular.inAppPurchase('purchase', androidPurchase.toSpecObject());
}

import { Singular, SingularIOSPurchase, SingularAndroidPurchase } from 'singular-react-native';
import { Platform } from 'react-native';

// iOS Example
if (Platform.OS === 'ios') {
  const iosPurchase = new SingularIOSPurchase(
    99.99,              // revenue
    'USD',              // currency
    'premium_bundle',   // productId
    'trans_12345',      // transactionId
    'base64receipt...'  // receipt
  );
  Singular.inAppPurchase('purchase', iosPurchase);
}

// Android Example
if (Platform.OS === 'android') {
  const androidPurchase = new SingularAndroidPurchase(
    99.99,                    // revenue
    'USD',                    // currency
    'purchaseDataJSON',       // receipt
    'signatureString'         // signature
  );
  Singular.inAppPurchase('purchase', androidPurchase);
}

inAppPurchaseWithArgs

Singular.inAppPurchaseWithArgs 方法

向 Singular 报告收入及附加属性，并在后台执行收据验证（如果启用）。购买对象应为 SingularIOSPurchase 或 SingularAndroidPurchase 类型。

签名

static inAppPurchaseWithArgs(
  eventName: string,
  purchase: SingularIOSPurchase | SingularAndroidPurchase,
  args: Record<string, any>
): void

SingularIOSPurchase 购买类构造函数

constructor(
  revenue: number,
  currency: string,
  productId: string,
  transactionId: string,
  receipt: string
)

SingularAndroidPurchase 购买类构造函数

constructor(
  revenue: number,
  currency: string,
  receipt: string,
  signature: string
)

使用示例

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

// iOS Example - Track IAP with additional attributes
if (Platform.OS === 'ios') {
  const iosPurchase = new SingularIOSPurchase(
    99.99,              // revenue
    'USD',              // currency
    'premium_bundle',   // productId
    'trans_12345',      // transactionId
    'base64receipt...'  // receipt
  );
  
  // Convert to plain object for TurboModule
  NativeSingular.inAppPurchaseWithArgs(
    'purchase',
    iosPurchase.toSpecObject(),
    {
      product_category: 'premium_content',
      is_first_purchase: true,
      user_tier: 'gold'
    }
  );
}

// Android Example - Track IAP with additional attributes
if (Platform.OS === 'android') {
  const androidPurchase = new SingularAndroidPurchase(
    99.99,                    // revenue
    'USD',                    // currency
    'purchaseDataJSON',       // receipt
    'signatureString'         // signature
  );
  
  // Convert to plain object for TurboModule
  NativeSingular.inAppPurchaseWithArgs(
    'purchase',
    androidPurchase.toSpecObject(),
    {
      product_category: 'premium_content',
      is_first_purchase: true,
      user_tier: 'gold'
    }
  );
}

import { Singular, SingularIOSPurchase, SingularAndroidPurchase } from 'singular-react-native';
import { Platform } from 'react-native';

// iOS Example - Track IAP with additional attributes
if (Platform.OS === 'ios') {
  const iosPurchase = new SingularIOSPurchase(
    99.99,              // revenue
    'USD',              // currency
    'premium_bundle',   // productId
    'trans_12345',      // transactionId
    'base64receipt...'  // receipt
  );
  
  Singular.inAppPurchaseWithArgs('purchase', iosPurchase, {
    product_category: 'premium_content',
    is_first_purchase: true,
    user_tier: 'gold'
  });
}

// Android Example - Track IAP with additional attributes
if (Platform.OS === 'android') {
  const androidPurchase = new SingularAndroidPurchase(
    99.99,                    // revenue
    'USD',                    // currency
    'purchaseDataJSON',       // receipt
    'signatureString'         // signature
  );
  
  Singular.inAppPurchaseWithArgs('purchase', androidPurchase, {
    product_category: 'premium_content',
    is_first_purchase: true,
    user_tier: 'gold'
  });
}

init

Singular.init 方法

使用提供的配置初始化 Singular SDK。这是开始使用 Singular SDK 时应调用的第一个方法。

签名

static init(singularConfig: SingularConfig): 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';

// Create configuration object
const config: SingularConfig = {
  apikey: 'YOUR_API_KEY',
  secret: 'YOUR_SECRET',
  customUserId: 'user-123456',
  sessionTimeout: 60,
  enableLogging: true,
  logLevel: 3,
}

// Initialize the SDK
NativeSingular.init(config);

import { Singular, SingularConfig } from 'singular-react-native';

// Create configuration object
const config = new SingularConfig('YOUR_API_KEY', 'YOUR_SECRET');

// Configure additional options if needed
config.customUserId = 'user-123456';
config.sessionTimeout = 60;
config.enableLogging = true;
config.logLevel = 3;

// Initialize the SDK
Singular.init(config);

isAllTrackingStopped

Singular.isAllTrackingStopped 方法

检查当前是否停止了所有跟踪。此方法返回一个解析为布尔值的 promise，表示当前是否停止了跟踪。

签名

static isAllTrackingStopped(): boolean

使用示例

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

// Check if tracking is stopped
NativeSingular.isAllTrackingStopped();

import { Singular } from 'singular-react-native';

// Check if tracking is stopped
Singular.isAllTrackingStopped();

limitDataSharing

Singular.limitDataSharing 方法

设置数据共享限制状态。使用该方法可根据用户同意或隐私要求限制数据共享。

签名

static limitDataSharing(limitDataSharingValue: boolean): void

使用示例

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

// To limit data sharing (e.g., when user opts out)
NativeSingular.limitDataSharing(true);

// To enable full data sharing (e.g., when user opts in)
NativeSingular.limitDataSharing(false);

import { Singular } from 'singular-react-native';

// To limit data sharing (e.g., when user opts out)
Singular.limitDataSharing(true);

// To enable full data sharing (e.g., when user opts in)
Singular.limitDataSharing(false);

resumeAllTracking

Singular.resumeAllTracking 方法

恢复之前停止的所有跟踪活动。使用该方法可在停止跟踪后重新启用跟踪。

签名

static resumeAllTracking(): void

使用示例

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

// Resume tracking when user opts back in
NativeSingular.resumeAllTracking();

import { Singular } from 'singular-react-native';

// Resume tracking when user opts back in
Singular.resumeAllTracking();

revenue

Singular.revenue 方法

使用货币和金额跟踪收入事件。这可让您的应用程序进行基本的收入跟踪。

签名

static revenue(currency: string, amount: number): void

使用示例

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

// Track revenue with currency and amount
NativeSingular.revenue('USD', 9.99);

import { Singular } from 'singular-react-native';

// Track revenue with currency and amount
Singular.revenue('USD', 9.99);

revenueWithArgs

Singular.revenueWithArgs 方法

跟踪带有货币、金额和附加属性的收入事件。通过该方法可使用自定义参数进行全面的收入跟踪。

签名

static revenueWithArgs(
  currency: string,
  amount: number,
  args: Record<string, any>
): void

使用示例

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

// Track revenue with additional attributes
NativeSingular.revenueWithArgs('USD', 19.98, {
  product_id: 'premium_gems',
  quantity: 2
});

import { Singular } from 'singular-react-native';

// Track revenue with additional attributes
Singular.revenueWithArgs('USD', 19.98, {
  product_id: 'premium_gems',
  quantity: 2
});

setCustomUserId

Singular.setCustomUserId 方法

为当前用户设置自定义用户 ID。这样就可以将 Singular 数据与自己的用户识别系统关联起来。

签名

static setCustomUserId(customUserId: string): void

使用示例

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

// Set custom user ID after user logs in
NativeSingular.setCustomUserId('user123456');

import { Singular } from 'singular-react-native';

// Set custom user ID after user logs in
Singular.setCustomUserId('user123456');

setDeferredDeepLinkTimeout

Singular.setDeferredDeepLinkTimeout 方法

设置在全新安装后，Singular 仍会解析延迟深度链接并调用您的 singularLinkHandler 的时长。默认值为 60 秒。

仅限 iOS，且必须在 Singular.init() 之前调用。该时间窗口在发送首次会话时评估，因此初始化之后再调用对该次安装不会产生任何影响。在 Android 上此方法只会输出一条日志而不执行任何操作，请改用 ddlTimeoutSec 配置属性。小于 5 秒的时长会被忽略，并保留先前的值。

签名

static setDeferredDeepLinkTimeout(duration: number): void

使用示例

import NativeSingular from 'singular-react-native/js/NativeSingular';

// Call before initializing the SDK
NativeSingular.setDeferredDeepLinkTimeout(120);

import { Singular, SingularConfig } from 'singular-react-native';

// Call before initializing the SDK
Singular.setDeferredDeepLinkTimeout(120);

const config = new SingularConfig('API_KEY', 'SECRET');
Singular.init(config);

setDeviceCustomUserId

此方法已废弃，不再使用。

Singular.setDeviceCustomUserId 方法

在设备级别设置自定义用户 ID。这样就可以在设备级别将 Singular 数据与自己的用户识别系统关联起来。

签名

static setDeviceCustomUserId(customUserId: string): void

使用示例

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

// Set device-level custom user ID
NativeSingular.setDeviceCustomUserId('device_user_123456');

import { Singular } from 'singular-react-native';

// Set device-level custom user ID
Singular.setDeviceCustomUserId('device_user_123456');

setGlobalProperty

Singular.setGlobalProperty 方法

设置将与所有事件一起发送的全局属性。这样，您就可以为所有事件添加一致的属性，而无需每次都指定这些属性。

签名

static setGlobalProperty(
  key: string,
  value: string,
  overrideExisting: boolean
): boolean

使用示例

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

// Set a global property
NativeSingular.setGlobalProperty(
  'user_tier',
  'premium',
  true
);

import { Singular } from 'singular-react-native';

// Set a global property
Singular.setGlobalProperty(
  'user_tier',
  'premium',
  true
);

setLimitAdvertisingIdentifiers

Singular.setLimitAdvertisingIdentifiers 方法

启用或禁用限制广告标识符模式。该选项会影响 SDK 收集和使用设备标识符进行跟踪的方式。

签名

static setLimitAdvertisingIdentifiers(enabled: boolean): void

使用示例

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

// Enable limited identifiers mode
NativeSingular.setLimitAdvertisingIdentifiers(true);

// Disable limited identifiers mode
NativeSingular.setLimitAdvertisingIdentifiers(false);

import { Singular } from 'singular-react-native';

// Enable limited identifiers mode
Singular.setLimitAdvertisingIdentifiers(true);

// Disable limited identifiers mode
Singular.setLimitAdvertisingIdentifiers(false);

setUserDetails

Singular.setUserDetails 方法

在初始化之后将哈希后的电子邮件地址和/或电话号码发送到 Singular。SDK 会在设备上对明文值进行规范化并使用 SHA-256 哈希，因此原始的电子邮件地址和电话号码不会被传输。如果想改为将 User Details 附加到第一个会话，请参阅设置用户 ID 和哈希 User Details，并在 init() 之前设置 SingularConfig.userDetails。

适用版本: React Native SDK 4.3.0 及以上版本。此方法在 init() 之前无效，原生 SDK 会记录错误并返回。JavaScript 层会拒绝 null 或缺失的参数，因此请使用 clearUserDetails() 来删除已存储的值。

签名

static setUserDetails(userDetails: SingularUserDetails): void

使用示例

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
// Cleartext values, hashed on the device by the SDK
NativeSingular.setUserDetails({
  email: 'user@example.com',
  phoneNumber: '+15551234567'
});
// Or supply your own SHA-256 hashes
NativeSingular.setUserDetails({
  emailSTD: 'b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514',
  phoneE164: '8a59780bb8cd2ba022bfa5ba2ea3b6e07af17a7d8b30c1f9b3390e36f69019e4'
});

import { Singular, SingularUserDetails } from 'singular-react-native';
// Cleartext values, hashed on the device by the SDK
const userDetails = new SingularUserDetails()
  .setEmail('user@example.com')
  .setPhoneNumber('+15551234567');
Singular.setUserDetails(userDetails);
// Or supply your own SHA-256 hashes
const hashed = new SingularUserDetails()
  .setEmailSTD('b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514')
  .setPhoneE164('8a59780bb8cd2ba022bfa5ba2ea3b6e07af17a7d8b30c1f9b3390e36f69019e4');
Singular.setUserDetails(hashed);

setUninstallToken

Singular.setUninstallToken 方法

为卸载跟踪注册推送通知令牌。调用此方法时应同时调用推送通知令牌，以启用卸载跟踪功能。

签名

static setUninstallToken(token: string): void

使用示例

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

// Register device token for uninstall tracking
NativeSingular.setUninstallToken(token);

import { Singular } from 'singular-react-native';
import messaging from '@react-native-firebase/messaging';

// Register device token for uninstall tracking
Singular.setUninstallToken(token);

skanGetConversionValue

Singular.skanGetConversionValue 方法

读取当前 SKAdNetwork 转换值。此方法返回一个承诺，该承诺解析为用于 SKAdNetwork 归因的当前转换值。此方法仅限 iOS。

签名

static skanGetConversionValue(): number | null

使用示例

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

// Get the current SKAdNetwork conversion value (iOS only)
if (Platform.OS === 'ios') {
  const conversionValue = NativeSingular.skanGetConversionValue();
  console.log('Current conversion value:', conversionValue ?? 0);
}

import { Singular } from 'singular-react-native';
import { Platform } from 'react-native';

// Get the current SKAdNetwork conversion value (iOS only)
if (Platform.OS === 'ios') {
  const conversionValue = Singular.skanGetConversionValue();
  console.log('Current conversion value:', conversionValue ?? 0);
}

skanRegisterAppForAdNetworkAttribution

Singular.skanRegisterAppForAdNetworkAttribution 方法

为 SKAdNetwork 归因注册应用程序。调用此方法可在 iOS 上启用 SKAdNetwork 归因。本方法仅适用于 iOS。

签名

static skanRegisterAppForAdNetworkAttribution(): void

使用示例

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

// Register for SKAdNetwork attribution (iOS only)
if (Platform.OS === 'ios') {
  NativeSingular.skanRegisterAppForAdNetworkAttribution();
}

import { Singular } from 'singular-react-native';
import { Platform } from 'react-native';

// Register for SKAdNetwork attribution (iOS only)
if (Platform.OS === 'ios') {
  Singular.skanRegisterAppForAdNetworkAttribution();
}

skanUpdateConversionValue

Singular.skanUpdateConversionValue 方法

更新 SKAdNetwork 转换值。此方法允许您手动更新用于 SKAdNetwork 归因的转换值。此方法仅限 iOS。

签名

static skanUpdateConversionValue(conversionValue: number): boolean

使用示例

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

// Update the SKAdNetwork conversion value (iOS only)
if (Platform.OS === 'ios') {
  const success = NativeSingular.skanUpdateConversionValue(5);
  if (success) {
    console.log('Conversion value updated successfully');
  }
}

import { Singular } from 'singular-react-native';
import { Platform } from 'react-native';

// Update the SKAdNetwork conversion value (iOS only)
if (Platform.OS === 'ios') {
  const success = Singular.skanUpdateConversionValue(5);
  if (success) {
    console.log('Conversion value updated successfully');
  }
}

skanUpdateConversionValues

Singular.skanUpdateConversionValues 方法

用精细值、粗略值和锁定参数更新 SKAdNetwork 4.0 转换值。此方法适用于 iOS 16.1+ 并仅限 iOS。

签名

static skanUpdateConversionValues(
  conversionValue: number,
  coarse: number,
  lock: boolean
): void

使用示例

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

// Update SKAdNetwork 4.0 conversion values (iOS 16.1+)
if (Platform.OS === 'ios') {
  NativeSingular.skanUpdateConversionValues(
    5,     // fine value (0-63)
    1,     // coarse value (0=low, 1=medium, 2=high)
    false  // lock
  );
}

import { Singular } from 'singular-react-native';
import { Platform } from 'react-native';

// Update SKAdNetwork 4.0 conversion values (iOS 16.1+)
if (Platform.OS === 'ios') {
  Singular.skanUpdateConversionValues(
    5,     // fine value (0-63)
    1,     // coarse value (0=low, 1=medium, 2=high)
    false  // lock
  );
}

stopAllTracking

Singular.stopAllTracking 方法

停止所有跟踪活动。使用该方法可在用户选择退出或符合隐私保护规定时禁用跟踪。

签名

static stopAllTracking(): void

使用示例

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

// Stop tracking when user opts out
NativeSingular.stopAllTracking();

import { Singular } from 'singular-react-native';

// Stop tracking when user opts out
Singular.stopAllTracking();

trackingOptIn

Singular.trackingOptIn 方法

表示用户已选择接受跟踪。当用户明确同意跟踪和数据收集时调用此方法。

签名

static trackingOptIn(): void

使用示例

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

// User has opted in to tracking
NativeSingular.trackingOptIn();

import { Singular } from 'singular-react-native';

// User has opted in to tracking
Singular.trackingOptIn();

trackingUnder13

Singular.trackingUnder13 方法

表示用户未满 13 周岁。调用此方法可遵守 COPPA 和其他针对 13 岁以下用户的规定。

签名

static trackingUnder13(): void

使用示例

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

// Notify Singular the user is under 13 years old
NativeSingular.trackingUnder13();

import { Singular } from 'singular-react-native';

// Notify Singular the user is under 13 years old
Singular.trackingUnder13();

unsetCustomUserId

Singular.unsetCustomUserId 方法

删除之前设置的自定义用户 ID。当用户注销或不想再将事件与当前用户 ID 关联时，调用此方法。

签名

static unsetCustomUserId(): void

使用示例

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

// Clear custom user ID when user logs out
NativeSingular.unsetCustomUserId();

import { Singular } from 'singular-react-native';

// Clear custom user ID when user logs out
Singular.unsetCustomUserId();

unsetGlobalProperty

Singular.unsetGlobalProperty 方法

删除先前设置的全局属性。如果不想再通过事件发送特定全局属性，请调用此方法。

签名

static unsetGlobalProperty(key: string): void

使用示例

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

// Remove a global property
NativeSingular.unsetGlobalProperty('user_tier');

import { Singular } from 'singular-react-native';

// Remove a global property
Singular.unsetGlobalProperty('user_tier');