FAQ

Probleme mit deiner Shopify-Integration? Diese FAQ behandelt die häufigsten Probleme und deren Lösungen, von Währungsumrechnung bis zu Theme-Dateispeicherorten.

Bildgrößen #

Shopify-Bild-URLs können feste Dimensionen aus dem Sync enthalten, z. B. _600x600.

Wenn dein Design für unterschiedliche Platzierungen unterschiedliche Ausgabegrößen benötigt, kannst du die synchronisierte feste Größe entfernen und eine neue Breite in der URL anfordern.

Beispiel (ersetze 600x600 durch deine konfigurierte Standardbildgröße):

{{ product.image
  | replace '_600x600.' '.'
  | replace '?v=' '?width=350&v=' }}

Das ist nützlich, wenn ein Design mehrere Bildformate verwendet (z. B. Produktkarten und große Hero-Platzierungen) und du das Synchronisieren mehrerer Bildattribute vermeiden möchtest.

Währungsumrechnung #

Die integrierte Währungsumrechnung von Shopify macht es einfach, das Währungssymbol und den Wechselkurs vom Webshop zu beziehen.

Standardmäßig wird Clerk.js für Shopify mit einem formatter ausgeliefert, der funktioniert, solange deine Drittanbieter-App das integrierte Währungsobjekt von Shopify nutzt.

Standardlösung #

Du musst einen Formatter in deinen Designs verwenden, um Preise umzurechnen.

Dieses Beispiel verwendet unsere Standard-Template-Sprache hier.

Bei der Verwendung von Währungsumrechnungen und Symbolen erkennt Clerk.js Einstellungen wie Sprache, Währung und Ländercode.

Die folgenden Beispiele zeigen, wie die verschiedenen Komponenten funktionieren.

Design Editor #

1. Erstelle eine Text-Komponente an der Stelle, an der der Preis angezeigt werden soll.

2. Füge folgenden Liquid-Code ein, um den Preis basierend auf dem Währungsumrechner innerhalb der Text-Komponente anzuzeigen:

{{ currency_symbol }}{{ item.price | currency_converter }}

Code-Modus #

1. Gehe in my.clerk.io zu Search/Recommendations > Designs und klicke bei deinem Design auf Edit Design.

2. Ersetze den bestehenden money oder money_eu Formatter für Preise durch currency_converter.

3. Klicke auf Update Design.

4. Jetzt kannst du die umgerechneten Preise und das Währungssymbol in deinem Design sehen.

Individuelle API-Lösung #

Disclaimer: Dies ist eine sehr individuelle Lösung, um Preisumrechnungen zu erhalten, wenn keine Daten von der Shopify API verfügbar sind. Verwende dies nur, wenn du eine spezielle, individuelle Einrichtung für Preisumrechnungen basierend auf geo-IP-Änderungen nutzt.

Hier findest du die Frontend-Lösungsdokumentation in Github.

In diesem Abschnitt wird erklärt, wie man kontextbezogene Daten in Echtzeit erhält, um sie innerhalb der von der Clerk API zurückgegebenen Inhalte anzuzeigen.

Das Designmuster besteht aus folgenden Teilen:

• Eine Kollektion, die alle Produkte enthält.

• Ein alternatives Layout zur Anzeige von Kollektionsinformationen als JSON.

• Eine JavaScript-Klasse, die die in der Kollektion bereitgestellten Daten sammelt.

• Ein JavaScript-Snippet, das die Daten für die relevanten Produkt-IDs aus einem gegebenen Ergebnis abruft und sie in ein div im Template einfügt.

Kollektion erstellen #

Um sicherzustellen, dass du eine Kollektion mit allen möglichen Produkten hast, erstelle eine Kollektion mit einer Bedingung, die auf alle Produkte zutrifft.

Die Kollektion sollte Clerk api heißen, damit sie auf das Frontend-Route /collection/clerk-api erhält.

Die Bedingung für die Kollektion sollte beispielsweise price > -1000000 sein.

Alternatives Layout erstellen #

Erstelle ein alternatives Layout, um deine Daten mit der Kollektion anzuzeigen.

Bearbeite dafür zuerst den Theme-Code des gewünschten Themes.

Unter dem Bereich Templates auf der linken Seite klicke auf Add new Template.

Wähle im Popup collection als Ressourcentyp aus.

Wähle liquid als Dateityp.

