RHEON

Guia para agência

GTM & Eventos de Rastreamento

Documentação completa de como o Google Tag Manager e o GA4 são instalados na loja, como os eventos são enviados ao dataLayere o que cada evento faz, com payload e gatilho no código.

Arquitetura

O rastreamento é multi-tenant: cada loja carrega seu próprio container GTM e ID de Analytics a partir de storeSettings.google, retornado pela API de configurações do tenant.

storeSettings.google (Admin/API)
  ↓
src/pages/_app.tsx → scripts GTM + GA4
  ↓
src/Gtm/index.ts → eventDataLayer() / sanitizeTag()
  ↓
Módulos GTM.ts por domínio + chamadas inline
  ↓
window.dataLayer.push(...)
Admin/API

Configuração no Admin

  • GTM: google.tagManager.ativoe google.tagManager.codigo
  • GA4: google.analytics.ativoe google.analytics.codigo
  • Ads: google.adWords(schema existe, sem implementação no frontend)
Schema: src/schemas/StoreSettings.tsx
Instalação

Scripts em _app.tsx

  • GTM: bootstrap padrão (gtm.js, gtm.start), noscript iframe, id lw-google-tagManager
  • GA4: gtag/js+ gtag('config'), id lw-google-analytics
  • Ambos compartilham o mesmo array dataLayer
Arquivo: src/pages/_app.tsx
Módulos

Onde os eventos são definidos

  • src/Gtm/index.ts— utilitários centrais
  • src/templates/*/GTM.ts— Header, PDP, Cart, Checkout, Offers, ShowcaseFilters
  • src/components/*/GTM.ts— ProductCard, Banner
  • Chamadas inline em páginas, hooks e BrandCard

Como os eventos são enviados

Todo evento customizado passa por eventDataLayer(). O contrato para tags/variáveis no GTM é o namespace marketplaceno payload.

eventDataLayer(data)

Garante window.dataLayer, faz push de { marketplace: null }(limpa o namespace anterior) e em seguida faz push do objeto datacom event+ marketplace. 

window.dataLayer = window.dataLayer || [];
window.dataLayer.push({ marketplace: null });
window.dataLayer.push(data);
Arquivo: src/Gtm/index.ts
Sanitização

sanitizeTag(tag)

Normaliza strings para o dataLayer: NFD, lowercase, barras e espaços viram hífen, remove acentos e caracteres especiais nas bordas. Usado em nomes de eventos, categorias, cupons e campos de texto.

Padrão de payload

Estrutura comum

{
  event: "nome_do_evento",
  marketplace: {
    /* campos específicos */
  }
}
GA4 Ecommerce

Eventos alinhados ao GA4

Nomes como view_cart, add_to_cart, remove_from_cart, begin_checkout, add_shipping_info, add_payment_info, purchasee add_to_wishlistseguem a convenção recomendada do GA4, com dados em marketplace.items[].

Catálogo de eventos

Eventos agrupados por área funcional. Quando o mesmo nome aparece em contextos diferentes (ex.: add_to_cart), o gatilho e o módulo definem a origem.

Bootstrap

Evento
O que faz
Payload principal
Gatilho
gtm.js
Inicialização do container GTM no carregamento da página.
gtm.start(timestamp)
Script GTM em _app.tsx

Busca & Descoberta

Evento
O que faz
Payload principal
Gatilho
search
Usuário submete busca no header.
search_term, is_seller_page, is_seller_search_active
Header/MiddleSearch — submit do formulário
product_details_search
Clique em produto no autocomplete da busca.
currency, value, items[] (id, marca, nome, fabricante, categoria)
Header/MiddleSearch — clique no autocomplete
search_page_success
Resultados da página de busca carregados (página 1).
route, search_term, linx_is_active, search_is_linx, is_success, total_results
pages/search — useEffectao receber resultados
brand_click
Clique em card de marca na vitrine.
brand_id, brand_name, brand_permalink
components/BrandCard — clique no link
category_click
Clique em categoria no menu de navegação.
category, categoryHref, categoryParent
Header/Nav — clique em item do menu
showcases_filter_control
Toggle de entrega turbo, entrega ou retirada nas vitrines.
filter_name(switch_delivery| button_delivery| button_pickup), route, filter_status
ShowcaseFilters/Filters — toggles de entrega
showcases_filter_change
Alteração de filtro (preço, atributos, etc.).
field, value
ShowcaseFilters/Filters — mudança de filtro
showcases_order_by_change
Alteração da ordenação da vitrine.
old_order, new_order
ShowcaseFilters/Grid — dropdown de ordenação

Produto / PDP

