What are Key/Value Pairs, and How to use them in your app marketing

5 minute read

Team Localytics

Key/value pairs are a set of linked items: a unique identifier and a value. These aren’t dissimilar to how you might think about the contents of a dictionary – each word represents a unique identifier, or key, and the value is that word’s definition. When used in your app, key/value pairs allow you to populate content, create custom deep links, and much, much more.

To take advantage of key/value pairs in your app marketing, you and your engineering team will need to do a bit of planning. That’s because key/value pairs only work if your app understands them. These identifiers and definitions need to be built in to the code of your app so that it can recognize the keys and know how to respond with the right values.

If you’re looking to enhance your messaging campaigns and app experience, using key/value pairs can unlock functionality beyond what you can do with the Localytics Dashboard. It might be hard to know how to take advantage of key/value pairs in the abstract – the possibilities are almost endless! That’s why we recommend coming up with campaign ideas, then working backwards to understand what your app will need to accomplish. Once you have that figured out, you can work with your engineering team to build in the key/value pairs that enable your marketing campaign ideas.

We’re going to dive into some of the ways that you can use key/value pairs to personalize your messages and create unique app experiences.


Key/value pairs are a very valuable addition to your mobile messaging toolkit. They’re one of the ways you can personalize messages to individual users or dynamically control how they experience the app.

TIP: key/value pairs are not noticeable to the user receiving the message but instead are delivered to the app and cause the app’s code to perform some type of action.

Push notifications

The most common use case for key/value pairs is for personalizing your messages. You can build a library of images that correlate to specific preferences, like favorite category for retail apps or genre for media and entertainment apps. When building out your push messages you can incorporate images that correspond with the individuals favorite categories automatically.

TIP: Keep in mind that you can also use liquid templating to personalize messages by dynamically inserting values into the message content eg. “Hey `{{ special.first_name }}`, order now for free shipping on your `{{ app.items_in_cart }}` items!”

key/values can deliver data you can use for a more complex rich push experience. For example, on iOS, you can send live streaming video or show the current status of a cab ride or delivery order. To do this, your key/value pair needs to connect a user or order ID to a content extension that will serve the content.

The push message you draft in Localytics should also include key/value pairs that allow for the display to be changed by using the property mutable content. Once the message is received by your app, it will use the key/value pairs to communicate with a service or content extension. The service extension can pull in static content, like message copy, pictures or video where the Content extension allows you to pull in live streaming content like a delivery map.


Key Value Pairs and Extensions


For retail apps, push messages are a great vehicle for delivering deals to app users. In order to keep the shopping experience consistent between mobile and web, it is necessary to sync discounts or offers (eg free shipping) with your PoS system. To do this, send your push message with a key/value pair to sync the offers available to the end user via your app to your PoS system. This ensures that your user should have access to that offer no matter where they check out, unifying the mobile app experience with the web.

In-app Messages

You can also use key/value pairs to alter the design elements of your in-app messages. Your app may be configured to change the dimension of the message window, hide the close button, or change the layout of your in-app messages by including a key/value pair with the message. With help from your dev team, you can design completely custom in-app messages that drive action and engagement in your app.

Another really common use case for key/value pairs is for deep linking. When paired with a CTA in your in-app message, you can use the key/value pair to drive users into a specific screen deeper in your app. For example, if you need a user to update their billing information you can drive them to the Account screen by linking to it with the key/value pair.

TIP: Deep links aren’t limited to in-app messages. They can be used with push notifications as well, as long as your app has been set up to handle them.

Inbox Messages

Using the Inbox tool, you can create A/B test to try out brand new app experiences and learn about how different layouts and colors impact your users behavior. When creating an Inbox campaign, you’re able to pass key/value pairs that can be configured to instruct the app on which version of the app layout to display. You can change button colors, copy, or any other design elements in your app experience.

With silent inbox campaigns you can change design elements in your app without the user seeing an actual message. This makes it really easy to update layouts or refresh colors in order to see what works best.

Mobile marketers are constantly working to optimize and personalize app experiences in order to drive engagement. With key/value pairs, they’re able to tackle more complex tests and design more advanced message journeys that delight users and move the needle.


Reliable products. Real results.

Every day, thousands of companies rely on Upland to get their jobs done simply and effectively. See how brands are putting Upland to work.

View Success Stories