Documentation for developers

Sommaire

I. Overview on quiz embedding

Quizity allows you to embed a quiz on your own website, if his author allowed it.

Quiz embedding requires you to insert a javascript code in the HTML source of your web page. The system is 100% javascript, requires no iFrames and gives the results of the quiz without any redirection.

With the same technique, you can also embed the quiz ranking on the same page. You will find many options to customize this quiz ranking.

Examples of quiz embedding can be found on Quizity's blog and on Allocine.fr.

Reminder on a few points of the terms of use : you may not modify the layout of the quiz beyond the options offered on this page, nor extract the quiz content. This includes that you should always display the name of the author correctly and not modify/override the javascript code.

II. Minimal code to embed a quiz

The minimal code to integrate a quiz on your page is the following :
<div id="qz_div">
	The <a id="qz_link" href="https://en.quizity.com" title="XXX" target="_blank">quiz</a> is now loading from Quizity.com, the website to <a href="https://en.quizity.com/create/quiz/0/">create a quiz</a>, please wait...
</div>

<script type="text/javascript" src="https://staticp.quizity.com/js/embed_quiz.js"></script>
Here, XXX represents the identifier of a quiz. You will find this identifier in the URL of a quiz. For example the quiz on this page :
https://en.quizity.com/play/quiz/999/quiz_on_American_history has the identifier 999.

However we advise you to add your referrer identifier to that code (cf section IV). This will allow you to add an internal quiz ranking to your website, even if you do not integrate that right now, and get statistics about the games that were played on your website.

III. Minimal code to display the ranking

You just have to add the following line in the HTML source code of your page :
<div id="qz_ranking"></div>
For example, here is the full code that will allow you to embed a quiz and its ranking afterwards :
<div id="qz_div">
	<a id="qz_link" href="XXXXXX" target="_blank">quiz</a> is now loading from Quizity.com, the website to <a href="https://en.quizity.com/create/quiz/0/">create a quiz</a>, please wait...
</div>

<div id="qz_ranking"></div>

<script type="text/javascript" src="https://staticp.quizity.com/js/embed_quiz.js"></script>
Notice : you can display the ranking anywhere in your page, just to put the line where it suits you.

IV. Options

Adding the options tag

To set options available for embedding, you have to insert the following tag in the HTML source code of your page :
<script>
	
	var quizity = {};
	
	Option1;
	Option2;
	Option3;
	etc.
	
</script>
If you omit an option, its default value will apply.

Here are the currently available options :

The referrer identifier

quizity.rid = XXX;
Default value null
The referrer identifier is a unique number attributed by Quizity to each of its members.
Its allows us to know which players played on your site.
It will be used to give you statistics about the number of people who played on your site, and also to build a local quiz ranking for you site (cf. the ranking.local option).


The interface language

quizity.hl = "XX";
The possible values are en and fr. Default value : en
This options defines the language that will be used in the quiz interface and in the quiz ranking. Currently, English and French are available.

The interface color

quizity.theme = X;
The possible values are 1 and 2. Default value : 1
If your website uses a light background and a dark font, use 1. If it is the opposite, use 2.

Display the quiz under white label

quizity.whiteLabel = X;
The possible values are true and false. Default value : false
This option is available only in our service offer to professionals and will not work without activation on our end. Please contact us for further information.
This option hides the "Powered by Quizity" banner at the start of the quiz and when the results are shown.
Please remember that the use of this option does not allow the display of a ranking.
This option is not available in iFrame mode.

Reload the page during the quiz

quizity.reloadPage = X;
The possible values are 1 and 2. Default value : 1
Quizity's default behavior is to let the player play a quiz and get his results without ever having to leave or reload the page. However, some websites may wish to reload the page during the game to generate more Page Views. With this option, the page will be reloaded at each page break and before the results are given.
This option will take effect in all modern browsers (this excludes IE6 and IE7).
This option is not available in iFrame mode.
This option is available only in our service offer to professionals and will not work without activation on our end. Please contact us for further information.

Reload the page without modifying its URL

quizity.preserveQueryString = X;
The possible values are true and false. Default value : false
If the previous "reloadPage" option is enabled, by default the quiz adds a GET variable qz_page=2, qz_page=3, etc. everytime the page is reloaded.
The only use of this is to let you monitor your users' activity on the different quiz pages through your logs.
To keep the quiz from modifying the page URL when reloading, enable this option.

Disable the use of the anchor

quizity.preserveHash = X;
The possible values are true and false. Default value : false
We use an anchor to let the player come back directly at the top of the quiz when he starts a new page of questions or gets his results. However, a few websites sometimes use the anchor system (the URL hash part) to work. If this is your case and that bugs happen, you may want to enable this option.

