Skip to content

Website & PWA

Integration

Kumulos provides an SDK to ease the integration of the Kumulos Analytics and Push Notification features into your web project. This guide provides an overview of setting up the SDK for your project and sample usage.

Project Setup

The Kumulos libraries are distributed through a CDN or NPM. For both integrations, you will need your Kumulos API key and secret key which can be found on the app dashboard in Kumulos' control panel. For configuring web push, you will also need the VAPID public key from the web push configuration dialog.

Note that in order to use web push notifications, your site must be served over HTTPS.

Website/CMS Projects using CDN

If you are integrating Kumulos into a WordPress Site, please see the video in our WordPess Setup Guide below. Otherwise, select the app, expand 'Messaging' in the left menu, click 'Configuration' and then the cog next to the web icon.

Click the copy icon to copy the code snippet (that includes your Kumulos API key, secret key and VAPID public key) and paste this into the <head> tag.

Web Push SDK Code Snippet for CDN

Next, host a service worker at https://your-domain.com/worker.js with the code snippet copied from the 'worker' tab of the web push configuration dialog:

Web Push SDK Service Worker Code Snippet

PWA/SPA Projects using NPM

Start by adding the package dependency to your project:

npm install --save @kumulos/web

Initialization

After installation, import and initialize the SDK in your application code using the code snippet from the 'NPM' tab of the web push configuration dialog:

Web Push SDK Code Snippet for CDN

Next, host a service worker at https://your-domain.com/worker.js with the code snippet copied from the 'worker' tab of the web push configuration dialog:

Web Push SDK Service Worker Code Snippet

Configuring Service Worker Location

If you want to host the service worker file at a different path on your domain, you can configure the path during initialization as follows:

Kumulos('init', {
    apiKey: 'YOUR_API_KEY',
    secretKey: 'YOUR_SECRET_KEY',
    vapidPublicKey: 'YOUR_VAPID_KEY',
    serviceWorkerPath: '/wp-content/themes/your-theme/assets/sw.js'
});

Checking Integration

When you run visit your web project in a browser, you can check that the SDK has been initialized correctly by selecting the app and clicking the Installs tab to see the ten most recent installs of your project. Click on any install to see more information.

Recent installs

If you experience any difficulties integrating an SDK or initializing the Kumulos client, please don't hesitate to contact support who are standing by to help!

Installation ID

When initialized for the first time, the Kumulos SDK will create a unique identifier for the web 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 method.

For website projects:

Kumulos(function (client) {
    client.getInstallId().then(function (installId) {
        // Use the install ID for something
    });
});

For PWA projects:

const installId = await kumulosClient.getInstallId();

Once you have the installation ID, you can send it to your web 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.

Analytics

Kumulos provides concise and easy to consume analytics & reporting features. By initializing the SDK, you automatically get engagement reporting and page view events out the box.

Event Tracking

Kumulos allows you to track custom analytics events that can be used as a trigger to fire automation rules (e.g. to trigger a push notification) or as steps in a funnel to track conversion through key user journeys in your project.

Track conversion

To track a custom analytics event, use the trackEvent method.

For website projects:

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

For PWA projects:

kumulosClient.trackEvent('product.purchased', {
    productId: 404
});

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

Checking Events from your Project

When you test your project, you can check that the SDK is recording events correctly by selecting the app and clicking the Installs tab to see the ten most recent installs of your project. Click on any install and then click on the Events tab.

Install events

Alternatively, to see counts of all analytics events, including system events such as opened a push notification, recorded by installs of the app in the last 30 days, expand 'Analytics' and click 'Explore' in the left menu.

Analytics Explorer

Page View Events

For website projects, the Kumulos SDK automatically gathers page view events which include the following properties:

  • page title (e.g. Checkout)
  • path (e.g. /blogs/super-cool-announcement)
  • query parameters (e.g. utm=your_campaign)

For PWA projects, you can track page view events as follows by hooking into your SPA router. For example (using the history module):

import { createBrowserHistory } from 'history';
import Kumulos from '@kumulos/web';

const kumulosClient = new Kumulos({...});
const history = createHistory();

history.listen(location => {
    let query = undefined;
    const qs = location.search;

    if (qs.length > 0) {
        query = qs
            .substring(1)
            .split('&')
            .map(vars => vars.split('='))
            .map(pairs => pairs.map(decodeURIComponent))
            .reduce((q, pair) => ({ ...q, [pair[0]]: pair[1] }), {});
    }

    kumulosClient.trackEvent('k.pageViewed', {
        title: 'your page title',
        path: location.pathname,
        query
    });
});

