FAQ

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

Bildgrößen #

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

Wenn Ihr Design für jede Platzierung eine andere Ausgabengröß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 Standardbildgröße):

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

Dies 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 geliefert, der funktioniert, solange Ihre Drittanbieter-App das integrierte Währungsobjekt von Shopify verwendet.

Standardlösung #

Sie müssen einen Formatter in Ihren Designs verwenden, um Preise umzurechnen.

Dieses Beispiel verwendet unsere Standard-Template-Sprache hier.

Beim Einsatz 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 Stelle, an der der Preis erscheinen soll.
2. Fügen Sie folgenden Liquid-Code ein, um den Preis basierend auf dem Währungskonverter in der Textkomponente anzuzeigen:

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

Code-Modus #

1. Gehen Sie in my.clerk.io zu Search/Recommendations > Designs und klicken Sie auf Design bearbeiten für Ihr Design.
2. Ersetzen Sie den vorhandenen money- oder money_eu-Formatter für Preise mit currency_converter.
3. Klicken Sie auf Design aktualisieren.
4. Sie können jetzt die umgerechneten Preise und das Währungssymbol in Ihrem Design sehen.

Eigene API-Lösung #

Haftungsausschluss: Dies ist eine sehr individuelle Lösung für Preisumrechnungen, falls keine Daten von der Shopify-API bereitgestellt werden. Verwenden Sie dies nur, wenn Sie ein spezifisches und individuelles Setup für Preisumrechnungen basierend auf Geo-IP-Änderungen nutzen.

Die Frontend-Lösungsdokumentation finden Sie bei Github.

Dieser Abschnitt beschreibt, wie Sie in Echtzeit kontextbezogene Daten erhalten, die in Inhalten aus der Clerk.io API angezeigt werden sollen.

Das Entwurfsmuster setzt sich aus folgenden Teilen zusammen:

• Eine Kollektion, die alle Produkte enthält.
• Ein alternatives Layout zur Darstellung der Kollektion 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 im Ergebnis verwendet und sie in einem Div im Template platziert.

Kollektion erstellen #

Um sicherzustellen, dass Sie eine Kollektion mit allen möglichen Produkten haben, erstellen Sie eine Kollektion mit einer Bedingung, die von allen Produkten erfüllt wird.

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

Die Bedingung sollte ähnlich wie price > -1000000 lauten.

Alternatives Layout erstellen #

Erstellen Sie ein alternatives Layout, um Ihre Daten mit der Kollektion anzuzeigen.

Öffnen Sie dazu zunächst den Theme-Code des gewünschten Themes.

Unter “Templates” auf der linken Seite klicken Sie auf Add new Template.

Im Popup wählen Sie collection als Ressourcentyp.

Wählen Sie liquid als Dateityp.

Geben Sie json im untersten Feld als Namen ein, damit die Datei collection.json.liquid heißt.

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

Sie können bei Bedarf gerne Felder im Template hinzufügen.

JS-Klasse hinzufügen #

Um die Daten aus Ihrer Kollektion zu erfassen und aufzubereiten, damit sie genutzt werden können, platzieren Sie den gesamten Inhalt von index.js im class-Ordner dieses Projekts innerhalb des Skript-Tags, das Clerk.js in theme.liquid enthält.

Das könnte beispielsweise so aussehen:

<script>
  // Clerk.js Injection Code
  // Clerk Config with Key and Formatters
  // Class from this project
  clerk_shopify_api.init()
  // Schließlich init() für die Klasse, damit sie beim Laden der Seite ausgeführt wird.
</script>

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

Die Lebensdauer, bevor Daten ungültig werden, beträgt 12 Stunden seit der letzten Erstellung.

Jede Änderung im Währungskontext macht die Daten ebenfalls ungültig.

Template-Funktion hinzufügen #

Binden Sie template.js im genutzten Design-Template ein.

Die Funktion ruft die Daten bei Verfügbarkeit ab und platziert sie in bestimmten Kindelementen innerhalb jeder Produktkachel.

Das Beispiel enthält die Felder list_price und price.

Hinweis: Sollten Sie andere Felder als price und list_price benötigen, fügen Sie diese in collection.json.liquid hinzu und passen Sie anschließend template.html und template.js so an, dass sie diese Felder ebenfalls nutzen. Die in Schritt 3 beschriebene Klasse müssen Sie nicht anpassen.

Theme-Dateien finden #

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

Jedes Theme funktioniert gleich – Sie bearbeiten die Theme-Dateien, um das gewünschte Ergebnis im Shop zu erzielen.

Die Dateinamen variieren jedoch von Theme zu Theme.

Shopify bietet ein Suchfeld, mit dem Sie eine gewünschte Theme-Datei schnell finden.

