How to use the secure token to pass prize and winner information

In this doc, we’ll give you insight into how to set up a secure token to get full flexibility on how you choose your contest winners and assign them a specific prize. 

The idea behind the secure token feature is to provide you with a standardised and secure way of passing external information to a Qualifio campaign to influence its behaviour. Thanks to this feature, you can pass prize information to your campaign and decide whether the participant can be a winner.

How to use this for value-maximising contests

• Boost customer retention and reward their loyalty. When customers receive something extra from a brand, it delights them. If your objective is to retain your most loyal customers, you might want to keep your greatest prize for them to win.
• Bring in more business and generate leads. Favour trial or ideal subscribers (buyer persona) by giving them an unexpected prize. This is definitely an effective tactic to improve your chances of converting them to paid subscribers.
• Offer the right prize. Some would argue that the most important part of a contest is the prize! It is thus a good idea to make them highly relevant to your target audiences. Users will be more likely to engage if you woo them with a prize they are interested in. For instance:
  • a spa day for your health, beauty and wellness magazine subscribers,
  • a cooking class for your food and recipe website readers,
  • “diapers for a year” for the audience of your parenting section.

How does it work?

1. Token setup

1. The first thing you must do is compute a token for each participation (based on CRM or CDP data, for instance). The data contained in this token will allow Qualifio to know whether a participant can win something and/or what they can win.
2. You should be able to share the token with Qualifio on campaign initialisation. This can be done either by passing the JWT in the URL or by sharing it via JavaScript: Sharing of secure tokens.

From a technical perspective, external information will be shared through a signed JSON Web Token (JWS) you generate following the standard structure defined by Qualifio. We explain this below.

Required claims

The token contains a series of statements (“claims”, which are basically name/value pairs) about an entity (the user). Qualifio requires the sub, exp and campaignId claims to be included in the token for it to be considered valid.

For more information on these claims, see What is a secure token and how does it work?

Additional claims

You can provide an additional claim named “gift” within the token, which contains two pieces of information:

• gift.cw is used to allow winning in a campaign. It has two possible values: true and false (Boolean).
  
  • If gift.cw is equal to true, the user can win.
  • If gift.cw is equal to false, the user cannot win.
• gift.label is the name of the prize the participant can win, based on their specific status in your applications.

Use of these claims is optional and follows the rules below:

Code example

This is what the payload of the token received by Qualifio should look like:

{
 "sub": "1234567890",
 "iat": 1619102989,
 "exp": 1619101489,
 "iss": "ABC Company",
 "campaignId": "123456",
 "gift": {
   "cw": true,
   "label": "five-night getaway to Lanzarote"
 }
}

2. Using the secure token in your campaign

Note: The ability to integrate your token into Qualifio is not automatically enabled for your account. If this is your first time using this integration, you will have to enable it and set it up – or contact your account Admin so they can do so. You will only need to do this once. Check this page’s “Use the secure token in Qualifio” section to integrate your token.

Manage prizes

Please note that you have the responsibility to share a number of tokens with gift.cw: true that doesn’t exceed the number of prizes set in your campaign.

Regardless of the value of the gift.cw field in the token, a prize will only be allocated if there are prizes available in the campaign. If you choose to distribute more winning tokens than the number of available prizes, those will be allocated on a first-come-first-served basis.

When your campaign ends, you will get the opportunity to choose winners for the remaining prizes (if any) by going to the Winners tab in your campaign statistics. (This is not applicable to instant win contests, in which prizes are won instantly.)

Personalise your content with the right prize name

With dynamic variables, you can show personalised content to your participants based on the gift.label claim value in your token.

Once your secure token is ready, go to your campaign and click on the Dynamic variables in any rich text module in the campaign editor. When you do this, you’ll see a few options to choose from. Select the Secure token > Name of the prize variable:

Below is a preview of what happens when the name of the prize (gift.label) gets shared with Qualifio on page load:

And there you have it! You now know how to access external information to pass prize information to Qualifio.

For more help

If you need more help, check out these support and learning resources:

• Learn more about the standard ways you can choose contest winners, check out this guide on drawing winners.
• Share all support issues via our support ticket system.
• Does this feature just not quite fit what you’re looking to do with Qualifio? Let us know via the Suggest a feature form! We want to hear what kind of magical functionality you need.