Custom participation limitation

Tabata Vossen -

Qualifio enables you to limit participations based on custom actions. In this tutorial, we’re going to look at how you can fetch external information to define in real time who can participate in your campaign.

Here’s a table of contents if you want to jump ahead:

  1. Use cases for custom participation limitations
  2. How to limit users who can participate?
  3. Integrate the token in Qualifio
  4. Enable the custom limitation in your campaign

Would you rather want to learn how to cap the number of participations submitted in your campaign? In this article, we show you how to use Qualifio’s individual and collective limitations.

Use cases for custom participation limitations

Custom participation limitations rely on external information and are therefore very flexible. This feature extends Qualifio’s capabilities by adding custom options for limiting participation in a campaign. Here are some scenarios where custom participation limitations are useful:

  • One use case for custom participation limitations is found in “purchase to enter” contests. Let’s say your objective is to encourage customers to spend more:
    • Users might be allowed to participate but they must have spent, say, at least €50 in your store over the last four weeks.
    • The limitation could also be one time per €20 spent (they get one participation per purchase of that amount). In that case, you’d increment the number of allowed participations with each purchase.
  • Another way you can control the number of participations of an individual is by setting a limitation based on loyalty points. For instance, users might have to collect a minimum number of bonus points before they are allowed to participate.
  • Finally, you can also restrict a campaign to paying subscribers only. If your objective is to create loyal subscribers and make free users pay for a membership, one of the perks you can offer them is exclusive access to premium campaigns. Only subscribers paying you will be eligible to participate.

How do you set this up? Let’s find out 😉

How to limit users who can participate?

Now that you know why you may want to limit which users may take part in your campaign, let’s check out exactly how to do it with Qualifio.

You can use a JSON Web Token to define a custom participation limitation. The idea behind this token is to provide you with a standardised and secure way of passing external information to a Qualifio campaign.

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.

Generate a JSON Web Token (JWT)

The first thing you must do is dynamically generate a token for each participation containing a minimal set of data allowing Qualifio to grant or deny campaign access.

Technical requirements

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.

Note: You have the responsibility to share all necessary information for the participation limitation. Need help? We explain this below.

Structure of the JSON Web Token (JWT)

The token contains a series of statements (“claims”, which are basically name/value pairs) about an entity (the user). Let’s break down the different parts.

Required claims

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

For the custom participation limitation, you can provide the following additional claims in the token payload:

limit
This piece of information states whether a user is allowed to take part in a campaign and/or how many times they’re allowed to do so. The JSON object contains two claims:

  • limit.canPlay is used to allow access to a campaign. It has two possible values: true and false (Boolean). If limit.canPlay returns true, the user can participate. If it returns false, the user cannot participate.
  • limit.nb represents the number of participations allowed for this participant, based on their specific status in your applications. It’s your responsibility to define the access rules and compute them to share this number in the token.

 

  "limit.nb" is present "limit.nb" is not present
“limit.canPlay”: true
The user can participate a given number of times. The user can participate, no matter whether they have already participated or not.
“limit.canPlay”: false
The user cannot participate. The user cannot participate.
(We ignore the limit.nb subclaim.)
"limit.canPlay" is not present The user can participate a given number of times. The user cannot participate.

Code example

In accordance with the open standard (RFC-7519), here is an example payload. 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,
"limit": {
"canPlay": true,
"nb": 4
}
}

If you’re having any issues setting this up, please create a support request.

Share the token with Qualifio

You should be able to share the token with Qualifio on page load. This can be done either by passing the JWT in the URL or by sharing it via JavaScript: Sharing of secure tokens.

Integrate the token with Qualifio

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.

Enable the custom limitation in your campaign

Step 1: Once your secure token is ready, go to Campaigns > Settings step of your campaign. This will bring up the different settings you can configure for your campaign.

Screenshot_2021-04-15_at_17.29.09.png

Step 2: Click on the Individual limitation drop-down menu under the Limit the number of participants section.

Screenshot_2021-04-15_at_17.30.25.png

When you do this, you’ll see a few options to choose from. Scroll down and select the Custom limitation one:

Screenshot_2021-05-17_at_17.59.45.png

Step 3: Add a message in case they try to participate!

Below is a preview of what happens if you try to participate and do not meet the criteria:

qualifio-purchase-to-enter-contest.png

Step 4: Click Save.

And there you have it! You now know how to access external information to limit participation in Qualifio.

For more help

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