Adding the Singular Plugin

To add the Singular plugin to your Cordova project, run the following:

cordova plugin add singular_cordova_sdk

Ionic

If you are using Ionic:

1. Install the Singular SDK plugin:

   $ ionic cordova plugin add singular_cordova_sdk

2. In your main ts file, declare a window variable:

   declare var cordova;

3. Now you can use the Singular plugin directly from Cordova:

   import {Component} from '@angular/core';
   import {Platform} from '@ionic/angular';
   declare var cordova;
   ...
   
   export class HomePage {
   constructor(public platform: Platform) {
   this.platform.ready().then(() => {
   
       // Add code to initialize the Singular SDK here
   
   }); 
   }}

Initializing the SDK (Required)

The Singular SDK initialization code should be called every time your app is opened. It is a prerequisite to all Singular attribution functionality. It also sends a new user session to Singular (sessions are used to calculate user retention).

To initialize the Singular SDK:

1. Create a SingularConfig object. The object contains your Singular SDK Key and Secret.
2. Configure optional settings if you want your app to support deep links and/or SKAdNetwork (see Adding Deep Linking Support and Adding SKAdNetwork Support below).
3. Initialize the SDK using the SingularConfig object.

Code example (with optional settings commented out):

// Create the configuration object
var singularConfig = new
cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");

/*
// Optional: Enable deep linking (requires additional setup steps, see guide)
var linkHandler = function(data){
var deeplink = data.deeplink;
var passthrough = data.passthrough;
var isDeferred = data.isDeferred;
// Add link handling logic here
}
singularConfig.withSingularLink(linkHandler);
*/

/*
// Optional: Enable SKAdNetwork (in Managed Mode, see guide for more options)
singularConfig.withSkAdNetworkEnabled(true);
*/

// Initialize Singular
cordova.plugins.SingularCordovaSdk.init(singularConfig);

Tracking Events

In addition to sending user sessions to Singular (through initializing the SDK), you can also send user events. Data about in-app events helps Singular analyze the performance of your user acquisition campaigns and measure KPIs.

For example, your organization may want to collect data about user logins, registrations, tutorial completions, or leveling up in a gaming app.

To send events to Singular, use the eventWithArgs method. Give the event a name and add any attributes you want to track.

// Example: Report an event called View Product with event attributes
cordova.plugins.SingularCordovaSdk.eventWithArgs(
  'ViewProduct', // Event name
  {
    // Event attributes
    productID:"123",
    productCategory:"Outerwear"
  }
)

Tracking In-App Purchase Revenue

To let Singular track how much revenue your app makes from in-app purchases, report IAP events to Singular.

We recommend using the eventWithArgs method and passing the IAP object as an event attribute. Singular uses the IAP object to validate the purchase and detect fraudulent purchases so they do not skew your revenue metrics (see the In-App Purchase Validation FAQ).

If you are using the https://github.com/j3k0/cordova-plugin-purchase library, you can use the following code:

store.when('product123 verified', onProductVerified);
product.verify();

function onProductVerified(product){
  const iap = new cordova.plugins.SingularCordovaSdk.SingularIAP(product);
  cordova.plugins.SingularCordovaSdk.eventWithArgs('IAP_EVENT', iap)
}

cordova.plugins.SingularCordovaSdk.customRevenue(
  customEventName, // E.g. "purchase"
  currencyCode, // E.g. "USD"
  purchaseAmount // E.g. 3.2
);

Tracking Ad Revenue Attribution

You can use the Singular plugin to set up ad revenue attribution (see the Ad Revenue Attribution FAQ).

To set up ad revenue attribution:

1. If you haven't done so yet, contact your Singular Customer Success Manager to enable ad revenue attribution for your account.
2. Add the appropriate code snippet to get ad revenue information from the mediation platform you use for ad revenue data. See code snippets in our Android SDK documentation.

3. Report ad revenue events to Singular using the following code:

   const adData = new
     cordova.plugins.SingularCordovaSdk.SingularAdData(
       mediationPlatform,
       currencyCode, // e.g., "USD"
       revenueAmount)
   
   cordova.plugins.SingularCordovaSdk.adRevenue(adData);

Adding Deep Linking Support

Deep links are links that open the app on the user's phone and send the user directly to a specific page or user experience instead of just the app's main widget.

Deep links are usually used in retargeting campaigns, aimed at users who already have the app on their phone but may not have engaged with it for a while.

Singular supports deep linking through Singular Links (see the Singular Links FAQ).

To use Singular Links in your app:

1. Follow the instructions in Singular Links Prerequisites.

