---
sidebar_position: 8
title: Analytics - GA4
---

# Analytics e Rastreamento - Google Analytics 4

## Visão Geral

O Decoda implementa um sistema de analytics que permite acompanhar o uso da plataforma e entender como os estudantes interagem com as atividades educacionais. O sistema utiliza **Google Analytics 4 (GA4)** como provedor padrão, mas será migrado para solução open source e auto hospedada no futuro.

### Objetivos

- 📊 **Acompanhamento de uso** — entender quais atividades são mais usadas
- 📈 **Análise de performance** — identificar onde os estudantes têm dificuldade
- 📚 **Melhoria educacional** — usar dados para aprimorar o conteúdo
- 🔒 **Privacidade** — respeitar escolha do usuário com consentimento prévio

---

## Arquitetura do Sistema

O sistema de analytics é modular e extensível:

```text
src/services/
├── analytics/
│   ├── AnalyticsManager.js       # Orquestrador central
│   ├── config.js                 # Configuração global
│   ├── NetworkDetector.js        # Detecta conectividade
│   ├── googleConsentMode.js      # Conformidade GDPR/LGPD
│   ├── usePageTracking.js        # Hook: rastrear rotas
│   ├── useActivityTracking.js    # Hook: atividades com fases
│   ├── useLetramentoTracking.js  # Hook: atividades simples
│   ├── providers/
│   │   ├── BaseProvider.js       # Interface base
│   │   ├── GA4Provider.js        # Implementação GA4
│   │   └── NoopProvider.js       # Dummy para offline
│   └── index.js                  # Exports
└── consent/
    ├── ConsentManager.js         # Gerencia consentimento
    ├── useConsent.js             # Hook de acesso
    └── index.js
```

### Componentes Principais

#### **AnalyticsManager**

Orquestrador central que:
- Instancia o provedor apropriado (GA4, Noop, etc)
- Verifica consentimento antes de rastrear
- Verifica conectividade (offline-aware)
- Fornece interface unificada para tracking

#### **Provedores (Providers)**

Interface plugável para diferentes serviços:

- **GA4Provider** — Envia eventos para Google Analytics 4
- **NoopProvider** — Não faz nada (usado em desenvolvimento)

#### **ConsentManager**

Gerencia o consentimento do usuário:
- Armazena escolha em localStorage
- Inicializa Google Consent Mode
- Dispara eventos quando consentimento muda

---

## Configuração

### Variáveis de Ambiente

Configure o analytics através de variáveis de ambiente no build Docker:

**Produção (com GA4):**

```bash
VITE_ANALYTICS_PROVIDER=ga4
VITE_GA4_ID=G-57HGKF773M
VITE_GA4_DEBUG=false
```

**Desenvolvimento (sem rastreamento):**

```bash
VITE_ANALYTICS_PROVIDER=noop
VITE_GA4_ID=
```

### Arquivo `.env.example`

```bash
# Analytics Provider: 'ga4' ou 'noop'
VITE_ANALYTICS_PROVIDER=noop

# Google Analytics 4 ID (ID de medição do GA4)
# Obtenha em: https://analytics.google.com → Data Streams → Web
VITE_GA4_ID=

# Debug mode para GA4 (mostra eventos no console)
VITE_GA4_DEBUG=false
```

---

## Build Docker com Analytics

### Build Básico (Desenvolvimento)

```bash
docker compose build app
docker compose up app
```

### Build com GA4 (Produção)

```bash
docker compose build --build-arg VITE_ANALYTICS_PROVIDER=ga4 \
  --build-arg VITE_GA4_ID=G-SEU_ID_AQUI \
  --build-arg GIT_COMMIT_HASH=$(git rev-parse --short HEAD) app
```

### Build com Variáveis de Ambiente

Crie um arquivo `.env` na raiz do projeto:

```bash
GIT_COMMIT_HASH=abc1234
VITE_ANALYTICS_PROVIDER=ga4
VITE_GA4_ID=G-57HGKF773M
VITE_GA4_DEBUG=false
```

Então execute:

```bash
docker compose build app
docker compose up
```

### Usando docker build diretamente

```bash
docker build \
  --build-arg GIT_COMMIT_HASH=$(git rev-parse --short HEAD) \
  --build-arg VITE_ANALYTICS_PROVIDER=ga4 \
  --build-arg VITE_GA4_ID=G-SEU_ID_AQUI \
  -t decoda:latest \
  ./app
```

---

## Fluxo de Consentimento

O sistema implementa um fluxo LGPD/GDPR-compliant:

```
Primeiro acesso
    ↓
[CookieBanner aparece]
    ↓
Usuário escolhe
    ├─→ "Aceitar"
    │   ├─ Armazena consentimento em localStorage
    │   ├─ Carrega GA4 script
    │   ├─ Inicializa Google Consent Mode
    │   └─ Começa a rastrear
    │
    └─→ "Rejeitar"
        ├─ Armazena consentimento=false em localStorage
        ├─ Carrega NoopProvider
        └─ Não rastreia nada
```

### Armazenamento

- Chave: `decoda_consent`
- Valor: `true` (aceito) ou `false` (rejeitado)
- Local: localStorage (persiste entre sessões)

---

## Rastreamento de Eventos

### Page Views (Automático)

Toda mudança de rota dispara automaticamente:

```javascript
page_view {
  page_path: '/atividades/puzzle',
  page_title: 'Puzzle Game',
  language: 'pt-BR'
}
```

**Integração:** Hook `usePageTracking()` no `App.jsx`

### Atividades de Programação (Com Fases)

Para atividades com múltiplas fases como Puzzle, Aspirador, etc:

```javascript
import { useActivityTracking } from '@/services/analytics';

export default function PuzzleGame() {
  const { trackPhaseCompletion } = useActivityTracking(gameConfig);

  useEffect(() => {
    if (phaseCompleted) {
      trackPhaseCompletion(phaseId, phaseName, success);
    }
  }, [phaseCompleted]);

  return <GameBase gameFactory={createGame} gameConfig={gameConfig} />;
}
```

**Eventos gerados:**
- `fase_completada` — quando fase é resolvida
- `fase_falhou` — quando usuário falha
- `atividade_abandonada` — quando sai sem terminar

**Dados rastreados:**
- `atividade_id`, `atividade_nome`
- `fase_numero`, `fase_nome`
- `tempo_sessao_segundos`
- `categoria` (ex: Variáveis, Sequências)

### Atividades de Letramento (Simples)

Para atividades sem fases como Mouse, Teclado:

```javascript
import { useLetramentoTracking } from '@/services/analytics';

export function MouseBasico() {
  const { trackCompletion } = useLetramentoTracking('mouse-basico', 'Mouse');

  return (
    <button onClick={() => trackCompletion(true)}>
      Concluir
    </button>
  );
}
```

**Eventos gerados:**
- `letramento_atividade_completada` — sucesso
- `letramento_atividade_falhou` — falha

### Rastreamento Customizado

```javascript
import { getAnalytics } from '@/services/analytics';

const analytics = getAnalytics();
analytics.trackEvent('hint_used', {
  activity: 'puzzle-fase-1',
  hint_type: 'algorithm',
});
```

---

## Comportamento Offline

O Decoda é projetado para funcionar sem internet:

- **Quando offline**: Eventos são ignorados silenciosamente
- **Sem armazenamento em fila**: Não há fila local de eventos
- **Quando reconecta**: Apenas eventos após reconexão são rastreados
- **Sem erros**: Falhas de analytics não afetam a app

---

## Relatórios no GA4

### Acessar a Propriedade

1. Abra [https://analytics.google.com](https://analytics.google.com)
2. Selecione propriedade "Decoda"
3. Navegue para relatórios

### Relatórios Úteis

**Dashboard em Tempo Real:**
- `Relatórios → Em tempo real`
- Vê eventos acontecendo agora
- Útil para testar implementação

**Atividades mais usadas:**
- `Relatórios → Envolvimento → Eventos`
- Filtrar por `page_path` contendo `/atividades/`
- Agregar por `page_title`

**Taxa de conclusão por fase:**
- `Relatórios → Envolvimento → Eventos`
- Procurar por `fase_completada`
- Agrupar por `fase_numero`

**Tempo gasto por atividade:**
- `Relatórios → Envolvimento → Páginas e telas`
- Ver `tempo_médio_na_página`

---

## Offline-First Build

Para criar uma build sem analytics (offline):

```bash
docker compose build --build-arg VITE_ANALYTICS_PROVIDER=noop app
```

Ou via arquivo `.env`:

```bash
VITE_ANALYTICS_PROVIDER=noop
```

Depois:

```bash
pnpm run build:offline
```

---

## Política de Privacidade

A página `/privacy-policy` está integrada na app e explica:

- ✅ O que é rastreado (page views, eventos de atividades)
- ✅ Quem coleta (Google Analytics)
- ✅ Como optar por não ser rastreado (cookies)
- ✅ Conformidade LGPD e GDPR

---

## Google Consent Mode

O sistema implementa [Google Consent Mode](https://support.google.com/analytics/answer/9976101) para conformidade regulatória:

- **analytics_storage** — controlado por consentimento do usuário
- **ad_storage** — desabilitado (Decoda não exibe anúncios)
- **ad_personalization** — desabilitado

Garante que GA4 respeita a escolha GDPR/LGPD do usuário.

---

## Troubleshooting

### GA4 não está rastreando

**Checklist:**

1. ✅ Variável `VITE_ANALYTICS_PROVIDER=ga4`?
2. ✅ Variável `VITE_GA4_ID` configurada corretamente?
3. ✅ Usuário aceitou cookies?
4. ✅ Verificou em GA4 Real-time?

**Debug:**

```bash
# Ativar debug mode
VITE_GA4_DEBUG=true docker compose build app
```

Procure por logs no console do browser:

```
GA4: Tracking event 'page_view'
GA4: Event sent successfully
```

### Eventos não aparecem em GA4

- GA4 leva até 24h para processar eventos
- Use `Relatórios → Em tempo real` para verificação imediata
- Verifique se consentimento foi aceito (`localStorage.getItem('decoda_consent')`)

### Banner de cookies não aparece

```javascript
// No console do browser:
localStorage.removeItem('decoda_consent');
location.reload();
```

---

## Extensibilidade

Para adicionar um novo provedor (ex: Umami, Plausible):

1. **Crie arquivo:** `src/services/analytics/providers/UmamiProvider.js`

```javascript
import { BaseProvider } from './BaseProvider';

export class UmamiProvider extends BaseProvider {
  async initialize() {
    // Carregar script Umami
  }

  trackPageView(data) {
    // Implementar rastreamento
  }

  trackEvent(eventName, eventData) {
    // Implementar rastreamento
  }
}
```

2. **Registre em:** `src/services/analytics/config.js`

3. **Atualize variáveis:** `.env.example` e `Dockerfile`

---

## Referências

- [Google Analytics 4 Docs](https://developers.google.com/analytics/devguides/collection/ga4)
- [Google Consent Mode](https://support.google.com/analytics/answer/9976101)
- [LGPD Lei 13.709](http://www.planalto.gov.br/ccivil_03/_ato2015-2018/2015/lei/l13105.htm)
- [GDPR Official](https://gdpr-info.eu/)

Veja também: `app/src/services/analytics/ACTIVITY_TRACKING.md` para documentação detalhada de integração em atividades.
