Understanding Key-Value Pairs and How They Support Smart Customization

Every marketer comes into their job with a different set of skills and a different knowledge base when it comes to the tools and technologies that make modern marketing possible. But while it’s not too difficult to get up to speed on key messaging channels (e.g. email, SMS, push, in-app messages) or marketing functionalities (e.g. dynamic segmentation, frequency capping), there are other, more esoteric elements that can be a challenge to wrap your head around, especially if you don’t have a technical background. That, in turn, can sometimes lead marketers to underutilize them, causing them to miss out on opportunities to support a better customer experience.

That’s often the case with one of these less-discussed tools: Key-value pairs (KVPs). So, to help out, we’re going to walk through what KVPs are, how they work, and how they can support your personalization and larger customer engagement efforts.

What Are Key-Value Pairs?

At its core, a key-value pair is a data unit made up of two linked components: A value (for instance, “blue”) and a corresponding key (for instance, “favorite color”) that describes that value. KVPs—which are also known as field-value pairs, name-value pairs, or attribute-value pairs—are typically used in computer programming when there’s a need to describe and categorize two things together.

Having a hard time wrapping your head around the concept? Just imagine that you have a whole bunch of customer records in a database somewhere, and one of the fields in that database is “Current City.” In general, each one of those employees is going to have a different title, but if you just listed the cities without giving any context, someone reviewing the data might well get confused—after all, that city might well be that individual’s hometown or where they went to college or a place they own property. With KVPs, however, that value (e.g. “Chicago”) would be paired with an explanatory key “(e.g. “Current City”)—so the data unit would be something like “Current City:Chicago” or an equivalent.

What Can Brands Do With Key-Value Pairs?

Because key-value pairs can be conceptualized in a range of different ways (e.g. in a list, in an array), there’s a wide variety of different ways they can be used in a software context. At Braze, however, they’re usually leveraged by our customers to outline or highlight some extra pieces of information within a specific messaging channel, allowing for nuanced customization.

Take Content Cards, for example. When a marketer wants to surface a Content Card to their users, they can create a Content Card campaign in the Braze dashboard and add in text, images, buttons, and whatever else they might want to include. All those elements end up being translated into code and then sent to the brand’s app or website, where KVPs written into that code will be used to render and customize the appearance and behavior of that Content Card. So, in essence, the Content Card you create in the Braze dashboard is turned into code, passed to the app or website and then reconstituted in the form of the message.

Our default Content Cards contain KVPs for things like the message title, images, body copy, buttons, and other core elements. But what if you want to do additional customization of your Content Cards—or on messages in other channels? In Braze, marketers can go into the dashboard and just edit the Content Card or other message they’re building and add KVPs using the edit tab. And when they do that, they’re really just adding to the code that’ll be passed to the app that has to deliver the message in question.

Imagine that you want to add an additional KVP with “user name” as the key and then “Josh Stevens” as the value to your Content Card. When Braze translates everything into code, all of the different standard KVPs that are associated with the different elements of the Content Card will be in there—and at the very end, that new, custom KVP will be included. And when the Content Card is launched, the app or website will read the code and say, okay, here’s the title KVP, let’s use that to render the title for this Content Card—and will do something similar for all the standard KVPs like the body copy, images, etc. When it gets to the custom KVP you added, it won’t render anything because there isn’t built-in action that it’s being instructed to take in connection with it. Instead, that KVP can serve as the foundation for future customization.

For brands that use the out-of-the-box Content Cards integration, that integration will only look for the basic KVPs needed to inform the out-of-the-box presentation of a given Content Card. But their developers can come back in and write additional code that can leverage any of those “extra” KVPs to support additional functionality, customization, and user value.

One place we often see this is in apps that are using Content Cards to power multiple different messaging experiences within a single app or website. Let’s imagine that your app is using Content Cards to power a scrolling news feed that showcases all the New Release movies that have just become available, as well as another, separate in-app inbox where Content Cards are being used to highlight all the different push notifications that each customer has received from your brand. The actual custom experience between these two different Content Card-powered experiences is very distinct, but they’re both fundamentally the same messaging channel—so how does your app know which Content Cards to put in the inbox and which ones to put in the news feed?

