> ## 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.

# Como usar links UTM direto para o checkout

> Aprenda a acionar funis pós-compra usando parâmetros UTM, incluindo a configuração de links direto para o checkout

O Aftersell permite acionar funis com base em parâmetros UTM, um recurso opcional voltado especificamente para casos de uso avançados. Você pode configurar seu funil para ser ativado quando um cliente visita seu site com uma query string UTM específica.

Essa configuração é opcional e normalmente necessária apenas para necessidades avançadas de rastreamento, como links direto para o checkout ou ofertas específicas de campanha.

<div id="how-utm-triggers-work">
  ## Como funcionam os gatilhos UTM
</div>

Os gatilhos UTM permitem exibir funis pós-compra específicos com base em parâmetros UTM na URL. Isso é útil para:

* **Ofertas específicas de campanha** - Exiba upsells diferentes de acordo com a campanha de marketing
* **Links direto para o checkout** - Acione funis quando os clientes pulam a vitrine da loja
* **Atribuição de canal** - Personalize ofertas com base na origem do tráfego (e-mail, redes sociais, anúncios)
* **Testes A/B** - Teste ofertas diferentes para variações diferentes de campanha

<div id="quick-start-basic-utm-trigger-setup">
  ## Início rápido: configuração básica de gatilho UTM
</div>

Para visitas padrão à vitrine da loja (não direto para o checkout), você pode configurar gatilhos UTM usando o app embed do Aftersell. Para ver como começar rapidamente com gatilhos UTM, confira este vídeo:

<iframe src="https://go.screenpal.com/player/cOfD38nOD9i" title="How to set up UTM Triggers" allowFullScreen style={{ width: '100%', aspectRatio: '16/9', borderRadius: '12px' }} />

<div id="enable-the-utm-app-embed">
  ### Ative o app embed de UTM
</div>

Para rastrear parâmetros UTM nas páginas da vitrine da loja:

1. No seu admin da Shopify, vá em **Online Store > Themes**
2. Clique em **Customize** no seu tema ativo
3. No editor de tema, clique no ícone de **App embeds** (peça de quebra-cabeça) na barra lateral esquerda
4. Encontre **Aftersell UTM Tracker** e **ative** o botão
5. Clique em **Save**

Depois de ativado, o Aftersell capturará automaticamente os parâmetros UTM quando os clientes visitarem sua vitrine com links UTM.

<div id="configure-utm-triggers-in-your-funnel">
  ### Configure gatilhos UTM no seu funil
</div>

Depois de ativar o app embed:

1. Vá em **Post-purchase Funnels** no admin do Aftersell
2. Crie ou edite um funil
3. Na seção **Triggers**, adicione um gatilho de **UTM Parameter**
4. Configure o parâmetro UTM e o valor que você quer corresponder
5. Salve seu funil

<div id="supported-utm-parameters">
  ## Parâmetros UTM compatíveis
</div>

O Aftersell é compatível com os seguintes parâmetros UTM padrão:

* `utm_source` - Identifica a origem do tráfego (por exemplo, google, newsletter, facebook)
* `utm_medium` - Identifica o meio de marketing (por exemplo, email, cpc, social)
* `utm_campaign` - Identifica a campanha específica (por exemplo, spring\_sale, product\_launch)
* `utm_term` - Identifica palavras-chave de busca paga (por exemplo, running+shoes)
* `utm_content` - Diferencia conteúdos ou links semelhantes (por exemplo, banner\_ad, text\_link)
* `utm_id` - Identifica o ID da campanha (por exemplo, campaign\_123)

Todos os seis parâmetros são rastreados e podem ser usados para acionar funis.

<div id="partial-field-matching">
  ## Correspondência parcial de campos
</div>

Ao configurar gatilhos UTM, o Aftersell oferece suporte a **correspondência parcial** para valores de parâmetros UTM. Isso significa:

* ✅ **Valor do gatilho:** `spring` → **Corresponde a:** `spring_sale`, `spring_2026`, `early_spring`
* ✅ **Valor do gatilho:** `email` → **Corresponde a:** `email_newsletter`, `promotional_email`
* ✅ **Valor do gatilho:** `sale` → **Corresponde a:** `spring_sale`, `flash_sale`, `sale_2026`

Essa flexibilidade permite criar gatilhos mais amplos que correspondem a múltiplas variações de campanha sem precisar criar gatilhos separados para cada uma.

**Exemplo:** Se você definir um gatilho para `utm_campaign` contendo `sale`, ele corresponderá a qualquer campanha com "sale" no nome, como `spring_sale`, `summer_sale` ou `flash_sale_2026`.

<div id="direct-to-checkout-utm-links">
  ## Links UTM direto para o checkout
</div>

A configuração básica mostrada no vídeo acima **não** oferece suporte a links que enviam os clientes **diretamente para o checkout**. Por padrão, o Aftersell só consegue detectar parâmetros UTM nas páginas da vitrine da loja. Isso ocorre porque ele depende de um theme app embed, que funciona apenas nas páginas da vitrine e não no checkout nem na página de agradecimento.

