Documentation pour les développeurs

Sommaire

I. Introduction à l'intégration de quiz

Quizity vous permet d'exporter un quiz sur votre propre site web, si son auteur l'a autorisé.

L'intégration d'un quiz exige que vous insériez un code javascript dans la source HTML de votre page web. Le système est 100% javascript, ne requiert pas d'iFrame et donne les résultats du quiz à vos visiteurs sans les rediriger.

Par le même mécanisme, il est aussi possible d'intégrer sur la même page de votre site un classement relatif au quiz. Il existe de nombreuses options pour personnaliser ce classement.

Des exemples d'intégration sont disponibles sur le blog de Quizity et sur Allocine.fr.

Rappel de quelques points des conditions d'utilisation du service : vous n'êtes pas autorisé à modifier l'affichage des quiz au-delà de ce qui est décrit sur cette page, ni à extraire le contenu des quiz. Cela inclut notamment l'obligation d'afficher le nom de l'auteur et de ne pas modifier/surcharger les liens ou le code javascript.

II. Le code minimal pour intégrer un quiz

Le code minimal à intégrer sur votre site est le suivant :
<div id="qz_div">
	Le <a id="qz_link" href="https://fr.quizity.com" title="XXX" target="_blank">quiz</a> est en train de charger depuis Quizity.com, le site pour <a href="https://fr.quizity.com/create/quiz/0/">créer un quiz</a>, veuillez patienter...
</div>

<script type="text/javascript" src="https://staticp.quizity.com/js/embed_quiz.js"></script>
Ici, XXX représente l'identifiant d'un quiz. Vous trouverez cet identifiant dans l'URL du quiz. Par exemple le quiz qui est sur la page :
https://fr.quizity.com/play/quiz/999/quiz_de_culture_G porte l'identifiant 999.

Nous vous conseillons néanmoins de rajouter à ce code votre identifiant de référent (cf section IV). Cela vous permettra de construire un classement interne à votre site, même si vous n'intégrez pas ce classement tout de suite, et de disposer de statistiques sur les parties qui auront été jouées sur votre site.

III. Le code minimal pour intégrer un classement

Vous devez simplement rajouter la ligne suivante dans la source HTML de votre page :
<div id="qz_ranking"></div>
Par exemple, voici le code complet permettant d'intégrer un quiz et son classement général juste après :
<div id="qz_div">
	<a id="qz_link" href="XXXXXX" target="_blank">quiz</a> est en train de charger depuis Quizity.com, le site pour <a href="https://fr.quizity.com/create/quiz/0/">créer un quiz</a>, veuillez patienter...
</div>

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

<script type="text/javascript" src="https://staticp.quizity.com/js/embed_quiz.js"></script>
Remarque : vous pouvez positionner le classement où vous voulez dans la page, il suffit d'ajouter la ligne où vous le souhaitez.

IV. Les options

Ajout de la balise des options

Pour configurer les options disponibles à l'intégration, vous devez rajouter la balise suivante dans la source HTML de votre page :
<script>
	
	var quizity = {};
	
	Option1;
	Option2;
	Option3;
	etc.
	
</script>
Le fait de ne pas mentionner une option fait que sa valeur pas défaut sera utilisée.

Voici la liste des options actuellement disponibles :

L'identifiant de référent (referrer id)

quizity.rid = XXX;
Valeur par défaut : null
L'identifiant de référent est un numéro unique attribué par Quizity à chacun de ses membres.
Il permet de savoir quels sont les joueurs qui ont joué depuis votre site web.
Il sera utilisé pour vous donner des statistiques sur le nombre de personnes ayant joué sur votre site, ainsi que pour la construction d'un classement interne à votre site (cf l'option ranking.local).


La langue de l'interface

quizity.hl = "XX";
Les valeurs possibles sont fr et en. Valeur par défaut : en
Cette option définit la langue utilisée dans l'interface du quiz et du classement. Pour l'instant, seuls le français et l'anglais sont disponibles.

Couleur de l'interface

quizity.theme = X;
Les valeurs possibles sont 1 et 2. Valeur par défaut : 1
Si votre site utilise un fond clair et une écriture sombre, utilisez 1. Si c'est l'inverse, utilisez 2.

Afficher le quiz en marque blanche

