Scripts personalizados

Os scripts personalizados permitem executar seu próprio JavaScript no carrinho usando o Cart SDK. Adicione-os no Cart Editor em Cart settings → Custom script, onde um dropdown alterna entre dois slots: Initialization e On cart update. Escreva JavaScript puro nesses editores, sem tags <script>. On cart update tem uma ação Reset to default que restaura seu template inicial; Initialization não tem, então guarde sua própria cópia antes de limpá-lo.

Muito do que os lojistas costumavam fazer por script agora é uma configuração nativa. Confira Antes de escrever um script primeiro: uma configuração continua funcionando através de redesigns do carrinho, e seu script pode não continuar.

Qual slot usar

	Initialization	On cart update
Executa	Uma vez, quando o carrinho carrega.	A cada alteração do carrinho após o primeiro carregamento.
Você escreve	O script inteiro.	Apenas o corpo do handler. O wrapper `cart_updated` é travado.
Use para	Registrar comportamento uma única vez: `configure`, `events.on`, `hooks.register*`.	Regras que precisam ser reavaliadas contra o conteúdo atual do carrinho.
Exemplo	Ocultar linhas de brinde grátis com um line transform.	Manter um brinde grátis sincronizado com um limite de gasto.

Initialization

O script Initialization executa uma vez quando o carrinho carrega. É o seu ponto de entrada para preparar tudo: configurar o comportamento do carrinho, assinar eventos e registrar hooks. O SDK está disponível como window.aftersell.cart. Chamadas de configuração que você faz aqui (configure(...), events.on(...), hooks.*) são seguras de chamar no topo do script mesmo antes de o carrinho ter inicializado completamente; elas são armazenadas em buffer e aplicadas quando ele inicializa. Ações que leem ou alteram o carrinho (como addItem ou getCart) devem rodar dentro de ready() ou de um handler de evento. O slot começa com três exemplos comentados — abrir o drawer a cada adição, reagir a cart_loaded e ocultar linhas de brinde grátis — então um script Initialization intocado não faz nada. Descomente um para testar, ou substitua-os. O formato natural para este slot é um registro único sem eventos envolvidos: registre o comportamento uma vez e deixe o carrinho aplicá-lo dali em diante. Ocultar linhas de brinde grátis do drawer, sem alterar o total, é o exemplo fornecido disso:

window.aftersell.cart.hooks.registerLineTransform((line) => {
  if (line.finalLinePrice === 0) line.setHidden(true);
});

registerLineTransform executa para cada linha conforme ela é renderizada, e setHidden é apenas de exibição, então a linha permanece no carrinho e ainda conta para o total, ela só não aparece no drawer. Veja Ocultar e rotular linhas do carrinho para mais do que um transform pode fazer. Ações que leem o carrinho vão dentro de ready():

window.aftersell.cart.ready().then(() => {
  const state = window.aftersell.cart.actions.getCart();
  console.log('Cart loaded with', state.itemCount, 'items');
});

Acessar o DOM do carrinho exige a mesma espera, e exige shadowRoot: o carrinho é renderizado dentro de um shadow root, então document.querySelector não consegue ver nada no drawer.

Vai ramificar por mercado, país ou moeda antes de o carrinho carregar? Leia context em vez disso. Ele está disponível de forma síncrona, sem precisar de ready(), então você pode nem registrar handlers para compradores aos quais uma regra não se aplica.

On cart update

O script On cart update executa toda vez que o carrinho muda. É um wrapper travado em torno de uma assinatura de cart_updated, então você edita apenas o corpo, e seu código recebe o cart atualizado. Este slot é para regras que precisam ser reavaliadas a cada mudança do carrinho. Um limite de brinde grátis é o caso clássico (gaste $75, ganhe uma sacola grátis), porque a resposta depende do conteúdo atual e nada mais consegue avisar quando ele muda:

window.aftersell.cart.events.on('cart_updated', (cart) => {
  const GIFT_VARIANT_ID = 1234567890;
  const THRESHOLD = 7500;   // $75.00, in cents

  let giftLine = null;
  let subtotal = 0;
  (cart.items ?? []).forEach((line) => {
    if (line.variantId === GIFT_VARIANT_ID) giftLine = line;
    else subtotal += line.finalLinePrice;   // the gift itself never counts toward the threshold
  });

  const shouldHaveGift = subtotal >= THRESHOLD;
  const hasGift = Boolean(giftLine);

  // Bail when the cart already matches. This is the part that matters: adding or
  // removing an item fires cart_updated again, so without this check the handler
  // re-enters itself forever.
  if (shouldHaveGift === hasGift) return;

  if (shouldHaveGift) window.aftersell.cart.actions.addItem(GIFT_VARIANT_ID, 1);
  else window.aftersell.cart.actions.removeItem(giftLine.key);
});

Mantendo o carrinho em um estado desejado

A linha if (shouldHaveGift === hasGift) return; é o que torna isso seguro, e ela se generaliza para todo script que mantém o carrinho em um estado desejado. Este slot tanto reage a mudanças do carrinho quanto as causa, então cada addItem ou removeItem o reexecuta. Descreva o estado que você quer, compare com o estado que você tem e retorne cedo quando eles já concordam, para que o handler convirja depois de uma passada em vez de entrar em loop. Veja as duas regras para a versão sem proteção a evitar e por que o payload é somente leitura. Em uma loja mais lenta, também vale manter uma flag de operação em andamento no nível do módulo, para que duas mudanças rápidas não possam ambas iniciar uma adição antes de a primeira ser concluída.

cart_updated dispara apenas em mudanças depois do primeiro carregamento (timing de eventos), então um script neste slot não vai reconciliar um carrinho que já se qualifica quando a página carrega. Para uma versão que trata os dois casos, assine cart_loaded e cart_updated com a mesma função a partir do slot Initialization. Veja Adicionar automaticamente um brinde grátis em um limite.

Quando um script quebra

Cada slot roda no seu próprio sandbox, então um script Initialization quebrado não impede o On cart update de rodar, e nenhum dos dois pode quebrar o carrinho em si. Dentro de um slot, porém, a execução para no primeiro erro. Tudo abaixo daquela linha é pulado, o que significa que qualquer configure, events.on ou hooks.register* mais abaixo nunca é registrado. Essa é a explicação usual para “meu handler nunca dispara” quando o código parece correto. O carrinho indica a linha com falha no console do navegador, e cada slot roda sob seu próprio nome de arquivo (aftersell-cart-init.js e aftersell-cart-cart-update.js), então você pode abrir qualquer um pelo painel Sources do DevTools e definir breakpoints. Veja Depuração para as mensagens exatas e para o canal de debug que captura falhas de hooks mantidas fora do console. Como cart_loaded é reproduzido para assinantes tardios, a ordem de registro nunca importa. A estrutura mais segura é registrar tudo primeiro e fazer o trabalho arriscado dentro dos handlers, onde um throw fica isolado naquele handler.

Por onde continuar

Cart SDK: os scripts personalizados são a forma de executar código do SDK. Veja as referências de configure, eventos, ações e hooks para a superfície completa, o objeto de carrinho para a estrutura do que os handlers recebem, e os casos de uso para snippets prontos.
Blocos Custom code: para adicionar marcação ao carrinho. Note que o modo HTML do bloco Custom code não executa JavaScript; use scripts personalizados (ou o modo React do bloco) para lógica.

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

Qual slot usar

Initialization

On cart update

Mantendo o carrinho em um estado desejado

Quando um script quebra

Por onde continuar

​Qual slot usar

​Initialization

​On cart update

​Mantendo o carrinho em um estado desejado

​Quando um script quebra

​Por onde continuar

Qual slot usar

Initialization

On cart update

Mantendo o carrinho em um estado desejado

Quando um script quebra

Por onde continuar