FAQ

Probleme mit deiner Shopify-Integration? Diese FAQ deckt die häufigsten Probleme und deren Lösungen ab, von Währungsumrechnung bis hin zu Speicherorten von Theme-Dateien.

Bildgrößen #

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

Wenn dein Design je Platzierung eine andere Ausgabegröße 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 hilfreich, wenn ein Design mehrere Bildformate nutzt (z.B. Produktkarten und große Hero-Platzierungen) und du vermeiden möchtest, mehrere Bild-Attribute zu synchronisieren.

Währungsumrechnung #

Shopifys eingebaute Currency Conversion macht es einfach, das Währungssymbol und den Wechselkurs aus dem Webshop auszulesen.

Standardmäßig kommt Clerk.js für Shopify mit einem formatter, der funktioniert, solange deine Drittanbieter-App Shopifys integriertes Währungsobjekt nutzt.

Standardlösung #

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

Dieses Beispiel nutzt unsere Standard-Templatesprache 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 funktionieren.

Design Editor #

1. Erstelle eine Text-Komponente an der Stelle, wo der Preis angezeigt werden soll.
2. Füge folgenden Liquid-Code ein, um den Preis basierend auf dem Währungs-Converter im Textfeld anzuzeigen:

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

Code-Modus #

1. Gehe in my.clerk.io zu Search/Recommendations > Designs und klicke auf Edit Design für dein Design.
2. Ersetze den vorhandenen money- oder money_eu-Formatter für Preise durch currency_converter.
3. Klicke auf Update Design.
4. Nun werden die umgerechneten Preise und das Währungssymbol in deinem Design angezeigt.

Eigene API-Lösung #

Hinweis: Dies ist eine sehr individuelle Lösung zur Preisumrechnung, falls keine Daten von der Shopify API vorhanden sind. Nur verwenden, wenn eine spezifische und eigene Einrichtung für Preisumrechnungen basierend auf Geo-IP-Änderungen genutzt wird.

Dies ist die Dokumentation der Frontend-Lösung in Github.

Dieser Abschnitt behandelt, wie man im Clerk.io API-Response kontextbasierte Daten in Echtzeit abrufen kann.

Das Designpattern besteht aus folgenden Teilen:

• Einer Kollektion, die alle Produkte enthält.
• Einem alternativen Layout zur Ausgabe der Kollektion als JSON.
• Einer JavaScript-Klasse, die die in der Kollektion verfügbaren Daten sammelt.
• Einem JavaScript-Snippet, das die Daten für die jeweiligen Produkt-IDs konsumiert und sie in einem div im Template platziert.

Kollektion erstellen #

Damit du eine Kollektion mit allen möglichen Produkten hast, erstelle eine Kollektion mit einer Bedingung, die von allen Produkten erfüllt wird.

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

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

Alternatives Layout erstellen #

Erstelle ein alternatives Layout, um deine Daten über die Kollektion anzuzeigen.

Bearbeite dazu zunächst den Theme-Code des Themes, das du nutzen möchtest.

Klicke links im Bereich “Vorlagen” auf Add new Template.

Wähle in der Pop-up-Auswahl collection für den Ressourcentyp.

Wähle liquid als Dateityp.

Schreibe unten json, sodass der erstellte Template-Name collection.json.liquid lautet.

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

Du kannst dem Produkt in diesem Template weitere Felder hinzufügen, wenn erforderlich.

JS-Klasse hinzufügen #

Um die Daten aus deiner Kollektion zu holen und verfügbar zu machen, platziere den gesamten Inhalt von index.js im class-Ordner dieses Projekts innerhalb des Skript-Tags mit Clerk.js, den du in theme.liquid eingefügt hast.

Das sieht etwa so aus:

<script>
  // Clerk.js Injection Code
  // Clerk Config mit Key und Formattern
  // 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 aufgrund von Zeitstempeln und Währungen ungültig, ohne dass Änderungen am Code nötig sind.

Der Zeitraum bis zur Ungültigkeit beträgt 12 Stunden seit dem letzten Aufbau der Daten.

Auch ein Wechsel des Währungskontexts macht die Daten ungültig.

Template-Funktion hinzufügen #

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

Die Funktion holt sich verfügbare Daten und platziert sie in bestimmten Child-Elementen der jeweiligen Produktkachel.

Das Beispiel schließt die Felder list_price und price ein.

