Erweiterte Einbindung des HTML-Integrationscodes (Widget) über die API
Einrichtung
Erstellen Sie ein Widget, indem Sie ein Options-Objekt an die Create-Funktion übergeben:
var widget = DigitaService.Widget.Create(options);
Optionen für die Einrichtung
Erforderlich
Option | Typ | Beschreibung |
|---|---|---|
options.element | string - HTMLElement | In dieses HTMLElement wird das Widget eingefügt. Sie können direkten Zugriff auf ein bestehendes HTMLElement geben oder die String-ID für dieses Element angeben. Wenn Sie diese Eigenschaft nicht angeben, wird versucht, eine ID „digitaservice-widget“ auf der Seite zu finden. |
options.engine | string | Die absolute URL zur Anwendung, die in das Widget geladen wird. |
Optional
Option | Typ | Standard | Beschreibung |
|---|---|---|---|
options.height | string | auto | Das Widget hat eine Standardhöhe von null, bevor er geladen wird. Sie können dies mit einem Platzhalterwert überschreiben, um Seitensprünge zu vermeiden, je nachdem, wo das Widget auf der übergeordneten Seite verwendet wird. Der Wert wird in Pixeln angegeben, z. B. „600px“. Wenn options.fixed = true verwendet wird, wird die Höhe auf den angegebenen Wert fixiert, wodurch Scrollleisten angezeigt werden. |
options.autoscroll | boolean | true | Abhängig von der Länge des Widget-Inhalts und der Anzeige des Benutzers kann es erforderlich sein, dass die Seite, die das Widget enthält, ein Scrollen der Hostseite erfordert. Das Standardverhalten, wenn ein Benutzer das Widget verwendet, besteht darin, die Hostseite nach oben zum Widget zu scrollen, um die Benutzerfreundlichkeit zu verbessern. Um dies zu deaktivieren, setzen Sie autoscroll auf false. Diese Eigenschaft wird false sein, wenn options.fixed wahr ist. |
options.sharingurl | string | Die URL, die das Widget enthält | Bei Verwendung von sozialem Teilen ist dies die URL, die Personen in sozialen Medien teilen werden, um sie zu Ihrer Kampagne zu führen. Wenn sharing eine leere Zeichenkette ist, wird die Hosting-Seite (die das Widget enthält) als URL verwendet. |
options.fixed | boolean | false | Normalerweise ändert das Widget automatisch seine Größe, um den Inhalt des Engines anzupassen und Scrollleisten zu vermeiden. Wenn dies auf true gesetzt ist, bleibt die Widget-Höhe konstant und ändert sich nicht. Bei Verwendung dieser Option sollte der options.height Wert auf einen anderen als „auto“ gesetzt werden. Wenn die Engine-Höhe größer als der Höhenwert ist, werden Scrollleisten zur Navigation verwendet. |
options.width | string | „100%“ | Die Breite des Widgets. Kann als CSS-Messung wie „%“ oder „px“ eingestellt werden. |
Laden
Sobald ein Widget eingerichtet ist, müssen Sie es laden. Sie können das Widget jederzeit laden.
Hinweis: Stellen Sie sicher, dass Sie alle untenstehenden Rückruffunktionen einrichten, bevor Sie laden, damit Sie alle Ereignisse erfassen können.
widget.load();
```# Ereignis-Callbacks
###### onReady
Sobald *widget.load()* aufgerufen wurde, wird das Widget geladen und initialisiert. Wenn das Widget diesen Vorgang abgeschlossen hat, wird ein optionaler *onReady* Callback aufgerufen.
widget.onReady = function (event) {
// geladen und bereit zur Nutzung
console.log(event.type); // “ready”
console.log(event.data); // {}
};
###### onError
Sobald *widget.load()* aufgerufen wurde, wird das Widget geladen und initialisiert. Tödliche Fehler, die danach auftreten, rufen einen optionalen *onError* Callback auf.
widget.onError = function (event) {
throw new Error(event.message);
};
###### onComplete
Sobald das Spiel beendet ist und der Benutzer den letzten Bildschirm sieht. Es liefert zudem ein *data object*, das beschreibt, was im Spiel geschehen ist.
*Hinweis: Wenn Sie darauf reagieren möchten, könnte es sinnvoll sein, im Callback ein Timeout einzufügen, damit der Benutzer Zeit hat, den Endbildschirm zu lesen, da es sofort beim Erreichen des letzten Bildschirms auftritt. Sie können auch onClose verwenden.*
widget.onComplete = function (event) {
console.log(event.type); // “complete”
console.log(event.data); // {}
console.log("Die Punktzahl des Benutzers war" + event.data.gameMetrics.score);
};
###### onResize
Tritt auf, wenn die Engine die Größe geändert hat und liefert die Höhe als Pixelwert.
widget.onResize = function (event) {
console.log(event.type); // “resize”
console.log(event.data); // {}
console.log("Anwendungshöhe:" + event.data.height);
};
###### onFirstInteraction
Wenn der Benutzer zum ersten Mal mit der geladenen Anwendung interagiert (berühren/klicken).
widget.onFirstInteraction = function () {
console.log("Der Benutzer hat zum ersten Mal mit der Anwendung interagiert");
};
###### onRouteChange
Tritt auf, wenn die Anwendung innerhalb des Widgets die Route gewechselt hat (zwischen Bildschirmen navigiert). Das Ereignis kann je nach Kontext ein Datenobjekt enthalten oder nicht.
widget.onRouteChange = function (event) {
console.log(event.type) // “routechange”
console.log(event.data) // {} oder undefined
console.log("Der Benutzer hat zu einem neuen Bildschirm navigiert");
};
###### onScrollToTop
Tritt auf, wenn die Anwendung versucht, wieder zum Anfang der Seite zu scrollen. Kann auf der übergeordneten Seite genutzt werden, um sicherzustellen, dass das Scrollen nicht ausgelöst wird (CORS) oder angepasst werden muss. Das Ereignis enthält kein Datenobjekt.
widget.onScrollToTop = function () {
console.log("Nach oben scrollen");
};
# Kennzahlen
Hier ist eine Liste der wichtigsten Kennzahlen, die je nach Art des Spiels genutzt werden können:
| Schlüssel | Beschreibung |
| ---- |
| **data.gameMetrics.CurrentAttempt** | Der Versuch des Benutzers, wenn er das Spiel abgeschlossen hat. |
| **data.gameMetrics.prizeID** | Die Preis-ID. |
| **data.gameMetrics.prizeImage** | Das Preisbild. |
| **data.gameMetrics.prizeName** | Der Preisname. |
| **data.gameMetrics.prizeRef** | Die Preisreferenz. |
| **data.gameMetrics.totalPossibleAttempts** | Die Gesamtanzahl der möglichen Versuche. |
| **data.gameMetrics.userWon** | true/false abhängig vom Status des Benutzers. |
| **data.gameMetrics.score** | Die Gesamtpunktzahl, mit der der Benutzer das Spiel abschließt. |
###### Zugangsdaten
| Schlüssel | Beschreibung |
| ---- |
| **data.credentials.isPreviewMode** | Überprüfen, ob das Spiel im Vorschau-Modus ist. |
| **data.credentials.projectID** | Die App-ID der aktuellen Anwendung. |
| **data.credentials.projectLanguage** | Die Sprache des Projekts im Widget (en, fr). |
| **data.credentials.projectName ** | Der Name der App. |
| **data.credentials.projectType** | Der Typ der App (Quiz, Memory...). |
| **data.credentials.publisherID** | Die Publisher-ID. |
| **data.credentials.sessionID** | Die Sitzungs-ID des aktuellen Spielers. |
# Fehlerbehandlung
Es gibt zwei Hauptmethoden, um Fehler zu erkennen und Informationen über Probleme innerhalb des Widgets abzurufen:## onError Callback
Der `onError` Callback erfasst alle schwerwiegenden Fehler, die nach dem Laden des Widgets auftreten. Dies kann hilfreich sein, um zu erkennen, wann eine Seite nicht existiert oder ein kritischer Fehler aufgetreten ist.
widget.onError = function (event) {
if (typeof event.data.message !== 'undefined') {
switch (event.data.message) {
default:
// Nichts tun
break;
case 'ERR_15':
console.log("Seite existiert nicht");
break;
}
}
};
## onRouteChange Callback
Der `onRouteChange` Callback wird ausgelöst, wenn die Anwendung zwischen verschiedenen Bildschirmen innerhalb des Widgets navigiert. Dies ist nützlich, um Fehler im Zusammenhang mit dem Anwendungsstatus und der Inhaltsverfügbarkeit zu verfolgen.
widget.onRouteChange = function (event) {
if (typeof event.data.errorCode !== 'undefined') {
switch (event.data.errorCode) {
default:
// Nichts tun
break;
case 'ERR_01':
console.log("Kein Tarif verfügbar");
break;
case 'ERR_02':
console.log("Inhalt noch nicht verfügbar");
break;
case 'ERR_03':
console.log("Inhalt abgelaufen");
break;
case 'ERR_04':
console.log("Keine weiteren Ansichten verfügbar");
break;
case 'ERR_05':
console.log("Sicherheitsfehler");
break;
case 'ERR_07':
console.log("Anwendung nicht veröffentlicht");
break;
case 'ERR_08':
console.log("Premium Anwendung nicht verfügbar");
break;
case 'ERR_09':
console.log("Session-Uid nicht erkannt");
break;
case 'ERR_10':
console.log("Session-Uid bereits verwendet");
break;
case 'ERR_11':
console.log("Plan nicht aktiviert");
break;
case 'ERR_12':
console.log("Falsche Daten empfangen");
break;
case 'ERR_13':
console.log("SSO-Anruf fehlgeschlagen");
break;
case 'ERR_14':
console.log("Sprache nicht verfügbar");
break;
}
}
};
Mit `onError` und `onRouteChange` können Sie effektiv Probleme innerhalb des Widgets verfolgen und beheben, um eine bessere Benutzererfahrung zu gewährleisten.
# Benutzerinformationen beim Bildschirmende abrufen (`onRouteChange`)
Bei der Verwendung von **Dynamic Path**, **Advent Calendar** oder **Combo** können Sie Benutzerinformationen am Ende jedes Spiels über den `onRouteChange` Callback abrufen.
Diese Methode ist wichtig, da das Standard `onComplete` Ereignis nur einmal ausgelöst wird, **wenn die gesamte mehrstufige Erfahrung abgeschlossen ist**, und nicht, wenn jedes eingebettete Spiel endet.
Dies ermöglicht es Ihrem System, die vollständigen Spielergebnisse (über `gameInfo`) zu erhalten, wenn der Benutzer den Bildschirm Beenden der Erfahrung erreicht.
# Einrichtung
Nach der Erstellung Ihres Widgets:
var widget = DigitaService.Widget.Create(options);
Fügen Sie den `onRouteChange` Listener hinzu:
widget.onRouteChange = function (event) {
console.log(event.type); // "routechange"
console.log(event.data); // { ... } oder undefined
console.log("Benutzer navigierte zu einem neuen Bildschirm");
};
# Erkennung des Bildschirm Ende
Wenn der Benutzer den Bildschirm Ende des Spiels erreicht, gibt das Widget eine Route zurück, die übereinstimmt mit:
event.data.screen === 'screen_end-YOUR_APP_ID'
Ersetzen Sie `YOUR_APP_ID` durch Ihre tatsächliche Anwendung-ID.# Abrufen der Benutzerinformationen (`gameInfo`)
Wenn der Bildschirm beendet ist, kannst du die Daten extrahieren:
event.data.gameInfo
`gameInfo` enthält ein **Array von Benutzerinformationen**, das Folgendes umfassen kann:
* Benutzereingabedaten
* Spielergebnisse oder Scores
* Erfasste Felder während der Erfahrung
Diese Daten sind nur auf dem Endbildschirm für Erlebnisse verfügbar, die in **Dynamic Path**, **Advent Calendar** oder **Combo** genutzt werden.
# Beispiel
widget.onRouteChange = function (event) {
if (event.data && event.data.screen === 'screen_end-12345') {
const daten = event.data.gameInfo;
console.log("Informationen zum Endbildschirm:", daten);
// Bearbeite oder leite diese Informationen bei Bedarf weiter
}
};
```
Aktualisiert am: 20/11/2025
Danke!