Overview

Push notifications are an effective way to keep users engaged with an app.

Once enabled and configured, you will be able to send unlimited push notifications to unlimited iOS and Android devices, when specific events occur in your app.

You will also be able to send notifications from within your agency console and even let your clients send push notifications from their client portal.

Enable Push

To enable push notifications for an app, click on that app and then from the app dashboard for that app, select Push in the left menu.

Push Dashboard

Click the primary action button to enable push notifications, clicking YES,PROCEED when prompted.

Enable Push Dialog

Your 30 day trial of push notifications will now begin.

Configuration

In order to send push notifications to iOS and/or Android devices you must configure the Apple Push Notification Service (APNS) and/or Google Cloud Messaging (GCM) and upload your push certificate to Kumulos.

Configure Push Dashboard

Either click CONFIGURE NOW or the cog icon next to the platform you would like to configure. This will open the platform configuration dialog where you can enter the required information to send push notifications to iOS devices via APNS and/or Android devices via GCM.

Configure Push Dialog

GCM Configuration

In order to send push notifications to Android devices with Kumulos, you'll need to set up a GCM project and configure push for your app. These steps are shown in the following video guide.

Configuring GCM for Android with Kumulos

After configuring Kumulos and GCM, refer to the Android SDK integration guide for instructions for integrating Kumulos into your app project.

APNS Configuration

In order to send push notifications to iOS devices with Kumulos, you'll need to create certificates in the Apple Developer Member Center. The steps to complete this are shown in the video guide.

Configuring APNS for iOS with Kumulos

After configuring your project, you can refer to the Objective-C integration guide or Swift SDK integration guide as appropriate for details on integrating the notifications into your app.

Sending a notification

Once you have configured at least one of APNS or GCM, you can send push notifications from your agency console. Your client can also send push notifications from their client portal if you have enabled this for them.

Campaign Driven Push

To send a push notification from your agency console, click on the app and then from the app dashboard for that app, select push from the left menu. Click the primary action button to display the Compose Push Notification dialog.

Compose Dialog

Fill in the title and message content for your notification and click "Send". Your clients can send notifications from their client portal in exactly the same way.

Open a URL

To open a URL when the push notification is tapped by the user, toggle the "Open URL" switch and enter the URL you want to open.

Ensure that you have reviewed the apporpriate SDK integration guides to support URL push

Background Push

To send a notification that can be processed in the background, toggle the "Background Push" switch. The title & message become optional, and can be omitted to create a silent push.

On iOS this will set the content-available flag on the notification.

Data

To add an arbitrary meta-data object to the push notification, toggle the "Data" switch and enter a valid JSON object into the editor. Additional data can be consumed by the SDK, please refer to the platform integration guides for further information.

Event Driven Push

If you also use the Kumulos Build feature you can send notifications programmatically via KScripts. These will be listed under the Event-driven tab.

Please refer to the API reference for KScript for more detail on implementation.

Audience segments and targeted push

Segments allow you to target specific groups of your audience. By defining segments, you can easily send your users content that will be relevant and meaningful to them.

Defining segments

To add, edit and delete audience segments for an app, click on the app and then from the app dashboard for that app, expand push from the left menu and select segments.

To define a new audience segment, click the primary action button. This will open the add segment dialog. Give the segment a descriptive name (as this is what your team and your client will see when sending targeted push notifications).

Add Segment

Next, select the filters that will be used to define your audience segment. From the Filter by drop down, you can choose to filer your audience by:

Filter by

Coming soon, you will also be able to filter by the last time/date the app was active (in the foreground) and the number of sessions (time app was active in foreground) within a given date range.

Add multiple filters to define your audience segment. Filters are applied via a boolean and (i.e. an install must match all filters to be in an audience segment). As you add your filters you will be able to see how many installs your audience segment will currently target.

Filters targeting

When done, click Save to save your audience segment. Your segment will now be listed, showing how many filters define it and how many installs it is currently targeting.