quizity.whiteLabel = X;
Les valeurs possibles sont true et false. Valeur par défaut : false
Cette option est disponible uniquement dans notre offre aux professionnels et ne fonctionnera pas sans activation de notre part. Veuillez nous contacter pour plus d'information.
Cette option a pour effet de masquer le bandeau "Propulsé par Quizity" au début du quiz et au moment des resultats.
Notez que l'utilisation de cette option enlève la possibilité d'avoir un classement des joueurs.
Cette option n'est pas disponible en mode iFrame.

Recharger la page au cours du quiz

quizity.reloadPage = X;
Les valeurs possibles sont true et false. Valeur par défaut : false
Cette option est disponible uniquement dans notre offre aux professionnels et ne fonctionnera pas sans activation de notre part. Veuillez nous contacter pour plus d'information.
Le comportement par défaut de Quizity est de permettre au joueur de jouer à un quiz et d'obtenir ses résultats sans jamais avoir à quitter ou recharger la page. Néanmoins, certains sites souhaitent des rechargements de page au cours de la partie afin de générer davantage de Pages Vues.
En activant cette option, la page sera rechargée à chaque Saut de Page et avant l'obtention des résultats.
Cette option prend effet sur tous les navigateurs modernes (ce qui exclut IE6 et IE7).
Cette option n'est pas disponible en mode iFrame.

Recharger la page sans modifier son URL

quizity.preserveQueryString = X;
Les valeurs possibles sont true et false. Valeur par défaut : false
Si l'option précédente "reloadPage" est activée, par défaut le quiz recharge la page en ajoutant à chaque fois la variable GET qz_page=2, qz_page=3, etc.
Cela a pour unique objectif de vous permettre de suivre l'activité de vos visiteurs sur les différentes pages du quiz grâce à vos logs.
Pour que le quiz recharge la page sans modifier l'URL, activez cette option.

Désactiver l'utilisation de l'ancre

quizity.preserveHash = X;
Les valeurs possibles sont true et false. Valeur par défaut : false
Nous utilisons une ancre pour permettre au joueur de revenir directement en haut du quiz lorsqu'il commence une nouvelle page de questions ou qu'il obtient ses résultats.
Néanmoins, il arrive parfois que certains sites utilisent le système d'ancre (l'URL hash part) pour fonctionner. Si c'est votre cas et que des bugs se produisent, activez cette option.

Modifier les options du classement

quizity.ranking = {};
Si vous souhaitez utiliser l'une des options du classement présentées ci-dessous, vous devez obligatoirement commencer par inclure cette ligne.

Désactiver l'affichage du classement ou changer le moment de son apparition

quizity.ranking.display = X;
Les valeurs possibles sont 0, 1 ou 2. Valeur par défaut : 1
Si vous avez ajouté la ligne HTML nécessaire à l'affichage d'un classement (cf. section III) et que cette option est fixée à 1, le classement sera affiché dès que vos visiteurs arriveront sur la page.
Si vous fixez cette option à 2, le classement ne sera affiché qu'après que le joueur ait terminé le quiz.
Si vous fixez cette option à 0, le classement ne sera pas affiché.

Afficher un classement interne à votre site

quizity.ranking.local = XXXXX;
Les valeurs possibles sont true et false. Valeur par défaut : false
Un classement local est un classement interne à votre site, qui n'affiche que les noms des joueurs qui ont joué depuis votre site.
Cela signifie que des joueurs qui auraient découvert le quiz directement sur Quizity.com ne seront pas affichés.
Vous devez avoir renseigné l'option de l'identifiant de référent pour que cela fonctionne.

Classement par score ou par ordre chronologique

quizity.ranking.criteria = X;
Les valeurs possibles sont 1 ou 2. Valeur par défaut : 1
Fixez cette option à 1 pour trier les joueurs selon leur score, par ordre décroissant.
Fixez cette option à 2 pour afficher les joueurs par ordre antéchronologique, c'est-à-dire afficher le nom de ceux qui ont joué en dernier.

Nombre maximum de lignes dans le classement

quizity.ranking.maxPlayers = XX;
Les valeurs possibles sont un entier compris entre 1 et 20. Valeur par défaut : 10
Cette option fixe le nombre maximum de lignes dans le tableau du classement.

Cacher les lignes vides du classement

quizity.ranking.noEmptyLines = XXXXX;
Les valeurs possibles sont true et false. Valeur par défaut : false
Imaginons que vous ayez fixé le nombre maximum de lignes dans le classement (cf. option précédente) à 10.
Si seulement 6 joueurs ont joué au quiz, il restera 4 lignes vides dans le tableau.
Si vous fixez cette option à false, le tableau comportera 10 lignes, dont 4 vides.
Si vous fixez cette option à true, le tableau ne comportera que les 6 lignes remplies.

