push.delivery is a service of ethinking GmbH

Getting Started

API documentations available:

Admin API

Overview

This API documentation covers management of tags and tag groups from external services.

URL scheme: https://<customer-id>.push.delivery/push-admin-api/<endpoint>

To use the service you need HTTP basic auth. Data is sent as JSON via POST. The client ID used in the endpoints is listed in the admin UI.

REST Endpoints

tag/add

Create a tag or make sure a tag or tag group with a specific source id exists. More than one tag or tag group can be specified in a single request. The expiration timestamps are optional. This is a POST request.

Example URL
https://<customer-id>.push.delivery/push-admin-api/tag/add/<client-id>
Example POST Request (content type: application/json) : create single tag in root
{
    "tags": [
        {
            "name" : "My Tag No. 1",
            "sourceId" : "my_tag_1",
            "expiration" : "expiration date in milliseconds (optional)"
        }
    ]
}
Example POST Request (content type: application/json) : create single tag in specific group
{
    "tags": [
        {
            "name" : "My Tag No. 1",
            "sourceId" : "my_tag_1",
            "expiration" : "expiration date in milliseconds (optional)",
            "groupSourceId" : "my_group_1"
        }
    ]
}
Example POST Request (content type: application/json) : create group in root
{
    "groups": [
        {
            "name" : "My Group Of Tags No. 1",
            "sourceId" : "my_group_1"
        }
    ]
}
Example POST Request (content type: application/json) : create group in other group
{
    "groups": [
        {
            "name" : "My Group Of Tags No. 2",
            "sourceId" : "my_group_2",
            "parentGroupSourceId" : "my_group_1"
        }
    ]
}
Example Response (content type: application/json) : after creating a tag
{
    "tags": [
        {
            "name" : "My Tag No. 1",
            "sourceId" : "my_tag_1",
            "expiration" : "expiration date in milliseconds (optional)",
            "id" : 123
        }
    ]
}

tag/update

Update a tag or a tag group. Can also be used to move a tag or group to a different parent group. Only one tag or tag group can be specified in a single request. This is a POST request.

Example URL
https://<customer-id>.push.delivery/push-admin-api/tag/update/<client-id>

The update tag endpoint works the same way as the tag/add endpoint.

Example POST Request (content type: application/json) : update single tag to different specific group
{
    "tags": [
            {
                "sourceId" : "my_tag_1",
                "groupSourceId" : "my_group_2",
                "expiration" : "expiration date in milliseconds (optional)"
            }
      ]
}

tag/delete

Delete a tag or a tag group. Groups have to be empty before deleting. Only one tag or tag group can be specified in a single request. This is a POST request.

Example URL
https://<customer-id>.push.delivery/push-admin-api/tag/delete/<client-id>
Example POST Request (content type: application/json) : delete a tag by its source ID
{
    "tags": [
        {
            "sourceId" : "my_tag_1"
        }
    ]
}
Example POST Request (content type: application/json) : delete a tag group by its source ID
{
    "groups": [
        {
            "sourceId" : "my_group_1"
        }
    ]
}
Example Response (content type: text/plain)
  <empty-string>

tag/get

Get all tags and tag groups as tree. This is a GET request.

Example URL
https://<customer-id>.push.delivery/push-admin-api/tag/get/<client-id>
Example Response (content type: application/json)
{
    "tags": [
        {
            "id" : 123,
            "name" : "My Tag No. 1",
            "sourceId" : "my_tag_1",
            "expiration":"date in milliseconds (optional)"
        }
    ],
    "groups": [
        {
            "id" : 124,
            "name" : "My Group Of Tags No. 1",
            "sourceId" : "my_group_1",
            "tags" : [ ... ],
            "groups" : [ ... ]
        }
    ]
}

App API

Overview

This API documentation covers registration and deregistration of devices.

URL scheme: https://<customer-id>.push.delivery/push-api/<endpoint>

To use the service you need HTTP basic auth. Data is sent as JSON via POST.

REST Endpoints

reg

Subscribe device to a tag or multiple tags. Tags can be identified by ID or sourceID (externally assigned ID). Tags with sourceID’s are typically created from external services by accessing the push admin REST API. Either tagIds or tagSourceIds needs to be provided. Other tags the device might be already subscribed to are not affected by this call.

Table 1. Request Parameter Description
Name Description Example

tagId

The ID(s) of the tag

4

tagSourceId

The source ID(s) of the tag

sport_football_team_fcb_goal

appId