Modify the ranking options

quizity.ranking = {};
If you wish to use any of the options described below, you must first include this line.

Disable the quiz ranking or change the moment it appears

quizity.ranking.display = X;
The possible values are 0, 1 or 2. Default value : 1
If you added the line of HTML required for ranking display (cf. section III) and that this option is set to 1, the ranking will be displayed as soon as the visitors arrive on the page.
If you set this option to 2, the ranking will be displayed after the player has finished the quiz.
If you set this option to 0, the ranking will not be displayed.

Display a local ranking

quizity.ranking.local = XXXXX;
The possible values are true or false. Default value : false
A local ranking is a ranking internal to your website, it will display only the names of members who played from your website.
This implies that the players who discover the quiz directly on Quizity.com will not be displayed.
You also have to set the referrer identifier option to make this work.

Ranking sorted by score or by chronological order

quizity.ranking.criteria = X;
The possible values are 1 or 2. Default value : 1
Set this option to 1 to sort players by descending scores.
Set this option to 2 to display players by antichronological order, that is to say latest players first.

Maximal number of lines in the ranking

quizity.ranking.maxPlayers = XX;
The possible values of this options are an integer between 1 and 20. Default value : 10
This option sets the maximum number of lines in the ranking board.

Hide the empty lines of the ranking

quizity.ranking.noEmptyLines = XXXXX;
The possible values are true or false. Default value : false
Imagine that the maximum number of lines in the ranking (cf. previous option) is set to 10.
If only 6 players played the quiz, 4 lines will not be filled.
If you set this option to false, the board will display 10 lines, 4 of which will be empty.
If you set this option to true, the board will only display the 6 filled lines.

Hide the whole ranking if it is empty

quizity.ranking.hideIfEmpty = XXXXX;
The possible values are true or false. Default value : false
If this option is set to true, the ranking will not be displayed at all if it is empty.

Hide a ranking widget on pages that do not display a quiz

quizity.ranking.container = "XXXXX";
The value of this option is the ID attribute of an HTML tag of your choice that contains the ranking. The default value is qz_ranking_container
This option is used to hide an HTML block that contains the quiz ranking on pages that do not display a quiz.

Example : you have a single template for all pages of your blog. You wish to display the ranking in a nice box in the right column of your blog. It looks like this :



The problem is, the ranking block is also displayed on pages which do not have a quiz and it is empty :



Let's say that the HTML code of the block is the following : 
<div class="right_block">
	<h1>Quiz ranking</h1>
	<div id="qz_ranking"></div>
</div>
The solution is to make this quiz invisible with style="display:none" and give it a specific ID, and the quiz itself will make it reappear if a ranking is to be displayed. It is this ID that you have to define in the option. By default, it is qz_ranking_container.

Example of a code that would make this happen : 
<div id="qz_ranking_container" class="right_block" style="display:none">
	<h1>Quiz ranking</h1>
	<div id="qz_ranking"></div>
</div>
or another way to reach the same result : 
<div id="qz_ranking_container" style="display:none">
	<div class="right_block">
		<h1>Quiz ranking</h1>
		<div id="qz_ranking"></div>
	</div>
</div>
Notice : do not try to apply CSS rules on IDs #qz_ranking_container and #qz_ranking because they will be reset when the quiz loads.If need be, please use CSS classes or use the style="" tag.

Customize the design of the ranking with CSS

quizity.ranking.customCSS = XXXXX;
The possible values are true, false or the path to a CSS file. Default value : false
You can almost entirely customize the look of the ranking so it can match with the design of your site. You just have to modify the CSS values which exposed at the bottom of this page.
If this option is set to false, the default design will be applied.
If this option is set to true, Quizity considers that you included the modified CSS in the page yourself.
If the option is a string which is the path to your CSS file, Quizity will include that file in the page for you.

Example : 
quizity.ranking.customCSS = "/css/quizity_classement.css";
Notice : if you give a path to a CSS file, we suggest you host the file yourself. Using a CSS file on which you do not have total control may present a security risk.

Hide the ranking title

quizity.ranking.skipHeader = XXXXX;
Possible values are true or false. Default value : false
By default, the first line of the ranking displays "Quiz ranking" or "The played the quiz".
If you set this option to true, this title will not be displayed.

Display links to the profile pages

quizity.ranking.links = XXXXX;
Possible values are true or false. Default value : false
If you set this option to true, the name of players will be clickable and will open a new window on their Quizity profile page.

