Zum Hauptinhalt springen
Mit dem $wsAsse-Modul lösen Sie aus einem Template heraus ASSE-Events (Asynchronous Server-Side Events) aus. Ein Event sendet im Hintergrund einen HTTP-Request an eine in der Konfiguration hinterlegte externe URL um Daten an einen externen Dienst zu übermitteln (z. B. Tracking nach einer Bestellung). Auf dieser Seite geht es um das Auslösen vorkonfigurierter Events aus dem Template. Wie ein Event eingerichtet wird (Ziel-URL, HTTP-Methode, Wiederholungen, Erfolgsbedingungen), ist in der ASSE-Konfiguration beschrieben.

​
Voraussetzung

Bevor $wsAsse im Template etwas bewirkt, muss mindestens ein Event in der Konfiguration angelegt sein. Ohne ein konfiguriertes Event gibt es keine Event-ID, die Sie auslösen könnten, und fire() liefert false. Die Konfiguration legt fest, welche URL aufgerufen wird, welche HTTP-Methode verwendet wird, wie oft bei Fehlern wiederholt wird und unter welchen Bedingungen ein Request als erfolgreich gilt.

​
Grundkonzept

Ein ASSE-Event durchläuft immer denselben Ablauf: Event konfigurieren → im Template auslösen → Request läuft asynchron im Hintergrund. Sie richten ein Event einmalig in der Konfiguration ein und vergeben ihm eine ID. Im Template lösen Sie es dann über fire() unter dieser ID aus und geben optional Daten mit. Der Shop verschickt den HTTP-Request daraufhin selbstständig im Hintergrund.

​
Asynchron: Rückgabe ist nicht gleich Erfolg

fire() gibt true zurück, sobald das Event gültig konfiguriert wurde und der Request eingereiht wurde. Dies bedeutet jedoch nicht, dass der externe Server den Request erfolgreich verarbeitet hat. Da ASSE die Requests asynchron versendet, erfolgt die tatsächliche Ausführung zeitversetzt. Verlassen Sie sich deshalb nicht auf den Rückgabewert, um den Erfolg der externen Verarbeitung zu prüfen.

​
Auslösung beim Seitenaufbau

fire() wird ausgeführt, wenn das Template gerendert wird, also bei jedem Aufruf der entsprechenden Seite. Platzieren Sie den Aufruf daher nur auf der entsprechenden Seite (z. B. die Bestellbestätigung) und bedenken Sie: Wenn der Kunde die Seite neu lädt, wird das Event erneut ausgelöst. Stellen Sie bei zählrelevanten Events (z. B. Tracking) sicher, dass ein erneutes Auslösen keine Probleme verursacht.

​
Daten übergeben

Den optionalen zweiten Parameter data hängt ASSE je nach HTTP-Methode an die URL an oder sendet ihn im Request-Body. Zwei Punkte sind dabei wichtig, damit die Daten korrekt ankommen:
  • Der Wert wird nicht automatisch URL-kodiert. Enthält er Sonderzeichen, kodieren Sie ihn selbst.
  • Übergeben Sie eine Liste oder ein Objekt, wird der Wert automatisch in ein JSON-Objekt umgewandelt.

​
Modulübersicht

Beispiel / Ausschnitt über $wsAsse 
{{= $wsAsse | json }}
JSON-Ausgabe 
{
  "asseConfigs": [...],
  "fire": "ƒ()"
}
Anmerkung: "ƒ()" kennzeichnet eine Funktion (Methode). Variablen und Methoden in der Übersicht
NameRückgabe-TypBeschreibung
asseConfigsarrayListe aller konfigurierten Events mit ihren Einstellungen.
fire()boolLöst ein vorkonfiguriertes Event aus.

​
Variablen

​
$wsAsse.asseConfigs