Wenn Sie den Namen der gesuchten Datei nicht kennen, können Sie das Suchfeld nutzen, um sie zu finden.

Wenn Sie beispielsweise den Code der Suchseite suchen, wird die Datei wahrscheinlich “search” im Dateinamen haben.

Falls Sie unsicher sind, ob Sie die richtige Datei gefunden haben, können Sie den HTML-Code der Theme-Datei mit dem HTML-Code der jeweiligen Seite vergleichen, um zu schauen, ob sie übereinstimmen.

Das geht in Google Chrome, indem Sie mit der rechten Maustaste auf einen Bereich der Seite klicken und ‘Untersuchen’ auswählen.

Sie können dann das HTML der Seite untersuchen und prüfen, ob Klassen/IDs von Elementen in der Datei mit denen auf der Seite übereinstimmen.

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

Empfehlungen im Warenkorb-Drawer #

Die Installation durch einen Shopify-Entwickler wird dringend empfohlen.

Diese Anleitung beschreibt eine stark angepasste Lösung, die sich je nach Shopify-Theme unterschiedlich verhalten kann. Sie ist speziell für Themes konzipiert, bei denen sich der Warenkorb im DOM aller Seiten befindet, aber erst durch Nutzerinteraktion angezeigt wird.

Die Anzeige von Clerk.io Recommendations im Warenkorb-Drawer auf Shopify ist eine großartige Möglichkeit, Käufern vor dem Checkout zusätzliche Produkte zu präsentieren.

1. Bearbeiten Sie den Code Ihres Shopify-Themes in Online Store > Themes > Edit code.
2. Suchen Sie die Datei, in der das Cart-Drawer-Template abgelegt ist (meistens cart-drawer.liquid o. ä.).
3. Fügen Sie ein Clerk.io Recommendations-Snippet aus Recommendations > Elements ein.
4. Benennen Sie die Klasse von clerk um, um das Rendering zu steuern control the rendering. Z. B. indem Sie sie clerk_m nennen:

<span
  class="clerk_m"
  data-template="@cart-others-also-bought"
  data-products="[{% for item in cart.items %}{{ item.product_id }}{% unless forloop.last %}, {% endunless %}{% endfor %}]"
></span>

1. Fügen Sie zusammen mit oben stehendem Snippet ein Script ein, welches Clerk.io Recommendations rendert, sobald der Nutzer den Warenkorb öffnet. Eine Möglichkeit ist, einen MutationObserver zu verwenden. Das folgende Skript enthält alle diese Elemente – als Beispiel für die Umsetzung:

<script>
    // Select the node that will be observed for mutations
    const targetNode = document.querySelector("cart-drawer.drawer");

    // Add all of the class names of the cart drawer, when it is opened
    const targetNodeClasses = "drawer animate active";

    // Options for the observer (which mutations to observe)
    const config = { attributes: true };

    let cartFetched = false;
    let previousitemsID = [];
    
    // Function to fetch cart data
    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 function to execute when mutations are observed
    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;
                    }
                }

            }
        }
    };

    // Create an observer instance linked to the callback function
    const clerk_observer = new MutationObserver(callback);

    // Start observing the target node for configured mutations
    clerk_observer.observe(targetNode, config);
</script>

Speichern Sie die bearbeitete Datei des Cart-Drawers und testen Sie, ob Clerk-Empfehlungen angezeigt werden, sobald ein Produkt in den Warenkorb gelegt wurde.

HTTP-Authentifizierung #

HTTP-Authentifizierung wird oft auf Staging-Seiten eingesetzt, um unerwünschte Besucher zu vermeiden.

Dadurch wird der Clerk.io-Importer blockiert und ein 401 Unauthorized-Fehler im Sync-Log angezeigt.

Sie beheben dies, indem Sie die Authentifizierungsdaten in die Import-URL einfügen.

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

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

Häufige Sync-Fehler #

Beim Import von Daten mit der Shopify-Integration ist Ihr Webshop-Server verantwortlich, Produkt-, Kategorie- und Umsatzdaten an Clerk.io zu senden.

In manchen Fällen kann jedoch die Serverkonfiguration den Importer blockieren und einen Fehler bei Data Sync auslösen.

Im Folgenden finden Sie eine Liste häufiger Fehler und deren Behebung.

401 Unauthorized #

Dieser Fehler tritt auf, wenn für Ihren Webshop oder Ihre Entwicklungsumgebung eine HTTP-Authentifizierung benötigt wird.

Abhilfe schaffen Sie, indem Sie Benutzername und Passwort in die Import-URL einfügen:

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

Berechtigungsfehler #

