Set up your Riddle quiz leaderboard

We are super excited to introduce our quiz leaderboard for Riddle’s quiz maker!

(Updated May 21, 2020 – quiz leaderboards are now available as part of our quiz maker plug-in on WordPress. No coding required!)

Part of our Pro and Team plans – our quiz leaderboard will let you set up quiz competitions. It’s a powerful tool to get your audience to keep coming back (and challenging their friends).

Run daily, weekly, or monthly quiz contests – it’s a powerful audience retention mechanic.

Want to create an ‘always new’ quiz contest? Quiz leaderboards work especially well with our auto-quiz format. Display new questions every hour/day/week/month – and challenge your audience to come back for the latest round of questions.

Quiz leaderboard – key info

  •  Pro/Team feature
  • Each quiz will require a lead form – so each quiz taker can enter
  • The leaderboard will shown at the end of the quiz – after the lead form.
  • Please note – the leaderboard will also replace the standard quiz result page for each Riddle type.

Basic setup

(This is our 1st version – so it requires a bit of PHP coding skills to set up. Fear not – future versions will be much more intuitive.)

  1. Download these files from GitHub (https://github.com/riddle-com/custom-riddle-leaderboards).
  2. Create a secret key for your leaderboard – to prevent anyone else from posting to it.
    • Head to /app/config/RiddleConfig.php and take the secret you just generated and replace “false” with it.
    • The secret must be put within single quotes (e.g.: ‘R2UMSHOnnhrR6he1’)

    • Upload all the files to your website via FTP.
    • It is super/uber/muy important that your site is secured with an SSL certificate, so that you can access it via https://.
  3. Create a quiz on riddle.com (the easy part!)
  4. In your quiz, set up the lead form in the ‘collect leads’ step.
  5. Select the fields you want to collect – and use in your leaderboard.
    • A field with the ID “Email” is required.
    • A field with the ID “nickname” is also required.
  6. Disable the skip option in the lead form.
  7. Head to the Quiz result landing page section of the ‘Advanced’ step: 
    • In the URL field enter a URL of the following format:
      https://yourwebsite.com/file-path-to-your-files/riddle-webhook.php?secret=yoursecret

IMPT: Please don’t forget to activate the quiz landing page like in the image above. 

You can publish your quiz now and your leaderboard will work perfectly.

However – you can also customize the heck out of it.

For example, the header image is a black cat. (Long story but our devs like adding cats to tease/annoy our CEO Boris – who’s more a dog person.)

  • Everything that is customizable is located in the folder /app.
  • You can also edit the /web folder to customize the CSS-styling of the leaderboard.
  • Please do not touch the /src folder since it is crucial for the leaderboard to work. 
  • We added comments in the code – highlighting ways you can customize your leaderboard.

Your quiz leaderboard – advanced customization

Our team of ace devs built the quiz leaderboard to give you maximum flexibility to suit your needs.

And don’t worry, it’s not as hard as it looks.

Any questions? Always feel free to ask us on support chat – we’re super quick to respond. πŸ™‚


Sample use cases

You can: 

  1. Control the heading and introduction of your quiz leaderboard
  2. Choose the ‘better-than’ percentage
  3. Change your ‘missed-place’ point
  4. Change the leaderboard table structure/layout
  5. Customize other settings

Change the heading and introduction text of your board

/app/views/leaderboard-module.php on line 31

  • In general, you can change all the white text you see when looking at the code.
  • This is just a basic example – you can customize the introduction text your quiz takers would see.

Change the ‘better-than’ percentage

/app/views/leaderboard-module.php on line 23

  • You can set the lowest ‘comparison’ percentage possible a quiz taker can see.
  • For example, imagine Bob scores 1/15. That might only beat 5% of the other quiz takers.
  • However, that’s a bit soul-crushing as a user. To keep the Bobs of the world Bob happy – you can set the lowest % a user will ever see.
  • The default is 20% – but you can set it whatever you like.
  • You can simply edit the number following “min”.

Customize the success message

Want to customize the message that each quiz taker will see? (e.g. “You’re better than XX% of people who took this quiz. Congratulations!”)

Boom – we got you covered.

Just make sure the variable “%%PERCENTAGE%%%” stays the way it is. It holds the value you specified above.

This code produces the following output: 


Choose your ‘missed-place’ breaking point

/app/views/leaderboard-module.php on line 80

You can also show your quiz takers how far they scored – from a specified top-range of quiz takers (e.g. “You missed the top 10 by 22%!”).

Users will not see this block if they’re scored higher than the break point (in this case in the top 10).

This is useful – it shows each quiz taker how close they were to the top positions.

You can change the number and the corresponding text here:


Add the leaderboard column names

/app/views/leaderboard-module.php on line 36

Right, so you’ve set up your quiz lead form with the information you want to collect.

  • Now it’s time to customize what your audience will see in the quiz leaderboard.
  • In our example, we have been using the ranking number (“#”) and identified the entries by email and name.
  • You could also identify users by the nickname they give (“BobTheGreat”).

Add another table column

Add another table header (e.g. the travel destination of your quiz taker) by adding this line somewhere within the <tr> tags: <th>Destination</th>

  • Each field must already be included in your quiz lead form.
  • Any type of form field will work – such as a dropdown in our example.
  • Change the entries the way you want it.
  • Make note of the ID-text in the bottom of the editing popup (see below).
  • Delete the ##### in the ID tag (e.g. #19227: Destination)
  • You can also change the text behind the ID to something more memorable.
  • IMPT: This field is case sensitive. The value is passed directly to the quiz leaderboard. Make sure the entry here and in your setup are exactly the same (they are also case-sensitive => “nickname” is not the same as “Nickname”).
  • Click save in your lead form to save your changes.

These settings will produce the following field:

In this example, we are using a Field ID ‘Destination’. This will also be the name of the field we will specify in our PHP-code.

So we’ll only need to insert this to your code now. You’ll do this by adding a new row to this file:

/app/views/leaderboard-module.php on line 4

Just add this line within the single quotes:
<td>{ lead2.Destination.value }</td>


Wait – you want even more customization?

Okay – buckle up. Let’s see what else you can customize:

  • Amount of entries shown on the board
    • /app/views/leaderboard-module.php on line 47
    • By default, we show the first 5 users on top of the board. But you could also show up to 1,000 if you want.
    • Simply edit the range number in the brackets [1, 5].

  • Ranking of the quiz taker on the board.
    • /app/views/leaderboard-module.php on line 56
    • By default, the board has been set to show one entry before and after the ranking of the current user.
    • You can edit this by changing the ‘range’.

  • Add a featured image in the leaderboard
    • Our devs love cats… and our founder Boris doesn’t. πŸ˜‰
    • You can change the black cat in the leaderboard here: /app/views/landingpage.php on line 5. 
    • Just specify a new image URL there.

Those are just a few of the features you can customize. Check out our comments in the code to see further customization options.

Whew! All finished – this is a work in progress.

Got ideas on how we can make this quiz leaderboard even better?

Just drop us a line in the support chat on this blog or riddle.com, or send a note to hello@riddle.com.