Anmelden

nShift Help Center

nShift Checkout Widget Benutzerinteraktion

Avatar
Malene Tidemann
Aktualisiert

nshift-checkout-label.png

 

Zwei verschiedene Arten von Änderungen können das Widget beeinflussen: externe und interne. Beide müssen von der Webseite unterschiedlich behandelt werden.

Erfahren Sie mehr über:

 

Wichtiger Hinweis: Das nShift Checkout Widget kann nicht mit Delivery Checkout (Legacy-Version) verwendet werden. Lesen Sie mehr über das Legacy-Widget hier. 

 

Externe Änderungen

Eine externe Änderung tritt auf, wenn sich Parameter ändern, die beeinflussen könnten, welche Versandoptionen im Widget angezeigt werden. Übliche Parameter wären die Postleitzahl des Empfängers oder der Gesamtpreis der gekauften Artikel. Das Hauptmerkmal dieser Parameter ist, dass sie extern zum Widget sind. Wenn sich einer von ihnen ändert, sollten neue Versandoptionsdaten vom Server angefordert werden. Sobald die Daten verfügbar sind, sollte die Widget-Methode updateOptions aufgerufen werden, um die neuen Versandoptionen anzuzeigen. Um Versandoptionsdaten anzufordern, verwenden Sie den Code aus dem Abschnitt Das Widget mit Versandoptionen füllen.

 

 

Interne Änderungen

Eine interne Änderung tritt auf, wenn der Benutzer mit dem Widget interagiert. Dazu gehören Ereignisse wie die Auswahl einer Versandoption oder das Eingeben von Text in ein Eingabefeld. Wann immer eine Änderung eintritt, wird die Funktion resultCallback aus den widgetSettings mit einem Ergebnisobjekt aufgerufen. Wenn die Eigenschaft valid im Ergebnisobjekt true ist, können die Informationen im Ergebnisobjekt verwendet werden, um eine Sendung zu erstellen. Wenn valid false ist, sind die Informationen unvollständig und es ist weitere Benutzerinteraktion erforderlich. Die Informationen im Ergebnisobjekt können dennoch verwendet werden, um die Webseite zu aktualisieren und die bisherige Auswahl des Benutzers widerzuspiegeln. Zum Beispiel, um den Gesamtpreis basierend auf der aktuellen Auswahl im Widget zu aktualisieren.


Bitte beachten Sie, dass interne Änderungen keine Anforderung neuer Versandoptionen auslösen sollten. Die vom Benutzer im Widget eingegebenen oder ausgewählten Informationen ändern nicht, welche Versandoptionen verfügbar sind.

 

Das Ergebnisobjekt

Dies ist die Struktur des Ergebnisobjekts. Es ist entweder als Ergebnisargument im resultCallback oder über die Eigenschaft result der Widget-Instanz verfügbar.

 

