Eventos

Eventos permitem executar código quando algo acontece no carrinho. Eles ficam em window.aftersell.cart.events. Assinar é uma chamada de configuração, então é seguro no topo do seu script, sem precisar esperar por ready().

Eventos disponíveis

Evento	Payload	Dispara quando
`cart_loaded`	`AftersellCart`	O carrinho carrega, uma vez por página.
`cart_updated`	`AftersellCart`	O conteúdo do carrinho muda, após o primeiro carregamento.
`item_added`	`{ item }`	Uma nova linha aparece no carrinho.
`item_removed`	`{ item }`	Uma linha desaparece do carrinho.
`cart_opened`	Nenhum	O drawer abre.
`cart_closed`	Nenhum	O drawer fecha.
`checkout`	Nenhum	O botão de checkout é clicado.

Assinando

events.on(event, handler) registra um handler e retorna uma função que cancela a assinatura:

const off = window.aftersell.cart.events.on('cart_updated', (state) => {
  console.log('Cart total is now', state.totalPrice);
});

// later, to stop listening:
off();

events.once(event, handler): dispara uma vez e cancela a si mesmo.
events.off(event, handler): remove um handler específico.

Um handler que lança um erro é isolado e registrado no console; os outros handlers ainda são executados.

As duas regras

Quase todo bug de evento tem origem em uma destas.

Não altere o carrinho a partir de `cart_updated` sem uma proteção

Alterar o carrinho dentro de um handler de cart_updated dispara cart_updated de novo. Se esse handler alterar o carrinho novamente, você tem um loop infinito. O comprador vê o carrinho oscilando enquanto a página martela o Shopify.

Nunca chame uma ação incondicionalmente a partir de cart_updated ou cart_loaded. Proteja-a com uma verificação do estado que você está prestes a criar, para que a segunda passagem não faça nada.

// ❌ Loops forever: every add triggers an update, which triggers another add.
window.aftersell.cart.events.on('cart_updated', (state) => {
  window.aftersell.cart.actions.addItem(GIFT_VARIANT_ID, 1);
});

// ✅ Guarded: once the gift is present, the condition is false and it stops.
window.aftersell.cart.events.on('cart_updated', (state) => {
  const hasGift = state.items.some((line) => line.variantId === GIFT_VARIANT_ID);
  if (state.totalPrice >= 5000 && !hasGift) {
    window.aftersell.cart.actions.addItem(GIFT_VARIANT_ID, 1);
  }
});

O carrinho oferece uma rede de segurança: uma atualização que produz um carrinho idêntico não emite nada, então uma rebusca que não muda nada não reinicia o ciclo. Isso protege você de loops acidentais sem efeito. Mas não protege de um handler que genuinamente altera o carrinho a cada vez.

Trate o payload como somente leitura

Todo handler de um mesmo evento recebe o mesmo objeto. Mutá-lo muda o que os handlers depois do seu veem, incluindo handlers de outros apps na loja.

// ❌ Corrupts the payload for every later handler.
window.aftersell.cart.events.on('cart_updated', (state) => {
  state.items = state.items.filter((line) => line.finalLinePrice > 0);
});

// ✅ Copy first.
window.aftersell.cart.events.on('cart_updated', (state) => {
  const paidItems = state.items.filter((line) => line.finalLinePrice > 0);
});

Para realmente alterar o carrinho, use uma ação. Para mudar como as linhas são renderizadas, use registerLineTransform.

cart_loaded

Dispara uma vez, quando o carrinho carrega pela primeira vez na página. O payload é o objeto de carrinho completo.

window.aftersell.cart.events.on('cart_loaded', (state) => {
  console.log('Page loaded with', state.itemCount, 'items');
});

Use para: qualquer coisa que precise rodar contra o estado inicial do carrinho, como reconciliar um brinde, inicializar um widget ou reportar o conteúdo do carrinho para analytics no carregamento da página. cart_loaded é reproduzido para assinantes atrasados. Se você assinar depois que o carrinho já carregou, seu handler é chamado imediatamente com o carrinho atual. A ordem de assinatura nunca importa, então você não precisa se preocupar se o seu script chegou antes do carrinho.

