Cordova SDK - Methods Reference

Follow
Avatar
Jared Ornstead
Updated

Cordova SDK - Methods Reference

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

adRevenue

Singular.adRevenue Method

Tracks ad revenue events with detailed ad data information. This method allows you to report revenue generated from ads displayed in your application with various parameters to categorize and analyze the ad performance.

Signature

adRevenue(adData: Object): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

// Create ad data object with required fields
var adData = {
  adPlatform: 'AdMob',
  currency: 'USD',
  revenue: 0.05,
  adUnitId: 'ca-app-pub-1234567890123456',
  adType: 'Rewarded',
  adPlacementName: 'level_complete'
};

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

clearGlobalProperties

Singular.clearGlobalProperties Method

Removes all previously set global properties. This is useful when you need to reset the global properties, for example when a user logs out of your application.

Signature

clearGlobalProperties(): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

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

createReferrerShortLink

Singular.createReferrerShortLink Method

Creates a short link with referrer information that can be used for sharing and attribution. This method generates trackable links that can be shared with users, allowing you to attribute installs and activities to specific referral sources.

Signature

createReferrerShortLink(
  url: string,
  refName: string,
  refId: string,
  passthroughParams: Object,
  resultHandler: Object
): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

// Create a short link for referral
var resultHandler = {
  onSuccess: function(link) {
    console.log('Generated short link:', link);
    // Share the link with users
  },
  onError: function(error) {
    console.error('Error creating short link:', error);
  }
};

Singular.createReferrerShortLink(
  'https://sample.sng.link/B4tbmv8fp',
  'John Doe',
  'aq239897',
  { channel: 'sms', campaign: 'summer_promo' },
  resultHandler
);

customRevenue

Singular.customRevenue Method

Tracks custom revenue events with a specified event name, currency, and amount. This allows for more specific revenue tracking with custom event names.

Signature

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

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

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

customRevenueWithArgs

Singular.customRevenueWithArgs Method

Tracks custom revenue events with a specified event name, currency, amount, and additional attributes. This allows for more detailed revenue tracking with custom parameters.

Signature

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

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

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

Tracks events with the specified name. Use this method to track user actions and engagement within your application.

Signature

event(eventName: string): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

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

eventWithArgs

Singular.eventWithArgs Method

Tracks events with the specified name and additional custom attributes. Use this method to track user actions with detailed parameters.

Signature

eventWithArgs(
  eventName: string,
  args: Object
): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

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

getGlobalProperties

Singular.getGlobalProperties Method

Retrieves all currently set global properties. This method accepts a callback function that receives an object containing all global properties that have been set for the SDK.

Signature

getGlobalProperties(success: Function): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

// Get all global properties
Singular.getGlobalProperties(function(properties) {
  console.log('Global properties:', properties);
});

getLimitDataSharing

Singular.getLimitDataSharing Method

Retrieves the current data sharing limitation status. This method accepts a callback function that receives a boolean indicating whether data sharing is currently limited.

Signature

getLimitDataSharing(success: Function): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

// Check if data sharing is limited
Singular.getLimitDataSharing(function(isLimited) {
  if (isLimited) {
    console.log('Data sharing is currently limited');
  }
});

handlePushNotification

Singular.handlePushNotification Method

Processes a push notification payload for attribution. This method should be called when your app receives a push notification to allow Singular to attribute it correctly. This method is iOS-only.

Signature

handlePushNotification(pushNotificationPayload: Object): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

// Handle a received push notification (iOS only)
if (device.platform === 'iOS') {
  var userInfo = remoteMessage.data;
  Singular.handlePushNotification(userInfo);
}

iapPurchase

SingularIAP Constructor

Creates an in-app purchase (IAP) object for tracking revenue from in-app purchases with platform-specific receipt validation. This constructor processes purchase data from both iOS App Store and Android Play Store transactions, formatting the data for proper revenue attribution and receipt verification.

Signature

function SingularIAP(product: Object): SingularIAP

Usage Example

