React Native SDK Methods Reference

This comprehensive reference documents all available methods in the Singular SDK for mobile app tracking. The SDK provides functionality for initialization, user identification, event tracking, revenue reporting, attribution, data privacy compliance, and configuration. Each method is presented with a description, signature, and practical usage examples to help developers integrate Singular's SDK capabilities into their applications.

adRevenue

Singular.adRevenue Method

Tracks ad revenue events with detailed ad data information.

Signature

static adRevenue(adData: SingularAdData): void

Usage Example

// Create ad data object 
const adData = new SingularAdData()
     .withAdPlatform("AdMob")
     .withAdType("Rewarded")
     .withAdNetworkName("Google")
     .withCurrency("USD")
     .withRevenue(0.05);

// Track ad revenue event
Singular.adRevenue(adData);

clearGlobalProperties

Singular.clearGlobalProperties Method

Removes all previously set global properties.

Signature

static clearGlobalProperties(): void

Usage Example

// Clear all global properties, for example when a user logs out 
Singular.clearGlobalProperties();

createReferrerShortLink

Singular.createReferrerShortLink Method

Creates a short link with referrer information that can be used for sharing and attribution.

Signature

static createReferrerShortLink(baseLink: string, referrerName: string, referrerId: string, passthroughParams: SerializableObject, completionHandler: (result: string, error: string) => void): void

Usage Example

Singular.createReferrerShortLink( 
        "https://sample.sng.link/B4tbm/v8fp?_dl=https%3A%2F%2Fabc.com", 
        "John Doe", // Referrer Name 
        "aq239897", // Referrer ID 
        { "channel": "sms", "campaign": "summer_promo" }, // Passthrough parameters 
        (shortLinkURL, error) => { if (error) { 
           console.error("Error creating short link:", error); return; }
           console.log("Generated short link:", shortLinkURL);
          // Share the link with users
     }
);

customRevenue

Singular.customRevenue Method

Tracks a custom revenue event with a specified event name, currency, and amount.

Custom Revenue Event Names are limited to 32 ASCII characters. For non-ASCII characters, the limit is 32 bytes once converted to UTF-8.
Currency Codes must be ALL CAPS and adhere to the three-letter ISO 4217 currency code

Signature

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

Usage Example

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

customRevenueWithArgs

Singular.customRevenueWithArgs Method

Tracks a custom revenue event with a specified event name, currency, amount, and additional custom attributes.

Custom Revenue Event Names are limited to 32 ASCII characters. For non-ASCII characters, the limit is 32 bytes once converted to UTF-8.
Event attribute names and attribute values are limited to 500 ASCII characters.
Currency Codes must be ALL CAPS and adhere to the three-letter ISO 4217 currency code

Signature

static customRevenueWithArgs(eventName: string, currency: string, amount: number, args: SerializableObject): void

Usage Example

// Track a custom revenue event with additional parameters 
Singular.customRevenueWithArgs( 
        "in_app_purchase", 
        "USD", 
        5.99, 
        { 
           "product_id": "com.app.gems_pack_small", 
           "quantity": 1, 
           "transaction_id": "T12345678", 
           "receipt_id": "R98765432" 
        }
);

event

Singular.event Method

Tracks a simple custom event with Singular's SDK.

Event Names are limited to 32 ASCII characters. For non-ASCII characters, the limit is 32 bytes once converted to UTF-8.

Signature

static event(eventName: string): void

Usage Example

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

eventWithArgs

Singular.eventWithArgs Method

Tracks a custom event with additional attributes with Singular's SDK.

Event Names are limited to 32 ASCII characters. For non-ASCII characters, the limit is 32 bytes once converted to UTF-8.
Event attribute names and attribute values are limited to 500 ASCII characters.

Signature

static eventWithArgs(eventName: string, args: SerializableObject): void

Usage Example

// Track an event with additional parameters 
Singular.eventWithArgs(
        "level_completed", 
        { 
           "level_number": 5, 
           "difficulty": "hard", 
           "time_spent": 120, 
           "score": 9500 
        }
);

getLimitDataSharing

Singular.getLimitDataSharing Method

Gets the current data sharing limitation status for the user.

Signature

static getLimitDataSharing(): boolean

Usage Example

