Erweiterte Einbindung des HTML-Integrationscodes (Widget) über die API
Widget-Beispielcode
<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>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 | Zeichenkette - HTMLElement | Das Widget wird in dieses HTMLElement eingefügt. Sie können einen direkten Zugriff auf ein vorhandenes HTMLElement übergeben oder die String-ID für dieses Element angeben. Wenn Sie diese Eigenschaft nicht angeben, wird versucht, eine „digitaservice-widget“-ID auf der Seite zu finden. |
| options.engine | Zeichenkette | Die absolute URL zur Anwendung, die in das Widget geladen wird. |
Optional
| Option | Typ | Standardwert | Beschreibung |
|---|---|---|---|
| options.height | Zeichenkette | auto | Das Widget hat eine Standardhöhe von null, bevor es geladen ist. Sie können dies mit einem Platzhalterwert überschreiben, um ein Springen der Seite zu vermeiden, je nachdem, wo das Widget auf der übergeordneten Seite verwendet wird. Der Wert ist in Pixel wie „600px“. Wird options.fixed = true verwendet, bleibt der Höhenwert fixiert, wodurch Scrollleisten eingeführt werden. |
| options.autoscroll | boolesch | true | Abhängig von der Inhaltslänge des Widgets und der Anzeige des Benutzers kann es erforderlich sein, dass die Seite, die das Widget enthält, gescrollt werden muss. Das Standardverhalten, wenn ein Benutzer das Widget verwendet, ist, die Hosting-Seite an den Anfang des Widgets zu scrollen, um die Benutzerfreundlichkeit zu unterstützen. Um dies zu deaktivieren, setzen Sie autoscroll auf false. Diese Eigenschaft ist false, wenn options.fixed true ist. |
| options.sharingurl | Zeichenkette | Die Hosting-URL, die das Widget enthält | Bei der Verwendung von Social Sharing ist dies die URL, die Personen in sozialen Medien teilen, um sie zu Ihrer Kampagne zu bringen. Wenn sharing eine leere Zeichenfolge ist, wird die Hosting-Seite (die das Widget enthält) als URL verwendet. |
| options.fixed | boolesch | false | Normalerweise passt sich die Größe des Widgets automatisch an den Inhalt der Engine an, um 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 Wert von options.height auf einen anderen Wert als „auto“ gesetzt werden. Wenn die Höhe der Engine größer ist als der Höhenwert, werden Scrollleisten zum Navigieren verwendet. |
| options.width | Zeichenkette | „100%“ | Die Breite des Widgets. Kann als CSS-Maßeinheit wie „%“ oder „px“ angegeben werden. |
Laden
Sobald ein Widget eingerichtet ist, muss es geladen werden. Sie können das Widget jederzeit laden.
Hinweis: Stellen Sie sicher, dass Sie alle der unten aufgeführten Rückrufe eingerichtet haben, bevor Sie das Laden starten, damit Sie alle Ereignisse erfassen können.
widget.load();Ereignis-Callback-Funktionen
onReady
Sobald widget.load() aufgerufen wurde, lädt und initialisiert dies das Widget. Wenn das Widget diesen Prozess abgeschlossen hat, wird optional der onReady Callback ausgelöst.
widget.onReady = function (event) {
// geladen und bereit zur Nutzung
console.log(event.type); // “ready”
console.log(event.data); // {}
};onError
Sobald widget.load() aufgerufen wurde, lädt und initialisiert dies das Widget. Alle schwerwiegenden Fehler, die danach auftreten, lösen optional den onError Callback aus.
widget.onError = function (event) {
throw new Error(event.message);
};onComplete
Sobald das spiel beendet ist und der benutzer den letzten Bildschirm betrachtet. Es liefert auch ein Datenobjekt, welches beschreibt, was im spiel passiert ist.
Hinweis: Wenn Sie darauf reagieren möchten, könnte es sinnvoll sein, innerhalb des Callbacks einen Timeout zu setzen, damit der benutzer Zeit hat, den Bildschirm Beenden zu lesen, da dies sofort eintritt, wenn der letzte Bildschirm erreicht ist. Sie können auch onClose verwenden.
widget.onComplete = function (event) {
console.log(event.type); // “complete”
console.log(event.data); // {}
console.log("Das Spielergebnis des Benutzers war" + event.data.gameMetrics.score);
};onResize
Tritt auf, wenn die Engine die Größe ändert, und stellt die Höhe als Pixelwert zur Verfügung.
widget.onResize = function (event) {
console.log(event.type); // “resize”
console.log(event.data); // {}
console.log("Anwendungshöhe:" + event.data.height);
};onClose
Die anwendung kann mit einer speziellen schließen-Schaltfläche konfiguriert werden, die es dem benutzer ermöglicht, die Experience ausdrücklich zu schließen. Wenn diese Schaltfläche konfiguriert ist und der benutzer damit interagiert, wird das schließen-Ereignis ausgelöst. Dies ist ein guter Zeitpunkt, um das Widget von Ihrer Seite zu entfernen und den Lebenszyklus des Widgets zu beenden.
widget.onClose = function () {
DigitaService.Widget.Destroy();
};onFirstInteraction
Wenn der benutzer zum ersten Mal mit der geladenen anwendung interagiert (Berührung/Klick).
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 (navigiert zwischen Bildschirmen). Das Ereignis kann je nach Kontext ein Datenobjekt enthalten oder auch 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, zurück bis zum oberen Rand 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("Scroll zurück bis zum oberen Rand");
};Metriken
Hier finden Sie eine Liste der wichtigsten Kennzahlen, die je nach Spieltyp verwendet werden können:
| Schlüssel | Beschreibung |
|---|---|
| data.gameMetrics.CurrentAttempt | Die Versuche des Benutzers, nachdem 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 je nach Benutzerstatus. |
| data.gameMetrics.score | Die Gesamtpunktzahl, mit der der Benutzer das Spiel abschließt. |
Anmeldeinformationen
| Schlüssel | Beschreibung |
|---|---|
| data.credentials.isPreviewMode | Prüfen, ob das Spiel im Vorschaumodus ist. |
| data.credentials.projectID | Die App-ID der aktuell gespielten 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 zu erhalten:
onError Callback
Der `onError`-Callback erfasst alle schwerwiegenden Fehler, die nach dem Laden des Widgets auftreten. Dies kann nützlich sein, um zu erkennen, wann eine Seite nicht existiert oder ein kritischer Fehler auftritt.
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 Anwendungszustand und der Verfügbarkeit von Inhalten 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 ist noch nicht verfügbar");
break;
case 'ERR_03':
console.log("Inhalt ist abgelaufen");
break;
case 'ERR_04':
console.log("Keine weiteren Ansichten");
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("Sitzungs-ID nicht erkannt");
break;
case 'ERR_10':
console.log("Sitzungs-ID bereits verwendet");
break;
case 'ERR_11':
console.log("Plan nicht aktiviert");
break;
case 'ERR_12':
console.log("Falsche Daten erhalten");
break;
case 'ERR_13':
console.log("SSO-Anruf fehlgeschlagen");
break;
case 'ERR_14':
console.log("Sprache nicht verfügbar");
break;
}
}
};Durch die Nutzung von onError und onRouteChange können Sie effektiv Probleme innerhalb des Widgets verfolgen und beheben, um ein besseres Benutzererlebnis zu gewährleisten.
Aktualisiert am: 05/03/2025
Danke!