Intelligent Content Engine - Integration

e-Spirit AG

12.02.2019
Inhaltsverzeichnis

1. Einleitung

Das Modul Intelligent Content Engine stattet FirstSpirit mit zahlreichen Funktionen aus, die es Redakteuren erlauben, auch komplexeste Anwendungsfälle im Bereich A/B-Testing, Realtime Targeting und Personalisierung abzubilden. Trotz der Komplexität können Sie durch die cloudbasierte Implementierung auch zu Zeiten unvorhersehbarer Lastspitzen die Vorteile von FirstSpirit voll ausspielen: Die Intelligent Content Engine belastet Ihre bisherige Hardware nicht zusätzlich. Einfache Dinge bleiben einfach und komplexe Dinge werden möglich. Das hochdynamische System bleibt dank der FirstSpirit-Integration sehr einfach zu administrieren - auch ohne tiefgreifendes Systemverständnis.

Ein Bestandteil der Auslieferung des FirstSpirit ICE-Moduls ist ein Beispielprojekt. Es basiert auf dem bekannten Mithras Energy-Projekt und kann als Grundlage für eigene FirstSpirit ICE-Projekte verwendet werden. Die vorliegende Dokumentation erläutert die Funktionalitäten des Moduls anhand von Anwendungsfällen und orientiert sich dabei an diesem Projekt.

1.1. Architektur

Die Intelligent Content Engine besteht aus zwei Komponenten, die auf dem Livesystem integriert werden:

  • Das Modul, das auf dem FirstSpirit-Server installiert wird
  • Die Intelligent Content Engine, die die Aussteuerung der Varianten übernimmt

FirstSpirit ICE unterstützt aktuell kein separates QA- oder Entwicklungssystem.

Architektur der Intelligent Content Engine
Abbildung 1. Architektur der Intelligent Content Engine


  1. Das Modul übernimmt die Integration der Intelligent Content Engine in FirstSpirit. Die Variantenpflege selbst geschieht nicht innerhalb von FirstSpirit, sondern in der Intelligent Content Engine.
  2. Die Intelligent Content Engine übernimmt sowohl die Variantenpflege als auch deren Aussteuerung.
  3. Die Variantenpflege kann, anders als vom ContentCreator gewohnt, direkt in der Live-Ansicht der Webseite vorgenommen werden. Es ist keine spezielle Editieransicht erforderlich. Dafür muss der Redakteur jedoch in FirstSpirit ICE eingeloggt sein. Das bringt den Redakteur noch näher an das Erlebnis, das der Kunde auf der Webseite hat.
  4. Die Hauptanwendungsfälle des Moduls Intelligent Content Engine sind A/B-Testing und Realtime Targeting. Der Datenaustausch, der zur Aussteuerung nötig ist, geschieht in Echtzeit und direkt zwischen der Intelligent Content Engine und der auf dem Livesystem ausgespielten Anwendung. Trotz der dynamischen Natur der Anwendungsfälle ist es nicht nötig, leistungsfähigere Hardware bereitzustellen.

Alle Varianten werden direkt in FirstSpirit ICE gepflegt und ausschließlich dort eingestellt. Das FirstSpirit-Projekt selbst enthält nur die Referenzen auf das entsprechende Projekt in der Intelligent Content Engine.

Statische Inhalte werden wie üblich in FirstSpirit gepflegt und über ein Live-System bereitgestellt. Hier können klassische Deployment-Prozesse verwendet werden. Die dynamischen Inhalte von FirstSpirit ICE werden nach der Auslieferung der statischen Inhalte an den Kundenbrowser direkt dort von der Intelligent Content Engine angefordert. Für dieses Zusammenspiel müssen in den FirstSpirit-Vorlagen Anpassungen vorgenommen werden.

1.2. Technische Voraussetzungen

Das Modul Intelligent Content Engine hat die folgenden technischen Voraussetzungen:

  • FirstSpirit (Isolated- oder Legacy-Mode) ab der Version 2018-10
  • Java 8 oder höher
  • mindestens ein Account für die Intelligent Content Engine

Ein Account für die Intelligent Content Engine wird durch den Technical Support der e-Spirit AG bereitgestellt.

2. Installation und Konfiguration