Evento
O que faz
Payload principal
Gatilho
product_details
Visualização da página de produto (PDP).
currency, value, geolocation_is_active, items[]rico (sku, seller, categoria, ean, estoque, atributos, url, imagem, retenção)
Pdp/index — useEffectno mount
add_to_cart
Produto adicionado ao carrinho a partir da PDP.
currency, value, items[]com quantidade
Pdp/BuyBox — sucesso da mutation de carrinho
add_to_wishlist
Produto adicionado à lista de desejos na PDP.
currency, value, items[]
Pdp/BuyBox — sucesso ao favoritar
remove_from_wishlist
Produto removido da lista de desejos na PDP.
currency, value, items[]
Pdp/BuyBox — sucesso ao desfavoritar
freight_at_pdp
Cálculo de frete na PDP concluído.
freight_zip_code, freight_success, items[], freight_response[]
Pdp/BuyBox — sucesso do cálculo de frete
btn_click-pdp-buy_now
Clique em "Comprar agora" na PDP.
route
Pdp/BuyBox — botão comprar
btn_click-pdp-add_to_cart
Clique em "Adicionar ao carrinho" na PDP.
route
Pdp/BuyBox — botão adicionar
click_seller_PDP
Clique no link do seller na PDP.
seller_id, seller_code, seller_name, seller_permalink
Pdp/BuyBox — link do seller
related_product_click
Clique em produto relacionado na PDP.
id, price, category, name, sku, url, geolocation_is_active
Pdp/index — clique em relacionado

Ofertas

Evento
O que faz
Payload principal
Gatilho
add_to_cart
Oferta adicionada ao carrinho na página de ofertas.
currency, value, items[] (campos específicos de oferta)
Offers/index — sucesso da mutation
btn_click-offers-buy_now
Clique em "Comprar agora" na página de ofertas.
route
Offers/index — botão comprar
btn_click-offers-add_to_cart
Clique em "Adicionar" na página de ofertas.
route
Offers/index — botão adicionar
click_seller_offers
Clique no link do seller na página de ofertas.
seller_id, seller_code, seller_name, seller_permalink
Offers/index — link do seller
offers_details
Não chamadoVisualização detalhada da página de ofertas com frete.
permalink, items[]com opções de frete por oferta
Definido em Offers/GTM.ts — sem chamada no código
offer_freight_success
Não chamadoResumo de sucesso do frete na página de ofertas.
offers_length, freight_length, offers_page_warn
Definido em Offers/GTM.ts — sem chamada no código

Carrinho

Evento
O que faz
Payload principal
Gatilho
view_cart
Visualização do carrinho com itens.
currency, value, coupon, coupon_discount, items[]com index
pages/cart — useEffectquando carrinho não vazio
add_to_cart
Produto adicionado via card de produto (vitrine).
currency, value, items[]com index
ProductCard/Button — sucesso ao adicionar
edit_from_cart
Quantidade alterada no carrinho ou no mini-card.
currency, value, coupon, items[]
Cart/index ou ProductCard/Button — edição de quantidade
remove_from_cart
Item removido do carrinho.
currency, value, items[]com quantidade removida
Cart/index ou ProductCard/Button — qty = 0
apply_coupon
Tentativa de aplicar cupom (sucesso ou erro).
coupon, coupon_success, coupon_message(se falha)
Cart/index — mutation de cupom
remove_coupon
Remoção de cupom do carrinho.
coupon, coupon_success
Cart/index — delete cupom
click_seller_cart
Clique no link do seller dentro do carrinho.
seller_id, seller_code, seller_name, seller_permalink
Cart/Items — links do seller (4 pontos)
minimum_value_at_cart
Não chamadoValor mínimo por grupo de entrega no carrinho.
delivery_groups_minimum_value[]
Definido em Cart/GTM.ts — sem chamada no código

Checkout (funil GA4)

Evento
O que faz
Payload principal
Gatilho
begin_checkout
Início do checkout com dados do pedido.
currency, value,total_items , value_without_shipping,coupon, items[]
Checkout/index — useEffectno mount
add_shipping_info
Opção de entrega selecionada para um seller.
currency, value, coupon, items[][]com delivery_group
Checkout/DeliveryOptions — sucesso da mutation
add_payment_info
Forma de pagamento aberta/selecionada.
payment_type, discount, coupon, items[]
Checkout/Payment — abertura do accordion de pagamento
purchase
Compra finalizada com sucesso.
transaction_id, payment_status( REGISTRADO), user_email, shipping, payment_type, installments, items[]
Checkout/Payment — sucesso ao finalizar pedido

Geolocalização