Segments

Note that the number of installs targeted by a segments is dynamic and always updated when sending a push notification to a segment. In other words when new users install your app, they are automatically included in the all audience segments whose filters apply to them.

Your clients can define audience segments from their client portal in exactly the same way.

Targeting a segment

To send a targeted push notification campaign to an audience segment, from your agency console, click on the app and then from the app dashboard for that app, select push from the left menu. Click the primary action button to display the Compose Push Notification dialog. From the Targeting drop-down, select the audience segment you wish to target.

Target segment

Fill in the title and message content for your notification and click "Send". Your clients can send targeted notifications to audience segments from their client portal in exactly the same way.

Channels

Channels allow your users to subscribe to content based on their preferences. By defining either portal visible marketing groups or allowing your app to create private or public groups, channels allow you to target content at a receptive audience.

Defining channels via the client portal

To add, edit and delete channels for an app click on the app and then from the dashboard, expand push on the left menu and select channels.

Push Channels List

To create a new channel, click the primary action button. This will open the add channel form. Give the channel a descriptive name and a unique identifier. You can also optionally define a JSON object of meta data which will be returned to your app when requested from the API. This field can be used to provide additional filtering or information when rendering the channel within your app.

Add Push Channel

Note that channels must be subscribed to by an app, they will initially target no installs.

Targeting a channel

To send a push notification to all the installs subscribed to a channel, form your agency console, click on the app and then from the dashboard select push from the left menu. Click the primary action button to display the Compose Push Notification dialog. From the Targeting drop-down, select the channel you wish to target.

Push Channels Composer

Fill in the title and message for the notification and click "Send", your clients can send a notification to a channel from their client portal in exactly the same way.

Notes on the visibility of channels

In order for a channel to be visible in the agency dashboard for targeting notifications via the UI it must be created with the showInPortal flag set to true and will require a friendly name.

Any channel which has a friendly name will be returned to an app requesting a list of channels and is considered publicly available, finer control of what channels are rendered can be achieved with metadata.

Channels with no friendly name are considered private and will not be returned in listing requests unless the requesting install is subscribed to it.

Channel metadata

You can optionally provide a dictionary of meta data to be associated with the channel which will be returned to your app as part of the read request. This metadata can be used for any additional contextual information used by your app, for example any business rules regarding categorization or access control.

Push Dashboard

Once configured, your push notifications dashboard will show recent trends in your subscribers and notifications history along with a summary of recent notifications that have been sent.

Configured Push Dashboard

If you have applied your branding to your console, then the push notification dashboard will reflect your logo and color theme. This is what your clients will see in their client portal.

Branded Push Dashboard

Notification History

You can view sent notifications by expanding Push in the left menu and clicking History.

Push Notification History

The notifications list shows all sent notifications along with summary information about them. It is split into two tabs:

  • Campaign driven push notifications, created and sent from your agency console or by your client from their client portal
  • Event driven push notifications, triggered by events in your app and sent via the Push API or, if you are using the App Build feature, via KScripts.

For each notification that has been sent, you will be able to see the number of installations that will receive the notification and the number of users that have clicked on the notification to open the app.

Again, if you have applied your branding to your console, then the notification history will reflect your logo and color theme. This is what your clients will see in their client portal.

Branded Notification History

You can also send notifications by building an integration with the REST interface of the Kumulos Push API, allowing you complete flexibility when defining business rules that generate notifications.

Any notifications created in this way will still be accessible via the history area in your App's Push notifications dashboard under the Event-driven tab.

Push API

Install IDs

When sending notifications to specific users the Kumulos Push API uses installIds, these are unique identifiers within your app used by all the Kumulos services to cluster requests by the originating device. They are not used to authenticate your app, or a specific user of the app.

When it is initialized for the first time the Kumulos SDK will automatically generate a unique identifier for the device your App is installed on and will use this identifier for every subsequent interaction with our services.