Schreibe json in das unterste Feld, sodass der Name des erstellten Templates collection.json.liquid ist.

Der Inhalt dieser Datei sollte die Datei collection.json.liquid sein, die sich im liquid-Ordner dieses Projekts befindet.

Du kannst nach Bedarf Felder zum Produkt in diesem Template hinzufügen.

JS-Klasse hinzufügen #

Um die Daten aus deiner Kollektion abzurufen und aufzubereiten, platziere den kompletten Inhalt der Datei index.js im Ordner class dieses Projekts innerhalb des Skript-Tags, das Clerk.js enthält, das du in theme.liquid eingefügt hast.

Das sollte so aussehen:

<script>
  // Clerk.js Injection Code
  // Clerk Config mit Key und Formatters
  // Klasse aus diesem Projekt
  clerk_shopify_api.init()
  // Schließlich init() für die Klasse, damit sie beim Laden der Seite ausgeführt wird.
</script>

Diese Klasse invalidiert die Daten anhand von Zeitstempel und Währungen, ohne dass du den Code ändern musst.

Die Zeit bis zur Invalidation beträgt 12 Stunden nach dem letzten Aufbau der Daten.

Jede Änderung im Währungskontext invalidiert die Daten ebenfalls.

Template-Funktion hinzufügen #

Binde die template.js im verwendeten Design-Template ein.

Die Funktion ruft die Daten ab, wenn sie verfügbar sind, und platziert sie in den spezifischen Kindelementen innerhalb jeder Produktkachel.

Im Beispiel sind die Felder list_price und price enthalten.

Zu beachten: Falls du Felder verwenden möchtest, die sich von price und list_price unterscheiden, füge diese in collection.json.liquid hinzu und bearbeite jeweils template.html und template.js so, dass sie diese Felder ebenfalls verarbeiten. Die in Schritt 3 beschriebene Klasse musst du nie bearbeiten.

Theme-Dateien finden #

Shopify bietet über 100 verschiedene Themes, um deinen Webshop zu gestalten und anzupassen.

Jedes Theme funktioniert gleich: Du passt die Theme-Dateien an, um auf deinem Shop ein bestimmtes Ergebnis zu erzielen.

Die Namen der Theme-Dateien unterscheiden sich jedoch von Theme zu Theme.

Shopify bietet dir ein Suchfeld, um die gewünschte Theme-Datei schnell und einfach zu finden.

Wenn du den Namen der gewünschten Datei nicht kennst, kannst du das Suchfeld nutzen, um sie zu finden.

Wenn du zum Beispiel die Datei für die Suchseite suchst, wird sie wahrscheinlich “search” im Dateinamen haben.

Wenn du unsicher bist, ob du die richtige Datei gefunden hast, kannst du das HTML in der Theme-Datei mit dem HTML auf der entsprechenden Seite vergleichen.

In Google Chrome geht das, indem du mit der rechten Maustaste auf einen Abschnitt der Seite klickst und ‘Inspect’ auswählst.

Du kannst dann das HTML auf der Seite inspizieren und prüfen, ob die class/ID der Elemente in der Datei mit denen auf der Seite übereinstimmt.

Benötigst du weitere Hilfe dabei, kannst du dich auch an unser Support-Team wenden.

Empfehlungen im Cart Drawer #

Die Installation durch einen Shopify-Entwickler wird dringend empfohlen.

Diese Anleitung beschreibt eine sehr individuell angepasste Lösung, die in verschiedenen Shopify-Themes unterschiedlich funktionieren kann. Sie ist speziell für Themes gedacht, bei denen der Warenkorb auf jeder Seite im DOM vorhanden ist, aber erst sichtbar wird, wenn der Nutzer ihn öffnet.

Empfehlungen von Clerk im Cart Drawer auf Shopify anzuzeigen ist eine großartige Möglichkeit, Kunden vor dem Kaufabschluss zusätzliche Produkte vorzuschlagen.

1. Bearbeite den Code deines Shopify-Themes bei Online Store > Themes > Edit code.

2. Finde die Datei mit dem Template für den Cart Drawer (meistens cart-drawer.liquid oder ähnlich).

3. Füge ein Clerk Recommendations Snippet aus Recommendations > Elements ein.

4. Benenne die Klasse von clerk um, um das Rendering zu steuern Steuerung des Renderings. Zum Beispiel, indem du sie clerk_m nennst:

<span class="clerk_m" data-template="@cart-others-also-bought" data-products="[{% for line_item in cart.items %}{% if forloop.index0 > 0 %}, {% endif %}{{ line_item.product.id }}{% endfor %}]"></span>

5. Füge zusammen mit dem obigen Snippet ein Skript hinzu, um Clerk Recommendations anzuzeigen, sobald der Benutzer den Warenkorb öffnet. Eine Möglichkeit ist die Verwendung eines MutationObservers. Das folgende Skript enthält alle Elemente und zeigt ein Beispiel, wie es gemacht werden kann:

<script>
    // Node auswählen, der auf Mutationen beobachtet werden soll
    const targetNode = document.querySelector("cart-drawer.drawer");

    // Alle Klassennamen des Cart Drawers, wenn er geöffnet ist
    const targetNodeClasses = "drawer animate active";

    // Optionen für den Observer (zu beobachtende Mutationen)
    const config = { attributes: true };

    let cartFetched = false;
    let previousitemsID = [];
    
    // Funktion, um Cart-Daten zu holen
    async function fetchCartData() {
        const response = await fetch("/cart.js");
        const data = await response.json();
        let itemsID = [];
        let cartItems = data.items;
        for (var i = 0; i < cartItems.length; i++) {
            itemsID.push(cartItems[i].product_id);
        }
        return itemsID;
    }

    // Callback, wenn Mutationen beobachtet werden
    const callback = async (mutationList, observer) => {
        for (const mutation of mutationList) {
            if (mutation.type === "attributes") {
                if (targetNode.className == targetNodeClasses && !cartFetched) {
                    cartFetched = true;
                    try {
                        const itemsID = await fetchCartData();
                          if (JSON.stringify(previousitemsID) != JSON.stringify(itemsID)) {
                            await Clerk('content', '.clerk_m', 'param', { products: itemsID })
                            previousitemsID = itemsID
                          }
                    } catch (error) {
                        console.error(error);
                    } finally {
                        cartFetched = false;
                    }
                }

            }
        }
    };

    // Observer-Instanz mit dem Callback erstellen
    const clerk_observer = new MutationObserver(callback);

    // Die Überwachung der Zielnode für konfigurierte Mutationen starten
    clerk_observer.observe(targetNode, config);
</script>

Deine Cart Drawer Datei sollte so aussehen:

HTTP-Authentifizierung #

HTTP-Authentifizierung wird häufig auf Staging-Seiten genutzt, um unerwünschte Besucher fernzuhalten.

Dadurch wird der Clerk Importer blockiert und im Sync-Log die Fehlermeldung 401 Unauthorized angezeigt.

Du kannst das 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 Synchronisationsfehler #

Beim Importieren von Daten mit der Shopify-Integration ist der Server deines Webshops für das Senden von Produkt-, Kategorie- und Verkaufsdaten an Clerk verantwortlich.

In einigen Fällen kann jedoch die Serverkonfiguration verhindern, dass der Importer Zugriff bekommt und somit ein Fehler unter Data Sync auftreten.

Hier findest du eine Liste der häufigsten Fehler und wie du sie behebst.

401 Unauthorized #

Dieser Fehler tritt auf, wenn für deinen Webshop oder deine Entwicklungsumgebung HTTP-Authentifizierung erforderlich ist.

Das Problem wird gelöst, indem du den Benutzernamen und das Passwort in die Import-URL aufnimmst:

http://username:password@awesomeshop.myshopify.com

Berechtigungsfehler #

Dieser Fehler tritt meist auf, wenn du für deine Private App keinen Lesezugriff auf Shop-Inhalte wie Artikel, Blogs, Kommentare, Seiten und Weiterleitungen gewährt hast.

So behebst du das Problem:

1. Logge dich bei Shopify ein und gehe zu Apps > Manage Private Apps > Clerk.io (oder dem von dir vergebenen App-Namen).

2. Scrolle zu Admin API Permissions und klicke auf Review disabled Admin API permissions.

3. Finde Shop-Inhalte wie Artikel, Blogs, Kommentare, Seiten und Weiterleitungen und wähle Read access:

4. Scrolle ganz nach oben und klicke auf Save.

Umgang mit require.js #

Dieser Guide gilt nur bei der Verwendung von Clerk.js 1.

In manchen Setups verhindert Require.js, dass Clerk.js geladen wird, sodass keine Slider oder Suchergebnisse angezeigt werden.

