Kumulos provides an SDK in the form of an NPM package for your React Native apps.

Integration

Integrate SDK components and dependencies

The Kumulos SDK is an open source project hosted on Github. You can find a link to the project in your agency console and here: https://github.com/Kumulos/KumulosSdkReactNative. It is distributed via NPM for referencing in your apps.

To install the Kumulos SDK, run the commands shown below from your project's root directory.

npm install kumulos-react-native --save
react-native link kumulos-react-native
react-native link react-native-device-info

Initialization

To configure the SDK for use you need to initialize it with your app's API credentials. This should be done early in your application startup so that you can start calling API methods and using features.

const client = new KumulosClient({
    apiKey: "YOUR_API_KEY",
    secretKey: "YOUR_SECRET_KEY"
});

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

That's it, you're now good to go! Continue reading to learn more about analytics, configuring push notifications and calling Build API methods in your app.

Analytics

So long as you initialize the SDK at some point in your app's lifecycle, Kumulos will automatically record analytics data such as the device model, operating system version and more, available in Analytics & Reporting for your app.

Installation ID

When initialized for the first time, the Kumulos SDK will create a unique identifier for the current installation. This identifier can be used to target push notifications to a specific device via KScript or the Push Notifications API.

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

// Assuming client is an initialized KumulosClient instance
const id = await client.getInstallId();

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.

Once you have configured location updates on the platform of choice you can send the updates to Kumulos via the helper method in the stats namespace.

client.sendLocationUpdate(-54.618946, -65.234551);

Push

The Kumulos SDK provides push notifications via APNS and GCM. To integrate Kumulos Push into your app you have to complete the following steps.

Integration

The Kumulos SDK provides utility methods to handle push tokens, with push registration being performed by the defacto standard modules.

To use push notifications, install & link the additional dependencies:

npm install react-native-push-notification --save
react-native link react-native-push-notification

For iOS, you will also need to manually link PushNotificationIOS.

For Android, you need to set up the Android project correctly.

Note you also need to enable the "Push Notifications" capability and "Remote notifications" background mode in your iOS project, and ensure that provisioning is set up correctly.

After integration has been completed, you can configure the APNS or GCM projects as follows.

Configuring APNS

Configuring APNS for iOS with Kumulos

Configuring GCM

Configuring GCM for Android with Kumulos

Next you need to enable and configure the Kumulos push service with the certificates you have created.

After this setup has been completed, you can continue with the client integration.

Registering for and handling Push Notifications

The following sample code shows how to set up handlers using Kumulos and the React Native push notifications plugin to handle the most common push scenarios.

// index.js
import PushNotification from 'react-native-push-notification';
import configurePush from './push';

...

configurePush(kumulosClient);

When you are ready to request the push token from the user, you would then call:

PushNotification.requestPermissions();

The push configuration helper is shown below. This sample handles push conversion tracking and URL pushes for you, and can be adapted to suit your needs.

// push.js
import { Linking, Platform } from 'react-native';

import PushNotification from 'react-native-push-notification';

function sendLocalNotification(notification) {
    let opts = {};

    if (Platform.OS === 'android') {
        opts.title = notification.title;
        opts.message = notification.alert;
        opts.data = notification.custom;
    }
    else if (Platform.OS === 'ios') {
        opts.title = notification.alert.title;
        opts.message = notification.alert.body;
        opts.userInfo = notification.data.custom;
    }

    PushNotification.localNotification(opts);
}

function handleNotificationReceived(notification) {
    if (Platform.OS === 'android' && !notification.bgn) {
        sendLocalNotification(notification);
    }
}

function handleNotificationOpened(kumulosClient, notification) {
    let customFields = {};

    if (Platform.OS === 'android') {
        customFields = notification.data;
    }
    else if (Platform.OS === 'ios') {
        customFields = notification.data.custom;
    }

    // Track push open conversion
    kumulosClient.pushTrackOpen(customFields['i']);

    // Handle URL push, open in browser
    if (customFields['u']) {
        let url = customFields['u'];
        Linking.canOpenURL(url).then(supported => {
            if (!supported) {
            } else {
                return Linking.openURL(url);
            }
        }).catch(err => console.error('An error occurred', err));
    }

    // Take any other desired action, deep linking etc.
}

function handleNotification(kumulosClient, notification) {
    console.info(notification);
    if (notification.userInteraction === false) {//received
        handleNotificationReceived(notification);
    }
    else {//opened
        handleNotificationOpened(kumulosClient, notification);
    }
}

export default function configurePush(kumulosClient) {
    const options = {
        senderID: "YOUR GCM SENDER ID",
        onRegister: function (tokenObj) {
            kumulosClient.pushStoreToken(tokenObj.token);
        },
        onNotification: notification => handleNotification(kumulosClient, notification),
        requestPermissions: false,
        popInitialNotification: false
    };

    PushNotification.configure(options);
}

If you want to unregister the token for the current installation, you can use kumulosClient.pushRemoveToken().

Push channels

You can create and manage subscriptions to push channels from the SDK. Channels allow you to send push notifications to certain interest groups.

All channel management is performed through methods of the PushSubscriptionManager class.

import KumulosClient, {PushSubscriptionManager} from 'kumulos-react-native';

// Assume a configured kumulosClient instance to pass at construction
const subManager = new PushSubscriptionManager(kumulosClient);

The interface of the subscription manager is as follows:

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

export interface ChannelSpec {
    uuid: string;
    subscribe: boolean;
    meta?: any;
    name?: string;
    showInPortal?: boolean;
}

interface PushSubscriptionManager {
    constructor(client: KumulosClient);
    /**
     * Subscribes to the channels given by unique ID
     */
    subscribe(uuids: string[]): Promise<Response>;
    /**
     * Unsubscribes from the channels given by unique ID
     */
    unsubscribe(uuids: string[]): Promise<Response>;
    /**
     * Sets the current installations channel subscriptions to those given by unique ID.
     *
     * Any other subscriptions will be removed.
     */
    setSubscriptions(uuids: string[]): Promise<Response>;
    /**
     * Clears all of the existing installation's channel subscriptions
     */
    clearSubscriptions(): Promise<Response>;
    /**
     * Lists the channels available to this installation along with subscription status
     */
    listChannels(): Promise<PushChannel[]>;
    /**
     * Creates a push channel and optionally subscribes the current installation.
     *
     * Name is optional, but required if showInPortal is true.
     */
    createChannel(channelSpec: ChannelSpec): Promise<PushChannel>;
}

When creating channels, the visiblity and meta data can be controlled. Please make sure you understand these concepts when creating channels from the SDK.

Build

You can call API methods defined in the Kumulos Build service using the Kumulos.Call method.

To talk to Kumulos, you need two things:

  • your method title (in lowerCamelCase)
  • an (optional) parameters object

Kumulos.call returns a promise, see example usage below:

try {
    const data = await kumulosClient.call("yourMethodName", params);
}
catch (err) {
    console.error(err);
}

And you're done! You can now make calls to Kumulos from your React Native application. The data object returned by Kumulos.call can be either an array of objects (in case of a select action) or a number in case of other actions.

Changelog

1.0.0

  • Initial release with Analytics, Push, and Build support for iOS & Android