Ne pas du tout afficher le classement s'il est vide

quizity.ranking.hideIfEmpty = XXXXX;
Les valeurs possibles sont true et false. Valeur par défaut : false
Si cette option est fixée à true, le classement ne sera pas affiché du tout s'il est entièrement vide.

Cacher un widget de classement sur les pages où il n'y a pas de quiz

quizity.ranking.container = "XXXXX";
La valeur de cette option est l'attribut ID d'une balise HTML de votre choix qui contient le classement. La valeur par défaut est qz_ranking_container
Cette option est utilisée pour cacher le bloc HTML qui contient le classement sur les pages où il n'y a pas de quiz.

Exemple : vous avez un template unique pour l'ensemble de votre blog. Vous décidez d'ajouter un bloc dans la colonne de droite pour avoir un bel affichage du classement du quiz. Cela ressemble à ceci :



Le problème, c'est que sur d'autres pages de votre blog où il n'y a pas de quiz, vous avez un bloc de classement vide :



Imaginons que le code HTML de ce bloc est le suivant : 
<div class="right_block">
	<h1>Classement du quiz</h1>
	<div id="qz_ranking"></div>
</div>
La solution est de rendre ce bloc invisible avec style="display:none" et de lui donner un ID spécifique, et c'est le quiz lui-même qui le fera ré-apparaître s'il y a besoin d'afficher un classement. C'est cet ID spécifique que vous devez indiquer. Par défaut, il s'agit de qz_ranking_container.

Exemple du code qui donnera l'effet désiré : 
<div id="qz_ranking_container" class="right_block" style="display:none">
	<h1>Classement du quiz</h1>
	<div id="qz_ranking"></div>
</div>
ou une autre façon d'arriver au même résultat : 
<div id="qz_ranking_container" style="display:none">
	<div class="right_block">
		<h1>Classement du quiz</h1>
		<div id="qz_ranking"></div>
	</div>
</div>
Remarque : n'essayez pas d'appliquer une règle CSS sur les ID #qz_ranking_container et #qz_ranking car ils seront réinitialisés au chargement du quiz. Si besoin, appliquez plutôt une classe ou utilisez l'attribut style="".

Personnaliser le design du classement via CSS

quizity.ranking.customCSS = XXXXX;
Les valeurs possibles sont true, false ou le chemin vers un fichier CSS. Valeur par défaut : false
Vous pouvez presque entièrement personnaliser le design du classement pour qu'il s'intègre parfaitement au style de votre site. Vous n'avez qu'à modifier les propriétés CSS qui sont exposées en bas de cette page.
Si cette option est fixée à false, le design par défaut sera appliqué.
Si cette option est fixée à true, Quizity considère que vous avez vous-même inclus les feuilles de styles CSS modifiées.
Si cette option est une chaîne de caractères qui contient le chemin vers votre fichier CSS, Quizity incluera ce fichier pour vous sur la page.

Exemple : 
quizity.ranking.customCSS = "/css/quizity_classement.css";
Avertissement : si vous indiquez un chemin vers un fichier CSS, nous vous conseillons d'héberger vous-même ce fichier. Inclure un fichier CSS dont vous n'avez pas le contrôle présente un risque de sécurité.

Supprimer le titre du classement

quizity.ranking.skipHeader = XXXXX;
Les valeurs possibles sont true et false. Valeur par défaut : false
Par défaut, la première ligne du classement indique le titre "Classement du quiz" ou "Ils ont joué au quiz".
En fixant cette option à true, ce titre ne sera pas affiché.

Mettre des liens vers les pages de profil

quizity.ranking.links = XXXXX;
Les valeurs possibles sont true et false. Valeur par défaut : false
En fixant cette valeur à true, le nom des joueurs dans le classement seront cliquables et ouvriront une nouvelle fenêtre sur la page de profil Quizity du joueur.

V. Récapitulatif du code d'intégration complet

Avec les commentaires : 
<div id="qz_div">
	<a id="qz_link" href="XXXXXXXXXXXXXXXX" target="_blank">quiz</a> est en train de charger depuis Quizity.com, le site pour <a href="https://fr.quizity.com/create/quiz/0/">créer un quiz</a>, veuillez patienter...
