Push

Channel identifier

In the API this channel can be referenced using: nativePush

This identifier can be used in the rules array, and customBody sections.


Channel setup

To setup the Push channel you must:

  1. integrate the App Messaging Foundation SDK into your mobile apps in order to register the required push token details and profile ID to send messages.
  2. configure your native push channels and authentication scheme in the App Messaging channel setup. You need to configure FCM for Android and APNS for iOS.
    Learn more in the Setup guide.

Send messages

To send native push messages using the Enterprise Communications API, ensure that when you want to send a message you include the nativePush channel in your rules or ruleSet and follow the guidance below for creating the rest of the request.

Address your messages

When you integrate the App Messaging Foundation SDK into your mobile app you must provide a callback for the SDK to authorise and identify app users. The callback should issue a JWT using the settings you specified, and importantly include the ID or the user (by default in the sub claim) which is used as the profile ID for the user.

You should ensure you start a session with the SDK which calls the auth callback in your app and the App Messaging Foundation SDK acquires the native push tokens automatically from the device and uploads them against the profile your JWT claims to represent.

To target who an app messaging message is delivered to, you must include the profileId for the user in the to section of the request. This sends a push message to mobile devices associated with the profile ID.

1166

Integrating the App Messaging Foundation SDK into your App

Message content

You must specify a body and title for your push messages. The body is the main body text of your message; we recommend keeping this to 160 characters to ensure it can be displayed in full on most mobile devices. The title is shown above the body text on Android, and concatenated to the front of the body text on iOS. The title is used to give context to the message.

Examples

{
  "body": "A push message sent from the One API",
  "title": "dotdigital news!",
  "to": {
    "profileId": "[email protected]"
  },
  "rules": [
    "nativePush"
  ]
}

📘

Badge counts and custom behaviors

Use a customBody to define advanced or device specific features such as iOS badge counts or custom data payloads to drive deep links.


Channel options

There are no channel options for the nativePush channel.


Custom body

The Enterprise Communications API automatically creates basic push messages for you if you define the body and title properties when sending a message, but you can specify advanced options if you use the customBody property and define a nativePush object within it.

PropertyTypeDescription
platformsmessageAlertPlatforms objectThe platform specific details for the alert. If specified, these are set verbatim and alert.title and alert.body values are ignored.

messageAlertPlatforms

PropertyTypeDescription
apnsmessageAlertApns objectThe APNS native channel push message specific details.
fcmmessageAlertFcm objectThe FCM native channel push message specific details.

messageAlertApns

PropertyTypeDescription
badgeintegerThe value to display on the application badge.
soundstringThe sound file to play on the device when the notification arrives.
alertstringThe alert to display on the device when the notification arrives.
payloadobjectThe data payload to send to the device.

messageAlertFcm

PropertyTypeDescription
collapse_keyobjectThe collapse key to send to FCM.
dataobjectThe payload to send to the device.
notificationmessageAlertFcmNotification objectDetails of the notification to display.

messageAlertFcmNotification

PropertyTypeDescription
title_stringThe title to display.
body_stringThe body to display.
imagestringContains the URL of an image that is going to be downloaded on the device and displayed in a notification. JPEG, PNG, BMP have full support across platforms. Animated GIF and video only work on iOS. WebP and HEIF have varying levels of support across platforms and platform versions. Android has 1MB image size limit. Quota usage and implications/costs for hosting image on Firebase Storage.
{
  "to": {
    "profileId": "[email protected]"
  },
  "customBody": {
    "nativePush": {
      "platforms": {
        "apns": {
          "alert": "Push message send",
          "badge": 1
        },
        "fcm": {
          "notification": {
            "title": "Exciting news!",
            "body": "Push message send"
          }
        }
      }
    }
  },
  "rules": [
    "nativePush"
  ]
}

Receipts and inbounds

Receipts
If you need to to know the status of messages you've sent using one of our Enterprise Communications APIs, you can request that delivery receipts are forwarded to a URL of your choosing using the webhook system.

You can receive the following types of receipts:

  • Sent
  • Failed
    If a push cannot be sent to any of the profile’s devices.