akleiber/CSE-de.md Secret

## CSE-de.md

      
    Raw
  

              CSE-de.md
            
          
Table of Contents  generated with DocToc

8select CSE - Technische Dokumentation

Wie wird die 8select Curated Shopping Engine eingebunden?

Tenant-Id
Die 8select Engine einbinden
Ein 8select Widget einbinden

PSP-TLV - Liste von Sets anzeigen
PSP-PSV - Ein bestimmtes Set anzeigen
SYS-PSV - Ein passendes Set zur SKU anzeigen

SYS-PSV mit anderer SKU neuladen


SYS-PSV-Button - Button über den zum Set gesprungen werden kann
SYS-ACC - Ergänzende Vorschläge zu einer in den Warenkorb gelegten SKU anzeigen

Widget-Element
Parameter
CSS Klassen
Beispiel Antwort vom Endpunkt
Widget-Element initialisieren


Callbacks

SYS-PSV Callback
SYS-ACC Callback


Lazy Loading
Container-Elemente / Überschriften / Erweiterungen

Beispiel mit Container-Element


Funktionsweise der 8select CSE
Web Tracking aka. Eightlytics für KPIs und Abrechnung

Eightlytics einbinden


Eightlytics API

eightlytics('purchase', order)


8select Widget API

Allgemein

initCSE()


Shop-Your-Set
reinitSys(newSku, [oldSku])


8select CSE - Technische Dokumentation

Wie wird die 8select Curated Shopping Engine eingebunden?

Die 8select CSE wird über ein JavaScript Snippet geladen. 8select Widgets werden mit Hilfe von div-Elementen in Ihrem Shop platziert.
Tenant-Id

In vielen Snippets befindet sich der Wert your-company. Dieser muss durch Ihre Tenant-Id ersetzt werden.
Die 8select Engine einbinden

Den folgenden Code in Ihrem HTML Dokument möglichst oben im <head> Tag einfügen.
<script async src="https://widget.your-company.8select.io/loader.js"></script>
Wenn ältere Browser unterstützt werden müssen, die noch nicht mit dem async Attribut umgehen können, kann alternativ folgender Code im <head> Tag eingefügt werden:
<script type="text/javascript">/*{literal}<![CDATA[*/
    (function(d, s) {
        var script = d.createElement(s);
        script.src   = '//widget.your-company.8select.io/loader.js';
        var entry = d.getElementsByTagName(s)[0];
        entry.parentNode.insertBefore(script, entry);
    })(document, 'script');
/*]]>{/literal}*/</script>
Der Code /*{literal}<![CDATA[*/ und /*]]>{/literal}*/ ist für Template Engines wie Drupal, Joomla oder Smarty und sorgt dafür, dass das Snippet auch dort einwandfrei funktioniert.
Ein 8select Widget einbinden

Den folgenden Code an der Stelle einbinden, an der das entsprechende Widget angezeigt werden soll.
PSP-TLV - Liste von Sets anzeigen

<div data-stylefactor="42" data-8select-widget-id="psp-tlv"></div>
data-stylefactor grenzt die angezeigten Sets auf ein bestimmtes Thema ein. Den Stylefactor entnehmen Sie bitte der Management-Console (CSE-MCON).
PSP-PSV - Ein bestimmtes Set anzeigen

<div data-set-id="42" data-8select-widget-id="psp-psv"></div>
data-set-id definiert welches Set angezeigt werden soll. Die Set-Id entnehmen Sie bitte der Management-Console (CSE-MCON).
SYS-PSV - Ein passendes Set zur SKU anzeigen

<div data-sku="42" data-8select-widget-id="sys-psv"></div>
data-sku ist die SKU des aktuellen Artikels. Die CSE sucht basierend darauf ein Set welches diesen Artikel enthält.
Der Wert für data-sku muss dynamisch gesetzt werden und muss einer der im Stammdatenfeed übergebenen SKU oder Master-SKU entsprechen.
SYS-PSV mit anderer SKU neuladen

Wenn Ihr Shop Varianten via Ajax nachlädt, so müssen Sie das Shop-Your-Set Widget über die geänderte SKU informieren.
window._8select.reinitSys('21', '42');

Siehe https://gist.github.com/akleiber/8e4916d96b994428389f747e7fb79020#reinitsysnewsku-oldsku
SYS-PSV-Button - Button über den zum Set gesprungen werden kann

Der SYS-PSV-Button weißt den Kunden darauf hin, dass es zum aktuell angesehenen Artikel ein passendes Set gibt.

