Configuring a Cordova Client

important

Before you begin configuring a Cordova application to receive push messages, you should have the following installed, available, or configured as appropriate:

  • Java 8 (no newer versions since they would cause errors with the advmanager)
  • Node.js
  • Cordova (see Cordova Documentation)
  • Android Studio if developing for an Android platform
  • XCode if developing for an iOS platform

In this document we will give step by step instructions to build a very simple application that is able to receive push notifications using the aerogear push sdk.

Running the samples in the android emulator

This documentation will use the cordova emulate android command to run the samples. This command expects the emulator to be already up and running. To start the emulator use the emulator @AVDMNAME -no-snapshot-load commmand, replacing AVDNAME with your AVD. To have the list of AVDS use emulator -list-avds

The emulator command can be found in the emulator folder of the Android SDK.

Create a new project

To create a new cordova application, run the following command:

cordova create upshello org.aerogear.PushHelloWorld UpsHelloWorld
cd upshello
cordova platform add ios
cordova platform add android

This will create an application named UpsHelloWorld inside the upshello folder with package org.aerogear.PushHelloWorld. The two platform add commands will add the platforms we want to target (in this example iOS and Android).

Now check that all the requirements are installed with:

cordova requirements

If any of the requirements is not satisfied, fix them before continuing.

Two commonly missing requirements are:

  • The SDK. To install the SDK:
    1. Open Android Studio
    2. Click on Tools -> SDK Manager
    3. Select Android SDK and check Android 9.0 Pie
    4. Click on Apply
  • The gradle tool. The installation of gradle depends on the platform you are running on (see Gradle Installation)

If all the requisites are satisfied, test that everything works by running:

cordova build
cordova emulate android
cordova build
cordova emulate ios
important

To avoid signing issues when running on iOS, do not connect any iOS device to your development machine.

Installing the push libraries

To be able to use the push sdk you will need to install the following packages:

  • cordova-plugin-device: this is used by the SDK to detect the platform the sdk is running on
  • @aerogear/cordova-plugin-aerogear-push: this is the cordova plugin for the push sdk
  • @aerogear/push: this is the push sdk package

To install those packages, run:

cordova plugin add @aerogear/cordova-plugin-aerogear-push
cordova plugin add cordova-plugin-device
npm install --save @aerogear/push
note

If you are targeting an android device, you will need to put the google-services.json file into the platforms/android/app folder.

To get that file, you must create an app in your FireBase account (with package org.aerogear.PushHelloWorld) and download it from there.

Installing webpack

The following steps will be needed to correctly install webpack:

  1. install the cordova-plugin-webpack plugin 
    $ cordova plugin add cordova-plugin-webpack
  2. create an src folder 
    $ mkdir src
  3. move the index.js file from www/js to src 
    $ mv www/js/index.js src
  4. create a configuration file for webpack 
    $ echo "const path = require('path');
  module.exports = {
    mode: 'development',
    entry: './src/index.js',
    output: {
      path: path.resolve(__dirname, 'www/js'),
      filename: 'index.js',
    },
    devtool: 'inline-source-map',
  };" > webpack.config.js

Enabling clear-text connection

If your UnifiedPush Server is exposed on an http address, you will need to enable clear-text connection in your application by editing the Content Security Policy in your www/index.html file

Change

<meta 
    http-equiv="Content-Security-Policy" 
    content="default-src 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *; img-src 'self' data: content:;">

to

<meta 
    http-equiv="Content-Security-Policy" 
    content="default-src 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *; img-src 'self' data: content:; connect-src http://*:*">
caution

In this example, we enabled clear-text on every site. A better choice would be to put the IP Address of your UnifiedPush Server instead of the *

If you are targeting android you will have to add this to your config.xml file

<edit-config file="app/src/main/AndroidManifest.xml" mode="merge" target="/manifest/application" xmlns:android="http://schemas.android.com/apk/res/android">
  <application android:usesCleartextTraffic="true" />
</edit-config>

Register the application with the UnifiedPush Server

To register the application, you must use the PushRegistration object from the @aerogear/push package with a code similar to the following:

function register() {
  console.log('Registering...');
  new PushRegistration({
      url: 'http://192.168.1.187:9999',  // change this to your UPS URL
      android: { // your variant platform (android, ios or webpush)
          senderID: '829475845435',  // Your senderID as you see it in your Firebase Console
          variantID: '172bf953-f266-4e32-866b-662ff32d653c', // The id of the variant you created
          variantSecret: '7680585e-c22e-4105-b0fc-fbcb150036d4' // the secret of the variant you created
      }
  })
  .register()
  .then(() => {
      console.log('Registered!');
  })
  .catch(error => {
      console.log('Failed: ', error.message, JSON.stringify(error))
  });
}

Receiving Push Notifications

Receiving Push Notifications is as simple as registering a callback handler:

PushRegistration.onMessageReceived((notification => {
  console.log('Received push notification: ', notification.message);
}));

Complete code

Change the src/index.js file with the following content:

import { PushRegistration } from '@aerogear/push';

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;');

    this.registerToUPS();

    PushRegistration.onMessageReceived((notification => {
      console.log('Received push notification: ', notification.message);
    }));
  },

  registerToUPS: () => {
    console.log('Registering...');
    new PushRegistration({
      url: 'http://192.168.1.187:9999',  // change this to your UPS URL
      android: { // your variant platform (android, ios or webpush)
        senderID: '829475845435',  // Your senderID as you see it in your Firebase Console
        variantID: '172bf953-f266-4e32-866b-662ff32d653c', // The id of the variant you created
        variantSecret: '7680585e-c22e-4105-b0fc-fbcb150036d4' // the secret of the variant you created
      }
    })
    .register()
    .then(() => {
      console.log('Registered!');
    })
    .catch(error => {
      console.log('Failed: ', error.message, JSON.stringify(error))
    });
  }
};

app.initialize();

Running the application

The application can run in the emulator for Android, while it needs to run on a real device for iOS (the iOS simulator does not support push notifications).

  1. Be sure that the emulator is already up and running
  2. Issue cordova emulate android
  1. Connect an iOS device to the USB port of your mac
  2. Run XCode with 
    $ open platforms/ios/UpsHelloWorld.xcworkspace
  3. Configure the Signing and Capabilities
  4. Click on the run icon

Throubleshooting

cordova emulator android takes forever to install the app into the emulator

This can happen when the cordova emulator android command is not able to install the app into the emulator. To solve the issue, simply close the emulator and run it again with

emulator @AVDNAME -no-snapshot-load
← React Native ClientJava Sender API →