Visão geral

O Cart SDK é uma API JavaScript para o Aftersell Cart na sua loja. Ele permite mudar como o carrinho se comporta, reagir ao que os compradores fazem e ler ou alterar o conteúdo do carrinho a partir de código. Você executa código do SDK por meio de Scripts personalizados, ou pelo modo React de um bloco Custom code para um bloco que renderiza sua própria UI.

Muito do que os lojistas pedem ao SDK já é uma configuração. Antes de escrever um script, verifique se um bloco do carrinho, as condições por mercado/país/moeda ou uma configuração do carrinho já fazem isso. Esses continuam funcionando após redesigns do carrinho, e seu script pode não continuar.

O ponto de entrada global

Tudo parte de um único global:

window.aftersell.cart

Todo snippet destes docs escreve window.aftersell.cart por extenso, então qualquer um deles funciona sozinho quando você o cola. Criar um alias uma vez (const cart = window.aftersell.cart;) e usar cart daí em diante também é perfeitamente válido, e seguro mesmo antes de o carrinho carregar. Só lembre de incluir essa linha se você encurtar um snippet, já que um cart solto por si só lança cart is not defined.

Quatro partes fazem o trabalho:

Configure

Defina como o carrinho se comporta: quando o drawer abre, como o dinheiro é formatado, se a Aftersell intercepta o adicionar ao carrinho.

Events

Reaja ao que acontece: o carrinho carregou, um item foi adicionado, o drawer abriu, o checkout foi clicado.

Actions

Leia e altere o carrinho: abra-o, adicione um item, atualize uma quantidade, leia o estado atual.

Hooks

Mude como o próprio carrinho funciona: oculte ou renomeie linhas, reordene-as, anexe dados extras, controle o adicionar ao carrinho.

Se um script seu parou de disparar no adicionar ao carrinho, comece por Interceptação do adicionar ao carrinho. Ela explica por que o Aftersell assume a adição e todas as maneiras de isentar um formulário.

Mais três membros menores:

Membro	Para que serve
`ready()`	Uma Promise que resolve assim que o carrinho carregou pela primeira vez.
`context`	Contexto do comprador renderizado pelo servidor, legível de forma síncrona.
`shadowRoot`	O shadow root do carrinho, para consultar elementos dentro do drawer.

Eventos, ações ou hooks?

Os três são fáceis de confundir, e escolher o errado é o motivo mais comum de um script não fazer o que seu autor esperava:

Você quer…	Use	Exemplo
Executar código quando algo acontece	Evento	Enviar um evento de analytics quando um item é adicionado.
Mudar o que está no carrinho	Ação	Adicionar um brinde quando o total passar de $50.
Mudar como o carrinho funciona ou renderiza	Hook	Ocultar linhas de brinde no drawer.

A distinção que mais importa: uma ação altera o carrinho real do comprador (e o total dele), enquanto um hook só altera o que renderiza. Ocultar uma linha com um hook a mantém no carrinho e no total; removê-la com uma ação a tira de verdade.

Como e quando ele carrega

O carrinho carrega em dois estágios, e o SDK foi construído para que você não precise pensar em ordem:

Um pequeno stub cria window.aftersell.cart imediatamente, então ele está sempre lá.
O SDK completo carrega logo depois e assume, atualizando o stub no lugar, de modo que uma referência capturada antes continua funcionando.

Isso dá a você duas categorias de chamada:

Chamadas de configuração: seguras imediatamente

configure(...), events.on(...) e toda chamada hooks.register*. São armazenadas em buffer antes do boot e reproduzidas em ordem assim que o SDK carrega. Coloque-as no topo do seu script.

Ações: aguarde ready()

Tudo sob actions.*. Execute-as dentro de ready() ou de um handler de evento. Chamadas cedo demais, elas avisam no console e não fazem nada, com segurança: as assíncronas ainda resolvem, então uma cadeia .then() não quebra.

// Set-up: fine at the top level, before the cart has loaded.
window.aftersell.cart.configure({ open_on_add_to_cart: 'always' });

window.aftersell.cart.events.on('item_added', (payload) => {
  console.log('Added', payload.item.title);
});

// Actions: wait until the cart is ready.
window.aftersell.cart.ready().then(() => {
  const state = window.aftersell.cart.actions.getCart();
  console.log(state.itemCount, 'items');
});

ready()

ready() retorna uma Promise que resolve assim que o primeiro carregamento do carrinho termina. Ela resolve tanto em falha quanto em sucesso, então um comprador com conexão instável nunca deixa seu script travado. Verifique se getCart() é null em vez de presumir que um carrinho chegou. Chamar ready() depois que o carrinho já carregou resolve imediatamente, então é seguro usá-la como um portão geral de “o carrinho existe agora” em qualquer lugar do seu código.

Você não precisa de ready() dentro de um handler de evento. Quando cart_loaded, cart_updated ou item_added dispara, o carrinho está carregado e é seguro chamar ações.

context

window.aftersell.cart.context contém dados do comprador renderizados pelo servidor, legíveis de forma síncrona, sem precisar de ready(). Use-o para ramificações por mercado ou país que precisam acontecer antes de o carrinho carregar.