2. For Android, add this code to the main activity:

   import singular_cordova_sdk.SingularCordovaSdk;
   
   @Override
   public void onNewIntent(Intent intent) {
     SingularCordovaSdk.handleNewIntent(intent);
   }

   For iOS, add this code to your AppDelegate:

   #import "SingularCordovaSdk.h"
   
     - (BOOL)application:(UIApplication*)application
     didFinishLaunchingWithOptions:(NSDictionary*)launchOptions
     {
        self.viewController = [[MainViewController alloc] init];
        [SingularCordovaSdk setLaunchOptions: launchOptions];
        return [super
     application:application didFinishLaunchingWithOptions:launchOptions];
     }
   
     - (BOOL)application:(UIApplication *)application
     continueUserActivity:(NSUserActivity *)userActivity
     restorationHandler:(void (^)(NSArray<id> * _Nullable))restorationHandler{
      [SingularCordovaSdk startSessionWithUserActivity:userActivity];
      return
     YES;
     }

3. Before initializing the Singular SDK in your code, add .withSingularLink to the Singular config object and specify your link handler function:

   var singularConfig = new
     cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");
   
   var linkHandler = function(data){
     var deeplink = data.deeplink;
     var passthrough = data.passthrough;
     var isDeferred = data.isDeferred;
     // Add link handling logic here
   }
   
   singularConfig.withSingularLink(linkHandler);
   
   cordova.plugins.SingularCordovaSdk.init(singularConfig);

Adding SKAdNetwork Support

The Singular plugin supports the SKAdNetwork framework. You can enable SKAdNetwork tracking for your app using the configuration options below.

Managed Mode (Recommended)

In managed mode, Singular manages the SKAdNetwork conversion value for you automatically, based on a conversion model of your choice that you can set up in the Singular platform.

To learn more, see Understanding Singular's Conversion Value Management and the SKAdNetwork Model Configuration FAQ. For a step-by-step guide to using SKAdNetwork with Singular, see How to Get Started with SKAdNetwork.

To enable SKAdNetwork in managed mode, use the following code:

var singularConfig = new
  cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");

// Enable SKAdNetwork (in managed mode by default)
singularConfig.withSkAdNetworkEnabled(true);

cordova.plugins.SingularCordovaSdk.init(singularConfig);

Manual Mode

If you already have your own strategy and tools for managing the SKAdNetwork conversion value, you can use SKAdNetwork in manual mode.

To enable SKAdNetwork in manual mode, use the following code:

var singularConfig = new
  cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");

// Enable SKAdNetwork
singularConfig.withSkAdNetworkEnabled(true);

// Select SKAdNetwork manual mode
singularConfig.withManualSkanConversionManagement();

// Optional: define handler to track changes to the conversion value
var conversionHandler = function(updatedConversionValue){
  // Do something with updatedConversionValue
}

singularConfig.withConversionValueUpdatedHandler(conversionHandler);

// Initialize the Singular SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);

To update the conversion value use the following code:

cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(
  newConversionValue,
  function(isSuccess){
    // isSuccess == true if the update was successful
  }
)

To retrieve the current conversion value, use the following code:

cordova.plugins.SingularCordovaSdk.skanGetConversionValue(
  function(conversionValue){
    // Do something with conversionValue
  }
)

Other Options

Tracking Uninstalls

To let Singular track app uninstalls, send the APNS/FCM token to Singular using the following code:

Android:

cordova.plugins.SingularCordovaSdk.setUninstallToken(fcmToken)

iOS:

cordova.plugins.SingularCordovaSdk.setUninstallToken(apnsToken)

Creating Short Referrer Links

Use short links to transform long, parameter-filled Singular Links into shorter and more secure links that are convenient for sharing.

Typically, you will want to create short links dynamically so that your app's users can share them with friends to invite them to use the app.

To create a short link, you need:

• A Singular Link that leads to your app download (see the Singular Links FAQ).
• Any parameters you want to add to the link dynamically (see Tracking Link Parameters for the list of options).
• The name and ID of the referring user, if you want to be able to track new app installs back to the user who shared the link.

To create short links use the following code:

cordova.plugins.SingularCordovaSdk.createReferrerShortLink(
    longLinkURL, 
    referrerName,
    referrerID,
    {
        // Tracking link parameters to add to the short link, e.g. "channel":"sms"
        param1: value1,
        param2: value2,
        ...
    },
    {
        onSuccess: function (shortLinkURL) {
        // Do something with shortLinkURL
        },
        onError: function (error) {
        // Handle error
        }
    }
)