FAQ

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

Währungsumrechnung #

Die in Shopify integrierte Währungsumrechnung macht es einfach, das Währungssymbol und den Wechselkurs vom 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 nutzt.

Standardlösung #

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

Dieses Beispiel nutzt unsere Standardvorlage 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 Stelle, an der der Preis erscheinen soll.

2. Fügen Sie den folgenden Liquid-Code hinzu, um den Preis basierend auf dem currency_converter im Textfeld anzuzeigen:

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

Code-Modus #

1. Gehen Sie in my.clerk.io zu Search/Recommendations > Designs und klicken Sie für Ihr 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. Sie sehen nun die umgerechneten Preise und das passende Währungssymbol in Ihrem Design.

Individuelle API-Lösung #

Haftungsausschluss: Dies ist eine sehr individuelle Lösung, um Preisumrechnungen zu erhalten, wenn keine Daten von der Shopify API verfügbar sind. Verwenden Sie diese Lösung nur, wenn Sie eine spezifische und individuelle Einrichtung für Preisumrechnungen basierend auf Geo-IP-Änderungen verwenden.

Die Dokumentation der Frontend-Lösung finden Sie auf Github.

Dieser Abschnitt behandelt, wie Sie Kontextdaten in Echtzeit erhalten, die innerhalb von Inhalten angezeigt werden, die von der Clerk API zurückgegeben werden.

Das Designmuster besteht aus folgenden Teilen:

• Eine Kollektion, die alle Produkte enthält.

• Ein alternatives Layout, um Kollektion-Informationen als JSON auszugeben.

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

• Ein JavaScript-Snippet, das die Daten für die relevanten Produkt-IDs im Ergebnis nutzt und diese in ein 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 für die Kollektion sollte in etwa price > -1000000 sein.

Alternatives Layout erstellen #

Erstellen Sie ein alternatives Layout, um Ihre Daten mithilfe der Kollektion darzustellen.

Bearbeiten Sie dazu zunächst den Theme-Code für das gewünschte Theme.

Wählen Sie im Bereich „Vorlagen“ auf der linken Seite Add new Template.

Wählen Sie im Popup collection als Ressourcentyp.

Wählen Sie liquid als Dateityp.

Tragen Sie in das unterste Feld json ein, sodass die Vorlage den Namen collection.json.liquid erhält.

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

Gerne können Sie nach Bedarf weitere Felder für das Produkt in dieser Vorlage anlegen.

JS-Klasse hinzufügen #

Um die Daten aus Ihrer Kollektion zu erfassen und für die weitere Nutzung vorzubereiten, fügen Sie den gesamten Inhalt von index.js aus dem Ordner class dieses Projekts in das Script-Tag mit Clerk.js in Ihrer theme.liquid ein.

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()
  // Zum Schluss init() für die Klasse, damit sie beim Laden der Seite ausgeführt wird.
</script>

Diese Klasse invalidiert die Daten basierend auf Zeitstempeln und Währungen, ohne dass Sie den Code anpassen müssen.

Die Zeit bis zur Invalidierung beträgt 12 Stunden seit der letzten Aktualisierung der Daten.

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

Template-Funktion hinzufügen #

Binden Sie die template.js-Datei in die Design-Vorlage ein, die verwendet wird.

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

Das Beispiel enthält die Felder list_price und price.

Beachten Sie: Falls Sie andere Felder als price und list_price nutzen möchten, fügen Sie sie in collection.json.liquid hinzu und passen dann template.html und template.js so an, dass diese Felder auch genutzt werden. Die in Schritt 3 beschriebene Klasse müssen Sie in der Regel nicht anpassen.

Theme-Dateien finden #

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

Jedes Theme funktioniert gleich – Sie passen die Theme-Dateien an, um ein bestimmtes Ergebnis auf Ihrem Shop zu erzielen.

Allerdings ändern sich die Namen der Theme-Dateien von Theme zu Theme.

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

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

Suchen Sie beispielsweise die Datei für die Suchseite, hat diese Datei wahrscheinlich ‘search’ im Dateinamen.

Sind Sie sich unsicher, ob Sie die richtige Datei gefunden haben, vergleichen Sie das HTML in der Theme-Datei mit dem HTML auf der betreffenden Seite, um zu sehen, ob diese übereinstimmen.

Das können Sie in Google Chrome tun, indem Sie mit Rechtsklick auf einen Bereich der Seite klicken und ‘Untersuchen’ auswählen.

Sie können anschließend das HTML der Seite prüfen und sehen, ob Klassen-/ID-Namen der Elemente in der Datei und auf der Seite übereinstimmen.

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

Empfehlungen im Warenkorb-Drawer #

Die Installation durch einen Shopify-Entwickler wird dringend empfohlen.

Diese Anleitung beschreibt eine stark individualisierte Lösung, die sich je nach Shopify-Theme unterschiedlich verhalten kann. Sie ist speziell für Themes konzipiert, bei denen der Warenkorb auf jeder Seite Teil des DOM ist, aber erst beim Öffnen durch den Nutzer sichtbar wird.

Die Anzeige von Clerk Recommendations im Warenkorb-Drawer ist eine gute Möglichkeit, Kunden vor dem Checkout weitere Produkte anzubieten.

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

