A transição de plataformas de analytics proprietárias para soluções auto-hospedadas é um movimento crescente entre equipes técnicas que priorizam conformidade com LGPD/GDPR e soberania sobre seus dados. No entanto, migrar anos de histórico consolidado no Google Analytics (GA4 ou Universal Analytics) para uma instalação Matomo on-premise apresenta desafios técnicos específicos: limites de cota de API, mapeamento correto de dimensões e a necessidade de processar múltiplos sites sob a mesma conta sem perda de fidelidade.

Neste artigo, você entenderá como arquitetar um pipeline de migração pontual utilizando Python para extrair métricas históricas de diferentes propriedades e ingeri-las de forma estruturada no Matomo.

O Cenário: 1 Conta, Múltiplos Domínios e Consistência de Dados

Quando gerenciamos uma conta corporativa com diferentes domínios (neste caso, seis páginas ou aplicações distintas), a importação manual via interface nativa do Matomo pode ser lenta e suscetível a interrupções de timeout. Cada site possui seu próprio siteId no Matomo e correspondente Property ID no Google Analytics.

Para garantir que o processo seja resiliente, a melhor abordagem envolve construir uma rotina ETL (Extract, Transform, Load) programática com as seguintes fases:

1. Autenticação e Extração: Consulta à Google Analytics Data API em batches diários.
2. Normalização: Conversão de schemas, mapeamento de URLs canônicas, eventos e metas para a taxonomia do Matomo.
3. Carga em Lote (Tracking Web API / Bulk Import): Envio dos logs processados diretamente para a API do Matomo ou inserção em banco com tratamento de filas.

Estrutura do Pipeline em Python

Utilizamos a biblioteca oficial google-analytics-data para recuperar métricas e dimensões agregadas, estruturando a paginação para não estourar os limites de requisição.

python
from google.analytics.datav1beta import BetaAnalyticsDataClient
from google.analytics.datav1beta.types import DateRange, Dimension, Metric, RunReportRequest
import requests
import json

class GAMatomoMigrator:
def init(self, gacredentialspath, matomourl, matomotoken):
self.client = BetaAnalyticsDataClient.fromserviceaccountjson(gacredentialspath)
self.matomourl = matomourl
self.matomotoken = matomo_token

def fetch_ga_daily_report(self, property_id, start_date, end_date):
    request = RunReportRequest(
        property=f"properties/{property_id}",
        dimensions=[Dimension(name="date"), Dimension(name="pagePath"), Dimension(name="country")],
        metrics=[Metric(name="activeUsers"), Metric(name="screenPageViews")],
        date_ranges=[DateRange(start_date=start_date, end_date=end_date)],
    )
    return self.client.run_report(request)

def send_to_matomo(self, matomo_site_id, tracking_payload):
    endpoint = f"{self.matomo_url}/matomo.php"
    params = {
        "idsite": matomo_site_id,
        "rec": 1,
        "token_auth": self.matomo_token
    }
    params.update(tracking_payload)
    response = requests.post(endpoint, params=params)
    return response.status_code == 200

Mapeamento Concorrente para Múltiplas Propriedades

Com 6 páginas distintas, a execução sequencial pode levar horas ou dias, dependendo do volume diário de visitas. Para mitigar isso, empregamos execução concorrente com ThreadPoolExecutor ou asyncio, associada a um dicionário de configuração centralizado:

python
from concurrent.futures import ThreadPoolExecutor

SITESCONFIG = [
{“gaproperty”: “123456781”, “matomositeid”: 1},
{“gaproperty”: “123456782”, “matomositeid”: 2},
{“gaproperty”: “123456783”, “matomositeid”: 3},
{“gaproperty”: “123456784”, “matomositeid”: 4},
{“gaproperty”: “123456785”, “matomositeid”: 5},
{“gaproperty”: “123456786”, “matomosite_id”: 6},
]

def runmigrationforsite(migrator, siteinfo):
print(f”Iniciando migração para o Site ID: {siteinfo[‘matomosite_id’]}”)
# Executa lógica de batching e envio com retries automáticos
pass

Orquestração paralela controlada

with ThreadPoolExecutor(maxworkers=3) as executor:
for site in SITESCONFIG:
executor.submit(runmigrationfor_site, None, site)

Essa abordagem permite isolar falhas de rede: caso a migração do Site 3 encontre um erro de paginação, o progresso dos demais domínios permanece preservado em log.

Considerações de Performance e Integridade

• Controle de Cota da API do Google: Monitore a resposta de quota no cabeçalho das requisições para evitar bloqueios de 24 horas (RESOURCE_EXHAUSTED).
• Timestamp Spoofing no Matomo: Para importar dados históricos preservando a data original, o parâmetro cdt (Custom Date Time) deve ser utilizado, exigindo que o token de autenticação possua permissões administrativas na instância Matomo.
• Desativação Temporária do Arquivamento: Durante a importação em massa, desative o auto-arquivamento em tempo real do Matomo via painel (config.ini.php) e processe relatórios via cron job consolidado (core:archive) após o término da carga.

Como especialista em IA e engenharia de dados, costumo estruturar esses pipelines com checkpoints automáticos em banco SQLite local ou Redis, garantindo que o processo seja reiniciado exatamente de onde parou em caso de interrupção.

Conclusão e Próximos Passos

A migração do Google Analytics para uma infraestrutura Matomo on-premise assegura controle irrestrito sobre dados sensíveis, mas exige um script de migração robusto para consolidar múltiplos ativos sem corromper métricas históricas.

Se a sua empresa precisa planejar e executar migrações de dados analíticos complexas ou implementar fluxos automatizados em Python, entre em contato para avaliar uma consultoria técnica sob medida.