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 please ensure you have completed the steps in the Setting up push notifications section.

Sending messages

Sending native push messages is simple using the Omnichannel API; simply ensure that when you want to send a message using the Omnichannel API in your rules or ruleSet you include the nativePush channel, and follow the guidance below for creating the rest of the request:

Addressing your messages

When you integrate the App Messaging Foundation SDK into your mobile app you will need to 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 will be used as the profile id for the user. You should ensure you start a session with the SDK which will call the auth callback in your app and the App Messaging Foundation SDK will now acquire the native push tokens automatically from the device and upload them against the profile your JWT claims to represent.

Now to target who a App Messaging message is delivered to simply include the profileId for the user in the to section of the request. This will send a push message to mobile devices associated with the profile id.

1166

Integrating the App Messaging Foundation SDK into your App

Message content

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

Examples

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

πŸ“˜

Badge Counts / Custom Behaviours

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

Channel Options

The nativePush channel has the following channel options:

Deep Links and URLs

You can optionally specify that when a push notification is tapped on that it invokes a deep link or opens an URL in a browser instead of the standard action of simply opening the app the push is related to. This can be useful as you can do a variety of things using deep links and URLs, such as:

  • Open specific pages within your app
  • Trigger an action within the app
  • Open a website or web form in a new browser

For deep links to work your app or another app must support the deep link scheme you use.

If you want to invoke a deep link or open a URL then you can specify the following channel options:

PropertyTypeDescription
channelOptions.nativePush*Push Channel Options objectThe push channel options block

Push Channel Options Object

PropertyTypeDescription
deepLink*Deep Link objectThe Deep Link and URL block

Deep Link Object

PropertyTypeDescription
fcm.url*StringThe deep link or URL link to use for Android devices
apns.url*StringThe deep link or URL link to use for iOS devices
trackingLinkStringThis URL will be called by the SDK embedded within the mobile app if the push notification is tapped / clicked on. It can be used to implement click tracking if required.

Example

{
  "body": "A push message sent from the Omnichannel API",
  "title": "dotdigital news!",
  "to": {
    "profileId": "[email protected]"
  },
  "channelOptions": {
          "nativePush": {
               "deepLink": {
                    "fcm": {
                         "url": "https://dotdigital.com"
                    },
                    "apns": {
                         "url": "https://dotdigital.com"
                    },
                    "trackingLink": "https://reporting.acme.com/example"
               }
          }
  },
  "rules": [
    "nativePush"
  ]
}

Custom Body

The Omnichannel 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 using the details below:

PropertyTypeDescription
platforms*messageAlertPlatforms objectThe platform specific details for the alert. If specified, these are set verbatim and alert.title / 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 soundfile to play on the device when the notification arrived
alert*stringThe 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
notification*messageAlertFcmNotification objectDetails of the notification to display

messageAlertFcmNotification

PropertyTypeDescription
title*stringThe title to display
body*stringThe body to display
iconstringThe icon to display

Examples of sends using custom bodies are:

{
  "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

To receive feedback Push channel sends please see the following:

Receipts

If you need to to know the status of messages you've sent using one of our Omnichannel API, you can request that delivery receipts are forwarded to a URL of your choosing using the webhook system. See the events in the Message Events section for more details on the receipt events you can receive.

You can receive the following types of receipts, as the Push channel in a fire and forget style communication:

  • Sent
  • Failed - If a push cannot be sent to any of the profiles devices