FAQ

Kategorie-Slider ausblenden #

Wenn eine Clerk.io Recommendation zu einer Kategorieseite hinzugefügt wird, die nur wenige Produkte enthält, werden auf der Seite die gleichen Produkte angezeigt.

Um dies zu vermeiden, kannst du die Recommendation auf Kategorieseiten ausblenden, indem du eine if-Abfrage im Recommendation Design Code hinzufügst.

Ändere die Zahl in der if-Abfrage auf die Mindestanzahl der Produkte, die benötigt wird, um die Recommendation anzuzeigen.

{% if products.length > 7 %}
 
 <!-- Recommendation code -->

{% endif %}

Beispiel:

{% if products.length > 7 %}
<div class="clerk-wrapper">
    <div class="clerk-headline-wrapper">
        <h2 class="clerk-headline">{{headline}}</h2>
    </div>
    <div class="clerk-slider-wrapper">
        <div class="clerk-slider">
            {% for item in products %}
            <div class="clerk-slider-content">
                <!-- START PRODUCT CARD -->
                <!-- END PRODUCT CARD -->
            </div>
            {% endfor %}
        </div>
    </div>
</div>
{% endif %}

Dieser Ansatz blendet lediglich den Slider aus, zählt aber dennoch als Recommendation-Nutzung. Für wenige Kategorien funktioniert diese Methode gut.

Wenn du jedoch viele Kategorien mit wenigen Produkten hast, empfehlen wir stattdessen, das Einfügen des Sliders auf Server-Ebene zu blockieren.

Kompatible Produkte empfehlen #

Die KI von Clerk empfiehlt Produkte basierend darauf, was am wahrscheinlichsten zusammen gekauft wird. Das funktioniert für die meisten Shops sehr gut, aber einige Kataloge enthalten Produkte, die physisch oder technisch kompatibel sein müssen – zum Beispiel Autoteile, elektronische Komponenten oder Maschinenteile.

In solchen Fällen reicht es nicht, wenn ein Produkt beliebt ist. Es muss auch passen zu dem Produkt, das ein Kunde ansieht.

Die Lösung besteht darin, deine Produkte mit Attributen zu versehen, die die Kompatibilität definieren, und dann dynamisches Filtern zu nutzen, um Empfehlungen nur auf passende Produkte zu beschränken.

Die KI von Clerk bestimmt weiterhin, welche Produkte am besten angezeigt werden – aber nur im durch den Filter eingeschränkten Bereich. Das bedeutet, du bekommst beides: intelligente Sortierung innerhalb einer kompatiblen Auswahl.

Attribute hinzufügen #

Die benötigten Attribute hängen davon ab, wie Kompatibilität in deinem Katalog funktioniert. Diese sollten als Teil deiner Produktdaten an Clerk übermittelt werden, entweder über deine Integration oder per API.

Du kannst überprüfen, ob deine Attribute verfügbar sind, indem du zu Data > Products gehst und ein beliebiges Produkt öffnest.

Hier sind drei gängige Muster, von einfach bis komplex.

Einzelnes Attribut #

Wenn alle Produkte desselben Herstellers garantiert kompatibel sind, füge den Hersteller als Attribut zu jedem Produkt hinzu. Filtere dann die Empfehlungen so, dass nur Produkte desselben Herstellers angezeigt werden.

Definiere in deinem Einbettungscode eine Variable mit dem aktuellen Hersteller und verwende sie als Filter:

<span class="clerk"
      data-template="@product-page-alternatives"
      data-products='["CURRENT_PRODUCT_ID"]'
      data-filter="vendor = $product_vendor">
</span>

var product_vendor = "ACME Corp";

So sieht ein Kunde, der ein Produkt von ACME Corp betrachtet, nur Empfehlungen desselben Herstellers.

Mehrere Attribute #

Manchmal reicht ein einzelnes Attribut nicht aus. Zum Beispiel muss ein Autoteil sowohl zur Marke als auch zum Modell des Fahrzeugs passen.

Du kannst mehrere Bedingungen in einem Filter kombinieren:

<span class="clerk"
      data-template="@product-page-alternatives"
      data-products='["CURRENT_PRODUCT_ID"]'
      data-filter="make = $product_make and model = $product_model">
</span>

var product_make = "Toyota";
var product_model = "Corolla";

Es werden nur Produkte angezeigt, die Marke und Modell entsprechen.

Kompatibilitätsgruppen #

In komplexeren Katalogen hat jedes Produkt eine einzigartige Liste anderer Produkte, mit denen es kompatibel ist – das lässt sich nicht allein durch gemeinsame Attribute abbilden.

Die Lösung ist, eine Gruppenkennung (group identifier) zu berechnen, basierend auf dem Satz kompatibler Produkt-IDs, und sie als Attribut zu speichern. Produkte mit dem exakt gleichen Set kompatibler Artikel erhalten die gleiche Kennung, sodass du danach filtern kannst.

Zum Beispiel: Wenn die Produkte A, B und C kompatibel miteinander sind, kannst du einen Hash aus ihren sortierten IDs berechnen und als compatibility_group-Attribut speichern. Dann filtere danach:

<span class="clerk"
      data-template="@product-page-alternatives"
      data-products='["CURRENT_PRODUCT_ID"]'
      data-filter='compatibility_group = $product_group'>
</span>

var product_group = "a1b2c3d4";

Dieser Ansatz eignet sich gut, wenn die Kompatibilitätsbeziehungen aus einer externen Datenbank oder einem PIM-System stammen. Der Hash sollte immer dann neu berechnet werden, wenn sich die Kompatibilitätsdaten ändern, und zusammen mit den Produktdaten an Clerk übermittelt werden.

Tipp: Falls ein Produkt zu mehreren Kompatibilitätsgruppen gehören kann, speichere die Kennungen als Listenattribut und nutze den Operator in anstelle von =. Mehr zu Filter-Syntax.

Den richtigen Ansatz wählen #

Starte mit dem einfachsten Ansatz, der deinen Anwendungsfall abdeckt. Du kannst jederzeit weitere Attribute ergänzen, wenn du mehr Kontrolle benötigst.

Für eine ausführliche Betrachtung aller Möglichkeiten, Filter in Einbettungscodes zu nutzen, siehe Dynamisches Filtern.

Recommendations im dynamischen Sidecart anzeigen #

Ein Sidecart ist ein Warenkorb-Drawer, Miniwarenkorb, Basket-Overlay oder eine andere Warenkorb-Oberfläche, die sich öffnet und aktualisiert, ohne eine neue Seite zu laden. Sein HTML kann sich ändern, wenn ein Besucher ein Produkt hinzufügt, entfernt oder eine Menge anpasst.

Recommendations in solch einem Warenkorb müssen dem Live-Status des Warenkorbs folgen. Eine normale Injection, die nur beim Laden der Seite gerendert wird, reicht nicht aus. Die Implementierung muss Sidecart, Warenkorb-Ereignisse, das Clerk.io Element und das Recommendation Design koordinieren.

Bevor du beginnst #

Untersuche den Live-Sidecart, bevor du das Element erstellst oder das Design-Script schreibst. Notiere den Sidecart-Container, Inhaltsbereich, die Selector und das Attribut für Produkt-IDs, Ladeindikator, Events bei Warenkorb-Aktualisierung und ob durch Updates der Body des Sidecarts oder der gesamte Container ersetzt wird.

Kopiere keine Selector, Attribute oder Events aus einem anderen Shop. Das Markup von Sidecarts unterscheidet sich je nach Theme und Plugin. Nutze die vorhandenen Warenkorb-Events der Plattform, so weit sie zuverlässig sind; sonst verwende den kleinstmöglichen gefilterten MutationObserver, um Änderungen am Warenkorb zu erkennen. Vermeide es, den ganzen body ohne Filter zu beobachten, denn das gerenderte Clerk.io-Markup kann den Observer erneut auslösen.

Element erstellen #

Erstelle ein separates Element für den Sidecart. Nutze die recommendations/complementary API und die Best Cross-Sell Products Logik. Konfiguriere es so, dass die Produkt-IDs aus dem Live-Warenkorb gelesen werden, Produkte im Warenkorb ausgeschlossen werden und etwa vier bis acht Produkte zurückgegeben werden.

Die bevorzugte Konfiguration ist, die Cart-IDs in den Element-Einstellungen zu übergeben: Setze die API auf recommendations/complementary, den Produkttyp auf products, die ID-Quelle auf das Element und den ID-Selector sowie das Attribut auf die im Sidecart gefundenen Werte.

Falls der Sidecart beim Initialisieren des Elements keine Produkt-IDs enthält, setze die Parameter stattdessen aus dem Design-Script:

contentElement.setAttribute("data-api", "recommendations/complementary");
contentElement.setAttribute("data-products", ids.join(","));
contentElement.setAttribute("data-exclude", ids.join(","));
contentElement.setAttribute("data-limit", "8");

Clerk("content", "#" + contentElement.id, function (content) {
  content.param({
    api: "recommendations/complementary",
    products: ids,
    exclude: ids,
    limit: 8
  });
});

Betrachte diese Script-basierte Konfiguration als Fallback. Sie muss ausgeführt werden, nachdem die aktuellen Warenkorb-IDs verfügbar sind – nicht nur beim ersten Laden der Seite.

Element montieren #

Platziere das Element an einer stabilen Position und verschiebe das gerenderte Recommendation-Root nach dem Rendern durch Clerk.io in den Sidecart. Verwende eigenständige clerk--Klassen, damit das Design keine Stile anderer Anbieter wie hr- oder aw- erbt.

Auf Desktop kann ein Recommendation-Rail neben dem Sidecart stehen:

.clerk-sidecart-recs {
  position: absolute;
  top: 0;
  right: 100%;
  width: 250px;
  height: 100vh;
}

Falls die Plattform das Rail beschneidet, füge overflow: visible !important zur Sidecart-Host-Klasse hinzu. Auf Mobilgeräten verschiebe das Root in den Sidecart-Body und verwende position: static.

Recommendations aktuell halten #

