Push

Richie Push API

REST API for sending push notifications to Richie apps

Richie Push API is a server-to-server REST API which can be used by the publishers to send push notifications to Richie apps running on iOS and Android devices.

Request

  • Method: POST
  • URL:
https://data.richie.app/push/v2/admin/task
  • Headers:
Authorization: Basic <credentials>
Content-Type: application/json

HTTP Basic auth credentials will be provided to Richie Push API integrators by Richie.

Body

{
  "app_id": "your-app-id",
  "topics": [
    "breaking-news",
    "sports",
    "culture"
  ],
  "payloads": {
    "ios": {
      "aps": {
        "alert": {
          "title": "Push Notification Title for iOS",
          "body": "Push Notification Body Text for iOS",
          "publisher-item-id": "100200",
        },
        "content-available": 1
        "issue-guid": "2258b0e6-6748-46c2-8e67-0893c0542fbb",
        "issue-page": 10
      }
    },
    "android": {
      "data": {
        "title": "Push Notification Title for Android",
        "body": "Push Notification Body Text for Android",
        "external-browser-url": "https://example.com/news/article/1",
        "issue-guid": "2258b0e6-6748-46c2-8e67-0893c0542fbb",
        "issue-page": 10
      }
    }
  }
}

app_id

The client app identifier. This value will be provided to Richie Push API integrators by Richie.

topics

With topics you can target specific groups of app clients. Client apps can register to a set of topics and push notifications can then be sent to those topics. Topics are app-specific, and are configured separately from Push API.

To send push notification to all client apps regardless of their topic subscriptions, use the special topic all_users.

payloads

There are 6 supported keys which are used to specify the contents of notification:

  • title
  • body
  • publisher-item-id
  • external-browser-url
  • issue-guid
  • issue-page

These keys can be sent to either iOS clients, Android clients or all clients.

  • For iOS, place these keys in ios { aps { alert { … } } } object
  • For Android, place these keys in android { data { alert { … } } } object

Max size for each payload (ios and android) is 4 KB.

title

The notification's title. Required, string.

body

The notification's body text. Required, string.

publisher-item-id

Publisher's identifier for the news item related to current notification. Client apps will use this identifier for opening related news item if user taps on the notification. This value must be present in the news feed consumed by the client apps.

If this key is omitted, tapping on the notification will bring the app to the foreground without any navigation action. Optional, string.

If this value is provided, external-browser-url should be omitted.

external-browser-url

A full HTTPS URL which should be opened in an external mobile browser when user taps on the current notification. If this value is provided, publisher-item-id should be omitted.

Optional, HTTPS URL string.

issue-guid and issue-page

If specified, this must be the uuid string value of an Richie Editions Issue (https://richie.dev/docs/editions/indexes) and an optional page number, an integer, to open the issue to. If the page number is not specified, the issue will be opened to the first page.

content-available

This flag is relevant for iOS only, and should be placed directly under the aps object (NOT under alert). If content-available is set to 1, the operating system is asked to launch the app in the background when push notification is received, even if user does not tap on it. This gives the app a chance to update and cache the latest news feeds, so they are readily available when user opens the app the next time.

Response

HTTP 201

Returned when push notification payload was accepted for delivery to the mobile clients. The delivery is asyncronous. In most cases, it takes less than 60 seconds to reach all end user devices.

HTTP 401

Returned if HTTP Basic auth credentials were invalid. Please contact Richie to get valid credentials for your app.

User-specific request

Target a single or several clients by using external_user_ids instead of topics.

  • Method: POST
  • URL:
https://data.richie.app/push/v2/admin/task
  • Headers:
Authorization: Basic <credentials>
Content-Type: application/json

HTTP Basic auth credentials will be provided to Richie Push API integrators by Richie.

Body

{
  "app_id": "your-app-id",
  "external_user_ids": [
    "abcde...",
    "12345..."
  ],
  "payloads": {
    "ios": {
      "aps": {
        "alert": {
          "title": "Push Notification Title for iOS",
          "body": "Push Notification Body Text for iOS",
          "publisher-item-id": "100200",
        },
        "content-available": 1
      }
    },
    "android": {
      "data": {
        "title": "Push Notification Title for Android",
        "body": "Push Notification Body Text for Android",
        "external-browser-url": "https://example.com/news/article/1"
      }
    }
  }
}

Content analytics

Push payload may contain additional fields which can be used in content analytics. For example, if push notification refers to a news item using the publisher-item-id key, the analytics event which is posted when that news item is opened can refer to the values included in the push payload. The configuration of analytics events themselves is done separately by Richie team and it may target various analytics backends.

An example push payload with extra keys for content analytics:

  [...],
  "payloads": {
    "ios": {
      "aps": {
        "alert": {
          "title": "Push Notification Title for iOS",
          "body": "Push Notification Body Text for iOS",
          "publisher-item-id": "100200",
          "custom_key": "custom_value"
        },
        "content-available": 1
      }
    },
    "android": {
      "data": {
        "title": "Push Notification Title for Android",
        "body": "Push Notification Body Text for Android",
        "publisher-item-id": "100200",
        "custom_key": "custom_value"
      }
    }
  }

Limitations

  • Additional keys used in analytics cannot contain dash characters (-) due to internal platform limitations
  • Nested keys are not supported. All additional keys must be on the same level as the default payload keys (such as title, body, etc)

Push delivery analytics

Optional push delivery analytics can be configured, where each push task will be reported to a desired endpoint. The endpoint must authenticate the analytics data request and decode a JSON body.

An example POST request body which will be sent to the configured endpoint:

{
  "app_id": "an-app",
  "completion_time_ms": 765,
  "deletions": 0,
  "failures": 17,
  "payloads": {
    "android": {
      "data": {
        "alert": {
          "body": "Push Notification Body Text for Android",
          "external-browser-url": "https://example.com/news/article/1",
          "title": "Push Notification Title for Android"
        },
        "task_id": "00f5c216-ee53-4e29-af13-f109d5563a9e"
      }
    },
    "ios": {
      "aps": {
        "alert": {
          "body": "Push Notification Body Text for iOS",
          "publisher-item-id": "100201",
          "title": "Push Notification Title for iOS"
        },
        "content-available": 1,
        "task_id": "00f5c216-ee53-4e29-af13-f109d5563a9e"
      }
    }
  },
  "successes": 14400,
  "topics": [
    "all_users",
    "food"
  ]
}
Previous
Richie Entitlements API
Next
Push Credentials