FAQ

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

Währungsumrechnung #

Die integrierte Währungsumrechnung von Shopify erleichtert das Auslesen des Währungssymbols und Wechselkurses aus dem Webshop.

Standardmäßig wird Clerk.js für Shopify mit einem formatter ausgeliefert, der funktioniert, solange deine Drittanbieter-App das integrierte Währungsobjekt von Shopify verwendet.

Standardlösung #

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

Dieses Beispiel nutzt unsere Standard-Template-Sprache hier.

Bei der Nutzung von Währungsumrechnung 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 die Preise angezeigt werden sollen.

2. Füge folgenden Liquid-Code ein, um basierend auf dem Währungsumrechner den Preis in die Textkomponente einzufügen:

{{ 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. Jetzt solltest du die umgerechneten Preise und das Währungssymbol in deinem Design sehen:

Individuelle API-Lösung #

Hinweis: Dies ist eine sehr individuelle Lösung, um Preisumrechnungen zu erhalten, wenn keine Daten von der Shopify API verfügbar sind. Verwende diese nur, wenn du eine spezielle, benutzerdefinierte Lösung für Preisumrechnungen basierend auf geo-IP-Änderungen nutzt.

Dies ist die Frontend-Lösungsdokumentation auf Github.

In diesem Abschnitt wird behandelt, wie du Kontextdaten in Echtzeit für die Anzeige in Inhalten erhalten kannst, die von der Clerk API zurückgegeben werden.

Das Design-Pattern besteht aus folgenden Teilen:

• Eine Kollektion, die alle Produkte enthält.

• Ein alternatives Layout, das Kollektioninformationen als JSON rendert.

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

• Ein JavaScript-Snippet, das die relevanten Produkt-IDs aus einem gegebenen Suchergebnis nutzt und in einem Div im Template platziert.

Kollektion erstellen #

Um sicherzustellen, dass 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 die Route /collection/clerk-api im Frontend erhält.

Die Bedingung für die Kollektion sollte etwa so lauten: price > -1000000.

Alternatives Layout erstellen #

Erstelle ein alternatives Layout zur Anzeige deiner Daten mit Hilfe der Kollektion.

Dazu bearbeite zuerst den Theme-Code des gewünschten Themes.

Gehe im linken Bereich unter “Templates” auf Add new Template.

Wähle im Pop-up als Ressourcen-Typ collection aus.

Wähle als Dateityp liquid aus.

Trage unten json ein, sodass die erstellte Datei collection.json.liquid heißt.

Der Inhalt dieser Datei sollte jene collection.json.liquid aus dem liquid-Ordner dieses Projekts sein.

Du kannst im Template nach Bedarf weitere Felder zum Produkt hinzufügen.

JS-Klasse hinzufügen #

Um die Daten aus deiner Kollektion zu entnehmen und aufzubereiten, platziere den gesamten Inhalt von index.js aus dem Ordner class dieses Projekts im Script-Tag mit Clerk.js, das du bereits in theme.liquid eingefügt hast.

Das sollte so aussehen:

<script>
  // Clerk.js Injection Code
  // Clerk Config with Key and Formatters
  // Class from this project
  clerk_shopify_api.init()
  // Finally init() for the class to make sure it runs when the page loads.
</script>

Diese Klasse macht Daten basierend auf Zeitstempeln und Währungen ungültig, ohne dass du den Code ändern musst.

Der Zeitraum bis zur Ungültigmachung beträgt 12 Stunden seit dem letzten Datenaufbau.

Jede Änderung im Währungskontext setzt die Daten ebenfalls zurück.

Template-Funktion hinzufügen #

Binde template.js im verwendeten Design-Template ein.

Die Funktion liest die Daten bei Verfügbarkeit aus und platziert sie in spezifischen Kindelementen jeder Produktkachel.

Das Beispiel umfasst die Felder list_price und price.

Hinweis: Falls du andere Felder als price und list_price benötigst, füge diese in collection.json.liquid hinzu und passe dann zusätzlich template.html und template.js an, damit sie die Felder verwenden. Die im Schritt 3 beschriebene Klasse brauchst du nie zu bearbeiten.

Mehrere Währungen #

Hinweis: Dies ist veraltet. Das Pixel-Tracking-Skript ersetzt dies. Folge den Schritten 4 und 5 aus dem Shopify-Startleitfaden.

Wenn du mehrere Währungen im Shopify-Webshop nutzt, ist es wichtig, dass Bestellungen in eine Währung umgerechnet werden, damit die umsatzbezogene Performance in Clerk korrekt ist.

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

Verwendest du zum Beispiel sowohl GBP als auch DKK im Shop, werden die Dashboards die Performance entweder nur in GBP oder nur in DKK anzeigen.

Darum ist es wichtig, auf eine Währung umzurechnen – schließlich möchtest du ja nicht, dass ein Einkauf über 600 GBP von Clerk als 600 DKK verstanden wird!

Damit deine Clerk-Dashboards deine Verkaufsdaten in einer gemeinsamen Währung anzeigen, kannst du dies im Sales-Tracking-Code einstellen, den du bei der ursprünglichen Installation in deinen Shop eingefügt hast.

Gehe zu Settings > Checkout > Additional Scripts im Shopify-Backend und ändere 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 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);
    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 -->

Stelle sicher, dass das Visitor Tracking Script unverändert bleibt – dies befindet sich direkt unter dem Sales Tracking Code.

Deine Bestellungen sollten nun als eine Währung ins Clerk-Dashboard übermittelt werden.

Theme-Dateien finden #

Shopify bietet mehr als 100 verschiedene Themes zur Gestaltung und Anpassung deines Webshops.

Jedes Theme funktioniert gleich – du passt die Theme-Dateien an, um ein gewünschtes Ergebnis im Shop zu erzielen.

Allerdings ändern sich die Dateinamen von Theme zu Theme.

Shopify stellt dir ein Suchfeld zur Verfügung, mit dem du die gesuchte Theme-Datei schnell und einfach findest.

Falls du den Namen der gesuchten Datei nicht kennst, kannst du das Suchfeld zur Lokalisierung verwenden.

Zum Beispiel: Suchst du die Datei mit dem Code für die Suchseite, wird der Dateiname vermutlich ‘search’ enthalten.

Falls du dir nicht sicher bist, ob du die richtige Datei gefunden hast, kannst du den HTML-Code in der Theme-Datei mit dem HTML der jeweiligen Seite vergleichen.

Das geht in Google Chrome, indem du mit der rechten Maustaste auf einen Bereich der Seite klickst und ‘Inspect’ auswählst.

Du kannst dann das HTML der Seite überprüfen und kontrollieren, ob Klassen/IDs der Elemente in der Datei mit denen auf der Seite übereinstimmen.

Wenn du weitere Unterstützung benötigst, kannst du dich auch an unser Support-Team wenden.

Empfehlungen im Cart-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 gedacht, bei denen der Warenkorb ein Teil des DOM auf jeder Seite ist, aber erst sichtbar wird, wenn der Nutzer ihn öffnet.

Die Anzeige von Clerk Recommendations im Cart-Drawer auf Shopify ist eine tolle Möglichkeit, Käufer:innen weitere Produkte vor dem Checkout anzuzeigen.

1. Bearbeite den Code deines Shopify-Themes in Online Store > Themes > Edit code.

2. Suche die Datei, in der sich das Cart-Drawer-Template befindet (normalerweise cart-drawer.liquid oder ähnlich).

3. Füge ein Clerk Recommendations Snippet aus Recommendations > Content ein.

4. Benenne die Klasse von clerk um, um das Rendering zu steuern wie hier beschrieben. Zum Beispiel, indem du sie clerk_m nennst:

<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. Ergänze das oben eingefügte Snippet um ein Script zur Darstellung der Clerk Recommendations beim Öffnen des Warenkorbs. Ein Ansatz ist die Verwendung eines MutationObserver. Das folgende Script enthält alle nötigen Elemente und dient dir als Beispiel:

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

Deine Cart-Drawer-Datei sollte dann so aussehen:

HTTP-Authentifizierung #

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

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

Das kannst du beheben, indem du die Anmeldedaten 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 Datenimport über die Shopify-Integration ist der Server deines Webshops dafür verantwortlich, Produkt-, Kategorie- und Verkaufsdaten an Clerk zu senden.

Falls die Serverkonfiguration dies verhindert, kann der Importer nicht zugreifen und es tritt ein Fehler beim Data Sync auf.

Hier sind die häufigsten Fehler und ihre Lösungen:

401 Unauthorized #

Dieser Fehler tritt auf, wenn dein Webshop oder deine Entwicklungsumgebung eine HTTP-Authentifizierung erfordert.

Die Lösung ist das Einfügen von Benutzername und Passwort als Teil der Import-URL:

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

Berechtigungsfehler #

Dieser Fehler tritt oft auf, wenn du keinen Lesezugriff auf Shop-Inhalte wie Artikel, Blogs, Kommentare, Seiten und Weiterleitungen in deiner Private App gewährt hast.

So behebst du das:

1. Melde dich bei Shopify an und gehe zu Apps > Manage Private Apps > Clerk.io (oder zum von dir vergebenen App-Namen).

2. Scrolle zu Admin API Permissions und klicke auf Review disabled Admin API permissions.

3. Suche Shop-Inhalte wie Artikel, Blogs, Kommentare, Seiten und Weiterleitungen und wähle Read access:

4. Scrolle ganz nach oben und klicke Save.

Umgang mit require.js #

Dieser Hinweis gilt nur für Clerk.js 1.

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

Dann erscheint folgender Fehler in der Konsole:

Uncaught ReferenceError: Clerk is not defined

Es gibt zwei Möglichkeiten, mit Require.js umzugehen. Beide Ansätze erfordern Anpassungen am tracking-script, das normalerweise in index.liquid eingefügt ist.

In Require.js einbinden #

Der beste Ansatz ist es, Require.js so einzubinden, dass Clerk erkannt wird.

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 dazu window.__clerk_ignore_requirejs = true; am Anfang des Tracking-Skripts ein:

Danach ist Require.js mit Clerk kompatibel.

Upgrade auf Clerk.js 2 #

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

Damit kannst du Clerk auf jedem Webshop leichter installieren.

Da sich die beiden Versionen jedoch etwas unterscheiden, musst du diese Schritte befolgen, um ein Upgrade erfolgreich durchzuführen.

Die zwei Hauptunterschiede von Clerk.js 2:

• Die Designs in my.clerk.io nutzen die Liquid Template-Sprache, können aber auch mit dem Design-Editor einfach erstellt werden.

• Das Skript muss direkt vor dem </head>-Tag im Shop-Template eingefügt werden.

Designs erstellen #

Da Clerk.js 2 einen anderen Ansatz für Designs verwendet, musst du neue Designs erstellen.

Du kannst deine Clerk.js 2-Designs folgendermaßen erstellen:

• Mit dem intuitiven Design Editor, wie in den folgenden Schritten beschrieben.

• Deine alten Designs konvertieren. Hier findest du eine Anleitung dazu.

Option Design Editor #

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

2. Gib deinem Design auf dem nächsten Bildschirm einen Name (wir empfehlen, “V2” hinzuzufügen, um kenntlich zu machen, dass du Clerk.js 2 verwendest).

3. Wähle den Design-Typ aus.

4. Klicke auf Publish Design, wenn du fertig bist, und gehe zu Schritt 2 der Anleitung.

5. Klicke im Design Editor auf ein vorhandenes Element wie Name, Bild, Button etc., um es zu bearbeiten, oder füge neue Elemente hinzu, um weitere Produktinformationen zum Design hinzuzufügen.

6. Klicke auf Publish. Daraufhin erscheinen sie vorübergehend nicht mehr im Webshop, bis du mit Schritt 2 fertig bist. Wähle das neue Design für alle Inhalte, die aktualisiert werden sollen.

7. Gehe zu Recommendations/Search > Content und ändere deine Clerk-Inhalte so, dass sie dein neues Design verwenden.

Jetzt bist du bereit, auf Clerk.js 2 umzustellen.

Skript ersetzen #

1. Suche die Template-Datei, die auf allen Seiten des Webshops dargestellt wird und wo das bisherige Clerk.js-Skript am Ende zu finden ist.

2. Entferne das alte Skript aus der Datei:

3. Gehe zu my.clerk.io > Developers > Tracking Code.. Diese Seite enthält jetzt deinen Clerk.js 2-Tracking-Code.

4. Kopiere den Code und füge ihn direkt vor dem </head>-Tag im Template ein:

5. Speichere dein Template.

Glückwunsch! Du nutzt jetzt die deutlich verbesserte Clerk.js 2-Integration!

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

Clerk Zugriff auf “Customer Events” gewähren #

Wenn wir dir beim Einrichten oder bei der Fehlersuche des Order-Trackings via Shopify-Pixel helfen, bitten wir dich evtl. um Zugriff auf den Bereich “Customer events” in deinem Shopify-Admin.

Folge diesen Schritten, um die nötigen Rechte zu vergeben:

1. Gehe in Shopify zu Settings > Users and permissions.
2. Klicke auf das Teammitglied Clerk.io (oder den gewünschten Benutzer).
3. Scrolle zu Store settings und aktiviere:
   • View customer events
   • Manage and add custom pixels
4. Klicke auf Save.

Diese Berechtigungen erlauben es unserem Team, den Bereich für Customer Events anzusehen und den Clerk Pixel zu verwalten, damit wir das Order-Tracking prüfen können.