Google Analytics

Visão Geral

Visão geral da API do Google Analytics da V4MOS.AI

A API do Google Analytics da V4MOS.AI centraliza dados de sessões, eventos, eventos personalizados, clientes, produtos e transações das propriedades GA4 conectadas ao seu organization. Todos os endpoints ficam sob o prefixo /v1/google-analytics e seguem os mesmos padrões de autenticação, paginação e resposta da plataforma.

Endpoints Disponíveis

Autenticação

Todos os endpoints exigem o query parameter organizationId. Todos, menos as rotas da auditoria (/events-by-device, /products-by-device e /landing-sessions), autenticam com os headers x-client-id e x-client-secret; as rotas da auditoria só aceitam Bearer token (detalhes mais abaixo, nas rotas por aparelho). Veja Autenticação.

Parâmetros Comuns

  • organizationId (obrigatório) – Organização que possui a integração do Google Analytics
  • userId – Escopo de usuário
  • page – Número da página (padrão: 1)
  • limit – Registros por página (padrão: 500, máx: 5000)
  • createdStart / createdEnd – Filtro por intervalo de datas (ISO 8601)

Filtros Específicos por Recurso

Sessões (/v1/google-analytics/sessions)

  • createdStart / createdEnd

Eventos (/v1/google-analytics/events)

  • createdStart / createdEnd

Eventos Personalizados (/v1/google-analytics/custom-events)

  • createdStart / createdEnd

Clientes (/v1/google-analytics/customers)

  • createdStart / createdEnd

Produtos (/v1/google-analytics/products)

  • createdStart / createdEnd

Transações (/v1/google-analytics/transactions)

  • createdStart / createdEnd

Engajamento (/v1/google-analytics/engagement)

  • startDate / endDate (obrigatórios, YYYY-MM-DD, UTC, até 366 dias); sem paginação
  • Devolve sessões, sessões engajadas e taxa de rejeição ((1 - sessões engajadas / sessões) * 100) por dia, no total e por aparelho
  • engagementSeconds: tempo médio de engajamento por sessão do GA4, em segundos (userEngagementDuration / sessions: SUM(user_engagement_duration) / SUM(sessions), só nas linhas que têm a medida); num período com backfill parcial é a média dos dias medidos, enquanto sessões e rejeição contam todos os dias; null para dado do GA4 carregado antes do backfill do tempo de engajamento

Eventos por aparelho (/v1/google-analytics/events-by-device)

  • startDate / endDate (obrigatórios, YYYY-MM-DD, UTC, até 366 dias); eventNames opcional (separados por vírgula, até 50); sem paginação
  • Devolve por evento (ex.: add_to_cart, purchase, form_submit) contagem, eventos-chave, valor e transações do período, no total e por aparelho

Produtos por aparelho (/v1/google-analytics/products-by-device)

  • startDate / endDate (obrigatórios, YYYY-MM-DD, UTC, até 366 dias); sem paginação
  • Devolve visualizações de produto, carrinhos, checkouts, compras e receita de item do período, somando todos os produtos, no total e por aparelho

As duas rotas por aparelho são da auditoria: só aceitam Bearer token de kind user ou oaclient emitido para a aplicação V4MOS. O par x-client-id / x-client-secret e service accounts de cliente recebem 403.

Sessões por página de entrada (/v1/google-analytics/landing-sessions)

  • startDate / endDate (obrigatórios, YYYY-MM-DD, UTC, até 366 dias); sem paginação
  • Devolve sessões, sessões engajadas e taxa de rejeição por grupo de canal (com as sessões do período anterior, de mesmo tamanho) e as 10 páginas de entrada com mais sessões
  • Também é da auditoria: mesmo acesso das rotas por aparelho (Bearer user ou oaclient; o par e service accounts recebem 403)

Destaques do Modelo de Dados do Google Analytics

Sessões

  • Campanhas e tráfego: campaign_id, campaign_name, source_medium, session_source_medium
  • Páginas: page_title, page_path
  • Usuários e sessões: sessions, total_users, new_users, engaged_sessions, sessions_per_user
  • Data: date

Eventos

  • Identificação: event_name, date
  • Métricas: event_count, event_count_per_user, event_value, events_per_session, key_events

Eventos Personalizados

  • Identificação: event_name, event_date
  • Métricas: metric_name, metric_value
  • Mapeamento RD Station: custom_rd_action, custom_rd_asset_id, custom_rd_filter
  • Categoria: custom_event_category, custom_event_label

Clientes

  • Campanhas e segmentação: campaign_id, campaign_name, device_category, source_medium
  • Geografia: city, region, country
  • Audiência: active_users, total_users, sessions, engaged_sessions, bounce_rate
  • Receita: purchase_revenue, total_revenue, total_purchases, purchaser_rate
  • Data: date

Produtos

  • Identificação: item_id, item_name
  • Receita e compras: item_revenue, items_purchased
  • Interações: items_viewed, items_added_to_cart, items_checked_out, items_clicked_in_promotion, item_list_click_through_rate
  • Data: date

Transações

  • Identificação: event_name, date
  • Métricas: transactions, transactions_per_purchaser

Respostas

Todas as respostas seguem o padrão:

{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 500,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Nesta página