Asynchronous-Server-Side-Events (kurz "ASSE") bietet die Möglichkeit, beliebige Daten aus dem Shop asynchron per HTTPS zu externen Dienstleistern zu übermitteln. Das Format der Daten (JSON, XML etc.) ist dabei ebenfalls beliebig. Diese asynchrone Schnittstelle lässt sich flexibel für die Weitergabe von Newsletter-, Such- oder Tracking-Daten einsetzen.

Inhalt

1 Funktionsweise

2 Integration

 

1 Funktionsweise

Übertragung der Daten

Die Datenübermittlung über ASSE verläuft unabhängig vom Client. Das bedeutet, dass die Daten nicht im Browser oder in Cookies gespeichert werden, sondern vom Shop-Server zum Empfänger-Server gesendet und dort gespeichert werden. Die Shopseite wird somit nicht beeinträchtigt, wenn z. B. die Gegenseite/der Empfänger nicht reagiert.

Die Übertragung erfolgt ausschließlich über HTTPS.

Es muss ein Ziel in Form einer URL definiert werden, an das die Daten gesendet werden. Daten können auch an mehrere Ziele versendet werden.

Die Übertragungsart kann als POST-, GET- oder PUT-Request erfolgen.

Erwartet der empfangende Server einen eigenen Parameternamen, kann dieser angegeben und mitgesendet werden. Auch für den HTTP-Header der Übertragung können zusätzliche Parameter definiert werden.

Das Dateiformat ist frei wählbar. Üblich sind Formate wie XML oder JSON.

Da die Kommunikation zwischen Servern problematisch sein kann, werden mehrere Zustellversuche ausgeführt. Ebenso ist eine Zeitspanne (Time-out) definiert, in der das externe System antworten muss. Für unterschiedliche Anwendungszwecke gibt WEBSALE verschiedene Wertepaare für Time-out und Zustellversuche und deren zeitliche Abstände vor.

Prüfmechanismen

Außerdem stellt WEBSALE Prüfmechanismen zur Verfügung, über die eine oder mehrere Bedingungen definiert werden können, ob die Übertragung korrekt erfolgt ist. Folgende Bedingungen können geprüft werden:

•HTTP-Statuscode: Erst wenn der Server des externen Systems mit einem bestimmten Statuscode, z. B. "200", antwortet, wird die Übertragung als erfolgreich gewertet.

•ContentType: Das externe System kann ein bestimmtes Datenformat, z. B. XML oder JSON, zurückliefern. Bei Antwort in falschem Datenformat war die Prüfung nicht erfolgreich.

•ResponsePlain: Die Antwort, die als erfolgreich gewertet werden soll, kann auch definiert werden, z. B. "OK". Liefert das externe System als HTTP-Antwort "OK" zurück, war die Prüfung erfolgreich. Bei keiner bzw. allen anderen Antworten war die Prüfung nicht erfolgreich.

•ResponseJSON: Die Antwort wird geprüft, ob sie als JSON-Format interpretierbar ist.

•ResponseJSONData: Gibt das externe System einen Datensatz im JSON-Format zurück, kann dieser dann auf einen speziellen Wert oder eine Liste an Werten geprüft werden. Werden die konfigurierten Datenelemente nicht gefunden oder haben die falschen Werte, war die Prüfung nicht erfolgreich.

Werden mehrere Bedingungen angegeben, dann werden diese als UND-Verknüpfungen gewertet, d. h. alle Bedingungen müssen erfüllt sein, um die Übertragung als erfolgreich zu bewerten.

Übertragungsfehler und System-Überwachung

Beachten Sie bitte, dass Fehler bei der Datenübermittlung nicht direkt im Shop oder im Online-Servicebereich sichtbar sind, weil die Übertragung asynchron erfolgt. Sollte die Übertragung auch mit der maximalen Anzahl an Zustellversuchen innerhalb der Zeitspanne nicht erfolgreich sein, werden die entsprechenden Dateien in ein Fehlerverzeichnis verschoben. Über die WEBSALE-Systemüberwachung erfolgt in diesem Fall eine Benachrichtigung an die WEBSALE-System-Administratoren, die sich dann mit dem Shop-Administrator in Verbindung setzen.

Integrations-Beispiele

Sehen Sie im Kapitel Anwendungsbeispiele Codes für die asynchrone Datenübermittlung an Facebook oder externe Newsletter-Dienstleister.

Referenz: Anwendungsbeispiele ASSE

 

2 Integration

Schritt 1: Freischaltung/Aktivierung

Setzen Sie sich bitte mit Ihrem WEBSALE-Ansprechpartner in Verbindung und lassen Sie "ASSE" für Ihren Shop freischalten. Die Freischaltung kann global oder pro Subshop erfolgen.

Schritt 2: Shopkonfiguration shop.config ergänzen

Fügen Sie in der Shopkonfiguration shop.config folgenden Abschnitt ein und konfigurieren Sie die Pflicht-Parameter:

ID: Vergeben Sie für jede asynchrone Übertragung eine eindeutige Bezeichnung.
Endpoint: Geben Sie die URL der Zieladresse an. Hinweis: Sie können hier auch WEBSALE-Tags verwenden.
Type: Entscheiden Sie sich für eine Übertragungsart POST, GET oder PUT.
ContentType: Format der versendeten Daten.
ServiceCategory: Einstellung für Anzahl der Zustellungsversuche und TimeOut.

<ASSE>
   <+Entry>
      ID               = shopconfirm                                           # eindeutige alphanumerische Bezeichnung 
      Endpoint         = https://api.shop.de/shop-certification/v2/order/log   # Server-URL des Empfängers
      Type             = POST                                                  # Übertragungsart
      ContentType      = application/json                                      # Datenformat: z. B. application/json, application/xml, application/txt
      ServiceCategory  = OrderNotification                                     # [Tracking|OrderNotification]
     
    </+Entry>
