Integração headless¶

O Gift Card Hero oferece suporte a lojas virtuais Shopify headless que não usam o sistema de temas padrão da Shopify. Ative o modo headless para obter um trecho de código de integração que você incorpora na sua loja virtual personalizada.

Passo 1: Ative o modo headless¶

Acesse For developers na navegação à esquerda. No cartão Headless mode, clique em Enable headless mode. O selo de status muda para Enabled. Clique em Save na barra de salvamento para mantê-lo.

Ativar o modo headless

Passo 2: Copie o código de integração¶

Quando o modo headless estiver ativado, um trecho de código aparece na página. Clique em Copy to clipboard. O trecho contém uma <div id="sc-giftcard-builder"> vazia, um bloco de configuração e o script da loja do Gift Card Hero. Adicione-o à página de produto do cartão-presente.

Trecho do código de integração

Passo 3: Substitua os placeholders¶

O trecho de código contém valores de placeholder que você deve substituir pelas informações específicas da sua loja:

Placeholder	Substitua por	Exemplo
`[MONEY_FORMAT]`	A string de formato monetário da sua loja	`${{amount}}`
`[PRODUCT_ID]`	O ID numérico do seu produto de cartão-presente na Shopify	`7654321098765`
`[MYSHOPIFY_DOMAIN]`	O endereço `.myshopify.com` da sua loja	`my-store.myshopify.com`
`[ADD_TO_CART_CALLBACK]`	Uma função JavaScript que trata da adição de itens ao carrinho	`addItemToCart`
`[LOCALE]`	O código de locale das suas traduções	`en`

[PRODUCT_ID] é um número e não tem aspas no trecho. Os outros ficam entre aspas. Substitua '[ADD_TO_CART_CALLBACK]' junto com as aspas pela sua função (por exemplo, addToCart: addItemToCart), porque o Gift Card Hero a chama como função.

Formato monetário¶

A string de formato monetário define como os preços são exibidos. A página mostra o formato monetário da própria loja como exemplo, ao lado do placeholder. Veja o guia de formatação de moedas da Shopify para os códigos de formato.

Formatos comuns:

${{amount}} — dólares americanos
{{amount}} EUR — euros
${{amount}} CAD — dólares canadenses

ID do produto¶

Para encontrar o ID Shopify do seu produto de cartão-presente:

Abra o Shopify Admin
Acesse Products
Clique no seu produto de cartão-presente
Olhe a URL na barra de endereços do navegador — o ID numérico fica no final

Por exemplo, se a URL for https://admin.shopify.com/store/my-store/products/7654321098765, o ID do produto é 7654321098765.

Função de callback para adicionar ao carrinho¶

O placeholder [ADD_TO_CART_CALLBACK] deve ser substituído pelo nome de uma função JavaScript que sua loja virtual usa para adicionar itens ao carrinho. O Gift Card Hero a chama com um objeto e espera uma promise de volta:

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 guarda as escolhas do comprador (mensagem, remetente, destinatário, data de entrega e os dados do design do cartão). Passe todas elas para a linha do carrinho sem alterações, para que o cartão-presente seja criado corretamente. Se a função não existir, a adição ao carrinho falha com "Add to cart method is not defined in headless mode".

Locale¶

O placeholder [LOCALE] define o idioma da interface do Gift Card Hero. Use o código de um idioma que você configurou nas traduções do app, escrito exatamente igual (por exemplo, en ou fr). O padrão é en se for omitido.

Como o trecho obtém suas configurações¶

Quando a página carrega, o script da loja solicita as configurações de cartão-presente, o produto e as traduções de https://gifthero.syncu.be/api/configuration/headless, usando seus [MYSHOPIFY_DOMAIN], [PRODUCT_ID] e [LOCALE]. Não é necessário login. A resposta fica em cache por cerca de um minuto, e salvar suas configurações no app atualiza o cache.

Se o ID do produto estiver errado, a solicitação falha com Product id is incorrect e nada é exibido. Se o formato monetário, o ID do produto ou a loja estiver ausente do trecho, o script informa isso no console do navegador.

Valores personalizados¶

Se você vende cartões-presente de valor personalizado, o valor deve ficar entre o mínimo e o máximo que você definiu no app; o servidor recusa valores fora desse intervalo. Quando o checkout é criado pelo Gift Card Hero, o servidor reconstrói o pedido com base nas suas configurações, então o preço não pode ser alterado pelo navegador. Nesse fluxo, o comprador é enviado ao link de checkout que o servidor retorna, em vez de sua função de adicionar ao carrinho ser chamada.

Após a integração¶

Depois que o trecho for incorporado e os placeholders substituídos, o Gift Card Hero exibe a interface de seleção de cartões-presente na sua loja virtual. Para criar sua própria interface em vez do construtor de cartões do app, marque também Enable storefront API na página For developers. O construtor então deixa de ser exibido, e a API da loja virtual (window.GiftHeroAPI) é carregada para você controlar.