Introduction

The Kumulos SDK is an open source project hosted on Github and can be found at https://github.com/Kumulos/KumulosSdkReactNative.

This guide assumes you have completed the steps from the introduction and have configured your project via the Apple Developer Account and the Firebase Console, it will cover the following steps:

  1. Integrate the SDK and configuring your project for APNS/FCM capability

  2. Initializing the SDK components within your project and register for push notifications

  3. Register the Kumulos InstallationID with your backend to provide a link between the device and your users represented in your CRM backend for later targeting of notifications.

  4. Sending a test push notification from your Unica app and receiving on the device.

  5. Custom analytics events

  6. Optional advanced behavior for native push notifications

  7. Optional advanced behavior for rich In-App messages

Integration

The Kumulos React Native module requires native features so should be installed in an ejected project.

To install & link the project, run the following commands:

npm install kumulos-react-native --save
pod install --project-directory=ios

Manual linking steps are required for each platform.

Android Linking Steps

To complete the linking process for Android, you need to ensure your project uses the following versions for tools & libraries:

  • Gradle plugin v3.1.3 or greater
  • Build tools v23.0.3 or greater
  • Support library v27.+

Place the google-services.json created during the introduction in your project's android/app directory.

In addition, you must add the following to your android/app/build.gradle file:

android {
    // ...
    packagingOptions {
        exclude 'META-INF/NOTICE'
        exclude 'META-INF/ASL2.0'
        exclude 'META-INF/LICENSE'
    }

    dependencies {
    // Kumulos debug & release libraries
        classpath 'com.google.gms:google-services:4.2.0'
    }

    // ADD THIS AT THE BOTTOM
    apply plugin: 'com.google.gms.google-services'
}

iOS Project Configuration

The notification will expand upon swiping the notification on devices supporting 3D Touch. In order to enable this functionality you need open your iOS project in Xcode and add a Notification Service Extension to your application.

Add a Notification Service extension

In order to support all the features of the Apple Push Notifications Service your app must have a notification service extension in order to allow some limited processing of the notification on receipt, before the operating system presents it to the user.

This is a second build target added to your existing xcode project by going to your project info screen and clicking the '+' button at the footer.

Build targets

From the popup window, select the Notification Service Extension template for your new project and click 'Next'.

Service Extension Template

On the final window add an appropriate name for your extension and click 'Finish'.

Service Extension Configuration

Add the following to the Podfile generated by React Native and run pod install.

target 'KumulosNotificationServiceExtension' do
  pod 'KumulosSdkObjectiveCExtension', '4.2.2'
end

The template for the project will have created a file named NotificationService.m automatically, replace its content with the following lines:

#import "NotificationService.h"
#import <KumulosSDKExtension/KumulosNotificationService.h>

@interface NotificationService ()
@end

@implementation NotificationService
- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
   [KumulosNotificationService didReceiveNotificationRequest:request withContentHandler: contentHandler];
}
@end

The Kumulos SDK helper functions will automatically add picture attachments and buttons to the notification content.

Configure your app capabilities and entitlements

In your app project settings use the "+ capability" button to add the App Groups, Background Modes and Push Notifications capabilities.

In your Notification Extension use the "+ capability" button to add the App Groups capability.

In both projects the App Groups capability should be configured to share the same group, this must exactly match the group defined in your Identifiers capabilities earlier.

group.{your.bundle.identifier}.kumulos

In your app project the Background Modes should have the "Remote Notifications" mode checked.

Test your configuration

At this point you can test deploy your app onto a device to ensure that your entitlements and capabilities are configured correctly.

Make sure to correctly set up signing for the extension target.

Initialization

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

In your App.js:

import Kumulos from 'kumulos-react-native';

Kumulos.initialize({
    apiKey: 'YOUR_API_KEY',
    secretKey: 'YOUR_SECRET_KEY'
});

// When you are ready to request the push token from the user, you would then call:
Kumulos.pushRequestToken();

In your ios/AppDelegate.m application:didFinishLaunchingWithOptions: method:

#import <KumulosReactNative/KumulosReactNative.h>
...
KSConfig* kumulosConfig = [KSConfig
                                configWithAPIKey:@"YOUR_API_KEY"
                                andSecretKey:@"YOUR_SECRET_KEY"];
[kumulosConfig enableInAppMessaging:KSInAppConsentStrategyAutoEnroll];
[KumulosReactNative initializeWithConfig:kumulosConfig];

You should also enable Background Fetch in Background Modes capabilities section of your Xcode project.

In your android/app/src/main/java//MainApplication.java onCreate method:

import com.kumulos.android.KumulosConfig;
import com.kumulos.reactnative.KumulosReactNative;
...
KumulosConfig.Builder kumulosConfig = new KumulosConfig.Builder("YOUR_API_KEY", "YOUR_SECRET_KEY");
kumulosConfig.enableInAppMessaging(KumulosConfig.InAppConsentStrategy.AUTO_ENROLL);
KumulosReactNative.initialize(this, kumulosConfig);

Registering with your CRM

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 later to target push notifications to a specific device.

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

const id = await Kumulos.getInstallId();

Once you have the installation ID, you can send it to your app's CRM backend to be used later for push targeting.

User Association

If your app makes use of an identifier to uniquely tell which user is signed into a device (for example a primary key integer or UUID, or an email address), you can send this identifier to Kumulos for later push targeting via the same key.

Kumulos.associateUserWithInstall('unique-user-identifier');

Sending a test

TODO: Unica system / screenshots.

Event Tracking

