Storefront API¶

Die Storefront API bietet eine JavaScript-Schnittstelle (window.GiftHeroAPI) für den Aufbau eigener Auswahl- und Kaufabläufe für Geschenkgutscheine in Ihrem Onlineshop.

Konfiguration der Storefront API

API aktivieren¶

Gehen Sie in der linken Navigation zu For developers.
Setzen Sie den Haken bei Enable storefront API und speichern Sie.

Die Oberfläche für Geschenkgutscheine, die die App auf Ihrer Produktseite erzeugt, wird ausgeschaltet, und stattdessen wird window.GiftHeroAPI geladen. Die Oberfläche bauen Sie selbst.

Die API liest keine Guthaben von Geschenkgutscheinen aus. Sie erfasst die Auswahl des Käufers und legt den Geschenkgutschein in den Warenkorb.

Headless-Storefronts

Bei einem Headless-Storefront wird die API geladen, sobald der Headless-Modus und Enable storefront API beide aktiv sind. Siehe Headless-Integration.

Initialisierung¶

Die API lädt asynchron. Gift Card Hero löst ein Ereignis auf window aus, sobald sie bereit ist. Warten Sie auf dieses Ereignis, bevor Sie Methoden aufrufen:

window.addEventListener('gift.hero:initalized', function () {
  const api = window.GiftHeroAPI;
  // API is ready to use
});

Der Ereignisname ist mit initalized geschrieben

Der Ereignisname enthält einen Tippfehler: gift.hero:initalized (ohne zweites „i“). Verwenden Sie ihn genau so, wie er geschrieben ist. Das Ereignis wird auf window ausgelöst, nicht auf document, nachdem das Storefront-Skript von Gift Card Hero geladen wurde. Wenn das Skript nicht auf der Seite ist oder die Storefront API ausgeschaltet ist, wird das Ereignis nicht ausgelöst.

Wenn die API startet, wählt sie die erste Variante (oder die Variante aus dem URL-Parameter ?variant=) und das erste Bild aus.

Methoden¶

addToCart(quantity?, skipValidation?)¶

Prüft die Kartendaten und legt den konfigurierten Geschenkgutschein mit /cart/add.js von Shopify in den Warenkorb.

try {
  const result = await window.GiftHeroAPI.addToCart(1);
  // result: { status: 200, data: { ... } }
} catch (e) {
  // e: { status: 400, data: { errors: ['...'] } } when validation fails
}

Parameter	Typ	Standard	Beschreibung
`quantity`	number	1	Anzahl der hinzuzufügenden Geschenkgutscheine
`skipValidation`	boolean	false	Die Karte hinzufügen, auch wenn `validate()` Fehler meldet

Rückgabe: ein Promise mit der Warenkorb-Antwort von Shopify ({ status, data }). Es wird mit { status: 400, data: { errors } } abgelehnt, wenn die Prüfung fehlschlägt.

generatePreview()¶

Öffnet eine Vorschau, die zeigt, wie der Geschenkgutschein für den Empfänger aussieht, mit den bisher gesetzten Daten.

window.GiftHeroAPI.generatePreview();

getImages()¶

Gibt ein Array von Bild-URLs zurück, die für den Geschenkgutschein verfügbar sind: Ihre eigenen Designs, die ausgewählten integrierten Designs und, sofern aktiviert, die Produktbilder.

const images = window.GiftHeroAPI.getImages();
// ['https://cdn.shopify.com/...', 'https://cdn.shopify.com/...']

getOptions()¶

Gibt die Produktoptionen zurück, einschließlich der verfügbaren Wertstufen.

const options = window.GiftHeroAPI.getOptions();

getTranslations()¶

Gibt die Übersetzungen der Oberfläche für die aktuelle Sprache zurück, etwa die Beschriftungen und die Prüfmeldung.

const translations = window.GiftHeroAPI.getTranslations();

getVariants()¶

Gibt das Array der Produktvarianten zurück.

const variants = window.GiftHeroAPI.getVariants();

setCardData(cardData)¶

Legt alle Daten des Geschenkgutscheins auf einmal fest.

window.GiftHeroAPI.setCardData({
  variantId: 12345678,
  image: 'https://cdn.shopify.com/...',
  message: 'Happy Birthday!',
  from: 'Alice',
  to: 'Bob',
  deliveryDate: new Date('2026-12-25'),
  email: 'recipient@example.com'
});

