When we talk about personalization, we usually talk about why to personalize content, or what you can expect to get from it: Making the right ask at the right time is critical to taking advantage of the limited interactions you have with your supporters. We don’t always focus on the how, because the technical details can vary so much depending on the technology platforms you’re using — as well as your overall data strategy.
But if you’re using the BSD Tools, you have access to a little-known — but powerful — feature called the Personalization API. It requires a bit of technical know-how, but with just a small amount of code, you can personalize your supporters’ web experiences based on how they’ve engaged with you in the past: You can customize donation amounts based on a donor’s prior giving, ask your one-time donors to upgrade to a monthly gift, or give your most engaged supporters ways to get more deeply involved with your organization — all tailored to their known interests, activity, location, and any other information stored in their constituent profile.
How does all of this work? Here’s a primer that will help anyone with just a bit of front-end development expertise started.
Personalizing calls-to-action
Imagine that we want to add a small call-to-action link in our site header.
<header>
<nav>
// Navigation menu items
<a class=”personalized-cta”></a>
</nav>
</header>
First, we’ll need to check if a guid cookie has been set. The guid — or “globally unique identifier” — cookie is the key to everything: It’s the secure, unique identifier that allows us to get access to some basic information about the user. The BSD Tools set a guid cookie when the visitor identifies themselves in certain ways, such as clicking a link in an email or making a donation.
We’re using the JavaScript Cookie library here, but any method of retrieving a cookie will work.
const button = document.querySelector('.personalized-cta');
const guid = Cookies.get('guid');
If the visitor doesn’t have a guid cookie, we don’t know if they’ve ever engaged with the site before, so we’ll start by asking them to sign up.
if (!guid) {
button.setAttribute('href', 'https://yourbsdtoolsdomain.org/page/s/');
button.innerText = 'Sign Up';
}
However, if the visitor does have a guid set, we can make a call to the Personalization API to find out more about them. (Note: If you’re using the API from outside of the BSD Tools, your site URL will need to be whitelisted to prevent Cross-Origin Request Scripting errors. Contact Client Services to get that set up.)
We’re using the axios JavaScript library here, but the concept is the same regardless of how you like to make AJAX requests. The domain will be your BSD Tools Domain. The path is /page/graph/loe/ with the user’s guid appended.
axios.get(`https://yourbsdtoolsdomain.org/page/graph/loe/`)
If the request is successful, the Personalization API will respond with a JSON object that looks something like this:
{
"email":true,
"location":true,
"phone":true,
"donor":true,
"qd_enrolled":false,
"last_donation":"2018-11-02 18:44:07",
"highest_previous_contribution":25.00,
"group_recurring_donors": false
}
email: Whether the user has an email address in the BSD Tools
location: Whether the user has a physical address in the BSD Tools
phone: Whether the user has a phone number in the BSD Tools
donor: Whether the user has donated previously
qd_enrolled: Whether the user has enrolled in Quick Donate
last_donation: The date of the user’s last gift (if they’re a previous donor)
highest_previous_contribution: The largest one-time donation the user has made to date
group_recurring_donors: One example of a dynamic constituent group, in this case identifying whether the current user is part of the group of monthly donors.
You can configure the API to return membership in multiple constituent groups, allowing you to determine whether the user is part of one of your key segments (our Client Services team can help you set that up). For instance, in the example data above, you know whether the user is part of the constituent group identifying monthly donors, so you can use the Personalization API to show your monthly donors different content. Create a dynamic constituent group identifying people from certain states and you could target them with a specific ask, and so on.
All of this information can be used to personalize content. In the case of our call to action in the header, we’ll ask supporters whose emails are known to donate instead, and, if they’ve given previously, use their highest previous contribution to set the ask amount, instead of a generic $15.
You can preselect the donation amount on a BSD Tools donation form by including the parameter defaultAmt=XX in the URL. If the amount isn’t one of the preset options, it will be filled in as the “Other” option.
axios.get(`https://yourbsdtoolsdomain.org/page/graph/loe/`)
.then((response) => {
const data = response.data;
// The user has signed up for the email list, so let's ask them to donate.
if (data.email) {
let suggestedAmount = 15; // The default amount
if (data.highest_previous_contribution) {
// Ask the user for $5 more than their previous highest contribution.
// You could also scale the amount by a percentage, such as increasing it by 20%
// and then rounding to the nearest dollar.
suggestedAmount = data.highest_previous_contribution + 5;
}
button.setAttribute('href', `https://yourbsdtoolsdomain.org/page/contribute/default?defaultAmt=`);
button.innerText = `Donate ;
}
}
For supporters who have signed up for emails but never donated, the button will read Donate $15 and choose $15 as the default gift amount on the BSD Tools donation form. For a past donor with a highest previous contribution of $25, the button text and default selection will instead encourage them to donate $30.
All together then, our simple example to personalize a call to action in the header looks like this:
import Cookies from 'js-cookie';
import axios from 'axios';
const button = document.querySelector('.personalized-cta');
const guid = Cookies.get('guid');
// Handle case if no guid cookie is present.
if (!guid) {
button.setAttribute('href', 'https://yourbsdtoolsdomain.org/page/s/');
button.innerText = 'Sign Up';
} else {
// Call the Personalization endpoint using the guid value.
axios.get(`https://yourbsdtoolsdomain.org/page/graph/loe/`)
.then((response) => {
const data = response.data;
// The user has signed up for the email list, so let's ask them to donate.
if (data.email) {
let suggestedAmount = 15; // The default amount
if (data.highest_previous_contribution) {
// Ask the user for $5 more than their previous highest contribution.
// You could also scale the amount by a percentage, such as increasing it by 20%
// and then rounding to the nearest dollar.
suggestedAmount = data.highest_previous_contribution + 5;
}
button.setAttribute('href', `https://yourbsdtoolsdomain.org/page/contribute/default?defaultAmt=`);
button.innerText = `Donate ;
}
}, (error) => {
// If an error occurs (i.e. the guid value is invalid), fall back to a email signup CTA.
button.setAttribute('href', 'https://yourbsdtoolsdomain.org/page/s/');
button.innerText = 'Sign Up';
});
}
You can further use the data returned from the Personalization API to customize content as needed. You might look at the date of the last contribution and ask supporters who’ve already donated within the last month to take another action (maybe contacting their legislative officials through CallOut), while asking past supporters who haven’t donated recently to consider donating again.
Though this example works client-side, you could just as easily access the cookie and call the API server-side. Ultimately, the ways in which you use the Personalization API to create individualized experiences for your supporters are up to you. We’ve worked with our clients to use this API in all kinds of ways, from highlighting candidates running in the supporter’s state to upselling one-time donors to a monthly giving program.
A note on security
Features like the Personalization API, which expose a small amount of user data to the browser, need to be especially conscious of privacy and data security concerns. The BSD Tools take a number of precautions to make sure that personal data isn’t exposed in unintended ways.
First, most of the information returned is boolean: it’s either true or false. It specifies whether a person has an email address or location on file, but not the actual email address or location.
Some unidentified personal information, like the user’s last contribution amount, are included, however, so the second set of precautions is for the guid cookie itself. Its value is designed to be impossible to guess or derive from another known piece of data (like the user’s email address), and is non-sequential, meaning that having one guid value can’t help you figure out another user’s guid. When it’s set and retrieved as a cookie, it’s always over a secure connection, so no one can intercept it. It functions as a sort of secure “key” to fragments of the user’s profile.
Finally, you’ll note that a number of setup tasks mentioned above require you to contact our client services team. When you make a request to use the API, our team can provide some guidance and recommendations for how to use it safely.
Need help personalizing your content and communications for your audience? Let’s talk about it.