Guia do desenvolvedor de comércio eletrônico (GA4)

Neste guia, descrevemos como implementar recursos de comércio eletrônico do Google Analytics 4 (GA4) usando o Gerenciador de tags do Google em um site.

O comércio eletrônico do GA4 permite que os dados de impressões, promoções, vendas e listas de produtos sejam enviados com vários eventos de comércio eletrônico sugeridos.

Você tem duas opções para ativar o comércio eletrônico na tela do editor de tags da interface da Web:

Implementar com a camada de dados (recomendado)
Implementar com uma variável JavaScript personalizada

Nessas seções, mostraremos como usar a camada de dados para medir as atividades de comércio eletrônico indicadas abaixo:

Impressões e visualizações da lista de itens/produtos
Cliques na lista de itens/produtos
Visualizações de detalhes de itens/produtos
Adições/remoções do carrinho
Visualizações/impressões da promoção
Cliques na promoção
Finalizações de compra
Compras
Reembolsos

Migração de objetos da camada de dados de comércio eletrônico legado

Quem já implementou o comércio eletrônico avançado para as propriedades da Web do Google Analytics e tem objetos de camada de dados, como 'impressions' e 'products', pode continuar a usá-los em vez das referências a 'items', como mostrado neste documento.

Como limpar o objeto de comércio eletrônico

Recomendamos usar o comando a seguir para limpar o objeto de comércio eletrônico antes de enviar um evento de comércio eletrônico para a camada de dados. Isso impedirá que vários eventos de comércio eletrônico em uma página afetem uns aos outros.

dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.

Medir impressões e visualizações da lista de itens/produtos

Para medir impressões e visualizações da lista de itens, envie uma lista desse tipo à camada de dados e colete um evento view_item_list com essas informações. No exemplo a seguir, suponha que os detalhes dos produtos exibidos em uma página sejam conhecidos quando a página é carregada.

// Measure product views / impressions
dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "view_item_list",
  ecommerce: {
    items: [
     {
       item_name: "Triblend Android T-Shirt",       // Name or ID is required.
       item_id: "12345",
       price: 15.25,
       item_brand: "Google",
       item_category: "Apparel",
       item_category2: "Mens",
       item_category3: "Shirts",
       item_category4: "Tshirts",
       item_variant: "Gray",
       item_list_name: "Search Results",
       item_list_id: "SR123",
       index: 1,
       quantity: 1
     },
     {
       item_name: "Donut Friday Scented T-Shirt",
       item_id: "67890",
       price: 33.75,
       item_brand: "Google",
       item_category: "Apparel",
       item_category2: "Mens",
       item_category3: "Shirts",
       item_category4: "Tshirts",
       item_variant: "Black",
       item_list_name: "Search Results",
       item_list_id: "SR123",
       index: 2,
       quantity: 1
     }]
  }
});

Configuração de tag para este exemplo:

Tipo de tag: evento do GA4
Nome do evento: view_item_list
Parâmetro do evento (nome – valor): 'items' – {{Ecommerce Items}}
Tipo de variável: camada de dados – 'ecommerce.items'
Acionador: "event" é igual a "gtm.dom"

Medir cliques na lista de itens/produtos

Para medir os cliques em listas de itens/produtos, envie um item à camada de dados e colete um evento select_item que representa o produto clicado, como neste exemplo:

/**
 * Call this function when a user clicks on a product link.
 * @param {Object} productObj An object that represents the product that is clicked.
 */
function onProductClick(productObj) {
  dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
  dataLayer.push({
    event: "select_item",
    ecommerce: {
      items: [{
        item_name: productObj.name, // Name or ID is required.
        item_id: productObj.id,
        item_brand: productObj.brand,
        item_category: productObj.category,
        item_category2: productObj.category_2,
        item_category3: productObj.category_3,
        item_category4: productObj.category_4,
        item_variant: productObj.variant,
        item_list_name: productObj.list_name,
        item_list_id: productObj.list_id,
        index: productObj.index,
        quantity: productObj.quantity,
        price: productObj.price
      }]
    }
  });
}

Configuração de tag para este exemplo:

Tipo de tag: evento do GA4
Nome do evento: select_item
Parâmetro do evento (nome – valor): 'items' – {{Ecommerce Items}}
Tipo de variável: camada de dados – 'ecommerce.items'
Acionador: "event" é igual a "select_item"

Medir visualizações e impressões de detalhes de itens/produtos

Para medir uma visualização dos detalhes do produto, envie uma lista de itens à camada de dados e colete um evento view_item com essas informações. No exemplo a seguir, suponha que os detalhes dos produtos exibidos em uma página sejam conhecidos no momento do carregamento da página.

// Measure a view of product details. This example assumes the detail view occurs on pageload,
dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "view_item",
  ecommerce: {
    items: [{
      item_name: "Donut Friday Scented T-Shirt", // Name or ID is required.
      item_id: "67890",
      price: 33.75,
      item_brand: "Google",
      item_category: "Apparel",
      item_category2: "Mens",
      item_category3: "Shirts",
      item_category4: "Tshirts",
      item_variant: "Black",
      item_list_name: "Search Results",  // If associated with a list selection.
      item_list_id: "SR123",  // If associated with a list selection.
      index: 1,  // If associated with a list selection.
      quantity: 1
    }]
  }
});

Configuração de tag para este exemplo:

Tipo de tag: evento do GA4
Nome do evento: view_item
Parâmetro do evento (nome – valor): 'items' – {{Ecommerce Items}}
Tipo de variável: camada de dados – 'ecommerce.items'
Acionador: "event" é igual a "gtm.dom"

Medir adições ou remoções de um carrinho de compras

Da mesma forma, para medir adições ou remoções de um carrinho de compras, você pode coletar um evento add_to_cart ou remove_from_cart com os itens adicionados ou removidos:

Adicionar um produto a um carrinho de compras

// Measure when a product is added to a shopping cart
dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "add_to_cart",
  ecommerce: {
    items: [{
      item_name: "Donut Friday Scented T-Shirt", // Name or ID is required.
      item_id: "67890",
      price: "33.75",
      item_brand: "Google",
      item_category: "Apparel",
      item_category2: "Mens",
      item_category3: "Shirts",
      item_category4: "Tshirts",
      item_variant: "Black",
      item_list_name: "Search Results",
      item_list_id: "SR123",
      index: 1,
      quantity: 2
    }]
  }
});

Configuração de tag para este exemplo:

Tipo de tag: evento do GA4
Nome do evento: add_to_cart
Parâmetro do evento (nome – valor): 'items' – {{Ecommerce Items}}
Tipo de variável: camada de dados – 'ecommerce.items'
Acionador: "event" é igual a "add_to_cart"

Remover um produto do carrinho de compras

// Measure the removal of a product from a shopping cart.
dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "remove_from_cart",
  ecommerce: {
    items: [{
      item_name: "Donut Friday Scented T-Shirt", // Name or ID is required.
      item_id: "67890",
      price: 33.75,
      item_brand: "Google",
      item_category: "Apparel",
      item_variant: "Black",
      item_list_name: "Search Results",  // If associated with a list selection.
      item_list_id: "SR123",  // If associated with a list selection.
      index: 1,  // If associated with a list selection.
      quantity: 1
    }]
  }
});

Configuração de tag para este exemplo:

Tipo de tag: evento do GA4
Nome do evento: remove_from_cart
Parâmetro do evento (nome – valor): 'items' – {{Ecommerce Items}}
Tipo de variável: camada de dados – 'ecommerce.items'
Acionador: "event" é igual a "remove_from_cart"

Medir promoções

Você pode medir as impressões e os cliques em promoções internas do site, como banners exibidos no próprio site que anunciam promoções de um determinado subconjunto de produtos ou uma oferta de frete grátis.

Medir visualizações/impressões da promoção

Para medir uma visualização dos detalhes do produto, envie as informações da promoção à camada de dados e colete um evento view_promotion com essas informações. No exemplo a seguir, suponha que os detalhes dos produtos exibidos em uma página sejam conhecidos no momento do carregamento da página.

