Integrazione avanzata del codice di integrazione HTML (widget) tramite l'API
Esempio di codice per il Widget
<html>
<head>
<!-- Includi i pacchetti -->
<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/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à inserito in questo HTMLElement. Puoi passare l'accesso diretto a un HTMLElement esistente o fornire l'ID stringa per quell'elemento. Se non fornisci questa proprietà, tenterà di trovare un ID "digitaservice-widget" nella pagina. |
options.engine | string | L'URL assoluto dell'applicazione che sarà caricata all'interno del 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 con un valore segnaposto per evitare salti di pagina a seconda di dove viene utilizzato il widget nella pagina principale. Il valore è in pixel, ad esempio "600px". Quando si usa options.fixed = true l'altezza sarà bloccata al valore fornito introducendo barre di scorrimento. |
options.autoscroll | boolean | true | A seconda della lunghezza del contenuto del widget e della visualizzazione dell'utente, potrebbe essere necessario scorrere la pagina che ospita il widget. Il comportamento predefinito quando un utente utilizza il Widget è quello di far scorrere la pagina ospitante fino alla parte superiore del widget per migliorare l'usabilità. Per disabilitare questo comportamento, imposta autoscroll su false. Questa proprietà sarà false se options.fixed è true. |
options.sharingurl | string | L'URL della pagina che ospita il widget | Quando si utilizza la Condivisione Sociale, questo è l'URL che le persone condivideranno sui Social Media per portarle alla tua campagna. Se condivisione è una stringa vuota, verrà utilizzata la pagina ospitante (contenente il widget) come URL. |
options.fixed | boolean | false | Solitamente, il widget cambierà dimensione automaticamente per adattarsi al contenuto dell'engine ed evitare le barre di scorrimento. Se impostato a true, l'altezza del widget sarà fissa e non cambierà. Quando si utilizza questa opzione, il valore di options.height dovrebbe essere impostato a qualcosa di 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 in misure CSS come "%" o "px" per esempio. |
Caricamento
Una volta configurato un Widget, devi caricarlo. Puoi caricare il widget in qualsiasi momento.
Nota: Assicurati di configurare eventuali callback sotto riportati prima di caricarlo in modo da non perdere nessun evento.
widget.load();
```# Callback degli Eventi
###### onReady
Una volta chiamata *widget.load()*, verrà caricato e inizializzato il widget. Quando il widget avrà completato questo processo, invocherà un callback opzionale *onReady*.
widget.onReady = function (event) {
// caricato e pronto all'uso
console.log(event.type); // "ready"
console.log(event.data); // {}
};
###### onError
Una volta chiamata *widget.load()*, verrà caricato e inizializzato il widget. Qualsiasi errore critico che si verifica da quel momento invocherà un callback opzionale *onError*.
widget.onError = function (event) {
throw nuova piattaforma, nuovo login! Error(event.message);
};
###### onComplete
Una volta completata la partita e l'utente si trova sull'ultima schermata. Fornisce anche un *oggetto dati* che descrive cosa è avvenuto nella partita.
*Nota: se vuoi agire su questo evento, ti consiglio di inserire un timeout all'interno del callback in modo che l'utente abbia il tempo di leggere la Schermata Finale, poiché l'evento 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 l'Engine ha riguadagnato, fornendo l'altezza come valore in pixel.
widget.onResize = function (event) {
console.log(event.type); // "resize"
console.log(event.data); // {}
console.log("Altezza dell'applicazione:" + event.data.height);
};
###### 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 le Applicazioni per la prima volta");
};
###### onRouteChange
Si verifica quando le Applicazioni hanno cambiato rotta 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 piattaforma, nuovo login! schermata");
};
###### onScrollToTop
Si verifica quando le Applicazioni stanno cercando di scorrere indietro in cima alla pagina. Può essere utilizzato sulla pagina principale per assicurarsi che lo scroll non venga attivato (CORS) o che debba essere regolato. L'evento non include un oggetto dati.
widget.onScrollToTop = function () {
console.log("Scroll A Top");
};
# Metriche
Ecco un elenco delle metriche chiave che possono essere utilizzate a seconda del tipo di partita:
| Chiave | Descrizione |
| ---- |
| **data.gameMetrics.CurrentAttempt** | Il numero di tentativi effettuati dall'utente una volta che ha completato 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** | vero/falso a seconda dello stato dell'utente. |
| **data.gameMetrics.score** | L'importo totale dei punti accumulati che questo utente ha completato nella partita. |
###### Credenziali
| Chiave | Descrizione |
| ---- |
| **data.credentials.isPreviewMode** | Controlla se la partita è in modalità anteprima. |
| **data.credentials.projectID** | L'id dell'App attualmente in uso. |
| **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'attuale giocatore. |
# Gestione degli Errori
Ci sono due modi principali per rilevare errori e ottenere informazioni sui problemi che si verificano all'interno del widget:## Callback onError
Il callback `onError` cattura tutti gli errori gravi che si verificano dopo il caricamento del widget. Questo può essere utile per identificare quando una pagina non esiste o se si verifica un grave malfunzionamento.
widget.onError = function (event) {
if (typeof event.data.message !== 'undefined') {
switch (event.data.message) {
default:
// Non fare nulla
break;
case 'ERR_15':
console.log("La pagina non esiste");
break;
}
}
};
## Callback onRouteChange
Il callback `onRouteChange` viene attivato quando l'applicazioni naviga tra diverse schermate all'interno del widget. Questo è utile per tracciare errori relativi allo stato dell'applicazioni e alla disponibilità dei contenuti.
widget.onRouteChange = function (event) {
if (typeof event.data.errorCode !== 'undefined') {
switch (event.data.errorCode) {
default:
// 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("Contenuto scaduto");
break;
case 'ERR_04':
console.log("Nessuna visualizzazione rimasta");
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 disponibile");
break;
case 'ERR_09':
console.log("Session Uid non rilevato");
break;
case 'ERR_10':
console.log("Session Uid già utilizzato");
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 sia `onError` che `onRouteChange`, puoi efficacemente tracciare e gestire i problemi che possono verificarsi all'interno del widget, garantendo una migliore esperienza utente.
# Recuperare Informazioni Utente sulla Schermata Finale (`onRouteChange`)
Quando utilizzi **Dynamic Path™**, **Advent Calendar** o **Combo™**, puoi recuperare informazioni utente alla fine di una qualsiasi partita attraverso il callback `onRouteChange`.
Questo metodo è richiesto perché l'evento standard `onComplete` viene attivato solo **quando l'intera esperienza a più fasi è completata**, non quando finisce ogni partita inclusa.
Questo consente al tuo sistema di ricevere i risultati completi della partita (tramite `gameInfo`) quando l'utente raggiunge la schermata finale dell'esperienza.
# Configurazione
Dopo aver creato il tuo widget:
var widget = DigitaService.Widget.Create(options);
Aggiungi l'ascoltatore `onRouteChange`:
widget.onRouteChange = function (event) {
console.log(event.type); // "routechange"
console.log(event.data); // { ... } o undefined
console.log("Utente navigato a una nuova piattaforma, nuovo login!");
};
# Rilevare la Schermata Finale
Quando l'utente raggiunge la schermata finale della partita, il widget restituirà una route che corrisponde a:
event.data.screen === 'screen_end-YOUR_APP_ID'
Sostituisci `YOUR_APP_ID` con il tuo effettivo ID applicazione.# Recupero delle Informazioni 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
Questa risorsa è disponibile solo sulla schermata finale per le 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 della schermata finale:", data);
// Elabora o trasmetti queste informazioni secondo necessità
}
};
```
Aggiornato il: 20/11/2025
Grazie!