Gibt eine Liste aller konfigurierten Events mit ihren Einstellungen zurück. Nutzen Sie sie, um zu prüfen, welche Events (und damit welche Event-IDs) verfügbar sind, bevor Sie eines auslösen. Ist die Liste leer ([]), ist kein Event konfiguriert. Die Events werden in der Konfiguration angelegt. 
{{= $wsAsse.asseConfigs | json }}

​
Methoden

​
$wsAsse.fire()

Löst ein vorkonfiguriertes Event aus. Dabei wird im Hintergrund ein HTTP-Request an die in der Konfiguration hinterlegte URL gesendet. Über den zweiten Parameter können Sie optional Daten für den aktuellen Vorgang übergeben. Je nach HTTP-Methode werden diese an die URL angehängt oder im Request-Body gesendet. Signatur
$wsAsse.fire(eventId, data) Rückgabe
bool - true, wenn das Event gültig konfiguriert ist und ausgelöst wurde, false bei einem Konfigurationsproblem, etwa wenn die eventId keinem konfigurierten Event entspricht. Beachten Sie das asynchrone Verhalten: true sagt nichts über den Erfolg des externen Requests aus. Parameter
NameTypPflichtBeschreibung
eventIdstringjaID des auszulösenden Events. Muss einer gültigen ID aus der Konfiguration entsprechen.
datastringneinZusätzliche Daten, die mit dem Request gesendet werden (siehe Daten übergeben).
Beispiel, das ein vorkonfiguriertes Event myevent mit der Nutzer-ID auslöst: 
{{ var $eventData = "userid=" + $wsAccount.id }}
{{ $wsAsse.fire('myevent', $eventData) }}
$wsAccount.id stammt aus dem Modul $wsAccount und liefert die ID des eingeloggten Kunden.

​
Beispiele

​
Awin-Tracking auf der Bestellbestätigungsseite auslösen

Ein häufiger Anwendungsfall ist das Senden von Tracking-Daten an einen externen Dienstleister nach einer erfolgreichen Bestellung. Dieses Beispiel baut die Bestelldaten (Bestellnummer, Warenwert, Währung) aus $wsCheckout zu einer Parameter-Zeichenkette zusammen und löst damit das Event awintracking aus. Da dieser Aufruf bei jedem Seitenaufbau feuert (siehe Auslösung beim Seitenaufbau), gehört er ausschließlich auf die Bestellbestätigungsseite. 
{{ var $eventData = "&merchant=12345" }}
{{ var $eventData = $eventData + "&amount=" + $wsCheckout.sum.totalNet }}
{{ var $eventData = $eventData + "&ch=aw" }}
{{ var $eventData = $eventData + "&parts=DEFAULT:" + $wsCheckout.sum.totalNet }}
{{ var $eventData = $eventData + "&cr=" + $wsCheckout.sum.currency }}
{{ var $eventData = $eventData + "&ref=" + $wsCheckout.orderId }}
{{ var $eventData = $eventData + "&testmode=0" }}

{{ if $wsVoucher.vouchers[0] }}
  {{ var $eventData = $eventData + "&vc=" + $wsVoucher.vouchers[0].id }}
{{ /if }}

{{ $wsAsse.fire('awintracking', $eventData) }}
In der Konfiguration muss dafür ein Event mit der ID awintracking angelegt sein, das auf die Awin-Tracking-URL verweist. merchant=12345 ist ein Platzhalter und durch Ihre Awin-Merchant-ID zu ersetzen. Ergebnis Nach Aufbau der Bestellbestätigungsseite wird der Tracking-Request im Hintergrund an Awin gesendet.
  • ASSE-Konfiguration – legt Ziel-URL, HTTP-Methode, Wiederholungen und Erfolgsbedingungen eines Events fest. Voraussetzung, damit fire() etwas bewirkt.
  • $wsCheckout – liefert die Bestelldaten, die im Tracking-Beispiel übergeben werden.
  • $wsAccount – liefert die im einfachen Beispiel verwendete Nutzer-ID.