// Check if data sharing is limited 
const isLimited = Singular.getLimitDataSharing(); 
console.log("Data sharing limitation status:", isLimited);

// Use the status to adjust app behavior
if (isLimited) {
     // Adjust functionality for users with limited data sharing
}

getGlobalProperties

Singular.getGlobalProperties Method

Retrieves all currently set global properties.

Signature

static getGlobalProperties(): Map<string, string>

Usage Example

// Get all global properties 
const properties = Singular.getGlobalProperties();
        
     // Iterate through properties
     properties.forEach((value, key) => {
        console.log(${key}: ${value});
     });

inAppPurchase

Singular.inAppPurchase Method

This method requires using React Native's In-App Purchase package to manage transactions in your app.

Tracks an in-app purchase event with purchase details.

Event Names are limited to 32 ASCII characters. For non-ASCII characters, the limit is 32 bytes once converted to UTF-8.

Signature

static inAppPurchase(eventName: string, purchase: SingularPurchase): void

Usage Example

// Add the Singular Purchase Class imports
import { 
        Singular, 
        SingularConfig, 
        Events, 
        SingularPurchase, 
        SingularIOSPurchase, 
        SingularAndroidPurchase } from 'singular-react-native';
  
// Create purchase object
let singularPurchase = null;
  
if (Platform.OS === 'ios') {
   singularPurchase = new SingularIOSPurchase(
     product.revenue,
     product.currency,
     purchase.productId,
     purchase.transactionId,
     purchase.transactionReceipt,
   );
  } else if (Platform.OS === 'android'){
   singularPurchase = new SingularAndroidPurchase(
     product.revenue,
     product.currency,
     purchase.transactionReceipt,
     purchase.signatureAndroid,
   );
}
  
// Track in-app purchase
Singular.inAppPurchase('iap_purchase', singularPurchase);

inAppPurchaseWithArgs

Singular.inAppPurchaseWithArgs Method

This method requires using React Native's In-App Purchase package to manage transactions in your app.

Tracks an in-app purchase event with purchase details and additional custom attributes.

Event Names are limited to 32 ASCII characters. For non-ASCII characters, the limit is 32 bytes once converted to UTF-8.
Event attribute names and attribute values are limited to 500 ASCII characters.

Signature

static inAppPurchaseWithArgs(eventName: string, purchase: SingularPurchase, args: SerializableObject): void

Usage Example

// Add the Singular Purchase Class imports
import { 
        Singular, 
        SingularConfig, 
        Events, 
        SingularPurchase, 
        SingularIOSPurchase, 
        SingularAndroidPurchase } from 'singular-react-native';
  
// Create purchase object
let singularPurchase = null;
  
if (Platform.OS === 'ios') {
   singularPurchase = new SingularIOSPurchase(
     product.revenue,
     product.currency,
     purchase.productId,
     purchase.transactionId,
     purchase.transactionReceipt,
   );
  } else if (Platform.OS === 'android'){
   singularPurchase = new SingularAndroidPurchase(
     product.revenue,
     product.currency,
     purchase.transactionReceipt,
     purchase.signatureAndroid,
   );
}
        
// Track in-app purchase with additional attributes
Singular.inAppPurchaseWithArgs(
     "iap_purchase",
     singularPurchase,
     {
        "is_first_purchase": true,
        "subscription_type": "yearly",
        "discount_applied": "holiday_special",
        "previous_subscription": "monthly"
     }
);

init

Singular.init Method

Initializes the Singular SDK with the provided configuration. The config parameter is a SingularConfig object, which must be instantiated with a valid SDK Key (apiKey) and Secret (secret) using the constructor: new SingularConfig(apikey: string, secret: string).

Signature

static init(config: SingularConfig): void

Usage Example

// Create configuration 
const config = new SingularConfig('SDK KEY', 'SDK SECRET')
     .withCustomUserId("user123")
     .withSessionTimeoutInSec(60)
     .withLimitDataSharing(false)
     .withSingularLink((params) => { 
        // Handle deep link parameters 
        console.log("Deep link received:", params); 
     });

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

isAllTrackingStopped

Singular.isAllTrackingStopped Method

Checks if all tracking has been stopped in the SDK.

Signature

static isAllTrackingStopped(): boolean

Usage Example