If you want are using your own backend solution you will need to manage your own lookup to pair an installId with whatever identifier your app models devices or users with, an example of this interaction is shown in the diagram below.

Managing install IDs

Authentication

The Kumulos Push API authenticates other back-end services via HTTP Basic Auth using your app's API Key as the username and your Server Key as the password, both of these are available from the App Dashboard in your Agency Console.

Sending Notifications

POST https://push.kumulos.com/notifications

Payload

The request payload must be provided as a JSON object, with the following fields and validation rules met, an example of a simple cURL request is shown below.

{
  broadcast: Boolean, when true the message will be sent to all registered devices
  installIds: Array of installIds to send the notification to
  segmentId: Integer id of the segment to target
  segmentUuid: Unique identifier of the segment to target
  channelIds: Array of integer ids of the channel(s) to target
  channelUuids: Array of unique identifier(s) of the channel(s) to target
  excludeInstallIds:  Install Ids to be excluded from the results of a channel or segment target
  title: String, required
  message: String, required
  data: Optional object of additional key / values to be passed in the notification payload for your app to consume
  isBackground: Boolean, when true the message will be sent for processing in the background (content-available flag in iOS)
  url: String, set a url for the message to open in the device browser
}

At least one of broadcast, installIds, segmentId / Uuid or channel Id / Uuid must be provided to send a notification.

Sample cURL

curl -X POST
    -H "Content-Type: application/json"
    -H "Accept: application/json"
    -u API_KEY:SERVER_KEY
    -d '{
        "broadcast": true,
        "title": "Hello World",
        "message": "from Kumulos Push"
}' "https://push.kumulos.com/notifications"

Responses

401 Unauthorized

Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.

422 Unprocessable Entity

Your request was either unparsable / invalid JSON, was missing required fields, or had provided invalid values for a given key.

The response body will return a JSON object describing what keys were not present or had invalid values.

201 Created

Your request was accepted and processed.

The response body will contain a JSON object describing the notification object that was created as a result.

{
  "appId":1,
  "source":1,
  "status":1,
  "filters": { "broadcast":true },
  "title":"Hello World",
  "message":"from Kumulos Push",
  "data":null,
  "updatedAt":"2017-01-01T00:00:00+0000",
  "createdAt":"2017-01-01T00:00:00+0000",
  "id":1
}

Note that although your request has been successful there may be a slight delay in receiving your notification. This endpoint adds the notifications to our database and queues them for sending, there may also be transmission delays between the platform provider, for example the APNS service, and the target device.

Checking opens

GET https://push.kumulos.com/notifications/{id}/install-opens

Sample cURL

curl -X GET
 -H "Content-Type: application/json"
 -H "Accept: application/json"
 -u API_KEY:SERVER_KEY
 "https://push.kumulos.com/notifications/1/install-opens"

Responses

401 Unauthorized

Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.

200 OK

Your request was accepted and processed.

The response body will contain an array of JSON objects showing the install IDs that opened the notification along with the time that the open was recorded.

[
  {"installId":"abcdefgh","openedAt":"2017-01-01 00:00:00"},
  {"installId":"ijklmnop","openedAt":"2017-01-01 00:00:00"}
]

Creating a channel

POST https://push.kumulos.com/channels

Sample cURL

curl -X POST
    -H "Content-Type: application/json"
    -H "Accept: application/json"
    -u API_KEY:SERVER_KEY
    -d '{
      "uuid": "channel-uuid",
      "name": "friendly name"
      "showInPortal": true
      "meta": {
          "additional": "data"
      }
}' "https://push.kumulos.com/channels"

Responses

401 Unauthorized

Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.

422 Unprocessable Entity

Your request was either unparsable / invalid JSON, was missing required fields, or had provided invalid values for a given key.

The response body will return a JSON object describing what keys were not present or had invalid values.

201 Created

Your request was accepted and processed.