</div>
	
<div id="qz_ranking_container" style="display: none;">
	<div id="qz_ranking"></div>
</div>

<script>
	
	//Cette ligne est obligatoire pour utiliser une ou plusieurs options
	var quizity = {};
	
	//Votre identifiant de référent qui vous a été donné sur Quizity.com (cf. page pour les développeurs). Ce numéro unique sert à déterminer quels sont les joueurs qui ont joué depuis votre site (pour créer un classement local + vous donner des statistiques). Par défaut : null
	quizity.rid = null;
	//Langue utilisée pour afficher les instructions dans l'interface. Par défaut : "en"
	quizity.hl = "fr";
	//Thème graphique de l'interface. Utilisez 1 si l'arrière-plan de votre site est clair, 2 s'il est foncé. Par défaut : 1
	quizity.theme = 1;
	//Afficher le quiz en marque blanche. Par défaut: false
	quizity.whiteLabel = false;
	//Recharger la page au cours du quiz. Par défaut: false
	quizity.reloadPage = false;
	//Recharger la page sans modifier son URL. Par défaut: false
	quizity.preserveQueryString = false;
	//Désactiver l'utilisation d'une ancre pendant le quiz. Par défaut: false
	quizity.preserveHash = false;
	
	//Cette ligne est obligatoire pour utiliser une ou plusieurs options du classement
	quizity.ranking = {};
	//Affichage du classement. Utiliser 0 pour "jamais", 1 pour "toujours", 2 pour "après avoir répondu au quiz". Par défaut : 1
	quizity.ranking.display = 1;
	//N'afficher dans le classement que les joueurs qui ont joué au quiz sur votre site. Par défaut : false
	quizity.ranking.local = false;
	//Le critère de classement. Utilisez 1 pour trier les joueurs par score décroissant, 2 pour un tri par ordre antéchronologique (affiche les joueurs les plus récents). Par défaut : 1
	quizity.ranking.criteria = 1;
	//Le nombre maximal de lignes affichées dans le classement. Actuellement limité à 20. Par défaut : 10
	quizity.ranking.maxPlayers = 10;
	//Ne pas afficher du tout le classement s'il est vide. Par défaut : false
	quizity.ranking.hideIfEmpty = false;
	//Si vous souhaitez définir vous-même l'attribut ID de la balise HTML qui contient le widget de classement. Cf Quizity.com pour l'utilité de cette option. Par défaut : "qz_ranking_container"
	quizity.ranking.container = "qz_ranking_container";
	//Ne pas afficher de ligne vide dans le classement. Par défaut : false
	quizity.ranking.noEmptyLines = false;
	//Utiliser vos propres feuilles de style CSS pour le design du classement. Fixez la valeur à true, false ou le chemin d'un fichier CSS. Cf Quizity.com. Par défaut : false
	quizity.ranking.customCSS = false;
	//Enlever la première ligne du classement qui contient le titre. Par défaut : false
	quizity.ranking.skipHeader = false;
	//Afficher un lien cliquable sur le nom de joueurs dans le classement, qui ouvre une nouvelle fenêtre sur la page de profil du membre en question. Par défaut : false
	quizity.ranking.links = false;

</script>

<script type="text/javascript" src="https://staticp.quizity.com/js/embed_quiz.js"></script>
Compacté sur une ligne et sans les commentaires (obligatoire sur Blogger notamment pour éviter des bugs) : 
<div id="qz_div">Le <a id="qz_link" href="https://fr.quizity.com" title="XXX" target="_blank">quiz</a> est en train de charger depuis Quizity.com, le site pour <a href="https://fr.quizity.com/create/quiz/0/">créer un quiz</a>, veuillez patienter...</div><div id="qz_ranking_container" style="display: none;"><div id="qz_ranking"></div></div><script>var quizity={};quizity.rid=1;quizity.hl="fr";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. Annexes

Intégration par iFrame

L'intégration par iFrame vous permet d'intégrer des quiz sur des sites qui accepteraient les iFrames mais pas le Javascript.

L'intégration par iFrame est donc compatible avec plus de sites internet mais, en contrepartie, présente des inconvénients que l'on ne retrouve pas avec l'intégration par Javascript. L'intégration par iFrame est moins naturelle et globalement moins agréable pour l'internaute.

