Custom participation limit

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 limits
2. How to limit users who can participate?
   • Generate a JSON Web Token (JWT)
   • Technical requirements
   • Structure of the token
   • Share the token with Qualifio
3. Integrate the token in Qualifio
4. Enable the custom limit 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 limits.

Use cases for custom participation limits

Custom participation limits 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 limits are useful:

• One use case for custom participation limits 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 limit 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 limit based on the collected 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 limit. The idea behind this token is to provide you with a standardised and secure way of passing external information to a Qualifio campaign.

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 limit. 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 some claims to be included in the token for it to be considered valid:

• sub
• exp
• campaignId (Find your campaign ID)

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

Additional claims

For the custom participation limit, 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.canPlay”: true

“limit.canPlay”: false

Code example

In accordance with the open standard (RFC-7519), here is an example payload:

{
 "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 limit 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.

Step 2: Click on the Individual limit drop-down menu under the Limits section.

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

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:

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:

• Learn more about the standard ways you can limit participation, check out this guide on setting individual and collective limits.
• 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.