JavaScript 
var SingularIAP = require('./SingularIAP');

// Example for Android Play Store purchase
var androidProduct = {
  currency: 'USD',
  price: '$4.99',
  id: 'com.app.premium_gems',
  transaction: {
    type: 'android-playstore',
    receipt: 'eyJvcmRlcklkIjoiR1BBLjEyMzQ...',
    signature: 'signature_string_here'
  }
};

var androidIAP = new SingularIAP(androidProduct);

// Example for iOS App Store purchase
var iosProduct = {
  currency: 'USD',
  price: '$4.99',
  id: 'com.app.premium_gems',
  transaction: {
    type: 'ios-appstore',
    appStoreReceipt: 'MIITtQYJKoZIhvcNAQcCoIITpj...',
    id: 'transaction_identifier_123'
  }
};

var iosIAP = new SingularIAP(iosProduct);

// The resulting object contains:
// - ppc: product currency
// - r: revenue amount (parsed from price string)
// - is_revenue_event: true
// Platform-specific fields:
// Android: ptr, receipt, receipt_signature
// iOS: ptr, pti, pk

init

Singular.init Method

Initializes the Singular SDK with the specified configuration. This method must be called before any other SDK methods. The configuration object should include your API key, secret, and other optional settings.

Signature

init(singularConfig: SingularConfig): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');
var SingularConfig = cordova.require('singular-cordova-sdk.SingularConfig');

// Create and configure the SDK
var config = new SingularConfig('YOUR_API_KEY', 'YOUR_SECRET');

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

isAllTrackingStopped

Singular.isAllTrackingStopped Method

Checks whether all tracking has been stopped. This method accepts a callback function that receives a boolean indicating the current tracking status.

Signature

isAllTrackingStopped(success: Function): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

// Check if tracking is stopped
Singular.isAllTrackingStopped(function(isStopped) {
  if (isStopped) {
    console.log('All tracking is currently stopped');
  }
});

limitDataSharing

Singular.limitDataSharing Method

Sets the data sharing limitation status. Use this method to comply with privacy regulations by limiting what data is shared with third parties.

Signature

limitDataSharing(value: boolean): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

// Enable data sharing limitation
Singular.limitDataSharing(true);

resumeAllTracking

Singular.resumeAllTracking Method

Resumes all tracking activities after they have been stopped. Use this method to re-enable tracking when users opt back in.

Signature

resumeAllTracking(): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

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

revenue

Singular.revenue Method

Tracks revenue events with a specified currency and amount. This is the basic method for tracking revenue without additional attributes.

Signature

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

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

// Track a simple revenue event
Singular.revenue('USD', 9.99);

revenueWithArgs

Singular.revenueWithArgs Method

Tracks revenue events with a specified currency, amount, and additional attributes. This allows for more detailed revenue tracking with custom parameters.

Signature

revenueWithArgs(
  currency: string,
  amount: number,
  args: Object
): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

// Track a revenue event with attributes
Singular.revenueWithArgs(
  'USD',
  9.99,
  {
    product_id: 'premium_monthly',
    transaction_id: 'txn_12345'
  }
);

setCustomUserId

Singular.setCustomUserId Method

Sets a custom user ID for the current session. This allows you to associate Singular data with your own user identification system.

Signature

setCustomUserId(userId: string): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

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

setGlobalProperty

Singular.setGlobalProperty Method

Sets a global property that will be sent with all subsequent events. This is useful for tracking persistent user attributes or application state. The method accepts a callback function that receives a boolean indicating success.

Signature

setGlobalProperty(
  key: string,
  value: any,
  overrideExisting: boolean,
  success: Function
): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

// Set a global property
Singular.setGlobalProperty(
  'user_tier',
  'premium',
  true,
  function(success) {
    if (success) {
      console.log('Global property set successfully');
    }
  }
);

setLimitAdvertisingIdentifiers

Singular.setLimitAdvertisingIdentifiers Method