</ASSE>

Referenz: Abschnitt ASSE

Prüfung der Zustellung (optional)

Optional können Sie eine Bedingung für eine erfolgreiche Zusendung hinterlegen. Ist die Bedingung erfüllt, gilt die Zusendung als erfolgreich - es werden keine weiteren Zustellversuche unternommen.

Ergänzen Sie dazu den <ASSE>-Abschnitt mit folgenden Parametern:

<ASSE>
   <+Entry>
      ...
      <DefinitionOfOK>      
         <+ConditionGroup>
            <+Condition>
               Proof          = HTTP-StatusCode        # Bedingung einer erfolgreichen Zustellung
               DataSelector   =                        # Auswahl des Datenfeldes, nur bei Proof = ResponseJSONData
               Type           = value                  # Art der Prüfung
               Value          = 200                    # zu prüfender Wert
            </+Condition>
         </+ConditionGroup>
      </DefinitionOfOK>
 
   </+Entry>
</ASSE>

Referenz: Abschnitt ASSE

Zusätzliche Parameter mit dem HTTP-Header übergeben (optional)

Wenn Sie für die HTTPS-Übertragung zusätzliche Parameter benötigen, ergänzen Sie den <ASSE>-Abschnitt der Shopkonfiguration shop.config mit folgenden Parametern:

<ASSE>
   <+Entry>
      ...
      <AdditionalHeaders>
         <+HttpHeader>
            Name               = 
            Value              = 
         </+HttpHeader>
      </AdditionalHeaders>
 
   </+Entry>
</ASSE>

Referenz: Abschnitt ASSE

Schritt 3: Authentifizierung/Sicherheit der Zugangsdaten einrichten

Wenn eine Authentifizierung in der Payload erfolgen soll, hinterlegen Sie die entsprechenden Passwörter, Zugangsdaten etc. im Abschnitt <FreeMessages-Txt> in der Shopkonfiguration shop.config. So ist sichergestellt, dass Passwörter nicht im Klartext in den HTML-Bearbeitungs-Templates auf dem Server zu sehen sind.

<FreeMessages-Txt>
   MyApiKey            = abcdef12345
</FreeMessages-Txt>

Integration im Template kann dann an beliebiger Stelle über die FMSG-Tags erfolgen, z.B. ~FMSG-MyApiKey~

Referenz: Abschnitt FreeMessages-Txt

Wegweiser: Freie Standardtexte definieren

Schritt 4: Gewünschtes Template bearbeiten und die Payload zusammenstellen

Das Tag ASSE-Fire(ID, Payload) lässt sich flexibel in alle Templates einbinden und löst die asynchrone Datenübermittlung aus. Es benötigt 2 Parameter: Die entsprechende ID aus der Shopkonfiguration shop.config und die Payload, in der die zu übermittelnden Daten zusammengestellt werden.

Folgendes Code-Beispiel zeigt das Auslösen der Übertragung von Bestelldaten auf der HTML-Bestelleingangsbestätigungsseite (ws_confirm.htm):

~DC-FPFireJSON_set({"apiKey": "~FMSG-MyApiKey~", "email": "$A-E-Mail$", )~
~DC-FPFireJSON_append("orderId": $WS-OrderID$, "productItemIds": )~
 
{BASKET-PR-Data}
   ~DC-Int1_set(0)~
   ~DC-FPFireJSON_append([
      {@BASKET-PR-Data}
         $DC-Int1_add(1)${!DC-Int1(1)},{/!DC-Int1(1)}"$BASKET-PR-Number$"
      {/@BASKET-PR-Data}
   ]})~
{/BASKET-PR-Data}
 
~ASSE-Fire(<ID>,$WS-DisableXSSProtectionOnce$$DC-FPFireJSON$)~

Referenz: Frei verwendbare DesignControl-Tags DC-FPX
Referenz: DC-FPX_set()
Referenz: DC-FPX_append
Referenz: ASSE-Fire()

Der Inhalt der Payload im JSON-Format, die mit DC-FPFireJSON übergeben wird, sieht dann so aus:

{
   "apiKey":"XXXXX",
   "email":"E-Mail des Kunden",
   "orderId":"Auftrags-Bestellnummer",
   "productItemIds":[
      "kommaseparierte Liste mit Produkt-IDs der bestellten Produkte"
   ]
}

Alternativ zu den DC-FPX_append-Tags können die zu erstellenden JSON-Daten auch mit der JSON-Schnittstelle erzeugt werden. Siehe 5 JSON-Daten neu erstellen und modifizieren.

Fehlermeldung ergänzen

Um Konfigurationsfehler beim Erzeugen des Events zu erkennen, kann man unterhalb seines Codes das Tag ASSE-LastErrorCode verwenden, um sich den Fehler ausgeben zu lassen. Im Fehler-Fall kontaktieren Sie bitte Ihren WEBSALE-Ansprechpartner.

{ASSE-LastErrorCode}
   Errorcode des aufgetretenen Fehlers: ~ASSE-LastErrorCode~
{/ASSE-LastErrorCode}

Referenz: ASSE-LastErrorCode

Haben Sie alle Schritte durchgeführt, ist die Integration von Asynchronous-Server-Side-Events erfolgreich in Ihrem Shop integriert und aktiv.

Integrations-Beispiele

Sehen Sie im Kapitel Anwendungsbeispiele Codes für die asynchrone Datenübermittlung an Facebook oder externe Newsletter-Dienstleister.

Referenz: Anwendungsbeispiele ASSE