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

Tabata Vossen -

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 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

Please note: This step is intended for developers. We offer this feature and the structure expected but don’t provide support for code customisation to develop the token itself.
  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:

  gift.label is present gift.label is not present
gift.cw:true

Participant may win a given prize.

Participant may win any prize.
gift.cw: false Participant may not win (gift.label is ignored.) Participant may not win.
gift.cw is not present Participant may win a given prize.

Contest runs in a standard way.

! Note A participant may or may not win a prize based on prize availability. In instant win contests, it will depend on the schedule of the prize calendar. In other types of contests, it will simply depend on whether there’s a prize available to be won in the campaign.

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:Schermafbeelding_2022-01-28_om_15.53.54.png

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

Schermafbeelding_2022-01-28_om_16.00.50.png

Please note: The prize name passed in the token overwrites the prize name set up in Qualifio. For instance, if your token tells Qualifio that a participant can win “a new barbecue”, that is the value that will be returned and displayed for the participant – even if no such prize was created in your campaign.

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:

Can’t find the answer you need?

Send us a question and connect with an expert to get personal assistance.

Contact support

Vous ne trouvez pas les réponses que vous cherchez ?

Nous sommes là pour vous aider. Envoyez-nous une demande en direct !

Contacter le support
helpcenter experts