Headless-integratie¶

Gift Card Hero ondersteunt headless Shopify-webshops die het standaard themasysteem van Shopify niet gebruiken. Schakel de headless-modus in om een integratiecodefragment te krijgen dat je in je eigen webshop insluit.

Stap 1: Schakel headless-modus in¶

Ga naar For developers in het linkermenu. Klik in de kaart Headless mode op Enable headless mode. Het statuslabel verandert naar Enabled. Klik op Save in de opslagbalk om dit te bewaren.

Headless-modus inschakelen

Stap 2: Kopieer de integratiecode¶

Zodra headless-modus is ingeschakeld, verschijnt op de pagina een codefragment. Klik op Copy to clipboard. Het fragment bevat een lege <div id="sc-giftcard-builder">, een configuratieblok en het Gift Card Hero-webshopscript. Voeg het toe aan je productpagina voor cadeaubonnen.

Integratiecodefragment

Stap 3: Vervang de placeholders¶

Het codefragment bevat placeholderwaarden die je moet vervangen door de gegevens van je eigen winkel:

Placeholder	Vervang door	Voorbeeld
`[MONEY_FORMAT]`	De geldnotatie van je winkel	`${{amount}}`
`[PRODUCT_ID]`	De numerieke Shopify-ID van je cadeaubonproduct	`7654321098765`
`[MYSHOPIFY_DOMAIN]`	Het `.myshopify.com`-adres van je winkel	`my-store.myshopify.com`
`[ADD_TO_CART_CALLBACK]`	Een JavaScript-functie die items aan de winkelwagen toevoegt	`addItemToCart`
`[LOCALE]`	De localecode van je vertalingen	`en`

[PRODUCT_ID] is een getal en staat zonder aanhalingstekens in het fragment. De andere waarden staan tussen aanhalingstekens. Vervang '[ADD_TO_CART_CALLBACK]' samen met de aanhalingstekens door je functie (bijvoorbeeld addToCart: addItemToCart), omdat Gift Card Hero die als functie aanroept.

Geldnotatie¶

De geldnotatie bepaalt hoe prijzen worden getoond. De pagina toont de eigen geldnotatie van je winkel als voorbeeld naast de placeholder. Zie de handleiding voor valutanotatie van Shopify voor de notatiecodes.

Veelgebruikte notaties:

${{amount}} — Amerikaanse dollars
{{amount}} EUR — euro's
${{amount}} CAD — Canadese dollars

Product-ID¶

Zo vind je de Shopify-ID van je cadeaubonproduct:

Open Shopify Admin
Ga naar Products
Klik op je cadeaubonproduct
Kijk in de adresbalk van je browser — het numerieke ID staat aan het eind

Als de URL bijvoorbeeld https://admin.shopify.com/store/my-store/products/7654321098765 is, dan is het product-ID 7654321098765.

Callback voor toevoegen aan winkelwagen¶

De placeholder [ADD_TO_CART_CALLBACK] moet je vervangen door de naam van een JavaScript-functie waarmee je webshop items aan de winkelwagen toevoegt. Gift Card Hero roept die aan met één object en verwacht een promise terug:

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 bevat de keuzes van de koper (bericht, afzender, ontvanger, leverdatum en de gegevens van het cadeaubonontwerp). Geef ze allemaal ongewijzigd door aan je winkelwagenregel, zodat de cadeaubon correct wordt aangemaakt. Als de functie ontbreekt, mislukt het toevoegen aan de winkelwagen met "Add to cart method is not defined in headless mode".

Locale¶

De placeholder [LOCALE] bepaalt de taal van de interface van Gift Card Hero. Gebruik de code van een taal die je hebt ingesteld in de vertalingen van de app, precies zo geschreven (bijvoorbeeld en of fr). Standaard is en als je het weglaat.

Hoe het fragment zijn instellingen ophaalt¶

Wanneer de pagina laadt, vraagt het webshopscript je cadeaubonnen-instellingen, het product en je vertalingen op bij https://gifthero.syncu.be/api/configuration/headless, met je [MYSHOPIFY_DOMAIN], [PRODUCT_ID] en [LOCALE]. Er is geen login nodig. Het antwoord wordt ongeveer een minuut in de cache bewaard, en het opslaan van je instellingen in de app vernieuwt het.

Is het product-ID onjuist, dan mislukt het verzoek met Product id is incorrect en wordt er niets getoond. Ontbreekt de geldnotatie, het product-ID of de winkel in het fragment, dan meldt het script dat in de browserconsole.

Aangepaste bedragen¶

Verkoop je cadeaubonnen met een vrij bedrag, dan moet het bedrag binnen het minimum en maximum blijven die je in de app hebt ingesteld; de server weigert bedragen erbuiten. Wanneer de checkout via Gift Card Hero wordt aangemaakt, bouwt de server de bestelling opnieuw op uit je instellingen, dus de prijs kan niet vanuit de browser worden gewijzigd. In deze flow wordt de koper naar de checkoutlink gestuurd die de server teruggeeft, in plaats van dat je functie voor toevoegen aan de winkelwagen wordt aangeroepen.

Na de integratie¶

Zodra het fragment is ingesloten en de placeholders zijn vervangen, toont Gift Card Hero zijn cadeaubonselectie op je webshop. Wil je in plaats daarvan je eigen interface bouwen, vink dan ook Enable storefront API aan op de pagina For developers. De builder van de app wordt dan niet meer getoond, en de Storefront API (window.GiftHeroAPI) wordt voor je geladen zodat jij die kunt aansturen.