Esempio di codice del widget

<html>
<head>
   <!-- Includi i bundle -->
   <script src="https://cdn-apps.drimify.com/prod/widget/index.js" type="text/javascript"></script>

   <!-- Configura il widget al caricamento della pagina -->
   <script>
       window.addEventListener('load', function () {
           var widget = DigitaService.Widget.Create({
               autoscroll: true,
               element: 'gamification-widget',
               engine: 'https://apps.drimify.com/Rf6aGmBR/',
               fixed: false,
               height:['auto'],
               sharingurl: 'https://apps.drimify.com/Rf6aGmBR/',
               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 di opzioni alla funzione Create:

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

Opzioni di configurazione

Obbligatorie

Facoltative

Caricamento

Una volta configurato il widget, devi caricarlo. Puoi farlo in qualsiasi momento.

Nota: configura tutte le callback descritte di seguito prima di caricare il widget, in modo da intercettare tutti gli eventi.

widget.load();

Callback degli eventi

onReady

La chiamata a widget.load() avvia il caricamento e l’inizializzazione del widget. Al termine di questo processo, viene richiamata la callback facoltativa onReady.

Nota: onReady viene attivata prima che venga visualizzata la prima schermata. Il primo evento onRouteChange indica che il partecipante può vedere il contenuto. Se l’esperienza non riesce ad avviarsi, onReady non viene attivata e viene richiamata onError.

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

onError

La chiamata a widget.load() avvia il caricamento e l’inizializzazione del widget. Qualsiasi errore irreversibile che si verifica da quel momento in poi richiama la callback facoltativa onError.

widget.onError = function (event) {
   console.log(event.data.message); // Ad esempio, "ERR_15"
};

onComplete

Viene richiamata quando la partita è terminata e l’utente sta visualizzando l’ultima schermata. Fornisce anche un oggetto dati che descrive ciò che è avvenuto durante la partita.

Nota: se vuoi eseguire un’azione in risposta a questo evento, valuta la possibilità di inserire un ritardo nella callback, così da lasciare all’utente il tempo di leggere la Schermata Finale. L’evento viene infatti attivato non appena questa viene raggiunta. In alternativa, puoi utilizzare onClose.

widget.onComplete = function (event) {
   console.log(event.type); // “complete”
   console.log(event.data); // {}
   console.log("Punteggio dell’utente: " + event.data.gameMetrics.score);
};

onResize

Viene richiamata quando l’applicazione viene ridimensionata e restituisce l’altezza in pixel.

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

onFirstInteraction

Viene richiamata quando l’utente interagisce per la prima volta con l’applicazione caricata, tramite tocco o clic.

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

onRouteChange

Viene richiamata quando l’applicazione cambia percorso all’interno del widget, passando da una schermata all’altra. A seconda del contesto, l’evento può contenere o meno un oggetto dati.

widget.onRouteChange = function (event) {
   console.log(event.type) // “routechange”
   console.log(event.data) // {} oppure undefined
   console.log("L’utente è passato a una nuova schermata");
};

onScrollToTop

Viene richiamata quando l’applicazione tenta di tornare all’inizio della pagina tramite scorrimento. Può essere utilizzata nella pagina che ospita il widget per verificare che lo scorrimento non venga attivato (CORS) o per adattarne il comportamento. L’evento non contiene un oggetto dati.

widget.onScrollToTop = function () {
   console.log("Scorrimento verso l’inizio della pagina");
};

Metriche

Di seguito sono elencate le principali metriche disponibili, a seconda del tipo di gioco:

Credenziali

Gestione degli errori

Esistono due modi principali per rilevare gli errori e ottenere informazioni sui problemi che si verificano all’interno del widget:

Callback onError

La callback onError intercetta gli errori irreversibili, ossia quelli che impediscono all’esperienza di avviarsi o di riprendere il funzionamento. Il codice di errore è disponibile in event.data.message. In questi casi, onReady non viene attivata.

widget.onError = function (event) {
    if (event.data && typeof event.data.message !== 'undefined') {
        switch (event.data.message) {
            default:
                // Non eseguire alcuna azione
                break;
            case 'ERR_04':
                console.log("Nessuna visualizzazione residua");
                break;
            case 'ERR_05':
                console.log("Errore di sicurezza");
                break;
            case 'ERR_07':
                console.log("Applicazione non pubblicata");
                break;
            case 'ERR_08':
                console.log("Applicazione Premium non disponibile");
                break;
            case 'ERR_09':
                console.log("UID della sessione non rilevato");
                break;
            case 'ERR_10':
                console.log("UID della sessione non consentito");
                break;
            case 'ERR_13':
                console.log("Chiamata SSO non riuscita");
                break;
            case 'ERR_14':
                console.log("Lingua non disponibile");
                break;
            case 'ERR_15':
                console.log("La pagina non esiste");
                break;
            case 'ERR_17':
                console.log("Configurazione SSO non valida");
                break;
            case 'ERR_21':
                console.log("Nessun gioco assegnato a Combo o Dynamic Path");
                break;
        }
    }
};

Callback onRouteChange

La callback onRouteChange viene attivata quando l’applicazione passa da una schermata all’altra all’interno del widget. È utile per monitorare gli errori relativi allo stato dell’applicazione e alla disponibilità dei contenuti.

widget.onRouteChange = function (event) {
    if (event.data && typeof event.data.errorCode !== 'undefined') {
        switch (event.data.errorCode) {
            default:
                // Non eseguire alcuna azione
                break;
            case 'ERR_02':
                console.log("Il contenuto non è ancora disponibile");
                break;
            case 'ERR_03':
                console.log("Il contenuto è scaduto");
                break;
            case 'ERR_04':
                console.log("Nessuna visualizzazione residua");
                break;
            case 'ERR_16':
                console.log("Nessuna domanda disponibile");
                break;
            case 'ERR_18':
                console.log("Intervallo tra due periodi di attivazione");
                break;
            case 'ERR_19':
                console.log("Al di fuori degli orari di apertura");
                break;
        }
    }
};

errorCode è presente solo in queste schermate di indisponibilità. Le altre schermate che impediscono al partecipante di giocare (partita già giocata, restrizioni di accesso, moduli rifiutati) non contengono errorCode: puoi identificarle tramite il nome della schermata in event.data.screen.

Per l’elenco completo dei nomi delle schermate, l’ordine degli eventi al caricamento, il comportamento di session_uid e i timeout di caricamento, consulta Ciclo di vita del widget e gestione degli errori.

Recupero delle informazioni sull’utente nella Schermata Finale (onRouteChange)

Quando utilizzi Dynamic Path™, Advent Calendar o Combo™, puoi recuperare le informazioni sull’utente al termine di ogni partita tramite la callback onRouteChange.

Questo metodo è necessario perché l’evento standard onComplete viene attivato solo al termine dell’intera esperienza a più fasi, non alla conclusione di ogni singola partita integrata.

In questo modo, il tuo sistema può ricevere tutti i risultati della partita (tramite gameInfo) quando l’utente raggiunge la Schermata Finale dell’esperienza.

Configurazione

Dopo aver creato il widget:

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

Aggiungi il listener onRouteChange:

widget.onRouteChange = function (event) {
    console.log(event.type);   // "routechange"
    console.log(event.data);   // { ... } oppure undefined
    console.log("L’utente è passato a una nuova schermata");
};

```# Rilevamento della Schermata Finale

Quando l’utente raggiunge la schermata finale della partita, il widget restituisce una route corrispondente a:

event.data.screen === 'screen_end-YOUR_APP_ID'

Sostituisci `YOUR_APP_ID` con l’ID effettivo della tua applicazione.

# Recupero delle informazioni sull’utente (`gameInfo`)

Una volta rilevata la schermata finale, puoi estrarre i dati:

event.data.gameInfo

`gameInfo` contiene un **array di informazioni sull’utente**, che può includere:
* Dati inseriti dall’utente
* Risultati o punteggi della partita
* Campi raccolti durante l’esperienza

Questo payload è disponibile solo nella schermata finale delle esperienze utilizzate all’interno di **Dynamic Path**, **Advent Calendar** o **Combo**.

# Esempio

widget.onRouteChange = function (event) {
if (event.data && event.data.screen === 'screen_end-12345') {
const dati = event.data.gameInfo;
console.log("Informazioni sulla schermata finale:", data);
// Elabora o inoltra queste informazioni secondo necessità
}
};

Aggiornato il: 29/10/2026