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": "dave@acme.com"
  },
  "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:

Property	Type	Description
`channelOptions.nativePush`*	Push Channel Options* object	The push channel options block

Push Channel Options Object

Property	Type	Description
`deepLink`*	Deep Link* object	The Deep Link and URL block

Deep Link Object

Property	Type	Description
`fcm.url`*	String	The deep link or URL link to use for Android devices
`apns.url`*	String	The deep link or URL link to use for iOS devices
trackingLink	String	This 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": "dave@acme.com"
  },
  "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:

Property	Type	Description
`platforms`*	messageAlertPlatforms* object	The platform specific details for the alert. If specified, these are set verbatim and alert.title / alert.body values are ignored

messageAlertPlatforms

Property	Type	Description
`apns`	messageAlertApns* object	The APNS native channel push message specific details
`fcm`	messageAlertFcm* object	The FCM native channel push message specific details

messageAlertApns

Property	Type	Description
`badge`	integer	The value to display on the application badge
`sound`	string	The soundfile to play on the device when the notification arrived
`alert`*	string	The alert to display on the device when the notification arrives
`payload`	object	The data payload to send to the device

messageAlertFcm

Property	Type	Description
`collapse_key`	object	The collapse key to send to FCM
`data`	object	The payload to send to the device
`notification`*	messageAlertFcmNotification* object	Details of the notification to display

messageAlertFcmNotification

Property	Type	Description
`title`*	string	The title to display
`body`*	string	The body to display
`image`	string	Contains 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

Examples of sends using custom bodies are:

{
  "to": {
    "profileId": "joe@acme.com"
  },
  "customBody": {
    "nativePush": {
      "platforms": {
        "apns": {
          "alert": "Push message send",
          "badge": 1
        },
        "fcm": {
          "notification": {
            "title": "Exciting news!",
            "body": "Push message send"
          }
        }
      }
    }
  },
  "rules": [
    "nativePush"
  ]
}

{
  "to": {
    "email": "joe@acme.com"
  },
  "customBody": {
    "nativePush": {
      "platforms": {
        "apns": {
          "alert": {
            "body"    : "Your body" ,
            "subtitle": "Sub title" ,
            "title"   : "Your title"
          },
          "badge": 1,
          "payload": {
            "dd_deepLink": {
                "url": "example://navigation?type=prod&id=123"
            }
          }
        },
        "fcm": {
          "notification": {
            "body": "Your body",
            "title": "Your title"
          },
          "data": {
            "dd_deepLink": {
              "url": "example://navigation?type=prod&id=123"
            }
          }
        }
      }
    }
  },
  "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