Warenkorb-Aktionen lösen oft mehrere Events in kurzer Folge aus und können den Body des Sidecarts ersetzen. Debounciere Warenkorb-Events und relevante DOM-Änderungen und warte, bis der Warenkorb aktualisiert ist, bevor du renderst.

Verfolge einen Schlüssel, der aus den aktuellen Produkt-IDs gebildet wird, z.B. ids.join(","). Rendere nur, wenn sich der finale Schlüssel ändert. Falls Mengenänderungen Empfehlungen beeinflussen sollen, nimm die Mengen mit in den Schlüssel auf; andernfalls ist eine reine Mengenänderung kein Grund für eine neue Recommendation-Anfrage.

Nutze ein Render-Lock und eine kurze Cooldown-Periode pro Schlüssel, um überlappende oder wiederholte Render-Vorgänge zu verhindern, während Fragmente sich setzen. Wenn das Recommendation-Root während einer Aktualisierung entfernt wird, stelle es einmalig für den gleichen Cart-Schlüssel wieder her.

Verfolge den Cart-Key sowohl am Element als auch am sichtbaren Recommendation-Root. Vergleiche vor Anwendung einer asynchronen Antwort den Response-Key mit dem aktuellen Cart-Key. Das verhindert, dass eine alte Antwort die Recommendations für einen aktuelleren Warenkorb überschreibt.

var key = ids.join(",");
contentElement.setAttribute("data-products", ids.join(","));
contentElement.setAttribute("data-exclude", ids.join(","));
contentElement.setAttribute("data-clerk-sidecart-request-key", key);
root.setAttribute("data-clerk-sidecart-render-key", key);

if (getCartProductIds().join(",") !== key) return;

Verwende nicht einfach die Präsenz von bestehenden Produktkarten als einzige Absicherung. Das Initial-Rendering kann erfolgen, bevor Warenkorb-IDs verfügbar sind, und sonst den Sidecart auf den falschen Produkten einfrieren.

Fallback-Rendering #

Wenn das Clerk.io-Root nach einem Cart-Refresh verschwindet, markiere ein manuell erzeugtes Fallback-Root mit data-clerk-sidecart-fallback="true". Blende es aus, solange es leer ist oder lädt, entferne es, wenn ein echtes Clerk.io-Root erscheint, und cache das Fallback-HTML nach Cart-Key, damit keine doppelten API-Calls bei der Wiederherstellung entstehen.

Desktop- und Mobil-Layout #

Auf Desktop kann das Recommendation-Rail neben dem Sidecart stehen. Auf Mobilgeräten setze es in den Sidecart-Inhalt und zeige jeweils nur ein Produkt an. Verwende entweder die nativen Slider-Controls von Clerk.io oder eigene Controls, aber niemals beide Pfeil-Sätze gleichzeitig.

Wenn das Design die Steuerung übernimmt, blende die generierten Controls von Clerk.io innerhalb dieses Designs aus:

.clerk-sidecart-recs .clerk-slider-nav,
.clerk-sidecart-recs .clerk-slider-prev,
.clerk-sidecart-recs .clerk-slider-next,
.clerk-sidecart-recs .clerk-slider-button,
.clerk-sidecart-recs [class*="clerk-slider-arrow"] {
  display: none !important;
}

Das Verschieben eines gerenderten Roots oder Ersetzen von Warenkorb-Fragmenten während der Slider-Initialisierung kann Produktkarten ohne sichtbare Pfeile hinterlassen. Entscheide, welcher Code die Steuerung übernimmt, und teste die Ownership nach jedem Refresh.

In den Warenkorb legen #

Falls Recommendation-Karten „In den Warenkorb“-Buttons haben, verwende den AJAX-Endpunkt der Plattform und verhindere die normale Link-Navigation. Nach Erfolg löse ggf. das Standard-Warenkorb-Event der Plattform aus und terminere einen synchronisierten, abgeschlossenen Sync. Wenn Clerk.js verfügbar ist, tracke die Aktion zusätzlich mit Clerk("cart", "add", productId, { quantity: 1 });.

Ergebnis überprüfen #

Teste einen bestehenden und einen leeren Warenkorb. Teste das Öffnen und Schließen des Sidecarts, Hinzufügen und Entfernen von Produkten, Mengenänderungen und Aktualisierung ohne kompletten Page-Reload.

Prüfe Placement des Rails auf Desktop, Inline-Platzierung auf Mobilgeräten, Ein-Produkt-Mobil-Slides, Lade-, Leere- und Fehlerzustände. Stelle sicher, dass kein leeres Überschriften-Platzhalter sichtbar ist, während der Warenkorb lädt.

Untersuche im Browser-Netzwerk-Panel die Aufrufe zu api.clerk.io. Der gleiche finale Cart-Key sollte keine doppelten Recommendation-Requests auslösen und eine ältere Antwort niemals die aktuelle Recommendations-Liste überschreiben. Füge abschließend ein empfohlenes Produkt aus dem Sidecart zum Warenkorb hinzu und prüfe, dass Cart, Tracking und Recommendations sich korrekt aktualisieren.