// Check if tracking is currently stopped 
const isTrackingStopped = Singular.isAllTrackingStopped();
        
     // Adjust UI based on tracking status
     if (isTrackingStopped) {
        console.log("All tracking is currently stopped");
        // Update UI to reflect tracking status
     } else {
        console.log("Tracking is active");
     }

limitDataSharing

Singular.limitDataSharing Method

Limits data sharing for the current user, typically used for CCPA compliance.

Signature

static limitDataSharing(shouldLimitDataSharing: boolean): void

Usage Example

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

Resumes all tracking activities after they were stopped.

Signature

static resumeAllTracking(): void

Usage Example

// Resume tracking when user opts back in 
Singular.resumeAllTracking();
console.log("Tracking has been resumed");
// Update UI to reflect that tracking is now active

revenue

Singular.revenue Method

Tracks a simple revenue event with a specified currency and amount.

Currency Codes must be ALL CAPS and adhere to the three-letter ISO 4217 currency code

Signature

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

Usage Example

// Track a simple revenue event 
Singular.revenue("USD", 19.99);

revenueWithArgs

Singular.revenueWithArgs Method

Tracks a revenue event with a specified currency, amount, and additional custom attributes.

Event attribute names and attribute values are limited to 500 ASCII characters.
Currency Codes must be ALL CAPS and adhere to the three-letter ISO 4217 currency code

Signature

static revenueWithArgs(currency: string, amount: number, args: SerializableObject): void

Usage Example

// Track a revenue event with additional parameters 
Singular.revenueWithArgs(
     "EUR", 
     9.99, 
     { 
        "subscription_type": "monthly", 
        "is_promotional": false, 
        "user_tier": "premium", 
        "payment_method": "credit_card" 
     }
);

setCustomUserId

Singular.setCustomUserId Method

Sets a custom user ID for the current user to be used with Singular's SDK.

Signature

static setCustomUserId(customUserId: string): void

Usage Example

// Set the custom user ID after user logs in 
Singular.setCustomUserId("user_123456");

setDeviceCustomUserId

Singular.setDeviceCustomUserId Method

Enterprise Feature: Associates a custom user ID with the current device for cross-platform tracking.

Signature

static setDeviceCustomUserId(customUserId: string): void

Usage Example

// Set a device-level custom user ID 
Singular.setDeviceCustomUserId("device_user_987654");

setGlobalProperty

Singular.setGlobalProperty Method

Sets a global property that will be sent with all subsequent events.

Signature

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

Usage Example

// Set a global property that will be included with all events 
const wasSet = Singular.setGlobalProperty("user_tier", "premium", true);
        
// Set another global property without overriding if it exists
Singular.setGlobalProperty("app_version", "2.1.3", false);
        
if (wasSet) {
     console.log("Global property was set successfully");
}

setUninstallToken

Singular.setUninstallToken Method

Sets the device token for uninstall tracking via push notifications.

Signature

static setUninstallToken(token: string): void

Usage Example

// Set the device token for uninstall tracking 
// This is typically obtained from the platform's push notification service 
const deviceToken = "a1b2c3d4e5f6g7h8i9j0..."; // FCM or APNS token 
Singular.setUninstallToken(deviceToken);

skanGetConversionValue

Singular.skanGetConversionValue Method

Gets the current SKAdNetwork conversion value (iOS only).

Signature

static skanGetConversionValue(): number | null

Usage Example

// Get the current SKAdNetwork conversion value 
const conversionValue = Singular.skanGetConversionValue();
        
if (conversionValue !== null) {
     console.log("Current conversion value:", conversionValue);
} else {
     console.log("Conversion value not available");
}

skanRegisterAppForAdNetworkAttribution

Singular.skanRegisterAppForAdNetworkAttribution Method

Registers the app for SKAdNetwork attribution (iOS only).

Signature

static skanRegisterAppForAdNetworkAttribution(): void

Usage Example

// Register app for SKAdNetwork attribution 
// This is typically called early in the app lifecycle 
Singular.skanRegisterAppForAdNetworkAttribution();

skanUpdateConversionValue

Singular.skanUpdateConversionValue Method

Updates the SKAdNetwork conversion value (iOS only).

Signature

static skanUpdateConversionValue(conversionValue: number): boolean

Usage Example

