> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Integração personalizada
> Chame a API de Strategies diretamente para alimentar experiências personalizadas na vitrine - carrosséis de PDP, upsells de carrinho personalizados e qualquer outro lugar que as superfícies nativas do Aftersell não alcancem.
## 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
```liquid theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
{% comment %}
Aftersell Carousel (Splide)
Type: Section — save to sections/aftersell-upsell-carousel.liquid
{% endcomment %}
{% if product %}
{{ section.settings.heading | default: 'You might also like' }}
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:
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
var products = {{ cart.items | json }}.map(function(item) {
return {
productId: 'gid://shopify/Product/' + item.product_id,
variantId: 'gid://shopify/ProductVariant/' + item.variant_id,
quantity: item.quantity,
price: item.price / 100
// ...other fields as needed
};
});
```
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:
```json theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
{
"success": true,
"products": [ /* enriched recommended products */ ],
"evaluationId": "f3a1c2e0-...",
"resolution": { "strategyId": "...", "matchedRuleIds": [...], "fallbackUsed": false },
"meta": { "servedFromCache": false, "processingTimeMs": 12, "data": {} }
}
```
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](#attribution) 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](/pt/aftersell/strategies_api_reference_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](/pt/aftersell/strategies_building_in_app) 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:
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
properties: {
"_source": "Aftersell",
"_attribution": "CTA"
}
```
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:
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
properties: {
"_source": "PDP Carousel",
"_strategy_id": "{{ section.settings.strategy_id }}",
"_campaign": "summer-2026"
}
```
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:
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
.then(function(data) {
if (!data || !data.success || !data.products || !data.products.length) {
clearSkeletons(); return;
}
evaluationId = data.evaluationId; // declare `var evaluationId;` alongside your other state
renderCards(data.products.slice(0, MAX_PRODUCTS));
})
```
Em seguida, inclua-o nas propriedades de adicionar ao carrinho:
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
properties: Object.assign(
{ "_source": "Aftersell", "_attribution": "CTA" },
evaluationId ? { "__as_offer_id": evaluationId } : {}
)
```
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.