In diesem Fall siehst du im Konsolenfenster diesen Fehler:

Uncaught ReferenceError: Clerk is not defined

Es gibt zwei Wege, um mit Require.js umzugehen. Beide benötigen Änderungen am tracking-script, das normalerweise in index.liquid eingefügt ist.

In Require.js einbinden #

Die beste Methode ist, zu versuchen, dass Require.js Clerk erkennt.

Das geht, indem du am Ende des Tracking-Skripts require(['clerk'], function() {}); einfügst:

Require.js ignorieren #

Falls die obige Lösung nicht funktioniert, ist es möglich, Require.js zu ignorieren.

Füge dafür ganz oben im Tracking-Script window.__clerk_ignore_requirejs = true; ein:

Nachdem du eine dieser Lösungen verwendet hast, ist Require.js jetzt mit Clerk kompatibel.

Upgrade zu Clerk.js 2 #

Clerk.js 2 ist eine schnellere und flexiblere Version unserer JavaScript-Bibliothek.

Die Installation von Clerk auf jedem Webshop wird dadurch einfacher.

Da sich die beiden Versionen jedoch leicht unterscheiden, musst du diese Schritte befolgen, um erfolgreich zu upgraden.

Die zwei wichtigsten Änderungen in Clerk.js 2:

• Die Designs in my.clerk.io nutzen die Liquid Template-Sprache, können aber auch einfach über den 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 einen anderen Ansatz für Designs nutzt, musst du neue Designs erstellen.

Du kannst deine Clerk.js 2 Designs auf zwei Arten erstellen:

• Verwende den intuitiven Design Editor, um neue Designs zu erstellen, wie in den folgenden Punkten beschrieben.

• Konvertiere deine alten Designs. Folge dieser Anleitung, um zu sehen, wie das geht.

Design Editor Option #

1. Gehe zu my.clerk.io > Recommendations/Search > Designs > New Design.

2. Benenne im nächsten Schritt dein Design (Wir empfehlen, “V2” anzuhängen, damit klar ist, dass du Clerk.js 2 nutzt).

3. Wähle den Design-Typ aus.

4. Klicke auf Publish Design und fahre mit Schritt 2 der Anleitung fort.

5. Im Design Editor kannst du beliebige vorhandene Elemente wie Name, Bild, Button etc. bearbeiten oder neue Elemente hinzufügen, um mehr Informationen zu den Produkten anzuzeigen.

6. Klicke auf Publish. Damit sind diese Designs vorerst nicht im Shop sichtbar, bis Schritt 2 abgeschlossen ist. Wähle das neue Design für alle Elemente aus, die aktualisiert werden sollen.

7. Gehe zu Recommendations/Search > Elements und stelle das Clerk Element so um, dass es das neue Design nutzt.

Jetzt bist du bereit, auf Clerk.js 2 zu wechseln.

Script ersetzen #

1. Finde die Template-Datei, die auf allen Seiten des Webshops genutzt wird und in der das ursprüngliche Clerk.js Script fast am Ende enthalten ist.

2. Entferne das alte Script aus der Datei:

3. Gehe zu my.clerk.io > Developers > Tracking Code.. Diese Seite enthält jetzt deinen Clerk.js 2 Tracking-Code.

4. Kopiere diesen Code und füge ihn direkt vor dem </head>-Tag im Template ein:

5. Speichere dein Template.

Herzlichen Glückwunsch! Du verwendest jetzt das stark verbesserte Clerk.js 2-Setup!

Die komplette Dokumentation zu Clerk.js 2 findest du hier: https://docs.clerk.io/docs/clerkjs-quick-start

Zugriff auf Kundenevents #

Wenn wir dir beim Einrichten oder beim Troubleshooting des Order Trackings via Shopify-Pixel helfen, bitten wir dich ggf. um Zugriff auf den Bereich “Customer events” im Shopify-Backend.

Folge diesen Schritten, um die erforderlichen Rechte zu vergeben:

1. Gehe in Shopify zu Settings > Users and permissions.
2. Klicke auf das Teammitglied Clerk.io (oder den gewünschten Benutzer).
3. Scrolle zu Store settings und aktiviere:
   • View customer events
   • Manage and add custom pixels
4. Klicke auf Save.

Diese Rechte erlauben unserem Team, den Bereich “Customer events” zu sehen und den Clerk Pixel zu verwalten, sodass wir das Order Tracking korrekt überprüfen können.