Evento
O que faz
Payload principal
Gatilho
geolocation_status
Modal de geolocalização aberto ou fechado.
step(default| search| register), status(opened| closed), is_authenticated
Header/MiddleGeo — mudança de estado do modal
geolocation_step_changed
Navegação entre etapas do fluxo de endereço.
old_step, next_step
Header/MiddleGeo — voltar ou avançar etapa
geolocation_address_selected
Endereço confirmado, salvo ou com erro.
step, address_success, is_authenticated, error_message
MiddleGeo, Addresses, Register — confirmação/erro
geolocation_pin_dragged
Pin do mapa arrastado pelo usuário.
is_authenticated
Header/MiddleGeo/Search — drag do pin
geolocation_is_from
Origem da localização: navegador ou Google.
address_is_from(navigator| google), is_authenticated
Header/MiddleGeo/Search — geolocalização ou autocomplete
geolocation_removed
Endereço de geolocalização removido.
is_authenticated
Header/MiddleGeo/Trigger — limpar endereço

UI, Navegação & Banners

Evento
O que faz
Payload principal
Gatilho
btn_click- { nome}
Clique em botões de login/cadastro (nome dinâmico).
route
Header/MiddleUser: header-entre_ou_cadastre, header-popover-entrar; SideMenu: side_menu-entre_ou_cadastre
banner-click
Clique em banner promocional.
banner_id, banner_type, banner_order, banner_title, banner_img_url, banner_location, banner_permalink
components/Banner — clique (desativável via triggerGTM=false, ex.: press)
add_to_wishlist
Favoritar produto no card da vitrine.
currency, value, items[]
ProductCard/Favorite — toggle favorito
remove_from_wishlist
Desfavoritar produto no card da vitrine.
currency, value, items[]
ProductCard/Favorite — toggle favorito

Padrões de payload

Campos recorrentes no namespace marketplace. Use esta referência ao configurar variáveis e triggers no GTM.

Ecommerce

items[]

  • item_id, item_name, item_sku
  • item_sku_seller, item_brand_id, item_brand
  • item_seller_id, item_category, item_category_id
  • price, discount, quantity , index
  • item_image, item_url, item_sob_encomenda
  • Checkout: delivery_group, delivery_group_value
Seller

Campos de seller

  • seller_id, seller_code
  • seller_name, seller_permalink
  • Eventos: click_seller_PDP, click_seller_cart, click_seller_offers
Cupom

Campos de cupom

  • coupon— código sanitizado
  • coupon_discount— valor do desconto
  • coupon_success, coupon_message— apply/remove
Geolocalização

Campos de geo

  • geolocation_is_active— lat/long válidos
  • step, status, is_authenticated
  • address_success, error_message
  • address_is_from: navigatorou google
Checkout

Campos de compra

  • transaction_id, payment_status
  • payment_type, installments
  • value_without_shipping, shipping
  • user_email, total_items
Sanitização

sanitizeTag()

Aplicado em termos de busca, nomes de produto/categoria, cupons, rotas, mensagens de erro e nomes dinâmicos de botões. Garante consistência para variáveis do GTM.

Matriz de módulos e arquivos

Mapa dos módulos GTM.tsexportados e onde são consumidos no código.

Módulo
Funções exportadas
Consumido em
Eventos principais
Header/GTM.ts
search, productClick, categoryClick, buttonClick, geoStatus, geoStepChanged, geoAddressSelected, geoPinDragged, geoAddressIsFrom, geoAddressRemoved
MiddleSearch, Nav, MiddleUser, MiddleGeo/*
search, product_details_search, category_click, geolocation_*
Pdp/GTM.ts
productDetails, addToCart, editWishlistItem, freightAtPdp, btnClickAtPdp, sellerLinkClickAtPdp, relatedProductClick
Pdp/index, Pdp/BuyBox
product_details, add_to_cart, freight_at_pdp, btn_click-pdp-*
Cart/GTM.ts
viewCart, editCartItem, couponEvents, sellerLinkClickAtCart, minimumValueAtCart
pages/cart, Cart/index, Cart/Items
view_cart, edit_from_cart, apply_coupon, click_seller_cart
Checkout/GTM.ts
beginCheckout, addShippingInfo, addPaymentInfo, purchase
Checkout/index, DeliveryOptions, Payment
begin_checkout → add_shipping_info → add_payment_info → purchase
Offers/GTM.ts
offersDetails, addToCart, btnClickAtOffers, sellerLinkClickAtOffers, offerFreightSuccess
Offers/index
add_to_cart, btn_click-offers-*, click_seller_offers
ShowcaseFilters/GTM.ts
filterSwitchControl, filtersChange, orderByChange
ShowcaseFilters/Filters, Grid
showcases_filter_*, showcases_order_by_change
ProductCard/GTM.ts
editCartItem, editWishlistItem
ProductCard/Button, Favorite
add_to_cart, edit_from_cart, add/remove_from_wishlist
Banner/GTM.ts
btnClickAtPdp (banner click)
components/Banner
banner-click

Guia GTM & Eventos — Lean Marketplace Farma — documentação estática para agência e time de marketing.