// Update the SKAdNetwork conversion value 
// Value must be between 0-63 
const wasUpdated = Singular.skanUpdateConversionValue(12);

     if (wasUpdated) {
        console.log("Conversion value was updated successfully");
     } else {
        console.log("Failed to update conversion value");
     }

skanUpdateConversionValues

Singular.skanUpdateConversionValues Method

Updates the SKAdNetwork 4.0 conversion values including fine, coarse, and lock window (iOS 16.1+ only).

Signature

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

Usage Example

// Update SKAdNetwork 4.0 conversion values 
// Fine value: 0-63 
// Coarse value: 0-2 (Low, Medium, High) 
// Lock: whether to lock the postback window 
Singular.skanUpdateConversionValues(45, 2, false);
        
// Example with named constants for clarity
const FINE_VALUE = 45;
const COARSE_VALUE_HIGH = 2;
const LOCK_WINDOW = false;
Singular.skanUpdateConversionValues(FINE_VALUE, COARSE_VALUE_HIGH, LOCK_WINDOW);

stopAllTracking

Singular.stopAllTracking Method

Stops all tracking activities in the SDK.

Signature

static stopAllTracking(): void

Usage Example

// Stop all tracking when user opts out 
Singular.stopAllTracking();
console.log("All tracking has been stopped");
// Update UI to reflect that tracking is now disabled

trackingOptIn

Singular.trackingOptIn Method

Opts the user into tracking for analytics and attribution purposes.

Signature

static trackingOptIn(): void

Usage Example

// Call when user has consented to tracking 
Singular.trackingOptIn();
console.log("User has opted into tracking");

trackingUnder13

Singular.trackingUnder13 Method

Marks the user as being under 13 years old, limiting data collection in compliance with COPPA.

Signature

static trackingUnder13(): void

Usage Example

// If user is determined to be under 13 years old 
Singular.trackingUnder13();
console.log("User marked as under 13, GDPR_UNDER_13 flag applied");

unsetCustomUserId

Singular.unsetCustomUserId Method

Removes the previously set custom user ID from Singular tracking.

Signature

static unsetCustomUserId(): void

Usage Example

// Remove the custom user ID when user logs out 
Singular.unsetCustomUserId();
console.log("Custom user ID has been removed");

unsetGlobalProperty

Singular.unsetGlobalProperty Method

Removes a previously set global property.

Signature

static unsetGlobalProperty(key: string): void

Usage Example

// Remove a global property that is no longer needed 
Singular.unsetGlobalProperty("temporary_campaign_id");
console.log("Global property has been removed");

React Native SDK - SDK Methods Reference

React Native SDK Methods Reference

adRevenue

Singular.adRevenue Method

Signature

Usage Example

clearGlobalProperties

Singular.clearGlobalProperties Method

Signature

Usage Example

createReferrerShortLink

Singular.createReferrerShortLink Method

Signature

Usage Example

customRevenue

Singular.customRevenue Method

Signature

Usage Example

customRevenueWithArgs

Singular.customRevenueWithArgs Method

Signature

Usage Example

event

Singular.event Method

Signature

Usage Example

eventWithArgs

Singular.eventWithArgs Method

Signature

Usage Example

getLimitDataSharing

Singular.getLimitDataSharing Method

Signature

Usage Example

getGlobalProperties

Singular.getGlobalProperties Method

Signature

Usage Example

inAppPurchase

Singular.inAppPurchase Method

Signature

Usage Example

inAppPurchaseWithArgs

Singular.inAppPurchaseWithArgs Method

Signature

Usage Example

init

Singular.init Method

Signature

Usage Example

isAllTrackingStopped

Singular.isAllTrackingStopped Method

Signature

Usage Example

limitDataSharing

Singular.limitDataSharing Method

Signature

Usage Example

resumeAllTracking

Singular.resumeAllTracking Method

Signature

Usage Example

revenue

Singular.revenue Method

Signature

Usage Example

revenueWithArgs

Singular.revenueWithArgs Method

Signature

Usage Example

setCustomUserId

Singular.setCustomUserId Method

Signature

Usage Example

setDeviceCustomUserId

Singular.setDeviceCustomUserId Method

Signature

Usage Example

setGlobalProperty

Singular.setGlobalProperty Method