Key-Value Pairs

Braze enables you to send extra data payloads to user devices via key-value pairs. This feature is available across push, in-app, and News Feed messaging channels. Extra data payloads can help you update internal metrics and app content as well as customize push notification properties, such as alert prioritization, localization, and sounds.

Push Notifications

iOS

Apple Push Notifications service (APNs) supports setting alert preferences and sending custom data using key-value pairs. APNs makes use of the Apple-reserved aps library, which includes predetermined keys and values that govern alert properties.

APS Library
Key Value Type Value Description
alert string or dictionary object For string inputs, displays an alert with the string as the message with Close and View buttons; for non-string inputs, displays an alert or banner depending on the input’s child properties
badge number Governs the number that is displayed as the badge on the app icon
sound string The name of the sound file to play as an alert; must be in the app’s bundle or Library/Sounds folder
content-available number Input values of 1 signal to the app the availabilty of new information upon launch or session resumption
Alert Properties Library
Key Value Type Value Description
title string A short string that Apple Watch displays briefly as part of a notification
body string The push notification’s content
title-loc-key string or null A key that sets the title string for the current localization from the Localizable.strings file
title-loc-args array of strings or null String values that can appear in place of the title localization format specifiers in title-loc-key
action-loc-key array of string or null If present, the specified string sets the localization for the Close and View buttons
loc-key string or null A key that sets the notification message for the current localization from the Localizable.strings file
loc-args array of strings String values that can appear in place of the localization format specifiers in loc-key
launch-image strings The name of an image file in the app bundle you wish to be used as the launch image when users tap the action button or move the action slide

Braze’s message composer automatically handles the creation of the following keys: alert and its properties, content-available, sound, and category. These values can be input directly in the Dashboard as shown below.

iOS Automatic Keys

When Braze sends a push notification to APNs, the payload will be formatted as a JSON.

Simple Payload

1
2
3
{
    "aps" : { "alert" : "Message received from Spencer" },
}

Complex Payload

1
2
3
4
5
6
7
8
9
10
11
12
{
    "aps" : {
        "alert" : {
            "body" : "Hi, welcome to our app!",
            "loc-key" : "France",
            "loc-args" : ["Bonjour", "bienvenue"],
            "action-loc-key" : "Button_Type_1",
            "launch-image" : "Paris"
      },
        "content-available" : 1
    },
}
Custom Key-Value Pairs

In addition to the aps library payload values, you may send custom key-value pairs to a user’s device. In the message composer, click the gear icon and specify your key-value pairs below. The values in these pairs are restricted to primitive types: dictionary (object), array, string, number, and Boolean.

key-valueInput

Use-cases for custom key-value pairs include but are not limited to internal metrics keeping and setting the context for the user interface. Braze allows you to send additional key-value pairs along with a push notification to be used however you so please via your application within the extras key. If you prefer to use another key, ensure that your app can handle this custom key. Note you should avoid handling a top-level key or dictionary called ab in your application.

Apple advises clients to avoid including customer information or any sensitive data as custom payload data. Furthermore, Apple recommends that any action associated with an alert message should not delete data on a device. Note that if you are using the HTTP/2 provider API, any individual payload you send to APNs cannot exceed a size of 4096 bytes. The legacy binary interface, which will soon be depreciated, only supports a payload size of 2048 bytes.

Android

Firebase Cloud Messaging (FCM) allows you to send send additional data payloads in push notifications using key-value pairs. FCM specifies two types of payloads: notification and data. The notification payload has a 2KB limit and predetermined set of keys that govern message content. The data payload enables developers to send as much as 4KB of custom key-value pairs.

Notification Payload Key-Values
Key Value Type Value Description
body string The content of the push notification
title string The title of the push notification
icon string The file name of the desired image to display

Braze’s message composer automatically handles the creation of the notifcation payload.

Data Payload

Custom key-value pairs can be input by clicking the gear icon and specifying your key-value pairs below.

key-valueInput

Use-cases for custom key-value pairs include but are not limited to internal metrics keeping and setting the context for the user interface; they may be used for whatever purpose you choose. Note that your app’s backend must be able to process custom key-value pairs for the data payload to function properly. For more information on accessing key-value pairs sent with Android push notifications, refer to the Braze Documention.

Braze automatically formats both payloads as a JSON before sending them to FCM.

Notification and Data Payloads

1
2
3
4
5
6
7
8
9
10
11
{
    "notification" : {
        "body" : "Message received from Spencer",
        "title" : "Hi Will!",
        "icon" : "Smiley"
    },
    "data" : {
        "volume" : "6.7",
        "contents" : "https://blog.braze.com/"
    }
}
FCM Messaging Options

Android push notifications can be further customized with FCM message options. These include notification priority, sound, delay, lifespan, and collapsibility. These values can be input directly in the Dashboard as shown below. Refer to the Braze Documentation for further instructions on how to set these options in the Braze message composer.

Android Automatic Keys

Silent Push Notifications

A silent push notification is a push notification containing no alert message or sound, used to update your app’s interface or content in the background. These notifications make use of key-value pairs to trigger these background app actions. Silent push notifications also power Braze’s uninstall tracking.

Marketers should test that silent push notifications trigger expected behavior before sending them to their app’s users. Once you compose your iOS or Android silent push notification, ensure that you only target a test user by filtering on external user ID or email address.

Upon campaign launch, you should check that you have not received any visible push notification on your test device. For instructions on how to check if your silent push notification has updated your app as intended, contact your dedicated success manager or success@braze.com.

Please note that the iOS operating system may gate notifications for some features (Uninstall Tracking, Geofences, and Push Stories). Please note that if you are experiencing difficulties with these features, the iOS’s silent notifications gate might be the cause.

Web

Key-value pairs can also be added to web push notifications. Select the gear icon in the Braze message composer to do so.

key-valueInput

In-App Messages

To add a key-value pair to an in-app message, select the gear icon in the Braze message composer.

key-valueInput

Emails

For Braze customers that use SendGrid, key-value pairs will be sent as unique arguments. SendGrid allows you to attach an unlimtied number of key-value pairs up to 10,000 bytes of data. These key-value pairs can be seen in posts from the SendGrid Event Webhook. Note that bounced emails will not deliver key-value pairs to SendGrid.

key-valueInput

News Feed

Key-value pairs can be added to a News Feed Card in the Braze message composer below the categories drop down-menu.

key-valueInput

WAS THIS PAGE HELPFUL?