V. Recap of the complete embed code

With comments : 
<div id="qz_div">
	<a id="qz_link" href="XXXXXXXXXXXXXXXX" target="_blank">quiz</a> is now loading from Quizity.com, the website to <a href="https://en.quizity.com/create/quiz/0/">create a quiz</a>, please wait...
</div>
	
<div id="qz_ranking_container" style="display: none;">
	<div id="qz_ranking"></div>
</div>

<script>
	
	//This line is compulsory to use any of the following ranking options
	var quizity = {};
	
	//Your referrer id that was given to you by Quizity.com (cf. the developers page). This unique number is used to determine wich players played from your website (to create a local ranking + draw statistics for you). Default : null
	quizity.rid = null;
	//Language used to display instructions in the interface. Default : "en"
	quizity.hl = "en";
	//Visual theme of the interface. Use 1 if the background of your website is light, 2 if it is black. Default : 1
	quizity.theme = 1;
	//Display the quiz under white label. Default: false
	quizity.whiteLabel = false;
	//Reload the page during the quiz. Default: false
	quizity.reloadPage = false;
	//Reload the page without modifying its URL. Default: false
	quizity.preserveQueryString = false;
	//Disable the use of an anchor during the quiz. Default: false
	quizity.preserveHash = false;
	
	//This line is mandatory if you wish to display the ranking
	quizity.ranking = {};
	//Display the ranking. Use 0 for "never", 1 for "always", 2 for "after the player played the quiz". Default : 1
	quizity.ranking.display = 1;
	//Display only the names of the players who played on your website. Defaut : false
	quizity.ranking.local = false;
	//Sort criteria for the ranking. Use 1 to sort players by descending score, 2 for antichronological order (displays latest players). Default : 1
	quizity.ranking.criteria = 1;
	//The maximal number of lines in the ranking board. Currently limited to 20. Default : 10
	quizity.ranking.maxPlayers = 10;
	//Do not display the ranking at all if it is empty. Default : false
	quizity.ranking.hideIfEmpty = false;
	//If you wish to specify the ID of the HTML tag that contains the ranking widget. Cf Quizity.com to understand how it can be used. Default : "qz_ranking_container"
	quizity.ranking.container = "qz_ranking_container";
	//Do not display empty lines in the ranking. Default : false
	quizity.ranking.noEmptyLines = false;
	//Use you own CSS rules for the ranking design. Set to true, false or a path to a CSS file. Cf Quizity.com. Default : false
	quizity.ranking.customCSS = false;
	//Skip the title line of the ranking. Default : false
	quizity.ranking.skipHeader = false;
	//Display clickable links on players' names, that will open a new window on the player's Quizity profile page. Default : false
	quizity.ranking.links = false;

</script>

<script type="text/javascript" src="https://staticp.quizity.com/js/embed_quiz.js"></script>
Compressed on a single line without comments (namely required on Blogger to avoid bugs) : 
<div id="qz_div">The <a id="qz_link" href="https://en.quizity.com" title="XXX" target="_blank">quiz</a> is now loading from Quizity.com, the website to <a href="https://en.quizity.com/create/quiz/0/">create a quiz</a>, please wait...</div><div id="qz_ranking_container" style="display: none;"><div id="qz_ranking"></div></div><script>var quizity={};quizity.rid=1;quizity.hl="en";quizity.theme=1;quizity.preserveHash=false;quizity.reloadPage=false;quizity.preserveQueryString=false; quizity.whiteLabel=false;quizity.ranking={};quizity.ranking.display=1;quizity.ranking.local=false; quizity.ranking.criteria=1;quizity.ranking.maxPlayers=10;quizity.ranking.hideIfEmpty=false; quizity.ranking.container="qz_ranking_container";quizity.ranking.noEmptyLines=false;quizity.ranking.customCSS=false; quizity.ranking.skipHeader=false;quizity.ranking.links=false;</script><script type="text/javascript" src="https://staticp.quizity.com/js/embed_quiz.js"></script>

VI. Appendice

Embed with iFrame

Embedding with an iFrame allows you to integrate quizes on websites that allow iFrames but not Javascript.

iFrame embed is compatible with more websites but on the other hand, it has drawbacks which do not exist in the Javascript method. iFrame embed is less natural and globally less pleasant to visitors.

For example, the size, color and type of the default font used for quizes are not the same as on your website.
Another disadvantage is that the quiz is "trapped" in a frame which has fixed height and width, thus requiring the visitor to scroll in the frame to browse questions.