{
   "valid":true,
   "sessionId":"00000000-0000-0000-0000-000000000000",
   "checkoutId":"00000000-0000-0000-0000-000000000000",
   "checkoutVersion":1,
   "optionId":"00000000-0000-0000-0000-000000000000",
   "pickupPointId":"12345",
   "timeSlotId":"2345",
   "addons":[
      {
         "addonId":"NOTIFY",
         "price":1.0,
         "originalPrice":0.0,
         "fields":[
            {
               "fieldId":"EMAIL",
               "value":"info@example.com"
            }
         ],
         "additionalValues":{
            "key1":"value1"
         }
      }
   ],
   "fields":[
      {
         "fieldId":"PHONE",
         "value":"1234567890"
      }
   ],
   "totalPrice":1.0,
   "totalOriginalPrice":0.0,
   "taxRate":0.0,
   "additionalValues":{
      "key2":"value2"
   },
   "resultsVersion":"2",
   "widgetVersion":"2"
}

 

  • valid - Diese Eigenschaft ist true, wenn das Ergebnis gültig ist und verwendet werden kann, um eine Sendung zu erstellen.

     
  • sessionId - Diese Eigenschaft ist die UUID der Sitzung, die zur Anforderung der Versandoptionen verwendet wurde. Sie ist erforderlich, um eine Sendung zu erstellen.

     
  • checkoutId - Diese Eigenschaft ist die UUID der Checkout-Konfiguration, die zur Generierung der Versandoptionen verwendet wurde.
  • checkoutVersion - Diese Eigenschaft ist die Versionsnummer der Checkout-Konfiguration, die zur Generierung der Versandoptionen verwendet wurde. Dies ist die tatsächliche Versionsnummer der Checkout-Konfiguration, auch wenn die Sitzung nur mit der aktiven Checkout-Konfigurations-ID erstellt wurde.

     
  • optionId - Diese Eigenschaft ist die UUID der im Widget ausgewählten Versandoption. Sie ist erforderlich, um eine Sendung zu erstellen.

     
  • pickupPointId - Diese Eigenschaft ist die trägerspezifische ID des im Widget ausgewählten Abholpunkts. Sie ist nur erforderlich, wenn die Versandoption Abholpunkte verwendet. Beachten Sie, dass Format und Länge der ID trägerspezifisch sind.

     
  • timeSlotId - Diese Eigenschaft ist die trägerspezifische ID des im Widget ausgewählten Zeitfensters. Sie ist nur erforderlich, wenn die Versandoption Zeitfenster verwendet. Beachten Sie, dass Format und Länge der ID trägerspezifisch sind.

     
  • addons - Diese Eigenschaft ist ein Array mit Addons, die unter der ausgewählten Versandoption ausgewählt wurden. Jeder Eintrag im Array ist ein Objekt mit diesen Eigenschaften:
     
    • addonId - Diese Eigenschaft ist die ID des Addons.
    • price - Diese Eigenschaft ist der Preis, der zum Gesamtpreis hinzugefügt wurde, weil dieses Addon ausgewählt wurde.
    • originalPrice - Diese Eigenschaft ist der ursprüngliche Preis, der zum ursprünglichen Gesamtpreis hinzugefügt wurde, weil dieses Addon ausgewählt wurde.
    • fields - Diese Eigenschaft ist ein Array von Eingabefeldern unter dem ausgewählten Addon. Jeder Eintrag im Array ist ein Objekt mit diesen Eigenschaften:
      • fieldId - Diese Eigenschaft ist die Feld-ID.
      • value - Diese Eigenschaft ist der Wert des Feldes als Zeichenkette.
    • additionalValues - Diese Eigenschaft ist ein Objekt mit Schlüsseln und Werten, die durch den Abschnitt „Zusätzliche Rückgabewerte“ der Checkout-Konfiguration definiert sind.
  • fields - Diese Eigenschaft ist ein Array von Eingabefeldern unter der ausgewählten Versandoption. Jeder Eintrag im Array ist ein Objekt mit diesen Eigenschaften:
     
    • fieldId - Diese Eigenschaft ist die Feld-ID.
    • value - Diese Eigenschaft ist der Wert des Feldes als Zeichenkette.
  • totalPrice - Diese Eigenschaft ist der Gesamtpreis der ausgewählten Versandoption und aller ausgewählten Addons.

     
  • totalOriginalPrice - Diese Eigenschaft ist der ursprüngliche Gesamtpreis der ausgewählten Versandoption und aller ausgewählten Addons.

     
  • taxRate - Diese Eigenschaft ist der in der Checkout-Konfiguration festgelegte Steuersatz.

     
  • additionalValues - Diese Eigenschaft ist ein Objekt mit Schlüsseln und Werten, die durch den Abschnitt „Zusätzliche Rückgabewerte“ der Checkout-Konfiguration definiert sind.

     
  • resultsVersion - Diese Eigenschaft ist die Version des Ergebnisobjekts. Sie ist derzeit immer der String "2".

     
  • widgetVersion - Diese Eigenschaft ist die Version des Widgets, das das Ergebnisobjekt erzeugt hat. Sie ist derzeit immer der String "2".

 

