Phonegap

Phonegap

 

Support

Follow

With the xtremepush module for Cordova you can add xtremepush to both iOS and Android apps built with Cordova or PhoneGap or Ionic.

Platform Specific Information

Xtremepush supports push notifications for iOS devices via Apple's Push Notification Service (APNs for short). And push notifications for Android devices via Google’s GCM/FCM (Google/Firebase Cloud Messaging for Android) service. This page contains PhoneGap specific instructions but you will need to connect your iOS and Android app to the platform separately.

N.B. To integrate successfully you will need to have your xtremepush App Key, APNS certs for iOS and, Google project number and GCM API key for Android. These are used to connect your app to the platform and the Apple and Google push services. You will find links to documentation on connecting to the platform below:

Full Cordova integration guides are given for iOS and Android below.

Installing the Xtremepush Plugin in your Project

  1. In a terminal navigate to your project directory
  2. From a terminal navigate to your application directory, and add the plugin with the following command:
  • cordova plugin add https://github.com/xtremepush/XtremePush-Phonegap
  1. Now edit your index.js file to register with the xtremepush server on a deviceready event, taking care to switch "APP_KEY" and "GCM_PROJECT_NUMBER" to actual values.

var app = {
   // Application Constructor
   initialize: function() {
       this.bindEvents();
   },
   // Bind Event Listeners
   //
   // Bind any events that are required on startup. Common events are:
   // 'load', 'deviceready', 'offline', and 'online'.
   bindEvents: function() {
       document.addEventListener('deviceready', this.onDeviceReady, false);    
       window.addEventListener('orientationchange', doOnOrientationChange);
},

   // deviceready Event Handler
   //
   // The scope of 'this' is the event. In order to call the 'receivedEvent'
   // function, we must explicitly call 'app.receivedEvent(...);'
   onDeviceReady: function() {
       registerXtremePush();
   }
};

function registerXtremePush() {
XtremePush.register({
appKey:"APP_KEY",
debugLogsEnabled:true,
impressionsBatchingEnabled:true,
inappMessagingEnabled:true,
tagsBatchingEnabled:true,
inboxEnabled:true,

ios:{
nameCollectingEnabled:true,
locationsEnabled:true,
locationsPermissionsRequest:true,
badgeWipingEnabled:true
},
android:
{
gcmProjectNumber:"GCM_PROJECT_NUMBER",
geoEnabled:true,
beaconsEnabled:true
}
});
}

function doOnOrientationChange() {
XtremePush.onConfigChanged();
}


app.initialize()


Android:

The max Android level that should be targeted in the app is 25. This can be set by adding the following preferences to the config.xml file in the app folder:
    <preference name="android-targetSdkVersion" value="25" />
    <!-- optional -->
    <preference name="android-minSdkVersion" value="14" />
    <preference name="deployment-target" value="8.0" />

 

Callback Functions

MessageResponseCallback, deeplinkCallback,  and inboxBadgeCallback are JavaScript functions defined in a JavaScript file of your project. After created you have to define them in the registerXtremePush function as example:

 

messageResponseCallback : "onMessageResponse",

inboxBadgeCallback: "inboxBadgeCallbackFunction",

deeplinkCallback : "onDeeplinkReceived",

 

They are called to be executed in special cases as explained below:

 

messageResponseCallback

A basic implementation is shown below.


function onMessageResponse(data) {
        let jo = JSON.parse(JSON.stringify(data));
        console.log(JSON.stringify(jo));

        if (jo.response.type == = "present") {

        } else if (jo.response.type == = "click") {

        } else if (jo.response.type == = "dismiss") {

        }
    }


The response.type variable shown above can be either present | click | dismiss

  • present - when a push notification is receved and the app is in the foreground
  • click - when a message is clicked
  • dismiss - when a message is dismissed

 

