Cordova SDK - SDK Methods Reference

Follow
Avatar
Jared Ornstead
Updated

Cordova SDK - SDK Methods Reference

This comprehensive reference documents all available methods in the Singular SDK for Cordova applications. 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. 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

static adRevenue(adData: SingularAdData): void

Usage Example

javascript
// Create ad data object
adRevenueClicked:function(){
     const adData = new cordova.plugins.SingularCordovaSdk.SingularAdData("Medation_Platform","USD",0.05)
          .withNetworkName('networkName') 
          .withAdType('adType') 
          .withAdGroupType('adGroupType') 
          .withImpressionId('impressionId') 
          .withAdPlacementName('adPlacementName') 
          .withAdUnitId('adUnitId') 
          .withAdUnitName('adUnitName') 
          .withAdGroupId('adGroupId') 
          .withAdGroupName('adGroupName') 
          .withAdGroupPriority('adGroupPriority') 
          .withPrecision('precision') 
     
     // Track ad revenue event
     cordova.plugins.SingularCordovaSdk.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

static clearGlobalProperties(): void

Usage Example

javascript
// Clear all global properties, for example when a user logs out
cordova.plugins.SingularCordovaSdk.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

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

Usage Example

javascript
cordova.plugins.SingularCordovaSdk.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
    {
        onSuccess: function(shortLinkURL) {
            console.log("Generated short link:", shortLinkURL);
            // Share the link with users
        },
        onError: function(error) {
            console.error("Error creating short link:", error);
        }
    }
);

customRevenue

Singular.customRevenue Method

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

  • Note: 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

javascript
// Track a custom revenue event
cordova.plugins.SingularCordovaSdk.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. This allows for more detailed revenue tracking with custom parameters.

  • Note: 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: Object): void

Usage Example

javascript
// Track a custom revenue event with additional parameters
cordova.plugins.SingularCordovaSdk.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 event with the specified name. Use this method to track user actions and engagement within your application.

  • Note: 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

javascript
// Track a simple event
cordova.plugins.SingularCordovaSdk.event("level_completed");

eventWithArgs

Singular.eventWithArgs Method

Tracks an event with the specified name and additional custom attributes. This allows for more detailed event tracking with custom parameters.

  • Note: 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: Object): void

Usage Example

javascript
// Track an event with additional parameters
cordova.plugins.SingularCordovaSdk.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 returns an object containing all global properties that have been set for the SDK.

Signature

static getGlobalProperties(success: Function): void

Usage Example

javascript
// Get all global properties
cordova.plugins.SingularCordovaSdk.getGlobalProperties(function(properties) {
    console.log("Current global properties:", properties);
});

getLimitDataSharing

Singular.getLimitDataSharing Method

Retrieves the current data sharing limitation status. This method returns a boolean indicating whether data sharing is currently limited.

Signature

static getLimitDataSharing(success: Function): void

Usage Example

javascript
// Check if data sharing is limited
cordova.plugins.SingularCordovaSdk.getLimitDataSharing(function(isLimited) {
    console.log("Data sharing is limited:", isLimited);
});

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.

Signature

static handlePushNotification(pushNotificationPayload: Object): void

Usage Example

javascript
// Handle a received push notification
document.addEventListener('push-notification', function(event) {
    var notification = event.notification;
    cordova.plugins.SingularCordovaSdk.handlePushNotification(notification);
}, false);

init

Singular.init Method

Initializes the Singular SDK with the provided configuration. This is the first method you should call to start using the Singular SDK.

Signature

static init(singularConfig: SingularConfig): void

Usage Example

javascript
document.addEventListener('deviceready', function() {
    // Create configuration object
    var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
        "SDK KEY", 
        "SDK SECRET"
    );
    
    // Initialize the SDK
    cordova.plugins.SingularCordovaSdk.init(singularConfig);
}, false);

isAllTrackingStopped

Singular.isAllTrackingStopped Method

Checks if all tracking is currently stopped. This method returns a boolean indicating whether tracking is currently stopped.

Signature

static isAllTrackingStopped(success: Function): void

Usage Example

javascript
// Check if tracking is stopped
cordova.plugins.SingularCordovaSdk.isAllTrackingStopped(function(isStopped) {
    console.log("Tracking is stopped:", isStopped);
});

limitDataSharing

Singular.limitDataSharing Method

Sets the data sharing limitation status. Use this method to limit data sharing based on user consent or privacy requirements.

Signature

static limitDataSharing(value: boolean): void

Usage Example

javascript
// Limit data sharing based on user consent
cordova.plugins.SingularCordovaSdk.limitDataSharing(true);

revenue

Singular.revenue Method

Tracks a revenue event with the specified currency and amount. This method is used to report revenue generated within your application.

Signature

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

Usage Example

javascript
// Track a revenue event
cordova.plugins.SingularCordovaSdk.revenue("USD", 4.99);

