> ## Knowledge Base Index > Fetch the complete knowledge base index at: https://help.drimify.com/sitemap.xml > Use this file to discover available pages before exploring further. > Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash). # Intégration avancée du code d'intégration HTML (widget) via l'API # Code d’exemple du widget ``` ``` # 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 inséré dans cet élément HTML. Vous pouvez passer l'accès direct à un élément HTML existant ou fournir l'ID en chaîne de caractères pour cet élément. Si vous ne fournissez pas cette propriété, 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 | 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 remplacement pour éviter le saut de page, selon l'emplacement du widget dans la page parente. La valeur est en pixels comme “600px”. Lors de l'utilisation de *options.fixed = true*, la valeur de la hauteur sera verrouillée sur 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 lorsqu'un utilisateur utilise le Widget est de faire défiler la page hôte jusqu'en haut du widget pour faciliter l'utilisation. Pour désactiver cela, réglez autoscroll sur false. Cette propriété sera false si *options.fixed* est true. | | **options.sharingurl** | string | L'URL de la page hébergeant le widget | Lors de l'utilisation du partage sur les réseaux sociaux, c'est l'URL que les gens partageront pour amener d'autres utilisateurs à votre campagne. Si l'URL de partage est vide, elle utilisera la page hébergeant (contenant le widget) comme URL. | | **options.fixed** | boolean | false | En général, le widget s'adaptera automatiquement pour épouser le contenu du moteur et éviter les barres de défilement. Si cela est activé, la hauteur du widget restera fixe et ne changera pas. En utilisant cette option, la valeur *options.height* devrait être définie sur autre chose que “auto”. Si la hauteur du moteur est supérieure à la valeur de hauteur, des barres de défilement seront utilisées pour naviguer. | | **options.width** | string | “100%” | La largeur du widget. Peut être définie avec une mesure CSS comme “%” ou “px” par exemple. | ### Chargement Une fois le Widget configuré, vous devez le charger. Vous pouvez charger le widget à tout moment. *Note : Assurez-vous de paramétrer tous les callbacks ci-dessous avant de charger afin de pouvoir intercepter tout événement.* ``` widget.load(); ``` # Callbacks d'événements ###### onReady Une fois que *widget.load()* a été appelé, cela va charger et initialiser le widget. Lorsque le widget a terminé ce processus, il déclenchera un *onReady* callback optionnel. ``` widget.onReady = function (event) { // chargé et prêt à l'utilisation console.log(event.type); // “ready” console.log(event.data); // {} }; ``` ###### onError Une fois que *widget.load()* a été appelé, cela va charger et initialiser le widget. Toute erreur fatale survenant après ce point déclenchera un *onError* callback optionnel. ``` widget.onError = function (event) { throw new Error(event.message); }; ``` ###### onComplete Quand le jeu est terminé et que l'utilisateur voit l'écran final. Cela 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 un délai d'attente à l'intérieur du callback pour que l'utilisateur ait le temps de lire l'Écran De Fin, puisqu'il apparaît instantanément en atteignant le dernier écran. Vous pouvez également utiliser onClose.* ``` widget.onComplete = function (event) { console.log(event.type); // “complete” console.log(event.data); // {} console.log("Score de l'utilisateur : " + event.data.gameMetrics.score); }; ``` ###### onResize Se produit lorsque le moteur a redimensionné l'application, fournit la hauteur en valeur de pixels. ``` widget.onResize = function (event) { console.log(event.type); // “resize” console.log(event.data); // {} console.log("Hauteur de l'application : " + event.data.height); }; ``` ###### onFirstInteraction Quand 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 à l'intérieur du widget (navigue entre les écrans). L'événement peut ou non contenir un objet de données selon le contexte. ``` widget.onRouteChange = function (event) { console.log(event.type); // “routechange” console.log(event.data); // {} ou undefined console.log("L'utilisateur a navigué vers un nouvel écran"); }; ``` ###### onScrollToTop Se produit lorsque l'application essaie de faire défiler vers le haut de la page. Peut être utilisé sur la page parente pour s'assurer que le défilement n'est pas exécuté (CORS) ou doit être ajusté. L'événement ne contient pas d'objet de données. ``` widget.onScrollToTop = function () { console.log("Défilement vers le haut"); }; ``` # Statistiques Voici une liste des principales mesures qui peuvent être utilisées selon le type de jeu : | Clé | Description | | ---- | | **data.gameMetrics.CurrentAttempt** | Les essais réalisés par l'utilisateur une fois qu'il a terminé le jeu. | | **data.gameMetrics.prizeID** | L'identifiant 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 le statut de l'utilisateur. | | **data.gameMetrics.score** | Le nombre total de points accumulés que cet utilisateur a en complétant le jeu. | ###### Identifiants | Clé | Description | | ---- | | **data.credentials.isPreviewMode** | Vérifiez si le jeu est en mode prévisualisation. | | **data.credentials.projectID** | L'identifiant 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, mémorisation...). | | **data.credentials.publisherID** | L'identifiant du distributeur. | | **data.credentials.sessionID** | L'identifiant de session du joueur actuel. | # Gestion des erreurs Il y a deux principales façons de détecter les erreurs et d'obtenir des informations sur les problèmes se produisant au sein du widget :## onError Callback Le callback `onError` permet de capturer toute erreur fatale survenant après le chargement du widget. Cela peut être utile pour identifier si une page n'existe pas ou en cas d'échec critique. ```javascript widget.onError = function (event) { if (typeof event.data.message !== 'undefined') { switch (event.data.message) { default: // Ne rien faire break; case 'ERR_15': console.log("La page n'existe pas"); break; } } }; ``` ## onRouteChange Callback Le callback `onRouteChange` est déclenché lorsque l'application navigue entre différents é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. ```javascript widget.onRouteChange = function (event) { if (typeof event.data.errorCode !== 'undefined') { switch (event.data.errorCode) { default: // 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("Aucune vue restante"); 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("Plan non activé"); break; case 'ERR_12': console.log("Données incorrectes reçues"); break; case 'ERR_13': console.log("Échec de l'appel SSO"); break; case 'ERR_14': console.log("Langue non disponible"); break; } } }; ``` En utilisant `onError` et `onRouteChange`, vous pouvez efficacement suivre et gérer les problèmes pouvant survenir dans le widget, assurant ainsi une meilleure expérience utilisateur. # Récupération des Informations Utilisateur sur l'Écran de Fin (`onRouteChange`) Lors de l'utilisation de **Dynamic Path**, **Advent Calendar**, ou **Combo**, vous pouvez récupérer les informations utilisateur à la fin d'un jeu via le callback `onRouteChange`. Cette méthode est nécessaire car l'événement standard `onComplete` se déclenche uniquement **une fois que l'ensemble de l'expérience multi-étapes est terminé** et non à la fin de chaque jeu intégré. Cela permet à votre système de recevoir les résultats complets du jeu (via `gameInfo`) lorsque l'utilisateur atteint l'écran de fin de l'expérience. # Configuration Après avoir créé votre widget : ```javascript var widget = DigitaService.Widget.Create(options); ``` Ajoutez l'écouteur `onRouteChange` : ```javascript widget.onRouteChange = function (event) { console.log(event.type); // "routechange" console.log(event.data); // { ... } ou undefined console.log("L'utilisateur a navigué vers un nouvel écran"); }; ``` # Détection de l'Écran de Fin Quand l'utilisateur atteint l'écran de fin du jeu, le widget renverra une route correspondant à : ```javascript event.data.screen === 'screen_end-VOTRE_APP_ID' ``` Remplacez `VOTRE_APP_ID` par l'identifiant réel de votre application.# Récupération des Informations Utilisateur (`gameInfo`) Une fois l'écran de fin détecté, vous pouvez extraire les données : ``` event.data.gameInfo ``` `gameInfo` contient un **tableau d'informations utilisateur**, qui peut inclure : * Données saisies par l'utilisateur * Résultats ou scores du jeu * Champs collectés pendant l'expérience Cette charge utile n'est disponible que sur l'écran de fin pour les expériences utilisées dans **Dynamic Path**, **Calendrier de l'Avent**, ou **Combo**. # Exemple ``` widget.onRouteChange = function (event) { if (event.data && event.data.screen === 'screen_end-12345') { const données = event.data.gameInfo; console.log("Informations écran de fin:", données); // Traitez ou transmettez ces informations selon les besoins } }; ```