API reference on SwaggerHub

Introduction

The Push API allows you to target your audience in the right way with push notifications for web and mobile platforms. This API enables the use of advanced location based marketing techniques such as geo-targeting, fencing and i-Beacons.

Enable the complete toolset this API has to offer by using the client software development kit (SDK) within your mobile or web application. The toolset allows you to send enriched push messages with video and images or notify users about a specific subject.

Conceptual model

Conceptual model

Definitions

Action

As part of the core functionality of the Push API, actions can be added to the content of your notifications. This allows users to interact with your messages and your app. Actions will be shown in the form of buttons, allowing you to provide extra functionality in a message. Whenever your notifications include one or more actions, the Notificare SDKs will automatically register any interaction and display it for you in the dashboard as responses to your messages. By using actions you can easily capture user responses without having to develop any functionality.

Possible actions include: - registering a user's choice - allowing a user to provide text input - taking a picture - opening a browser - calling a webhook - making a phone call - sending an sms - sending a deep link - executing code in your app

Actionable Rich Push Template

To bootstrap campaigns creation, the Push API allows your messages to use pre-defined action templates that combine rich content types and actions. By default the Push API include templates that use all the types of rich content, but you can also create your own action templates and customize your messaging strategy even more. This is ideal for apps that use recurrent types of messages and want to implement faster content selection and smarter use of actionable notifications.

APNS

APNS stands for Apple Push Notifications Service. It is the force behind all push notifications delivered in iOS devices and Safari browsers. The Push API provides a robust connection between APNS servers, allowing your apps to scale the number of notifications without having to scale your infrastructure. APNS offers an authenticated and encrypted IP-persistent connection between its servers and an iOS device or Safari browser. This allows devices to receive notifications even when your apps are not being used. When connecting a device to the APNS servers it will be provided a unique identifier which is used by Notificare to send notifications to devices.

Beacon (iBeacon)

Smartphone and tablets with Bluetooth Low Energy capabilities and iOS 7 and Android 4.3 can receive signals from BTLE devices also known as beacons or iBeacons. These devices can be used as microregions providing location accuracy between 70 meters (approx. 229 feet) and 20 centimeters (approx. 3.9 inches). These devices are usually powered by coin batteries or USB cables, allowing them to be placed nearly anywhere. Please note that since this technology relies on Bluetooth technology, it is possible that elements like water, metal surfaces or the human body can interfere with the signal broadcast by these devices. With the Push API, beacons can extend interactions inside any region and register a users’ behavior in places where region monitoring cannot.

Device

Devices are the core of your audience. Every unique smartphone, tablet or browser that accesses your applocation will be registered as a device. Devices can be registered without requesting any permission from the user. By default all platforms will provide Notificare's SDKs with a device token that identifies that unique device. For iOS and web apps, users are required to accept notifications. This gives your application the necessary permissions to show remote notifications even when users are not using your applications. In Android this permission is requested beforehand when users first install your app. Please note that users have the power to disable remote notifications at any time in the device’s settings.

Dwelling

Users of your application will be dwelling in a region or beacon from whenever they first enter the area to the moment they leave it. This allows geo-triggers to provide a delay in minutes before they get executed. This is extremely useful if you wish to filter any visits to your regions or beacons that occur under a certain amount of time. When users dwell inside a region for a short amount of time (for example when travelling too fast) you might not want to trigger certain notifications. This allows you to specifically target users that stay inside a region or beacon for a specific amount of time. Any delay provided in a geo-trigger must be specified in minutes. Please note that both iOS and Android will take up to 20 seconds by default to determine if a user entered or exited a region or beacon.

Environment

An app environment will determine which APNS server it should use. Notificare apps are divided into two types of environments: development and production. An app which is created for development will communicate with APNS sandbox servers. This is reserved for apps built directly from Xcode into a device. Only debug builds will retrieve a device token from APNS sandbox servers and those tokens must be registered with a Notificare app created with a development environment. All other types of builds (Ad-Hoc, AppStore or Enterprise) must use a Notificare app which is created in a production environment. In Android and web apps this distinction is not relevant. Those apps are not required to have a clear separation between environments, although it is recommended.

FCM

FCM stands for Firebase Cloud Messaging. It is the service used by the Push API to deliver notifications on Android devices and Chrome and Opera browsers. In 2016, FCM replaced GCM as the mechanism used to send notifications on Android. FCM operates by creating an authenticated and encrypted connection between its servers and users’ devices. It allows apps running on Android and websites in Chrome and Opera to receive notifications even when they are not running. When connecting a device to the FCM servers, it will be provided with a unique identifier which is used by the Push API to send push notifications to devices.

