NEXUS Google Analytics GA4

Resumo técnico

Integração do NEXUS com o Google Analytics 4: encaminhamento server-side de eventos nativos via Measurement Protocol (sem cookies de terceiros) e consulta de métricas pela Data API (OAuth 2.0) — com client_id pseudonimizado (SHA-256 + salt), sanitização de propriedades (sem PII), seleção de eventos a encaminhar, dashboard com usuários/sessões/pageviews, tempo real, top pages e i18n PT/EN.

Escopo executado

• plugin.json: v1.0.0, categoria "Monitoring" (aba SEO & Marketing, ícone bar-chart-3).
• Gateway server-side via hook: PluginManager::registerFilter('after_track_event', 'ga4_on_after_track_event') — o core rastreia eventos e o plugin os reencaminha ao GA4 sem cookies de terceiros (único da série com filter de eventos do core).
• Eventos padrão encaminháveis (ga4_default_forward_events): page_view, login_success, login_failure, task_created, task_completed, comment_added, ai_explain_used, plugin_activated, onboarding_step — lista configurável.
• ga4_forward_event — só encaminha com enabled + forward_enabled + mp_ready e evento na allowlist; nome normalizado a 40 chars ([a-z0-9_]), engagement_time_msec=1, nexus_session_id opcional.
• ga4_mp_collect — POST em https://www.google-analytics.com/mp/collect?measurement_id={G-…}&api_secret={secret} (endpoint /debug/mp/collect para validação com validationMessages); timeout 8s; sucesso = HTTP 2xx com corpo vazio; trata VALUE_INVALID/NAME_INVALID no debug.
• ga4_client_id — pseudonimização: sha256(site_salt | user|session) convertido no formato GA4 digits.digits (dois blocos hexdec de 8 chars); site_salt gerado com random_bytes(16) na primeira carga e persistido.
• ga4_sanitize_properties — deny list anti-PII (password, passwd, secret, token, api_key, authorization, cookie, csrf, session, content, text, body, description, comment, comment_text, title, email, phone, cpf, cnpj); strings cortadas em 100 chars; chaves normalizadas a 40 chars; arrays viram JSON se ≤ 200 chars.
• Config (plugin.google_analytics.config via DB::setConfig): measurement_id validado por regex ^G-[A-Z0-9]+$ (erro i18n se inválido), api_secret só atualiza se não-vazio (máx. 200), property_id só dígitos (máx. 20), oauth_client_id/secret (máx. 500), oauth_refresh_token (limpa access token ao salvar), toggles enabled/forward_enabled/client_tracking/dedupe_client/anonymize, lista forward_events.
• Sem tabela MySQL dedicada: config e stats 24h (forwarded_total, forwarded_day, forwarded_today, last_forward_at, last_error, last_error_at) vivem na config — primeiro da série sem DDL própria.
• ga4_stats — api_online, mp_ready, oauth_ready, contadores de forward, último erro, config pública (sem secrets) e available_events.
• ga4_test_connection — exige mp_ready; envia evento nexus_connection_test pelo debug endpoint (e dispara um collect real para aparecer no Realtime); retorna oauth_note (pronto/pendente).
• OAuth 2.0 (ga4_oauth_token) — refresh token em https://oauth2.googleapis.com/token (timeout 12s); access_token cacheado até expires_in, renovando com < 60s de margem.
• Data API (ga4_data_api_run) — POST https://analyticsdata.googleapis.com/v1beta/properties/{propertyId}:runReport|:runRealtimeReport com Bearer; timeout 20s; oauth_pending quando faltam credenciais.
• ga4_report — activeUsers, sessions, screenPageViews por dia (range 7daysAgo/today + totals).
• ga4_realtime — activeUsers por unifiedScreenName (limit 10).
• ga4_top_pages — screenPageViews por pagePath (limit 1–50).
• API: 7 actions (ga4_stats, ga4_settings_get, ga4_settings_save, ga4_test_connection, ga4_report, ga4_realtime, ga4_top_pages).
• UI Alpine.js (tab.php, 564 linhas) — tema azul (blue-600), ícone bar-chart-3, aba SEO & Marketing; 3 sub-abas (Dashboard, Eventos, Configuração); 4 KPI cards (Encaminhados Hoje, Total Forward, MP Configurado, OAuth Data API); badge Forward Online / MP Pronto / Offline com atalho para configuração; alerta de último erro de forward; gráfico de linha Chart.js (3 séries nas cores #2563eb/#059669/#d97706 — usuários, sessões, pageviews) no Dashboard + painéis de tempo real e top pages; aba Eventos com checkboxes de seleção dos eventos a encaminhar; aba Configuração com guias em 2 blocos (Measurement ID + API Secret em 6 passos; OAuth/Data API em 7 passos com Property ID, Client ID, Client Secret, Refresh Token); campos de secret como password com hint "(já configurado — deixe vazio para manter)"; botão Testar conexão com feedback.
• i18n próprio — lang.json (pt_BR/en_US) carregado via nexusRegisterPluginI18n + nx_load_dictionary; UI usa window.t() e __() (com fallback); primeiro da série com dicionário próprio.
• Fastr: /ga4 → ga4_stats (resumo, argumento opcional; descrição i18n).
• Cron: cronjob.json existe mas com jobs: [] e nota "Plugin sob demanda; nenhuma rotina periódica segura ou necessária" — on-demand.
• client_tracking (gtag.js no browser) desligado por padrão — o forward é server-side; segredos nunca expostos ao frontend (ga4_public_config só expõe flags e *_configured).

Stack e ferramentas

• PHP 8 (sem framework)
• MySQL 8 (sem tabela dedicada — config + stats em plugin.google_analytics.config)
• Alpine.js + Tailwind CSS (premium light, azul) + Chart.js (linha 3 séries)
• Measurement Protocol (google-analytics.com/mp/collect + /debug/mp/collect)
• Google Analytics Data API v1beta (runReport / runRealtimeReport, OAuth 2.0)
• cURL (MP 8s, OAuth 12s, Data API 20s)
• i18n próprio (lang.json + nx_load_dictionary)

Tags operacionais

• Google Analytics
• GA4
• Measurement Protocol
• Data API
• Event Tracking
• SEO & Marketing
• OAuth
• Plugin NEXUS

Resultado operacional

• Eventos nativos do NEXUS (page_view, task_created, login_success…) no GA4 sem gtag.js no browser — gateway server-side sem cookies de terceiros.
• Privacidade: client_id pseudonimizado (SHA-256 + salt) e sanitização anti-PII antes do envio.
• Dashboard analítico: usuários, sessões e pageviews dos últimos 7 dias (gráfico), tempo real e top pages pela Data API.
• OAuth automático: refresh token renova o access token com cache (sem intervenção).
• Controle fino: seleção de quais eventos encaminhar + toggles (forward, plugin, anonymize).
• i18n PT/EN e comando /ga4 no chat.
• Sob demanda: sem cron, sem custo de processamento periódico.