FAQ

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

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

Dieses Beispiel nutzt 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 einzelnen Komponenten funktionieren.

Design Editor #

1. Erstellen Sie eine Text-Komponente an der Stelle, an der der Preis angezeigt werden soll.

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

{{ 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 money- oder money_eu-Formatter für Preise durch currency_converter.

3. Klicken Sie auf Update Design.

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

Individuelle API-Lösung #

Haftungsausschluss: Dies ist eine sehr individuelle Lösung, um Preisumrechnungen zu ermöglichen, wenn keine Daten von der Shopify API verfügbar sind. Verwenden Sie dies nur, wenn Sie ein spezifisches und angepasstes Setup für Preisumrechnungen basierend auf Geo-IP-Änderungen nutzen.

Hier finden Sie die Dokumentation zur Frontendlösung in Github.

In diesem Abschnitt wird erläutert, wie Sie kontextbezogene Daten in Echtzeit abrufen und im von der Clerk API zurückgegebenen Inhalt anzeigen.

Das Designmuster besteht aus folgenden Teilen:

• Eine Kollektion, die alle Produkte enthält.

• Ein alternatives Layout zum Rendern der Kollektion als JSON.

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

• Ein JavaScript-Snippet, das die Daten für relevante Produkt-IDs in einem Ergebnis verarbeitet und innerhalb eines Divs in der Vorlage platziert.

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, da sie so die Route /collection/clerk-api im Frontend erhält.

Die Bedingung für die Kollektion könnte z.B. price > -1000000 lauten.

Alternatives Layout erstellen #

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

Bearbeiten Sie dazu 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 im untersten Feld json ein, sodass der Name der erstellten Vorlage collection.json.liquid ist.

Der Inhalt dieser Datei sollte der collection.json.liquid-Datei entsprechen, die Sie im „liquid“-Ordner dieses Projektes finden.

Sie können bei Bedarf im Template weitere Felder zum Produkt hinzufügen.

JS-Klasse hinzufügen #

Um die Daten aus Ihrer Kollektion abzurufen und vorzubereiten, fügen Sie den gesamten Inhalt von index.js aus dem class-Ordner dieses Projekts innerhalb des Script-Tags mit Clerk.js, das Sie in theme.liquid platziert haben, ein.

Das sollte wie folgt aussehen:

<script>
  // Clerk.js Injection Code
  // Clerk Config with Key and Formatters
  // Klasse aus diesem Projekt
  clerk_shopify_api.init()
  // Am Ende init() für die Klasse, damit es beim Laden der Seite läuft.
</script>

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

Der Zeitraum bis zur Invalidierung beträgt 12 Stunden nach der letzten Datenerstellung.

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

Vorlagenfunktion hinzufügen #

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

Die Funktion liest die Daten ein, sobald sie verfügbar sind, und platziert sie innerhalb bestimmter Kind-Elemente in jedem Produkt-Block.

Im Beispiel sind die Felder list_price und price enthalten.

Wichtig: Wenn Sie andere Felder als price und list_price nutzen möchten, fügen Sie diese in collection.json.liquid hinzu und passen danach template.html und template.js an, um diese Felder zu verwenden. Die Klasse aus Schritt 3 müssen Sie nie anpassen.

Mehrere Währungen #

Hinweis: Dies ist veraltet. Das Pixel-Tracking-Skript ersetzt das. Befolgen Sie Schritt 4 und 5 aus dem Shopify-Startleitfaden.

Bei der Verwendung mehrerer Währungen in Ihrem Shopify-Webshop ist es wichtig, dass Bestellungen in einer Währung zusammengeführt werden, damit Ihre umsatzbezogene Performance in Clerk korrekt ist.

Im Clerk-Dashboard wird die Performance immer in genau einer Währung gemeldet.

Wenn Sie beispielsweise GBP und DKK im Webshop nutzen, wird Ihre Performance ausschließlich in GBP oder ausschließlich in DKK gemeldet.

Deshalb ist die Umrechnung auf eine Währung wichtig—schließlich möchten Sie nicht, dass ein Einkauf über 600 GBP von Clerk als 600 DKK erfasst wird!

Damit Ihre Clerk-Dashboards Ihre Verkaufsdaten in einer einheitlichen Währung anzeigen, können Sie dies im Sales Tracking-Code anpassen, den Sie beim Clerk-Setup eingebunden haben.

Wechseln Sie dazu im Shopify-Backend zu Settings > Checkout > Additional Scripts, und ändern Sie den Sales Tracking Code von diesem:

<!-- Start of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
<script>
  (function (w, d) {
      var e = d.createElement('script'); e.type = 'text/javascript'; e.async = true;
      e.src = 'https://cdn.clerk.io/clerk.js';
      var s = d.getElementsByTagName('script')[0]; s.parentNode.insertBefore(e, s);
      w.__clerk_q = w.__clerk_q || []; w.Clerk = w.Clerk || function () { w.__clerk_q.push(arguments) };
  })(window, document);
  Clerk('config', {
      key: 'yourPublicKey'
  });
  let clerk_order_id = parseInt("'{'+'{ checkout.order.id }'+'}'");
  document.addEventListener('DOMContentLoaded', (e)=> {
      clerk_order_id = window.Shopify.checkout.order_id
  });
  if ( isNaN( clerk_order_id ) ) {
      if(window.Shopify){
          clerk_order_id = window.Shopify.checkout.order_id
      }
  }
  let log_sale_retry = setInterval(() => {
      if( ! isNaN( clerk_order_id ) ){
          Clerk('call', 'log/sale/shopify', {
              sale: clerk_order_id
          });
          clearInterval(log_sale_retry);
      }
  }, 100);
  </script>
  <!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

zu folgendem:

<!-- Start of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
<script>
    (function (w, d) {
        var e = d.createElement('script'); e.type = 'text/javascript'; e.async = true;
        e.src = 'https://cdn.clerk.io/clerk.js';
        var s = d.getElementsByTagName('script')[0]; s.parentNode.insertBefore(e, s);
        w.__clerk_q = w.__clerk_q || []; w.Clerk = w.Clerk || function () { w.__clerk_q.push(arguments) };
    })(window, document);
    let clerkLocale = Shopify.locale;
    let publicKey;
    switch (clerkLocale) {
        case 'en':
            publicKey = 'yourPublicKeyEN';
            break;
        case 'fr':
            publicKey = 'yourPublicKeyFR';
            break;
        case 'de':
            publicKey = 'yourPublicKeyDE';
            break;
        // Add more cases as needed
    }
    Clerk('config', {
        key: publicKey
    });
    let clerk_order_id = parseInt("'{'+'{ checkout.order.id }'+'}'");
    document.addEventListener('DOMContentLoaded', (e) => {
        clerk_order_id = window.Shopify.checkout.order_id
    });
    if (isNaN(clerk_order_id)) {
        if (window.Shopify) {
            clerk_order_id = window.Shopify.checkout.order_id
        }
    }
    let log_sale_retry = setInterval(() => {
        if (!isNaN(clerk_order_id)) {
            Clerk('call', 'log/sale/shopify', {
                sale: clerk_order_id
            });
            clearInterval(log_sale_retry);
        }
    }, 100);
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

Beachten Sie: Lassen Sie das Visitor Tracking Script unverändert—dieses finden Sie direkt unter dem Sales Tracking Code.

Ihre Bestellungen erscheinen jetzt in den Clerk-Dashboards zusammengefasst in einer Währung.

Theme-Dateien finden #

Shopify bietet mehr als 100 verschiedene Themes, um Ihr Webshop-Design zu gestalten und anzupassen.

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

Allerdings unterscheiden sich die Dateinamen der Themes von Theme zu Theme.

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

Falls Sie den Namen der Datei nicht kennen, können Sie das Suchfeld verwenden, um sie zu finden.

Wenn Sie zum Beispiel den Code für die Suchseite suchen, wird die entsprechende Datei vermutlich „search“ im Dateinamen enthalten.

Wenn Sie unsicher sind, ob Sie die richtige Datei gefunden haben, können Sie den HTML-Code der Theme-Datei mit dem Code der Seite vergleichen.

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

Sie können dann das HTML auf der Seite inspizieren und prüfen, ob die Klassen/IDs der Elemente im Datei-HTML mit denen auf der Seite übereinstimmen.

Falls Sie dabei Hilfe benötigen, können Sie sich auch an unser Support-Team wenden.

Empfehlungen im Warenkorb #

Die Installation durch einen Shopify-Entwickler wird dringend empfohlen.

Diese Anleitung beschreibt eine stark angepasste Lösung, die sich je nach Theme unterschiedlich verhalten kann. Sie ist gezielt für Themes konzipiert, bei denen der Warenkorb auf jeder Seite Bestandteil des DOMs ist, aber standardmäßig verborgen bleibt.

Die Anzeige von Clerk Recommendations im Warenkorb-Drawer in Shopify ist eine großartige Möglichkeit, Shop-Besuchern vor dem Bezahlvorgang weitere Produkte zu zeigen.

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

2. Finden Sie die Template-Datei für den Warenkorb-Drawer (normalerweise cart-drawer.liquid oder ähnlich).

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

4. Ändern Sie die Klasse von clerk zur Steuerung des Renderings. Zum Beispiel indem Sie sie in clerk_m umbenennen:

<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 zusätzlich das folgende Skript ein, um Clerk Recommendations beim Öffnen des Warenkorbs zu rendern. Eine Möglichkeit ist die Nutzung eines MutationObservers. Das folgende Skript bündelt alle erforderlichen Elemente und veranschaulicht die Vorgehensweise:

<script>
    // Das zu beobachtende Node-Element auswählen
    const targetNode = document.querySelector("cart-drawer.drawer");

    // Alle Klassennamen des geöffneten Warenkorb-Drawers angeben
    const targetNodeClasses = "drawer animate active";

    // Optionen für den Observer (zu beobachtende Veränderungen)
    const config = { attributes: true };

    let cartFetched = false;
    let previousitemsID = [];
    
    // Funktion zum Abrufen der Warenkorbdaten
    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 beobachtete 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;
                    }
                }

            }
        }
    };

    // Beobachter-Instanz mit der Callback-Funktion erstellen
    const clerk_observer = new MutationObserver(callback);

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