// Measure promotion views. This example assumes that information about the
// promotions displayed is available when the page loads.
dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "view_promotion",
  ecommerce: {
    items: [{
      item_name: "Donut Friday Scented T-Shirt", // Name or ID is required.
      item_id: "67890",
      price: 33.75,
      item_brand: "Google",
      item_category: "Apparel",
      item_category2: "Mens",
      item_category3: "Shirts",
      item_category4: "Tshirts",
      item_variant: "Black",
      promotion_id: "abc123",
      promotion_name: "summer_promo",
      creative_name: "instore_suummer",
      creative_slot: "1",
      location_id: "hero_banner",
      index: 1,
      quantity: 1
    }]
  }
});

Configuração de tag para este exemplo:

Tipo de tag: evento do GA4
Nome do evento: view_promotion
Parâmetro do evento (nome – valor): 'items' – {{Ecommerce Items}}
Tipo de variável: camada de dados – 'ecommerce.items'
Acionador: "event" é igual a "gtm.dom"

Medir cliques na promoção

Para medir um clique em uma promoção, colete um evento select_promotion com uma matriz de item a que a promoção está associada:

/**
 * Call this function when a user clicks on a promotion.
 * @param {Object} promoObj An object that represents an internal site promotion.
 */
function onPromoClick(promoObj) {
  dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
  dataLayer.push({
    event: "select_promotion",
    ecommerce: {
      items: [{
        item_name: promoObj.name, // Name or ID is required.
        item_id: promoObj.id,
        item_brand: promoObj.brand,
        item_category: promoObj.category,
        item_category2: productObj.category_2,
        item_category3: productObj.category_3,
        item_category4: productObj.category_4,
        item_variant: promoObj.variant,
        promotion_id: promoObj.pid,
        promotion_name: promoObj.pname,
        creative_name: promoObj.pcreative_name,
        creative_slot: promoObj.pcreative_slot,
        location_id: promoObj.plocation,
        index: promoObj.index,
        quantity: promoObj.quantity,
        price: promoObj.price
      }]
    }
  });
}

Configuração de tag para este exemplo:

Tipo de tag: evento do GA4
Nome do evento: select_promotion
Parâmetro do evento (nome – valor): 'items' – {{Ecommerce Items}}
Tipo de variável: camada de dados – 'ecommerce.items'
Acionador: "event" é igual a "select_promotion"

Medir uma finalização de compra

Para medir uma finalização de compra, envie os detalhes do produto à camada de dados e colete um evento begin_checkout com essas informações:

/**
 * A function to handle a click on a checkout button.
 */
function onCheckout() {
  dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
  dataLayer.push({
    event: "begin_checkout",
    ecommerce: {
      items: [{
        item_name: "Donut Friday Scented T-Shirt", // Name or ID is required.
        item_id: "67890",
        price: 33.75,
        item_brand: "Google",
        item_category: "Apparel",
        item_category2: "Mens",
        item_category3: "Shirts",
        item_category4: "Tshirts",
        item_variant: "Black",
        item_list_name: "Search Results",
        item_list_id: "SR123",
        index: 1,
        quantity: 1
      }]
    }
  });
}

Configuração de tag para este exemplo:

Tipo de tag: evento do GA4
Nome do evento: begin_checkout
Parâmetro do evento (nome – valor): 'items' – {{Ecommerce Items}}
Tipo de variável: camada de dados – 'ecommerce.items'
Acionador: "event" é igual a "begin_checkout"

Medir compras

Para medir transações, envie uma lista de itens à camada de dados e colete um evento purchase com essas informações. No exemplo a seguir, suponha que os detalhes dos produtos exibidos em uma página sejam conhecidos no momento do carregamento da página.

dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "purchase",
  ecommerce: {
      transaction_id: "T12345",
      affiliation: "Online Store",
      value: "59.89",
      tax: "4.90",
      shipping: "5.99",
      currency: "EUR",
      coupon: "SUMMER_SALE",
      items: [{
        item_name: "Triblend Android T-Shirt",
        item_id: "12345",
        price: "15.25",
        item_brand: "Google",
        item_category: "Apparel",
        item_variant: "Gray",
        quantity: 1
      }, {
        item_name: "Donut Friday Scented T-Shirt",
        item_id: "67890",
        price: 33.75,
        item_brand: "Google",
        item_category: "Apparel",
        item_variant: "Black",
        quantity: 1
      }]
  }
});

Configuração de tag para este exemplo:

