Kumulos provides an SDK in the form of a Cordova plugin to ease the integration of the Kumulos App Build, Push Notification and Analytics features into your hybrid app. This guide provides an overview of setting up the SDK for your project and sample usage.

The open-source Kumulos SDK is on Github https://github.com/Kumulos/KumulosSdkCordova and currently supports hybrid apps on iOS and Android, allowing you to:

  • Call API Methods - This feature takes URL encoded form POST requests and returns API method responses in JSON.
  • Upload Analytics - Upon instantiation, the Kumulos SDK will submit meta data about the current installation to Kumulos, including a unique installation ID (generated by Kumulos).
  • Receive push notifications - This feature provides methods to:
    • upload and store push tokens in Kumulos
    • track opens in Kumulos
    • subscribe to channels

Installation

The Kumulos SDK can be installed with the following command:

cordova plugin add cordova-plugin-kumulos-sdk

If you are using Ionic framework, then you need to prefix this command with ionic as is convention:

ionic cordova plugin add cordova-plugin-kumulos-sdk

N.B. The Kumulos Cordova plugin depends on Promises. Please ensure you have a suitable promise polyfill available in your app runtime. Frameworks such as Ionic usually include a polyfill default.

Initialization

The plugin defines a global window.kumulosSdk object containing:

  • Client - the SDK core class. This is required to provide apiKey and secretKey when instantiating the class.
  • getDeviceInfo() - the method to get device information. This returns a device info object which has the following properties:
  • iOSTokenType - the iOS push token type (development, ad-hoc, app-store), required for registering for push notifications on iOS only.
  • timeZone - time zone in IANA (Internet Assigned Numbers Authority) format

Although in the global scope, window.kumulosSdk is not available until after the deviceready event and this must be initialized before calling its methods. Please see the example below.

var kumulosClient

initializeSdk().then(function (client) {
    kumulosClient = client;
    console.log('Service initialized')
})

function initializeSdk() {
    return new Promise(function (resolve, reject) {
        document.addEventListener('deviceready', function () {
            var apiKey = 'XXXXXXXXXXXXXXXXXXXXXXXX';
            var secretKey = 'XXXXXXXXXXXX';
            var kumulosClient = new window.kumulosSdk.Client(apiKey, secretKey);
            resolve(kumulosClient);
        }, false);
    });
};

Your API Key and Secret Key can be obtained from your App Dashboard in your agency console.

You may also need to add https://*.kumulos.com to the Content-Security-Policy meta tag in your app, for example in www/index.html

The first time the Client object is initialized, a unique installation ID is generated and stored in a file located in a persistent and private data directory on the device. This is then uploaded to Kumulos along with other metadata for the app (e.g. version) and the device (e.g. platform, os version etc) for use in analtyics. The unique installation ID will then be retrieved from the persistent storage each time the client object is initialized for sending metadata and push tokens to Kumulos.

Calling API Methods

Example code to make an API call is shown below:

var params = {}
params.Name = $('#name').val()
params.Email = $('#email').val()
params.Password = $('#password').val()

kumulosClient.call('createCustomer', params)

Push Notifications

To receive and handle native push notifications, it is recommend to use Phonegap-plugin-push v1.10.5. For example:

cordova plugin add [email protected] --variable SENDER_ID="XXXXXXX"

Make sure the package name in config.xml matches the GCM/FCM project's package name (sometimes it is necessary to removing and re-add the android platform again to update this properly) cordova platform add android

The following example shows how to upload push token to Kumulos and then track opens using Phonegap-plugin-push.

var senderId = 'XXXXXXXXXXXX';

var push = window.PushNotification.init({
    android: {
        senderID: senderId,
        sound: true,
        forceShow: true
    },
    ios: {
        alert: 'true',
        badge: 'true',
        sound: 'true'
    }
})

push.on('registration', function(data) {
    kumulosClient.pushStoreToken(data.registrationId).then(function(response) {
        console.log(response.status);
    })
})

push.on('error', function(e) {
        console.log(e);
});

push.on('notification', function(data) {
    var id = data.additionalData.custom.i;
    kumulosClient.pushTrackOpen(id).then(function(response) {
        console.log(response.status);
    })
})

To remove the token from Kumulos server, please see the example below.

push.unregister(function(data) {
    kumulosClient.pushRemoveToken().then(function(response) {
        console.log(response.status);
    })
})

Finally, if you need to check whether the push notification permission has been granted, you can call the static method:

PushNotification.hasPermission(function(data) {
    if (data.isEnabled) {
        console.log('Push Notifications Enabled');
    }
});

Push Channels

The SDK provides methods for subscribing the app installation to push notification channels. These methods are accessed from the client's pushChannels manager property. The interface is declared as follows:

interface PushChannel {
    uuid: String;
    name?: String;
    subscribed: Boolean;
    meta?: any;
}

interface ChannelSpec {
    uuid: String;
    subscribe: Boolean;
    meta?: any;
    name?: String;
    showInPortal?: Boolean;
}

declare class PushChannelManager {
    constructor(credentials: Client.Credentials);
    subscribe(uuids: String[]): Promise<IResponse>;
    unsubscribe(uuids: String[]): Promise<IResponse>;
    setSubscriptions(uuids: String[]): Promise<IResponse>;
    clearSubscriptions(): Promise<IResponse>;
    listChannels(): Promise<PushChannel[]>;
    createChannel(channelSpec: ChannelSpec): Promise<PushChannel>;
}

For example, to list push channels:

kumulosClient.pushChannels
    .listChannels()
    .then(channels => console.log(channels))
    .catch(err => console.error(err));

This will return a list of all public channels (as well as any private channels this install is subscribed to) along with a boolean for whether or not this install is subscribed to that channel. For each channel, you will get:

{
    'uuid',
    'name',
    'meta',
    'subscribed'
}

When creating channels, you can control the visiblity and add meta-data.

Installation ID

When initialized for the first time, the Kumulos SDK will create a unique identifier for the app installation that initialized the SDK.

This identifier can be used to target push notifications to a specific device through KScript or the Push Notifications API.

In order to retrieve this installation ID, simply access the class variable:

kumulosClient.getInstallId().then(installId => {
    // Use the ID
}).catch(err => {
    // Something went wrong
    console.error(err);
});

Once you have the installation ID, you can send it to your app's backend to be used later for push targeting. For more information about push targeting, please see the KScript Documentation or push notification documentation as appropriate.

Location Tracking

You can send Kumulos location updates and use this to trigger events such as push notifications when an install enters a GeoFence.

How you configure location updates depends on the specific use case of your app. You should consider both accuracy and battery life when making this decision.

Once you have set up location updates from the OS, you can send them to Kumulos like so:

kumulosClient.sendLocationUpdate({lat: 0, lng: 0});

Plugins which can provide location updates include:

  • https://github.com/mauron85/cordova-plugin-background-geolocation
  • https://www.transistorsoft.com/shop/products/cordova-background-geolocation

Contributing

Pull requests are welcome for any improvements you might wish to make. If it's something big and you're not sure about it yet, we'd be happy to discuss it first. You can either file an issue or contact technical support.

License

This project is licensed under the MIT license with portions licensed under the BSD 2-Clause license. See our LICENSE file and individual source files for more information.

Thanks

We would like to thank to Travis Kriel from Sketch Advertising in South Africa for diligently correcting a mistake in this guide.