Overview
What it does
Section titled “What it does”GA4 Reports copies aggregate Google Analytics 4 metrics into Capell on a schedule. The admin page and dashboard widgets read these local snapshots rather than calling Google during every page view, so a Google API outage does not remove the last successfully stored report.
Setup requirements
Section titled “Setup requirements”Run the package and settings migrations, then open Monitoring > GA4 Reports settings. Provide the numeric GA4 property ID without the properties/ prefix, an absolute path to a Google service-account JSON file, the number of days to sync, and the sync cron expression. Keep the credentials file outside the settings store, readable by the application but not publicly accessible, and grant that service account read access to the selected GA4 property.
Enable reporting only after the setup-status check recognises the property and credentials file. The file must contain valid service-account JSON with client_email and private_key values. You can also change the admin page slug; update bookmarks and internal links if you do.
Laravel’s scheduler must be running. The default cron expression is 0 2 * * *, which starts a daily sync at 02:00 in the application’s scheduler timezone. The package also schedules daily pruning of old sync-run history. These tasks run as scheduled commands rather than queued jobs.
Where it appears and who can use it
Section titled “Where it appears and who can use it”Open Monitoring > GA4 Reports for overview totals, traffic trend, top pages, setup status, last sync, and Sync now. Traffic, top-pages, and setup-status widgets can also be enabled on the main dashboard and Marketing Studio dashboard.
View:GA4ReportsPage controls access to the report page. That page permission also exposes Sync now, so grant it only to administrators who may make an immediate Google API request. Access to GA4 Reports settings follows the host application’s settings permissions.
Sync lifecycle and recovery
Section titled “Sync lifecycle and recovery”Each sync fetches the configured date window, upserts daily and page-level snapshots for the property, records row counts and status, then clears the report cache. A property-and-window lock prevents overlapping manual or scheduled runs. The scheduled task also uses single-server and overlap protection, which matters on multi-server installations.
The Google client uses a bounded timeout and retries transient HTTP failures; the defaults are three attempts with increasing delay. If the run still fails, Capell stores a redacted error and leaves existing snapshots available. It does not continually retry a failed run in the background. Check the setup-status and last-error display, correct the property access, credentials file, scheduler, or Google API failure, then select Sync now or wait for the next scheduled run. An already running message means another sync still holds the lock; do not start parallel runs.
Data visibility, privacy, and retention
Section titled “Data visibility, privacy, and retention”Capell stores the GA4 property ID and aggregate metrics by date, including users, sessions, views, engagement, events, key events, average session duration, and page paths and titles. It does not import visitor identifiers or raw GA4 events. Anyone who can view the report can see page-level analytics, so treat that permission as analytics-data access.
Sync history includes its window, status, row counts, timestamps, and a sanitised failure message. The credentials path is stored in settings, but credential contents remain in the referenced file and known secret values are removed from stored errors. Sync-run history is pruned after 90 days by default when the scheduler runs. That retention job does not delete the stored daily or page metric snapshots.
For how to use GA4 Reports, see the admin guide. For developers: see the README.