Par exemple, la taille, la couleur et le type de la police utilisée par défaut pour le quiz ne sont pas les mêmes que ceux de votre site web.
Un autre inconvénient est que le quiz est "enfermé" dans un cadre d'une hauteur et d'une largeur fixe, obligeant l'internaute à utiliser la molette pour faire défiler les questions à l'intérieur du cadre.

Pour limiter au maximum ces inconvénients, nous vous laissons la possibilité d'intégrer un ou plusieurs fichiers CSS dans l'iFrame, afin de personnaliser certains éléments du design. Les chemins sont à passer sous forme url-encodée en paramètres GET de l'adresse de l'iFrame avec les noms "css0", "css1", "css2", etc.

Il est également possible de fournir des propriétés CSS directement dans une chaîne url-encodée passée dans un paramètre GET nommé "scss".

Etant donné la charge serveur supplémentaire que nous occasionne l'intégration par iFrame, nous réservons la possibilité d'ajouter ses propres propriétés CSS aux sites ayant l'amabilité de préserver les liens retours vers Quizity.

Pour le reste, les différentes options décrites sur cette page pour l'intégration par Javascript s'appliquent également à l'intégration par iFrame. Il suffit de transmettre les paramètres de configuration sous la forme d'une chaîne au format JSON url-encodée, dans un paramètre nommé "jsconfig".

Sous forme non concaténée et non url-encodée, un code d'intégration de quiz par iFrame pourrait ressembler à ceci :

<iframe
	height = "550"
	width = "550"
	src = "https://iframe.quizity.com/embed_iframe.php?
		ct = quiz
		&cid = xxx				//identifiant unique du quiz
		&jsconfig = {
			"rid" : xxx,		//identifiant de référant
			"hl" : "fr",
			"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">
	Le <a id="qz_link" href="https://fr.quizity.com" target="_blank">quiz</a> est en train de charger depuis Quizity.com, le site pour <a href="https://fr.quizity.com/create/quiz/0/">créer un quiz</a>, veuillez patienter...
</iframe>

Explications sur la façon dont les joueurs sont ajoutés au classement

Si le visiteur joue sur votre site et qu'il a une session ouverte sur Quizity.com en même temps, il est immédiatement ajouté au classement, sans avoir à se rendre sur Quizity !

Mais même si le joueur n'est pas connecté sur Quizity, rien n'est perdu. Il suffit qu'il se rende sur Quizity après avoir joué puis qu'il se connecte ou crée un compte, et voilà ! Sa partie est immédiatement comptabilisée et ajoutée à votre classement local et dans le classement général. Les points qu'il a gagnés sur votre site sont même ajoutés rétroactivement sur son compte !

Permettre aux utilisateurs d'un forum de poster des quiz

Notre code rend extrêmement simple la création d'un BBcode pour créer un quiz. En effet, le seul élément variable à insérer dans le code d'intégration est l'identifiant du quiz.

Ainsi, sur le forum du site Warriorlabs, un membre n'a qu'à écrire ceci pour insérer un quiz dans son article : 
Jouez au quiz: [quiz]https://fr.quizity.com/play.quiz/xxx/yyyyyyyy[/quiz]

Feuille de style CSS du classement

Pour vous aider à comprendre comment modifier les CSS du classement, voici la structure d'un classement de 3 lignes dont la dernière est vide : 
<div id="qz_ranking_container" style="display: none;">
	<div id="qz_ranking">
		<div class="qz_ranking_header">Classement du quiz</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">Propulsé par Quizity.com</a>
		</div>
	</div>
</div>
Et voici les propriétés CSS par défaut du classement : 
.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;
}
Vous n'avez qu'à copier ces propriétés dans un fichier, les modifier à votre convenance et inclure le fichier sur votre page web. La seule contrainte est que vous ne devez pas empêcher l'affichage de la dernière ligne du tableau qui fait référence à Quizity.

Remarque : comme précisé précédemment, les propriétés CSS appliquées à #qz_ranking ou #qz_ranking_container ne seraient pas prises en compte. Appliquez plutôt des classes CSS sur les balises correspondantes si besoin.

Faites-nous des retours !

Est-ce que tout marche bien ? Est-ce que vous avez besoin d'aide ? Est-ce que vous souhaitez plus de fonctionnalités ?

Dites-nous tout en nous écrivant à . Merci !

Cookies et données personnelles

En naviguant sur ce site, vous acceptez notre politique de cookies et de gestion des données personnelles consultable ici.