Google Analytics 4 (importação)

1. O que é importado e o que não é

As duas opções leem dados da sua conta Google e são ativadas separadamente. Respondem a perguntas diferentes; você não precisa das duas.

Opção	O que busca	Para quê
Data API	Totais diários: sessões, usuários, visualizações de página e sessões engajadas	Medir a cobertura. O GA4 conta 3.000 sessões e o MousePlayer gravou 40: sem o número de referência, nem se percebe a diferença.
Importação BigQuery	Sessões GA4 individuais com seus eventos	Saber o que ocorreu numa visita que o MousePlayer não pôde gravar.

Uma sessão importada não pode ser reproduzida. O GA4 não guarda capturas da página nem movimentos do mouse, então não há como construir uma reprodução. Você recebe números e eventos ao lado das gravações, nada além disso, e não os apresentamos como algo a mais.

A importação tem tabelas próprias e nunca é misturada às gravações. Caso contrário, mudaria silenciosamente o significado de cada indicador derivado — perfis comportamentais, avaliação dos visitantes, análise de atrito — e ninguém conseguiria distinguir linhas medidas de importadas.

2. Opção 1: Data API

Você precisa do ID da propriedade e de uma chave de conta de serviço.

O ID da propriedade não é o ID de medição

Este é o erro mais comum e a mensagem do Google não o identifica. O ID de medição tem o formato G-ABC123XYZ, está no snippet de rastreamento e aparece em toda parte. O ID da propriedade é só numérico e aparece na administração, em Administrador, Configurações da propriedade. É esse que usamos; rejeitamos o primeiro com uma explicação para evitar um erro 400.

Criar e autorizar a conta de serviço

No Google Cloud Console, crie uma conta de serviço e gere uma chave JSON.
No mesmo projeto, ative a Google Analytics Data API.
No GA4, em Administrador, Gerenciamento de acesso à propriedade, adicione o e-mail da conta de serviço com o papel Leitor. Uma conta de serviço é um usuário independente; sem isso, o Google responde 403 sem dizer o motivo.

Cole o conteúdo do arquivo JSON no campo. Ele é armazenado criptografado e depois exibido apenas de forma abreviada.

3. Opção 2: importação BigQuery

Esta opção lê a exportação bruta do GA4. Configure-a uma vez no GA4: Administrador, Vinculações do BigQuery. As tabelas só aparecem no dia seguinte - antes disso, a importação não encontra nada e isso não é falha.

O que informar

O ID do projeto GCP que contém a exportação. Não é necessariamente o mesmo projeto para o qual você exporta dados do MousePlayer.
O ID do conjunto de dados. O GA4 usa o nome analytics_<propertyId>.
Uma chave de conta de serviço com Leitor de dados do BigQuery no conjunto de dados e Usuário de jobs do BigQuery no projeto. O acesso de leitura basta; não conceda mais permissões.

Quanto custa e quem paga

O BigQuery cobra pelos bytes lidos, e a conta é sua. Por isso a importação lê poucos dias por execução e faz uma única consulta: outra leria as mesmas tabelas novamente. Além disso, um limite rígido interrompe a consulta antes que fique cara; nesse caso, o registro de entregas informa que o intervalo é grande demais.

A frequência

A cada seis horas por padrão, buscando novamente os últimos três dias. Não é arbitrário: o GA4 completa dados por até 48 horas, e a exportação diária só aparece no dia seguinte. Consultar mais vezes não gera números mais novos, apenas os mesmos.

4. A chave que conecta os dois lados

Se também configurar a ponte de análise para GA4, o MousePlayer registra em cada sessão o ID de cliente do cookie _ga . É exatamente o valor que a exportação BigQuery contém como user_pseudo_id.

Com ele, uma sessão GA4 pode ser associada a uma gravação e, no outro sentido, você vê o que o GA4 contou na mesma visita. Sem a ponte, os dois lados ficam apenas lado a lado, desconectados.

O mesmo campo também guarda seu próprio identificador de cliente se usar setUserId(). Não pode conter ambos: fica ali o ID de cliente do Google ou seu próprio número.

5. Consentimento, retenção e exclusão

Os dados importados tinham cookie

Só são importadas linhas com um user_pseudo_id . Quando o visitante recusa, o GA4 envia sinais sem cookies pelo Consent Mode, que não têm esse identificador: ficam de fora sem depender de uma promessa. Linhas modeladas, ou seja, estimadas, também ficam de fora: armazenar uma estimativa como sessão seria guardar visitas que nunca ocorreram.

Por quanto tempo ficam

180 dias por padrão, contados do dia descrito pela linha, não da importação. Caso contrário, o prazo nunca terminaria, pois cada execução busca os mesmos dias novamente.

Exclusão

Se um visitante pedir a exclusão dos dados, suas sessões GA4 importadas também são apagadas, na medida em que o identificador permita atribuí-las a ele. Se excluir o projeto, todas são apagadas, inclusive linhas nunca vinculadas às gravações. A rotina diária de retenção as deixa intactas deliberadamente: dados GA4 têm seu próprio calendário e as gravações expiram antes.

6. Quando nada chega

Cada execução registra o resultado na página de integrações, incluindo falhas, em palavras claras. Isso normalmente já explica o que falta.

Mensagem	O que fazer
O ID da propriedade deve ser apenas numérico	Você informou o ID de medição. O número correto está no GA4, em Configurações da propriedade.
HTTP 403 da Data API	A conta de serviço não tem o papel Leitor na propriedade GA4 ou a Data API não está ativada no projeto GCP.
Conjunto de dados ou tabelas de exportação não encontrados	Falta a vinculação BigQuery, o conjunto tem outro nome ou ainda não passou um dia.
Acesso negado (BigQuery)	Falta Leitor de dados do BigQuery no conjunto ou Usuário de jobs do BigQuery no projeto para a conta de serviço.
A consulta leria dados demais	O limite de custo interrompeu a consulta antes de qualquer cobrança. Escolha um intervalo menor.
nenhuma sessão no intervalo	Não é falha. Não houve sessões com consentimento nos dias buscados.

Como podemos ajudar?