User Association

Kumulos allows associating a user identifier with the current installation ID. This user identifier is useful for performing analytics aggregations & analyses at the user level, for example, funnels completed by users across multiple devices. You can also optionally associate a collection of attributes with the user.

To associate the current app installation with a user, you can use the helper method as shown below.

For website projects:

Kumulos('associateUser', 'unique-user-id');

For PWA projects:

kumulosClient.associateUser('unique-user-id');

User association is time-aware, so say two different users log in to the app, their user IDs will be associated with the same install for the time between subsequent calls to the helper method. For example:

Kumulos('associateUser', 'Bob');
// This event will belong to Bob
Kumulos('trackEvent', 'product.purchased');
Kumulos('associateUser', 'Alice');
// This event will belong to Alice
Kumulos('trackEvent', 'product.purchased');

Attributes

You can optionally associate a collection of attributes with the user for targeting, personalization or attribution. To associate attributes with the user, pass a collection into the helper method as shown.

Kumulos('associateUser', 'unique-user-id', {
    name: 'Shawn',
    age: 25
});

The collection of attributes for a given user must be less than 250 KiB in size.

If you do not have a user identifier, use the installation ID generated by the Kumulos SDK.

Messaging & Push Notifications

Kumulos provides powerful multi-channel messaging services to reach your users. By initializing the SDK you can quickly and easily receive push notifications to re-engage your users and keep them up to date.

Configuration & Setup

To integrate into your web project, you have to complete the following steps:

  1. Enable Push in the Kumulos Agency Console
  2. Integrate the SDK components with your web project
  3. Register to receive push notifications from your website or PWA

Registering for Web Push Notifications

In order to send push notifications to your users, you have to request permission to send them notifications. This section outlines how to request permission using the Kumulos Soft Prompts (recommended), or requesting permission directly from a widget of your choosing.

Using Soft Prompts

The soft prompt mechanism offers the user a method to indicate intent to opt in to notifications prior to being asked for the native browser permission. Soft prompts follow best-practices for user experience and will stay up to date with current browser requirements.

You can configure the soft prompts in the SDK with the pushPrompts option during initialization, passing either 'auto' (default), or an object describing the prompts.

In the case of 'auto', the prompt configuration will be managed from the Kumulos Console's web-push configuration page.

Auto Resubscribe

If you have previously used another web push notification system, then by default users who have previously subscribed for web push notifications from the previous system, will automatically be resubscribed to receive web push notifications from Kumulos on their next site visit with no interaction necessary.

Advanced

Setting prompts in code

Alternatively, you can specify the prompts in the code directly:

Kumulos('init', {
    apiKey: 'YOUR_API_KEY',
    secretKey: 'YOUR_SECRET_KEY',
    vapidPublicKey: 'YOUR_VAPID_KEY',
    pushPrompts: {
        'my-bell-prompt': {
            type: 'bell',
            trigger: {
                event: 'k.pageViewed',
                afterSeconds: 3,
                filters: [
                    ['path', 'in', ['/', '/blog/*']],
                ]
            },
            labels: {
                tooltip: {
                    subscribe: 'Get the latest updates!'
                }
            },
            colors: {
                bell: {
                    bg: '#fa0',
                    fg: '#fff'
                }
            },
            position: 'bottom-left'
        }
    }
});

The above example defines a bell prompt which will show to the user on the home and blog pages, after three seconds of being on the page.

Prompt configuration follows the following interfaces:

type FilterOperator = 'in';
type FilterValue = number | boolean | string | string[];
type PropFilter = [string,FilterOperator,FilterValue];

interface PromptTrigger {
    event: string;
    afterSeconds?: number;
    filters?: PropFilter[];
}

interface BellPromptConfig {
    type: 'bell';
    trigger: PromptTrigger;
    labels?: {
        tooltip?: {
            subscribe?: string;
        };
    };
    colors?: {
        bell?: {
            bg?: string;
            fg?: string;
        };
    };
    position: 'bottom-left' | 'bottom-right';
}

Request Directly

To prompt your user for permission directly, you can use the pushRegister method. This will ask the user to accept notifications, and then subscribe them if they accept.

It is strongly recommended to prompt the user as a result of interaction on the page. Once a user blocks notifications, you cannot prompt them again using the browser's dialog so it's a good idea to ask them if they'd like update before calling the pushRegister method.

Future browser updates will likely make this mandatory for many browsers

In a website project:

Kumulos('pushRegister');

For a PWA project:

kumulosClient.pushRegister();

Safari Configuration

To support sending notifications to desktop Safari, configuration of the following items is necessary:

  • Site URL
  • Icon (square, >=512px)
  • APNS certificate