<div id="enable-utm-tracking-on-checkout-pages">
  ### Ative o rastreamento de UTM nas páginas de checkout
</div>

Para rastrear parâmetros UTM na página de checkout (para links direto para o checkout), você precisa **adicionar um Shopify Pixel** à sua loja.

⚠️ **Limitações importantes:**

* Essa configuração exige que o visitante tenha um **token de carrinho** quando chegar ao checkout por um link UTM. Sem um token de carrinho, os dados de UTM não serão capturados.
* **Os métodos de checkout expresso (Shop Pay, Apple Pay, Google Pay) não são compatíveis** porque eles pulam o carrinho e não geram um token de carrinho. Clientes que usam checkout expresso não acionarão funis baseados em UTM.

<div id="setting-up-the-shopify-pixel">
  ### Configurando o pixel da Shopify
</div>

Siga estas instruções passo a passo para configurar o rastreamento de UTM direto para o checkout:

1. No seu admin da Shopify, vá em **Settings > Customer Events**.
2. Clique em **Add Custom Pixel** e dê o nome que preferir.
3. No menu suspenso **Permission**, selecione **Analytics**. Essa é a única permissão necessária.
4. No menu suspenso **Data Sale**, você pode escolher **Data collected does not qualify as data sale**. O Aftersell mantém todos os dados coletados privados e nunca os compartilha com ninguém além de você.
5. No editor de código que aparecer, cole o código fornecido abaixo.
6. Clique em **Save** e depois em **Connect**.

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
/**  
 * IMPORTANT: This pixel can only fire on sessions where the  
 * customer has a cart object, otherwise it will be skipped.  
 * For example, clicking "Buy Now" on a product page skips the cart,  
 * going directly to checkout.  
**/  
function processData({event, cartToken}) {  
  // TODO: Edit MYSHOPIFY_DOMAIN to your domain. E.g.  
  // const MYSHOPIFY_DOMAIN = 'example-store.myshopify.com';  
  const MYSHOPIFY_DOMAIN = '';  
  
  const enableDebug = false;  
  
  // DO NOT EDIT PAST HERE  
  const SESSION_STORAGE_KEY = 'as-customer-trigger-data';  
  const HOST = 'https://start.aftersell.app';  
  
  if (!MYSHOPIFY_DOMAIN) {  
    if (enableDebug) {  
      console.log("UTM pixel didn't fire because of missing Shopify domain");  
    }  
    return;  
  }  
  if (!cartToken) {  
    if (enableDebug) {  
      console.log("UTM pixel didn't fire because of missing cart token");  
    }  
  }  
    
  let existingCustomerData = null;  
  try {  
      existingCustomerData = JSON.parse(  
          sessionStorage.getItem(SESSION_STORAGE_KEY) || 'null'  
      );  
  } catch (ignore) {  
    if (enableDebug) {  
      console.log("UTM pixel didn't fire because malformed user data json");  
    }  
  }  
    
  const allowedUrlParams = [  
        'utm_source',  
        'utm_medium',  
        'utm_campaign',  
        'utm_term',  
        'utm_id',  
        'utm_content',  
    ];  
    
  const searchParams = new URLSearchParams(event.context.window.location.search);  
  let hasCustomerData = false;  
  const customerData = {};  
  for (const param of allowedUrlParams) {  
    const paramValue = searchParams.get(param) || existingCustomerData?.[param];  
    if (paramValue) {  
        hasCustomerData = true;  
        customerData[param] = paramValue;  
    }  
  }  
  
  if (hasCustomerData) {  
    sessionStorage.setItem(SESSION_STORAGE_KEY, JSON.stringify(customerData));  
  
    const postBody = {  
      shop: MYSHOPIFY_DOMAIN,  
      cartToken,  
      checkoutToken: event.data.checkout.token ?? undefined,  
      customerTriggerData: customerData,  
    };  
  
    if (enableDebug) {  
      console.log("UTM pixel fired with the following data:", postBody);  
    }  
      
    fetch(`\${HOST}/api/v1/storefrontSessions`, {  
        method: 'POST',  
        headers: {  
            'Content-Type': 'application/json',  
        },  
        body: JSON.stringify(postBody),  
    });  
  } else {  
    if (enableDebug) {  
      console.log("UTM pixel didn't fire because there was no data to send");  
    }  
  }  
}  
  
analytics.subscribe('checkout_started', (event) => {  
   // minimum realistic time between adding item to cart and clicking checkout  
    const COOKIE_POLLING_INTERVAL_MS = 500;  
  
    let currentCookieValue = getCookieValue({ cookie: document.cookie, cookieName: 'cart' });  
    processData({event, cartToken: currentCookieValue});  
  
    setInterval(() => {  
        const newCookieValue = getCookieValue({ cookie: document.cookie, cookieName: 'cart' });  
        if (newCookieValue !== currentCookieValue) {  
            currentCookieValue = newCookieValue;  
            processData({event, cartToken: newCookieValue});  
        }  
    }, COOKIE_POLLING_INTERVAL_MS);  
});  
  