Ihre Warenkorb-Drawer-Datei sollte nun so aussehen:

HTTP-Authentifizierung #

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

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

Sie können das Problem beheben, indem Sie die Anmeldedaten in die Import-URL einfügen.

Gehen Sie in my.clerk.io > Data > Configuration und aktualisieren die Import-URL wie folgt:

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

Häufige Synchronisierungsfehler #

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

Manchmal kann die Serverkonfiguration jedoch den Zugriff für den Importer stoppen, was zu einem Fehler in Data Sync führt.

Hier sind die häufigsten Fehler und deren Behebung:

401 Unauthorized #

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

Die Lösung ist, den Benutzernamen und das Passwort als Teil der Import-URL einzufügen:

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

Berechtigungsfehler #

Dieser Fehler tritt meistens auf, wenn Sie Lesezugriff auf Store content like articles, blogs, comments, pages and redirects in Ihrer Private App nicht vergeben haben.

So beheben Sie den Fehler:

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

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

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

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

Umgang mit require.js #

Diese Anleitung gilt nur, wenn Sie Clerk.js 1 verwenden.

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

Dabei erscheint folgender Fehler in Ihrer Konsole:

Uncaught ReferenceError: Clerk is not defined

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

In Require.js einbinden #

Die beste Vorgehensweise ist, Require.js so einzubinden, dass Clerk erkannt wird.

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

