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:

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

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

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.

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

Para avaliar 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 são conhecidos quando a página é carregada:

// Measure product views / impressions
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_category_2': 'Mens',
       'item_category_3': 'Shirts',
       'item_category_4': '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_category_2': 'Mens',
       'item_category_3': 'Shirts',
       'item_category_4': '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"

Avaliar cliques na lista de itens/produtos

Para avaliar 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(productObj) {
  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_category_2': productObj.category_2,
        'item_category_3': productObj.category_3,
        'item_category_4': 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"

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

Para avaliar 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({
  '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_category_2': 'Mens',
      'item_category_3': 'Shirts',
      'item_category_4': '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"

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

Da mesma forma, para avaliar 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({
  '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_category_2': 'Mens',
      'item_category_3': 'Shirts',
      'item_category_4': '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({
  '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"

Avaliar promoções

Você pode avaliar 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.

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

Para avaliar 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({
  '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_category_2': 'Mens',
      'item_category_3': 'Shirts',
      'item_category_4': '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"

Avaliar cliques na promoção

Para avaliar 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({
    '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_category_2': productObj.category_2,
        'item_category_3': productObj.category_3,
        'item_category_4': 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"

Avaliar uma finalização de compra

Para avaliar 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({
    '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_category_2': 'Mens',
        'item_category_3': 'Shirts',
        'item_category_4': '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"

Avaliar compras

Para avaliar 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({
  'event': 'purchase',
  'ecommerce': {
    'purchase': {
      'transaction_id': 'T12345',
      'affiliation': 'Online Store',
      'value': '35.43',
      'tax': '4.90',
      'shipping': '5.99',
      'currency': 'EUR',
      'coupon': 'SUMMER_SALE',
      'items': [{
        'item_name': 'Triblend Android T-Shirt',
        'item_id': '12345',
        'item_price': '15.25',
        'item_brand': 'Google',
        'item_category': 'Apparel',
        'item_variant': 'Gray',
        'quantity': 1,
        'item_coupon': ''
      }, {
        'item_name': 'Donut Friday Scented T-Shirt',
        'item_id': '67890',
        'item_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
  • Parâmetro do evento (nome – valor): 'items' – {{Ecommerce Items}}
  • Tipo de variável: camada de dados – 'ecommerce.items'
  • Acionador: "event" é igual a "gtm.dom"

Avaliar reembolsos

Para avaliar um reembolso total de uma transação, colete um evento refund com o código 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({
  '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 avaliar um reembolso parcial, adicione uma lista de items que inclui os códigos 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({
  '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_category_2': 'Mens',
       'item_category_3': 'Shirts',
       'item_category_4': '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 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 mostrada anteriormente neste guia, por exemplo:

// A Custom JavaScript Variable that returns an ecommerceData object
// that follows the data layer syntax.
function() {
  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