function getCookieValue({ cookie, cookieName }) {  
    const cartCookieRegex = new RegExp(`^\${cookieName}=`);  
    const cartCookie = cookie  
        .split(';')  
        .map((val) => val.trim())  
        .find((val) => cartCookieRegex.test(val));  
    if (!cartCookie) return null;  
    const cartCookieValue = cartCookie.replace(`\${cookieName}=`, '');  
    return cartCookieValue;  
}
```

**Observações importantes de configuração:**

* **Edite `MYSHOPIFY_DOMAIN`:** Você deve substituir a string vazia pelo domínio myshopify.com da sua loja (por exemplo, `'example-store.myshopify.com'`)
* **Ative o modo de depuração (opcional):** Defina `enableDebug = true` para ver logs no console para solução de problemas
* **Parâmetros compatíveis:** O pixel rastreia todos os seis parâmetros UTM padrão listados no array `allowedUrlParams`

<div id="testing-your-utm-trigger-setup">
  ## Testando sua configuração de gatilho UTM
</div>

Depois de configurar os gatilhos UTM, use esta lista de verificação para confirmar que tudo está funcionando corretamente:

<div id="for-storefront-utm-tracking-app-embed">
  ### Para rastreamento de UTM na vitrine (app embed)
</div>

* ✅ **App embed ativado:** Verifique se o app embed Aftersell UTM Tracker está ativado nas configurações do seu tema
* ✅ **URL de teste:** Visite sua loja com um parâmetro UTM (por exemplo, `yourstore.com?utm_campaign=test`)
* ✅ **Conclua a compra:** Adicione um produto ao carrinho e finalize o checkout
* ✅ **Verifique o funil:** Confirme que o funil correto aparece na página de agradecimento
* ✅ **Order browser:** Confira o Aftersell Order Browser para confirmar que o gatilho UTM foi detectado

<div id="for-direct-to-checkout-utm-tracking-shopify-pixel">
  ### Para rastreamento de UTM direto para o checkout (pixel da Shopify)
</div>

* ✅ **Pixel instalado:** Verifique se o pixel personalizado está salvo e conectado em Settings > Customer Events
* ✅ **Domínio configurado:** Confirme que `MYSHOPIFY_DOMAIN` está definido corretamente no código do pixel
* ✅ **Token de carrinho presente:** Garanta que o cliente tenha itens no carrinho antes de ir para o checkout (obrigatório para o rastreamento)
* ✅ **URL de teste:** Use um link direto para o checkout com parâmetros UTM (por exemplo, `yourstore.com/checkout?utm_campaign=test`)
* ✅ **Conclua a compra:** Finalize o processo de checkout
* ✅ **Verifique o funil:** Confirme que o funil correto aparece na página de agradecimento
* ✅ **Order browser:** Confira o Aftersell Order Browser para confirmar que o gatilho UTM foi detectado
* ⚠️ **Checkout expresso:** Lembre-se de que Shop Pay, Apple Pay e Google Pay NÃO funcionam com gatilhos UTM

<div id="troubleshooting-tips">
  ### Dicas de solução de problemas
</div>

Se os gatilhos UTM não estiverem funcionando:

1. **Ative o modo de depuração:** Defina `enableDebug = true` no código do pixel e verifique o console do navegador em busca de mensagens de erro
2. **Verifique o token de carrinho:** Garanta que os clientes tenham itens no carrinho antes de chegar ao checkout (o pixel exige token de carrinho)
3. **Verifique a configuração do gatilho:** Confirme que o parâmetro UTM e o valor no gatilho do seu funil correspondem aos parâmetros da URL
4. **Teste a correspondência parcial:** Lembre-se de que os gatilhos usam correspondência parcial - `sale` corresponderá a `spring_sale`, `flash_sale`, etc.
5. **Verifique a prioridade dos funis:** Se vários funis corresponderem, apenas o funil de maior prioridade será exibido
6. **Revise o Order Browser:** Use o Aftersell Order Browser para ver quais gatilhos foram acionados em cada pedido

<div id="best-practices-for-utm-triggers">
  ## Boas práticas para gatilhos UTM
</div>

* **Use nomenclatura consistente:** Estabeleça uma convenção de nomenclatura para seus parâmetros UTM (por exemplo, `utm_campaign=email_spring_2026`)
* **Aproveite a correspondência parcial:** Use valores de gatilho mais amplos para corresponder a múltiplas variações de campanha
* **Teste antes de lançar:** Sempre teste seus links UTM e gatilhos antes de enviá-los aos clientes
* **Documente suas campanhas:** Mantenha um registro de quais parâmetros UTM você está usando em cada campanha
* **Combine com outros gatilhos:** Use gatilhos UTM junto com gatilhos de produto ou de valor do pedido para uma segmentação mais precisa
* **Monitore o desempenho:** Verifique regularmente o Order Browser para ver quais campanhas UTM estão gerando mais upsells