Lógica que precisa estar correta tanto no carregamento da página quanto em cada mudança posterior deve assinar ambos cart_loaded e cart_updated com a mesma função. Esse é o padrão para “manter X em sincronia com o carrinho”.

cart_updated

Dispara toda vez que o conteúdo do carrinho muda após o primeiro carregamento, seja pelo drawer, pelas suas próprias ações, pelo tema ou por outro app. O payload é o objeto de carrinho completo.

window.aftersell.cart.events.on('cart_updated', (state) => {
  document.querySelector('#my-total').textContent =
    window.aftersell.cart.actions.formatMoney(state.totalPrice);
});

Use para: manter algo fora do carrinho em sincronia, como um total personalizado, uma barra de progresso, um badge no header ou um evento de analytics a cada mudança. Uma atualização que produz um carrinho idêntico não emite nada. Reabrir o drawer, voltar para a aba ou uma rebusca que retorna o mesmo conteúdo não o disparam.

Releia as duas regras antes de chamar uma ação aqui dentro.

item_added

Dispara quando uma linha nova aparece no carrinho. O payload é { item }, onde item é a linha do carrinho.

window.aftersell.cart.events.on('item_added', (payload) => {
  myAnalytics.track('Added to cart', {
    id: payload.item.variantId,
    title: payload.item.title,
    quantity: payload.item.quantity,
  });
});

Use para: rastreamento de adição ao carrinho em uma ferramenta de analytics de terceiros. Este é o uso mais comum do SDK. Veja rastreando adições ao carrinho. Duas coisas a saber sobre como ele é derivado:

Uma mudança de quantidade não é uma adição. O carrinho detecta adições e remoções fazendo diff das linhas, não das quantidades. Um comprador subindo uma linha de 1 para 3 dispara cart_updated, não item_added. Se você precisa capturar aumentos de quantidade também, compare com o estado anterior em um handler de cart_updated.

Ele também não dispara para itens que já estavam no carrinho quando a página carregou; esses chegam via cart_loaded. Adicionar vários produtos distintos de uma vez dispara o evento uma vez por linha.

item_removed

Dispara quando uma linha desaparece do carrinho. O payload é { item }, a linha como estava logo antes de sumir, então você ainda pode ler seu key, variantId e title.

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

Use para: reverter algo que você fez na adição, como limpar uma flag, exibir novamente uma oferta que o comprador recusou ou reportar remoções para analytics. Mesma ressalva de item_added: reduzir uma quantidade sem chegar a zero não é uma remoção.

cart_opened e cart_closed

Disparam quando o drawer abre e fecha. Sem payload.

window.aftersell.cart.events.on('cart_opened', () => {
  myAnalytics.track('Cart viewed');
});

window.aftersell.cart.events.on('cart_closed', () => {
  document.body.classList.remove('cart-is-open');
});

Use para: rastreamento de visualizações, pausar um vídeo ou carrossel atrás do drawer, alternar uma classe na página. Nenhum dos dois dispara no carregamento inicial da página, apenas em uma abertura ou fechamento real.

checkout

Dispara quando o comprador clica no botão de checkout, imediatamente antes de o navegador navegar. Sem payload.

window.aftersell.cart.events.on('checkout', () => {
  myAnalytics.track('Checkout started');
});

Use para: rastreamento de intenção de checkout.

Você não pode cancelar o checkout a partir deste handler. O evento é uma notificação, não um portão; a navegação acontece independentemente do que seu código faz. Mantenha o handler rápido e síncrono: um await ou uma chamada de rede lenta pode não terminar antes de a página descarregar. Use navigator.sendBeacon para qualquer coisa que você precise enviar de forma confiável.

Ouvindo de fora do SDK

Todo evento também é despachado como um CustomEvent do DOM em window, então você pode escutar sem tocar em window.aftersell.cart. Isso é útil em um arquivo de tema, um app de terceiros ou um script que carrega independentemente do carrinho.