GCM

GCM stands for Google Cloud Messaging. It was the service used by Notificare to deliver notifications in Android devices and Chrome browsers. It was replaced by FCM in 2016. FCM (listed above) operates in much the same way as GCM.

Geo-trigger

Location-based triggers are interactions that can be created whenever a device enters or leaves a certain region or is in the vicinity of a beacon. These triggers can be set to generate a remote notification or simply be used to add/remove users to/from a segment or add/remove devices to/from tags. These interactions allow your app to engage or categorize your audience based on your customer's visits to your stores or venues.

Install

This is a metric collected by Notificare’s SDKs whenever a device installs and opens your app for the first time. This metric will also always be registered whenever a device uninstalls your app, and installs and opens it again. Read the definition of 'Uninstalls' below to understand how that metric is collected.

Major

A Major, or region identifier, is a unique number within your list of regions that serves to identify your region and the beacons created inside that region. All the beacons inside that region must be set to share the right Major number in order for them to be visible in your mobile apps. This allows your app to only display the beacons for the region of the user.

Minor

A Minor, or beacon identifier, is a unique number within your list of beacons for a specific regions that identifies a beacon inside an application. This number must match a Minor already set in a beacon device or be configured as the Minor value of a beacon. In order to allow your app to recognize and monitor a specific beacon, configuring beacons with a Minor is a mandatory step.

Pass Type ID

A Pass Type ID is an identifier used by Apple Wallet (formely known as Passbook). Every pass needs to have a Pass Type ID and needs to be protected by a digital signature created using a corresponding Pass Type ID certificate. In order for Notificare to create Wallet compatible passes for you, you are required to upload a pass certificate which is generated in Apple’s Developer Portal.

Proximity UUID

In the Push API, the Proximity UUID is an essential configuration of Location Service if you want to do proximity marketing using beacons. This value can be generated by Notificare and later configured in your beacon devices or simply made to match your existing beacons UUID. Each application can only use one Proximity UUID. You are only allowed to configure regions to use beacons when you provide a Notificare app with a Proximity UUID.

Region

As part of Notificare's location-based services, your app can monitor visits to any point on the globe. A region should have a center position based on the latitude and longitude intersection point and a radius varying between 50 meters (approx. 164 feet) and 50 kilometers (approx. 310 miles). Regions with either a very large or very small radius will lose precision when used to track visitors in a certain area. For the best results, choose a radius between 100 meters (approx. 328 feet) and 2 kilometers (approx. 1.2 miles). Also take into account that GPS data will be inaccurate when users are inside buildings or when there is no wifi within reach. In these cases we recommend the use of BTLE beacons as the source of your location-based tracking or campaigns.

Rich Content

A notification can hold different types of content. In the Push API these types can vary from simple alerts, HTML, web pages, images, video, maps to coupons. Due to limitations in the platform, this content will only be available whenever a user clicks on a notification in the device’s notification center or on the lock screen. Or, if your app uses Notificare's inbox functionality, the content will be available when a user opens a message from the inbox. You are also free to create your own content types. However, you will need to handle these by yourself since Notificare's SDKs will ignore any unknown content types.

Segment

To group users by a certain category, user profiles can be added or removed from segments through the API. Segments can be used as a recipient of a message, allowing your app to send one single message to a group of users. When using segments as the recipient of a campaign, that campaign will be sent to all the devices of a user, if applicable. Users can also be added to a certain segment in bulk operations using the data importer. This is extremely useful for apps that already do this segmentation through third-party software (like CRMs or ERMs) and need to import these groups to the Push API.

Segmentation Rules

This mechanism allows your application to automate the way it categorizes users or devices based on your users’ behavior. These rules allow you to add or remove users from segments or devices from tags. They can be set whenever a user opens a notification, clicks on an action, enters or leaves a region or beacon. Or simply whenever any automation event is executed. This is the easier way of categorizing your users without having to manage it yourself.

Session

Every time a user opens your application, a session is collected by Notificare's SDK. It will give you an overview of how many people use your app per hour, day, or month. With this metric you can measure the effects that push notifications, and on- and offline campaigns, have on your mobile and website audience.

Tags

Tags allow you to group devices based on app-specific properties (e.g. type of device, selected language, level reached in a game, user preferences etc.). Tags can be used as the recipient of your messages, allowing you to reach only specific devices, regardless of the user profiles they are associated with. This is a mechanism only available through Notificare’s SDKs.

Uninstalls