To circumvent these drawbacks as much as possible, we allow you to include one or more CSS files in the iFrame in order to customize a few design elements. The paths need to be passed as url-encoded GET parameters in the iFrame address with the names "css0", "css1", "css2", etc.

You can also provide CSS properties directly in a url-encoded string passed as a GET parameter called "scss".

Since iFrame embeds have a heavier support cost for us, we reserve the option of adding custom CSS properties for websites which are kind enough to maintain backlinks to Quizity.

Beyond these considerations, the different options described on this page for Javascript embed also apply for iFrame apply. All you need to do is transmit the configuration parameters in the form of a JSON url-encoded string.

If the address of the iFrame could be not concatenated and not url-encoded, a quiz iFrame embed code would look like this :

<iframe
	height = "550"
	width = "550"
	src = "https://iframe.quizity.com/embed_iframe.php?
		ct = quiz
		&cid = xxx				//unique quiz identifier
		&jsconfig = {
			"rid" : xxx,		//referrer identifier
			"hl" : "en",
			"ranking" : {
				"display" : 2,
				"local" : true,
				"maxPlayers" : 20
			}
		}
		&scss = body { color: white; }
		&css0 = http://www.example.com/style.css
		&css1 = http://www.example.com/style2.css
	"
	frameborder = "0"
	style = "border: none; margin: 10px 0;"
	allowtransparency = "true">
	The <a id="qz_link" href="https://en.quizity.com" target="_blank">quiz</a> is now loading from Quizity.com, the website to <a href="https://en.quizity.com/create/quiz/0/">create a quiz</a>, please wait...
</iframe>

Explanations on how players are added to rankings

If the visitor plays on your site and has an active session on Quizity at the same time, he is immediatly added to the ranking with no need to go to Quizity !

But even if the player is not connected to Quizity, no problem. He just has to go to Quizity after the game and connect or register, and voilà ! His game is immediatly saved and added to your local ranking and in the general ranking. The points he won on your site are even retrospectively added to his account !

Allow users on a forum to post quizes

Our code makes it extremely easy to build a BBcode to allow users to post quizes. The only variable element of the embed code is the identifier of the quiz.

For example, on the forum of Warriorlabs, a member just has to write this to post a quiz in his article : 
Play this quiz: [quiz]https://en.quizity.com/play.quiz/xxx/yyyyyyyy[/quiz]

CSS stylesheets of the ranking

To help you understand how to modify the CSS rules of the ranking, here is the structure of a 3 lines ranking, the last one being empty : 
<div id="qz_ranking_container" style="display: none;">
	<div id="qz_ranking">
		<div class="qz_ranking_header">Quiz ranking</div>
		<div class="qz_line qz_line_even">
			<div class="qz_lc">
				<span class="qz_rank">1.</span>
				<span class="qz_login">Marie</span>
				<span class="qz_score">100%</span>
			</div>
		</div>
		<div class="qz_line qz_line_odd">
			<div class="qz_lc">
				<span class="qz_rank">2.</span>
				<span class="qz_login">Martin</span>
				<span class="qz_score">90%</span>
			</div>
		</div>
		<div class="qz_line qz_line_even">
			<div class="qz_lc">
				<span class="qz_rank">3.</span>
				<span class="qz_login"> </span>
				<span class="qz_score"></span>
			</div>
		</div>
		<div class="qz_line qz_line_even">
			<a href="XXX" target="_blank">Powered by Quizity.com</a>
		</div>
	</div>
</div>
And here are the default CSS rules of the ranking : 
.qz_header {
	font-size: 18px;
	font-weight: bold;
	padding: 5px 0;
	text-align: center;
}

.qz_lc {
	position: relative;
}

.qz_line {
	height: 20px;
	padding: 5px 10px;
}

.qz_line_even {
	
}

.qz_line_odd {
	background: #e2e1e1;
}

.qz_login {
	left: 30px;
	position: relative;
}

.qz_rank {
	font-weight: bold;
	left: 0;
	position: absolute;
	top: 0;
}

.qz_score {
	position: absolute;
	right: 0;
	top: 0;
}
Just copy these rules in a file, modify them as you wish and include the file in your page. The only constraint is that you may not prevent the last line of the ranking that refers to Quizity from being displayed.

Notice : as stated before, CSS rules applied on #qz_ranking or #qz_ranking_container will not be taken into account. You had rather set CSS classes on the corresponding HTML tags if need be.

Send us your feedback !

Is everything working fine ? Do you need help ? Do you wish for more functionalities ?

Tell us everything by writing at . Thank you !

Cookies and privacy

By browsing this website, you accept our cookie and privacy policy explained here.