FAQ

Probleme mit Ihrer Shopify-Integration? Diese FAQ behandelt die häufigsten Probleme und deren Lösungen – von Währungsumrechnung bis zu Speicherorten von Theme-Dateien.

Bildgrößen #

Shopify-Bild-URLs können feste Dimensionen vom Sync enthalten, zum Beispiel _600x600.

Wenn Ihr Design für jede Platzierung eine andere Ausgabegröße benötigt, können Sie die synchronisierte feste Größe entfernen und eine neue Breite in der URL anfordern.

Beispiel (ersetzen Sie 600x600 durch Ihre konfigurierte Standard-Bildgröß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 Sie vermeiden möchten, mehrere Bildattribute zu synchronisieren.

Währungsumrechnung #

Die integrierte Währungsumrechnung von Shopify macht es einfach, das Währungssymbol und den Wechselkurs aus dem Webshop auszulesen.

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

Standardlösung #

Sie müssen einen Formatter in Ihren 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. Erstellen Sie eine Text-Komponente, an der die Preise angezeigt werden sollen.

2. Fügen Sie der Text-Komponente folgenden Liquid-Code hinzu, um den Preis anhand des Währungskonverters anzuzeigen:

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

Code-Modus #

1. Navigieren Sie in my.clerk.io zu Search/Recommendations > Designs und klicken Sie bei Ihrem Design auf Edit Design.

2. Ersetzen Sie den vorhandenen money- oder money_eu-Formatter für Preise durch currency_converter.

3. Klicken Sie auf Update Design.

4. Nun sehen Sie die umgerechneten Preise und das Währungssymbol in Ihrem Design.

Individuelle API-Lösung #

Haftungsausschluss: Dies ist eine sehr individuelle Lösung für Preisumrechnungen, wenn keine Daten aus der Shopify API zur Verfügung stehen. Verwenden Sie diese nur, wenn Sie ein spezifisches und individuelles Setup für Preisumrechnung auf Basis von Geo-IP nutzen.

Die Dokumentation dieser Frontend-Lösung finden Sie in Github.

In diesem Abschnitt wird beschrieben, wie Sie kontextbezogene Daten in Echtzeit abrufen, um sie im Inhalt anzuzeigen, der von der Clerk API zurückgegeben wird.

Das Design-Muster besteht aus folgenden Teilen:

• Eine Kollektion, die alle Produkte enthält.

• Ein alternatives Layout zur Darstellung der Kollektion als JSON.

• Eine JavaScript-Klasse, die die in der Kollektion verfügbaren Daten sammelt.

• Ein JavaScript-Snippet, das die Daten für die betreffenden Produkt-IDs abruft und in einem Div-Element im Template anzeigt.

Kollektion erstellen #

Um sicherzustellen, dass Sie eine Kollektion mit allen möglichen Produkten haben, erstellen Sie eine Kollektion mit einer Bedingung, die auf alle Produkte zutrifft.

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

Die Bedingung könnte z. B. price > -1000000 lauten.

Alternatives Layout erstellen #

Erstellen Sie ein alternatives Layout zur Anzeige Ihrer Daten mittels der Kollektion.

Bearbeiten Sie hierfür zunächst den Theme-Code des gewünschten Themes.

Unter dem Bereich “Vorlagen” auf der linken Seite klicken Sie auf Add new Template.

Wählen Sie im Popup collection als Ressourcentyp.

Wählen Sie als Dateityp liquid.

Tragen Sie im untersten Feld json ein, sodass der Name der angelegten Vorlage collection.json.liquid lautet.

Der Inhalt dieser Datei sollte der collection.json.liquid-Datei aus dem liquid-Ordner dieses Projekts entsprechen.

Sie können dem Produkt in dieser Vorlage zusätzliche Felder hinzufügen, wenn nötig.

JS-Klasse hinzufügen #

Um die Daten aus Ihrer Kollektion zu holen und aufzubereiten, legen Sie den gesamten Inhalt von index.js aus dem class-Ordner dieses Projekts innerhalb des Skript-Tags mit Clerk.js in theme.liquid ab.

Das sollte in etwa so aussehen:

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

Diese Klasse invalidiert Daten anhand von Zeitstempel und Währungen, ohne dass Sie den Code ändern müssen.

Die Zeit vor Invalidierung beträgt 12 Stunden nach dem letzten Datenaufbau.

Jede Änderung des Währungskontexts invalidiert die Daten ebenso.

Template-Funktion hinzufügen #

Binden Sie die template.js in das verwendete Design-Template ein.

Die Funktion holt die Daten, wenn verfügbar, und platziert sie in spezifischen Kind-Elementen innerhalb jeder Produktkachel.

Das Beispiel umfasst die Felder list_price und price.

Wichtig: Wenn Sie Felder verwenden möchten, die sich von price und list_price unterscheiden, fügen Sie sie in collection.json.liquid hinzu und passen Sie auch template.html und template.js an. Die in Schritt 3 beschriebene Klasse müssen Sie nie ändern.

Theme-Dateien finden #

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

Alle Themes funktionieren gleich – Sie passen die Theme-Dateien an, um ein bestimmtes Ergebnis im Shop zu erzielen.

Die Dateinamen der Themes unterscheiden sich allerdings je nach Template.

Shopify stellt Ihnen ein Suchfeld zur Verfügung, mit dem Sie die gewünschte Theme-Datei leicht finden können.

Wenn Sie den Namen der Datei nicht kennen, die Sie suchen, können Sie das Suchfeld zur Orientierung verwenden.

Wenn Sie z. B. die Datei für die Suchseite suchen, wird der Dateiname vermutlich ‘search’ enthalten.

Falls Sie nicht sicher sind, ob Sie die richtige Datei gefunden haben, vergleichen Sie das HTML in der Theme-Datei mit dem HTML der entsprechenden Seite, um zu prüfen, ob sie übereinstimmen.

Dies können Sie in Google Chrome tun, indem Sie mit der rechten Maustaste auf einen beliebigen Bereich der Seite klicken und ‘Untersuchen’ wählen.

Nun können Sie das HTML der Seite prüfen und sehen, ob Klassen/ID der Elemente in der Datei mit denen auf der Seite übereinstimmen.

Wenn Sie weitere Hilfe benötigen, wenden Sie sich gern an unser Support-Team.

Empfehlungen im Cart Drawer #

Die Installation durch einen Shopify-Entwickler wird dringend empfohlen.

Diese Anleitung beschreibt eine sehr individuelle Lösung, die sich je nach Shopify-Theme unterschiedlich verhalten kann. Sie ist explizit für Themes gedacht, bei denen der Warenkorb auf jeder Seite im DOM liegt, aber erst sichtbar wird, wenn der Nutzer ihn öffnet.

Die Anzeige von Clerk Recommendations im Cart Drawer auf Shopify ist eine großartige Möglichkeit, Käufern vor dem Checkout weitere Produkte anzuzeigen.

1. Bearbeiten Sie den Code Ihres Shopify-Themes in Online Store > Themes > Edit code.

2. Suchen Sie die Datei, in der sich das Cart Drawer-Template befindet (meistens cart-drawer.liquid oder ähnlich).

3. Fügen Sie ein Clerk Recommendations-Snippet aus Recommendations > Elements ein.

4. Benennen Sie die Klasse von clerk um, um das Rendering zu steuern, z. B. in clerk_m:

<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. Zusätzlich zum obigen Snippet, fügen Sie ein Skript ein, das Clerk Recommendations rendert, sobald der Warenkorb geöffnet wird. Eine Möglichkeit ist die Verwendung eines MutationObservers. Das folgende Skript enthält alle erforderlichen Elemente und dient Ihnen als Beispiel:

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

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

    // Optionen für den Observer
    const config = { attributes: true };

    let cartFetched = false;
    let previousitemsID = [];
    
    // Funktion zum Abrufen der Cart-Daten
    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-Funktion für Mutationen
    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 erzeugen
    const clerk_observer = new MutationObserver(callback);

    // Beobachtung starten
    clerk_observer.observe(targetNode, config);
</script>

Ihre Cart Drawer-Datei sollte dann so aussehen:

HTTP-Authentifizierung #

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

Dies blockiert den Clerk-Importer und zeigt einen 401 Unauthorized-Fehler im Synchronisationsprotokoll an.

Sie beheben das, indem Sie die Authentifizierungsdaten in die Import-URL eintragen.

In my.clerk.io > Data > Configuration aktualisieren Sie Ihre Import-URL so:

https://USER:PASS@www.ewoksRus.com

Häufige Sync-Fehler #

Beim Importieren von Daten mit der Shopify-Integration ist Ihr Webshop-Server dafür verantwortlich, Produkt-, Kategorie- und Verkaufsdaten an Clerk zu senden.

In manchen Fällen kann die Serverkonfiguration verhindern, dass der Importer Zugriff erhält, was einen Fehler in Data Sync verursacht.

Nachfolgend finden Sie eine Liste der häufigsten Fehler und deren Lösungen.

401 Unauthorized #

Dieser Fehler tritt auf, wenn Ihr Webshop oder Ihre Entwicklungsumgebung HTTP-Authentifizierung erfordert.

Lösung: Geben Sie Benutzername und Passwort in der Import-URL an:

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

Berechtigungsfehler #

Dieser Fehler tritt in der Regel auf, wenn Sie Lesezugriff auf Shop-Inhalte wie Artikel, Blogs, Kommentare, Seiten und Weiterleitungen in Ihrer privaten App nicht gewährt haben.

So beheben Sie das:

1. Melden Sie sich bei Shopify an und gehen Sie zu Apps > Manage Private Apps > Clerk.io (oder wie die App benannt wurde).

2. Scrollen Sie zu Admin API Permissions und klicken Sie auf Review disabled Admin API permissions.

3. Suchen Sie Shop-Inhalte wie Artikel, Blogs, Kommentare, Seiten und Weiterleitungen und wählen Sie Read access:

4. Scrollen Sie zum Seitenanfang und klicken Sie auf Save.

Umgang mit require.js #

Diese Anleitung gilt nur bei Nutzung 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 erscheint folgender Fehler in der Konsole:

Uncaught ReferenceError: Clerk is not defined

Es gibt zwei Möglichkeiten, mit Require.js umzugehen. Beide Methoden erfordern Änderungen am tracking-script, das normalerweise in index.liquid eingefügt wird.

In Require.js einbinden #

Die beste Methode ist es, Require.js so zu konfigurieren, dass Clerk erkannt wird.

Fügen Sie dazu am Ende des Tracking-Skripts require(['clerk'], function() {}); ein:

Require.js ignorieren #

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

Dazu fügen Sie am Anfang des Tracking-Skripts window.__clerk_ignore_requirejs = true; ein:

Nach Anwendung einer der beiden Lösungen arbeitet Require.js jetzt mit Clerk zusammen.

Upgrade zu Clerk.js 2 #

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

Damit wird die Installation von Clerk auf jedem Webshop vereinfacht.

Da sich die beiden Versionen aber geringfügig unterscheiden, müssen Sie für das Upgrade folgende Schritte durchführen.

Die zwei wichtigsten Unterschiede in Clerk.js 2 sind:

• Die Designs in my.clerk.io verwenden 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 Ihres Webshops eingefügt werden.

Designs erstellen #

Da Clerk.js 2 einen anderen Ansatz für Designs hat, müssen Sie neue Designs erstellen.

Sie können Ihre Clerk.js 2-Designs auf zwei Arten erstellen:

• Verwenden Sie den intuitiven Design Editor, wie in den folgenden Punkten beschrieben.

• Konvertieren Sie Ihre alten Designs. Siehe diese Anleitung für die Vorgehensweise

Design Editor-Variante #

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

2. Geben Sie Ihrem Design im nächsten Schritt einen Namen (wir empfehlen die Ergänzung “V2”, damit klar ist, dass Sie Clerk.js 2 nutzen).

3. Wählen Sie den Design-Typ.

4. Klicken Sie auf Publish Design, wenn Sie fertig sind, und gehen Sie zu Schritt 2 der Anleitung.

5. Im Design Editor können Sie vorhandene Elemente wie Name, Bild, Button etc. bearbeiten oder neue Elemente hinzufügen, um mehr Produktinfos anzuzeigen.

6. Klicken Sie auf Publish. Dadurch werden diese Designs vorübergehend nicht im Webshop angezeigt, bis Schritt 2 abgeschlossen wurde. Wählen Sie das neue Design für alle zu aktualisierenden Elemente aus.

7. Gehen Sie zu Recommendations/Search > Elements und legen Sie für Ihr Clerk-Element das neue Design fest.

Sie sind jetzt bereit für den Wechsel auf Clerk.js 2.

Script ersetzen #

1. Suchen Sie die Template-Datei, die für alle Seiten des Webshops verwendet wird und in der das ursprüngliche Clerk.js-Script am Ende steht.

2. Entfernen Sie das alte Script aus der Datei:

3. Gehen Sie zu my.clerk.io > Developers > Tracking Code.. Hier befindet sich jetzt Ihr Clerk.js 2 Tracking-Code.

4. Kopieren Sie diesen Code und fügen Sie ihn direkt vor dem </head> Tag im Template ein:

5. Speichern Sie Ihr Template.

Herzlichen Glückwunsch! Sie nutzen jetzt das deutlich verbesserte Clerk.js 2-Setup!

Die vollständige Dokumentation zu Clerk.js 2 finden Sie hier: https://docs.clerk.io/docs/clerkjs-quick-start

Zugriff auf Kundenereignisse #

Wenn wir Sie bei der Einrichtung oder Fehlersuche beim Order-Tracking per Shopify Pixel unterstützen, bitten wir Sie ggf. um Zugriff auf den Bereich “Customer events” in Ihrem Shopify-Adminbereich.

Befolgen Sie diese Schritte, um die notwendigen Berechtigungen zu vergeben:

1. Gehen Sie in Shopify zu Settings > Users and permissions.
2. Klicken Sie auf den Mitarbeiter mit dem Namen Clerk.io (oder den Mitarbeiter, den Sie aktualisieren möchten).
3. Scrollen Sie zu Store settings und aktivieren Sie:
   • View customer events
   • Manage and add custom pixels
4. Klicken Sie auf Save.

Diese Berechtigungen ermöglichen unserem Team die Ansicht des “Customer events”-Bereichs und die Verwaltung des Clerk-Pixels, damit wir überprüfen können, ob das Order-Tracking korrekt funktioniert.