Prerequisites

Complete these prerequisite steps before installing the Singular Cordova SDK to ensure a smooth integration process.

Installation

Installing the Singular Plugin

Add the Singular plugin to your Cordova project using the Cordova CLI. The plugin provides JavaScript bindings to the native Singular SDKs for iOS and Android.

Install via Cordova CLI

1. Open terminal: Navigate to your Cordova project's root directory.
2. Add plugin: Run the following command to install the Singular SDK plugin:
   bash

   cordova plugin add singular_cordova_sdk

3. Verify installation: Confirm the plugin was added by checking your config.xml file for the plugin entry or by running:
   bash

   cordova plugin list

Ionic Framework Integration

If you're building your Cordova app with Ionic Framework, follow these additional steps to properly integrate the Singular SDK.

Install Plugin for Ionic

1. Install via Ionic CLI: Use the Ionic Cordova command to add the plugin:
   bash

   ionic cordova plugin add singular_cordova_sdk

2. Declare Cordova variable: In your main TypeScript file (typically app.component.ts or home.page.ts), declare the Cordova variable at the top:
   TypeScript

   declare var cordova;

3. Initialize within platform ready: Use the platform ready event to ensure native plugins are loaded before SDK initialization:
   TypeScript

   import { Component } from '@angular/core';
   import { Platform } from '@ionic/angular';
   
   declare var cordova;
   
   export class HomePage {
     constructor(public platform: Platform) {
       this.platform.ready().then(() => {
         // Initialize Singular SDK here (see SDK Integration section)
   
       });
     }
   }

Platform Configuration

Android Configuration

Configure Android-specific permissions and settings to enable core SDK functionality and attribution tracking.

Add Required Permissions

Add the necessary Android permissions to your Cordova config.xml file to enable attribution, network access, and install referrer tracking.

1. Open config.xml: Navigate to the root of your Cordova project and open the config.xml file.
2. Add permissions: Within the <platform name="android"> section, add the following permission:
   config.xml

   <platform name="android">
       <!-- Required for GAID collection and attribution -->
       <edit-config file="app/src/main/AndroidManifest.xml" mode="merge" target="/manifest">
           <uses-permission android:name="com.google.android.gms.permission.AD_ID" />
       </edit-config>
   </platform>

Additional Permissions (Auto-Added)

The following permissions are automatically added by the Singular Cordova plugin and do not require manual configuration:

• android.permission.INTERNET - Network access for data transmission
• android.permission.ACCESS_NETWORK_STATE - Network state monitoring
• BIND_GET_INSTALL_REFERRER_SERVICE - Install referrer tracking

iOS Configuration

iOS configuration is handled automatically by the Cordova plugin. No additional manual configuration steps are required for iOS projects.

SDK Integration

Initialize the Singular SDK every time your app launches. SDK initialization is essential for all Singular attribution functionality and creates a new session for calculating user retention metrics.

Basic SDK Initialization

Create a SingularConfig object with your SDK credentials and initialize the SDK using the init() method. This should be done as early as possible in your app's lifecycle.

Initialization Example

1. Get credentials: Log into your Singular account and navigate to Developer Tools > SDK Integration > SDK Keys to find your SDK Key and Secret.
2. Create configuration: Instantiate a SingularConfig object with your credentials.
3. Initialize SDK: Call init() to start the SDK.

// Create the Singular configuration object
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

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

Advanced Configuration

Configure additional SDK features by chaining configuration methods before calling init(). This example demonstrates common configuration options including deep linking, logging, and session timeout.

// Create configuration with credentials
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

// Enable debug logging (disable in production)
singularConfig.withLoggingEnabled();

// Set custom session timeout (default is 60 seconds)
singularConfig.withSessionTimeoutInSec(120);

// Configure deep linking handler
var linkHandler = function(data) {
  var deeplink = data.deeplink;
  var passthrough = data.passthrough;
  var isDeferred = data.isDeferred;

  console.log("Received deep link:", deeplink);
  console.log("Is deferred:", isDeferred);

  // Handle navigation based on deep link
  if (deeplink) {
    // Navigate to appropriate screen
  }
};
singularConfig.withSingularLink(linkHandler);

// Set custom user ID (if user is logged in)
singularConfig.withCustomUserId("user_12345");

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

Meta Install Referrer Attribution

Configure Meta (Facebook) Install Referrer attribution to track installs from Facebook and Instagram ad campaigns.

Enable Meta Install Referrer

If AMM is not enabled or you need Meta Install Referrer for legacy tracking, add your Facebook App ID to the SDK configuration.

1. Find Facebook App ID: Log into your Facebook Developer account and navigate to your app's dashboard to locate the App ID.
2. Add to configuration: Use the withFacebookAppId() method to enable Meta Install Referrer:
   JavaScript

   // Create configuration
   var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
     "YOUR_SDK_KEY",
     "YOUR_SDK_SECRET"
   );
   
   // Enable Meta Install Referrer
   singularConfig.withFacebookAppId("YOUR_FACEBOOK_APP_ID");
   
   // Initialize SDK
   cordova.plugins.SingularCordovaSdk.init(singularConfig);