revenueWithArgs

Singular.revenueWithArgs Method

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

  • 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: Object): void

Usage Example

javascript
// Track a revenue event with additional parameters
cordova.plugins.SingularCordovaSdk.revenueWithArgs(
    "USD",
    4.99,
    {
        "product_id": "com.app.premium_upgrade",
        "transaction_id": "T12345678"
    }
);

resumeAllTracking

Singular.resumeAllTracking Method

Resumes all tracking activities that were previously stopped. Use this method to re-enable tracking after it has been stopped.

Signature

static resumeAllTracking(): void

Usage Example

javascript
// Resume tracking, for example when user opts back in
cordova.plugins.SingularCordovaSdk.resumeAllTracking();

setCustomUserId

Singular.setCustomUserId Method

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

Signature

static setCustomUserId(userId: string): void

Usage Example

javascript
// Set custom user ID after user logs in
cordova.plugins.SingularCordovaSdk.setCustomUserId(userId);

setGlobalProperty

Singular.setGlobalProperty Method

Sets a global property that will be sent with all events. This allows you to add consistent attributes to all events without specifying them each time.

Signature

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

Usage Example

javascript
// Set a global property
cordova.plugins.SingularCordovaSdk.setGlobalProperty(
    "user_tier", 
    "premium", 
    true, 
    function(isSuccess) {
        console.log("Global property set successfully:", isSuccess);
    }
);

setUninstallToken

Singular.setUninstallToken Method

Sets the device token for uninstall tracking. This method should be called with the push notification token to enable uninstall tracking.

Signature

static setUninstallToken(token: string): void

Usage Example

javascript
// Set uninstall token when push token is received
document.addEventListener('push-registration', function(event) {
    var token = event.registrationId;
    cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
}, false);

skanGetConversionValue

Singular.skanGetConversionValue Method

Retrieves the current SKAdNetwork conversion value. This method is specific to iOS and returns the current conversion value used for SKAdNetwork attribution.

Signature

static skanGetConversionValue(success: Function): void

Usage Example

javascript
// Get the current SKAdNetwork conversion value
cordova.plugins.SingularCordovaSdk.skanGetConversionValue(function(conversionValue) {
    console.log("Current conversion value:", conversionValue);
});

skanRegisterAppForAdNetworkAttribution

Singular.skanRegisterAppForAdNetworkAttribution Method

Registers the app for SKAdNetwork attribution. This method is specific to iOS and should be called to enable SKAdNetwork attribution.

Signature

static skanRegisterAppForAdNetworkAttribution(): void

Usage Example

javascript
// Register for SKAdNetwork attribution
if (device.platform === 'iOS') {
    cordova.plugins.SingularCordovaSdk.skanRegisterAppForAdNetworkAttribution();
}

skanUpdateConversionValue

Singular.skanUpdateConversionValue Method

Updates the SKAdNetwork conversion value. This method is specific to iOS and allows you to manually update the conversion value used for SKAdNetwork attribution.

Signature

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

Usage Example

javascript
// Update the SKAdNetwork conversion value
if (device.platform === 'iOS') {
    cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(5, function(isSuccess) {
        console.log("Conversion value updated successfully:", isSuccess);
    });
}

skanUpdateConversionValues

Singular.skanUpdateConversionValues Method

Updates the SKAdNetwork conversion values with additional parameters. This method is specific to iOS 16.1+ and allows you to update the fine, coarse, and lock values for SKAdNetwork 4.0 attribution.

Signature

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

Usage Example

javascript
// Update the SKAdNetwork 4.0 conversion values
if (device.platform === 'iOS') {
    cordova.plugins.SingularCordovaSdk.skanUpdateConversionValues(
        5,           // fine value (0-63)
        "medium",    // coarse value (low/medium/high)
        false,       // lock
        function(isSuccess) {
            console.log("Conversion values updated successfully:", isSuccess);
        }
    );
}

stopAllTracking

Singular.stopAllTracking Method

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

Signature

static stopAllTracking(): void

Usage Example

javascript
// Stop tracking, for example when user opts out
cordova.plugins.SingularCordovaSdk.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

static trackingOptIn(): void

Usage Example

javascript
// User has opted in to tracking
cordova.plugins.SingularCordovaSdk.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

static trackingUnder13(): void

Usage Example

javascript
// Notifies Singular the User is under 13 years old, GDPR_UNDER_13 flag applied.
cordova.plugins.SingularCordovaSdk.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

static unsetCustomUserId(): void

Usage Example

javascript
// Clear custom user ID when user logs out
cordova.plugins.SingularCordovaSdk.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

static unsetGlobalProperty(key: string): void

Usage Example

javascript
// Remove a global property
cordova.plugins.SingularCordovaSdk.unsetGlobalProperty("user_tier");