To generate an APNS certificate, you need access to an Apple Developer account.

Generating a Safari Push Certificate

In the Apple Developer console, add a new identifier for your website.

Add Website Push Identifier

Next, navigate to the certificates list. From here, add a new certificate.

For the type of certificate, choose Services > Website Push ID Certificate:

Website Push ID

Generate a Certificate Signing Request (CSR) using the Keychain Access app:

Request Certificate Wizard

Save CSR to Disk

Upload the generated CSR into the developer console:

Upload CSR

Download the issued certificate:

Download certificate

Once downloaded, open the certificate file to add it to your keychain.

Now export the certificate & private key from the Keychain access tool as a P12 file:

Export P12

Finally, upload the certificate into the Kumulos Messaging Web Configuration modal, and fill in the site URL and icon fields:

Configure Safari Push

Checking Integration Status

When you test your project, you can check that the integration has been successful using the install browser by selecting the app in the Kumulos Console and clicking the Installs tab to see the ten most recent installs of your project.

Click on an install, click the 'Push' tab and click Send Test Push.

Install push details

If you do not receive the push notification, check the Error Log for any errors sending the push notification to the native push gateways. If you continue to experience problems, please don't hesitate to contact support who are standing by to help!

Handling Notification Events

The Kumulos SDK exposes two optional handlers for notification events. These handlers can be used to perform actions on your page in response to notification data and content.

To configure the handlers, pass functions to the initialization options:

new Kumulos({
    // ... other options
    onPushReceived: function (n) {
        console.log('Received: ', n);
    },
    onPushOpened: function (n) {
        console.log('Opened: ', n);
    }
});

Both handlers are optional.

onPushReceived will be triggered on all currently open tabs when any push notification is received from Kumulos.

onPushOpened will be triggered on the newly-opened tab after Kumulos has been initialized. Any other open tabs will not receive the open callback.

Note Safari is not supported due to lack of W3C push implementation.

Both handlers receive a notification object as their only argument, it has the following interface:

interface KumulosPushNotification {
    id: number;
    title: string;
    message: string;
    url?: string;
    iconUrl?: string;
    imageUrl?: string;
    data: {
        [key: string]: any;
    };
}

Channels

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

All channel management is performed with an instance of the ChannelSubscriptionManager. The manager is available from an SDK client instance as follows.

For website projects:

Kumulos(function (kumulosClient) {
    var subscriptionManager = kumulosClient.getChannelSubscriptionManager();
});

For PWA projects:

const subscriptionManager = kumulosClient.getChannelSubscriptionManager();

All further examples will reference the subscription manager, which exposes the following interface:

interface Channel {
    uuid: string;
    name?: string;
    subscribed: Boolean;
    meta?: PropsObject | null;
}
interface ChannelSpec {
    uuid: string;
    subscribe: boolean;
    meta?: PropsObject | null;
    name?: string;
    showInPortal?: boolean;
}
interface ChannelSubscriptionManager {
    /**
     * 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<Channel[]>;
    /**
     * Creates a push channel and optionally subscribes the current installation.
     *
     * Name is optional, but required if showInPortal is true.
     */
    createChannel(channelSpec: ChannelSpec): Promise<Channel>;
}

Channel visibility and metadata

Channel visibility and meta data can be controlled when they are created.

Browser Feature Support

The following table illustrates which web push features are supported by different browsers on different operating systems.

Web Push Browser Feature Support

Web-to-App Banners

Web-to-App Banners allow you to direct website users to your mobile app using a Deferred Deep Link. These banners are configured in the Kumulos console, and show on your website when the configured condition is met.

In order to enable the banners feature for your website, you must:

  • Configure Deferred Deep Linking for your app
  • Complete the basic SDK integration steps as shown at the start of this guide
  • Enable deferred deep linking support for the web SDK

Once the web SDK snippet has been included on your site, you simply need to enable the deferred deep linking feature in the web SDK initialization as follows:

Kumulos("init", {
    apiKey: "YOUR_API_KEY",
    secretKey: "YOUR_SECRET_KEY",
    vapidPublicKey: "YOUR_VAPID_KEY",
    // Add the features key with 'ddl' to enable web-to-app banners
    features: ['push', 'ddl']
});

Note when features is not specified, the web SDK defaults to enabling the 'push' feature. You can also disable the push feature and only use web-to-app banners by passing features: ['ddl'] (this also makes the vapidPublicKey optional).

Once the feature has been enabled, you can configure Web-to-App Banners as shown in the user guide.

Troubleshooting

