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 installations of your app on iOS and Android devices, via the native Apple Push Notification Service (APNS) and Google Cloud Messaging (GCM/FCM).

You can use audience segments to target specific users of your app based on filters such as country and city. You can also use channels to categorize the content you send and let users subscribe to content relevant to them.

You can then send notifications as part of a marketing campaign from your agency console and/or let your clients send push notifications from their client portal. You can also Schedule notifications in advance to be sent in the future.

If you want to send notifications when specific events occur in your app, you can do this in one of two ways. If you use the Build feature of Kumulos to host the backend of your app, you can send push notifications via Kscripts (for example: when a user has a new chat message or a post gets a new like). Alternatively, you can send push notifications from an other backend system using the Push API.

Push is currently supported in the Obj-C and Swift SDKs for iOS, the Android SDK and the Cordova SDK.

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/FCM) 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/FCM.

Configure Push Dialog

GCM/FCM 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/FCM, 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.

Segments

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.

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 agency console

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 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 install, they will initially target no installs.

Notes on the visibility of channels

Channels created in the agency console are considered publicly available. They will be visible in the agency console / client portal and returned to any app requesting a list of channels from the SDK.

In order for a channel created via an SDK or the Push API 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 is considered publicly available and so will be returned to an app requesting a list of channels, 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 to apps requesting a list of channels 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, such as any business rules regarding categorization or access control. For example: if you want to add a channel for a special offer or promotion ahead of time, you could add a start date in the JSON object that your app could use to determine when to present the channel to users of the app.

Sending notifications

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 select Push from the left menu. Click the primary action button to display the Compose Push Notification wizard that will walk you through four simple steps to sending a push notification.

Compose Wizard

Target

First, choose who you want to send the notification to. Either send to all installs subscribed to receive push notifications or target a specific segment or channel.

Choose target

When you select a segment or channel, the wizard will tell you approximately how many installs will be targeted. Click Next when done.

Content

Next, define the content of the notification. If you want the notification to appear in the foreground, add a title and a message. Use the emoji pickers to add emojis to your title and message as required. However, please note that Kumulos supports Emoji v4.0 / Unicode version 9.0 which is fully supported in iOS 10.3 and Android v7. Older versions of iOS and Android may not support all emojis available. See Emojipedia for more details of what emojis are supported in which versions.

Choose target

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.

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 appropriate SDK integration guides to support URL push

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.

Add data

iOS Badges

To set the badge on your app on iOS, toggle the "Set Badge" switch. By clicking on "Badge Type" you can choose whether to set the badge to the absolute number you enter in "Count" or to Increment the badge by the positive or negative number you enter in "Count".

Set badge

Schedule

Lastly, decide when you want the notification to be sent. If you want the notification to be sent immediately, just click "Send". The notification will appear under "Recently created notifications" in your Push Dashboard

Send immediately

Alternatively, if you want to schedule a notification in advance to be sent in the future, toggle the "Scheduled" switch. Enter the date and time you want the notification to be sent.

Send immediately

Next, set what this date and time is relative to. Do you want everyone to receive the notification at exactly that same time in either UTC or your own timezone (which Kumulos will detect)? Or, more likely, do you want users to receive the notification at that date and time in their local timezone (according to the device on which the app is installed)?

Select Timezone

Finally, if choosing to schedule the notification according for the local timezone (according to the device on which the app is installed), what should Kumulos do for installs on devices for which this time has already past? Should we "Ignore" these installs or send at the same time, the "Next Day"?

Timezone Strategy

For example: At 4pm on Christmas Eve, Marketing Mandy in New York decides to send a "Happy Christmas" notification to all of her customers at midnight on Christmas Day. However, for Surfer Steve in Sydney, that was already 6 hours ago. What should Kumulos do? In this example, Marketing Mandy should "Ignore" Surfer Steve as a "Happy Christmas" notification on Boxing Day won't work.

Click "Send" once done.

Event Driven Push

If you also use the Kumulos Build feature you can send notifications programmatically via KScripts. Please refer to the API reference for KScript for more detail on implementation.

Alternatively, you can send push notifications from an other backend system using the Push API.

These will be listed under the "Event-driven" tab in the "History".

Push Dashboard

Once configured, your push notifications dashboard will show recent trends in your subscribers and notifications history along with a summary of recently created notifications.

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

Scheduled Notifications

You can view notifications scheduled to be sent in the future by expanding Push in the left menu and clicking "Scheduled".

Scheduled Push Notifications

From here, you can "Edit" the content and data in the notification or "Cancel" the notification. Once a notification has been scheduled, it is not possible to change the target for the notification or the schedule. If you wish to do so, "Cancel" the notification and create a new notification with the required target and/or schedule.

Once a scheduled notification has been sent (for all timezones if "Device Local Time" was selected), it will not be shown under "Scheduled" notifications, but will be shown in "History"

Notification History

You can view all 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

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.

{
  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
  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
  data: Optional object of additional key / values to be passed in the notification payload for your app to consume
  ios: {
      hasBadge: Boolean
      badgeType: String, either "incrementBy" or "setTo"
      badgeCount: Positive or Negative integer. Set to 0 to clear badge.       
  }
  scheduled: Boolean
  schedule: {
      sendAt: DateTime of format "Y-m-d H:i", required if scheduled is true
      strategy: String, either "local" or "utc", required if scheduled is true
      pastTimes: String, either "ignore" or "nextDay", required if scheduled is true,
  }
  collapseId: String, a unique identifier for the device operating system to group and collapse related notifications.
}

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"

Sample PHP

<?php
    $postData = json_encode(array(
        "broadcast" => true,
        "title" => "Test Broadcast",
        "message" => "Test from PHP")
    );

    $curl = curl_init();

    curl_setopt_array( $curl, [
        CURLOPT_URL => "https://push.kumulos.com/notifications",
        CURLOPT_HTTPHEADER => array (
            'content-type: application/json',
            'accept: application/json',
            'content-length: ' . strlen($postData),
        ),
        CURLOPT_USERPWD => 'API_KEY:SERVER_KEY',
        CURLOPT_CUSTOMREQUEST => "POST",
        CURLOPT_POSTFIELDS => $postData,
        CURLOPT_RETURNTRANSFER => true
    ] );

    $response = curl_exec($curl);
    $err = curl_error($curl);

    curl_close($curl);

    if ($err) {
        echo "cURL Error #:" . $err;
    }
    else {
        echo $response;
    }
?>

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
}

Checking open rates

You can then use the ID of the notification created to get which installs have opened the notification. This will allow you to track who has opened what message and when. Very useful if you are measuring the effectiveness of your push campaigns.

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 technical support who can arrange this.