The answer? Those custom KVPs. By including a KVP that identifies whether a message belongs in the inbox or the feed and then having your developers write a function that uses those KVPs to sort the messages, you can ensure that every Content Card is included in the right experience and rendered the way you intend. By the same token, if you want to create special customizations within one of those messaging experiences, you can add custom KVPs that flag when a given message should behave differently from other Content Cards and when it should follow the standard rendering. And, ultimately, that makes KVPs a powerful way to add extra information—and support deep customization—to the marketing messages you send.

Something else we see brands doing to support seamless message triggering and customization is adding Liquid personalization to their KVPs. Liquid’s responsive nature makes it possible to modify KVPs based on specific actions or subscription states associated with each individual user, allowing one KVP to adjust based on information associated with each user you’re trying to reach. This kind of filtering is used all the time by Braze customers to determine which Content Cards should be surfaced to which customers, depending on an individual user’s actions (e.g. did they open this email?) or state (e.g. are they a member of your loyalty program?).

What does that look like? Imagine that you’re a news brand and you have a button within your app that users can press to opt into ongoing in-app updates—delivered via Content Cards—on the upcoming US presidential election. In a scenario like this, you’d want to trigger a Content Card letting them know that they’d turned on in-app updates and welcoming them to the flow, but only if they actually pushed the button in question; if they haven’t pressed the button, you don’t want to show them any Content Cards in that flow. To fulfill that use case, you can log that button click as a custom event, create a Content Card designed to welcome them to the in-app flow, and include a custom KVP that tells the app whether or not an individual user has clicked the button. Then, when the message is sent to the app to be rendered, the handler function will determine whether or not to display the card to a given user based on what the KVP tells it about whether the button has been pushed. That way, you can deploy the campaign, but ensure that only people who have signaled interest in receiving it actually do—and do it all in a simple, scalable way.

Can Key-Value Pairs Be Used For Other Messaging Channels?

It’s definitely possible to leverage KVPs to support customized experience in other channels—however, it’s also true that Content Cards tend to be the place that marketers are most likely to make use of them. Because Content Cards natively leverage key-value pairs to inform messages sent into this channel, KVPs are front of mind for marketers using Content Cards, making the mental leap to using them to customize outreach less significant.

That said, one common use case we see for KVPs in other messaging channels is leveraging them to help support a nuanced message tagging system. A cool thing about key-value pairs that when you add one to a message, it literally becomes encoded in the object itself, whatever it is—whether you’re working a push notification, a Content Card, or other messaging channel, the KVP you’ve added is now automatically part of the code associated with that message. For brands that are using our Currents high-volume data export feature, that makes it possible to add different KVPs to different subsets of your marketing campaigns and then segment and analyze those specific campaigns within an external analytics platform.

That means, for instance, that a data scientist at a Braze customer could potentially pull all of the analytics for every push notification that’s been “tagged” with a specific custom KVP. And that’s a pretty powerful tool, because once you have that organizational system in place, you can start doing things like assigning real-time value that was driven for each relevant message—think things like conversions and purchases. In that scenario, you could potentially tag every promotional campaign sent via push with a custom KVP, then, on the backend, you could pull together all the clicks, opens, impressions, conversions, etc. associated with those specific campaigns and easily compare how it performed compared to last year’s equivalent campaign.

Why Does the Partnership Between Marketing and Engineering Teams Matter for Key-Value Pairs?

While it’s always a good idea to cultivate a good relationship between your marketing team and your developers, this connection is especially important if you want to take full advantage of KVPs to enrich and better understand the impact of your customer messaging program. Why? Because unless you have a very technical marketing team, you’re going to require some level of dev support to make the most of custom KVPs in your marketing efforts.