Campo	Descrição	Disponível antes do boot
`shopify_market`	O mercado Shopify do comprador.	Sim
`customer_country`	Código de país de duas letras.	Sim
`customer_currency`	Código da moeda ativa.	Sim
`money_format`	O formato de dinheiro Shopify da loja.	Sim
`backend_url`	Host direto do backend, usado como fallback quando o app proxy não está configurado.	Sim
`storefront_access_token`	Token para chamadas à Storefront API.	Não — adicionado quando o carrinho inicializa

storefront_access_token é o único campo de context que o servidor não renderiza em cart.context. Ele é adicionado a context quando o carrinho inicializa, então lê-lo no topo do seu script retorna undefined. Aguarde window.aftersell.cart.ready() primeiro.

if (window.aftersell.cart.context.customer_country === 'CA') {
  // Canada-only behavior, decided before the cart loads.
}

Para mostrar configurações de bloco diferentes por mercado, país ou moeda, use as condições no editor do carrinho em vez disso. Nenhum script necessário. A UI completa de Conditions está disponível hoje em Rewards.

shadowRoot

O carrinho renderiza dentro de um shadow root, então document.querySelector não consegue ver nada dentro do drawer. Para alcançar um elemento no carrinho, consulte o shadow root:

const root = window.aftersell.cart.shadowRoot;
const button = root?.querySelector('.cart-external-checkout-button');

Mire nas mesmas classes públicas cart-external-* que o Custom CSS usa. Esses são os pontos de apoio suportados. As gêmeas cart-internal-* são o encanamento interno do carrinho, então consulte as externas.

Recorra ao shadow root somente quando nenhum bloco, configuração ou hook resolver. Um hook sobrevive a um redesign do carrinho; uma consulta ao DOM é problema do seu código manter.

O shadow root só existe depois que o carrinho inicializou, então leia-o dentro de ready() ou de um handler de evento, e não no topo do seu script.

Depuração

Um script quebrado nunca deve derrubar o adicionar ao carrinho ou o drawer, então o SDK contém as falhas em vez de deixá-las se propagar. Onde uma falha aparece depende do que quebrou:

O que falhou	Onde aparece
Seu script lançou um erro no nível superior	`console.error`, indicando a linha e o que nunca executou
Um handler de evento lançou um erro	`console.error`; os outros handlers ainda executam
Um hook lançou um erro	Silencioso. Vai para o canal de debug abaixo
Uma ação executou antes de o carrinho carregar	`console.warn`; a chamada não faz nada

Quando seu script lança um erro

Um script personalizado para no primeiro erro, então todo configure, events.on e hooks.register* abaixo daquela linha nunca executa. O carrinho diz isso explicitamente:

[aftersell-cart] Initialization script error on line 12 — 4 more line(s) did not run;
any configure/events/hooks below are unregistered.

Essa é a mensagem a procurar quando um handler que você com certeza registrou nunca dispara: ele provavelmente nunca foi alcançado. O número da linha é a instrução de nível superior onde a execução parou, não a função interna que lançou o erro, e ele é omitido em vez de adivinhado se a stack do navegador não for utilizável. Seus scripts também executam com seus próprios nomes de arquivo, então aparecem como aftersell-cart-init.js e aftersell-cart-cart-update.js no DevTools. Você pode abri-los no painel Sources e definir breakpoints como em qualquer outro arquivo.

O canal de debug

As falhas de hooks são deliberadamente mantidas fora do console para que os compradores nunca as vejam. Elas vão para cá em vez disso:

// After reproducing the problem, inspect what was swallowed:
window.aftersellCartDebugEvents.filter((entry) => entry.level === 'ERROR');

// Or watch them live:
window.addEventListener('aftersell-cart-debug', (event) => console.log(event.detail));

Para onde ir a seguir

Configure

Toda opção, com um exemplo de cada.

Events

Todo evento, quando dispara e o que não fazer em um handler.

Actions

Toda ação, com um snippet de cada.

Hooks

Todo hook, e como os registros se compõem.

Cart object

O formato do carrinho e de suas linhas.

Use cases

Soluções completas e executáveis para pedidos comuns.

Primeiros passos

Página inicial

Melhores práticas

Upsells pós-compra

Carrinho

Upsells no checkout (Shopify Plus)

Página de agradecimento

Upsells na página de produto

Rokt Thanks

Estratégias

Análises e rastreamento

Integrações

Aftersell MCP

Faturamento e conta

Solução de problemas

O ponto de entrada global

Configure

Events

Actions

Hooks

Eventos, ações ou hooks?

Como e quando ele carrega

Chamadas de configuração: seguras imediatamente

Ações: aguarde ready()

ready()

context

shadowRoot

Depuração

Quando seu script lança um erro

O canal de debug

Para onde ir a seguir

Configure

Events

Actions

Hooks

Cart object

Use cases

​O ponto de entrada global

Configure

Events

Actions

Hooks

​Eventos, ações ou hooks?

​Como e quando ele carrega

Chamadas de configuração: seguras imediatamente

Ações: aguarde ready()

​ready()

​context

​shadowRoot

​Depuração

​Quando seu script lança um erro

​O canal de debug

​Para onde ir a seguir

Configure

Events

Actions

Hooks

Cart object

Use cases

O ponto de entrada global

Eventos, ações ou hooks?

Como e quando ele carrega

ready()

context

shadowRoot

Depuração

Quando seu script lança um erro

O canal de debug

Para onde ir a seguir