Sobre o projeto

laravel-analytics é um pacote Laravel desenvolvido pela Spatie para recuperar dados de analytics do Google Analytics usando a Google Analytics Data API. ## Recursos O pacote expõe uma facade `Spatie\Analytics\Facades\Analytics` com vários métodos de conveniência: - `fetchMostVisitedPages(Period $period, int $maxResults = 20)` — retorna fullPageUrl, pageTitle, screenPageViews - `fetchVisitorsAndPageViews(Period $period)` — retorna activeUsers e screenPageViews - `fetchVisitorsAndPageViewsByDate(Period $period)` — adiciona uma chave date por linha - `fetchTotalVisitorsAndPageViews(Period $period)` — agrega totais por data - `fetchTopReferrers(Period $period, int $maxResults = 20)` — retorna pageReferrer e screenPageViews - `fetchUserTypes(Period $period)` — retorna usuários novos vs recorrentes - `fetchTopBrowsers(Period $period, int $maxResults = 10)` — retorna browser e screenPageViews - `fetchTopCountries(Period $period, int $maxResults = 10)` — retorna country e screenPageViews - `fetchTopOperatingSystems(Period $period, int $maxResults = 10)` — retorna operatingSystem e screenPageViews - `get(Period $period, array $metrics, array $dimensions = [], ...)` — consultas arbitrárias GA4 com ordenação, paginação, filtros de dimensão e filtros de métrica Todos os métodos retornam uma `Illuminate\Support\Collection` de arrays. ## Instalação ```bash composer require spatie/laravel-analytics ``` Opcionalmente, publique a configuração: ```bash php artisan vendor:publish --tag="analytics-config" ``` A configuração publicada em `config/analytics.php` requer: - `property_id`: seu ID da propriedade GA4 - `service_account_credentials_json`: caminho para uma chave JSON da service account, ou um array contendo as credenciais - `cache_lifetime_in_minutes`: padrão 1440 minutos; defina como 0 para desativar o caching - `cache.store` e prefixo/vida útil opcionais para o cache subjacente ## Configuração de autenticação 1. Crie um projeto no [Google Cloud Console](https://console.developers.google.com/apis) 2. Ative a **Google Analytics Data API** na API Library 3. Crie uma service account e faça download da chave JSON 4. Compartilhe sua propriedade GA4 com o email da service account com pelo menos o papel Analyst 5. Armazene o arquivo JSON de forma segura e aponte a configuração para ele ## Períodos A classe `Spatie\Analytics\Period` suporta: ```php Period::days(7) Period::months(6) Period::create($startDate, $endDate) // aceita instâncias Carbon ``` ## Testes com fakes A facade oferece um método `fake` para testes unitários e de feature: ```php use Spatie\Analytics\Facades\Analytics; Analytics::fake(); // ou com respostas predefinidas Analytics::fake([ ['pageTitle' => 'Home', 'activeUsers' => 10, 'screenPageViews' => 20], ]); ``` Os testes do pacote podem ser executados com: ```bash vendor/bin/pest ``` ## Licença Licenciado sob MIT. Veja o LICENSE do repositório para detalhes.