The response body will contain a JSON object describing the channel that was created as a result.

    {
      "appId":1,
      "uuid":"channel-uuid",
      "name":"Channel Name",
      "showInPortal":true,
      "meta": {
        "additional":"data"
      },
      "updatedAt":"2017-02-16 14:43:03",
      "createdAt":"2017-02-16 14:43:03",
      "id":1
    }

Updating a channel

PUT /channels/{id}

Sample cURL

curl -X PUT
    -H "Content-Type: application/json"
    -H "Accept: application/json"
    -u API_KEY:SERVER_KEY
    -d '{
      "uuid": "channel-uuid",
      "name": "friendly name"
      "showInPortal": true
      "meta": {
          "additional": "data"
      }
}' "https://push.kumulos.com/channels/{id}"

Responses

401 Unauthorized

Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.

422 Unprocessable Entity

Your request was either unparsable / invalid JSON, was missing required fields, or had provided invalid values for a given key.

The response body will return a JSON object describing what keys were not present or had invalid values.

200 Success

Your request was accepted and processed.

The response body will contain a JSON object describing the channel in its updated state.

    {
      "appId":1,
      "uuid":"channel-uuid",
      "name":"Channel Name",
      "showInPortal":true,
      "meta": {
        "additional":"data"
      },
      "updatedAt":"2017-02-16 14:43:03",
      "createdAt":"2017-02-16 14:43:03",
      "id":1
    }

Deleting a channel

DELETE /channels/{id}

curl -X DELETE
    -H "Content-Type: application/json"
    -H "Accept: application/json"
    -u API_KEY:SERVER_KEY
   "https://push.kumulos.com/channels/{id}"

Responses

401 Unauthorized

Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.

204 No Content

Your request was accepted and processed.

Subscribing installs to a channel

POST /channels/{id}/subscriptions

Sample cURL

curl -X POST
    -H "Content-Type: application/json"
    -H "Accept: application/json"
    -u API_KEY:SERVER_KEY
    -d '{
      "installIds": ["uuid-1", "uuid-2"]
}' "https://push.kumulos.com/channels/{id}/subscriptions"

Responses

401 Unauthorized

Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.

422 Unprocessable Entity

Your request was either unparsable / invalid JSON, was missing required fields, or had provided invalid values for a given key.

The response body will return a JSON object describing what keys were not present or had invalid values.

204 No Content

Your request was accepted and processed.

Unsubscribing installs from a channel

DELETE /channels/{id}/subscriptions

Sample cURL

curl -X DELETE
    -H "Content-Type: application/json"
    -H "Accept: application/json"
    -u API_KEY:SERVER_KEY
    -d '{
      "installIds": ["uuid-1", "uuid-2"]
}' "https://push.kumulos.com/channels/{id}/subscriptions"

Responses

401 Unauthorized

Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.

422 Unprocessable Entity

Your request was either unparsable / invalid JSON, was missing required fields, or had provided invalid values for a given key.

The response body will return a JSON object describing what keys were not present or had invalid values.

204 No Content

Your request was accepted and processed.

Calling from KScript

If you have multiple apps on Kumulos and you want an event in one app to trigger a push notification to an install of another app, you can do this using the HTTP client in a Kscript method.

var username = 'API Key of your other Kumulos app';
var password = 'Server Key of your other Kumulos app';
var auth = base64_encode( username + ':' + password );

var client = K.http.createClient('https://push.kumulos.com');
var headers =
{
  'Authorization': 'Basic ' + auth,
  'Content-Type': 'application/json',
  'Accept': 'application/json'  
};


var params =
{     
  'broadcast': true,
  'title' : 'Hello',
  'message': 'World'
};

var response = client.post('notifications', K.JSON.stringify(params), headers);

if (response.isError()) {
    K.log(res.getBody());
}

If you have companion apps with different push notification certificates and API methods but you want two apps to share the same a backend database tables (for example: to access the Install IDs of the other app), please contact [email protected] who can arrange this.