Feld	Typ	Beschreibung
`variantId`	number	Die ausgewählte Varianten-ID
`image`	string	URL des ausgewählten Kartenbilds
`message`	string	Nachricht des Geschenkgutscheins
`from`	string	Name des Absenders
`to`	string	Name des Empfängers (optional)
`deliveryDate`	`Date`	Geplantes Zustelldatum als JavaScript-`Date`-Objekt (optional)
`email`	string	E-Mail-Adresse des Empfängers (optional)

Die SMS-Zustellung ist über die API nicht verfügbar. Deshalb gibt es kein Telefonfeld.

Einzelne Setter¶

Methode	Parameter	Beschreibung
`setDeliveryDate(date)`	`Date`	Geplantes Zustelldatum festlegen. Wirft einen Fehler, wenn es kein gültiges Datumsobjekt ist
`setEmail(email)`	string	E-Mail-Adresse des Empfängers festlegen
`setFrom(name)`	string	Namen des Absenders festlegen
`setTo(name)`	string	Namen des Empfängers festlegen
`setImage(image)`	string	URL des ausgewählten Kartenbilds festlegen
`setMessage(message)`	string	Nachricht des Geschenkgutscheins festlegen
`setVariant(variantId)`	number oder string	Ausgewählte Variante festlegen
`setProperty(name, value)`	string, string	Der Warenkorbposition eine zusätzliche Eigenschaft hinzufügen

validate()¶

Prüft die aktuellen Daten des Geschenkgutscheins und gibt { valid, errors } zurück. errors ist ein Array von Meldungen, das aus Ihren Übersetzungen gebildet wird.

const { valid, errors } = window.GiftHeroAPI.validate();

Prüfregeln:

Wenn eine E-Mail-Adresse des Empfängers gesetzt ist, sind Zustelldatum, Absendername (from) und Nachricht erforderlich.
Wenn ein Zustelldatum gesetzt ist, sind E-Mail-Adresse des Empfängers, Absendername und Nachricht erforderlich.
Ohne E-Mail-Adresse und ohne Zustelldatum ist nichts erforderlich.

setCustomAmount(amount)¶

Wählt einen frei festgelegten Betrag in Ihrer Shop-Währung aus (zum Beispiel 75 für 75,00). Das funktioniert nur, wenn frei festgelegte Beträge für Ihren Shop aktiviert sind. Andernfalls wird Custom amount is not enabled ausgelöst. Die Methode prüft Ihr Minimum und Maximum nicht. Prüfen Sie den Betrag daher selbst.

window.GiftHeroAPI.setCustomAmount(75);

Physische Geschenkgutscheine¶

Wenn Sie physische Geschenkgutscheine verkaufen, stellen Sie die API mit setCardType('physical') darauf um (mit setCardType('eGift') wechseln Sie zurück).

Methode	Beschreibung
`setCardType(type)`	`'eGift'` oder `'physical'`. Mit `'physical'` wird die erste physische Variante und das erste Bild gewählt
`getPhysicalProduct()`	Das physische Geschenkgutschein-Produkt
`getPhysicalVariants()`	Varianten des physischen Produkts
`getPhysicalImages()`	Bild-URLs des physischen Produkts
`setPhysicalVariant(variantId)`	Eine physische Variante wählen (nur im Typ physical)
`setPhysicalDeliveryAddress(address)`	Die Lieferadresse festlegen (nur im Typ physical): `firstName`, `lastName`, `address`, `zipCode`, `city`, `country` und optional `state`
`isPhysicalCard()`	`true`, wenn der Typ physical ausgewählt ist

uploadCustomDesign(file, options?)¶

Lädt ein eigenes Bild des Käufers hoch und gibt seine URL zurück, die Sie an setImage() übergeben können.

const { url } = await window.GiftHeroAPI.uploadCustomDesign(file);
window.GiftHeroAPI.setImage(url);

Die Datei muss ein JPG-, PNG-, GIF- oder WebP-Bild sein, standardmäßig bis 5 MB groß. Sie können die Grenzen mit options.maxSize (in Bytes) und options.allowedTypes ändern. Die Methode löst einen Fehler mit einer klaren Meldung aus, wenn die Datei abgelehnt wird.

Beispiel zur React-Integration¶

Ein vollständiges Beispiel zur React-Integration steht auf JSFiddle bereit. Es zeigt, wie Sie die API initialisieren, eine eigene Auswahloberfläche für Geschenkgutscheine bauen und den Ablauf „In den Warenkorb“ umsetzen:

React-Beispiel auf JSFiddle ansehen