> ## Documentation Index
> Fetch the complete documentation index at: https://strattumai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Analytics

> Configure o conector Google Analytics para ingerir métricas de sessões, páginas e eventos do GA4 na plataforma strattum.ai.

O conector Google Analytics ingere relatórios agregados de uma propriedade GA4 na infraestrutura strattum.ai. Os dados aparecem no Data Catalog como séries diárias de sessões, visualizações de página, eventos e aquisição de usuários.

## Capacidades

* Extrai relatórios pré-definidos da Google Analytics Data API (GA4).
* Agrega métricas por dia, com dimensões de origem, mídia, página e evento.
* Autenticação via Service Account do Google Cloud.

## Objetos suportados

Cada objeto é um relatório fixo com dimensões e métricas definidas.

| Objeto              | Dimensões                                    | Métricas                                           |
| ------------------- | -------------------------------------------- | -------------------------------------------------- |
| `sessions`          | `date`, `sessionSource`, `sessionMedium`     | `sessions`, `bounceRate`, `averageSessionDuration` |
| `page_views`        | `date`, `pagePath`, `pageTitle`              | `screenPageViews`                                  |
| `events`            | `date`, `eventName`                          | `eventCount`                                       |
| `user_acquisitions` | `date`, `firstUserSource`, `firstUserMedium` | `newUsers`, `totalUsers`                           |

## Pré-requisitos

<CardGroup cols={2}>
  <Card title="Propriedade GA4" icon="chart-line">
    Uma propriedade Google Analytics 4 e o seu Property ID numérico.
  </Card>

  <Card title="Service Account com acesso ao GA4" icon="user-shield">
    Uma Service Account do Google Cloud adicionada como leitora na propriedade. O passo a passo está abaixo.
  </Card>
</CardGroup>

## Configuração

<Steps>
  <Step title="Crie uma Service Account">
    No [Google Cloud Console](https://console.cloud.google.com), acesse **IAM & Admin → Service Accounts → Create Service Account**. Dê um nome como `strattum-ga-reader`.
  </Step>

  <Step title="Habilite a Google Analytics Data API">
    Em **APIs & Services → Library**, pesquise por `Google Analytics Data API` e clique em **Enable**.
  </Step>

  <Step title="Gere a chave JSON">
    Na Service Account, acesse **Keys → Add Key → Create new key**, selecione **JSON** e baixe o arquivo.

    <Warning>
      A chave JSON não expira automaticamente. Trate-a como senha crítica e rotacione periodicamente.
    </Warning>
  </Step>

  <Step title="Dê acesso à propriedade GA4">
    No Google Analytics, acesse **Admin → Property Access Management** e adicione o e-mail da Service Account (`nome@projeto.iam.gserviceaccount.com`) com o papel **Viewer**.
  </Step>

  <Step title="Descubra o Property ID">
    Em **Admin → Property Settings**, copie o **Property ID** numérico (ex: `123456789`). Não use o Measurement ID (`G-XXXX`).
  </Step>

  <Step title="Adicione o conector no Console">
    No menu lateral do Console, clique em **Conectores → + Nova Conexão** e selecione **Google Analytics**. Preencha os campos:

    * **Nome do Conector** — identificador na lista de conectores (Obrigatório)
    * **Property ID** — ID numérico da propriedade GA4 (Obrigatório)
    * **Service Account JSON** — cole o conteúdo do arquivo JSON baixado (Obrigatório)
  </Step>
</Steps>

## Autenticação e escopos

A autenticação é por Service Account do Google Cloud, com um escopo OAuth de leitura.

| Item                  | Valor                                                |
| --------------------- | ---------------------------------------------------- |
| Escopo OAuth          | `https://www.googleapis.com/auth/analytics.readonly` |
| Acesso na propriedade | Papel **Viewer** em Property Access Management       |

## Frequência de sync

O conector sincroniza **uma vez por dia**, às 6h. O GA4 consolida os dados do dia anterior, então a série diária fica completa após o fechamento do dia.

## Limitações conhecidas

* Os relatórios são fixos (os quatro objetos acima), com dimensões e métricas pré-definidas; não há relatório customizado pela configuração do conector.
* Os dados são agregados por dia — não há granularidade por sessão ou por usuário individual.
* Métricas do dia corrente podem estar incompletas até o GA4 consolidar; a série se estabiliza no fechamento do dia.
* É necessário usar o Property ID numérico, não o Measurement ID (`G-XXXX`).

## Troubleshooting

| Sintoma                         | Causa provável                              | O que fazer                                                                    |
| ------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------ |
| `403 PERMISSION_DENIED`         | Service Account sem acesso à propriedade    | Adicione o e-mail da Service Account como Viewer em Property Access Management |
| `property_id must not be empty` | Property ID vazio ou inválido               | Preencha o Property ID numérico de Property Settings                           |
| Nenhum dado retornado           | Uso do Measurement ID em vez do Property ID | Troque `G-XXXX` pelo ID numérico da propriedade                                |
| `API has not been enabled`      | Google Analytics Data API desabilitada      | Habilite a API em APIs & Services → Library                                    |

## Próximos passos

<CardGroup cols={2}>
  <Card title="Guia de desenvolvimento local" icon="terminal" href="/data-pipelines/local-development">
    Configure o ambiente local completo com Prefect, worker e Docker Compose.
  </Card>

  <Card title="Quickstart — Data Pipelines" icon="rocket" href="/data-pipelines/quickstart">
    Ative conectores via Console strattum.ai sem precisar de ambiente local.
  </Card>
</CardGroup>