Agrupar linhas de bundle de outro app

A maioria dos apps de bundle monta um bundle adicionando cada componente como sua própria linha do carrinho e depois vinculando-as com line item properties de design próprio. A Ajax API da Shopify entrega essas linhas ao carrinho sem nenhuma indicação de que elas pertencem umas às outras, então por padrão o drawer mostra um bundle de três partes como três itens sem relação, cada um com seu próprio preço e seletor de quantidade. setInternalProperties é como você diz ao carrinho que elas são uma coisa só.

Como o agrupamento funciona

O carrinho agrupa linhas com base em duas propriedades canônicas. Ele não conhece os nomes de propriedade do seu app de bundle, então você traduz: leia o que quer que o app escreveu e carimbe o par canônico em cada linha com um line transform.

Propriedade	Obrigatória	Valor
`_aftersell_cart_bundle_id`	Sim	Um ID compartilhado. Toda linha com o mesmo ID é um bundle.
`_aftersell_cart_bundle_role`	Não	Defina como `parent` na linha que o bundle deve exibir.

Elas passam por setInternalProperties, não pela Shopify. Elas são uma camada só de renderização: nunca chegam a properties, nunca são persistidas na Shopify e nunca aparecem no pedido.

Passo 1: descubra o que seu app escreve

Cada app de bundle nomeia suas propriedades de forma diferente, então comece olhando um carrinho real. Adicione um bundle na sua loja e execute isto no console do navegador:

window.aftersell.cart.actions.getCart().items.forEach((line) => {
  console.log(line.title, line.properties);
});

Você está procurando uma propriedade compartilhada entre as linhas do bundle. Geralmente é uma propriedade oculta (o nome começa com _) contendo um ID, uma referência ou o nome do bundle. Algo como _bundle_id, _bundle_ref ou _parent_id é típico. Anote a chave exata e se uma linha está marcada como o produto principal.

Passo 2: mapeie para as propriedades canônicas

Cole em Cart settings → Custom script → Initialization, substituindo os nomes de propriedade pelos que você encontrou:

window.aftersell.cart.hooks.registerLineTransform((line) => {
  const props = line.properties;
  if (!props) return;

  const bundleId = props._bundle_id;
  if (!bundleId) return;

  line.setInternalProperties({
    _aftersell_cart_bundle_id: bundleId,
    // Mark the main product so the bundle renders under it.
    _aftersell_cart_bundle_role: props._bundle_role === 'main' ? 'parent' : 'child',
  });
});

Essa é a integração inteira. Assim que duas ou mais linhas compartilham um ID, o carrinho as agrupa em um bundle.

Se seu app não marca um produto principal, deixe _aftersell_cart_bundle_role de fora por completo. O carrinho escolhe uma âncora para você.

O que você ganha

Uma vez que as linhas estão agrupadas, a linha âncora carrega um objeto bundle e o drawer renderiza o bundle como um único item:

Os filhos ficam aninhados sob a âncora em vez de aparecer como linhas separadas.
A quantidade é atômica. Alterar a quantidade do bundle escala todos os membros juntos, usando a proporção perAnchorQty de cada filho, então um bundle com dois de um componente mantém essa relação de dois para um.
A remoção é atômica. Remover o bundle remove todas as linhas membro em uma única requisição, em vez de deixar componentes órfãos para trás.
Uma única linha de preço. O que ela mostra segue a configuração de preço do bundle no bloco Cart items: o total de todos os membros, ou apenas o preço do produto principal.

Como a âncora é escolhida

A âncora é a linha que o bundle exibe. O carrinho a escolhe nesta ordem:

A linha com _aftersell_cart_bundle_role definido como parent.
Caso contrário, o membro de maior preço.
Caso contrário, o primeiro membro no carrinho.

O fallback por preço geralmente está certo, já que apps de bundle costumam colocar o desconto no produto principal. Defina o role explicitamente quando não estiver, por exemplo quando o produto principal é o item mais barato ou é grátis.

Regras que vale a pena conhecer

Um bundle precisa de pelo menos duas linhas. Uma única linha com um ID de bundle é deixada em paz e renderiza normalmente.
Bundles nativos da Shopify já são tratados. Linhas que a própria Shopify marca como componentizadas são ignoradas por este agrupamento e adaptadas automaticamente. Você só precisa disto para apps que adicionam linhas separadas.
O transform executa em toda renderização. Mantenha-o leve e livre de efeitos colaterais. Não chame ações nem faça fetch de dentro dele.
A mesclagem é aditiva. Suas propriedades se mesclam com quaisquer definidas por outro transform. Em um conflito genuíno pela mesma chave, o último transform registrado vence.
O agrupamento executa depois de ocultar e renomear, e antes da ordenação. Então uma linha que você oculta com setHidden nunca vira parte de um bundle, e um comparator vê a âncora, não os filhos.

Filhos agrupados saem de state.items. Uma vez que as linhas são agrupadas em um bundle, só a âncora aparece em getCart().items e nos payloads de evento; os filhos vão para anchor.bundle.children. Eles também deixam de contar para itemCount.O total do carrinho não é afetado, porque os totais vêm direto da Shopify. O agrupamento muda a apresentação, nunca o que o comprador paga.

Lendo um bundle de volta

window.aftersell.cart.events.on('cart_updated', (state) => {
  state.items.forEach((line) => {
    if (!line.bundle) return;
    console.log(line.title, 'is a bundle of', line.bundle.children.length, 'items:');
    line.bundle.children.forEach((child) => {
      console.log('  ', child.quantity, 'x', child.title);
    });
  });
});

Para agir sobre as linhas de um bundle, use bundle.memberKeys, que contém a key de cada membro, incluindo a âncora.

Usando para outras coisas

O agrupamento de bundle é para o que setInternalProperties foi construído, mas a camada é um canal geral para dados só de renderização que você deriva de uma linha. Qualquer coisa que você colocar lá é legível em line.internalProperties e em um bloco Custom code, sem tocar no carrinho real:

window.aftersell.cart.hooks.registerLineTransform((line) => {
  if (line.properties?._preorder_ship_date) {
    line.setInternalProperties({ _badge: `Ships ${line.properties._preorder_ship_date}` });
  }
});

Use-a quando o valor é derivado e só de exibição. Se o dado precisa sobreviver até o pedido, ele pertence a uma line item property real, definida com um input properties[...] oculto no formulário do produto para que chegue ao Shopify seja quem for que realize a adição.

Para onde ir a seguir

registerLineTransform: o hook pelo qual isto executa.
Cart object: o formato de bundle e seus filhos.
Cart items block: a configuração de preço do bundle.

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

Como o agrupamento funciona

Passo 1: descubra o que seu app escreve

Passo 2: mapeie para as propriedades canônicas

O que você ganha

Como a âncora é escolhida

Regras que vale a pena conhecer

Lendo um bundle de volta

Usando para outras coisas

Para onde ir a seguir

​Como o agrupamento funciona

​Passo 1: descubra o que seu app escreve

​Passo 2: mapeie para as propriedades canônicas

​O que você ganha

​Como a âncora é escolhida

​Regras que vale a pena conhecer

​Lendo um bundle de volta

​Usando para outras coisas

​Para onde ir a seguir

Como o agrupamento funciona

Passo 1: descubra o que seu app escreve

Passo 2: mapeie para as propriedades canônicas

O que você ganha

Como a âncora é escolhida

Regras que vale a pena conhecer

Lendo um bundle de volta

Usando para outras coisas

Para onde ir a seguir