> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# eKomi Produktbewertung

> Produktbewertungen von eKomi im Shop anzeigen, auf der Produktdetailansicht mit oder ohne AJAX und in Produktlisten.

eKomi ist ein externer Bewertungsdienst. Die Bewertungen entstehen dort, werden dort moderiert und dort gespeichert. WEBSALE V8s holt sie ab und zeigt sie in Ihrem Shop an.

![Ekomi Bewertung](https://mintcdn.com/websaleag-44ee7ea6/kWrWhXMhC1RLz3Kh/images/ekomi_bewertung.png?fit=max\&auto=format\&n=kWrWhXMhC1RLz3Kh\&q=85\&s=1606730b706470fc26525dd67075c8f1)

Diese Arbeitsteilung ist der Kern der Sache und bestimmt, an wen Sie sich mit welcher Frage wenden.

| Aufgabe | Zuständig |
| - | - |
| Bewertung schreiben, Sterne vergeben | eKomi |
| Bewertungserinnerungen per E-Mail versenden | eKomi |
| Moderation und Freigabe der Bewertungen | eKomi |
| Anzeige der Bewertungen im Shop | WEBSALE V8s |
| Gestaltung dieser Anzeige | Sie, im Template |

Alles, was das Zustandekommen einer Bewertung betrifft, klären Sie deshalb mit Ihrem Ansprechpartner bei eKomi, nicht mit WEBSALE.

## Voraussetzungen

### Beauftragung bei eKomi

Fragen Sie bei eKomi die Interface-ID und das zugehörige Passwort an. Betreiben Sie mehrere Sprachen oder Subshops, erhalten Sie unter Umständen mehrere Interface-IDs mit je eigenem Passwort.

### Test-Bewertungen

Für den Aufbau der Anzeige brauchen Sie Bewertungen, sonst bleiben alle Bereiche leer und Sie sehen nicht, was Sie bauen. eKomi stellt Ihnen dafür Test-Bewertungen bereit und löscht sie nach Abschluss der Integration wieder.

### Freischaltung bei WEBSALE

Beantragen Sie bei der WEBSALE AG die Freischaltung der eKomi-Produktbewertung und teilen Sie dabei die Interface-IDs und Passwörter mit, dazu für jede Interface-ID den Subshop, für den sie gelten soll.

Die Zuordnung Interface-ID zu Subshop nimmt WEBSALE vor, nicht Sie. Sie steht in der Administrationskonfiguration, auf die Sie keinen Zugriff haben. Das ist auch der Grund, warum diese Angaben im Antrag vollständig sein müssen.

Einem Subshop lassen sich mehrere Interface-IDs zuordnen. Genau das macht es möglich, Bewertungen aus dem Desktop-Shop im Mobile-Shop anzuzeigen und umgekehrt. Teilen Sie im Antrag mit, ob Sie eine solche Verknüpfung wünschen und für welche Subshops.

### Warenwirtschaft

eKomi versendet die Bewertungs-E-Mails auf Basis Ihrer Bestelldaten. Ihr angeschlossenes ERP-System muss diese Daten an eKomi übergeben können. Klären Sie das vorab, denn ohne diese Übergabe entstehen keine Bewertungen und die schönste Anzeige bleibt leer.

## Einrichtung auf der Produktdetailansicht

Die folgenden vier Schritte gelten für beide Varianten, mit und ohne AJAX. Was die AJAX-Variante zusätzlich braucht, steht im übernächsten Abschnitt.

### Schritt 1: Die Shopkonfiguration ergänzen

Legen Sie in der `shop.config` den Abschnitt `<ExternalProductRating>` an, darin den Unterabschnitt `<Ekomi>`. Die Stelle innerhalb der Datei ist beliebig.

Hinter `Template` tragen Sie den Namen des Templates ein, das die eKomi-Bewertungen anzeigt. Im Unterabschnitt `<AdvancedProductRatingImages>` ordnen Sie jedem Wertebereich eine Grafik zu, je Bereich ein `<+Entry>`.

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<ExternalProductRating>
   <Ekomi>
      Template = incl_prodrating_ekomi.htm

      <AdvancedProductRatingImages>
         <+Entry>
            From-Value = 0.0
            To-Value   = 1.0
            Image      = bewertung_1.png
         </+Entry>
         <+Entry>
            From-Value = 1.0
            To-Value   = 2.0
            Image      = bewertung_2.png
         </+Entry>
         <+Entry>
            From-Value = 2.0
            To-Value   = 3.0
            Image      = bewertung_3.png
         </+Entry>
         <+Entry>
            From-Value = 3.0
            To-Value   = 4.0
            Image      = bewertung_4.png
         </+Entry>
         <+Entry>
            From-Value = 4.0
            To-Value   = 5.1
            Image      = bewertung_5.png
         </+Entry>
      </AdvancedProductRatingImages>
   </Ekomi>
</ExternalProductRating>
```

> [!WARNING]
>
> Beachten Sie den letzten Eintrag: Er reicht bis `5.1`, nicht bis `5.0`. Die Skala von eKomi geht bis 5, und in den Produktlisten gilt die Obergrenze **ausschließend**. Ein Produkt mit der glatten Durchschnittsnote 5,0 fiele bei `To-Value = 5.0` durch alle Bereiche und bekäme gar keine Grafik. Es träfe also ausgerechnet die bestbewerteten Produkte.

Legen Sie hier **keinen** Auffangeintrag mit einem weiten Bereich an, wie Sie ihn aus der WEBSALE Produktbewertung kennen. Im Bewertungstemplate des Moduls gilt der **letzte** passende Eintrag, nicht der erste. Ein Auffangeintrag am Ende würde dort jede andere Grafik verdrängen.

Der Parameter `Template` darf nicht leer sein. Ohne ihn lässt sich das Modul nicht aufrufen.

Referenz: [Abschnitt ExternalProductRating](https://dokumentation.websale.de/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/produkte-katalog-und-suche.md#externalproductrating)

### Schritt 2: Das Bewertungstemplate anlegen

![Ekomi Bewertungsbalken](https://mintcdn.com/websaleag-44ee7ea6/kWrWhXMhC1RLz3Kh/images/ekomi_bewertungsbalken.png?fit=max\&auto=format\&n=kWrWhXMhC1RLz3Kh\&q=85\&s=08d622c19377f43926adae5c6ac36836)

Das Bewertungstemplate enthält die Tags und Klammerungen für die Anzeige der eKomi-Bewertungen. Über dieses Template gestalten Sie die Anzeige.

Legen Sie es unter genau dem Namen an, den Sie in Schritt 1 hinter `Template` eingetragen haben, und speichern Sie es in Ihrem Templateverzeichnis, beispielsweise `benutzer/templates/translation`.

Materialien: [incl\_prodrating\_ekomi.htm](https://dokumentation.websale.de/v8s/materialien/materialien-ekomi-produktbewertung.md#die-dateien-im-uberblick)

Nehmen Sie die Vorlage aus den Materialien als Ausgangspunkt. Sie enthält die Tags und die Klassennamen für die Bewertungsbalken bereits in der richtigen Verschachtelung.

### Schritt 3: Die Bewertungsbalken gestalten

Die Vorlage bringt die Klassennamen für die Bewertungsbalken mit, die Gestaltung selbst liegt bei Ihnen. Ergänzen Sie Ihre Styles-Datei um die folgenden Regeln.

```css theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
.rating_ekomi_graphic_line {
   margin-bottom: 2px;
}

.rating_ekomi_graphic_line a {
   margin-right: 5px;
   text-decoration: none;
}

.rating_ekomi_graphic_line a:hover {
   text-decoration: underline;
   cursor: pointer;
}

.rating_ekomi_graphic_line_complete {
   margin-right: 5px;
   background: #f4f4f4;
   border: 1px solid #ddd;
   display: inline-block;
   vertical-align: middle;
   width: 180px;
   height: 18px;
   position: relative;
}

.rating_ekomi_graphic_line_complete a {
   font-size: 11px;
}

.rating_ekomi_graphic_line_filler {
   background: #ffc757;
   height: 100%;
}

.rating_ekomi_graphic_line_0 a,
.rating_ekomi_graphic_line_0 a:hover {
   color: #999;
   text-decoration: none !important;
   cursor: default;
}

.rating_ekomi_graphic_score {
   color: #666;
   position: absolute;
   right: 10px;
   top: 3px;
}
```

Die Klasse `rating_ekomi_graphic_line_0` gilt für Bewertungsstufen ohne eine einzige Stimme. Der Balken bleibt dort leer, und der Link führt ins Leere, weil es nichts zu filtern gibt. Deshalb ist er in diesen Regeln ausgegraut und nicht anklickbar gestaltet.

Materialien: styles.css für die Bewertungsbalken

### Schritt 4: Das Modul auf der Produktdetailansicht aufrufen

![Ekomi Bewertung Produktliste](https://mintcdn.com/websaleag-44ee7ea6/kWrWhXMhC1RLz3Kh/images/ekomi_bewertung_produktliste.png?fit=max\&auto=format\&n=kWrWhXMhC1RLz3Kh\&q=85\&s=6488b88258401fd92f0903bba8db6eef)

`WS-Module(rating_ekomi)` lädt das in Schritt 1 eingetragene Template an die Stelle des Aufrufs. Die Stelle innerhalb von `<body>` ist frei wählbar.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<body>
   ...
   {PR-Data}
      ...
      ~WS-Module(rating_ekomi)~
      ...
   {/PR-Data}
   ...
</body>
```

> [!WARNING]
>
> Der Aufruf gehört in den `<body>`, nicht in den `<head>`. Das Modul liefert sichtbaren Seiteninhalt.

Referenz: [WS-Module()](https://dokumentation.websale.de/v8s/referenz/tags/ws/shop-seite-und-technik.md)

Damit ist die Variante ohne AJAX fertig. Bei ihr wird beim Blättern oder Filtern die komplette Seite neu geladen.

## Zusätzliche Schritte für die Variante mit AJAX

Mit AJAX wird beim Blättern und Filtern nur der Bewertungsbereich neu geladen, die übrige Seite bleibt stehen. Der Unterschied ist für den Käufer deutlich spürbar, sobald er mehrere Bewertungsseiten durchsieht.

Die vier Schritte oben gelten unverändert. Dazu kommen die folgenden.

Wegweiser: [AJAX-Funktionen](https://dokumentation.websale.de/v8s/templates/ajax-funktionen.md)

### Schritt A: System-Bibliothek und Design-Komponente einbinden

Prüfen Sie, ob die WEBSALE System-Bibliothek und Ihre WEBSALE Design-Komponente auf der Produktdetailansicht `ws_product.htm` eingebunden sind, und ergänzen Sie sie gegebenenfalls.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<head>
   ...
   <script type="text/javascript" src="/$WS/ws_sysdata/js/ws-system-1.8.3.js"></script>
   <script type="text/javascript" src="../IHR_VERZEICHNIS/ws-design-1.8.3.js"></script>
   ...
</head>
```

Materialien: [WEBSALE JavaScript-Bibliothek](https://dokumentation.websale.de/v8s/materialien/websale-javascript-bibliothek.md)

### Schritt B: Die Design-Komponente erweitern

Fügen Sie die vier Funktionen in Ihre Design-Komponente ein. Sie sind die Anknüpfungspunkte für Ihre eigenen Effekte, beispielsweise für eine Ladeanzeige oder eine Fehlermeldung.

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
// eKomi Produktbewertung

// wird beim Start des Nachladens aufgerufen, beispielsweise fuer eine Ladeanzeige
function ws_AJAXloadRatingEkomiStart()
{

}

// wird aufgerufen, wenn das Nachladen erfolgreich war
function ws_AJAXloadRatingEkomiResponseSuccess()
{

}

// wird aufgerufen, wenn das Nachladen nicht erfolgreich war
function wsAJAXloadRatingEkomiResponseError()
{

}

// wird aufgerufen, wenn die AJAX-Kommunikation selbst fehlschlug,
// beispielsweise bei unterbrochener Internetverbindung
function wsAJAXloadRatingEkomiError()
{

}
```

> [!WARNING]
>
> Die Schreibweise der Namen ist uneinheitlich: Die ersten beiden Funktionen beginnen mit `ws_AJAX`, die letzten beiden mit `wsAJAX` ohne Unterstrich. Übernehmen Sie die Namen genau so, sonst werden die Funktionen nicht gefunden und Sie suchen den Fehler an der falschen Stelle.

Legen Sie die vier Funktionen auch dann an, wenn Sie zunächst keine Effekte einbauen wollen. Sie bleiben dann leer, und Sie haben später einen fertigen Platz dafür.

### Schritt C: Hinweisbereiche anlegen (optional)

Wenn Sie Meldungen anzeigen wollen, legen Sie dafür Bereiche auf der Produktdetailansicht an. Diese blenden Sie aus den Funktionen in Schritt B heraus ein und aus.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{WS-TplComment}<!-- Ladeanzeige, bis eine Erfolgs- oder Fehlermeldung moeglich ist -->{/WS-TplComment}
<div id="eKomiAJAXInfo">Bewertungen werden geladen</div>

{WS-TplComment}<!-- Meldung, falls keine Kommunikation moeglich ist -->{/WS-TplComment}
<div id="eKomiAJAXError">Es ist ein Fehler aufgetreten</div>

{WS-TplComment}<!-- Erfolgsmeldung -->{/WS-TplComment}
<div id="eKomiAJAXSuccess">Bewertungen geladen</div>
```

Blenden Sie diese Bereiche im Ausgangszustand per CSS aus und erst aus den Funktionen heraus ein. Sonst stehen beim Seitenaufruf alle drei Meldungen gleichzeitig da.

### Schritt D: Den Anzeigebereich festlegen

Der nachzuladende Bereich braucht ein HTML-Element mit einer ID. Diese ID ist die Klammer zwischen Seite und AJAX-Template, sie muss an beiden Stellen gleich lauten.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<body>
   ...
   <div id="product_rating_ekomi">
      ~WS-Module(rating_ekomi)~
   </div>
   ...
</body>
```

Der Modulaufruf steht hier innerhalb des `div`. Das ist der Aufruf aus Schritt 4, nur jetzt mit dem umschließenden Element.

### Schritt E: Das AJAX-Template anlegen

Legen Sie ein Template an, beispielsweise `ws_ajax_ekomi.htm`, und speichern Sie es in Ihrem Templateverzeichnis. Darin legen Sie einen AJAX-Bereich an, dessen Name sich aus `WS-Ajax-` und der ID aus Schritt D zusammensetzt. Innerhalb dieses Bereiches steht wiederum der Modulaufruf.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<body>
   <WS-Ajax-product_rating_ekomi>
      ~WS-Module(rating_ekomi)~
   </WS-Ajax-product_rating_ekomi>
</body>
```

> [!WARNING]
>
> Der Name des Bereiches muss die ID aus Schritt D exakt enthalten, einschließlich Groß- und Kleinschreibung. Heißt das `div` `product_rating_ekomi`, heißt der Bereich `WS-Ajax-product_rating_ekomi`. Weicht eines der beiden ab, wird nichts nachgeladen und es erscheint auch keine Fehlermeldung.

Referenz: WS-Ajax-"ID" · WS-Module()

Materialien: [ws\_ajax\_eKomi.htm](https://dokumentation.websale.de/v8s/materialien/materialien-ekomi-produktbewertung.md#die-dateien-im-uberblick)

## Bewertungen in Produktlisten anzeigen

Auf der Produktübersichtsseite `ws_category.htm`, auf der Suchergebnisseite `ws_search.htm` und in anderen Produktlisten zeigen Sie die Bewertung direkt am Produkt an, ohne das Modul aufzurufen. Dafür gibt es eigene Tags, die Sie mit dem Parameter `ekomi` aufrufen.

| Tag | Liefert |
| - | - |
| `PR-RatingVotes(ekomi)` | Zahl der Bewertungen |
| `PR-RatingScore(ekomi)` | durchschnittliche Note, einstellig nach dem Komma |
| `PR-RatingVotesPositive(ekomi)` | Zahl der positiven Bewertungen, also der Noten über 3 |
| `PR-AdvRatingScoreImg(ekomi)` | Grafik zur Note aus `<AdvancedProductRatingImages>` |

Die Tags gehören in die Schleife `@PR-Data`.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{@PR-Data}
   ...
   {PR-RatingVotes(ekomi)}
      <img src="~PR-AdvRatingScoreImg(ekomi)~" alt="">
      ~PR-RatingVotes(ekomi)~ Bewertungen
   {/PR-RatingVotes(ekomi)}
   ...
{/@PR-Data}
```

Die Klammerung `{PR-RatingVotes(ekomi)}` greift nur, wenn das Produkt mindestens eine Bewertung hat. Unbewertete Produkte bleiben damit ohne leere Sterne, und Sie brauchen keine zusätzliche Abfrage.

> [!WARNING]
>
> `PR-AdvRatingScoreImg(ekomi)` liefert den Dateinamen genau so, wie er in der Konfiguration steht, ohne das Bildverzeichnis davorzusetzen. Das ist der Unterschied zum Tag ohne Parameter. Tragen Sie in der Konfiguration deshalb einen Pfad ein, der von der Seite aus stimmt, oder ergänzen Sie den Pfad im Template vor dem Tag.
>
> `PR-RatingScoreImg(ekomi)` gibt es nicht. Für die Grafik zur eKomi-Note ist ausschließlich `PR-AdvRatingScoreImg(ekomi)` zuständig, und damit auch der Abschnitt `<AdvancedProductRatingImages>` aus Schritt 1.

Ohne Freischaltung durch die WEBSALE AG liefern alle diese Tags nichts, und die Klammerung bleibt leer. Wenn also im Template alles richtig steht und trotzdem nichts erscheint, prüfen Sie zuerst die Freischaltung.

Referenz: [PR-RatingVotes()](https://dokumentation.websale.de/v8s/referenz/tags/pr/grundlagen-und-produktdaten.md) · [PR-RatingScore()](https://dokumentation.websale.de/v8s/referenz/tags/pr/grundlagen-und-produktdaten.md) · [PR-AdvRatingScoreImg()](https://dokumentation.websale.de/v8s/referenz/tags/e-prodrating-ekomi.md#die-bewertungsgrafiken) · [PR-Data](https://dokumentation.websale.de/v8s/referenz/tags/pr/grundlagen-und-produktdaten.md#die-tags-im-uberblick)

## Bewertungen als Rich Snippet übergeben

Die eKomi-Bewertungen lassen sich über Mikrodaten an die Suchmaschinen übergeben. Damit erscheinen die Sterne in den Suchergebnissen und nicht erst auf Ihrer Seite.

Wegweiser: [Mikrodaten (Rich Snippets)](https://dokumentation.websale.de/v8s/seo/strukturierte-daten-rich-snippets.md), Abschnitt Mikrodaten aus eKomi Produktbewertungen

## Verwandte Themen

* Wegweiser: [Beschreibung des Produktbewertungs-Moduls](https://dokumentation.websale.de/v8s/websale-produktbewertung/beschreibung-des-produktbewertungs-moduls.md)
* Wegweiser: [AJAX-Funktionen](https://dokumentation.websale.de/v8s/templates/ajax-funktionen.md)
* Wegweiser: Mikrodaten (Rich Snippets)


## Related topics

- [Materialien eKomi Produktbewertung](https://dokumentation.websale.de/v8s/materialien/materialien-ekomi-produktbewertung.md)
- [E-PRODRATING-EKOMI_ (eKomi Produktbewertung)](https://dokumentation.websale.de/v8s/referenz/tags/e-prodrating-ekomi.md)
- [Produkte, Katalog und Suche](https://dokumentation.websale.de/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/produkte-katalog-und-suche.md)
- [Produktlisten sortieren](https://dokumentation.websale.de/v8s/funktionen-fuer-produktlisten/produktlisten-sortieren.md)
- [Strukturierte Daten und Rich Snippets](https://dokumentation.websale.de/v8s/seo/strukturierte-daten-rich-snippets.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.