Controls whether advertising identifiers (IDFA/GAID) should be limited. Use this method to comply with privacy preferences and regulations.

Signature

setLimitAdvertisingIdentifiers(enabled: boolean): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

// Limit advertising identifiers
Singular.setLimitAdvertisingIdentifiers(true);

setUninstallToken

Singular.setUninstallToken Method

Sets the push notification token for uninstall tracking. This allows Singular to track app uninstalls by monitoring push notification delivery failures.

Signature

setUninstallToken(token: string): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

// Set the push notification token for uninstall tracking
Singular.setUninstallToken('your-fcm-or-apns-token-here');

skanGetConversionValue

Singular.skanGetConversionValue Method

Retrieves the current SKAdNetwork conversion value. This method accepts a callback function that receives the current conversion value as a number. This method is iOS-only.

Signature

skanGetConversionValue(success: Function): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

// Get current SKAdNetwork conversion value (iOS only)
if (device.platform === 'iOS') {
  Singular.skanGetConversionValue(function(value) {
    console.log('Current conversion value:', value);
  });
}

skanRegisterAppForAdNetworkAttribution

Singular.skanRegisterAppForAdNetworkAttribution Method

Registers the app for SKAdNetwork attribution. This method should be called early in the app lifecycle to enable SKAdNetwork tracking. This method is iOS-only.

Signature

skanRegisterAppForAdNetworkAttribution(): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

// Register for SKAdNetwork attribution (iOS only)
if (device.platform === 'iOS') {
  Singular.skanRegisterAppForAdNetworkAttribution();
}

skanUpdateConversionValue

Singular.skanUpdateConversionValue Method

Updates the SKAdNetwork conversion value. This method is used for SKAdNetwork 2.0-3.0 and accepts a callback function that receives a boolean indicating whether the update was successful. This method is iOS-only.

Signature

skanUpdateConversionValue(
  value: number,
  success: Function
): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

// Update SKAdNetwork conversion value (iOS only)
if (device.platform === 'iOS') {
  Singular.skanUpdateConversionValue(3, function(success) {
    if (success) {
      console.log('Conversion value updated successfully');
    }
  });
}

skanUpdateConversionValues

Singular.skanUpdateConversionValues Method

Updates SKAdNetwork 4.0 conversion values with fine value, coarse value, and lock status. This method is for iOS 16.1+ and accepts a callback function that receives a boolean indicating success. This method is iOS-only.

Signature

skanUpdateConversionValues(
  value: number,
  coarse: number,
  lock: boolean,
  success: Function
): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

// Update SKAdNetwork 4.0 conversion values (iOS 16.1+)
if (device.platform === 'iOS') {
  Singular.skanUpdateConversionValues(
    5,     // fine value (0-63)
    1,     // coarse value (0=low, 1=medium, 2=high)
    false, // lock
    function(success) {
      if (success) {
        console.log('Conversion values updated successfully');
      }
    }
  );
}

stopAllTracking

Singular.stopAllTracking Method

Stops all tracking activities. Use this method to disable tracking when users opt out or for privacy compliance.

Signature

stopAllTracking(): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

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

trackingOptIn

Singular.trackingOptIn Method

Indicates that the user has opted in to tracking. Call this method when the user explicitly consents to tracking and data collection.

Signature

trackingOptIn(): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

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

trackingUnder13

Singular.trackingUnder13 Method

Indicates that the user is under 13 years old. Call this method to comply with COPPA and other regulations for users under 13 years old.

Signature

trackingUnder13(): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

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

unsetCustomUserId

Singular.unsetCustomUserId Method

Removes the previously set custom user ID. Call this method when the user logs out or when you no longer want to associate events with the current user ID.

Signature

unsetCustomUserId(): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

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

unsetGlobalProperty

Singular.unsetGlobalProperty Method

Removes a previously set global property. Call this method when you no longer want a specific global property to be sent with events.

Signature

odedeunsetGlobalProperty(key: string): void

Usage Example

JavaScript 
var Singular = cordova.require('singular-cordova-sdk');

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