Skip to main content

​
Visão geral

Quando nem as superfícies nativas do Aftersell (pós-compra, checkout, Upcart) nem uma integração pronta atendem, você pode chamar a API de Strategies por conta própria a partir do seu tema da Shopify e renderizar os produtos retornados da forma que quiser. O padrão é o mesmo em todos os casos: monte um payload de contexto a partir do Liquid (para que atributos da Shopify como o produto atual, o conteúdo do carrinho e os campos do cliente sejam preenchidos no momento da renderização), faça um POST para /api/public/strategy/evaluate e renderize a resposta. Esta página cobre dois padrões de implementação:
  • Contexto de PDP - adicione uma seção às páginas de produto que chama a API com o produto visualizado no momento e renderiza um carrossel com as recomendações retornadas.
  • Contexto de carrinho - renderize um bloco de upsell dentro de um carrinho personalizado que chama a API com todos os itens de linha atuais do carrinho e renderiza os produtos retornados.
O formato do contexto de produto é o que difere entre os dois: um único produto na PDP, um array com todos os itens de linha no carrinho.

​
O que você vai precisar

  1. Sua chave de API da Strategy. No Aftersell, vá em Settings → Product Strategy e, no card Security Token, copie seu token (essa é a sua chave de API da Strategy).
  2. O ID da Strategy. Abra a Strategy que você quer executar no editor de Strategy do Aftersell e copie o ID dela.
  3. Acesso ao código do tema. Você adicionará uma seção Liquid (PDP) ou um bloco (carrinho personalizado) ao seu tema da Shopify - Online Store → Themes → … → Edit code.
Sua chave de API da Strategy fica no código do tema do lado do cliente, o que a torna visível para qualquer pessoa que visualizar o código-fonte da página. Trate-a como uma credencial pública da vitrine e rotacione-a no Aftersell em Settings → Product Strategy se ela for exposta de uma forma que você não pretendia.

​
Contexto de PDP: snippet de seção

Esse padrão adiciona uma seção da Shopify à sua página de produto. Quando a página é renderizada, o Liquid incorpora os atributos do produto atual, do carrinho e do cliente no payload; em seguida, o JavaScript envia um post para a API de Strategies e renderiza os produtos retornados em um carrossel Splide.

​
Instalando

  1. No seu admin da Shopify, vá em Online Store → Themes, clique em … no seu tema e selecione Edit code.
  2. Na pasta Sections, crie um novo arquivo chamado aftersell-upsell-carousel.liquid.
  3. Cole o snippet abaixo no novo arquivo e substitua YOUR_STRATEGY_API_KEY pela chave de API do Aftersell.
  4. Salve.
  5. Abra o template do seu produto (normalmente templates/product.json ou sections/main-product.liquid) e adicione a seção Aftersell Carousel onde você quer que o carrossel apareça. Pelo editor de tema, você também pode arrastá-la diretamente para a página de produto.
  6. Nas configurações da seção, cole o seu Strategy ID.

​
O que a seção envia

Para cada visualização de PDP, o payload inclui:
  • products - um array de um único elemento contendo o produto visualizado no momento (productId, variantId, quantity, price, handle, title, vendor, productType, tags, collections, sellingPlan).
  • cart - subtotal, contagem de itens e contagem de linhas do carrinho atual do comprador (omitido se o carrinho estiver vazio).
  • cartToken - para que a API possa vincular essa avaliação à mesma sessão.
  • customer - tags, país, estado, localidade, contagem de pedidos, total gasto e o indicador aceita-marketing, mas apenas se o comprador estiver logado.
  • session - código de moeda de shop.currency.
A seção não envia parâmetros UTM por padrão. Se você quiser segmentação baseada em UTM na PDP, capture-os no lado do cliente e adicione-os ao objeto session antes do fetch.

​
O snippet

Um carrossel de produtos alimentado por Strategy renderizado em uma página de produto da Shopify

​
Personalizando

O schema da seção expõe quatro configurações editáveis pelo lojista: Strategy ID, Heading, CTA Button Label e Max Products to Show. Adicione ou remova configurações no bloco {% schema %} para expor mais opções ao editor de tema. O CSS está limitado a nomes de classe .aftersell-* e inclui um carrossel de 4 itens controlado pelo Splide que passa para 2 itens em 768px e 1 item em 480px. Edite-o livremente para combinar com o seu tema - nada dele é necessário para a chamada de API funcionar.

​
Contexto de carrinho: bloco de upsell de carrinho personalizado

