FAQ
Haben Sie Probleme mit Ihrer individuellen Integration? Diese FAQ behandelt die häufigsten Probleme und deren Lösungen, von Single-Page-Apps bis hin zur Nachverfolgung von Verkäufen.
Single-Page-Apps #
Diese werden auch Progressive Web Apps (PWA) genannt und laden die Seite im Allgemeinen als eine einzige Seite, anstatt einzelne Seiten wie gewöhnlich zu laden.
Wenn eine Seite zum ersten Mal geladen wird, löst die Clerk.js-Bibliothek automatisch eine Funktion aus, um alle Element-Blöcke auf dieser Seite zu rendern.
Bei Single-Page-Apps, die Frameworks wie vue.js oder next.js verwenden, werden Seiten mit JavaScript gerendert und nicht durch einen Standardseitenaufruf.
Deshalb müssen Sie das Rendern mit Clerk.js steuern, um es an Ihre Ladeart der Seiten in der App anzupassen.
Clerk.js einbinden #
Clerk.js muss nur einmal geladen werden, wenn die Seite initial geladen wird.
Danach steht die Bibliothek während der gesamten Sitzung zur Verfügung.
Fügen Sie sie direkt vor dem </head> in Ihr HTML ein:
<!-- Start of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
<script type="text/javascript">
(function(w,d){
var e=d.createElement('script');e.type='text/javascript';e.async=true;
e.src='https://cdn.clerk.io/clerk.js';
var s=d.getElementsByTagName('script')[0];s.parentNode.insertBefore(e,s);
w.__clerk_q=w.__clerk_q||[];w.Clerk=w.Clerk||function(){w.__clerk_q.push(arguments)};
})(window,document);
Clerk('config', {
key: 'INSERT_PUBLIC_API_KEY'
});
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
Rendering steuern #
Standardmäßig rendert Clerk.js alle Elemente mit der Klasse clerk, unabhängig davon, ob sie beim initialen Laden der Seite eingefügt wurden oder wenn sich das DOM ändert.
Sie können das Timing steuern, indem Sie das Element einfügen, wenn es bereit für das Rendering ist.
Alternativ können Sie das Rendering mit der Funktion Clerk("content", "SELECTOR") steuern.
Jedes Mal, wenn eine Seite geladen wird, führen Sie diese Schritte der Reihe nach aus:
Fügen Sie das Clerk-Snippet mit einem eindeutigen Selector in das HTML ein, den Sie ansprechen können.
Führen Sie
Clerk("content", "SELECTOR")aus, um es zu rendern.
Wenn der Besucher die Seite verlässt, zerstören Sie das Snippet und rendern es erneut, wenn der Besucher auf die gleiche Seite zurückkehrt.
Dadurch stellen Sie sicher, dass Clerk.js das Snippet nicht als bereits gerendert ansieht, was dazu führen kann, dass es nicht angezeigt wird.
Beispiel:
<span
id="clerk-custom-snippet"
data-template="@home-page-visitor-recommendations">
</span>
<script>
Clerk("content", "#clerk-custom-snippet")
</script>
Clerk.js kann auch so konfiguriert werden, dass Elemente automatisch initialisiert werden mit Ihren eigenen Selektoren, nachdem Sie es das erste Mal gerendert haben.
Pagespeed-Einfluss #
Das Hinzufügen eines externen Tools wie Clerk.js erhöht die Ladezeit Ihrer Website geringfügig, der Einfluss ist jedoch vernachlässigbar im Vergleich zu den zusätzlichen Conversions, die es ermöglicht.
Im Folgenden sehen Sie, wie sich dies auf die Leistung Ihrer Website auswirkt.
Leistung #
Die Clerk.js-Bibliothek ist nur 37,5 kb groß und wird daher sehr schnell geladen.
Außerdem werden Elemente asynchron geladen, das heißt, der Rest der Seite kann geladen werden, während Clerk.js Inhalte rendert.
Ein Anstieg der Ladezeit einer Seite resultiert meistens aus dem Laden von mehr Bildern als zuvor, da die Suchergebnisse und Empfehlungen von Clerk am besten funktionieren, wenn sie visuell ansprechend dargestellt werden.
Um die zusätzliche Ladezeit zu minimieren, empfehlen wir die Verwendung von Bildern im webp-Format mit einer Auflösung, die der Größe in den Clerk-Elementen entspricht.
Beispiel: Haben Bilder in Empfehlungen eine Auflösung von 400x400px in der Desktop-Ansicht, senden Sie die Bilder in einer maximalen Auflösung von 420x420px oder ähnlich.
Google Page Speed #
Wenn Sie Google Page Speed Insights oder ein ähnliches Tool verwenden, um die Leistung Ihrer Seite zu analysieren, wird Clerk.js möglicherweise unter Leverage browser caching. aufgelistet.
Der Zweck von Clerk.js ist es, das Einfügen von Ergebnissen von Clerk auf jeder Website äußerst einfach zu machen.
Clerk.js beinhaltet viele Funktionen zur Steuerung von Tracking und UI-Komponenten wie Instant Search, Slider, Popups und mehr.
Wenn wir neue UI-Funktionen hinzufügen oder bestehende verbessern, sind diese in Clerk.js enthalten und müssen vom Endnutzer heruntergeladen werden, um sie zu nutzen.
Eine Cache-Gültigkeit von 60 Minuten bedeutet, dass neue Funktionen allen Nutzern innerhalb von maximal 60 Minuten zur Verfügung stehen.
Je länger die Cache-Zeit, desto länger dauert es, bis alle die neuesten Funktionen erhalten.
Wichtig ist, dass Endnutzer Clerk.js nur einmal herunterladen müssen, wenn neue Funktionen verfügbar sind.
Die Ablauffrist von 60 Minuten bedeutet einfach, dass der Browser des Nutzers alle 60 Minuten für Clerk.js nachfragt.
Wurden seitdem keine Änderungen vorgenommen, wird nichts erneut heruntergeladen.
Die Cache-Ablauffrist von 60 Minuten ist somit ein Kompromiss zwischen der Minimierung von Webanfragen und dem schnellen Erkennen neuer Funktionen und Verbesserungen.
Die meisten Sitzungen sind kürzer als 60 Minuten, daher erfolgt die Anfrage in der Regel nur einmal pro Sitzung.
Wie im Screenshot zu sehen, ist dies eine gängige Praxis, die (wie auch Clerk) von Google Analytics, Facebook, Trustpilot und vielen anderen genutzt wird.
CLS-Einfluss #
Cumulative Layout Shift (CLS) kann sich negativ auf SEO und Benutzererlebnis auswirken, wenn dynamisch eingefügter Inhalt das Layout der Seite verschiebt.
In bestimmten Fällen kann Clerk zum CLS-Wert beitragen.
Mehr über CLS lesen Sie hier.
Befolgen Sie diese Richtlinie nur, wenn Ihr CLS-Wert über 0,2 liegt und Clerk-Elemente im sichtbaren Bereich (“above the fold”) angezeigt werden.
Um ein Verschieben der Inhalte zu verhindern, sollte vor dem Laden von Clerk-Empfehlungen durch Clerk.js ein Platzhalter reserviert werden.
Dazu fügen Sie eine Mindesthöhe basierend auf der erwarteten Inhaltshöhe ein.
Beispielcode:
.clerk-slider-wrapper {
min-height: 300px; /* Anpassen je nach erwarteter Inhaltshöhe */
width: 100%;
}
API-Aufrufe durchführen #
Sie können Clerk.js verwenden, um API-Aufrufe zu machen, indem Sie die eingebaute Funktion Clerk("call") nutzen.
Diese Funktion erwartet 3 Argumente:
Einen API-Endpunkt
Ein JSON-Dictionary mit Parametern
Eine Callback-Funktion zur Verarbeitung der Antwort
Anfragen #
Nachfolgend ein Beispielskript, das die 10 beliebtesten Produkte anfordert und die Antwort in der Konsole ausgibt.
Die Antwort enthält ein JavaScript-Objekt mit dem Status des API-Calls und dem Ergebnis.
Skript #
function popularProducts(){
Clerk("call",
"recommendations/popular",
{
limit: 10,
labels:["Home Page / Bestsellers"]
},
function(response){
console.log(response);
},
function(response){
console.error(response);
}
);
}
Antwort #
__clerk_cb_1(
{
"status":"ok",
"count":72,
"facets":null,
"result":[399,410,551,338,403,439,425,402,406,456]
}
);
Callbacks #
Bei API-Aufrufen können Sie Callback-Funktionen einsetzen, um die Antwort wie gewünscht zu verarbeiten.
Die Funktionen nehmen als Argument response, das alle von der API zurückgegebenen Daten enthält.
Nachstehend ein Beispiel, das eine Liste von HTML-Elementen erstellt, die auf Kategorien mit der Suchanfrage “men” verlinken.
Clerk("call",
"search/categories",
{
'query': "men",
'limit': "10"
},
function(response) {
var cat = response.categories;
if (cat.length > 0) {
let heading = document.createElement('h3');
heading.textContent = 'Related Categories';
document.querySelector('#your-target').append(heading);
}
for (var index in cat) {
var clerkName = cat[index].name;
var clerkUrl = cat[index].url;
let link = document.createElement('a');
link.href = clerkUrl;
link.textContent = clerkName;
document.querySelector('#your-target').append(link);
}
}
)
„In-den-Warenkorb“-Buttons #
Diese Buttons funktionieren je nach Plattform unterschiedlich, und die Funktionalität kann sich zudem anhand eingesetzter Plugins verändern.
Da Clerks Designs aus HTML & CSS bestehen, können Sie diese Funktionalität normalerweise selbst ergänzen, sofern Sie deren Funktionsweise auf Ihrer Seite verstehen.
Allgemeines Vorgehen #
Manche „In-den-Warenkorb“-Buttons benötigen JavaScript zur Ausführung.
In solchen Fällen können Sie die Funktionalität zur bestehenden cart-Methode von Clerk hinzufügen.
Wie das funktioniert, steht in unseren Developer Docs hier.
Untersuchen Sie den „In-den-Warenkorb“-Button, um den zugehörigen Code zu ermitteln, z. B. auf einer Kategorieseite.
Der Code besteht üblicherweise aus einem <div>- oder einem button-Element.
Kopieren Sie den gesamten Button-HTML-Code.
Fügen Sie diesen Code in Ihr Design ein.
Jetzt müssen Sie die Variablen im Code identifizieren.
Meist benötigen Sie:
Produkt-ID
Produktmenge
Ersetzen Sie die Werte für die Produkt-ID durch die entsprechenden Liquid-Variablen.
Die ID wird immer {{ product.id }} sein und die Menge unterscheidet sich je nach Datenübertragung.
Für dieses Beispiel könnte sie {{ product.qty }} lauten.
Fügen Sie Ihren Code in das HTML Ihres Designs ein und testen Sie, ob er funktioniert.
Beispiel #
Der folgende „In-den-Warenkorb“-Button ist ein <div> mit der Klasse button-container:
Die Menge befindet sich im Warenkorb-URL-Link nach /cart?add=, die Produkt-ID direkt nach &id_product=.
Die Produkt-ID ist außerdem im Attribut data-id-product referenziert, die Menge im Attribut .data-minimal_quantity.
Diese Werte sollten im Design durch Liquid-Tags ersetzt werden, sodass in der HTML-Ausgabe die richtigen Produkt-IDs und Mengen eingesetzt werden.
Mit diesen Änderungen sieht der finale „In-den-Warenkorb“-Button so aus:
<div class="button-container">
<a
class="button ajax_add_to_cart_button btn btn-default"
style="position: relative;"
href="https://www.examplelinktocart.com/cart?add={{ product.qty }}&id_product={{ product.id }}&"
rel="nofollow"
title="Add to Cart"
data-id-product-attribute="0"
data-id-product="{{ product.id }}"
data-minimal_quantity="{{ product.qty }}">
<span style="color: orange !important">
<i class="icon-shopping-cart" aria-hidden="true"></i>
</span>
</a>
</div>
Konsolenfehler #
Clerk.js protokolliert viele Fehler in der Konsole, die Sie zum Debuggen verwenden können.
Wenn Sie auf den Fehler-Link klicken, erhalten Sie weitere Informationen, die Sie zur Fehlerbehebung oder zur Weitergabe an unser Support-Team nutzen können.
Im Folgenden finden Sie eine Liste der häufigsten Fehler.
Unbekannter Content #
Dieser Fehler wird angezeigt, wenn das eingefügte Snippet sich auf ein
Element bezieht, das nicht existiert (im Attribut data-template).
Um dies zu beheben, stellen Sie sicher, dass der im Embed-Code angegebene Name mit einem erstellten Element-Block in my.clerk.io übereinstimmt.
Sie können bei jedem Element auf Element bearbeiten klicken, um die richtige Referenz zu sehen.
Ungültiger API-Endpunkt #
Dieser Fehler tritt auf, wenn Sie die Klasse clerk irgendwo in Ihrem HTML verwenden.
Diese Klasse ist für unsere Snippets reserviert, da Clerk.js sie zur Identifikation der zu rendernden Elemente nutzt.
Nennen Sie die Klasse etwas anderes, zum Beispiel clerk-product.
Ungültiges Produktargument #
Dieser Fehler bedeutet, dass die übergebene ID eines Produkts den falschen Typ oder das falsche Format hat.
Wenn Ihre Produkt-IDs beispielsweise Integer sind, müssen sie dies auch im Embed-Code sein.
Denken Sie außerdem an die eckigen Klammern um die ID, um eine Liste zu erzeugen.
<span
class="clerk"
data-template="@product-page"
data-products="[123]">
</span>
Ungültiges Kategorieargument #
Dieser Fehler besagt, dass die übergebene ID einer Kategorie einen falschen Typ oder Format hat.
Meist passiert dies, wenn der Platzhalter im Kategorie-Embed-Code nicht durch eine tatsächliche ID ersetzt wurde:
<span
class="clerk"
data-template="@category-page"
data-category="INSERT_CATEGORY_ID">
</span>
Das Output des Codes sollte die ID der Kategorie enthalten:
<span
class="clerk"
data-template="@category-page"
data-category="257">
</span>
Wenn Sie das Snippet manuell kopiert haben, wählen Sie vorher Ihr Shopsystem im Choose your platform-Dropdown aus, bevor Sie das Snippet kopieren.
Dann wird die Logik Ihrer Plattform übernommen, um die richtige Kategorie-ID auszuwählen.
Ist Ihre Plattform nicht aufgelistet, müssen Sie selbst die Logik hinzufügen, um anhand des Webshop-Verhaltens die korrekte Kategorie-ID auszuwählen.
Falscher API-Key #
Dieser Fehler erscheint, wenn der von Ihnen genutzte öffentliche API-Key keinem Account bei Clerk zugeordnet ist.
Um dies zu beheben, loggen Sie sich in my.clerk.io ein und gehen Sie zu Developers > API Keys.
Hier finden Sie den Public API Key, den Sie dann Ihrem Clerk.js-Tracking-Script hinzufügen – entweder direkt im Code oder in den Einstellungen Ihrer Integration, abhängig von Ihrer Plattform.
POS/ERP-Umsatzdaten #
Für einige Webshops ist es relevant, Umsatzdaten aus anderen Systemen als dem eigentlichen Shop hochzuladen.
Zum Beispiel, wenn Sie den Algorithmus anhand der Verkäufe aus einem stationären Laden oder einem B2B-Shop optimieren möchten.
Clerk unterscheidet nicht zwischen Bestellungen aus verschiedenen Quellen – solange Sie eine ID, einen Zeitstempel und eine Liste der gekauften Produkte bereitstellen können, können sie zu Clerk hochgeladen werden.
Die empfohlene Vorgehensweise ist die Nutzung der CRUD API, da Sie so die Aufgabe vollständig automatisieren können.
Durch die Implementierung dieser API-Aufrufe können Sie Bestelldaten direkt in Ihr Store bei Clerk senden.
Machen Sie einfach einen POST-Aufruf an den /orders-Endpunkt in Ihrem ERP-System oder Webshop, führen Sie die Aufgabe regelmäßig (z. B. monatlich) aus, und Sie können Offline-Bestellungen nutzen, um Online-Empfehlungen und Suchergebnisse zu verbessern.
Alternativ können Sie eine CSV-Datei manuell hochladen, ohne Code.
Mehr dazu finden Sie hier.
Währungsumrechnung #
Für die Währungsumrechnung in Clerk gibt es mehrere Wege.
Eine einfache Methode ist unten beschrieben.
Preisobjekte senden #
Clerk muss die Preise jedes Produkts in den verschiedenen Währungen kennen.
Am einfachsten senden Sie diese als stringkodiertes JSON-Objekt mit formatierten Preisen, wobei der ISO-Code der Währung als Schlüssel dient, im Data Feed.
"products": [
{
"id": 1,
"name": "Cheese",
"description": "A nice piece of cheese.",
"price": 100,
"list_price": 50,
"categories": [25, 42],
"image": "http://example.com/images/products/1.jpg",
"url": "http://example.com/product/1",
"on_sale": true,
// String-encoded JSON examples
"prices_formatted": "{\"USD\":\"$100\", \"EUR\":\"€87.70\", \"GBP\":\"£68.68\"}",
"list_prices_formatted": "{\"USD\":\"$120\", \"EUR\":\"€97.70\", \"GBP\":\"£78.68\"}"
},
{
"id": 2,
"name": "A pound of nuts",
"description": "That's a lot of nuts!",
"price": 150,
"categories": [1],
"image": "http://example.com/images/products/2.jpg",
"url": "http://example.com/product/2",
"on_sale": false,
// String-encoded JSON example
"prices_formatted": "{\"USD\":\"$150\", \"EUR\":\"€142\", \"GBP\":\"£120\"}",
"list_prices_formatted": "{\"USD\":\"$150\", \"EUR\":\"€142\", \"GBP\":\"£120\"}"
}
]
Formatter erstellen #
In Clerk.js können Sie JavaScript-Funktionen definieren, die mit Ihren Designs verwendet werden.
Hier können Sie eine Funktion definieren, die Ihr price-dict als Argument erhält und den Preis für eine bestimmte Währung je nach Frontend-Logik zurückgibt.
Ersetzen Sie currency dabei durch die aktuell gewählte Währung aus dem Frontend.
Clerk('config', {
key: 'Your_API_Key',
formatters: {
currency_selector: function (price_list) {
const currency = "EUR";
price_groups_obj = JSON.parse(price_list)
return price_groups_obj[currency];
}
}
});
Formatter verwenden #
Nachdem Sie den Formatter definiert haben, können Sie ihn in Ihrem Design wie folgt einsetzen:
<div class="price">
<span class="price">
{{ product.prices_formatted | currency_selector }}
</span>
</div>
Kundenspezifische Preise #
Um individuelle Preise anzuzeigen, die darauf basieren, welcher Kunde eingeloggt ist, erstellen Sie ein Event in Clerk, das den korrekten Preis vor dem Rendern der Produkte einfügt.
Events sind JavaScript-Funktionen, die vor oder nach der Anzeige von Produkten durch Clerk ausgelöst werden.
Diese Methode kann eingesetzt werden, wenn Sie Preise von Ihrem Server, direkt aus einer JavaScript-Funktion im Frontend basierend auf Produkt-ID und Kunden-ID abfragen können.
Um individuelle Preise anzuzeigen, muss der Code direkt nach der Response ausgelöst werden.
Hier ein Beispiel eines einfachen Events:
<span class="clerk" data-template="@home-page-popular"></span>
<script>
Clerk('on', 'response', function(content, data) {
console.log(data.result);
});
</script>
Die Funktion nimmt das Argument data entgegen, das die komplette Response enthält, die Clerk von der API zurückliefert.
Individuelle Kundenpreise #
Wenn Sie individuell unterschiedliche Preise je Kunde anzeigen müssen, setzen Sie ein Event auf, das nach dem Rendern der Produkte den korrekten Preis einfügt.
Events sind JavaScript-Funktionen, die vor oder nach dem Anzeigen von Produkten durch Clerk ausgeführt werden.
Dieses Vorgehen setzt voraus, dass Sie Preise vom Server anhand von Produkt-ID und Kunden-ID per AJAX im Frontend abfragen können.
Der beste Weg ist, zuerst einen Platzhalter-Preiscontainer in Ihr Design einzufügen und diesen dann durch den Preis aus Ihrem AJAX-Aufruf zu ersetzen.
Ein Beispiel:
<div class="clerk-price-container">
<span class="clerk-price">
Loading price...
</span>
</div>
Verwenden Sie nun das Clerk-Event, um zu warten, bis die Produkte gerendert wurden, führen eine Anfrage an Ihren Preiser zur Preisermittlung auf Basis von Produkt- und Kunden-ID durch und ersetzen dann den Wert im HTML.
So zum Beispiel:
<script>
var customer_id = INSERT_CUSTOMER_ID;
Clerk("on", "rendered", function(content, data){
for (i = 0; i < data.product_data.length; i++) {
var product = data.product_data[i];
var custom_price = FETCH_PRICE_FROM_SERVER(product.id,customer_id);
let price_container = document.querySelector(`[data-clerk-product-id='${product.id}'] .clerk-price`);
price_container.innerText = custom_price;
}
})
</script>
Der obige Code setzt voraus, dass Sie einen eingeloggten Kunden über INSERT_CUSTOMER_ID identifizieren und dass Sie eine Funktion wie FETCH_PRICE_FROM_SERVER haben, die den Preis für das angegebene Produkt und den Kunden liefert.
price_container dient dazu, anhand von data-clerk-product-id das richtige Produkt-Element im HTML zu finden (dieses Attribut wird von Clerk.js an alle Produkte angehängt).
Zum Schluss wird der Platzhalter-Text („Loading price…“ in diesem Beispiel) durch den AJAX-Rückgabewert ersetzt.
Kundengruppenpreise #
Das Einrichten von Kundengruppenpreisen besteht aus 4 Schritten:
Erfassen aller Preise in Data Feed.
Integrieren einer globalen Variable, die die aktuelle Kundengruppen-ID abruft.
Erstellen einer Funktion zur Preisermittlung.
Darstellung des Preises im Design.
Preisobjekte erfassen #
Fügen Sie allen Produkten ein Attribut hinzu, das alle verschiedenen Preise enthält und jeder Gruppe einen Preis zuweist.
Dies sollte als JSON-Objekt gesendet werden, z. B.:
"customer_group_prices": {
"GROUP1": 100,
"GROUP2": 202,
"GROUP3": 309
}
Kunden-ID-Variable #
Fügen Sie eine dynamische globale Variable in Clerk.js hinzu, die die Kundengruppen-ID des aktuellen Nutzers als Wert enthält.
Die Kundengruppen-ID muss dem Key des dazugehörigen Preises im Data Feed entsprechen.
Hat ein Nutzer zum Beispiel Anspruch auf den Preis für „GROUP2“, dann muss die ID „GROUP2“ lauten.
Clerk('config', {
globals: {
customer_group: "GROUP2"
}
});
Preis abrufen #
Sie können nun einen Formatter anlegen, der die customer_group als Argument nimmt und den entsprechenden Preis zurückgibt.
Erstellen Sie dafür eine Funktion, die im Key des Preis-Objekts den Preis anhand der customer_group-ID zurückgibt.
Fügen Sie dies in die Clerk.js-Konfiguration ein. Beispiel, genannt getPrice:
Clerk('config', {
globals: {
customer_group: "GROUP2"
},
formatters: {
getPrice: function (prices, customer_group) {
return prices[customer_group];
}
}
});
Preis anzeigen #
Nachdem Sie den getPrice-Formatter erstellt haben, kann er im Design zusammen mit der in Schritt 1 angelegten customer_group_prices-Liste aufgerufen werden:
<li style="text-align: center; width: 180px;">
<a href="{{ product.url }}">
<img src="{{ product.image }}" />
{{ product.name }}
</a>
<div class="price">
{{ product.customer_group_prices | getPrice customer_group }}
</div>
</li>
HTTP-Authentifizierung #
HTTP-Authentifizierung wird oft auf Staging-Seiten eingesetzt, um unerwünschte Besucher fernzuhalten.
Dies blockiert in vielen Fällen auch den Clerk-Importer und führt typischerweise zu einem 401 Unauthorized-Fehler im Sync-Protokoll.
Sie können das Problem beheben, indem Sie die Authentifizierungsinformation in die Import-URL einfügen.
In my.clerk.io > Data > Configuration aktualisieren Sie Ihre Import-URL z. B. so:
http://USER:PASS@www.ewoksRus.com/JSONFEED
Keine verfolgten Bestellungen #
In my.clerk.io sind Verfolgte Bestellungen und Bestelldetails zu einer einzelnen Bestellübersichtsseite zusammengefasst.
Clerk muss die Verkäufe des Webshops kontinuierlich verfolgen, um die Ergebnisse stets an das aktuelle Verhalten Ihrer Kunden anzupassen.
Allerdings können bestimmte Einstellungen im Shop das Sales-Tracking verhindern.
Nachfolgend erfahren Sie, wie Sie das Sales-Tracking in einem Clerk.js-Setup debuggen und die häufigsten Fehler und Lösungen finden.
Vorab prüfen #
Stellen Sie sicher, dass Sie installiert haben:
Das Clerk.js Tracking-Script auf allen Seiten.
Das Sales-Tracking-Script auf Ihrer Order Success Page.
Beide sind notwendig, um Verkäufe im Zusammenhang mit einer Clerk.js-Integration nachzuverfolgen.
Protokolle prüfen #
Meist schlägt das Sales-Tracking wegen fehlerhafter Besucher-IDs oder Produkt-IDs im Sale-Aufruf fehl, der nach dem Kauf an Clerk gesendet wird.
Um dies zu debuggen, müssen Sie eine Test-Bestellung tätigen.
In manchen Fällen kann es auch am Sales-Tracking-Script selbst liegen, dies lässt sich durch Protokolle in my.clerk.io > Developers > Logs. prüfen.
Wenn das Sales-Tracking wegen eines Skriptfehlers fehlschlägt, sehen Sie den Fehler häufig auf dieser Seite.
Klicken Sie auf Details, um mehr zu sehen.
Können Sie keine Fehler im Protokoll sehen, ist der einfachste Weg, andere Fehler beim Sales-Tracking aufzuspüren, einen Test-Kauf durchzuführen.
Debugging bei Test-Bestellungen #
Im folgenden Beispiel nutzen wir Chrome, um das Debuggen des Sales-Trackings bei einer Test-Bestellung zu zeigen. Andere Browser bieten ähnliche Funktionen.
Legen Sie einige Produkte in den Warenkorb.
Gehen Sie zur Kasse.
Öffnen Sie vor dem Absenden der Bestellung die Konsole Ihres Browsers.
Wechseln Sie zu Netzwerk und suchen Sie nach “clerk”.
Schließen Sie die Bestellung ab, sodass Sie die Bestellbestätigungsseite sehen.
Wählen Sie den Aufruf, der mit sale beginnt (normalerweise sale?key=…).
Hier sehen Sie, welche Daten an die Sales-Tracking-API gesendet und was zurückerhalten wird.
Unter Vorschau können Sie häufige Fehler erkennen, die verhindern, dass Verkäufe nachverfolgt werden.
Im Folgenden typische Fehler beim Sales-Tracking:
Falsche Produktsyntax #
Dieser Fehler tritt auf, wenn die Produkt-IDs, die Sie senden, das falsche Format haben.
Die häufigsten Ursachen sind:
Die Produkt-IDs sind im Sales-Tracking String-codiert, in Clerk jedoch als Integer oder umgekehrt.
Die Liste der Produkt-IDs enthält Textformatierungszeichen statt reinem JSON:
"products":\[\\"id"\\:\\"123-m"\\\].
Fehlendes Argument #
Das heißt, Sie senden nicht alle notwendigen Daten, damit Clerk den Verkauf verfolgen kann.
Achten Sie darauf, alle notwendigen Datenattribute im Sales-Tracking zu übergeben.
Kein Aufruf gemacht #
Wenn Sie trotz Installation beider Skripte keinen sale-Aufruf sehen, wurde das Clerk.js-Skript möglicherweise nicht korrekt geladen.
Testen Sie das wie folgt:
Öffnen Sie die Konsole Ihres Browsers.
Tippen Sie „Clerk“ ein.
Wenn Clerk.js nicht korrekt geladen wurde, erscheint ein ReferenceError:
Uncaught ReferenceError: Clerk is not defined
In diesem Fall überprüfen Sie Ihr Clerk.js-Setup:
Installieren Sie Clerk.js auf allen Seiten.
Stellen Sie sicher, dass keine anderen JavaScript-Funktionen das Laden blockieren.
Iubenda blockiert #
Wenn Sie iubenda zur Cookie-Einwilligung nutzen (insbesondere mit Automatic blocking) und ein Besucher Cookies ablehnt, kann iubenda Clerk-Skripte oder Anfragen blockieren.
Typische Folgen:
- Die
sale-Anfrage wird nie gesendet, sodass die Bestellung nicht getrackt oder nicht zugeordnet wird. - Clerk-Elemente werden teils gar nicht gerendert, oder Clerk.js schreibt einen Konsolenfehler bzgl. mehrfach geladen (weil iubenda Skripte umschreibt oder verzögert).
Lösung: Clerk.io in iubenda erlauben #
Erlauben Sie in iubenda explizit Clerk, um es von Blockierungen auszunehmen.
Mindestens sollten Sie diese Domains erlauben:
cdn.clerk.io(Clerk.js)api.clerk.io(Tracking und Sales)
Die exakten UI-Begriffe können in iubenda variieren, oft findet sich dies in den Cookie Solution-Einstellungen Ihres iubenda-Projekts für Automatic blocking (allowlist/whitelist/ignore list).
Siehe die Anleitung von iubenda zu übermäßigen Blockierungen im automatischen Blockiermodus: https://www.iubenda.com/en/help/153445-what-to-do-when-the-automatic-blocking-mode-is-blocking-too-much/.
Lösung prüfen #
Nach Anpassung der iubenda-Einstellungen:
- Laden Sie den Shop, lehnen Cookies ab, und öffnen Sie die Browser-Konsole.
- Prüfen Sie, dass Clerk.js verfügbar ist (z. B. sollte
typeof Clerknicht"undefined"sein). - Führen Sie
Clerk("debug")aus, führen Sie eine Testbestellung durch und prüfen Sie, ob einesale-Anfrage an Clerk geht und mitstatus: "ok"zurückkommt.
Keine Clerk-Auswirkung #
Wenn Sie in my.clerk.io erfolgreich Verkäufe nachverfolgen, aber keiner davon als durch Clerk beeinflusst angezeigt wird, könnte in Ihrer Besucher-/Klickverfolgung ein Fehler stecken.
Stellen Sie zuerst sicher, dass die Besucher-Nachverfolgung funktioniert, indem Sie Folgendes tun:
Klicken Sie auf ein beliebiges Produkt über Clerks Search oder Recommendations.
Kaufabschluss mit diesem Produkt.
Einloggen in my.clerk.io und auf Bestellungen gehen.
Warten, bis die Bestellung erscheint.
Wenn die Besucher-Nachverfolgung funktioniert, sehen Sie den von Clerk hinzugefügten Wert in den Bestelldetails auf der Bestellübersicht:
Sind bei Ihrer eigenen Bestellung keine hinzugefügten Werte sichtbar, sehen Sie hier die häufigsten Fehlerquellen.
API-Setups #
Wenn Sie Clerk direkt über die API individuell einbinden, müssen Sie die Besucher-Nachverfolgung aktivieren.
Wie das geht, steht in diesem API-Artikel.
Falsche Produkt-IDs #
Damit die Besucher-Nachverfolgung funktioniert, müssen Click- und Sales-Tracking dieselben Produkt-IDs nutzen wie die im Import.
Meist funktioniert dies nicht, weil Sie Varianten-IDs statt Haupt-IDs oder die SKU statt der ID tracken.
So prüfen Sie, ob dies die Ursache ist:
Gehen Sie in my.clerk.io zu Data > Orders und klicken Sie auf die ID einer von Ihnen getätigten Bestellung.
Kann Clerk das Produkt nicht erkennen, sehen Sie ein ID- und Image-Platzhalter.
Gehen Sie zu Data > Products und suchen Sie nach dem Produktnamen der hinzugefügten Bestellung. Dort sehen Sie die erwartete Produkt-ID.
Nutzen Sie diese Info, um Ihr Sales-Tracking auf die korrekten Produkt-IDs umzustellen.
Wechselnde Besucher-ID #
Clerk verwendet eine Visitor-ID zur Erkennung jeder einzelnen Sitzung, einschließlich der geklickten und gekauften Produkte.
Deshalb sollte die ID mindestens während einer Sitzung und idealerweise über mehrere hinweg gleich bleiben.
Diese Visitor-ID wird beim Einsatz von Clerk.js automatisch angelegt, nutzen Sie aber ein API-Setup oder verändern Ihre Visitor-IDs, kann sich diese unbeabsichtigt ändern.
Dieser Fehler ist selten, kann aber durch folgende Schritte kontrolliert werden:
Öffnen Sie im Browser die Network-Einstellungen und filtern Sie nach „clerk“.
Prüfen Sie die
undefined-Requests, die sich auf Search oder Recommendations beziehen.In
payloadkannst du die aktuelle Visitor ID überprüfen. Du kannst dies für alle Anfragen tun, die mit Clerk verbunden sind.Klicke anschließend auf das Produkt und gib eine Bestellung mit diesem Produkt auf.
Überprüfe auf der Seite Order Success erneut dein Netzwerk und finde die Anfrage an
sale?.Stelle sicher, dass
visitorimpayloadmit der Visitor ID übereinstimmt, die du in Schritt 3 gesehen hast.
Wenn die visitor IDs nicht übereinstimmen, musst du herausfinden, warum sie sich ändern.
Ein häufiger Grund dafür, dass sich Visitor IDs ändern, kann darin liegen, dass du die IDs für jede neu geladene Seite neu generierst.
Aktualisiere deinen Code so, dass auf jeder Seite die gleiche Visitor ID verwendet wird.
Upgrade auf Clerk.js 2 #
Clerk.js 2 ist eine schnellere und flexiblere Version unserer JavaScript-Bibliothek.
Damit wird die Installation von Clerk auf jedem Webshop erleichtert.
Da sich die beiden Versionen jedoch leicht unterschiedlich verhalten, musst du die folgenden Schritte befolgen, um erfolgreich zu upgraden.
Die beiden wichtigsten Unterschiede in Clerk.js 2 sind:
Die Designs in my.clerk.io verwenden Liquid, können aber auch ganz einfach mit dem Design Editor erstellt werden.
Das Skript muss direkt vor dem
</head>-Tag in das Template deines Webshops eingefügt werden.
Designs erstellen #
Da Clerk.js 2 einen anderen Ansatz für Designs hat, musst du neue erstellen.
Du kannst deine Clerk.js 2 Designs entweder im Design Editor neu erstellen oder deinen alten Code in Liquid konvertieren, was im folgenden Leitfaden erklärt wird.
Nachfolgend findest du eine Beschreibung, wie du deine alten Code-Designs in Liquid konvertierst.
Design Editor Option #
Gehe zu my.clerk.io > Recommendations/Search > Designs > New Design.
Wähle einen anderen Designtyp als Blank und gib ihm einen Namen. Wir empfehlen, “V2” hinzuzufügen, damit erkenntlich ist, dass du Clerk.js 2 Designs verwendest.
Klicke im Design Editor auf eines der vorhandenen Elemente wie Name, Bild, Button usw., um es zu bearbeiten, oder füge dem Design neue Elemente hinzu.
Klicke auf Publish Design, wenn du fertig bist, und gehe zu Schritt 2 der Anleitung.
Gehe zu Recommendations/Search > Elements und ändere dein Clerk Element so, dass es dein neues Design verwendet; klicke dann auf Update Element.
Dadurch werden sie vorübergehend nicht in deinem Webshop angezeigt, bis du Clerk.js 2 wie weiter unten in diesem Leitfaden beschrieben eingefügt hast.
Designs konvertieren #
Da Clerk.js 2 die flexiblere Template-Sprache Liquid verwendet, musst du die Designs in diese Sprache übertragen.
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 erkenntlich ist, dass du Clerk.js 2 Designs verwendest.
Klicke auf Create Design.
Dadurch erhältst du ein leeres Design mit Produkt-HTML und CSS, das du verwenden kannst.
Gehe zurück zur Design-Übersicht und klicke bei deinem Clerk.js 1 Design auf Edit Design. Wir empfehlen, dies in einem neuen Tab zu machen, damit du den Code einfach kopieren kannst.
Kopiere das alte Clerk.js 1 Design in dein neues Clerk.js 2 Design.
Du wirst bemerken, dass in deinem neuen Design kein Container Code vorhanden ist.
Das liegt daran, dass Liquid for loops verwendet, um alle Produkte darzustellen.
Kopiere dein altes Product HTML innerhalb der for-loop, deinen alten Container Code darum herum und auch das CSS.
Konvertiere das Design in die Syntax von Liquid. Der Hauptunterschied besteht darin, dass alte Designs die Syntax
{{ formatter attribute }}verwendeten, während v2 die Syntax{{ product.attribute | formatter }}nutzt.Gehe alle deine Attribute durch und passe sie an das neue Format an.
Falls du
{{#if}}oder{{#is}}Statements verwendest, müssen auch diese konvertiert werden. Verwende die Syntax{% if product.attribute %}{% else %}{% endif %}.Entferne
id="{{ $id }}"und die Klasse:targetaus dem Container-Code in der Clerk.js 2 Version, da sie nicht mehr unterstützt werden.Im Folgenden siehst du ein Beispiel eines Clerk.js 1 Designs 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 ändere deinen Element Block, sodass er dein neues Design verwendet.
Klicke auf Update Element. Dadurch werden sie vorübergehend nicht in deinem Webshop angezeigt, bis du mit Schritt 2 fertig bist. Wähle das neue Design für alle Elemente, die aktualisiert werden sollen.
Script ersetzen #
Finde die Template-Datei, die für die Darstellung aller Seiten des Webshops verwendet wird und in der das ursprüngliche Clerk.js Script am unteren Ende zu finden ist.
Entferne das alte Clerk.js Script aus der Datei. Es sieht etwa so aus:
<!-- Start of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
<script type="text/javascript">
window.clerkAsyncInit = function() {
Clerk.config({
key: 'public_api_key'
});
};
(function(){
var e = document.createElement('script'); e.type='text/javascript'; e.async = true;
e.src = document.location.protocol + '//api.clerk.io/static/clerk.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(e, s);
})();
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
Gehe zu my.clerk.io > Developers > Tracking Code. Dort findest du den Clerk.js 2 Code.
Kopiere diesen Code und füge ihn direkt vor dem
</head>-Tag im Template ein und speichere die Änderung.
Herzlichen Glückwunsch! Du nutzt jetzt das stark verbesserte Clerk.js 2 Setup!
Die vollständige Dokumentation zu Clerk.js 2 findest du hier.
Umgang mit require.js #
Dieser Abschnitt gilt nur bei der Verwendung von Clerk.js 1.
In manchen Setups verhindert Require.js, dass Clerk.js geladen wird, wodurch keine Slider oder Suchergebnisse angezeigt werden.
In diesem Fall wird folgender Fehler in deiner Konsole angezeigt:
Uncaught ReferenceError: Clerk is not defined
Für den Umgang mit Require.js gibt es zwei Möglichkeiten. Beide Ansätze erfordern, dass du das Tracking-Skript anpasst, das du am unteren Rand aller Seiten eingefügt hast.
In Require.js einbinden #
Der beste Ansatz ist es, Require.js dazu zu bringen, Clerk zu erkennen.
Du kannst das erreichen, indem du require(['clerk'], function() {}); am unteren Ende des Tracking-Skripts einfügst:
Require.js ignorieren #
Falls die obige Lösung nicht funktioniert, kannst du Require.js ignorieren.
Füge dazu am Anfang des Tracking-Skripts window.__clerk_ignore_requirejs = true; ein:
Nachdem du eine dieser Methoden verwendet hast, ist Require.js nun mit Clerk kompatibel.
Diese Seite wurde von einer hilfreichen KI übersetzt, daher kann es zu Sprachfehlern kommen. Vielen Dank für Ihr Verständnis.