Custom push payloads

We’ve covered how to get started with Customer.io Push, but if you want to customize your push notifications even further and add things like deep links or images, custom payloads are the answer!

Getting started with custom payloads

Creating a custom payload for your push notification gives you granular control over the notification and its behaviour and appearance, in the same way as coding your email(s) in HTML does. It’s a bit more complex, but you can use it to add images, deep links, or interactions.

To access the custom payload editor, use this toggle:

You can then write or paste your custom code into the editor. Note there are different tabs for Android and iOS so that you can send custom code for each platform separately but, if you are using Firebase Cloud Messaging, you can just use the Android tab to send custom code that will be used for both Android and iOS.

Guidelines

First and foremost, identify what you’ll be doing with your custom payload: do you want to send people to a deep link in your app or show them an image? Next, make sure that your app supports that functionality. Many of these features require custom app development.

• If it does, your engineering team should be able to provide the JSON code for you.
• If it doesn’t, reach out to your engineering team and ask what your payload should be.

All apps are unique, there are many ways your custom code could be structured. Talk to your app developers to understand the payload you should send.

Once you have your payload, you’ll need to ensure that:

1. Your JSON code is valid.
2. The code you use follows the guidelines for the specific provider:
   • Apple Push Notification Service (APNs - iOS notifications)
   • Firebase Cloud Messaging (FCM - Android and iOS notifications)

Basic Example: FCM

Here’s the most basic example of a custom payload for sending to Android and iOS devices via Firebase Cloud Messaging:

{
  "message": {
      "notification": {
        "body": "YOUR MESSAGE BODY HERE",
        "title": "YOUR MESSAGE TITLE HERE"
      }
  }
}

Basic Example: APNs

And here’s the most basic example of a custom payload for sending to iOS devices via Apple Push Notification Service:

{
  "aps": {
    "alert": {
      "body": "YOUR MESSAGE BODY HERE",
      "title": "YOUR MESSAGE TITLE HERE"
    }
  }
}

Using liquid in push notifications

As always, you can use customer or event data in your custom payload. While you can technically use liquid in any string field, you probably want to limit liquid to body, title, and subtitle (on iOS) fields.

Here’s a basic Android (and iOS via FCM) example using customer and event data:

{
  "message": {
      "notification": {
         "body": "Hi {{customer.first_name}}, your {{event.event_title}} has been booked!",
         "title": "All set!"
      }
  }
}

And the same in iOS (when sending via APNs):

{
    "aps": {
        "alert": {
          "body": "Hi {{customer.first_name}}, your {{event.event_title}} has been booked!",
          "title": "All set!"
        }  
    }
}

This would result in a push notification that looks like this (on iOS):

Custom push payload reference

While you can send push notifications to both iOS and Android devices using FCM, if you want to provide a custom payload, you must provide separate payloads for your iOS and Android audiences.

If your custom payload does not match the shape below, or you provide an incorrect data type for a key, your notification may fail.

Android custom push payload

If you want to send a message, your push notification must include a message.notification object with a body, reflecting the message you want to send. You can pass additional options for the android push in the meassage.android.notification object.

The message.data object contains custom data that your app to interprets. Custom data isn’t supported natively; things like custom image handling and deep linking require additional development. Talk to your app’s developer(s) to understand the custom data that you can pass to your app. If you want to send a silent, custom data-only push, you can omit the message.notification object and send a data key instead.

The following shows the shape of an Android custom push payload; you’ll find a deeper explanation of the keys allowed in this payload below.

{
    "message": {
        "notification": {
            "title": "string", //(optional) The title of the notification.
            "body": "string" //(optional) The message you want to send.
        },
        "data": {
            //Optional key-value pairs that your app interprets.
            //We don't validate the keys or values you provide.
        },
        "android": {
            "notification": {
                //(Optional) Contains options specific to an android notification. 
                "icon": "string", 
                "sound": "string",
                "tag": "string",
                "color": "#rrggbb",
                "click_action": "string",
                "body_loc_key": "string",
                "body_loc_args": "stringified,array",
                "title_loc_key": "string",
                "title_loc_args": "stringified,array"
            }
        }
    }
}

iOS custom push payload (FCM)

When you send a custom notification, you can set a default message.notification with a body. The iOS custom payload portions of your notification appear in the apns object.

• headers is an object representing HTTP request headers defined in Apple Push Notification Service.
• payload is an object containing both the aps dictionary and any custom payload options you want to set, as defined by Apple’s payload reference. Including a title and body in the apns.payload.alert overrides the title and body set in the message.notification object.
• fcm_options is an object containing options for features provided by the FCM SDK for iOS.

The following shows the basic shape of an iOS custom push payload for FCM. You’ll find a deeper explanation of the iOS payload options that FCM supports in Google’s documentation.

{
  "message": {
    "notification": {
      // default notification
      "title": "string",
      "body": "string"
    },
    "apns": {
      "headers": {
        // headers defined in Apple Push Notification Service.
        "apns-priority": 10
      },
      "payload": {
        "aps": {
          // iOS message options go here
          "mutable_content": true      
        }
      },
      "fcm_options": {

      }
    } 
  }
}

iOS custom push payload (APNs)

If you want to send a message through the Apple Push Notification service (APNs), your push notification must include a aps.alert object with a body, reflecting the message you want to send. You can pass additional options for the push in the aps object (outside

You can pass additional options for the android push in the aps object (outside of the alert). Where the alert represents the message, these settings tell the device how to handle the message—whether to play a sound or add the message to a thread of notifications, etc.

You can also pass additional, custom data outside the aps object. This is data that your app is set up to interpret. Custom data isn’t supported natively; things like custom image handling and deep linking require additional development. Talk to your app’s developer(s) to understand the custom data that you can pass to your app. You can omit the alert and send a silent push, with just custom data (setting "content-available": 1), though it’s not the most common use case.

The following shows the shape of an iOS custom push payload using APNs; you’ll find a deeper explanation of the keys allowed in this payload below.

{
  "aps": {
    "alert": { 
    //can be string or object
    //alert object keys
      "body": "string",
      "title": "string",
      "subtitle": "string",
      "launch-image": "string",
    // localization arguments
      "title-loc-key": "string",
      "title-loc-args": ["array", "of", "strings"],
      "subtitle-loc-key": "string",
      "subtitle-loc-args": ["array", "of", "strings"],
      "loc-key": "string",
      "loc-args": ["array", "of", "strings"]
    },
    // message options
    "badge": number,
    "sound": "string or dictionary",
    "thread-id": "string",
    "category": "string",
    "content-available": number, 0 (default) or 1,
    "mutable-content": number, 0 (default) or 1,
    "target-content-id": string,
  },
  "custom-keys": "Optional, any type"
}

Got feedback?

We’re hoping to get your feedback on how you’re using custom payloads, if there’s anything you’re struggling with, or if there’s anything you’re really enjoying about it and want to make sure we keep.

Let us know!