Below is a complete example of custom notification handling. It does multiple things:

  • shows a custom dialog when a push message is received in foreground
  • opens an article page when a message is clicked
  • saves information when one of the message buttons is clicked

 function onMessageResponse(data) {
            let jo = JSON.parse(JSON.stringify(data));

            // When app is received in the foreground show an alert
            if (jo.response.type == = "present") {
                console.log(JSON.stringify(jo));
                openArticle(jo.message.data.articleId);

                //when the user clicks on a message 
            } else if (jo.response.type == = "click") {
                //default click action
                if (!jo.response.hasOwnProperty('action')) {
                    openArticle(jo.message.data.articleId);

                    //action for specific button click
                } else {
                    if (jo.response.action == = "like") {
                        likeArticle(jo.message.data.articleId);
                    } else if (jo.response.action == = "share") {
                        shareArticle(jo.message.data.articleId);
                    }
                }

                //show alert if dismiss button click
            } else if (jo.response.type == = "dismiss") {
                alert("message dismiss");
            }
        }

    }

  

inboxBadgeCallback

happens when the badge number updates. The badge number is checked when:

  • New push message arrives
  • Application is started
  • Inbox window is closed

An example is shown below


function onInboxBadgeUpdate(data){
    alert ('Inbox badge update ' + data);
}

 

deeplinkCallback

happens when a message with the click action 'Go to deeplink' is clicked. 

An example is shown below:


function onDeeplinkReceived(data){
    alert("deeplink Received "+data);
}
 

Foreground Notification Handling

It is important to define the right behaviour for the situation when a push notification is received in foreground. You don't want to interrupt the user workflow, but still be delivering important information to the user.

The default behaviour on both iOS and Android is to show OS style notification. But this can be changed, by adding the payload with key 'foreground' and value 'false' to your campaign.

Screen_Shot_2017-11-13_at_11.49.21.png

Now when the push is received, should the app be in the foreground, the notification will not be displayed.

 

Tagging, events and special cases

Tagging and events can then be implemented in your app as follows:

Sample button showing how to hitEvent

<button onclick="XtremePush.hitEvent('test-event')"> Hit Event </button>

 

Sample button showing how to hitTag

<button onclick="XtremePush.hitTag('test-tag')"> Hit Tag </button>

 

There are special cases where you are able to send values as string or maps in the methods hitEventWithValue. To do that you can use this structure:

 

Sample button showing how to call hitEventWithValue (Value can be a String or a Hash)

<button onclick="hitEventWithValue()"> Hit Tag With Value </button>

And in the JS file:

fuction hitEventWithValue(){

//var stringOrHash = {0: "number0", 1: "number1"};

//var stringOrHash = "numbers";

XtremePush.hitEventWithValue('tagString', stringOrHash);

}

If you have any difficulty in configuring the implementation, a sample app can be built using the following two files:

index.html

index.js

A full list of our JavaScript functions and their parameters can be found in the xtremepush.js plugin file.

Advanced Options

Attributions

If you would like xtremepush to collect IDFA/Ad ID and attribution data in your app, we have a git branch of the plugin that copies the required frameworks into your app. This can be installed using the following command:

cordova plugin add https://github.com/xtremepush/XtremePush-Phonegap#master+attributions

To enable the collection functionality, the attributionsEnabled parameter in the XtremePush.register() function must also be set with a value of true.

 

Remove Location Services

If you would like to remove the geo-location and beacon frameworks and services from your app, please use the following command when installing the plugin:

cordova plugin add  https://github.com/xtremepush/XtremePush-Phonegap#master-geo-beacon

 

Inbox

The inbox feature can be turned on in your app by adding the following to your XtremePush.register()function:

inboxEnabled: true

Here is a sample button showing how to open inbox

<button onclick="XtremePush.openInbox()">Open Inbox</button>

If you want to use the inbox badge functionality please use the following in your XtremePush.register()function:

inboxBadgeCallback: "onInboxBadgeUpdate"

Here is a sample button showing how to retrieve the latest badge number:

<button onclick="XtremePush.getInboxBadge()">Get Inbox Badge</button>

Other

For any further customisation of the plugin, please feel free to fork the GitHub repository and make any changes you like in your forked version, before adding the plugin to your app.

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.