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.

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:

Push Channel Options Object

Deep Link Object

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:

messageAlertPlatforms

messageAlertApns

messageAlertFcm

messageAlertFcmNotification

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"
  ]
}

{
  "to": {
    "email": "[email protected]"
  },
  "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