Intégration avancée du code d'intégration HTML (widget) via l'API
Exemple de code de widget
<html>
<head>
<!-- Include the bundles -->
<script src="https://cdn-apps.drimify.com/prod/widget/index.js" type="text/javascript"></script>
<!-- Setup the widget on page load -->
<script>
window.addEventListener('load', function () {
var widget = DigitaService.Widget.Create({
autoscroll: true,
element: 'gamification-widget',
engine: 'https://apps.drimify.com/XBs15jKF/',
fixed: false,
height:['auto'],
sharingurl: 'https://apps.drimify.com/XBs15jKF/',
width: '100%',
});
widget.onReady = function (event) {};
widget.onComplete = function (event) {};
widget.onFirstInteraction = function () {};
widget.onRouteChange = function (event) {};
widget.onScrollToTop = function () {};
widget.onClose = function () {};
widget.onError = function (errorEvent) {};
widget.load();
});
</script>
</head>
<body>
<div id="gamification-widget"></div>
</body>
</html>Configuration
Créez un Widget en passant un objet Options à la fonction Create :
var widget = DigitaService.Widget.Create(options);Options de configuration
Obligatoires
| Option | Type | Description |
|---|---|---|
| options.element | string - HTMLElement | Le widget sera intégré dans cet HTMLElement. Vous pouvez passer un accès direct à un HTMLElement existant ou fournir l'ID string de cet élément. Si cette propriété n'est pas fournie, il tentera de trouver un ID “digitaservice-widget” sur la page. |
| options.engine | string | L'URL absolue de l'application qui sera chargée dans le widget. |
Optionnelles
| Option | Type | Valeur par défaut | Description |
|---|---|---|---|
| options.height | string | auto | Le widget a une hauteur par défaut de zéro avant d'être chargé. Vous pouvez remplacer cela par une valeur de substitution pour éviter les sauts de page selon l'emplacement du widget sur la page parente. La valeur est en pixels comme “600px”. En utilisant options.fixed = true, la hauteur sera verrouillée à la valeur fournie, introduisant des barres de défilement. |
| options.autoscroll | boolean | true | Selon la longueur du contenu du widget et l'affichage de l'utilisateur, il peut être nécessaire de faire défiler la page hébergeant le widget. Le comportement par défaut lorsque l'utilisateur utilise le Widget est de défiler la page hôte jusqu'en haut du widget pour faciliter l'utilisation. Pour désactiver cette fonctionnalité, définissez autoscroll sur false. Cette propriété sera false si options.fixed est true. |
| options.sharingurl | string | L'URL hébergeant le widget | Lors de l'utilisation du Partage Social, c'est l'URL que les gens partageront sur les réseaux sociaux pour les amener à votre campagne. Si le partage est une chaîne vide, il utilisera la page hébergeante (contenant le widget) comme URL. |
| options.fixed | boolean | false | Habituellement, le widget changera de taille automatiquement pour s'adapter au contenu du moteur et éviter les barres de défilement. Si cela est défini sur true, alors la hauteur du widget sera fixe et ne changera pas. En utilisant cette option, la valeur de options.height ne doit pas être “auto”. Si la hauteur du moteur est supérieure à la valeur de la hauteur, des barres de défilement seront nécessaires pour naviguer. |
| options.width | string | “100%” | La largeur du widget. Peut être définie en une unité de mesure CSS comme “%” ou “px” par exemple. |
Chargement
Une fois qu'un Widget est configuré, vous devez le charger. Vous pouvez charger le widget à tout moment.
Remarque : Assurez-vous de configurer tout retour de fonction ci-dessous avant de le charger afin de pouvoir capturer tous les événements.
widget.load();Rappels d'Événements
onReady
Une fois que widget.load() a été appelé, cela chargera et initialisera le widget. Lorsque le widget aura terminé ce processus, il invoquera un rappel onReady optionnel.
widget.onReady = function (event) {
// chargé et prêt à être utilisé
console.log(event.type); // “ready”
console.log(event.data); // {}
};onError
Une fois que widget.load() a été appelé, cela chargera et initialisera le widget. Toute erreur fatale survenant après ce point déclenchera un rappel onError optionnel.
widget.onError = function (event) {
throw new Error(event.message);
};onComplete
Une fois que le jeu est terminé et que l'utilisateur regarde l'écran final. Il fournit également un objet de données décrivant ce qui s'est passé dans le jeu.
Remarque : si vous souhaitez agir sur cela, vous pouvez envisager de mettre un délai d'attente dans le rappel pour donner à l'utilisateur le temps de lire l'Écran De Fin car il intervient instantanément lorsque le dernier écran est atteint. Vous pouvez également utiliser onClose.
widget.onComplete = function (event) {
console.log(event.type); // “complete”
console.log(event.data); // {}
console.log("Le score de l'utilisateur était" + event.data.gameMetrics.score);
};onResize
Se produit lorsque le moteur a changé de taille, fournit la hauteur en pixels.
widget.onResize = function (event) {
console.log(event.type); // “resize”
console.log(event.data); // {}
console.log("Hauteur de l'application :" + event.data.height);
};onClose
L'application peut être configurée avec un bouton fermer dédié qui permet à l'utilisateur de fermer l'expérience de manière explicite. Si ce bouton est configuré et que l'utilisateur l'utilise, l'événement fermer sera envoyé. C'est un bon moment pour détruire le widget de votre page et terminer le cycle de vie du widget.
widget.onClose = function () {
DigitaService.Widget.Destroy();
};onFirstInteraction
Lorsque l'utilisateur interagit (touche/clic) avec l'application chargée pour la première fois.
widget.onFirstInteraction = function () {
console.log("L'utilisateur a interagi avec l'application pour la première fois");
};onRouteChange
Se produit lorsque l'application a changé de route au sein du widget. (Navigue entre les écrans). L'événement peut contenir ou non un objet de données selon le contexte.
widget.onRouteChange = function (event) {
console.log(event.type) // “routechange”
console.log(event.data) // {} ou non défini
console.log("L'utilisateur a navigué vers un nouvel écran");
};onScrollToTop
Se produit lorsque l'Application tente de faire défiler retour en haut de la page. Peut être utilisé sur la page parente pour s'assurer que le défilement n'est pas activé (CORS) ou doit être ajusté. L'événement ne contient pas d'objet de données.
widget.onScrollToTop = function () {
console.log("Défilement En Haut");
};Indicateurs
Voici une liste des indicateurs clés qui peuvent être utilisés selon le type de jeu :
| Clé | Description |
|---|---|
| data.gameMetrics.CurrentAttempt | Les tentatives de l'utilisateur une fois qu'il a terminé le jeu. |
| data.gameMetrics.prizeID | L'ID du prix. |
| data.gameMetrics.prizeImage | L'image du prix. |
| data.gameMetrics.prizeName | Le nom du prix. |
| data.gameMetrics.prizeRef | La référence du prix. |
| data.gameMetrics.totalPossibleAttempts | Le nombre total de tentatives possibles. |
| data.gameMetrics.userWon | Vrai/faux selon l'état de l'utilisateur. |
| data.gameMetrics.score | Le montant total des points accumulés avec lesquels cet utilisateur termine le jeu. |
Identifiants
| Clé | Description |
|---|---|
| data.credentials.isPreviewMode | Vérifie si le jeu est en mode prévisualisation. |
| data.credentials.projectID | L'ID de l'application actuelle jouée. |
| data.credentials.projectLanguage | La langue du projet dans le widget (en, fr). |
| data.credentials.projectName | Le nom de l'application. |
| data.credentials.projectType | Le type d'application (quiz, memory...). |
| data.credentials.publisherID | L'ID de l'éditeur. |
| data.credentials.sessionID | L'ID de session du joueur actuel. |
Gestion des erreurs
Il existe deux manières principales de détecter les erreurs et de récupérer des informations sur les problèmes survenant dans le widget :
Rappel onError
Le rappel onError capture toutes les erreurs graves qui se produisent après le chargement du widget. Cela peut être utile pour identifier lorsqu'une page n'existe pas ou si un échec critique se produit.
widget.onError = function (event) {
if (typeof event.data.message !== 'undefined') {
switch (event.data.message) {
par défaut:
// Ne rien faire
break;
case 'ERR_15':
console.log("La page n'existe pas");
break;
}
}
};Rappel onRouteChange
Le rappel onRouteChange est déclenché lorsque l'application navigue entre les différentes écrans à l'intérieur du widget. Cela est utile pour suivre les erreurs liées à l'état de l'application et la disponibilité du contenu.
widget.onRouteChange = function (event) {
if (typeof event.data.errorCode !== 'undefined') {
switch (event.data.errorCode) {
par défaut:
// Ne rien faire
break;
case 'ERR_01':
console.log("Aucun forfait disponible");
break;
case 'ERR_02':
console.log("Contenu non encore disponible");
break;
case 'ERR_03':
console.log("Contenu expiré");
break;
case 'ERR_04':
console.log("Plus de vues disponibles");
break;
case 'ERR_05':
console.log("Erreur de sécurité");
break;
case 'ERR_07':
console.log("Application non publiée");
break;
case 'ERR_08':
console.log("Application Premium non disponible");
break;
case 'ERR_09':
console.log("Session Uid non détectée");
break;
case 'ERR_10':
console.log("Session Uid déjà utilisée");
break;
case 'ERR_11':
console.log("Forfait non activé");
break;
case 'ERR_12':
console.log("Données reçues incorrectes");
break;
case 'ERR_13':
console.log("Appel SSO échoué");
break;
case 'ERR_14':
console.log("Langue indisponible");
break;
}
}
};En utilisant à la fois onError et onRouteChange, vous pouvez efficacement suivre et contrôler les problèmes qui pourraient survenir dans le widget, garantissant ainsi une meilleure expérience utilisateur.
Mis à jour le : 05/03/2025
Merci !