Zu beachten: Falls du Felder nutzen möchtest, die sich von price und list_price unterscheiden, füge sie in collection.json.liquid hinzu und passe dann template.html sowie auch template.js an. Du solltest die in Schritt 3 beschriebene Klasse nicht bearbeiten müssen.

Theme-Dateien finden #

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

Jedes Theme funktioniert gleich – du passt die Theme-Dateien an deine Wünsche an.

Die Dateinamen können sich jedoch von Theme zu Theme unterscheiden.

Shopify stellt ein Suchfeld zur Verfügung, mit dem du schnell die gewünschte Theme-Datei findest.

Falls du den Namen der Datei nicht kennst, hilft dir das Suchfeld beim Auffinden.

Beispiel: Suchst du nach der Datei für die Suchseite, wird sie wahrscheinlich ‘search’ im Namen enthalten.

Falls du unsicher bist, ob du die richtige Datei gefunden hast, vergleiche das HTML der Theme-Datei mit dem HTML der jeweiligen Seite, um Übereinstimmungen zu prüfen.

Das geht in Google Chrome mit Rechtsklick auf einen Seitenbereich und Auswahl von ‘Element untersuchen’.

Nun kannst du das HTML auf der Seite untersuchen und prüfen, ob Klasse/ID der Elemente identisch mit denen in der Datei sind.

Falls du dabei Unterstützung benötigst, wende dich gerne an unser Support-Team.

Empfehlungen im Warenkorb-Drawer #

Installation durch einen Shopify-Entwickler wird dringend empfohlen.

Diese Anleitung beschreibt eine stark angepasste Lösung, die sich je nach Shopify-Theme unterscheiden kann. Sie ist speziell für Themes, bei denen der Warenkorb auf jeder Seite im DOM liegt, aber erst beim Öffnen sichtbar wird.

Das Anzeigen von Clerk.io Recommendations im Warenkorb-Drawer auf Shopify ist eine großartige Möglichkeit, Käufern vor dem Checkout weitere Produkte vorzuschlagen.

1. Bearbeite den Code deines Shopify-Themes in Online Store > Themes > Edit code.
2. Finde die Datei, in der sich das Template für den Warenkorb-Drawer befindet (meist cart-drawer.liquid oder ähnlich).
3. Füge einen Clerk.io Recommendations-Snippet aus Recommendations > Elements ein.
4. Benenne die Klasse von clerk um, um das Rendering zu steuern control the rendering. Zum Beispiel indem du sie clerk_m nennst:

<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. Ergänzend zum obigen Snippet binde ein Skript ein, das Clerk.io Recommendations rendert, wenn der Nutzer den Warenkorb öffnet. Ein Ansatz nutzt einen MutationObserver. Das folgende Skript enthält diese Elemente und gibt ein Beispiel für die Herangehensweise:

<script>
    // Node auswählen, der auf Mutationen beobachtet werden soll
    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 (welche Mutationen beobachtet 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, die bei beobachteten Mutationen ausgeführt wird
    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 erstellen, die mit der Callback-Funktion verbunden ist
    const clerk_observer = new MutationObserver(callback);

    // Beobachtung des Ziel-Nodes für konfigurierte Mutationen starten
    clerk_observer.observe(targetNode, config);
</script>

Deine Warenkorb-Drawer-Datei sollte so aussehen:

HTTP-Authentifizierung #

HTTP-Authentifizierung wird häufig auf Staging-Seiten verwendet, um unerwünschte Besucher zu vermeiden.

Dies blockiert jedoch den Clerk.io Importer und zeigt eine 401 Unauthorized-Fehlermeldung im Sync-Log an.

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 Sync-Fehler #

Beim Import von Daten mit der Shopify-Integration ist der Server deines Webshops für die Übertragung von Produkt-, Kategorie- und Verkaufsdaten an Clerk.io verantwortlich.

Manchmal verhindert jedoch die Server-Konfiguration, dass der Importer Zugriff erhält, was einen Fehler in Data Sync verursacht.

Hier sind die häufigsten Fehler sowie deren Behebung:

401 Unauthorized #

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

Das Problem wird gelöst, indem du Username und Password als Teil der Import-URL einfügst:

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

Berechtigungsfehler #

Dieser Fehler tritt meist auf, wenn du keinen Lesezugriff auf Store content like articles, blogs, comments, pages and redirects in deiner privaten App gewährt hast.

So behebst du das:

1. Logge dich in Shopify ein und gehe zu Apps > Manage Private Apps > Clerk.io (oder dem Namen der App).
2. Scrolle zu Admin API Permissions und klicke auf Review disabled Admin API permissions.
3. Suche Store content like articles, blogs, comments, pages and redirects und wähle Read access:

1. Scrolle zum Seitenanfang und klicke auf Save.

Umgang mit require.js #

Diese Anleitung gilt nur bei Verwendung von Clerk.js 1.

In manchen Setups verhindert Require.js, dass Clerk.js geladen wird – dadurch erscheinen keine Slider oder Suchergebnisse.

Dann erscheint im Konsolen-Log folgender Fehler:

Uncaught ReferenceError: Clerk is not defined

Es gibt zwei Wege, mit Require.js umzugehen. Beide erfordern Änderungen am Tracking-Skript, das normalerweise in index.liquid eingefügt ist.

In Require.js einbinden #

Der beste Ansatz ist, Require.js dazu zu bringen, Clerk.io zu erkennen.

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

Require.js ignorieren #

Falls die obige Lösung nicht funktioniert, kannst du Require.js ignorieren.

Füge hierzu window.__clerk_ignore_requirejs = true; zu Beginn des Tracking-Skripts ein:

Nach einer dieser Vorgehensweisen ist Require.js jetzt mit Clerk.io kompatibel.

Upgrade auf Clerk.js 2 #

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

Das Installieren von Clerk.io auf jedem Webshop wird dadurch einfacher.

Da sich die beiden Versionen etwas unterscheiden, befolge bitte diese Schritte für ein erfolgreiches Upgrade.

Die wichtigsten Unterschiede in Clerk.js 2 sind:

• Die Designs in my.clerk.io nutzen die Liquid Templatesprache, können aber auch direkt mit dem 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.

Es gibt zwei Wege, deine Clerk.js 2 Designs zu erstellen:

• Verwende den intuitiven Design Editor zum Erstellen neuer Designs, wie im Folgenden beschrieben.
• Wandle alte Designs um. Folge dieser Anleitung für die Umwandlung.

Design-Editor-Option #

1. Gehe zu my.clerk.io > Recommendations/Search > Designs > New Design.
2. Gib deinem Design im folgenden Screen einen Namen (wir empfehlen, “V2” anzuhängen, damit klar ist, dass Clerk.js 2 genutzt wird).
3. Wähle den Design-Typ.
4. Klicke auf Publish Design, wenn du fertig bist, und gehe zu Schritt 2 der Anleitung.
5. Klicke im Design Editor eines der bestehenden Elemente wie Namen, Bild, Button usw. an, um es zu bearbeiten, oder füge weitere Elemente hinzu, um mehr Produktinformationen anzuzeigen.
6. Klicke auf Publish. Dadurch werden sie vorübergehend nicht in deinem Shop angezeigt, bis du Schritt 2 abgeschlossen hast. Wähle das neue Design für alle zu aktualisierenden Elemente.
7. Gehe zu Recommendations/Search > Elements und stelle dein Clerk.io Element auf das neue Design um.

Jetzt kannst du auf Clerk.js 2 umstellen.

Skript ersetzen #

1. Finde die Template-Datei, die für die Anzeige aller Shop-Seiten verwendet wird, und in der das ursprüngliche Clerk.js Script am Ende steht.
2. Entferne das alte Script aus der Datei:

1. Gehe zu my.clerk.io > Developers > Tracking Code. Hier findest du deinen Clerk.js 2 Tracking-Code.
2. Kopiere diesen Code und füge ihn direkt vor dem </head>-Tag in das Template ein:

1. Speichere dein Template.

Herzlichen Glückwunsch! Dein Shop nutzt nun die verbesserte Clerk.js 2-Integration!

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

Zugriff auf Customer Events #

Wenn wir bei der Einrichtung oder Fehlersuche bei der Bestellverfolgung via Shopify-Pixel helfen, bitten wir ggf. um Zugriff auf den Bereich Customer events im Shopify-Admin.

So vergibst du die nötigen Berechtigungen:

1. Gehe in Shopify zu Settings > Users and permissions.
2. Klicke auf den Mitarbeiter Clerk.io (oder den Benutzer, den du bearbeiten willst).
3. Scrolle zu Store settings und aktiviere:

• View customer events
• Manage and add custom pixels

4. Klicke auf Save.

Diese Berechtigungen ermöglichen es unserem Team, den Bereich Customer events einzusehen und das Clerk.io-Pixel zu verwalten, damit wir prüfen können, ob die Bestellverfolgung korrekt funktioniert.