Integración headless¶

Gift Card Hero admite tiendas online headless de Shopify que no usan el sistema de temas estándar de Shopify. Activa el modo headless para obtener un fragmento de código de integración que insertas en tu tienda online personalizada.

Paso 1: activa el modo headless¶

Ve a For developers en la navegación izquierda. En la tarjeta Headless mode, haz clic en Enable headless mode. La insignia de estado cambia a Enabled. Haz clic en Save en la barra de guardado para conservarlo.

Activar el modo headless

Paso 2: copia el código de integración¶

Cuando el modo headless está activo, aparece un fragmento de código en la página. Haz clic en Copy to clipboard. El fragmento contiene un <div id="sc-giftcard-builder"> vacío, un bloque de configuración y el script de la tienda de Gift Card Hero. Añádelo a la página de producto de tarjeta de regalo.

Fragmento del código de integración

Paso 3: sustituye los marcadores¶

El fragmento de código contiene valores de marcador que debes reemplazar con la información específica de tu tienda:

Marcador	Sustitúyelo por	Ejemplo
`[MONEY_FORMAT]`	El formato de moneda de tu tienda	`${{amount}}`
`[PRODUCT_ID]`	El ID numérico de Shopify de tu producto de tarjeta de regalo	`7654321098765`
`[MYSHOPIFY_DOMAIN]`	La dirección `.myshopify.com` de tu tienda	`my-store.myshopify.com`
`[ADD_TO_CART_CALLBACK]`	Una función de JavaScript que gestiona añadir artículos al carrito	`addItemToCart`
`[LOCALE]`	El código de idioma de tus traducciones	`en`

[PRODUCT_ID] es un número y no lleva comillas en el fragmento. Los demás van entre comillas. Sustituye '[ADD_TO_CART_CALLBACK]', junto con sus comillas, por tu función (por ejemplo addToCart: addItemToCart), porque Gift Card Hero la llama como función.

Formato de moneda¶

La cadena de formato de moneda determina cómo se muestran los precios. La página muestra el formato de moneda de tu propia tienda como ejemplo junto al marcador. Consulta la guía de formato de moneda de Shopify para ver los códigos de formato.

Formatos habituales:

${{amount}} — dólares estadounidenses
{{amount}} EUR — euros
${{amount}} CAD — dólares canadienses

ID del producto¶

Para encontrar el ID de Shopify de tu producto de tarjeta de regalo:

Abre Shopify Admin
Ve a Products
Haz clic en tu producto de tarjeta de regalo
Mira la URL en la barra de direcciones del navegador: el ID numérico está al final

Por ejemplo, si la URL es https://admin.shopify.com/store/my-store/products/7654321098765, el ID del producto es 7654321098765.

Callback de añadir al carrito¶

El marcador [ADD_TO_CART_CALLBACK] debe sustituirse por el nombre de una función de JavaScript que tu tienda usa para añadir artículos al carrito. Gift Card Hero la llama con un objeto y espera recibir una promesa:

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 contiene las elecciones del comprador (mensaje, remitente, destinatario, fecha de entrega y los datos del diseño de la tarjeta). Pásalas todas sin cambios a la línea de tu carrito para que la tarjeta de regalo se cree correctamente. Si falta la función, añadir al carrito falla con «El método de añadir al carrito no está definido en el modo headless».

Idioma¶

El marcador [LOCALE] define el idioma de la interfaz de Gift Card Hero. Usa el código de un idioma que hayas configurado en las traducciones de la app, escrito exactamente igual (por ejemplo en o fr). Si se omite, el valor predeterminado es en.

Cómo obtiene el fragmento su configuración¶

Al cargar la página, el script de la tienda pide tu configuración de tarjetas de regalo, el producto y tus traducciones a https://gifthero.syncu.be/api/configuration/headless, usando tu [MYSHOPIFY_DOMAIN], [PRODUCT_ID] y [LOCALE]. No requiere inicio de sesión. La respuesta se guarda en caché durante un minuto aproximadamente, y guardar tu configuración en la app la actualiza.

Si el ID del producto es incorrecto, la petición falla con Product id is incorrect y no se muestra nada. Si falta el formato de moneda, el ID del producto o la tienda en el fragmento, el script lo notifica en la consola del navegador.

Importes personalizados¶

Si vendes tarjetas de regalo de importe personalizado, el importe debe estar entre el mínimo y el máximo que definiste en la app; el servidor rechaza los importes fuera de ese rango. Cuando el pago se crea a través de Gift Card Hero, el servidor reconstruye el pedido a partir de tu configuración, así que el precio no puede modificarse desde el navegador. En este flujo, el comprador es enviado al enlace de pago (checkout) que devuelve el servidor, en lugar de que se llame a tu función de añadir al carrito.

Después de la integración¶

Cuando el fragmento esté insertado y los marcadores sustituidos, Gift Card Hero muestra su interfaz de selección de tarjetas de regalo en tu tienda online. Si quieres crear tu propia interfaz en lugar del creador de tarjetas de la app, marca también Enable storefront API en la página For developers. El creador no se mostrará y la API de Storefront (window.GiftHeroAPI) se cargará para que la controles.