Questo articolo è disponibile anche in:

Integrazione avanzata del codice di integrazione HTML (widget) tramite l'API

<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>

Configurazione

Crea un Widget passando un oggetto Options alla funzione Create:

var widget = DigitaService.Widget.Create(options);

Opzioni di Configurazione

Obbligatorie

Opzione	Tipo	Descrizione
options.element	string - HTMLElement	Il widget verrà iniettato in questo HTMLElement. Puoi fornire l'accesso diretto a un HTMLElement esistente o indicare l'ID stringa per quell'elemento. Se non fornisci questa proprietà, cercherà un id "digitaservice-widget" nella pagina.
options.engine	string	L'URL assoluto dell'applicazione che verrà caricata nel widget.

Opzionali

Opzione	Tipo	Predefinito	Descrizione
options.height	string	auto	Il widget ha un'altezza predefinita di zero prima di essere caricato. Puoi sovrascrivere questo valore con uno di segnaposto per evitare salti di pagina a seconda di dove il widget viene utilizzato nella pagina principale. Il valore è in pixel, come “600px”. Quando si utilizza options.fixed = true l'altezza sarà bloccata al valore fornito introducendo le barre di scorrimento.
options.autoscroll	boolean	true	A seconda della lunghezza del contenuto del widget e della visualizzazione dell'utente, potrebbe essere necessario che la pagina contenente il widget richieda lo scorrimento della pagina di hosting. Il comportamento predefinito quando un utente utilizza il Widget è quello di scorrere la pagina di hosting verso l'alto del widget per facilitare l'usabilità. Per disabilitare questa funzione, imposta autoscroll su false. Questa proprietà sarà false se options.fixed è true.
options.sharingurl	string	L'URL di hosting contenente il widget	Quando si utilizza la Condivisione Sociale, questo è l'URL che le persone condivideranno sui Social Media per portarli alla tua campagna. Se la condivisione è una stringa vuota, verrà utilizzata la pagina di hosting (contenente il widget) come URL.
options.fixed	boolean	false	Solitamente il widget cambierà automaticamente dimensione per adattarsi al contenuto dell'engine ed evitare le barre di scorrimento. Se impostato su true, l'altezza del widget sarà persistente e non cambierà. Quando utilizzi questa opzione, il valore di options.height deve essere impostato su un valore diverso da "auto". Se l'altezza dell'engine è maggiore del valore dell'altezza, verranno utilizzate le barre di scorrimento per navigare.
options.width	string	“100%”	La larghezza del widget. Può essere impostata come una misura CSS come “%” o “px” ad esempio.

Caricamento

Una volta impostato un Widget, è necessario caricarlo. Puoi caricare il widget in qualsiasi momento.

Nota: Assicurati di impostare eventuali callback prima di caricare in modo da poter gestire tutti gli eventi.

widget.load();

Callback per Eventi

onReady

Quando widget.load() viene chiamato, carica e inizializza il widget. Una volta completato questo processo, il widget invocherà un callback opzionale onReady.

widget.onReady = function (event) {
   // caricato e pronto all'uso
   console.log(event.type); // “ready”
   console.log(event.data); // {}
};

onError

Quando widget.load() viene chiamato, carica e inizializza il widget. Qualsiasi errore fatale che si verifica dopo quel punto invocherà un callback opzionale onError.

widget.onError = function (event) {
   throw new Error(event.message);
};

onComplete

Quando la partita è stata completata e l'utente sta guardando l'ultima schermata. Fornisce inoltre un oggetto dati che descrive ciò che è accaduto nella partita.

Nota: se desideri agire su questo, potresti voler impostare un timeout all’interno del callback in modo che l'utente abbia tempo di leggere la Schermata Finale poiché si verifica istantaneamente al raggiungimento dell'ultima schermata. Puoi anche utilizzare onClose.

widget.onComplete = function (event) {
   console.log(event.type); // “complete”
   console.log(event.data); // {}
   console.log("Il punteggio dell'utente è stato " + event.data.gameMetrics.score);
};

onResize

Si verifica quando il motore ha ridimensionato, fornendo l'altezza in pixel.

widget.onResize = function (event) {
   console.log(event.type); // “resize”
   console.log(event.data); // {}
   console.log("Altezza Applicazione:" + event.data.height);
};

onClose

Le applicazioni possono essere configurate con un pulsante di chiusura dedicato che permette all'utente di chiudere implicitamente l'esperienza. Se questo pulsante è configurato e l'utente interagisce con esso, l'evento di chiusura verrà inviato. Questo è un buon momento per distruggere il widget dalla tua pagina e terminare il ciclo di vita del widget.

widget.onClose = function () {
   DigitaService.Widget.Destroy();
};