Wiederherstellung der Benutzerauswahl

In einigen Fällen kann es notwendig sein, die vom Benutzer im Widget getroffenen Auswahlen und Eingaben wiederherzustellen. Zum Beispiel, wenn der Benutzer die Webseite verlässt, kann das aktuelle Ergebnis des Widgets in einem persistenten Speicher abgelegt werden. Wenn der Benutzer dann zur Webseite zurückkehrt, kann das gespeicherte Ergebnis gelesen und auf das Widget angewendet werden.

Es gibt zwei Möglichkeiten, ein Ergebnis im Widget wiederherzustellen: Die Methode setResult oder ein zweites optionales Argument bei updateOptions. Unabhängig davon, welche Methode verwendet wird, versucht das Widget, dieselben Optionen, Addons, Abholpunkte oder Zeitfenster im Ergebnisobjekt auszuwählen. Wenn eines der Elemente fehlt, wird stattdessen das erste sinnvolle Element ausgewählt.

 

  // Wenn das Widget mit Versandoptionen gefüllt ist
  widget.setResult(result);
  
  // oder wenn neue Optionen zusammen mit einem Ergebnis angewendet werden sollen
  widget.updateOptions(options, result);

 

Bitte beachten Sie, dass das Ergebnisargument der Methode updateOptions nur übergeben werden muss, wenn sich das Ergebnis ändern soll. Das Widget verfolgt intern das aktuelle Ergebnis und wendet es auf die verfügbaren Versandoptionen an.

 

 

Widget-Instanz

Die vom Aufruf nShiftCheckoutWidget.createWidget() zurückgegebene Widget-Instanz besitzt diese Eigenschaften und Methoden:

{
   enabled: true,
   result: {},
   setResult(result),
   install(),
   uninstall(),
   enable(),
   disable(),
   updateOptions(options, result)
}
  • enabled - Dies ist eine Eigenschaft, die den Aktiviert-/Deaktiviert-Status des Widgets enthält.

     
  • result - Dies ist eine Eigenschaft, die das aktuellste Widget-Ergebnis enthält. Weitere Informationen finden Sie im Abschnitt Das Ergebnisobjekt.

     
  • setResult(result) - Diese Methode nimmt ein Widget-Ergebnis als Argument und aktualisiert das Widget, um die im Ergebnis getroffenen Auswahlen widerzuspiegeln. Hauptsächlich wird diese Methode verwendet, um die Benutzerauswahl wiederherzustellen, wenn die Webseite mit dem Widget neu geladen wird. Weitere Informationen finden Sie im Abschnitt Das Ergebnisobjekt.

     
  • install() - Diese Methode fügt das Widget der Webseite hinzu. HTML-Elemente werden im Container-Element erstellt, wenn diese Methode aufgerufen wird. Weitere Informationen finden Sie unter Widget anzeigen.

     
  • uninstall() - Diese Methode entfernt das Widget von der Webseite. Alle vom Widget erstellten HTML-DOM-Elemente und Event-Listener werden entfernt. Weitere Informationen finden Sie unter Widget anzeigen.

     
  • enable() - Diese Methode aktiviert die Benutzerinteraktion mit dem Widget. Weitere Informationen finden Sie unter Das Widget mit Versandoptionen füllen.

     
  • disable() - Diese Methode deaktiviert die Benutzerinteraktion mit dem Widget. Weitere Informationen finden Sie unter Das Widget mit Versandoptionen füllen.

     
  • updateOptions(options, results) - Diese Methode aktualisiert die im Widget angezeigten Versandoptionen. Sie kann auch gleichzeitig die Benutzerauswahl aktualisieren, wenn das optionale results-Argument übergeben wird. Weitere Informationen finden Sie unter Das Widget mit Versandoptionen füllen.

 

 

Verwandte Beiträge