Sending push deep links and custom data

This page explains what you choose when you send a push message, and which payload your app receives as a result. Use it to connect the options in the Program Builder push node to the code in your app.

Your marketing team usually sends the push message, and your development team builds the app that receives it. Both need to agree on the option and the values before a deep link or a custom data payload works.

You can send the same options with the omnichannel messaging API. See Send the same options with the API.

Choose what happens when a user taps

The push notification node has an On tap drop-down menu with four options. Your choice decides which keys arrive in the payload, and therefore what your app must do.

Custom data is sent only with the Pass data option. If you enter custom data and then change the On tap option, Dotdigital Marketing clears it.

Enter values for each platform separately

The Open deep link and Pass data options both let you set a different value for each platform. The two options present this differently:

• Open deep link has two fields: Android deep link or URL and iOS deep link or URL.
• Pass data has two tabs: iOS and Android.

Complete the field or tab for each platform that your app supports.

The other two options need no per-platform values. Open app sends no link, and Open a survey, page, or form sends the same web address to both platforms.

Deep link length limits

The deep link fields have separate character and byte limits, and the byte limit is lower on iOS:

Send a deep link

Select Open deep link, then enter the value in the Android deep link or URL and iOS deep link or URL fields.

Each field accepts two kinds of value:

• A deep link into your app, such as myappscheme://product/123. Your app must register the URL scheme.
• A web address, such as https://example.com/product/123. The device opens it in the browser, unless your app claims that address with an Android App Link or an iOS universal link.

Your app must be able to receive the value that you send. Register a custom URL scheme, a universal link, or an Android App Link first. For the code you need, see the deep link section of the guide for your platform:

• Native Android apps
• Native iOS apps
• Hybrid JavaScript apps (Cordova)

Send a link to a survey, page, or form

Select Open a survey, page, or form, then choose the published landing page or form that you want to open.

This option works differently from the others:

• You choose an asset, not a URL. Dotdigital Marketing resolves your choice to the published web address of that page or form when it sends the message.
• Both platforms get the same address. The per-platform fields are hidden, because a web address works on iOS and Android alike.
• The tap is tracked. Dotdigital Marketing uses the same deep link mechanism as the Open deep link option, and adds a tracking link when the message is sent from a program.

Your app needs no extra code. The address starts with https, so the device opens it in the browser rather than in your app.

Send custom data

Select Pass data, then enter your JSON in the iOS and Android tabs.

Dotdigital Marketing delivers the JSON to your app in the dd_data object and does not change its structure. Your app decides what to do with it. Use this to build advanced push handling while you still send the message through Dotdigital Marketing.

For example, this data:

{
  "screen": "product-detail",
  "productId": "123"
}

arrives in the payload as:

{
  "dd_data": {
    "screen": "product-detail",
    "productId": "123"
  }
}

Your app is responsible for validating this data. Treat every value as untrusted input, and check that each key exists and has the type you expect before you use it.

Using personalisation in the data payload

You can insert a personalisation token into the Data field to send a value for each contact.

Dotdigital Marketing replaces the token with the contact's value as plain text. It does not adjust the result to keep the JSON valid, so you must write the JSON in a way that survives any value.

Test your message with a contact who has an empty value in each field that you insert, and with a contact whose value is unusually long.

For the code that reads dd_data, see the custom data section of the guide for your platform:

• Native Android apps
• Native iOS apps
• Hybrid JavaScript apps (Cordova)

Send a silent push message

The push notification node has a Silent push notification setting. Set it to Yes to deliver data to your app without notifying the user.

Use a silent push to start an action in your app in the background, for example to refresh cached content.

Your app receives only the data. Nothing appears on the device, so your app must receive the message and act on it.

Use a silent push with the Pass data option, so that your app has something to act on. A silent push has no alert for the user to tap, so a tap action serves no purpose. If you select Open a survey, page, or form, Dotdigital Marketing sets the silent setting back to No.

What a silent push sends

Your app needs extra configuration to receive a silent push. See the silent push section of the guide for your platform:

• Native iOS apps
• Hybrid JavaScript apps (Cordova)

To send a silent push with the API, see Sending a silent push with the API.

Title and message limits

A push notification displays a maximum of 160 characters in the title and in the message. The operating system replaces extra characters with an ellipsis.

The title and the message behave differently on each platform. On Android, the device shows the title above the body text. On iOS, the device joins the title to the front of the body text.

Send the same options with the API

You can send push messages with the Program Builder or with the omnichannel messaging API. The API uses the channel identifier nativePush.

Which endpoint to call

Before you build a request, read these guides:

• Calling the Omnichannel API, for authentication and the base request.
• Addressing your messages, for the to block. Push messages are addressed with the profileId, which comes from the sub claim of the JWT that your app supplies. See The role of the sub claim.
• Channel selection, for the rules and ruleSet arrays. Include nativePush to send to the push channel.
• Custom messages, for the customBody property.
• Push, for the full push channel reference and more examples.

How each Program Builder option maps to the API

This table maps each Program Builder option to its API equivalent:

Sending a silent push with the API

To send a silent push, set isSilent to true. This property sits inside customBody.nativePush.platforms, alongside the apns and fcm objects, so a silent push always uses customBody.

{
  "to": {
    "profileId": "05aed392-4de6-4ffe-8956-d855f854881d"
  },
  "customBody": {
    "nativePush": {
      "platforms": {
        "isSilent": true,
        "apns": {
          "alert": "Not displayed",
          "payload": {
            "dd_data": {
              "screen": "product-detail",
              "productId": "123"
            }
          }
        },
        "fcm": {
          "notification": {
            "title": "Not displayed",
            "body": "Not displayed"
          },
          "data": {
            "dd_data": {
              "screen": "product-detail",
              "productId": "123"
            }
          }
        }
      }
    }
  },
  "rules": [
    "nativePush"
  ]
}

Getting feedback on an API send

The push channel is a send-and-forget channel, so you receive two kinds of receipt: Sent, and Failed if the message reaches none of the profile's devices.

To receive receipts, you can use Message Events or Webhooks.

A receipt tells you that Dotdigital Marketing sent the message to Apple or Google. It does not tell you that the device displayed it. If a user has not granted notification permission, or the APNS environment does not match the build, you still receive a Sent receipt. See Push troubleshooting if messages do not arrive.