Der Kunde kann mit einem Klick auf den Button direkt zum Set runterscrollen oder springen.
Ein beliebiges Element mit dem Attribute data-8select-widget-id="sys-psv-button" wird als SYS-PSV-Button erkannt. Dieses Element sollte initial versteckt sein. Durch die Definition eines Callbacks wird der Button eingeblendet, wenn ein Set zum Artikel verfügbar ist.
Beispiel
<button
    data-8select-widget-id="sys-psv-button"
    onclick="_8select.utils.goToWidget(document.querySelectorAll('[data-8select-widget-id=sys-psv]')[0].getAttribute('data-8select-widget-uuid'), 0);" 
    ontouchend="_8select.utils.goToWidget(document.querySelectorAll('[data-8select-widget-id=sys-psv]')[0].getAttribute('data-8select-widget-uuid'), 0);" 
    type="submit" 
    style="display: none;"
  >Passender Look</button>

window._eightselect_config = window._eightselect_config || {}
window._eightselect_config['sys'] = {
  callback: function (error, sku, widgetUuid) {
    if (error) {
      // something went wrong or no set was found for given sku
      return
    }
    // everything fine and a set was found for given sku
    // we can show button that let's the customer know that we have a set and allows him/her to navigate to the widget with one click
    document.querySelector('[data-8select-widget-id=sys-psv-button]').style.display = 'block'
  }
}

_8select.utils.goToWidget(widgetUuid, offset)

SYS-ACC - Ergänzende Vorschläge zu einer in den Warenkorb gelegten SKU anzeigen

Widget-Element

<div data-sku="42" data-include-css="true" data-8select-widget-id="sys-acc"></div>
Parameter

data-sku ist die SKU des aktuellen Artikels. Die CSE sucht basierend darauf ein Set welches diesen Artikel enthält.
Der Wert für data-sku muss dynamisch gesetzt werden und muss eine der im Stammdatenfeed übergebenen SKU oder Master-SKU entsprechend.
data-include-css kann true oder false sein. Wird der Wert weggelassen, entspricht das dem Wert false.
Steht der Wert auf true so wird ein Basis CSS für ein CSS-Grid basierend auf https://purecss.io/grids/ ausgeliefert.
Außerdem werden CSS Deklarationen für einzelne Elemente ausgeliefert. Kommen neue Elemente hinzu werden diese z.B. über die Deklaration display:none ausgeblendet.
CSS Klassen

Folgende CSS Klassen sind nutzbar. Für manche Klassen sind Standardwerte gesetzt. Diese können mit Hilfe von !important überschrieben werden.
.-eightselect-item-list {
}

.-eightselect-item {
}

.-eightselect-item-image {
}

.-eightselect-item-body {
}

.-eightselect-item-brand {
}

.-eightselect-item-name {
    display: none;
}

.-eightselect-item-sales-price {
}

.-eightselect-item-stroke-price {
}
Beispiel Antwort vom Endpunkt

Das HTML des zurückgelieferten Widgets hat folgende Struktur:
<div class="-eightselect-item-list -eightselect-g">
    <div class="-eightselect-item -eightselect-u-1-4">
        <a href="#">
            <div class="-eightselect-item-image">
                <img src="" />
            </div>
            <div class="-eightselect-item-body">
                <div class="-eightselect-item-brand">Hugo Boss</div>
                <div class="-eightselect-item-name">Sakko</div>
                <div class="-eightselect-item-stroke-price">299,99</div>
                <div class="-eightselect-item-sales-price">249,99</div>
            </div>
        </a>
    </div>
    <div class="-eightselect-item -eightselect-u-1-4">
        <a href="#">
            <div class="-eightselect-item-image">
                <img src="" />
            </div>
            <div class="-eightselect-item-body">
                <div class="-eightselect-item-brand">Hugo Boss</div>
                <div class="-eightselect-item-name">Sakko</div>
                <div class="-eightselect-item-stroke-price">299,99</div>
                <div class="-eightselect-item-sales-price">249,99</div>
            </div>
        </a>
    </div>
    <div class="-eightselect-item -eightselect-u-1-4">
        <a href="#">
            <div class="-eightselect-item-image">
                <img src="" />
            </div>
            <div class="-eightselect-item-body">
                <div class="-eightselect-item-brand">Hugo Boss</div>
                <div class="-eightselect-item-name">Sakko</div>
                <div class="-eightselect-item-stroke-price">299,99</div>
                <div class="-eightselect-item-sales-price">249,99</div>
            </div>
        </a>
    </div>
    <div class="-eightselect-item -eightselect-u-1-4">
        <a href="#">
            <div class="-eightselect-item-image">
                <img src="" />
            </div>
            <div class="-eightselect-item-body">
                <div class="-eightselect-item-brand">Hugo Boss</div>
                <div class="-eightselect-item-name">Sakko</div>
                <div class="-eightselect-item-stroke-price">299,99</div>
                <div class="-eightselect-item-sales-price">249,99</div>
            </div>
        </a>
    </div>