Dieser Fehler tritt meist auf, wenn Sie keinen Lesezugriff auf Speicherinhalte wie Artikel, Blogs, Kommentare, Seiten und Weiterleitungen in Ihrer privaten App 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 auch immer Sie die App benannt haben).

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

3. Suchen Sie Speicherinhalte wie Artikel, Blogs, Kommentare, Seiten und Weiterleitungen und wählen Sie Lesezugriff:

4. Gehen Sie oben auf der Seite auf Speichern.

Umgang mit require.js #

Diese Anleitung gilt nur beim Einsatz von Clerk.js 1.

In manchen Setups verhindert Require.js das Laden von Clerk.js – dadurch werden keinerlei Slider oder Suchergebnisse angezeigt.

In diesem Fall erscheint folgender Fehler in der Konsole:

Uncaught ReferenceError: Clerk is not defined

Es gibt zwei Wege, um Require.js zu behandeln. Beide Methoden machen Änderungen am tracking-script erforderlich, das normalerweise in index.liquid eingefügt ist.

In Require.js einbinden #

Die beste Lösung ist, Clerk.io für Require.js verfügbar zu machen.

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

Require.js ignorieren #

Sollte die obige Lösung nicht funktionieren, kann Require.js ignoriert werden.

Setzen Sie window.__clerk_ignore_requirejs = true; an den Anfang des Tracking-Skripts.

Nach einer dieser Anpassungen ist Require.js problemlos mit Clerk.io nutzbar.

Upgrade zu Clerk.js 2 #

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

Es vereinfacht die Installation von Clerk.io in jedem Webshop.

Da sich die beiden Versionen jedoch leicht unterscheiden, müssen Sie folgende Schritte befolgen, um erfolgreich zu upgraden.

Die zwei wichtigsten Unterschiede in Clerk.js 2 sind:

• Die Designs in my.clerk.io nutzen die Liquid Templating-Sprache, können aber auch einfach mit dem Design Editor erstellt werden.
• Das Skript muss unmittelbar vor dem </head>-Tag im Template Ihres Webshops eingefügt werden.

Designs erstellen #

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

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

• Verwenden Sie den intuitiven Design Editor zum Erstellen neuer Designs wie im Folgenden beschrieben.
• Konvertieren Sie Ihre alten Designs. Folgen Sie dieser Anleitung für Details zur Umstellung.

Option Design Editor #

1. Gehen Sie zu my.clerk.io > Recommendations/Search > Designs > New Design.
2. Benennen Sie Ihr Design im nächsten Schritt (wir empfehlen, “V2” anzuhängen, um erkenntlich zu machen, dass Sie Clerk.js 2 nutzen).
3. Wählen Sie den Design-Typ.
4. Klicken Sie auf Design veröffentlichen und wechseln Sie in Schritt 2 der Anleitung.
5. Im Design Editor können Sie bestehende Elemente wie Name, Bild, Button etc. bearbeiten oder neue Elemente hinzufügen, um z. B. weitere Produktdetails anzuzeigen.
6. Klicken Sie auf Veröffentlichen – dadurch werden sie vorübergehend nicht im Webshop angezeigt, bis Sie mit Schritt 2 fertig sind. Wählen Sie für alle zu aktualisierenden Elemente das neue Design.
7. Gehen Sie zu Recommendations/Search > Elements und ändern Sie das jeweilige Clerk.io-Element auf das neue Design.

Jetzt können Sie zu Clerk.js 2 wechseln.

Skript ersetzen #

1. Finden Sie die Template-Datei, die für alle Seiten Ihres Webshops genutzt wird und in der das ursprüngliche Clerk.js-Skript (am Ende) enthalten ist.

2. Entfernen Sie das alte Skript aus der Datei:

3. Gehen Sie zu my.clerk.io > Developers > Clerk.js. Diese Seite enthält nun Ihren Clerk.js 2 Tracking-Code.

4. Kopieren Sie den Code und fügen Sie ihn unmittelbar vor dem </head>-Tag im Template ein.

5. Speichern Sie das Template.

Herzlichen Glückwunsch! Sie nutzen nun die stark verbesserte Clerk.js 2-Lösung!

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

Customer Events-Zugang #

Wenn wir Ihnen beim Einrichten oder beim Troubleshooting der Bestellverfolgung über Shopify Pixels helfen, werden wir Sie eventuell um Zugriff auf den Bereich “Customer events” im Shopify-Admin bitten.

So vergeben Sie die nötigen Rechte:

1. Gehen Sie in Shopify zu Settings > Users and permissions.
2. Klicken Sie auf den Mitarbeiternamen Clerk.io (oder den Nutzer, 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 es unserem Team, den Bereich Customer Events zu sehen und den Clerk.io Pixel zu verwalten, um die Bestellverfolgung korrekt zu prüfen.