The ID of the app

30

appVersion

Optional: the Version of the app

V1.0.11.3b

platformId

The ID of the platform

3

deviceId

The ID generated by the device

b77b7f01bab316ad38d3…​

Example URL
https://<customer-id>.push.delivery/push-api/reg
Example POST Request with tag ID (content type: application/json)
{
    "tagId": <id-number>,
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example POST Request with tag IDs (content type: application/json)
{
    "tagId": [<id-number>,<id-number>],
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example POST Request with tag source ID (content type: application/json)
{
    "tagSourceId": "<id-string>",
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example POST Request with tag source IDs (content type: application/json)
{
    "tagSourceId": ["<id-string>","<id-string>"],
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example Response (content type: text/plain)
  OK

The response will always be "OK", even if invalid parameters are provided.

ureg

Unsubscribe device from tag(s). If no tag id or tag sourceId is provided, all existing tag subscriptions for this device will be removed.

Table 2. Request Parameter Description
Name Description Example

tagId

the ID(s) of the tag(s), if omitted and no tagSourceId(s) provided, all tags will be unregistered

4

tagSourceId

The source ID(s) of the tag(s)

sport_football_team_fcb_goal

appId

The ID of the app

30

platformId

The ID of the platform

3

deviceId

The ID generated by the device

b77b7f01bab316ad38d3…​

Example URL
https://<customer-id>.push.delivery/push-api/ureg
Example POST Request with tag ID (content type: application/json)
{
    "tagId": <id-number>,
    "appId": <id-number>,
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example POST Request with tag IDs (content type: application/json)
{
    "tagId": [<id-number>,<id-number>],
    "appId": <id-number>,
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example POST Request with tag source ID (content type: application/json)
{
    "tagSourceId": "<id-string>",
    "appId": <id-number>,
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example POST Request with tag source IDs (content type: application/json)
{
    "tagSourceId": ["<id-string>","<id-string>"],
    "appId": <id-number>,
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example POST Request for complete unregistration (content type: application/json)
{
    "appId": <id-number>,
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example Response (content type: text/plain)
  OK

The response will always be "OK", even if invalid parameters are provided.

list

List subscribed device tags. Source Id of tags is optional.

Table 3. Request Parameter Description
Name Description Example

appId

The ID of the app

4

platformId

The ID of the platform

30

deviceId

The ID generated by the device

b77b7f01bab316ad38d3…​

Table 4. Response Parameter Description
Name Description Example

id

The ID of the tag

6

name

The name of the tag

Sport

Example URL
https://<customer-id>.push.delivery/push-api/list
Example POST Request (content type: application/json)
{
    "appId": <id-number>,
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example Response (content type: application/json)
[
    {
      "id": <tag-id-number>,
      "sourceId" "<tag-id-string>",
      "name": "<tag-name>"
    },
    {
      "id": <tag-id-number>,
      "name": "<tag-name>"
    }
]

tags

List available app tags. Tags are grouped. Tags and groups can both optionally have source IDs for external identification. Groups can have sub groups. Tags that are not in any group will appear in the response in the "default" group.

Table 5. Request Parameter Description
Name Description Example

appId

The ID of the app

30

platformId

The ID of the platform

4

Table 6. Response Parameter Description
Name Description Example

name

The name of the tag group

Sport

tags.id

The ID of the tag

6

tags.name

The name of the tag

Football goals

Example URL
https://<customer-id>.push.delivery/push-api/tags
Example POST Request (content type: application/json)
{
    "appId": <id-number>,
    "platformId": <id-number>
}
Example Response without source ID’s (content type: application/json)
[
    {
        "name" : "default",
        "tags" : [
            {
                "id": <tag-id-number>,
                "name": "<tag-name>"
            }
        ]
    },
    {
        "id" : <group-id-number>,
        "name" : "<group-name>",
        "tags" : [
           ...
        ],
        "groups" : [
            {
                "id" : <sub-group-id-number>,
                "name" : "<sub-group-name>",
                "tags" : [
                    ...
                ],
                "groups" : [
                    ...
                ]
            }
        ]
    }
]
Example Response with source ID’s (content type: application/json)
[
    {
        "id" : 0,
        "name" : "default",
        "tags" : [
            {
                "id": <tag-id-number>,
                "sourceId": "<tag-source-id-string>",
                "name": "<tag-name>"
            }
        ]
    },
    {
        "id" : <group-id-number>,
        "sourceId": "<group-source-id-string>",
        "name" : "<group-name>",
        "tags" : [
           ...
        ],
        "groups" : [
            {
                "id" : <sub-group-id-number>,
                "sourceId": "<sub-group-source-id-string>",
                "name" : "<sub-group-name>",
                "tags" : [
                    ...
                ],
                "groups" : [
                    ...
                ]
            }
        ]
    }
]

set

Set the subscriptions of a device to a tag or multiple tags. Tags can be identified by ID or sourceID (externally assigned ID). Tags with sourceID’s are typically created from external services by accessing the push admin REST API. Either tagIds or tagSourceIds needs to be provided. Each call will replace whatever subscriptions for this device existed before.

Note: if no tags are provided, the request will be ignored. To unregister the device please use the '/ureg' endpoint.

Table 7. Request Parameter Description
Name Description Example

tagId

The ID(s) of the tag

4

tagSourceId

The source ID(s) of the tag

sport_football_team_fcb_goal

appId

The ID of the app

30

appVersion

Optional: the Version of the app

V1.0.11.3b

platformId

The ID of the platform

3

deviceId

The ID generated by the device

b77b7f01bab316ad38d3…​

Example URL
https://<customer-id>.push.delivery/push-api/set
Example POST Request with tag ID (content type: application/json)
{
    "tagId": <id-number>,
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example POST Request with tag IDs (content type: application/json)
{
    "tagId": [<id-number>,<id-number>],
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example POST Request with tag source ID (content type: application/json)
{
    "tagSourceId": "<id-string>",
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example POST Request with tag source IDs (content type: application/json)
{
    "tagSourceId": ["<id-string>","<id-string>"],
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}
Example Response (content type: text/plain)
  OK

The response will always be "OK", even if invalid parameters are provided.

Push API

Overview

This API documentation covers submitting push jobs from external services.

URL scheme: https://<customer-id>.push.delivery/push-api/<endpoint>

To use the service you need HTTP basic auth. Data is sent as JSON via POST.

REST Endpoints

push

Submit a push job. Tags to be addressed can be specified via their id’s or their source id’s. For this endpoint a specific push user is available and can be looked up in the administration UI. Alternatively any user login can also be used to submit a push. If no appId’s are specified, it means all apps that are connected to the specified tags will be addressed, this is the default behavior.

The payload is typically an encoded JSON object, which then is transformed using a template for each platform. See Push Templates.

Table 8. Request Parameter Description
Name Description Example

tagIds

the IDs of the tags

101, 102

tagSourceIds

the source IDs of the tags

sport_football_team_fcb_goal, sport_football_team_fca_goal

appIds

the IDs of the apps (optional)

110, 111

payload

the payload of the push as string, typically a JSON object (escaped)

{ \'message \' : \'test\' }

Note: if the tag is expired notification will be not delivered.

Example URL
https://<customer-id>.push.delivery/push-api/push
Example POST Request with tag ID (content type: application/json)
{
    "tagIds": [ <id-number>, <id-number> ... ],
    "payload": "{ \"field1\" : \"value\", \"field2\" : \"value\" ... }"
}
Example POST Request with tag source ID (content type: application/json)
{
    "tagSourceIds": ["sport_football_team_fcb_goal", "sport_football_team_fca_goal"],
    "payload": "{ \"field1\" : \"value\", \"field2\" : \"value\" ... }"
}
Example POST Request with specific app ID (content type: application/json)
{
    "tagIds": [ <id-number>, <id-number> ... ],
    "payload": "{ \"field1\" : \"value\", \"field2\" : \"value\" ... }",
    "appIds" : [ <id-number> ]
}
Example Response (content type: text/plain)
  adfb51b1-b037-cf17-b1f1-fafa60de1203

The response will be a push job id that can be used for status queries.

In case of an invalid request, the response will be a HTTP 422 code. Invalid requests are missing for example payload, or tag id’s or specify non-existant tag source id’s.

status

Query the status of a push job. The status response will have an entry for each app addressed in the push job. It also will carry the transformed (by the push template) payload for each app.

Example URL
https://<customer-id>.push.delivery/push-api/status/<status-id>
Example GET Request
https://<customer-id>.push.delivery/push-api/status/adfb51b1-b037-cf17-b1f1-fafa60de1203
Example Response (content type: application/json)
[
   {
        key: {
            id: "<job-id-string>",
            platformId: <platform-id>,
            appId: <app-id>
        },
        created: <timestamp-long>,
        finished: <timestamp-long>,
        state: "<state-string>",
        totalCount: <count-long>,
        successCount: <count-long>,
        errorCount: <count-long>,
        messages: [ ],
        transformedPayload: "{ \"field1\" : \"value\"}"
    }
]

Push Templates

Overview

To support different push platform engines an template engine system is needed which provide the transformation of a common push message into the platform target format. The data exchange format uses the json format so the template engine must support json to json transformation like XSLT for XML.

Push template engine jolt

Example

Input JSON
{
    "title": "title",
    "message": "message",
    "articleId": "123",
    "url": "http://test.de/123",
    "pushID": "1234567"
}
Transform template JSON
[
    {
        "operation": "shift",
        "spec": {
            "title": "customFields.title",
            "message": "customFields.subtitle",
            "url": "customFields.url",
            "pushID": "customFields.pushId",
            "articleId": "collapseKey"
        }
    },
    {
        "operation": "default",
        "spec": {
            "customFields": {
                "feedId": "blick.directpush.testfeed.1",
                "regId": "123"
            },
            "timeToLive": "1800",
            "delayWhileIdle": "false"
        }
    }
]
  1. Result JSON

{
  "collapseKey" : "123",
  "customFields" : {
    "feedId" : "http://test.de/feed/1",
    "pushId" : "1234567",
    "regId" : "123",
    "subtitle" : "message",
    "title" : "title",
    "url" : "http://test.de/123"
  },
  "delayWhileIdle" : "false",
  "timeToLive" : "1800"
}

Android json push format

  1. Push format JSON

{
    "collapseKey": "123",      (1)
    "delayWhileIdle": "false", (2)
    "timeToLive": "1800",      (3)
    "customFields": {          (4)
        "field1": "value1",
        "field2": "value2",
        "fieldX": "valueX"
    }
}
1 GCM setting collapseKey
2 GCM setting delayWhileIdle
3 GCM setting timeToLive
4 entry point for custom fields

Note: The Server Key obtained from GCM should be configured in App→ API Key

IOS push input format

For the alert, two different fields can be used: alert and alertObj. Here alert will in fact set only the alert body text, where alertObj can have title and body text specified. Only one of the two should be used. The silent flag is optional.

  1. Push format JSON

{
    "alert": "title",        (1)
    "alertObj": {            (2)
        "title": "alert title",
        "body": "alert body"
    },
    "badge": "0",            (3)
    "sound": "default",      (4)
    "silent": true,          (5)
    "rich": true,            (6)
    "customFields": {        (7)
        "field1": "value1",
        "field2": "value2",
        "fieldX": "valueX"
    }
}
1 APNS setting alert message
2 APNS setting alert title and message
3 APNS setting badge
4 APNS setting sound
5 APNS setting content-available (optional)
6 APNS setting mutable-content (optional)
7 entry point for custom fields

Note: The Keystore(Certificate)/Key(Token) obtained from APNS should be configured in App→ Keystore(Certificate)/Key(Token)

Firebase push input format

  1. Push format JSON

{
    "collapseKey": "123",      (1)
    "delayWhileIdle": "false", (2)
    "timeToLive": "1800",      (3)
    "customFields": {          (4)
        "field1": "value1",
        "field2": "value2",
        "fieldX": "valueX"
    }
}
1 FCM setting collapseKey
2 FCM setting delayWhileIdle
3 FCM setting timeToLive
4 entry point for custom fields

Note: The Server Key obtained from FCM should be configured in App→ Server Key

Web-browser (Chrome, Firefox, etc.) push input format

Api key for app is a GCM/FCM server key (required for Chrome push and for other browsers which use GCM, e.g. Opera).

Example transform template:

[
  {
    "operation": "shift",
    "spec": {
      "url": "data.url",
      "*": "&"
    }
  },
  {
    "operation": "default",
    "spec": {
      "icon": "icon.png",
      "data": { "url": "http://push.delivery" },
      "requireInteraction": "true"
    }
  }
]

This template transforms "url":"link" to "data":{url:"link"} (as required for notification options), writes all other key-value pairs as is and adds default elements to resulting json.

The API for showing a notification in browser (javascript):

<ServiceWorkerRegistration>.showNotification(<title>, <options>);

Title and options could be declared and used as following:

const notificationTitle = 'Title';
const notificationOptions = {
    "title":"eThinking Push Demo",
    "body": "Body text line 1 \n Body text line 2",
    "data": { "url": "http://push.delivery" },
    ...
};
...
self.registration.showNotification(notificationTitle, notificationOptions);

Thus if the above described template and demo service worker (see source code) are used, then the outgoing json should contain following options:

The list of common notification options:

* title - notification's title
* body - notification's body text
* icon - url to icon image
* image - url to body image
* url - url will opened in a new window by click on the notification
* requireInteraction - if true, then the notification will not disappear until user action
* badge - small monochrome icon
* actions - array of actions / buttons (see example 2)

Other options:

* timestamp
* sound
* vibrate
* dir
* tag
* renotify
* silent

Example push message 1 ( title, icon, body and image ):

{
    "title":"eThinking Push Demo",
    "icon":"icon.png",
    "url":"http://push.delivery",
    "body":"Good morning!",
    "requireInteraction":"true",
    "image":"https://imageUrl"
}

notification view in Chrome:

Example

"Image" and "Require interaction" options work only in Chrome at the moment (tested on Google Chrome 60, Firefox 55, Opera 47). An "Image" option requires "https" url.


Example push message 2 ( title, icon, body and buttons ):

{
    "title":"Demo title",
    "icon":"iconFile.png",
    "body":"Hello!",
    "requireInteraction":"true",
    "actions": [
       {"action": "like", "title": "Like", "icon": "https://example/like.png"},
       {"action": "reply", "title": "Reply", "icon": "https://example/reply.png"}
    ]
}

notification view in Chrome:

Example

Actions should be handled in service worker:

self.addEventListener('notificationclick', function (event) {
    event.notification.close();
    let clickResponsePromise = Promise.resolve();
    if (event.action === 'like') {
        clients.openWindow("http://...");
    }
    else if (event.action === 'reply') {
        clients.openWindow("http://...");
    }
    event.waitUntil(Promise.all([clickResponsePromise]));
});

Javascript API

Overview

This API documentation covers usage of the Javascript library to receive push notifications

To use this library you need to have a project setup by ethinking. Please get in contact if you don’t have access to the Admin UI of the push library.

Setup of library

To initiate the library you need to do the following

<script src="<libraryLink>"></script> (1)
1 Library link provided with customer onboarding.
Example Initiation
let push = new ethinkingPush(
messageSenderId, (1)
projectName, (2)
serviceWorkerPath (3)
);
1 Firebase messengerId, retrieved from the firebase console
2 Project Name, provided by us beforehand
3 Path to your service worker, can be anything but needs .js ending: firebase_service_worker.js

Functions

init()

Initializes the push for a certain app. For the browser push Firefox and Chrome use the same app. All infos are coming from the Admin UI

Example Init
push.init({
  appId: '123', (1)
  user: 'api-test-123', (2)
  password: '12345657890' (3)
});

To get any of the information, go to your Admin UI, open an App

1 String - AppId
2 String - AppUser
3 String - AppPassword

getTags()

Gets tags from the push backend, depending on the status of the user it returns subscribed and all Tags

getTags() returns a promise, the objects represents all tags from your app and subscribed apps depending on the subscription status of the user
Example getTags
push.getTags().then(result => {
  // TODO show tags here in a list
});

The format of the promise will be an Array with the following structure:

Example Array for all Tags
[
   {
      id: 111,
      name: 'Test Tag',
      subscribed: false
   },
   {
      id: 111,
      name: 'Test Tag',
      subscribed: false
   }
]

registerTags(tags)

Register several or a single tag to the current DeviceId

The parameter tags can be a number or an Array
Example register single Tag
push.registerTags(123);
Example register several Tags
push.registerTags([123, 456]);

unregisterTags(tags)

Unregister several or a single tag to the current DeviceId

The parameter tags can be a number or an Array
Example unregister single Tag
push.unregisterTags(123);
Example unregister several Tags
push.unregisterTags([123, 456]);

subscribe(tags)

Subscribes the user and gets a deviceId necessary to update Tags. Requests the permission if none is given, gets deviceToken and stores it in localStorage

The parameter tags can be a number or an Array
Example several Tags
push.subscribe([123, 456]);

unsubscribe()

Unsubscribes the user and removes the deviceId

Example unsubscribe User
push.unsubscribe();
After the Unsubscription, the user needs to subscribe() again

checkPermission()

Check the browser notification permission, returns <boolean>

Example
push.checkPermission();

getPermission()

Requests the permission to send notifications without subscribing the user. Can be necessary when permission has been manually revoked.

Returns <boolean> and sets deviceId for the user

Example
push.getPermission();