Require.js ignorieren #

Falls die oben genannte Lösung nicht funktioniert, können Sie Require.js ignorieren.

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

Nachdem Sie eine der beiden Ansätze verwendet haben, ist Require.js nun mit Clerk kompatibel.

Upgrade auf Clerk.js 2 #

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

Die Installation von Clerk in jedem Webshop ist dadurch noch einfacher.

Da die beiden Versionen jedoch geringfügig unterschiedlich funktionieren, müssen Sie die folgenden Schritte befolgen, um erfolgreich upzugraden.

Die beiden Hauptunterschiede bei 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 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 verwendet, müssen Sie neue Designs erstellen.

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

• Verwenden Sie unseren intuitiven Design Editor (wie unten beschrieben).

• Konvertieren Sie Ihre alten Designs. Folgen Sie dieser Anleitung, um zu erfahren, wie das geht.

Option Design Editor #

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

2. Geben Sie im nächsten Bildschirm Ihrem Design einen Namen (wir empfehlen, „V2“ hinzuzufügen, damit klar ist, dass Sie Clerk.js 2 verwenden).

3. Wählen Sie den Design-Typ.

4. Klicken Sie auf Publish Design, wenn Sie fertig sind, und fahren Sie mit Schritt 2 der Anleitung fort.

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

6. Klicken Sie auf Publish. Dadurch werden die Designs vorübergehend nicht in Ihrem Webshop angezeigt, bis Sie mit Schritt 2 fertig sind. Wählen Sie das neue Design für alle Elemente, die aktualisiert werden sollen.

7. Gehen Sie zu Recommendations/Search > Elements und wählen Sie für Ihr Clerk Element Ihr neues Design aus.

Jetzt können Sie auf Clerk.js 2 umstellen.

Script ersetzen #

1. Suchen Sie die Template-Datei, in der alle Seiten des Webshops angezeigt werden und in der das originale Clerk.js-Skript meist am Seitenende zu finden ist.

2. Entfernen Sie das alte Skript aus der Datei:

3. Gehen Sie zu my.clerk.io > Developers > Tracking Code.. Auf dieser Seite finden Sie jetzt Ihren Clerk.js 2-Tracking-Code.

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

5. Speichern Sie Ihr Template.

Glückwunsch! Sie verwenden nun das optimierte Clerk.js 2-Setup!

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

Clerk Zugriff auf Customer Events gewähren #

Wenn wir Sie beim Einrichten oder beim Troubleshooting von Order-Tracking via Shopify-Pixels unterstützen, bitten wir ggf. um Zugriff auf den Bereich „Customer events“ im Shopify-Admin.

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

1. In Shopify: Navigieren Sie zu Settings > Users and permissions.
2. Klicken Sie auf den Mitarbeiter Clerk.io (oder den gewünschten Mitarbeiter-Account).
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, um die korrekte Funktion des Order-Trackings zu überprüfen.