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 secreteKey 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.

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.