This is a metric collected by Notificare’s platform whenever APNS, FCM or WebSockets provide feedback in response to an attempt to deliver a notification to a device token that is no longer valid. This can happen for example when a user has uninstalled your app or disconnected their browser from Notificare's WebSockets server. This metric will be stored as an event and subtracted from the number of installs from the event that collects installation information.

Visit

This is a metric collected by Notificare’s SDK whenever a user enters and then exits a certain region or beacon. Notificare's SDK automatically registers these visitors as soon as a region or beacon is created and loaded in the app. Please note that whenever a new region or beacon is created, the app must be launched or the user must move significantly (approx. 500 meters or 0.3 miles). This way new regions or beacons are recognized and loaded in the app.

Web Push

In modern browsers, web push is the capability to send messages to subscribers of a website or web app. You can do this even when the application or website is not in focus or opened at all. It can be used to send and present content to a user or trigger the browser to update its content.

Features

  • Configure Notficare with your business rules and you will be able to target your audience better. Configure regions, beacons, notifications, templates, assets, triggers, tags and many more to add a full service interaction.

  • Be able to better serve a logged-off user by already storing his preferences. Now, when the user logs in in the future, you can add the identifier of that user to his stored data. From a back-end perspective, you are now able to notify this user about events that are relevant to him (e.g. package deliverd, new e-mail arrived, etc.). You can also add value by knowing a user's interests/whereabouts and offering appropriate services.

Prerequirements

You need to have a valid certificate to sign the notifications:

  • For iOS notifications, you need a certificate from Apple's Developer Portal.
  • For Android notifications, you need a firebase project's server key.
  • For web notifications for Safari, you need a certificate from Apple's Developer portal.
  • For web notifications for Chrome, you need a certificate from firebase project.
  • For web notifications for Firefox, you need to have valid VAPID credentials.

Getting started

Authentication

To authenticate you'll need to request an access token. Use your API Store app's credentials (Consumer Key and Consumer Secret) to make an authentication request. The authorization service returns a JSON message that contains the access_token field.

Use one of the following 3 options:

cURL

Execute below cURL command to receive an access token. Replace APP_CONSUMER_KEY and APP_CONSUMER_SECRET with your app's credentials.

curl -X POST \
 'https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials' \
 -H 'content-type: application/x-www-form-urlencoded' \
 -d 'client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET'

If you are using cURL for Windows, please use the command below instead.

curl -X POST "https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials" -H "content-type: application/x-www-form-urlencoded" -d "client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET"

The authentication service returns a JSON message that contains the access token field.