Esse padrão é estruturalmente igual ao da PDP, com uma diferença fundamental: o array de contexto de produto é construído a partir dos itens de linha do carrinho, em vez do produto visualizado no momento. A Strategy então recebe todos os itens que o comprador adicionou e retorna recomendações com base no carrinho como um todo. A implementação fica onde estiver o código do seu carrinho personalizado - uma seção Liquid que renderiza o cart drawer, um bloco personalizado em uma vitrine headless ou um template de tema como cart.liquid. O formato da chamada de API e o tratamento da resposta são idênticos ao exemplo da PDP - apenas o array products é diferente. A estrutura fica assim:
O restante do payload (cart, customer, session, cartToken) e a chamada fetch para /api/public/strategy/evaluate permanecem inalterados em relação ao padrão da PDP acima - apenas o array products muda de [productContext] para o array derivado do carrinho.

​
O que acontece quando a Strategy retorna

O formato da resposta é o mesmo independentemente do contexto que você enviou:
O evaluationId é um id único para essa avaliação. Se você capturá-lo e anexá-lo aos produtos que renderiza, poderá atribuir o pedido resultante à recomendação exata que o gerou - veja Atribuição abaixo. Como você renderiza o array products fica totalmente a cargo do código do seu tema. O snippet da PDP acima os renderiza como um carrossel de cards com seletores de variante e botões de adicionar ao carrinho; um bloco de carrinho personalizado poderia renderizá-los como uma lista vertical dentro do drawer. Para o schema completo de requisição e resposta, consulte a referência da API Evaluate Strategy.

​
Quando nenhum produto é retornado

Se a Strategy não retornar produtos (products: []), cabe ao seu código decidir como lidar com isso. O snippet da PDP acima oculta o carrossel por completo. Um bloco de carrinho personalizado poderia recorrer à lista de upsell padrão do carrinho, ou simplesmente não renderizar nada. Para evitar uma resposta vazia, configure um Catch all na Strategy para que sempre haja um produto de fallback para retornar. Consulte a página Criando Strategies para saber como configurar um Catch all.

​
Dicas para integrações personalizadas

  • Monte o contexto no Liquid. O Liquid é executado no momento da renderização e tem acesso ao grafo completo de objetos da Shopify - product, cart, customer, shop, request. Use-o para preencher o payload no lado do servidor em vez de recorrer a chamadas do lado do cliente.
  • Mantenha a chave de API fora de repositórios públicos. Ela vai acabar no código do seu tema, que é enviado ao navegador - isso não é um problema. Mas não cole o mesmo tema em um repositório público nem compartilhe o bundle externamente.
  • Use um Catch all. Experiências na vitrine parecem quebradas quando um slot desaparece. Um Catch all com um pequeno conjunto de padrões seguros mantém a interface consistente.
  • Faça cache onde fizer sentido. A API de Strategies faz um cache leve no lado do servidor (meta.servedFromCache), mas, para PDPs de alto tráfego, você também pode querer aplicar debounce ou memoizar chamadas no cliente (por exemplo, não chamar novamente quando o mesmo produto é renderizado duas vezes em uma sessão).

​
Atribuição

Quando um comprador clica no botão de adicionar ao carrinho no snippet, a chamada /cart/add.js anexa propriedades de item de linha ao item do carrinho:
Essas propriedades acompanham o item de linha até o pedido da Shopify, onde aparecem no registro do item de linha. Você pode usá-las mais adiante para atribuir receita, filtrar pedidos ou alimentar ferramentas de análise que leem propriedades de item de linha. As chaves e os valores são convenções, não requisitos - a chamada de API funciona da mesma forma independentemente do que você colocar aqui. Altere-os para se adequarem ao seu próprio modelo de atribuição. Por exemplo:
Chaves de propriedade que começam com um sublinhado (_) ficam ocultas na interface do carrinho e do checkout, mas ainda assim são anexadas ao pedido. Use o prefixo de sublinhado para metadados exclusivos de atribuição que você não quer que os compradores vejam.
Aplique o mesmo padrão na implementação de contexto de carrinho - qualquer chamada de adicionar ao carrinho que você fizer a partir de um bloco de upsell personalizado pode carregar as propriedades que você precisar.

​
Atribuindo de volta à avaliação

Para vincular um pedido à avaliação exata que recomendou o produto - em vez de apenas “veio de uma Strategy” - capture o evaluationId da resposta e anexe-o ao item de linha na propriedade __as_offer_id. O AfterSell lê essa chave, então pedidos marcados com ela são atribuídos à avaliação específica nos relatórios. No handler evaluate(), guarde o id da resposta:
Em seguida, inclua-o nas propriedades de adicionar ao carrinho:
Mantenha o sublinhado duplo em __as_offer_id - é a chave que o AfterSell procura, e o prefixo de sublinhado a mantém oculta dos compradores. Se o evaluationId estiver ausente (por exemplo, se nenhum produto foi retornado), omita a propriedade em vez de enviar um valor vazio.