Unliche SDK – Cordova Plugin

Last Updated On January 03, 2019
< Back

 

 

The Unliche plugin for Cordova provides application session and event logging functionality via the Unliche native SDKs.
To measure installs and custom events, first integrate the plugin with your mobile app. After you initiate the initEvent method, you can track custom events.

1. Downloading the Plugin
The Unliche Cordova plugin is available from npm via the Cordova CLI:

cordova plugin add cordova-plugin-unliche

Before you can download the Unliche Cordova plugin, make sure you should have your app in the Unliche Analytics Platform.

 

2. Implementation

2.1 Install the plugin into your project.

$ cordova create MyApp
$ cd MyApp
$ cordova plugin add cordova-plugin-unliche

 

2.2 Initialize the tracker upon receiving the deviceready event. For example, in a new Cordova project,
you would add in onDeviceReady of index.js:

var app = {
 
    // Application Constructor
    initialize: function() {
        document.addEventListener('deviceready', this.onDeviceReady.bind(this), false);
    },

    // deviceready Event Handler
    // Bind any cordova events here. Common events are:
    // 'pause', 'resume', etc.
    onDeviceReady: function() {
        this.receivedEvent('deviceready');
    },

     // Update DOM on a Received Event
    receivedEvent: function(id) {
        var parentElement = document.getElementById(id);
        var listeningElement = parentElement.querySelector('.listening');
        var receivedElement = parentElement.querySelector('.received');

        listeningElement.setAttribute('style', 'display:none;');
        receivedElement.setAttribute('style', 'display:block;');

  // Unliche init
      window.plugins.unlichePlugin.initEvent(AccessToken);

    }
};

 

Note
AccessToken will get while register on portal of Unliche for tracking. If not already register then click here to register.
This API enables Unliche to detect installations, sessions, and updates.

* The Android INSTALL_REFERRER receiver is automatically added via plugin.xml

 

3. In-App Events Tracking API (Optional)
There are two types of optional events contains in Unliche sdk, 1) Sdk defined 2) Custom events

 

3.1 Unliche Sdk Defined Events
This API enables Unliche to track some in app events that are already defined in sdk. App just need to call the methods of event and use it with specific events.

Events:
3.1.1 Open
For user retention you have to include this event

Syntax:
window.plugins.unlichePlugin.openEvent();

 

3.2 Custom events (Advertiser defined events)
This API enables Unliche to track post install events. These events are defined by the advertiser and include an event id, in addition to optional event values. Tracking in-app events helps you measure and analyze how loyal users discover your app, and attribute them to specific campaigns/media sources.

Syntax
window.plugins.unlichePlugin.setCustomEvent(int customEventId);

  • customEventId – event id generated while create custom event in Unliche system

 

Syntax

window.plugins.unlichePlugin.setCustomEventWithParams(int customEventId, String additionalParam1, String 
additionalParam2, String additionalParam3, String additionalParam4, String additionalParam5);
  • customEventId – event id generated while create custom event in Unliche system
  • additionalParam1 to additionalParam5 – additional parameters which are advertiser wants to provide from app. Any parameter can be null.

 

4. Optional fields to provide
There are some optional parameter you can provide.

 

4.1 User ID
Syntax
window.plugins.unlichePlugin.setUserId(String userID);

 

4.2 User name
Syntax
window.plugins.unlichePlugin.setUserName(String userName);

 

4.3 User phone number
Syntax
window.plugins.unlichePlugin.setPhoneNumber(String phoneNumber);

 

5. Uninstalls
To track uninstalls you have to integrate GCM/FCM in your app. Register app to GCM with project number and provide GCM token to below function.
To integrate GCM/FCM in app click here

Syntax
window.plugins.unlichePlugin.setUninstallEvent(String GCMToken)

  • GCMToken – is token provided by GCM/FCM to client.

 

6. Testing the In-App Events Tracking
The below steps may be performed to test the in-app events integration from a tracking perspective:

1. Login to Unliche and define the events within your application.
2. Integrate the custom event tracking code in your application.
3. Navigate to “Event integration” section under “Technical Config: from left menu panel.
4. Then select the application and click on ‘Validate now’ button for each event.
5. The “Status” should be “Successful” for a successful integration.
6. If the “Status” is “Failed”, please check the integration again.

 

7. Standalone App/APK
You can track app that is out of store in Unliche, For that follow following steps.

 

7.1 Advertiser portal
1. Register and Login in Unliche system as advertiser
2. While creating new application select standalone APK option.
3. Enter package name, socket and app URL (Form which apk will download directly), all params should be unique. Click to create app and complete process.
4. Note that, socket name is needed at the time of Android app integration.

 

7.2 Android application
1. Integrate Unliche SDK in your app as per SDK documentation.
2. In addition add following meta-data tag in your androidmanifest file under application tag.

Syntax
<meta-data android:name="UNLICHE_SOCKET" android:value="TEST_SOCKET"/>

Note
TEST_SOCKET will be your unique socket name, that you already provided while creating app in advertiser portal.
3. Specify your Unliche SDK events in your application. (Default events are install and open which will call after installing and opening app

 

7.3 Testing
1. Click on app URL that will download APK in your device.
2. Install downloaded APK.
3. Do the activities according to events and observe result in advertiser portal. By just opening app you can see install and open events data in advertiser portal.

 

 

Advertising Identifiers
To increase the consistency and ease of attribution, the Unliche Cordova plugin collects device identifiers.

 

Android
The Google Advertising ID is automatically collected by the Cordova plugin. It requires the following:
– Dependency on com.google.android.gms:play-services-ads framework. This requires installing Android Support Repository and Google Play services from the Android SDK. (Ref. https://developer.android.com/sdk/installing/adding-packages.html)

 

iOS
The Apple Advertising ID is automatically collected by the Unliche plugin. It requires the following:
– Include AdSupport.framework in your iOS project. This is automatically added when installing the Unliche plugin on iOS.

 

Note
The “your_advertiser_ID” values correlate with the Advertiser ID and Conversion Key that Unliche provides when you create your Mobile App in Unliche.