Intégration headless¶

Gift Card Hero prend en charge les vitrines Shopify headless qui n'utilisent pas le système de thèmes standard de Shopify. Activez le mode headless pour obtenir un extrait de code d'intégration à intégrer à votre vitrine personnalisée.

Étape 1 : activer le mode headless¶

Allez dans For developers dans la navigation de gauche. Dans la carte Headless mode, cliquez sur Enable headless mode. Le badge de statut passe à Enabled. Cliquez sur Save dans la barre d'enregistrement pour le conserver.

Activer le mode headless

Étape 2 : copier le code d'intégration¶

Une fois le mode headless activé, un extrait de code apparaît sur la page. Cliquez sur Copy to clipboard. L'extrait contient une <div id="sc-giftcard-builder"> vide, un bloc de configuration et le script de la vitrine Gift Card Hero. Ajoutez-le à la page produit de votre carte-cadeau.

Extrait du code d'intégration

Étape 3 : remplacer les espaces réservés¶

L'extrait de code contient des valeurs d'espace réservé que vous devez remplacer par les informations propres à votre boutique :

Espace réservé	Remplacer par	Exemple
`[MONEY_FORMAT]`	Le format monétaire de votre boutique	`${{amount}}`
`[PRODUCT_ID]`	L'identifiant numérique Shopify de votre produit carte-cadeau	`7654321098765`
`[MYSHOPIFY_DOMAIN]`	L'adresse `.myshopify.com` de votre boutique	`my-store.myshopify.com`
`[ADD_TO_CART_CALLBACK]`	Une fonction JavaScript qui gère l'ajout d'articles au panier	`addItemToCart`
`[LOCALE]`	Le code de langue de vos traductions	`en`

[PRODUCT_ID] est un nombre et n'a pas de guillemets dans l'extrait. Les autres sont placés entre guillemets. Remplacez '[ADD_TO_CART_CALLBACK]', guillemets compris, par votre fonction (par exemple addToCart: addItemToCart), car Gift Card Hero l'appelle comme une fonction.

Format monétaire¶

La chaîne de format monétaire détermine l'affichage des prix. La page affiche le format monétaire de votre boutique à côté de l'espace réservé, à titre d'exemple. Voir le guide de mise en forme des devises de Shopify pour les codes de format.

Formats courants :

${{amount}} — dollars américains
{{amount}} EUR — euros
${{amount}} CAD — dollars canadiens

Identifiant du produit¶

Pour trouver l'identifiant Shopify de votre produit carte-cadeau :

Ouvrez Shopify Admin
Allez dans Products
Cliquez sur votre produit carte-cadeau
Regardez l'URL dans la barre d'adresse de votre navigateur : l'identifiant numérique se trouve à la fin

Par exemple, si l'URL est https://admin.shopify.com/store/my-store/products/7654321098765, l'identifiant du produit est 7654321098765.

Fonction de rappel d'ajout au panier¶

L'espace réservé [ADD_TO_CART_CALLBACK] doit être remplacé par le nom d'une fonction JavaScript que votre vitrine utilise pour ajouter des articles au panier. Gift Card Hero l'appelle avec un seul objet et attend une promesse en retour :

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 contient les choix de l'acheteur (message, expéditeur, destinataire, date de livraison et données du visuel de carte). Transmettez-les toutes à la ligne de votre panier sans les modifier, afin que la carte-cadeau soit créée correctement. Si la fonction est absente, l'ajout au panier échoue avec le message « Add to cart method is not defined in headless mode ».

Langue¶

L'espace réservé [LOCALE] définit la langue de l'interface de Gift Card Hero. Utilisez le code d'une langue que vous avez configurée dans les traductions de l'application, écrit exactement de la même façon (par exemple en ou fr). La valeur par défaut est en si elle est omise.

Comment l'extrait obtient ses paramètres¶

Au chargement de la page, le script de la vitrine demande vos réglages de carte-cadeau, le produit et vos traductions à https://gifthero.syncu.be/api/configuration/headless, en utilisant votre [MYSHOPIFY_DOMAIN], votre [PRODUCT_ID] et votre [LOCALE]. Aucune connexion n'est nécessaire. La réponse est mise en cache pendant environ une minute, et l'enregistrement de vos réglages dans l'application la rafraîchit.

Si l'identifiant du produit est incorrect, la requête échoue avec le message Product id is incorrect et rien ne s'affiche. Si le format monétaire, l'identifiant du produit ou la boutique est absent de l'extrait, le script le signale dans la console du navigateur.

Montants personnalisés¶

Si vous vendez des cartes-cadeaux à montant personnalisé, le montant doit rester entre le minimum et le maximum que vous avez définis dans l'application ; le serveur refuse les montants en dehors de ces bornes. Lorsque le paiement est créé via Gift Card Hero, le serveur reconstruit la commande à partir de vos réglages, de sorte que le prix ne peut pas être modifié depuis le navigateur. Dans ce cas, l'acheteur est redirigé vers le lien de paiement renvoyé par le serveur, au lieu que votre fonction d'ajout au panier soit appelée.

Après l'intégration¶

Une fois l'extrait intégré et les espaces réservés remplacés, Gift Card Hero affiche son interface de sélection de cartes-cadeaux sur votre vitrine. Pour créer votre propre interface au lieu du constructeur de cartes-cadeaux de l'application, cochez aussi Enable storefront API sur la page For developers. Le constructeur n'est alors plus affiché, et l'API Storefront (window.GiftHeroAPI) est chargée pour que vous la pilotiez.