Headless-Integration¶

Gift Card Hero unterstützt Headless-Shopify-Storefronts, die nicht das Standard-Theme-System von Shopify verwenden. Aktivieren Sie den Headless-Modus, um einen Integrationscode-Schnipsel zu erhalten, den Sie in Ihren individuellen Storefront einbetten.

Schritt 1: Headless-Modus aktivieren¶

Gehen Sie in der linken Navigation zu For developers. Klicken Sie in der Karte Headless mode auf Enable headless mode. Das Statusabzeichen wechselt zu Enabled. Klicken Sie in der Speicherleiste auf Save, um die Änderung zu behalten.

Headless-Modus aktivieren

Schritt 2: Den Integrationscode kopieren¶

Sobald der Headless-Modus aktiviert ist, erscheint auf der Seite ein Code-Schnipsel. Klicken Sie auf Copy to clipboard. Der Schnipsel enthält ein leeres <div id="sc-giftcard-builder">, einen Konfigurationsblock und das Storefront-Skript von Gift Card Hero. Fügen Sie ihn auf Ihrer Produktseite für Geschenkgutscheine ein.

Integrationscode-Schnipsel

Schritt 3: Platzhalter ersetzen¶

Der Code-Schnipsel enthält Platzhalterwerte, die Sie durch die Informationen Ihres Stores ersetzen müssen:

Platzhalter	Ersetzen durch	Beispiel
`[MONEY_FORMAT]`	Den Formatstring für Geldbeträge Ihres Stores	`${{amount}}`
`[PRODUCT_ID]`	Die numerische Shopify-ID Ihres Geschenkgutschein-Produkts	`7654321098765`
`[MYSHOPIFY_DOMAIN]`	Die `.myshopify.com`-Adresse Ihres Stores	`my-store.myshopify.com`
`[ADD_TO_CART_CALLBACK]`	Eine JavaScript-Funktion, die das Hinzufügen von Artikeln zum Warenkorb übernimmt	`addItemToCart`
`[LOCALE]`	Der Sprachcode Ihrer Übersetzungen	`en`

[PRODUCT_ID] ist eine Zahl und steht im Schnipsel ohne Anführungszeichen. Die anderen stehen in Anführungszeichen. Ersetzen Sie '[ADD_TO_CART_CALLBACK]' samt Anführungszeichen durch Ihre Funktion (zum Beispiel addToCart: addItemToCart), weil Gift Card Hero sie als Funktion aufruft.

Geldformat¶

Der Geldformat-String bestimmt, wie Preise angezeigt werden. Die Seite zeigt das Geldformat Ihres Stores als Beispiel neben dem Platzhalter. Die Formatcodes finden Sie im Leitfaden zur Währungsformatierung von Shopify.

Übliche Formate:

${{amount}} — US-Dollar
{{amount}} EUR — Euro
${{amount}} CAD — Kanadische Dollar

Produkt-ID¶

So finden Sie die Shopify-ID Ihres Geschenkgutschein-Produkts:

Öffnen Sie den Shopify Admin
Gehen Sie zu Products
Klicken Sie auf Ihr Geschenkgutschein-Produkt
Schauen Sie in die URL in der Adressleiste Ihres Browsers. Die numerische ID steht am Ende.

Wenn die URL zum Beispiel https://admin.shopify.com/store/my-store/products/7654321098765 lautet, ist die Produkt-ID 7654321098765.

Callback für das Hinzufügen zum Warenkorb¶

Der Platzhalter [ADD_TO_CART_CALLBACK] sollte durch den Namen einer JavaScript-Funktion ersetzt werden, mit der Ihr Storefront Artikel in den Warenkorb legt. Gift Card Hero ruft sie mit einem einzigen Objekt auf und erwartet ein Promise als Rückgabe:

function addItemToCart({ items, sections }) {
  // items: [{ id: <variant id>, quantity: 1, properties: { ... } }]
  // Add the line to your cart (for example a Storefront API cart) and return a promise.
}

properties enthält die Auswahl des Käufers (Nachricht, Absender, Empfänger, Lieferdatum und die Daten des Kartendesigns). Übergeben Sie alle unverändert an Ihre Warenkorbposition, damit der Geschenkgutschein korrekt erstellt wird. Fehlt die Funktion, schlägt das Hinzufügen zum Warenkorb mit der Meldung "Add to cart method is not defined in headless mode" fehl.

Locale¶

Der Platzhalter [LOCALE] legt die Sprache der Benutzeroberfläche von Gift Card Hero fest. Verwenden Sie den Code einer Sprache, die Sie in den Übersetzungen der App eingerichtet haben, genau so geschrieben (zum Beispiel en oder fr). Ohne Angabe ist der Standard en.

Wie der Schnipsel seine Einstellungen bezieht¶

Beim Laden der Seite fragt das Storefront-Skript Ihre Geschenkgutschein-Einstellungen, das Produkt und Ihre Übersetzungen unter https://gifthero.syncu.be/api/configuration/headless ab, und zwar mit Ihrem [MYSHOPIFY_DOMAIN], [PRODUCT_ID] und [LOCALE]. Dafür ist keine Anmeldung nötig. Die Antwort wird etwa eine Minute zwischengespeichert, und das Speichern Ihrer Einstellungen in der App aktualisiert sie.

Ist die Produkt-ID falsch, schlägt die Anfrage mit Product id is incorrect fehl und es wird nichts angezeigt. Fehlen Geldformat, Produkt-ID oder Shop im Schnipsel, meldet das Skript dies in der Browser-Konsole.

Eigene Beträge¶

Wenn Sie Geschenkgutscheine mit individuellem Betrag verkaufen, muss der Betrag zwischen dem Mindest- und dem Höchstwert liegen, den Sie in der App festgelegt haben. Der Server lehnt Beträge außerhalb dieser Grenzen ab. Wenn der Checkout über Gift Card Hero erstellt wird, baut der Server die Bestellung anhand Ihrer Einstellungen neu auf, sodass der Preis nicht im Browser geändert werden kann. In diesem Ablauf wird der Käufer zu dem Checkout-Link geleitet, den der Server zurückgibt, statt dass Ihre Funktion zum Hinzufügen zum Warenkorb aufgerufen wird.

Nach der Integration¶

Sobald der Schnipsel eingebettet und die Platzhalter ersetzt sind, zeigt Gift Card Hero seine Auswahloberfläche für Geschenkgutscheine in Ihrem Storefront an. Wenn Sie stattdessen eine eigene Oberfläche bauen möchten, aktivieren Sie auf der Seite For developers zusätzlich Enable storefront API. Der Builder wird dann nicht mehr angezeigt, und die Storefront API (window.GiftHeroAPI) wird für Sie geladen, damit Sie sie ansteuern können.