2. Finden Sie die Datei, in der sich das Template für den Warenkorb-Drawer befindet (meist 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 die Darstellung zu steuern. Zum Beispiel 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. Fügen Sie zu dem oben stehenden Snippet ein Script hinzu, um Clerk Recommendations beim Öffnen des Warenkorbs auszulösen. Ein Ansatz ist die Nutzung von MutationObserver. Das nachfolgende Script enthält alle benötigten Elemente und zeigt, wie Sie vorgehen können:

<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>

Ihre Datei für den Warenkorb-Drawer sollte wie folgt aussehen:

HTTP-Authentifizierung #

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

Dadurch wird der Clerk Importer blockiert und zeigt im Sync-Log einen 401 Unauthorized-Fehler an.

Sie können dies beheben, indem Sie die Authentifizierungsdaten in der Import-URL hinterlegen.

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

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

Häufige Synchronisationsfehler #

Beim Import von Daten mit der Shopify-Integration sendet der Server Ihres Webshops Produkt-, Kategorie- und Verkaufsdaten an Clerk.

In manchen Fällen kann die Serverkonfiguration verhindern, dass der Importer Zugriff erhält, was zu einem Fehler in Data Sync führt.

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

401 Unauthorized #

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

Lösen Sie das Problem, indem Sie den Username und das Passwort in die Import-URL einfügen:

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

Berechtigungsfehler #

Dieser Fehler tritt meist auf, wenn Sie keinen Lesezugriff für Store content like articles, blogs, comments, pages and redirects in Ihrer Private App erteilt haben.

So beheben Sie das:

1. Loggen Sie sich in Shopify ein und gehen Sie zu Apps > Manage Private Apps > Clerk.io (oder der von Ihnen gewählte App-Name).

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

3. Suchen Sie den Abschnitt Store content like articles, blogs, comments, pages and redirects und wählen Sie Read access:

4. Scrollen Sie zum oberen Ende der Seite und klicken Sie auf Save.

Umgang mit require.js #

Diese Anleitung gilt nur für die Verwendung von Clerk.js 1.

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

Dann erscheint folgender Fehler in Ihrer Konsole:

Uncaught ReferenceError: Clerk is not defined

Es gibt zwei Möglichkeiten, Require.js zu handhaben. Für beide müssen Sie Änderungen am tracking-script vornehmen, das normalerweise in index.liquid eingebunden wird.

In Require.js einbinden #

Die beste Lösung ist, Require.js dazu zu bringen, Clerk zu erkennen.

Fügen Sie dazu require(['clerk'], function() {}); ans Ende des Tracking Scripts hinzu:

Require.js ignorieren #

Wenn die obige Lösung nicht funktioniert, können Sie Require.js ignorieren.

Fügen Sie dafür window.__clerk_ignore_requirejs = true; am Anfang des Tracking Scripts ein:

Nachdem Sie eine der beiden Lösungen umgesetzt haben, ist Require.js mit Clerk kompatibel.

Upgrade auf Clerk.js 2 #

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

Sie macht die Installation von Clerk in jedem Webshop einfacher.

Da sich die beiden Versionen in einigen Punkten unterscheiden, müssen Sie folgende Schritte für ein erfolgreiches Upgrade beachten.

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 unmittelbar vor dem </head>-Tag in Ihrem Webshop-Template eingefügt werden.

Designs erstellen #

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

Sie haben zwei Möglichkeiten, Ihre Clerk.js 2 Designs zu erstellen:

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

• Konvertieren Sie Ihre alten Designs. Folgen Sie dieser Anleitung, wie Sie das machen.

Option Design Editor #

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

2. Geben Sie auf dem nachfolgenden Bildschirm Ihrem Design einen Name (wir empfehlen, “V2” hinzuzufügen, damit erkennbar 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 in der Anleitung.

5. Im Design Editor können Sie bestehende Elemente wie Name, Bild, Button usw. bearbeiten oder neue Elemente zum Design hinzufügen, um weitere Produktinformationen anzuzeigen.

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

7. Gehen Sie zu Recommendations/Search > Elements und ändern Sie das Clerk-Element, damit es Ihr neues Design verwendet.

Sie sind jetzt bereit, auf Clerk.js 2 umzusteigen.

Script ersetzen #

1. Finden Sie die Template-Datei, die für die Darstellung aller Seiten des Webshops genutzt wird und in der das ursprüngliche Clerk.js-Script unten eingefügt ist.

2. Entfernen Sie das alte Script aus der Datei:

3. Gehen Sie zu my.clerk.io > Developers > Tracking Code.. Diese Seite zeigt nun Ihren Clerk.js 2 Tracking Code.

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

5. Speichern Sie Ihr Template.

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

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

Zugang zu Customer Events für Clerk gewähren #

Wenn wir Sie bei der Einrichtung oder Fehlerbehebung des Order Trackings via Shopify-Pixel unterstützen, kann es sein, dass wir um Zugang zum Bereich „Customer Events“ in Ihrem Shopify-Admin bitten.

So gewähren Sie die benötigten Berechtigungen:

1. Gehen Sie in Shopify zu Settings > Users and permissions.
2. Klicken Sie auf den Mitarbeiter Clerk.io (oder den Benutzer, 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.

Mit diesen Berechtigungen kann unser Team den Bereich Customer Events einsehen und den Clerk Pixel verwalten, damit wir überprüfen können, ob das Order Tracking korrekt funktioniert.