FAQ
Probleme mit deiner WooCommerce-Integration? Dieses FAQ behandelt die häufigsten Probleme und deren Lösungen, von Daten-Synchronisationsfehlern bis zur manuellen Installation von Elementen.
Manuelle Element-Installation #
WooCommerce-Themes platzieren Hooks oft an nicht standardisierten Positionen.
Das bedeutet, dass das Clerk-Plugin die Embed-Codes möglicherweise nicht automatisch einfügen kann.
Folge diesen Schritten, um Codes manuell einzufügen, wenn nötig.
Suchformular finden #
Beginne damit, dein Suchformular zu finden.
Untersuche deine Website und suche nach einzigartigem Text im Suchfeld.

Theme-Dateien aufrufen #
Öffne die FTP-Dateien deines Webshops und finde public_html > wp-content > themes.
Ziehe den themes-Ordner auf deinen Desktop, um ihn auf deinen Computer zu kopieren.
So kannst du die Dateien durchsuchen.
Im Editor öffnen #
Öffne den Ordner in deinem bevorzugten Code-Editor.
Zum Beispiel in Sublime: Project > Add Folder to Project.
Wähle den themes-Ordner aus, den du im vorherigen Schritt gespeichert hast.
Dateien durchsuchen #
Jetzt kannst du die Dateien durchsuchen.
Du kannst dich entscheiden, nur in .php-Dateien zu suchen, da dies der Standard-Dateityp für WooCommerce-Theme-Dateien ist.
Such-Links korrigieren #
Falls du die Suche bereits eingerichtet und eine Seite in WooCommerce für Suchergebnisse erstellt hast, aber dein Suchfeld nicht korrekt verlinkt, folge diesen Schritten.
Beginne damit, deinen Webshop im Browser anzusehen. Wir empfehlen Chrome.
Suche nach HTML-Code, der eindeutig dem Suchfeld zugeordnet werden kann, zum Beispiel searchform:

Suche danach in deinem Editor, um eine Liste der Dateien zu finden, die ihn enthalten:

Finde die passende Datei auf dem FTP.
Formulareinstellungen aktualisieren #
Jetzt kannst du die Einstellungen so ändern, dass Clerk auf die korrekte Seite verweist.
Du musst drei Dinge ändern:
Die URL, zu der Kunden weitergeleitet werden, ist meist im
<form>-Element hinterlegt und muss mit dem Namen der Seite übereinstimmen, die du in WooCommerce erstellt hast. Dies ist meist"soegeresultater"oder"search-results".Das
"name"-Attribut des Eingabefeldes musssearchtermlauten.Das versteckte Eingabefeld mit
name="post_type"muss auskommentiert werden.
Ein Suchformular könnte vor der Änderung so aussehen:

Und nach der Änderung so:

Nun solltest du beim Suchen zur Suchseite weitergeleitet werden: www.mywebshop.com/soegeresultater?searchterm=test.
Verwendung von Formatters #
Clerk.js erlaubt es dir, eigene JavaScript-Funktionen zu schreiben, die deinen Designs neue Funktionalitäten hinzufügen.
Formatters können auf zwei Arten hinzugefügt werden:
Über my.clerk.io > Developers > Formatters, wo jeder Formatter als separater Eintrag erstellt wird.
Als Teil der Clerk.js-Konfiguration, wobei das Tracking-Script auf allen Seiten eingebunden wird, wodurch mehrere Formatters gleichzeitig definiert werden können.
In WooCommerce befindet sich das Tracking-Skript hier: wp-content > plugins > clerkio > includes > class-clerk-visitor-tracking.php.
Beispiel-Formatter #
Ein Beispiel siehst du unten:
Clerk('config', {
key: 'O7UITkJIXqXibeQF9ONobiGGKYYKtbvh',
formatters: {
log_price: function(price) {
console.log(price);
}
}
});
Mehrere Formatters #
Du kannst beliebig viele Formatters schreiben, durch Kommas getrennt:
formatters: {
log_price: function(price) {
console.log(price);
},
calculate_discount: function(price, special_price) {
return price - special_price;
},
substring: function(text) {
var short_string = text.substring(0, 20);
return short_string;
}
}
Verwendung in Designs #
Nachdem du deine Formatter erstellt hast, kannst du sie in deinen Designs folgendermaßen verwenden:
{%raw%}{{ price | log_price }} {{ price | calculate_discount | special_price }}{%endraw%}
Damit kannst du in deinen Designs beliebige Funktionalitäten umsetzen.
HTTP-Authentifizierung #
HTTP-Authentifizierung wird oft auf Staging-Seiten verwendet, um unerwünschte Besucher zu verhindern.
Dies blockiert den Clerk-Importer und zeigt einen 401 Unauthorized-Fehler im Sync-Log an.
Du kannst dies beheben, indem du die Authentifizierungsdaten in die Import-URL einfügst.
In my.clerk.io > Data > Configuration aktualisiere deine Import-URL wie folgt:
https://USER:PASS@www.ewoksRus.com
Häufige Synchronisations-Fehler #
Hinweis: Wir empfehlen, das Plugin immer auf die neueste Version zu aktualisieren, um alle aktuellen Funktionen von Clerk zu erhalten.
Beim Import von Daten mit Clerk’s WooCommerce Plugin ist dein Webshop-Server dafür verantwortlich, Produkt-, Kategorie- und Bestelldaten an Clerk zu senden.
In einigen Fällen kann jedoch die Server-Konfiguration den Import blockieren, wodurch ein Fehler im Data Sync entsteht.
Nachfolgend findest du eine Liste der häufigsten Fehler und deren Behebung.
401 Unauthorized #
Dieser Fehler tritt auf, wenn dein Webshop oder dev-Umgebung eine HTTP-Authentifizierung erfordert.
Dies wird gelöst, indem du Benutzername und Passwort als Teil der Import-URL einfügst:
http://username:password@woocommerce.clerk.io
403 Forbidden #
Der Fehler tritt auf, wenn dein Server den Importer blockiert.
In den meisten Fällen musst du einfach die IP-Adresse des Importers auf die Whitelist setzen, um den Zugriff zu ermöglichen.
Die aktuelle IP-Adresse findest du hier.
Stelle ebenfalls sicher, dass der Public Key, Private Key und die Import URL korrekt für den Store sind, den du in my.clerk.io betreibst.
Was, wenn ich bereits eine Whitelist habe, aber der Fehler immer noch auftritt?
Wenn du die Importer-IP-Adresse bereits auf die Whitelist gesetzt hast und der Fehler weiterhin auftritt, prüfe Folgendes:
Der Authentifizierungs-Teil des Bodys kann von der Shop-Server-Anfrage entfernt werden.
Rate Limit für den Server in Bezug auf Cloudflare.
404 Not Found #
Dieser Fehler tritt auf, wenn der Importer den Link zur Datenübertragung nicht erreichen konnte.
In den meisten Fällen liegt es daran, dass das Plugin entweder:
überhaupt nicht installiert ist
durch ein Update deaktiviert wurde
ein Cache verhindert, dass der Link initialisiert wird
WooCommerce-Permalinks auf Beitragsname statt Monat und Name stehen
Folge diesen Debugging-Schritten, um den Fehler zu beheben:
Stelle sicher, dass du das Plugin korrekt installiert hast und dass es aktiviert ist. Wenn du das Plugin kürzlich automatisch aktualisiert hast, deaktiviert WooCommerce manchmal das Plugin. Wenn das passiert ist, gehe zu Plugins > Clerk und klicke auf Aktivieren.
Leere den Cache deines Webshops, bevor du erneut versuchst zu importieren.
Wenn es immer noch nicht synchronisiert, gehe in dein WooCommerce-Backend, dann zu Settings > Permalinks und ändere die Allgemeinen Einstellungen auf Monat und Name und klicke auf Änderungen speichern:

429 Too Many Requests #
Dieser Fehler tritt auf, wenn dein Server dem Importer wegen zu vieler eingehender Anfragen den Zugriff verweigert.
Du kannst das beheben, indem du entweder:
das Request Limit auf deinem Server erhöhst.
die Page Size in my.clerk.io > Data > Configuration auf einen höheren Wert setzt, damit der Importer weniger, aber größere Anfragen stellt.
Wenn du den Hosting-Anbieter Byte.nl benutzt, kommt dieser Fehler meistens durch deren Rate Limiter zustande. In diesem Fall kontaktiere den Byte.nl-Support und bitte darum, den Importer User-Agent “clerk” auf die Whitelist zu setzen.
500 Internal Server Error #
Dieser Fehler bedeutet, dass dein Server einen internen Fehler hatte und nicht angeben kann, welcher Fehler aufgetreten ist.
In diesen Fällen prüfe das Server Log, um herauszufinden, welcher Prozess abgestürzt ist und warum.
Meistens liegt es einfach an einem Produkt mit einem ungültigen Attribut oder einer Funktion, die im Webshop falsch aufgerufen wird.
Ein Beispiel für einen solchen Fehler kann nach einem Upgrade von WooCommerce und Klarna auftreten. Das Problem wird hier vom ‘woocommerce-gateway-klarna’-Plugin verursacht, das nicht aktualisiert wurde.
Wenn dies der Fall ist, gehe zu woocommerce-gateway-klarna > includes > variables-checkout.php.
Suche nach:
if ( ! is_admin() && ! empty( $klarna_country )) {
und ändere es zu:
if ( ! is_admin() && ! empty( $klarna_country ) && WC()->session ) {
503 Service Unavailable #
Dieser Fehler ist normalerweise temporär und tritt auf, wenn der Server zu beschäftigt ist, um die Anfrage zu bearbeiten.
Bitte versuche es später erneut.
Wenn das Problem bestehen bleibt, kann das bedeuten, dass der Server überlastet ist und sich an seiner Kapazitätsgrenze befindet.
Überprüfe die Serverauslastung, um die aktuelle Nutzung zu sehen.
520 Unknown Error #
Dieser Fehler stammt in der Regel von Cloudflare und tritt oft wegen eines Engpasses in WooCommerce bei größeren Page Sizes auf.
Setze dafür deine Page Size auf 50 in my.clerk.io > Data > Configuration und starte einen neuen Data Sync.
522 Connection Timed Out #
Dieser Fehler tritt in der Regel auf, wenn der Server zu beschäftigt ist oder unser Importer keinen Zugriff auf den Server erhält.
Warte einige Minuten und versuche dann erneut zu synchronisieren, um zu sehen, ob der Server ausgelastet war.
Wenn es immer noch nicht funktioniert, stelle sicher, dass du die Importer-IP auf deinem Server auf die Whitelist setzt. Die neueste IP-Adresse findest du hier.
Ungültige API-Antwort #
Dieser Fehler tritt in der Regel auf, wenn Debugging in WooCommerce aktiviert ist.
Dies sollte in einer Live-Umgebung nie aktiviert sein, da es Seiten verlangsamt und potenziell Fehlermeldungen im Frontend anzeigt.
Das Sync-Problem entsteht, wenn WooCommerce beim Generieren der Produktdaten für den Import auf einen Fehler stößt.
Dies kann behoben werden, indem du Debugging in wp-config.php deaktivierst und define('WP_DEBUG', false) setzt.
Diese Anleitung erklärt es genauer:
https://docs.woocommerce.com/document/woocommerce-product-search/api/debugging/
Und diese Anleitung zeigt einen alternativen Workaround:
https://aristath.github.io/blog/wp-hide-php-errors
Fehler werden weiterhin geloggt, auch wenn der Debug-Modus deaktiviert ist, aber sie werden in eine Datei geschrieben.
Upgrade auf Clerk.js 2 #
Clerk.js 2 ist eine schnellere und flexiblere Version unserer JavaScript-Bibliothek.
Sie erleichtert die Installation von Clerk auf jedem Webshop.
Da sich die beiden Versionen aber leicht unterscheiden, musst du folgende Schritte befolgen, um erfolgreich upzugraden.
Die zwei Hauptunterschiede in Clerk.js 2 sind:
Die Designs in my.clerk.io nutzen die Liquid Template-Sprache, können aber auch einfach mit dem Design-Editor erstellt werden.
Das Script muss direkt vor dem
</head>-Tag im Template deines Webshops eingefügt werden.
Designs erstellen #
Da Clerk.js 2 eine andere Herangehensweise bei Designs hat, musst du neue erstellen.
Du kannst deine Clerk.js 2 Designs entweder im Design Editor neu anlegen oder deinen alten Code in Liquid umwandeln.
Hier eine Beschreibung, wie du Designs in Liquid umwandelst.
Design-Editor-Option #
Gehe zu my.clerk.io > Recommendations/Search > Designs > New Design.
Wähle einen anderen Design-Typ als Blank und gib ihm einen Namen. Wir empfehlen, “V2” hinzuzufügen, damit klar ist, dass es sich um Clerk.js 2 Designs handelt.
Im Design Editor kannst du bestehende Elemente wie Namen, Bild, Button usw. bearbeiten oder neue Elemente zum Design hinzufügen.
Klicke auf Publish Design, wenn du fertig bist, und gehe zu Schritt 2 in der Anleitung.
Gehe zu Recommendations/Search > Elements und stelle dein Clerk-Element auf das neue Design um, dann klicke Update Element.
Jetzt werden die Designs vorübergehend nicht in deinem Webshop angezeigt, bis Clerk.js 2 weiter unten in dieser Anleitung eingebunden ist.
Designs umwandeln #
Da Clerk.js 2 die flexiblere Template-Sprache Liquid nutzt, musst du die Designs umwandeln.
Gehe zu my.clerk.io > Recommendations/Search > Designs > New Design.
Wähle Blank > Code und gib ihm einen Namen. Wir empfehlen, “V2” hinzuzufügen, damit klar ist, dass es sich um Clerk.js 2 Designs handelt.
Klicke auf Create Design.
Du erhältst ein leeres Design mit Produkt-HTML und CSS, das du nutzen kannst.
Gehe zurück zur Designübersicht und klicke auf Edit Design für dein Clerk.js 1 Design. Am besten in einem neuen Tab öffnen, um den Code einfach kopieren zu können.
Kopiere das alte Clerk.js 1 Design in dein neues Clerk.js 2 Design.
Du wirst feststellen, dass es keinen Container-Code im neuen Design gibt.
Grund: Liquid verwendet for-Schleifen, um alle Produkte auszugeben.
Kopiere dein altes Produkt-HTML in die for-Schleife, den alten Container-Code drum herum und auch das CSS.
Passe das Design an die Liquid-Syntax an. Der Hauptunterschied: Alt war
{{ formatter attribute }}, jetzt ist es{{ product.attribute | formatter }}.Gehe alle Attribute durch und passe sie ans neue Format an.
Falls du
{{#if}}oder{{#is}}verwendest, müssen auch diese angepasst werden. Nutze{% if product.attribute %}{% else %}{% endif %}.Lösche
id="{{ $id }}"und die Klasse:targetaus dem Container-Code in der Clerk.js 2-Version, da diese nicht mehr unterstützt werden.Unten ein Beispiel für ein Clerk.js 1 Design, und die vollständig konvertierte Version:
Clerk.js 1 Design #
// Product HTML
<li class="clerk-product">
<a href="{{ url }}">
<img src="{{ image }}" />
<div class="clerk-product-name">{{ name }}</div>
<div class="clerk-price-wrapper">
{{#if list_price}}
<div class="clerk-old-price">
<s>Price {{ money_eu list_price }}</s>
</div>
<span class="clerk-new-price">Price {{ money_eu price }}</span>
{{else}}
<div class="clerk-product-price">Price {{ money_eu price }}</div>
{{/if}}
</div>
</a>
<div class="clerk-cta-button btn button">Buy Now</div>
</li>
// Container Code
<h2>{{ headline }}</h2>
<ul id="{{ $id }}" class=":target clerk-slider"></ul>
<!-- This code creates the slider by its ID. -->
<script type="text/javascript">
Clerk.ui.slider("{{ id }}").init();
</script>
Clerk.js 2 Design #
<h2>{{ headline }}</h2>
<ul class="clerk-slider">
{% for product in products %}
<li class="clerk-product">
<a href="{{ product.url }}">
<img src="{{ product.image }}" />
<div class="clerk-product-name">{{ product.name }}</div>
<div class="clerk-price-wrapper">
{% if product.list_price %}
<span class="clerk-old-price"><s>Price {{ product.list_price | money_eu }}</s></span>
<span class="clerk-new-price">Price {{ product.price | money_eu }}</span>
{% else %}
<div class="clerk-product-price">Price {{ product.price | money_eu }}</div>
{% endif %}
</div>
<div class="clerk-cta-button btn button">Buy Now</div>
</a>
</li>
{% endfor %}
</ul>
Klicke auf Update Design, um die Änderungen zu speichern.
Gehe zu Recommendations/Search > Elements und stelle deinen Element-Block auf das neue Design um.
Klicke auf Update Element. Nun werden die Designs vorübergehend nicht in deinem Webshop angezeigt, bis du Schritt 2 abgeschlossen hast. Wähle das neue Design für alle zu aktualisierenden Elemente.
Aktualisiere abschließend das Plugin gemäß dieser Anleitung.
Mehrsprachiges Setup #
Wenn du in WooCommerce WPML nutzt, solltest du deine Sprachen per URL unterscheiden können, z. B.:
Wenn du solche eindeutigen URLs hast, kannst du das WooCommerce-Plugin erweitern, um WPML zu unterstützen.
Es ist auch möglich, die Sprache über den lang-Parameter zu definieren. Zum Beispiel:
Store kopieren #
Am einfachsten kannst du Clerk bei mehreren Domains in Standard-Setups nutzen, indem du für jede Domain einen separaten Store in my.clerk.io anlegst.
So kannst du Produkte, Verkäufe, Währungen usw. je Domain getrennt auswerten.
Nach dem Initial Setup klicke oben links im Seitenmenü auf "+ Add new store" – das ist ganz unten in der Drop-down-Liste (meist unter dem bestehenden Store/dem Firmennamen).
Fülle auf der Add New Store-Seite die Angaben deines Webshops aus und wähle beim Feld Copy Elements From Existing Store deinen Hauptstore. Klicke dann Add Store:

So werden Elements und Designs vom Hauptstore übernommen. Übersetze Headlines auch in die richtige Sprache.
Installation und Konfiguration #
Offizieller WPML-Support wurde in der Clerk WooCommerce Extension hinzugefügt, d. h. ab dieser Version (oder neuer) ist WPML unterstützt.
Im Einstellungsbereich von WooCommerce siehst du wie gewohnt die Einstellungen.
Falls WPML in deiner WordPress-Seite aktiv und konfiguriert ist, findest du oben im Einstellungenbereich Multi Language Scope mit der aktuellen Sprache.
Um die Sprache zu wechseln, verwende den Selektor im oberen Panel. Wähle die zu konfigurierende Sprache und gib die gewünschten Einstellungen an. Wiederhole dies für jede Sprache.
Wähle beim Speichern der Konfiguration nicht die Option All Languages, da dies die Einstellung nur als Fallback speichert.
Domains synchronisieren #
Nach der Erweiterung des Plugins kannst du nun jeden Store mit seiner Sprachdomain synchronisieren.
Da du die Extension bereits installiert hast, kannst du direkt mit der Konfiguration und dem Daten-Sync starten.
Nach Abschluss des Syncs ist deine Domain einsatzbereit und entspricht der Konfiguration deines Hauptstores.
Shortcode-Integration #
Wenn du einen Shortcode-Editor wie Elementor nutzt, kann es passieren, dass unser Standard-Code-Snippet für Empfehlungen nicht gerendert wird, da die Produkt-ID dort anders verarbeitet wird als in einem normalen HTML-Block.
Bei Verwendung von Hooks kannst du in Appearance -> Custom Layouts -> Insert den Shortcode an dem zu Clerk gehörenden Hook einfügen (ggf. kann ein Entwickler solche anlegen, falls Clerk ein eigener Hook sein soll).
Code ersetzen #
Um den Code einzufügen, ersetze:
<span class="clerk"
data-template="@product-page-alternatives"
data-products="[<?php echo $product->get_id(); ?>]">
</span>
Durch:
<span class="clerk"
data-template="@product-page-alternatives"
data-products="[ [clerk_product_id] ]">
</span>
Probiere zuerst einfache Klammern und wenn das nicht funktioniert, doppelte Klammern:
<span class="clerk"
data-template="@category-page-popular"
data-category="[ [clerk_category_id] ]">
</span>
Wenn das auch nicht läuft, probiere diese Varianten:
<span class="clerk"
data-template="@product-page-alternatives"
data-products="[<?php the_ID(); ?>]">
</span>
<span class="clerk"
data-template="@product-page-others-also-bought"
data-products="[<?php the_ID(); ?>]">
</span>
Manuelle Einbindung #
Falls du den Shortcode nicht einbinden kannst oder keinen Editor verwendest, gehe zu Appearance > Personalization, klicke auf die Produktseite und folge dann Widget > Shopsidebar 1 > add widget > Clerk Content.
WP Bakery Builder #
Theme-Datei-Integration: Produktseiten-Slider auf alle Seiten hinzufügen
Navigiere zu Appearance > Theme File Editor > WooCommerce > content-single-product.php (oder eine ähnliche Datei, welche die Produktseitenstruktur enthält).
Füge den span-Code an der gewünschten Stelle in der Datei ein, um den Slider anzuzeigen. Das ist ähnlich wie eine Änderung per FTP.
<span class="clerk"
data-template="@product-page-alternatives"
data-products="[<?php the_ID(); ?>]">
</span>
<span class="clerk"
data-template="@product-page-others-also-bought"
data-products="[<?php the_ID(); ?>]">
</span>
Visuelle Hooks #
In WooCommerce werden manche Seiten mit Visual Hooks statt durch HTML-Dateien erstellt.
Um Inhalte auf solchen Seiten einzubinden, füge den Clerk Content in die aktive functions.php-Datei des Webshops ein.
Die functions.php-Datei findet sich in der Regel hier:
/wp-content/themes/IHR-THEME-NAME-child-theme/functions.php
Produktseiten-Beispiel #
Um z. B. ein Recommendations-Element mit @product-page-alternatives auf der Produktseite einzufügen, setze folgenden Code in den Hauptbereich von functions.php ein:
// CLERK ADD PRODUCT PAGE SLIDER
add_action('woocommerce_after_single_product', 'clerk_alternatives', 5);
function clerk_alternatives() {
$clerk_id = wc_get_product()->get_id();
echo "<span class='clerk'
data-template='@product-page-alternatives'
data-products='[$clerk_id]'>
</span>";
}
Warenkorb-Beispiel #
Ein weiteres Beispiel, um ein Recommendations-Element auf der Warenkorb-Seite einzufügen:
// CLERK ADD CART SLIDER
add_action('woocommerce_after_cart_contents', 'clerk_cart_slider', 5);
function clerk_cart_slider() {
$clerk_id = get_queried_object()->term_id;
echo "<span class='clerk'
data-template='@cart-others-also-bought'
data-products='[<?php $items = WC()->cart->get_cart(); foreach( $items as $cart_item ){ $product_id = $cart_item['product_id']; echo $product_id; if ($cart_item != end($items)) {echo ',';} } ?>]'></span>";
}
Um eigene Recommendation-Elemente auf den Seiten hinzuzufügen, ersetze den Code zwischen -Tags durch den Embed-Code aus deinen my.clerk.io Recommendations Elements, z. B.:

Der Wert in add_action() (hier 5) gibt die Priorität des Elements an, was bestimmt, wie früh das Element im Visual Hook angezeigt wird.
Hinweis: Bei der Priorität akzeptiert WooCommerce nur Vielfache von 5.
Weitere Infos zu WooCommerce-Seiten, die Visual Hooks nutzen:
https://www.businessbloomer.com/category/woocommerce-tips/visual-hook-series/
Powerstep-Probleme #
Doppelte Darstellung #
Wenn der Powerstep doppelt angezeigt wird, musst du die Seite aufteilen, um das zu beheben.
Im WooCommerce-Backend gehe zur Powerstep-Seite, die du unter Pages angelegt hast.
Wähle rechts oben Shortcodes und dann Row / Columns.
Klicke im Pop-up auf “OK”.
Ziehe
[clerk-powerstep]zwischen[row],[col]und[/row],[/col]und klicke Save.
Keine Darstellung #
Sollte der Powerstep weiterhin nicht angezeigt werden, musst du ggf. die WooCommerce-Einstellung “Cart Redirect” deaktivieren.
Dazu kannst du so vorgehen:
Gehe zu WooCommerce > Settings > Products und finde Add to cart behaviour.
Stelle sicher, dass beide Kontrollkästchen nicht aktiviert sind.
Klicke am Seitenende auf Save changes.

Diese Seite wurde von einer hilfreichen KI übersetzt, daher kann es zu Sprachfehlern kommen. Vielen Dank für Ihr Verständnis.