onFirstInteraction

Quando l'utente interagisce (tocca/clicca) con le applicazioni caricate per la prima volta.

widget.onFirstInteraction = function () {
   console.log("L'utente ha interagito con l'applicazione per la prima volta");
};

onRouteChange

Si verifica quando l'applicazione ha cambiato percorso all'interno del widget. (Naviga tra le schermate). L'evento può contenere o meno un oggetto dati a seconda del contesto.

widget.onRouteChange = function (event) {
   console.log(event.type); // “routechange”
   console.log(event.data); // {} o undefined
   console.log("L'utente ha navigato a una nuova schermata");
};

onScrollToTop

Si verifica quando l'applicazione sta cercando di scorrere indietro verso l'inizio della pagina. Può essere utilizzato sulla pagina principale per assicurarsi che lo scroll non venga attivato (CORS) o che debba essere regolato. L'evento non contiene un oggetto dati.

widget.onScrollToTop = function () {
   console.log("Scroll in cima");
};

Metrics

Ecco una lista dei metri chiave che possono essere utilizzati a seconda del tipo di partita:

Chiave	Descrizione
data.gameMetrics.CurrentAttempt	Gli tentativi dell'utente una volta completata la partita.
data.gameMetrics.prizeID	L'ID del premio.
data.gameMetrics.prizeImage	L'immagine del premio.
data.gameMetrics.prizeName	Il nome del premio.
data.gameMetrics.prizeRef	Il riferimento del premio.
data.gameMetrics.totalPossibleAttempts	L'importo totale dei tentativi possibili.
data.gameMetrics.userWon	true/false a seconda dello stato dell'utente.
data.gameMetrics.score	L'importo totale dei punti aggregati con cui l'utente completa la partita.

Credenziali

Chiave	Descrizione
data.credentials.isPreviewMode	Verifica se la partita è in modalità anteprima.
data.credentials.projectID	L'ID dell'app attualmente giocata.
data.credentials.projectLanguage	La lingua del progetto nel widget (en, fr).
data.credentials.projectName	Il nome dell'app.
data.credentials.projectType	Il tipo di app (quiz, memory...).
data.credentials.publisherID	L'ID del publisher.
data.credentials.sessionID	L'ID della sessione dell'utente attuale.

Gestione degli errori

Ci sono due modi principali per rilevare errori e recuperare informazioni sui problemi che si verificano all'interno del widget:

Callback onError

Il callback onError cattura qualsiasi errore fatale che si verifica dopo il caricamento del widget. Questo può essere utile per identificare quando una pagina non esiste o se si verifica un guasto critico.

widget.onError = function (event) {
    if (typeof event.data.message !== 'undefined') {
        switch (event.data.message) {
            predefinito:
                // Non fare nulla
                break;
            case 'ERR_15':
                console.log("Pagina non esiste");
                break;
        }
    }
};

Callback onRouteChange

Il callback onRouteChange viene attivato quando l'applicazione naviga tra diverse schermate all'interno del widget. Questo è utile per tracciare errori relativi allo stato dell'applicazione e alla disponibilità dei contenuti.

widget.onRouteChange = function (event) {
    if (typeof event.data.errorCode !== 'undefined') {
        switch (event.data.errorCode) {
            predefinito:
                // Non fare nulla
                break;
            case 'ERR_01':
                console.log("Nessun piano disponibile");
                break;
            case 'ERR_02':
                console.log("Contenuto non ancora disponibile");
                break;
            case 'ERR_03':
                console.log("Il contenuto è scaduto");
                break;
            case 'ERR_04':
                console.log("Nessuna visualizzazione disponibile");
                break;
            case 'ERR_05':
                console.log("Errore di sicurezza");
                break;
            case 'ERR_07':
                console.log("Applicazione non pubblicata");
                break;
            case 'ERR_08':
                console.log("Applicazioni Premium non disponibili");
                break;
            case 'ERR_09':
                console.log("Sessione Uid non rilevata");
                break;
            case 'ERR_10':
                console.log("Sessione Uid già utilizzata");
                break;
            case 'ERR_11':
                console.log("Piano non attivato");
                break;
            case 'ERR_12':
                console.log("Dati ricevuti errati");
                break;
            case 'ERR_13':
                console.log("Chiamata SSO fallita");
                break;
            case 'ERR_14':
                console.log("Lingua non disponibile");
                break;
        }
    }
};

Utilizzando entrambi i metodi onError e onRouteChange, puoi efficacemente monitorare e gestire problemi che potrebbero verificarsi all'interno del widget, garantendo una migliore esperienza utente.

Aggiornato il: 05/03/2025

È stato utile questo articolo?

Grazie!