</div>
Widget-Element initialisieren

Wie alle anderen Widgets wird auch das SYS-ACC Widget automatisch vom widget-loader erkannt, sofern es von vornherein im DOM ist.
Wird das Widget-Element erst nachträglich in das DOM aufgenommen, zum Beispiel ein Modal welches über einen AJAX Aufruf gefüllt wird, so muss das Widget-Element manuell initialisiert werden.
window._8select.initCSE();

Siehe https://gist.github.com/akleiber/8e4916d96b994428389f747e7fb79020#initcse
Callbacks

Einige Widgets rufen einen Error-First-Callback bei Erfolg- bzw. Fehlerfall auf.
Darüber lässt sich beispielsweise alternativer Inhalt anstelle eines Widgets anzeigen, wenn zum Beispiel gerade kein Set für ein bestimmtes Produkt zur Verfügung steht.
SYS-PSV Callback

Für das Widget SYS-PSV wird im Erfolgs- bzw. Fehlerfall window._eightselect_config.sys.callback aufgerufen.
Beispiel
window._eightselect_config = window._eightselect_config || {}
window._eightselect_config['sys'] = {
  callback: function (error, sku, widgetUuid) {
    if (error) {
      // something went wrong or no set was found for given sku
      return
    }
    // everything fine and a set was found for given sku
    // we can show button that let's the customer know that we have a set and allows him/her to navigate to the widget with one click
    document.querySelector('[data-8select-widget-id=sys-psv-button]').style.display = 'block'
  }
}

SYS-ACC Callback

Für das Widget SYS-ACC wird im Erfolgs- bzw. Fehlerfall window._eightselect_config['sys-acc'].callback aufgerufen.
Beispiel
window._eightselect_config = window._eightselect_config || {}
window._eightselect_config['sys-acc'] = {
  callback: function (error, sku, widgetUuid) {
    if (error) {
      // something went wrong or no set was found for given sku
      alert('uh oh')
      return
    }
    // everything fine and a set was found for given sku
    alert('YEAH BABY!')

  }
}

Lazy Loading

Um Widget-Elemente erst zu laden wenn diese im sichtbaren Bereich, oder in einem bestimmten Abstand zum sichtbaren Bereich sind, kann das Attribut data-load-distance-factor gesetzt werden.
data-load-distance-factor ist optional und kann eine Zahl größer oder gleich 0 sein. Der Wert beschreibt den Faktor, den ein Widget-Element vom unteren sichtbaren Bereich entfernt sein muss, bis es geladen wird. Siehe dazu folgende Illustration.
Ist das Attribut nicht gesetzt, so werden alle Widget-Elemente direkt geladen.
Der Wert 0 startet den Ladevorgang des Widgets sobald das Element den unteren sichtbaren Bereich erreicht.
Beim Wert 1 wird der Ladevorgang bereits einen Bildschirmabstand früher gestartet. Je größer der Wert, desto früher wird ein Widget geladen.
<div data-sku="42" data-8select-widget-id="sys-psv" data-load-distance-factor="1"></div>
Container-Elemente / Überschriften / Erweiterungen

Das Widget kann an beliebiger Stelle im HTML Dokument eingebunden werden.
Sie können das Widget also nahtlos in ihr Layout einfügen.
Die 8select Sets sind dynamisch, je nach Verfügbarkeit von Produkten kann es also mehr oder weniger aktive Sets geben.
Um zu vermeiden, dass Container-Elemente allein stehen bleiben, wenn das spezifizierte Set mal nicht mehr Verfügbar ist, sollte das oberste Container-Element initial versteckt sein.
Das heißt die Eigenschaft display sollte den Wert none erhalten. Darüber hinaus muss die CSS-Klasse -eightselect-widget-container gesetzt sein.
Sobald das Widget sowie das Set geladen sind, wird das Container-Element bzw. das Widget eingeblendet.
Beispiel mit Container-Element

<div class="teaserBox -eightselect-widget-container" style="display: none;">
    <h3 class="teaserTitle">Look der Woche</h3>
    <div class="teaserWrapper">
        <div data-8select-widget-id="psp-psv" data-set-id="365"></div>
    </div>