Für die Verwendung der Funktionalitäten des FirstSpirit ICE-Moduls ist die Installation und Konfiguration unterschiedlicher Komponenten notwendig. Die dafür erforderlichen Schritte werden in den nachfolgenden Unterkapiteln erläutert.

2.1. Installation des Moduls

Das Modul muss mithilfe der mitgelieferten IntelligentContentEngine-<Versionsnummer>.fsm-Datei auf dem FirstSpirit-Server hinzugefügt werden. Öffnen Sie für die Installation des Moduls den Server-Manager und wählen Sie den Bereich Server-EigenschaftenModule.

Modulverwaltung in den Server-Eigenschaften
Abbildung 2. Modulverwaltung in den Server-Eigenschaften


Im Hauptpanel ist eine Liste der auf dem FirstSpirit-Server installierten Module zu sehen. Wählen Sie nach dem Klicken auf Installieren die mitgelieferte ice-fsm-<Versionsnummer>.fsm aus und bestätigen Sie die Auswahl mit Öffnen. Nach der erfolgreichen Installation wurde der Liste ein Ordner Intelligent Content Engine hinzugefügt, der Alle Rechte erhalten muss.

Nach jeder Installation oder Aktualisierung eines Moduls ist ein Neustart des FirstSpirit-Servers notwendig.

2.2. Projekt-Import

Ein Bestandteil der Auslieferung des FirstSpirit ICE-Moduls ist ein Beispielprojekt, das auf dem FirstSpirit-Server zu installieren ist. Öffnen Sie dafür im Server-Manager den Import-Dialog über den Menüpunkt ProjektImportieren und wählen Sie über den Button Lokal die Datei ice_demo.tar.gz aus ihrem lokalen Dateisystem aus. Vergeben Sie anschließend einen Projektnamen sowie eine Beschreibung und bestätigen Sie den Import mit Ja. Nach der erfolgreichen Installation wurde das Projekt der Liste im Hauptpanel hinzugefügt (vgl. Abbildung Importiertes Projekt im Server-Manager).

Importiertes Projekt im Server-Manager
Abbildung 3. Importiertes Projekt im Server-Manager


2.3. Konfiguration der Projekt-Komponente

Für den Einsatz des Intelligent Content Engine-Moduls ist eine projektspezifische Konfiguration notwendig. Diese wird über die Projekt-Komponente vorgenommen, die dem mitgelieferten Beispielprojekt bereits hinzugefügt ist.

Öffnen Sie für die Konfiguration der Projekt-Komponente den Server-Manager und wählen Sie den Bereich Projekt-EigenschaftenProjekt-Komponenten. Im Hauptpanel ist eine Liste aller bereits vorhandenen Projekt-Komponenten zu sehen. Selektieren Sie den Eintrag FirstSpirit ICE Configuration und öffnen Sie den zugehörigen Konfigurationsdialog über Konfigurieren.

Konfigurationsdialog der Projekt-Komponente
Abbildung 4. Konfigurationsdialog der Projekt-Komponente


Mit der Einrichtung des Accounts für die Intelligent Content Engine durch den Technical Support der e-Spirit AG wird außerdem initial eine leere Site erzeugt. Der Begriff bezeichnet ein Projekt im Sinne von FirstSpirit innerhalb der Intelligent Content Engine.

Die Intelligent Content Engine ist unter der folgenden URL zu erreichen: https://adm.firstspirit-ice.com.

Site ID

In dem Eingabefeld des Konfigurationsdialogs ist die ID Ihrer Site anzugeben. Diese finden Sie in der FirstSpirit ICE-Oberfläche unter dem Menüpunkt SettingsGeneral Settings. Sie wird im oberen Bereich der Site dargestellt:

Site ID in FirstSpirit ICE
Abbildung 5. Site ID in FirstSpirit ICE


2.4. Ausgabekanal für Product Feeds

Falls Sie in Ihrem FirstSpirit-Projekt Produktdaten pflegen und auf Basis dieser Produktdaten Produktempfehlungen erzeugen wollen, müssen Sie zusätzlich zu den bereits vorhandenen Ausgabekanälen Ihres Projekts einen weiteren XML-Kanal hinzufügen.

Öffnen Sie dafür den Server-Manager und wählen Sie den Punkt Projekt-EigenschaftenVorlagensätze. Durch einen Klick auf Hinzufügen wird ein Dialog angezeigt, der folgendermaßen zu füllen ist:

Ausgabekanal anlegen
Abbildung 6. Ausgabekanal anlegen


Die Abbildung entspricht der Konfiguration des Ausgabekanals des mitgelieferten Beispielprojekts. Alternativ sind als Zieldatei-Erweiterung die Werte xml oder csv möglich.

Bestätigen Sie den Dialog anschließend mit OK, um das Hinzufügen des Ausgabekanals abzuschließen.

Die Liste der vorhandenen Vorlagensätze wird daraufhin um den neuen Ausgabekanal erweitert. Dieser wurde automatisch aktiviert und steht somit direkt im Projekt zur Verfügung.

Der neue Ausgabekanal dient der Erzeugung eines Product Feeds.

3. Anpassungen im Projekt

Nach der Installation und Konfiguration der verschiedenen Komponenten müssen innerhalb des Projekts einige Anpassungen vorgenommen werden, die in den nachfolgenden Unterkapiteln erläutert werden.

3.1. Vorlagenanpassungen

Die Intelligent Content Engine setzt für ihre Verwendung einige Bibliotheken voraus, die das zuvor installierte Modul bereitstellt. Sie integrieren FirstSpirit ICE in das FirstSpirit-Projekt und sind dafür in der verwendeten Seitenvorlage zu referenzieren.

Die Referenzierung kann auf zwei Wegen erfolgen:

includeIceLibraries
Die Standardmethode referenziert die benötigten Bibliotheken direkt und bindet sie in Form zweier HTML-Skript-Tags ein. Dafür ist vor dem schließenden <head>-Tag im HTML-Bereich der Seite folgender Aufruf hinzuzufügen:
$CMS_VALUE(class("com.espirit.moddev.ice.extensions.Initializer").includeIceLibraries(#global))$
getDynamicLibraryUrl & getStaticLibraryUrl
Alternativ lassen sich die benötigten Bibliotheken über die Angabe ihrer jeweiligen URL referenzieren. Das Modul stellt dafür die folgenden Methoden bereit:
$CMS_VALUE(class("com.espirit.moddev.ice.extensions.Initializer").getDynamicLibraryUrl(#global))$
$CMS_VALUE(class("com.espirit.moddev.ice.extensions.Initializer").getStaticLibraryUrl(#global))$

3.2. Einstellung des Seitenkontextes

Ein FirstSpirit-Projekt enthält meist verschiedene Seitentypen, die der Intelligent Content Engine mitzuteilen sind. Dies erfolgt über den sogenannten Seitenkontext, der für jede verwendete Seite im FirstSpirit-Projekt individuell einzustellen ist. Im Beispielprojekt ist er bereits in Abhängigkeit der jeweiligen Seitenvorlage definiert.

Für die Zuordnung des Seitenkontextes ist im <head>-Bereich der entsprechenden Seite ein JavaScript-Skript mit dem folgenden Format einzubinden:

<script>
   DY.recommendationContext = {type: 'HOMEPAGE'};
</script>

Dabei sind die folgende Werte für den Kontext zulässig:

Tabelle 1. Mögliche Werte für den Seitenkontext
SeitentypNotwendige AttributeBeispiel

Homepage

DY.recommendationContext = {type: 'HOMEPAGE'};

Kategorienseite / Übersichtsseite für Produkte

vollständige Produkthierarchie,

als Liste von Strings formatiert

DY.recommendationContext = {type:'CATEGORY',

data: ['TOP_LEVEL_CAT', 'CHILD_CAT','GRANDCHILD_CAT']};

Produktseite

SKU (Product Unique Identifier),

als String formatiert

DY.recommendationContext = {type:'PRODUCT', data: ['SKU123']};

Warenkorb

SKUs (Product Unique Identifiers),

als Liste von Strings formatiert

DY.recommendationContext = {type:'CART', data: ['SKU123','SKU234']};

Etwas anderes (die Seite entspricht keinem der vorherigen Typen)

DY.recommendationContext = {type: 'OTHER'};



Der Parameter SKU entspricht der Artikelnummer eines darzustellenden Produktes. Aufgrund seiner Eindeutigkeit eignet er sich als Identifier und wird in diversen Anwendungsfällen entsprechend verwendet.

Zur Unterstützung mehrerer Sprachen lässt sich zusätzlich der Parameter lng angeben. Für ihn kann die Locale der aktuell angezeigten Sprache verwendet werden (z.B. de_DE oder en_GB). Das genaue Format der Locale kann frei gewählt werden, allerdings muss es den Werten entsprechen, die im Product Feed angegeben wurden.

Beispiel:

<script>
   DY.recommendationContext = {type: 'HOMEPAGE', lng: 'en_GB'};
</script>

3.3. Product Feed (optional)

Sogenannte Data Feeds bieten die Option, der Intelligent Content Engine Datenmengen aus FirstSpirit (z.B. Produktinformationen) bereitzustellen. Sie dienen der Erzeugung von Empfehlungen auf der Webseite. Neben dem Content Feed, der beispielsweise Leseempfehlungen produziert, wird der Product Feed benötigt, um FirstSpirit ICE-Produktdaten für AI-gestützte Produktempfehlungen zur Verfügung zu stellen. Zusätzlich ermöglicht er, stark erweiterte Analysefunktionen über den Kundenstrom auf der Webseite zu verwenden. Das Vorgehen zum Erstellen eines Product Feeds wird beispielhaft in den folgenden Unterkapiteln beschrieben und kann am mitgelieferten Beispielprojekt nachvollzogen werden.

Wenn Sie keinen Product Feed verwenden möchten, können Sie diesen Abschnitt überspringen.

Um den Product Feed zielführend verwenden zu können, ist es nötig den Seitenkontext der Seite des einzelnen Produktes richtig einzustellen. Achten Sie hierbei darauf, die SKU des Produktes zu setzen (DY.recommendationContext = {type:'PRODUCT', data: ['SKU123']};).

3.3.1. Erzeugung des Product Feed auf FirstSpirit-Seite

Product Feeds müssen als CSV-, XML- oder JSON-Datei erzeugt und auf dem Server abgelegt werden, damit sie von der Intelligent Content Engine verarbeitet werden können. Basierend auf dem mitgelieferten Beispielprojekt, in dem das JSON-Format verwendet wird, skizziert das Kapitel die Erzeugung eines Product Feeds ebenfalls anhand dieses Formats.

Der folgende Code-Ausschnitt zeigt beispielhaft eine solche JSON-Datei:

Product Feed als JSON-Datei. 

[
   {
      "sku": "1085",
      "name": "DS 1400 modular",
      "url": "http://mithrasenergy.com/content/Products/Thin-layer-modules/Thinlayer-Product_1085.html",
      "price": 123.45,
      "in_stock": true,
      "image_url": "http://mithrasenergy.com/.../thinlayermodules/thin-layer-solar-panel_900x600.jpg",
      "categories": "THIN_LAYER_MODULES",
      "group_id": "5"
   },
   {
      "sku": "1074",
      "name": "DS 1200 block",
      "url": "http://mithrasenergy.com/content/Products/Thin-layer-modules/Thinlayer-Product_1074.html",
      "price": 234.56,
      "in_stock": false,
      "image_url": "http://mithrasenergy.com/.../thinlayermodules/close-up-of-thin-layer-solar-panel2_900x600.jpg",
      "categories": "THIN_LAYER_MODULES",
      "group_id": "5"
   }
]

Erfolgt die Pflege der Produktdaten mit einer externen Software, muss diese für die Erzeugung der Datei genutzt werden. Andernfalls lässt sich FirstSpirit nicht nur für die Datenpflege, sondern auch für die Bereitstellung der Datei einsetzen.

Dafür bietet sich die Persistierung der Daten in einer Datenquelle an. Mithilfe des während der Installation angelegten Ausgabekanals lassen sie sich dann in dann ins JSON-Format konvertieren.

Das mitgelieferte Beispielprojekt enthält die Tabellenvorlage mithras.products, deren JSON-Ausgabekanal wie folgt gefüllt ist:

JSON-Kanal der Tabellenvorlage. 

$CMS_SET(product, {:})$                                                                 ❶
$CMS_SET(void, product.put("sku", ""+#row.id))$                                         ❷
$CMS_SET(void, product.put("name", tt_name))$
$CMS_SET(void, product.put("image_url", ref(tt_mainPicture, abs:1).url))$               ❸
$CMS_SET(void, product.put("price", tt_price))$
$CMS_SET(void, product.put("in_stock", true))$
$CMS_SET(groupId, "")$
$CMS_SET(categories, [])$                                                               ❹

$CMS_FOR(for_category,tt_categories)$
   $CMS_SET(void, categories.add(for_category.tt_name))$
   $CMS_SET(groupId, ""+for_category.fs_id)$
$CMS_END_FOR$

$CMS_SET(void, product.put("group_id", groupId))$
$CMS_SET(joiner, class("com.google.common.base.Joiner"))$
$CMS_SET(void, product.put("categories", joiner.on("|").join(categories)))$
$CMS_SET(productPageRef, "")$

$CMS_IF(groupId == "320")$
   $CMS_SET(productPageRef, "pageref:thinlayermodule_product")$
$CMS_ELSIF(groupId == "321")$
   $CMS_SET(productPageRef, "pageref:cristallinemodules_product")$
$CMS_ELSIF(groupId == "322")$
   $CMS_SET(productPageRef, "pageref:electricsupplyunits_product")$
$CMS_ELSIF(groupId == "323")$
   $CMS_SET(productPageRef, "pageref:solarenergystorage_product")$
$CMS_ELSIF(groupId == "324")$
   $CMS_SET(productPageRef, "pageref:powerinverter_product")$
$CMS_ELSIF(groupId == "325")$
   $CMS_SET(productPageRef, "pageref:additionalequipment_product")$
$CMS_END_IF$

$CMS_SET(void, product.put("url", ref(productPageRef, contentId: #row.fs_id, abs:1, templateSet: "html").url))$   ❺
$CMS_SET(void, jsonProducts.add(product))$   

Im ersten Schritt findet die Initialisierung der Variablen product als leere Map statt. Sie dient der Erzeugung eines Produkts, das im letzten Schritt der Liste aller Produkte übergeben wird.

Anschließend erfolgt die Definition des Felds sku, dem die ID des entsprechenden Datensatzes zugewiesen wird.

Sowohl die URL des Produktbildes als auch die URL der Produktdetailseite muss jeweils als absolute URL gerendert werden. Dafür ist der Parameter abs:1 zu verwenden.

Im nächsten Schritt wird die Variable categories mit den Namen und IDs der im Formular ausgewählten Kategorien gefüllt. Die Kategorien werden dabei jeweils durch eine Pipe (|) getrennt.

Abschließend wird das erzeugte Produkt der Liste jsonProducts hinzugefügt. Sie wird im Ausgabekanal der zugehörigen Seitenvorlage erzeugt.

Im Beispielprojekt kann die Tabellenvorlage jeder Seite hinzugefügt werden, die auf der Seitenvorlage product_feed basiert. Ihr JSON-Ausgabekanal enthält folgenden Inhalt:

JSON-Kanal der Seitenvorlage. 

$CMS_TRIM(level:3)$
$CMS_SET(jsonProducts, [])$                 ❶
$CMS_VALUE(#global.page.body("products"))$  ❷
$CMS_VALUE(jsonProducts.toJSON)$            ❸
$CMS_END_TRIM$

Im ersten Schritt wird die Variable jsonProducts als leere Liste initialisiert, die dem zu erzeugenden Product Feed entspricht.

Danach wird der Inhaltsbereich ausgegeben, in dem die Tabellenvorlage eingebunden ist. In ihrem Ausgabekanal wird die Liste jsonProducts mit den einzelnen Produktdaten gefüllt.

Abschließend erfolgt die Ausgabe der ins JSON-Format konvertierten Liste.

Nachdem der Feed angelegt wurde, ist es wichtig, eine erste Freigabe und ein erstes Deployment des Feeds durchzuführen, damit er von der Intelligent Content Engine gelesen werden kann.

3.3.2. Einbindung des Product Feeds innerhalb der Intelligent Content Engine

Bei einem Besuch der Webseite führen Kunden unterschiedlichste Aktionen durch, die eine Ableitung verschiedener Informationen ermöglichen. Für die Ermittlung dieser Informationen sind spezifische Analysen notwendig, die FirstSpirit ICE-seitig eine Verwendung des Product Feeds erfordern. Dieser wird aufgrund regelmäßiger Abrufe kontinuierlich aktualisiert und muss daher über das Internet erreichbar sein. Die Angabe einer URL in der folgenden Form erlaubt es dabei, den Zugriff auf den Product Feed per HTTP Basic Auth zu beschränken: http://user:password@url

Für die Durchführung der notwendigen Schritte in der Intelligent Content Engine wird vorausgesetzt, dass die FirstSpirit-seitige Erzeugung des Product Feeds abgeschlossen und die zugehörige CSV-, XML- oder JSON-Datei auf dem Server verfügbar ist. Erst danach kann die FirstSpirit ICE-seitige Einbindung erfolgen. Öffnen Sie dazu das FirstSpirit ICE Management-Interface und selektieren Sie den Punkt SettingsData Feeds, um per Klick auf Add new einen neuen Product Feed anzulegen.

Product Feed anlegen
Abbildung 7. Product Feed anlegen


Zusätzlich zu einem beliebigen Namen muss als Feed Source die URL der auf dem Server abgelegten Product Feed-Datei angegeben werden. Per Klick auf den Button Preview können die Einstellungen auf ihre Richtigkeit hin geprüft und anschließend mit dem Button Save & Activate gespeichert werden. Ab diesem Zeitpunkt wird der Product Feed für die Seitenanalyse genutzt und kann ohne weitere Anpassungen beispielsweise im Audience Manager für die Segmentierung der Kunden nach betrachteten Produkten verwendet werden.

Product Feed-Einstellungen
Abbildung 8. Product Feed-Einstellungen


3.3.3. Events

Die Intelligent Content Engine ermöglicht die zielgruppenspezifische Auswertung von Kundenaktionen auf der Seite. In diesem Kapitel wird stellvertretend das Purchase-Event skizziert. Nach der Durchführung eines Bezahlvorgangs erlaubt es beispielsweise die Bestimmung der Einnahmen in Abhängigkeit einer bestimmten Zielgruppe oder den durchschnittlichen Einkaufswert eines einzelnen Kunden.

Die Kundenaktion löst die Übermittlung vordefinierter Daten an die Intelligent Content Engine aus. Im Fall des Purchase-Events lassen sich beispielsweise der Gesamtwert des Warenkorbs sowie dessen Einzelpositionen an FirstSpirit ICE übertragen.

DY.API('event', {
   name: 'Purchase',
   properties: {
      dyType: 'purchase-v1', ❶
      value: 90.55, ❷
      currency: 'any supported currency code', ❸
      cart: [

         {
            productId: 'item-34454', ❹
            quantity: 1,
            itemPrice: 65.87 ❺
         },
         {
            productId: 'sku-4324-bg',
            quantity: 2,
            itemPrice: 12.34
         }
      ]
   }
});

An dieser Stelle erfolgt die Identifierzierung des Events als ein Einkauf.

Die Variable value gibt den Gesamtwert des Warenkorbs in der Zahlungswährung als float-Wert an.

An dieser Stelle lässt sich optional eine alternative Währung angeben, die vom Site-Standard abweicht.

Die Variable productId enthält die Artikelnummer des Produkts, die exakt mit dem SKU-Wert aus dem Product Feed übereinstimmen muss.

Die Variable itemPrice entspricht dem Stückpreis des Produkts und ist ebenfalls ein float-Wert, wie die zuvor definierte Variable value.

Nachdem Kunden auf der Seite Produkte gekauft haben, lässt sich der erzielte Ertrag auf dem Dashboard ablesen. Auch Auswertungen wie der durchschnittlichen Wert des Warenkorbs sind (mit einem Tag Verzögerung) abrufbar.

Beispiel-Dashboard in FirstSpirit ICE mit Optimierungspotential
Abbildung 9. Beispiel-Dashboard in FirstSpirit ICE mit Optimierungspotential


4. Rechtliche Hinweise

Das Intelligent Content Engine-Modul ist ein Produkt der e-Spirit AG, Dortmund, Germany.

Für die Verwendung des Modules gilt gegenüber dem Anwender nur die mit der e-Spirit AG vereinbarte Lizenz.

Details zu möglicherweise fremden, nicht von der e-Spirit AG hergestellten, eingesetzten Software-Produkten, deren eigenen Lizenzen und gegebenenfalls Aktualisierungs-Informationen, finden Sie in der Datei ice-license-info.html, die mit dem Modul ausgeliefert wird.