If you are having issues with elements of the SDK integration, and push prompts or web-to-app banners are not displaying on your site or push registration is not working, we advise that you check through the below sections for tips on how to troubleshoot the integration.

Snippet

You can check the status of the snippet in your browser's development tools.

First, check the snippet included in the source code of the page. This requires the correct credentials (apiKey, secretKey, and vapidPublicKey)? Compare the code snippet to the snippets given in the integration section

You can view the SDK being initialised through developer tools of your browser. You can look for any error logs in the developer tools console, they may indicate integration problems.

Web Troubleshooting Configuration

Otherwise you will see the bundle being loaded successfully with a 200 status in the network traffic tab of the developer tools.

Web Troubleshooting Configuration

Domain

Another element that can be checked is the domain of site and location of the ServiceWorker.

First the site needs to be served over HTTPS as opposed to HTTP. Next, ensure that the domain the snippet is present on matches the domain configured in Kumulos. The configuration can be checked in the Messaging area of the platform under Configuration on the console by clicking on the gear icon next to the web symbol.

Web Troubleshooting Configuration

If this is correct then check that the worker code is also hosted on the same domain as the integration target listed in Kumulos

Web Troubleshooting Configuration

If you are using subdomains, all integration & files must be part of the same subdomain.

ServiceWorker

The 'worker.js' file should be hosted at a /worker.js path. For example if your domain name was 'cloudburger.com', the 'worker.js' file should be hosted at https://cloudburger.com/worker.js and the content type should be 'application/javascript'

If your integration is unreliable it is advisable to check if there are any other ServiceWorker registrations being made on the same site.

If you have two ServiceWorkers running on the same site this will cause conflicts and inconsistencies in how the integration will operate because only one ServiceWorker may be active for a domain at a time (this is a limitation of the ServiceWorker specification, not Kumulos).

WordPress Setup Guide

The following video shows how to add Kumulos Web Notifications to your WordPress site.

Configuring Notifications for WordPress with Kumulos

The relevant code snippet for your functions.php is as follows:

<?php


function kumulos_init_web_push()
{
    echo <<<'END'
<script>
    (function(w,p){w[p]=w[p]||function(){w[p].q=w[p].q||[];w[p].q.push(arguments)}})(window,"Kumulos");

    Kumulos("init", {
        apiKey: "YOUR_API_KEY",
        secretKey: "YOUR_SECRET_KEY",
        vapidPublicKey: "YOUR_VAPID_KEY"
    });
</script>

<script src="https://static.app.delivery/sdks/web/main.js" async></script>
END;
}

add_action('wp_head', 'kumulos_init_web_push');>

Changelog

1.10.0

  • Add support for probabilistic matching for Web-to-App banner handover to mobile SDKs

1.9.0

  • Web prompt icons for Alerts and Banners are now driven from prompt configuration as opposed to pulling directly from the configured web platform icon.

1.8.1

  • Support device safe area or "notch" on iPhone devices in Web-to-App banners
  • Minor enhancement and fix to feature requirement checking where the SDK could potentially fail to initialise ddl feature if the push feature was unsupported on safari/iphone

1.8.0

  • Add support for Web-to-App Banners
  • Update dependencies for latest patches

1.7.2

  • Fix DOMContentLoaded event edge case

1.7.1

  • Add channel selection prompt support to allow users to subscribe to topics of interest during push registration

1.7.0

  • Add banner style soft prompt feature
  • Additional positioning & appearance options for alert prompt types

1.6.0

  • Add alert style soft prompt feature

1.5.1, 1.5.2, 1.5.3, 1.5.4

  • Update dependencies for latest patches
  • Fix edge case with prompt trigger matching (1.5.3)
  • Fix edge case with prompt rendering on some websites (1.5.4)

1.5.0

  • Add notification event handlers for notification received and opened

1.4.0

  • Safari push notifications support
  • Allow subscribing to a channel from a soft prompt

1.3.1

  • Fix soft prompt heading color

1.3.0

  • Add configurable, optional interstitial page overlay shown when requesting native push permission

1.2.3

  • Fix base64 URL variant encoding

1.2.2

  • Render prompt UI using a portal

1.2.1

  • Reduce cache time for prompt config to one hour

1.2.0

  • Add auto resubscribe feature for migrating push subscriptions to Kumulos on next site visit
  • Implement all filter operators for soft prompt triggers

1.1.0

  • Add a configurable 'bell' soft prompt for push notifications
  • Show push notifications until the user dismisses them

1.0.1

  • Fix bug handling URL opening

1.0.0

  • Initial release with support for web push notifications and analytics events