Visão Geral

Permite configurar o comportamento de registro das UTMs (parâmetros de rastreamento de URL) no fechamento do pedido.

• Comportamento First Click: O sistema persistia a primeira UTM que trouxe o cliente, ignorando novas UTMs em sessões subsequentes caso já houvesse um registro.
• Comportamento Last Click: O sistema passa a atualizar os metadados do carrinho sempre que uma nova UTM é detectada, garantindo que a conversão seja atribuída à última origem de tráfego.

Objetivo: Permitir que a loja configure qual modelo de atribuição deseja utilizar.

Pré-requisitos

Certifique-se de que o ambiente de desenvolvimento esteja atualizado com a versão mais recente do SDK do Storefront que contenha suporte ao método getWithMetadata.

Alterações Técnicas Necessárias

Para habilitar a funcionalidade, as seguintes alterações devem ser realizadas no código do template da loja (Storefront).

Atualização da Query GraphQL (mini_cart.graphql)

É necessário buscar os metadados atuais do carrinho para comparar com os novos cookies de UTM.

Na query utilizada pelo componente de Mini Cart (geralmente mini_cart.graphql), adicione o campo metadata no retorno:

query MiniCart {
  checkout {
    # ... outros campos existentes
    metadata {
      key
      value
    }
  }
}

Utilização do SDK (getWithMetadata)

No fluxo de verificação do carrinho ou checkout, utilize a nova função do SDK para obter o objeto completo do checkout, incluindo os metadados.

const checkout = await client.checkout.getWithMetadata();

A resposta esperada conterá o array de metadados (utmSource, utmMedium, etc.), conforme imagem de referência:

metadata: [{ key: "utmSource", value: "teste" }, { key: "utmMedium", value: "teste2" }]

Atualização da Função addUtmMetadata

A função responsável por adicionar as UTMs ao carrinho deve ser refatorada para aceitar um parâmetro de configuração (flag) que define o comportamento desejado.

Lógica a ser implementada:

1. A função deve receber um parâmetro booleano, por exemplo: lastClick.
2. Se lastClick for true:

• Verificar se existem metadados de UTM no carrinho (obtidos via SDK/GraphQL).
• Comparar com as UTMs presentes nos cookies atuais do navegador.

Ação: Se os valores forem diferentes, atualizar os metadados do carrinho com os valores do cookie (sobrescrevendo o anterior).

3. Se lastClick for false (Comportamento Padrão):

• Manter a lógica original: Apenas adicionar a UTM ao carrinho se não houver nenhuma registrada. Ignorar novas UTMs se já existirem dados.

Pseudo-código da lógica:

function addUtmMetadata(cookieUtm, cartMetadata, lastClick = false) {
    const hasCartUtm = cartMetadata && cartMetadata.length > 0;

    // Cenário 1: Carrinho vazio de UTMs -> Adiciona sempre
    if (!hasCartUtm) {
        return updateCartMetadata(cookieUtm);
    }

    // Cenário 2: Last Click Ativo -> Verifica diferença e atualiza
    if (lastClick && hasCartUtm) {
        if (cookieUtm.source !== cartMetadata.source) {
             return updateCartMetadata(cookieUtm);
        }
    }

    // Cenário 3: Last Click Inativo (First Click) -> Não faz nada se já existir
    return;
}

Configuração da Loja

Recomenda-se criar uma constante de configuração no projeto ou utilizar uma variável de ambiente no front-end.

Exemplo em um arquivo de configuração:

export const STORE_CONFIG = {
  // ... outras configs
  USE_LAST_CLICK_ATTRIBUTION: true // Defina como false para manter o legado
};

Referência

Para consulta de código funcional, verifique as alterações realizadas no MR https://git.fbits.net/stores/awake/-/merge_requests/85