Kumulos allows you to track custom analytics events in order to observe your users activity in your app, allowing you to analyse behavior and optimize journeys to ensure your users are getting the full benefit of your app's features.

To track a custom analytics event, use Kumulos.trackEvent as follows:

Kumulos.trackEvent("product.purchased", {
  productId: 404,
});

Each event and its properties must be less than 250 KiB in size for the event to be tracked.

Event tracking is available offline as all events are persisted locally before being synced to the server in batches in the background.

A similar method trackEventImmediately will immediately start an event sync rather than waiting for the next time the app is backgrounded.

Push Notification Advanced features

Handling open events or background data pushes

The following sample code shows how to use Kumulos to handle push notifications for deep-linking and other common messaging tasks.


import Kumulos from 'kumulos-react-native';

Kumulos.initialize({
    apiKey: 'YOUR_API_KEY',
    secretKey: 'YOUR_SECRET_KEY',
    pushReceivedHandler: (notification) => {
        // Called when a push is received with your app in the foreground
    },
    pushOpenedHandler: (notification) => {
        // Called when a user taps on a push notification
    }
});

Handling notification action buttons

When a user interacts with your push message the pushOpenedHandler defined as above is called. If a button was tapped, the notification object will contain an actionId property:

Kumulos.initialize({
    ...
    pushOpenedHandler: (notification) => {
        console.log(notification.actionId);
    },
});

In-App Advanced Features

If you would like your users to opt-in to receive In-App messages you can configure the SDK during initialization to make opt-in explicit by setting the strategy, then calling the SDK helper to manage their consent.

In your ios/AppDelegate.m application:didFinishLaunchingWithOptions: method:

#import <KumulosReactNative/KumulosReactNative.h>
...
KSConfig* kumulosConfig = [KSConfig
                                configWithAPIKey:@"YOUR_API_KEY"
                                andSecretKey:@"YOUR_SECRET_KEY"];
[kumulosConfig enableInAppMessaging:KSInAppConsentStrategyExplicitByUser];
[KumulosReactNative initializeWithConfig:kumulosConfig];

In your android/app/src/main/java//MainApplication.java onCreate method:

import com.kumulos.android.KumulosConfig;
import com.kumulos.reactnative.KumulosReactNative;
...
KumulosConfig.Builder kumulosConfig = new KumulosConfig.Builder("YOUR_API_KEY", "YOUR_SECRET_KEY");
kumulosConfig.enableInAppMessaging(KumulosConfig.InAppConsentStrategy.EXPLICIT_BY_USER);
KumulosReactNative.initialize(this, kumulosConfig);

Once the configs have been set, you can now manage consent from the JS layer:

import { KumulosInApp } from "kumulos-react-native";

KumulosInApp.updateConsentForUser(true);

Note managing consent explicitly with the AUTO_ENROLL strategy is not supported and will result in a runtime exception

Deep-linking for In-App

In-App messages allow you to hand-off to react-native application screens via deep-linking action buttons. When tapped, these buttons pass control to the defined deep-link handler, including their defined data payload (configured in the In-App message composer for the action button).


import Kumulos from 'kumulos-react-native';

Kumulos.initialize({
    ...,
    inAppDeepLinkHandler: (data) => {
        // Called when a user taps a deep-link action button from an in-app message
    }
});

Using the In-App Inbox

In-app messages can optionally be persisted in a user-level inbox for later retrieval. This allows you to build features such as loyalty rewards or expiring coupons into your app. Regardless of whether they are stored in the inbox, the maximum amount of in-apps stored on a device is 50 (the oldest messages exceeding this limit will be evicted).

Retrieve messages

To retrieve a list of messages from the user's inbox and present the first in the list, see the following example:

KumulosInApp.getInboxItems().then(function (items) {
  KumulosInApp.presentInboxMessage(items[0]);
});

Mark as read

To mark a single or all inbox messages as read:

//single
KumulosInApp.getInboxItems().then(function (items) {
  KumulosInApp.markAsRead(items[0]);
});

//all
KumulosInApp.markAllInboxItemsAsRead();
Delete message

You can also delete an in-app message from inbox:

KumulosInApp.getInboxItems().then(function (items) {
  KumulosInApp.deleteMessageFromInbox(items[0]);
});

Inbox updated handler

In order to be notified when inbox changes you may set up a handler. The handler fires when one of the following happens to an in-app with an inbox configuration:

  • message fetched from server
  • message opened
  • message marked as read
  • message deleted
  • message evicted (expires or limit of stored messages exceeded)

You can use it as follows:

KumulosInApp.setOnInboxUpdatedHandler(() => {
  //refresh your inbox
});

Note, you can do KumulosInApp.setOnInboxUpdatedHandler(null) when you stop being interested in inbox updates.

Get inbox summary

You can retrieve an inbox summary as follows:

KumulosInApp.getInboxSummary()
  .then((summary) => {
    console.log(
      "total: " + summary.totalCount + " unread: " + summary.unreadCount
    );
  })
  .catch(() => {
    console.log("failed to get inbox summary!");
  });

Get inbox item's image URL

Each inbox item may have an image associated with it. imageUrl returns a URL to the image resized to 300px width or null if there is no image.

KumulosInApp.getInboxItems().then(function (items) {
    const url = items[0].imageUrl;
}

Changelog

1.1.0

  • Add In-App messaging to configuration
  • Add analytics event tracking
  • Break out advanced features into In-App and Push Notification headings, add In-App advanced config and Inbox features.
  • Standardize headings

1.0.0

  • Initial integration guide