In general, I tell Braze customers that they have to have a hand-in-glove relationship between their marketing and development teams. That’s because your marketers are usually the people who actually insert the IDs and KVPs into messages, and they usually do that through the Braze dashboard. At the same time, the developer teams are the ones who actually write the code that handles the custom actions associated with the KVPs that have been added in the dashboard. If you try to use custom KVPs without strong, consistent communication between those stakeholders, it can get messy.

Take the example I mentioned above where a brand is using custom KVPs to power two different Content Card messaging flows in a single app. With good cross-team communication, making this happen isn’t hard, but things break down quickly without it. If, for instance, the marketers on your team tag all of the Content Cards that are meant for the in-app inbox with “Inbox” with a capital “I” and the developer responsible for supporting this effort writes “inbox” with a lowercase “i,” none of the custom behavior associated with that Content Card will happen—in fact, the Content Card won’t appear in the inbox at all.

The only way to avoid that outcome is with clear communication across marketing and technical teams. So, if you’re going to take advantage of custom KVPs, making sure the lines of communication are strong is job number one.

How Much Work Does It Take to Use Key-Value Pairs?

For some marketers, KVPs can seem a little intimidating at first, since taking full advantage of them does require dev work. However, don’t let that stop you from making use of this key tool. The actual amount of work required to support most common custom KVP use cases from a dev perspective is actually pretty limited—generally, I’ve found that the dev work required can be completed in a couple of hours for all but the most complex implementations.

Usually, the first step is for someone on the marketing team to actually add the KVP in question to a message via the Braze dashboard. Once that happens, a developer will need to write the handler function to tell their app or website how to respond to a message including that KVP. In most cases, that’s it—that’s all that has to happen. And the complexity of that handler function is the big determining factor when it comes to the level of dev work and effort required. If all you want to do with your KVP is use it to sort message placement within your app, that might take a developer as little as 20 minutes. If, on the other hand, your handler function needs to do something advanced and architectural, it could take significantly longer. For instance, if you needed to create a KVP-related function that actually hits your servers, checks all the handler details, pulls all the handler data back, that might well take a couple days to code.

That said, I think that for 95% of the custom KVP use cases we see come through, you’re talking an hour or two of dev time, max.

How Are Brands Using Key-Value Pairs to Customize Content?

One of my favorite examples of a brand using custom KVPs in cool, interesting ways happened a couple years back. Grindr, which is a leading LGBTQ+ social network, was looking for a way to celebrate Pride month in the midst of the COVID-19 pandemic, and ended up deciding to take their celebration online, where they ​​launched a campaign called Pride Perseveres, offering daily activities, fundraisers, performances, and more in a safe, digital environment.

Because Grindr had limited time to build out the experience for their users, due to the disruptions caused by COVID, they turned to Braze and decided to power their digital celebration with Content Cards, which had already been implemented in their app as a content delivery tool. By taking advantage of Content Cards that were individually personalized using custom KVPs, Grindr was able to dynamically target and deliver relevant digital Pride events to each individual user and to power what looked like an innovate new UI, all without the back end lift it would have taken to build out a new feature in its app. Plus, the flexibility that Content Cards make possible allowed this calendar of events to accommodate everything from live performances to merchandise sales, tackling a variety of customer and brand needs within the same platform.

The results were impressive. Grindr saw up to 34% of daily active users (DAU) engage with Pride Perseveres content, and the app experienced a lift in DAU that helped mitigate the negative effects of the pandemic on the brand’s business. What’s more, response to the promotion was very positive, with 65% of users who interacted with the Content Cards-fueled UI expressing a positive view of the campaign, and users leaving feedback comments telling the company that the program had made them feel less alone and prouder than they otherwise might have been.

All in all, a major success—and one that wouldn’t have been possible without the flexibility and power of custom KVPs.

Final Thoughts

So, there you have it—with key-value pairs, brands can customize the message they send in new and exciting ways, while also digging deeper into the nuances of campaign performance. To learn more about KVPs and how to leverage them in connection with the Braze platform, check out our documentation.

Interested in working with a Braze Technical Account Manager (TAM) like Josh Collins to deepen your technical knowledge and get more out of your use of Braze? Contact your Braze account team for more information on how to get started.