Evento do bus	Evento do DOM
`cart_loaded`	`aftersell:cart:cart-loaded`
`cart_updated`	`aftersell:cart:cart-updated`
`item_added`	`aftersell:cart:item-added`
`item_removed`	`aftersell:cart:item-removed`
`cart_opened`	`aftersell:cart:cart-opened`
`cart_closed`	`aftersell:cart:cart-closed`
`checkout`	`aftersell:cart:checkout`

Atenção à nomenclatura: o bus usa snake_case, os eventos do DOM usam kebab-case atrás de um prefixo aftersell:cart:.

window.addEventListener('aftersell:cart:cart-updated', (event) => {
  console.log('Cart total is now', event.detail.totalPrice);
});

O payload chega em event.detail e corresponde ao objeto de carrinho. Os eventos são despachados em window, então um listener em qualquer lugar da página os recebe. O carrinho é renderizado em um shadow root, mas a fronteira do shadow nunca está no caminho do evento. Cada despacho clona o payload, então um listener que muta event.detail não afeta ninguém mais, e um listener que lança um erro não perturba o SDK.

cart-loaded não é reproduzido no DOM. O bus reproduz cart_loaded para assinantes atrasados, mas esse caminho não passa pelo despacho no DOM, então window.addEventListener('aftersell:cart:cart-loaded') registrado depois que o carrinho já carregou nunca dispara. Se a ordem de carregamento do seu script não é garantida, use window.aftersell.cart.events.on('cart_loaded', …), que reproduz, ou escute também aftersell:cart:cart-updated.

Eventos padrão de carrinho do Shopify

Separadamente, o carrinho publica os eventos padrão de carrinho do Shopify em document sempre que altera o carrinho, para que o código do tema e outros apps possam reagir às mutações do Aftersell da mesma forma que reagem às do tema:

Evento	Payload na instância do evento
`shopify:cart:lines-update`	`action: 'add' \| 'update' \| 'remove'`, `context: 'cart' \| 'product'`, `lines`
`shopify:cart:note-update`	`context: 'cart'`, `note`
`shopify:cart:discount-update`	`discountCodes: [{ code }]`

O payload não está em event.detail. detail carrega apenas { source: 'aftersell' } — a tag que o carrinho usa para ignorar os próprios eventos em vez de entrar em loop. Tudo na tabela acima é atribuído diretamente ao objeto do evento, então leia event.action, não event.detail.action.

Cada evento também carrega uma promise que o Aftersell resolve quando a escrita subjacente é concluída, seguindo o padrão do Shopify — aguarde-a, não a resolva você. Eles são despachados em document e propagam (bubble), então um listener em window também os recebe.

Para onde ir agora

Objeto de carrinho: o formato completo dos payloads acima.
Ações: como alterar o carrinho a partir de um handler.
Hooks: para mudar como o carrinho renderiza, em vez de reagir a ele.
Casos de uso: rastreamento de analytics, brindes e outros exemplos completos.

Primeiros passos

Página inicial

Melhores práticas

Upsells pós-compra

Carrinho Aftersell

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

Eventos disponíveis

Assinando

As duas regras

Não altere o carrinho a partir de `cart_updated` sem uma proteção

Trate o payload como somente leitura

cart_loaded

cart_updated

item_added

item_removed

cart_opened e cart_closed

checkout

Ouvindo de fora do SDK

Eventos padrão de carrinho do Shopify

Para onde ir agora

​Eventos disponíveis

​Assinando

​As duas regras

​Não altere o carrinho a partir de cart_updated sem uma proteção

​Trate o payload como somente leitura

​cart_loaded

​cart_updated

​item_added

​item_removed

​cart_opened e cart_closed

​checkout

​Ouvindo de fora do SDK

​Eventos padrão de carrinho do Shopify

​Para onde ir agora

Eventos disponíveis

Assinando

As duas regras

Não altere o carrinho a partir de `cart_updated` sem uma proteção

Trate o payload como somente leitura

cart_loaded

cart_updated

item_added

item_removed

cart_opened e cart_closed

checkout

Ouvindo de fora do SDK

Eventos padrão de carrinho do Shopify

Para onde ir agora