{
    "refresh_token_expires_in": "0",
    "api_product_list": "[xxxxxxx]",
    "api_product_list_json": [
        " xxxxxxx"
    ],
    "organization_name": "kpn",
    "developer_email": "demo123@kpn.com",
    "token_type": "Bearer",
    "issued_at": "1521039195424",
    "client_id": "APP_CONSUMER_KEY",
    "access_token": "haf2SDl07E9N7RluNQ4kJ1TkGgso",
    "application_name": "6e38edxxxxxxxxxxxxxxxx4065d79c",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

SwaggerHub

  1. Click on the Authorize button on the top right.
  2. In the form, fill in client_id and client_secret, using your app's credentials.
  3. Click Authorize.

Postman

When using Postman, you will have to import the Swagger file into a Postman collection as follows:

  1. Open the API reference on SwaggerHub.
  2. On the top right, click Export, click Download API and click 'YAML Unresolved'.
  3. In Postman from the menu click File and click Import... Choose the YAML file you downloaded in the previous step. A new collection will be added.
  4. Select Get Access Token from the collection.
  5. Make sure the right environment is selected, corresponding to the API.
  6. Edit the environment variables client_id and client_secret, using your app's credentials.
  7. Check the response code and message.
  8. Press the Send button to get an access token.

Note: Request variables are no longer linked to an environment, but to the collection.

Configuring the SDK

In order to send notifications, Notificare's SDKs need to be connected to your application's identity. For this, you need to add your username (applicationKey) and password (applicationSecret) to each SDK (one per platform).

How to...

Create your application

Log in and create a new app with Push API on your account home page. If you would like to add Push API to an existing app, just update the app products with Push - Notificare.

Send push notifications

Currently the Push API works on 3 platforms:

  • Apple platform (APNS)
  • Android platform (GCM/FCM)
  • Web platform (Web push)

Follow the steps below to configure 'push notifications' for each platform.

Configure APNS

An SSL certificate will allow the platform to send notifications on your behalf. Send us the APNS SSL certificate for your application via e-mail. Tell us the name of your application. If your certificate has a password, please let us know what it is as well.

Configure GCM/FCM

In 2016, Firebase Cloud Messaging (FCM) replaced the GCM (Google's Cloud Messaging) and became Android's official push provider. To be able to send notifications you currently need to have a project in Firebase.

In Firebase's project area you can find your server key under project settingsCloud Messaging.

Send us your server key for your application via e-mail. Tell us the name of your application.

Note: If you already have an existing application using the older Google Cloud Messaging, you will need to import the existing Google project into the Firebase Console.

Configure Web Push

Before you can start pushing notifications to your website, you will have to configure notifications for the right browser for desktop: Chrome, Opera, Firefox and Safari. This is all done via the Firebase Developer Console and Apple's Developer Console. Depending on for which browsers you want to enable push notifications, different data needs to be provided.

Send us an e-mail with the required data listed below and the name of the website you want to push notifications to.

Icon: An icon will be displayed in your push notifications. Ideally it's the icon of your website/application. Make sure is a square .png image with at least 256px and without transparency (no alpha channels).

Domain whitelist: This is the list of domains where your website runs. Include the protocol. At least one must be provided. For example: https://example.com.

URL format string: This will be the landing page for your notifications. It must provide a placeholder with the format %@ where we will place the notification ID. For example: https://NbIUjiuW8v9.demo.example.com/#%@.

Server key: To be able to send notifications to Chrome and Opera browsers, you need a server key. On FCM this key is located in your project settingsCloud Messagingserver key.

VAPID public key and VAPID private key: To be able to send notifications to Firefox users, you need VAPID public and private keys. if you do not have them, we can help you to generate a pair.

Web Push ID and Web Push Certificate: To be able to send notifications to Safari users, you need a Web Push ID and Certificate. With a password.

Get Push ID and Certificate for Safari

In order to support Safari website push on desktop, you will need a developer account with Apple. Once there, generate a Web Push ID and Web Push Certificate.

Create a Web Push ID:

  1. Sign in at Apple Developer.
  2. Click on Certificates, Identifiers & Profiles.
  3. Click on Web IDs under Identifiers section.
  4. Click the plus button found in the top right corner.
  5. Register a new Website Push ID. Start by providing a name for your app. Then provide the identifier for your app. This should take the form of a reverse DNS name (eg.: com.mydomain.myapp). This will become your website's identifier and should be prefixed with the string web. It also must be unique and once created cannot be changed.
  6. Click on Continue to proceed with the creation.
  7. Confirm the data introduced and continue by clicking on the Register button.

Generate a Web Push Certificate:

This certificate will allow us to send messages to your website. If you do not have one, here are the steps to follow to generate one

  1. Open the Keychain Access app from your applications, in your MacOS powered computer and request a signing certificate from an certificate authority by selection the option under Certificate Assistant
  2. Provide an email and check on Saved to disk on request options. Proceed by clicking on Continue button.
  3. Select your destination.

Now enter the Certificate into your Apple account:

  1. Sign in at Apple Developer.
  2. Click on Certificates, Identifiers & Profiles and on All.
  3. Click the plus button found in the top right corner.
  4. In that page, locate Web Push Certificate.
  5. Click on Continue.
  6. In the Web Push ID dropdown select the Web Push ID you want to use and proceed with Continue.
  7. Provide a Certificate Signing Request (CSR) and proceed with Continue.
  8. Provide the CSR by uploading the file. Proceed further by clicking Continue.
  9. The Web Push Certificate is generated. Download the file to your computer and install it in your Keychain Access app.
  10. Using the Keychain Access app, locate the certificate and export it in .p12 format by right-clicking on the file and selecting Export.
  11. In the saving process, it will ask for a password. Click OK.

Note: This file will give any push provider access to send notifications to your app. It is important to secure it with a strong password.

Get your audience

The user base of your application is the audience who will receive your notification.

The user base grows every time a new users registers in your application and saves his interests.

Get your audience workflow

Send a message to a target user

From your service, create the push message defining the target (User Segment). The Push API will sign the message using your certificate and send the message to the subscribers.

Send message to user workflow

Subscribe to topic

A subscription to a topic is triggered by the end user when registering his topics of interest in the system. The end user must choose from existing topics (User Segments).

Subscribe to topic workflow

Return codes

Code   Meaning
200   Success
201   Created
202   Accepted
400   Bad request
401   Unauthorized
404   Not Found
405   Method not Allowed
412   Precondition failed
429   Too many requests
500   Internal server error
502   Bad gateway
503   Service unavailable