Tipo de tag: evento do GA4
Nome do evento: purchase
Variáveis da camada de dados (Nome – Nome da variável da camada de dados):
- Itens de comércio eletrônico: ecommerce.items
- ID da transação de comércio eletrônico: ecommerce.transaction_id
- Afiliação de comércio eletrônico: ecommerce.affiliation
- Valor de comércio eletrônico: ecommerce.value
- Tributo de comércio eletrônico: ecommerce.tax
- Frete de comércio eletrônico: ecommerce.shipping
- Moeda de comércio eletrônico: ecommerce.currency
- Cupom de comércio eletrônico: ecommerce.coupon
Parâmetros de evento (Nome do parâmetro – Valor):
- items - {{Ecommerce Items}}
- transaction_id - {{Ecommerce Transaction ID}}
- affiliation - {{Ecommerce Affiliation}}
- value - {{Ecommerce Value}}
- tax - {{Ecommerce Tax}}
- shipping - {{Ecommerce Shipping}}
- currency - {{Ecommerce Currency}}
- coupon - {{Ecommerce Coupon}}
Acionador: "event" é igual a "purchase"

Medir reembolsos

Para medir um reembolso total de uma transação, colete um evento refund com o ID da transação a ser reembolsada:

// To refund an entire transaction, provide the transaction ID.
// This example assumes the details of the completed refund are
// available when the page loads:
dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "refund",
  ecommerce: {
    transaction_id: "T12345" // Transaction ID. Required for purchases and refunds.
  }
});

Configuração de tag para este exemplo:

Tipo de tag: evento do GA4
Nome do evento: refund
Parâmetro do evento (nome – valor): 'items' – {{Ecommerce Items}}
Tipo de variável: camada de dados – 'ecommerce.items'
Acionador: "event" é igual a "gtm.dom"

Para medir um reembolso parcial, adicione uma lista de items que inclui os IDs e as quantidades a serem reembolsadas:

// To measure a partial refund, provide an array of productFieldObjects and
// specify the ID and quantity of each product to be returned. This example
// assumes the partial refund details are known at the time the page loads:
dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "refund",
  ecommerce: {
      transaction_id: "T12345", // Transaction ID.
      items: [{
       item_name: "Donut Friday Scented T-Shirt",
       item_id: "67890", // ID is required.
       price: 33.75,
       item_brand: "Google",
       item_category: "Apparel",
       item_category2: "Mens",
       item_category3: "Shirts",
       item_category4: "Tshirts",
       item_variant: "Black",
       item_list_name: "Search Results", // If associated with a list selection.
       item_list_id: "SR123", // If associated with a list selection.
       index: 1, // If associated with a list selection.
       quantity: 1 // Quantity is required.
      }]
  }
});

Configuração de tag para este exemplo:

Tipo de tag: evento do GA4
Nome do evento: refund
Parâmetro do evento (nome – valor): 'items' – {{Ecommerce Items}}
Tipo de variável: camada de dados – 'ecommerce.items'
Acionador: "event" é igual a "gtm.dom"

Usar uma variável JavaScript personalizada

Se o seu site não for compatível com uma camada de dados, use uma variável JavaScript personalizada para chamar uma função que retorne o objeto de dados de comércio eletrônico. Esse objeto precisa usar a sintaxe de camada de dados mostrada anteriormente neste guia, por exemplo:

// A Custom JavaScript Variable that returns an ecommerceData object
// that follows the data layer syntax.
function getEcommerceData() {
  var ecommerceProductData = [
    {
      item_name: "Donut Friday Scented T-Shirt",
      item_id: "67890",  // ID is required.
      // Rest of the product data should follow the data layer syntax.
    },
    // Multiple products may be included.
  ];
  return ecommerceProductData;
}

Se você optar pela variável JavaScript personalizada, poderá utilizá-la da mesma forma que a camada de dados. Basta enviar o valor do parâmetro "items" como um parâmetro de evento na sua configuração de tag.

Configuração de tag para este exemplo:

Tipo de tag: evento do GA4
Nome do evento: qualquer
Ler dados da variável: {{gaEcommerceData}}
Acionador: "event" é igual a "gtm.dom"

Configurações de variável gaEcommerceData

Tipo de variável: JavaScript personalizada
Corpo da função: use o exemplo acima