</div>
Funktionsweise der 8select CSE

Das Loader-Script loader.js ist eine ca. 4 KB große JavaScript Datei. Dieses Script erzeugt ein FIF (Friendly IFrame) in dem die 8select CSE geladen wird.
Diese Technik verhindert das Blockieren von Downloads anderer Ressourcen. Außerdem wird das onload Event des Browsers nicht blockiert. Somit beeinflusst das Einbinden der 8select CSE in keinster Weise die Ladezeiten Ihres Shops.
Nachdem die 8select CSE geladen ist, füllt diese automatisch alle gekennzeichneten div-Elemente mit den entsprechenden Widgets.
Web Tracking aka. Eightlytics für KPIs und Abrechnung

Eightlytics ist das Web Analytics Tool von 8select, ähnlich wie z.B. Google Analytics oder Webtrekk.
Mit Hilfe unseres Web Analytics Tools sammeln wir Daten zur Nutzung der Widgets. Im Performance Dashboard können Sie so jederzeit die Performance der CSE einsehen.
Für eingebundene Widgets ist auch schon automatisch Eightlytics eingebunden.
Für die Auswertung der Umsätze die über die 8select CSE kommen, müssen Sie ein zweites JavaScript Snippet einbinden. Dies muss auf der Seite die nach einem erfolgreichen Checkout angezeigt wird erfolgen.
Eightlytics einbinden

Laden der Eightlytics Bibliothek
ACHTUNG - Die Variable tenantId muss durch ihre Tenant-Id ersetzt werden.
<script type="text/javascript">/*{literal}<![CDATA[*/
    var tenantId = 'your-company';
    window.eightlytics||function(a){a.eightlytics=function(){(a.eightlytics_queue=[]).push(arguments)};(function(b,a,d){var c=b.createElement(a);c.type="text/javascript";c.async=!0;c.src=d;b=b.getElementsByTagName(a)[0];b.parentNode.insertBefore(c,b)})(a.document,"script","https://widget." + tenantId + ".8select.io/eightlytics/eightlytics-queue.js")}(window);
/*]]>{/literal}*/</script>
Tracking von Transaktionen
ACHTUNG - Preise müssen in Cent übertragen werden - also aus 199,95 € wird 19995.
<script type="text/javascript">/*{literal}<![CDATA[*/
    window.eightlytics(
        'purchase',
        {
            customerid: '1234',
            orderid: '1234',
            products: [
                {
                  sku: '12345',
                  amount: 3,
                  price: 1199
                },
                {
                  sku: '456',
                  amount: 1,
                  price: 19995
                }
            ]
        }  
    );
/*]]>{/literal}*/</script>
Eightlytics API

eightlytics('purchase', order)

order


field
type
required
description


customerid
string
required
unique customer identifier


orderid
string
required
unique transaction identifier


products
array of product
required
which products does the order contain


product


field
type
required
description


sku
string
required
product identifier


amount
integer
required
how many units are added to the cart


price
integer
required
what does one unit cost in euro cent


{
  customerid: '1234',
  orderid: '1234',
  products: [
    {
        sku: '12345',
        amount: 3,
        price: 1199
      },
      {
        sku: '456',
        amount: 1,
        price: 19995
      }
  ]
}
8select Widget API

Allgemein

initCSE()

Wenn ihr Shop die Widget HTML-Elemente Asynchron nachläd (z.B. Shopware Einkaufswelten), dann muss nach dem Laden die CSE darüber informiert werden. Dies erfolgt durch einen Aufruf von initCSE()
window._8select.initCSE();
Shop-Your-Set

reinitSys(newSku, [oldSku])

Wenn Ihr Shop Varianten via Ajax nachlädt, so müssen Sie das Shop-Your-Set Widget über die geänderte SKU informieren.
window._8select.reinitSys('21', '42');

  
## wgt-ldr-lazy-load.pdf

      
Display the source blob

    
Display the rendered blob

    
    Raw
  

              wgt-ldr-lazy-load.pdf
            
          
      Loading

      Sorry, something went wrong. Reload?
      Sorry, we cannot display this file.
      Sorry, this file is invalid so it cannot be displayed.
      
          Viewer requires iframe.
field	type	required	description
customerid	string	required	unique customer identifier
orderid	string	required	unique transaction identifier
products	array of product	required	which products does the order contain
field	type	required	description
sku	string	required	product identifier
amount	integer	required	how many units are added to the cart
price	integer	required	what does one unit cost in euro cent