FAQ

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

Bildgrößen #

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

Wenn Ihr Design für verschiedene Platzierungen unterschiedliche Ausgabegerößen 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=' }}

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

Standardlösung #

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

Dieses Beispiel verwendet unsere Standard-Template-Sprache hier.

Bei 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 arbeiten.

Design Editor #

1. Erstellen Sie eine Text-Komponente an der Stelle, wo der Preis angezeigt werden soll.
2. Fügen Sie folgenden Liquid-Code ein, um den Preis basierend auf dem Currency Converter im Text-Element anzuzeigen:

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

Code-Modus #

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

Maßgeschneiderte API-Lösung #

Hinweis: Dies ist eine sehr individuelle Lösung, um Preisumrechnungen zu erhalten, wenn keine Daten aus der Shopify-API verfügbar sind. Verwenden Sie dies nur, wenn Sie eine spezielle, benutzerdefinierte Einrichtung für Preisumrechnungen aufgrund von Geo-IP-Änderungen verwenden.

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

Dieser Abschnitt erklärt, wie man kontextbezogene Daten in Echtzeit erhält, um sie im von der Clerk.io API zurückgegebenen Content anzuzeigen.

Das Design Pattern besteht aus folgenden Teilen:

• Einer Kollektion, die alle Produkte enthält.
• Ein alternatives Layout zum Rendern der Kollektion als JSON.
• Einer JavaScript-Klasse, die die in der Kollektion verfügbaren Daten sammelt.
• Ein JavaScript-Snippet, das die Daten für die relevanten Produkt-IDs in einem Ergebnis nutzt und sie in ein DIV im Template einfügt.

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 frontend erhält.

Die Bedingung für die Kollektion sollte z. B. price > -1000000 lauten.

Alternatives Layout erstellen #

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

Dafür bearbeiten Sie zunächst den Theme-Code des gewünschten Themes.

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

Wählen Sie im Popup collection als Ressourcentyp.

Wählen Sie liquid als Dateityp.

Schreiben Sie json in das unterste Feld, so dass der Name des Templates collection.json.liquid ist.

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 beliebig Felder hinzufügen.

JS-Klasse hinzufügen #

Um die Daten aus Ihrer Kollektion zu holen und vorzubereiten, damit Sie sie verwenden können, platzieren Sie den gesamten Inhalt von index.js aus dem class-Ordner dieses Projekts innerhalb des Script-Tags, das Clerk.js enthält und in theme.liquid platziert ist.

Das sollte ungefähr 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 macht Daten basierend auf Zeitstempel und Währungen ungültig, ohne dass Sie den Code ändern müssen.

Die Zeit bis zur Ungültigmachung beträgt 12 Stunden nach dem letzten Datenaufbau.

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

Template-Funktion hinzufügen #

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

Die Funktion holt die Daten, sobald sie verfügbar sind, und platziert sie in bestimmten Kindelementen innerhalb jeder Produktkachel.

Das Beispiel verwendet die Felder list_price und price.

Hinweis: Wenn Sie Felder verwenden müssen, die sich von price und list_price unterscheiden, fügen Sie diese in collection.json.liquid hinzu und passen Sie template.html sowie template.js entsprechend an. Die in Schritt 3 beschriebene Klasse müssen Sie in der Regel nicht ändern.

Theme-Dateien finden #

Shopify bietet über 100 verschiedene Themes zur Gestaltung und Anpassung Ihres Webshops.

Jedes Theme funktioniert gleich: Sie passen die Theme-Dateien an, um ein gewünschtes Ergebnis im Shop zu erzielen.

Allerdings ändern sich die Dateinamen von Theme zu Theme.

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

Wenn Sie den Namen der gesuchten Datei nicht wissen, können Sie das Suchfeld zur Hilfe nehmen.

Wenn Sie z. B. die Datei suchen, in der der Code für die Suchseite enthalten ist, wird diese wahrscheinlich ‘search’ im Dateinamen haben.

Wenn Sie nicht sicher sind, ob Sie die richtige Datei gefunden haben, können Sie den HTML-Code der Theme-Datei mit dem HTML der entsprechenden Seite vergleichen, um zu sehen, ob sie übereinstimmen.

Das geht in Google Chrome so: Rechtsklicken Sie auf einen beliebigen Bereich der Seite und wählen Sie ‘Untersuchen’.

Sie können dann den HTML-Code auf der Seite prüfen und kontrollieren, ob Klassen-/ID-Namen der Elemente mit denen in der Datei übereinstimmen.

Wenn Sie hierbei weitere Unterstützung benötigen, können Sie sich auch an unser Support-Team wenden.

Empfehlungen im Warenkorb-Drawer #

Die Installation durch einen Shopify-Entwickler wird dringend empfohlen.

Diese Anleitung beschreibt eine stark angepasste Lösung, die je nach Shopify-Theme unterschiedlich funktionieren kann. Sie ist speziell für Themes gedacht, bei denen der Warenkorb auf jeder Seite Teil des DOM ist, aber erst sichtbar wird, wenn er vom Nutzer geöffnet wird.

Das Anzeigen von Clerk.io Recommendations im Warenkorb-Drawer von Shopify ist eine großartige Möglichkeit, bevor der Kunde zur Kasse geht, Zusatzprodukte zu präsentieren.

1. Bearbeiten Sie den Code Ihres Shopify-Themes in Online Store > Themes > Edit code.
2. Suchen Sie die Datei mit dem Warenkorb-Drawer-Template (meist cart-drawer.liquid oder ähnlich genannt).
3. Fügen Sie einen Clerk.io Recommendations-Snippet aus Recommendations > Elements ein.
4. Bennenen Sie die Klasse von clerk um, um das Rendering zu steuern. Zum Beispiel, 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 dem obigen Snippet ein Script ein, um Clerk.io Recommendations anzuzeigen, wenn der Nutzer den Warenkorb öffnet. Eine Möglichkeit ist die Nutzung des MutationObserver. Das unten stehende Skript enthält alle relevanten Elemente als Beispiel:

<script>
    // Wählen Sie das zu überwachende Element für Änderungen
    const targetNode = document.querySelector("cart-drawer.drawer");

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

    // Optionen für den Observer (welche Änderungen überwacht werden)
    const config = { attributes: true };

    let cartFetched = false;
    let previousitemsID = [];
    
    // Funktion zum Abrufen der Warenkorb-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 bei beobachteten Veränderungen
    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 Callback-Funktion erstellen
    const clerk_observer = new MutationObserver(callback);

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

Speichern Sie die aktualisierte Warenkorb-Drawer-Datei und testen Sie, ob Clerk Empfehlungen angezeigt werden, wenn ein Produkt zum Warenkorb hinzugefügt wird.

HTTP-Authentifizierung #

HTTP-Authentifizierung wird oft auf Staging-Seiten verwendet, um unerwünschte Besucher auszuschließen.

Dies blockiert den Clerk.io Importer und führt im Sync-Protokoll zu einem 401 Unauthorized-Fehler.

Sie können dies beheben, indem Sie die Authentifizierungsinformationen in die Import-URL einfügen.

Aktualisieren Sie dazu in my.clerk.io > Data > Configuration 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 dafür verantwortlich, Produkt-, Kategorie- und Verkaufsdaten an Clerk.io zu senden.

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

Nachfolgend finden Sie die häufigsten Fehler und deren Behebung.

401 Unauthorized #

Dieser Fehler tritt auf, wenn für Ihren Webshop oder Ihr Dev-Umfeld HTTP-Authentifizierung erforderlich ist.

Lösen Sie dies, indem Sie den Benutzernamen und das Passwort in die Import-URL aufnehmen:

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

Berechtigungsfehler #

Dieser Fehler tritt in der Regel auf, wenn Sie Lesezugriff auf Store content like articles, blogs, comments, pages and redirects in Ihrer Private App nicht gewährt haben.

So beheben Sie es:

1. Melden Sie sich bei Shopify an und gehen Sie zu Apps > Manage Private Apps > Clerk.io (oder den von Ihnen vergebenen App-Namen).

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

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

4. Scrollen Sie nach oben und klicken Sie auf Save.

Umgang mit require.js #

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

In manchen Setups verhindert Require.js das Laden von Clerk.js, sodass keine Slider oder Suchergebnisse angezeigt werden.

In diesem Fall 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 das tracking-script anpassen, das normalerweise in index.liquid eingefügt wird.

In Require.js einbinden #

Die beste Methode ist, zu versuchen, Clerk.io in Require.js einzubinden.

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

Require.js ignorieren #

Falls die obige Lösung nicht funktioniert, kann Require.js ignoriert werden.

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

Nach Anwendung einer der beiden Methoden ist Require.js kompatibel mit Clerk.io.

Upgrade auf Clerk.js 2 #

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

Damit wird die Installation von Clerk.io in jedem Webshop einfacher.

Da sich beide Versionen leicht unterscheiden, sind folgende Schritte für ein erfolgreiches Upgrade notwendig.

Die zwei wichtigsten Unterschiede in Clerk.js 2 sind:

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

Designs erstellen #

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

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

• Verwenden Sie den intuitiven Design Editor zur Erstellung neuer Designs, wie in den folgenden Punkten beschrieben.
• Konvertieren Sie Ihre alten Designs. Folgen Sie dieser Anleitung, um zu erfahren, wie.

Option Design Editor #

1. Gehen Sie zu my.clerk.io > Recommendations/Search > Designs > New Design.
2. Geben Sie dem Design einen Namen (wir empfehlen “V2” hinzuzufügen).
3. Wählen Sie den Design-Typ.
4. Klicken Sie auf Publish Design, wenn Sie fertig sind, und machen Sie weiter mit Schritt 2.
5. Im Design Editor klicken Sie auf bestehende Elemente wie Name, Bild, Button etc., um sie zu bearbeiten, oder fügen Sie neue hinzu, um weitere Informationen anzuzeigen.
6. Klicken Sie auf Publish. Dadurch werden sie 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.
7. Gehen Sie zu Recommendations/Search > Elements und ändern Sie Ihr Clerk.io Element auf das neue Design.

Sie sind nun bereit für die Umstellung auf Clerk.js 2.

Skript ersetzen #

1. Finden Sie die Template-Datei, in der das Clerk.js-Skript im unteren Bereich eingetragen ist und die für alle Shopseiten genutzt wird.

2. Entfernen Sie das alte Skript aus der Datei:

3. Gehen Sie zu my.clerk.io > Developers > Tracking Code. Hier finden Sie Ihren neuen Clerk.js 2 Tracking Code.

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

5. Speichern Sie Ihr Template.

Glückwunsch! Sie verwenden jetzt 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

Zugriff auf Kundenevents #

Wenn wir Sie beim Einrichten oder Beheben von Problemen bei der Bestellverfolgung mit Shopify-Pixeln unterstützen, werden wir unter Umständen um Zugriff auf den Bereich Customer events in Ihrem Shopify-Admin bitten.

Gehen Sie wie folgt vor, um die erforderlichen Rechte zu vergeben:

1. In Shopify gehen Sie zu Settings > Users and permissions.
2. Klicken Sie auf den Mitarbeiter Clerk.io (oder den zu aktualisierenden Benutzer).
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 den Zugriff auf den Bereich Customer events und die Verwaltung des Clerk.io Pixels, um zu überprüfen, ob die Bestellverfolgung korrekt funktioniert.