Analytics Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[1.4.0] - 2026-07-21

Changed

• Renamed hook ap.analytics.site_selector.query → ap.analytics.siteSelector.query to align with cross-package hooks convention. Old name registered as a deprecation alias. Alias removal deferred to next major.
• Bumped artisanpack-ui/hooks to ^1.3.

Notes

• PrivacyIntegration still subscribes to legacy privacy.* hook names. Those will be updated to ap.privacy.* after the privacy package's Wave 1 rename ships; aliases in that package keep the current subscriptions working in the meantime.

[1.3.0] - 2026-07-07

Added

AI-Powered Analytics Agents

Four opt-in AI features that plug into artisanpack-ui/ai to turn raw analytics into narrative insights. Every feature ships an Agent, Livewire component, React and Vue components, and API endpoint, and honors the shared FeatureRegistry toggle.

• Insight summary agent (analytics.insight_summary): Streaming plain-language summary of what changed over a date range, returning {summary, highlights[], concerns[]}. Backed by InsightSummaryAgent.
• Anomaly explanation agent (analytics.explain_anomaly): Generates ranked hypotheses for a traffic spike or drop with confidence scores, evidence, and recommended next steps. Backed by AnomalyExplanationAgent.
• Segment insight agent (analytics.segment_insight): Surfaces non-obvious patterns in a referrer, page, or time segment relative to a baseline, returning observations with significance and suggested actions. Backed by SegmentInsightAgent.
• Digest email agent (analytics.digest_email): Composes opt-in weekly or monthly narrative digest emails. Extends the shared SummarizationAgent and ships with SendDigestEmailJob, DigestEmailMailable, a text-focused email template, an AnalyticsDigestPreference model, and per-user cadence preferences (off | weekly | monthly).
• Livewire triggers: <livewire:artisanpack-analytics::ai.insight-summary />, ai.anomaly-explanation, ai.segment-insight, and ai.digest-subscription components with disabled states when the corresponding feature is toggled off.
• React and Vue components: InsightSummary, AnomalyExplanation, SegmentInsight, and DigestSubscription shipped for both frameworks, together with useAiAgent and useApi hooks/composables.
• API endpoints: New routes under /api/analytics/ai/* for each agent, gated behind the analytics.ai.use ability. Ships with a permissive default gate (any authenticated user); override in your AuthServiceProvider for stricter policies.
• Digest dispatch command: analytics:digests:dispatch artisan command queues SendDigestEmailJob for every subscribed user; wire it into the scheduler on your preferred cadence.
• aiFeatures() registration: AnalyticsServiceProvider::aiFeatures() registers all four features with the AI package's feature registry so admin UIs can list them.
• Migration: analytics_digest_preferences table for per-user digest cadence.
• Documentation: New AI features guide covering feature keys, Livewire and React/Vue usage, gate customization, and digest scheduling.

Added

• Laravel 13 support — widened illuminate/* constraints to ^11.0|^12.0|^13.0 and orchestra/testbench to ^9.0|^10.0|^11.0. No PHP-floor change for users staying on Laravel 11 or 12.

[1.2.0] - 2026-05-20

Added

AI Bot Traffic Filtering

A multi-layered system that keeps automated traffic — AI crawlers, SEO tools, scrapers, and headless browsers — out of reported analytics. Bot-flagged data is stored but excluded from dashboard and query results by default. Enabled by default.

• Expanded bot pattern list: DeviceDetector now matches 60+ known bots, including AI crawlers (GPTBot, ClaudeBot, CCBot, PerplexityBot), regional crawlers (ByteSpider, Baidu, Sogou, Yandex), SEO tools (SEMrush, Ahrefs, Majestic), and scraper/automation tooling
• BotDetector service: Multi-signal confidence scoring (0–100) with a configurable threshold (default 70), combining user agent, engagement, request-pattern, and JavaScript fingerprint signals
• Bot detection columns: is_bot, bot_score, and bot_detected_at added to the analytics_visitors table
• JS fingerprint signals: The tracker payload now collects privacy-preserving WebDriver, headless, and missing-API signals
• AnalyzeBotTraffic job: Post-hoc behavioral analysis that scores recent visitors on a configurable schedule
• Bot-aware query scoping: excludeBots(), includeBots()/withBots(), and onlyBots() modifiers on AnalyticsQuery, plus getTopBotAgents() and getBotStats(), with a dashboard toggle to view bot traffic
• Bot Traffic widget: New dashboard widget for Livewire, React, and Vue showing filtered bot traffic, the bot share of total traffic, top bot agents, and a bot-only trend
• Artisan commands: analytics:bots to list flagged visitors (with CSV export) and analytics:whitelist to manage runtime whitelist entries
• Runtime whitelist: BotWhitelistEntry model and analytics_bot_whitelist table supplementing the static config whitelist
• Configuration: New bot_detection config section for the threshold, whitelist, per-signal toggles, and analysis schedule
• Documentation: New Bot Filtering guide and Bot Traffic widget reference, plus updated configuration, artisan command, and API reference docs

Security

• Updated vulnerable transitive development dependencies to patched versions, clearing all reported advisories (10 advisories across 6 packages, including symfony/yaml CVE-2026-45133)

[1.1.1] - 2026-05-20

Fixed

• MySQL migration foreign key constraint name collision: Gave the analytics foreign keys explicit names so migrations no longer fail on MySQL with duplicate auto-generated constraint names.

[1.1.0] - 2026-04-10

Added

Inertia.js Dashboard Support

• InertiaDashboardController: New controller that returns Inertia responses with analytics data as typed page props for React/Vue dashboards
• Inertia routes: Dedicated routes for dashboard, pages, traffic, audience, events, and realtime views when dashboard_driver is set to 'inertia'
• Dashboard driver config: New dashboard_driver option ('livewire' or 'inertia') to select dashboard rendering strategy

React Dashboard Components

• AnalyticsDashboard: Main dashboard page component
• PageAnalytics: Per-page analytics detail view
• MultiTenantDashboard: Multi-site management dashboard
• StatsCards: Key metrics card grid widget
• VisitorsChart: Line chart of visitors/pageviews over time
• TopPages: Most viewed pages table
• TrafficSources: Traffic source breakdown
• RealtimeVisitors: Live visitor count with polling
• SiteSelector: Site picker for multi-tenant setups
• useAnalyticsApi hook: Generic data fetching with polling and AbortController support

Vue Dashboard Components

• AnalyticsDashboard, PageAnalytics, MultiTenantDashboard: Vue 3 SFC equivalents of React page components
• StatsCards, VisitorsChart, TopPages, TrafficSources, RealtimeVisitors, SiteSelector: Vue 3 SFC equivalents of React widget components
• useAnalyticsApi composable: Vue 3 composable equivalent of the React hook

Consent Management Components (React & Vue)

• ConsentBanner: Cookie consent bar with accept/reject/customize actions
• ConsentPreferences: Category-level consent toggles panel
• ConsentStatus: Compact consent status indicator with manage button
• useConsent hook/composable: Consent state management with localStorage persistence, cookie sync, and server API synchronization

TypeScript Type Definitions

• Shared type definitions for API responses, data models, enums, query params, and component props
• Types cover: StatsData, TopPageItem, TrafficSourceItem, breakdown types, realtime types, consent types, and all Eloquent model interfaces

API Resources

• StatsResource: Overall analytics statistics
• PageViewTimeSeriesResource: Time series chart data
• TopPageResource: Most viewed pages
• TrafficSourceResource: Traffic source breakdown
• BrowserBreakdownResource: Browser usage breakdown
• CountryBreakdownResource: Geographic breakdown
• DeviceBreakdownResource: Device type breakdown
• EventBreakdownResource: Custom event breakdown

Frontend Installation Command

• analytics:install-frontend: New Artisan command to publish React or Vue components and add npm dependencies (--stack=react|vue, --force)

Documentation

• New docs/frontend/ section with 7 pages covering overview, installation, React/Vue components, consent components, hooks/composables, and TypeScript types
• New docs/api/resources.md documenting all API resources
• Updated index pages, artisan commands docs, and mkdocs.yml navigation

Changed

• Livewire 4 support: Updated registerLivewireComponents() to use addNamespace API for Livewire 4, with fallback to individual component() calls for Livewire 3
• Route registration: registerRoutes() now delegates dashboard routing to registerDashboardRoutes() based on the configured driver
• Service provider: Added publishReactComponents(), publishVueComponents(), and registerInertiaSharedData() methods
• CI workflows: Added release/* branches to CI workflow triggers so PRs targeting release branches run lint and tests
• GitHub Actions: Separated release workflow into dedicated release.yml with Packagist update step; added Livewire 3.6/4.0 test matrix

Infrastructure

• Migrated from GitLab to GitHub
• Added GitHub Actions CI workflow, issue templates, and PR templates
• Updated PHP version requirement to 8.4

[1.0.0] - 2026-01-23

First Stable Release

This is the first stable release of ArtisanPack UI Analytics.

Changes from Beta

• No functional changes from 1.0.0-beta1
• Production ready release

[1.0.0-beta1] - 2026-01-12

First Beta Release

This is the first beta release of ArtisanPack UI Analytics, a privacy-first analytics package for Laravel applications built on Livewire 3.

Highlights

• Privacy First: Local database storage for complete data ownership
• GDPR Compliant: Built-in consent management with Do Not Track support
• Real-Time Dashboard: Beautiful Livewire dashboard with live visitor counts
• Multi-Tenant Support: Domain, subdomain, API key, and header-based resolution
• External Providers: Optional integration with Google Analytics 4 and Plausible
• Laravel 11 and 12 Support: Compatible with current Laravel versions
• Livewire 3.6+ Compatible: Built for the latest Livewire features

Added

Core Features

• Analytics Dashboard Component: Full-featured Livewire dashboard with all widgets
• Page View Tracking: Track visitors, sessions, and page views with device/browser detection
• Event Tracking: Custom event tracking with categories, actions, and values
• Session Management: Track session duration, page depth, and bounce rates
• Visitor Resolution: Fingerprint-based visitor identification with IP anonymization

Livewire Components

• AnalyticsDashboard: Full-featured analytics dashboard with all widgets
• StatsCards: Summary statistics (page views, visitors, sessions, bounce rate)
• VisitorsChart: Interactive line chart of visitors over time
• TopPages: Most visited pages table with view counts
• TrafficSources: Referrer breakdown with percentage charts
• RealtimeVisitors: Live count of active visitors
• GoalProgress: Goal completion tracking with progress bars
• ConsentBanner: GDPR consent collection banner
• SiteSelector: Multi-tenant site switcher
• PageAnalytics: Per-page analytics view

Goal Tracking

• Goal Creation: Define conversion goals with URL patterns, events, or page views
• Conversion Tracking: Automatic goal matching and conversion recording
• Goal Progress: Track completion rates and target progress
• Funnel Analysis: Analyze user paths through conversion funnels

Multi-Tenant Support

• Site Model: Multi-site support with domain configuration
• Domain Resolver: Match sites by full domain
• Subdomain Resolver: Match sites by subdomain prefix
• API Key Resolver: Match sites by API key authentication
• Header Resolver: Match sites by custom HTTP headers
• Cross-Tenant Reporting: Aggregate data across multiple sites

Privacy & Compliance

• Consent Management: Configurable consent requirements before tracking
• Do Not Track Support: Honor browser DNT headers
• IP Anonymization: GDPR-compliant IP address handling
• Data Deletion Service: Remove visitor data on request
• Cookie Configuration: Customizable consent cookie settings

External Providers

• Local Provider: Built-in database storage provider
• Google Analytics 4 Provider: Send data to GA4 via Measurement Protocol
• Plausible Provider: Send data to Plausible Analytics
• Provider Interface: Create custom providers for any analytics service

Artisan Commands

• analytics:install: Install the package with migrations, config, and assets
• analytics:create-site: Create a new analytics site for multi-tenant setups
• analytics:list-sites: List all configured analytics sites
• analytics:regenerate-api-key: Regenerate API key for a site
• analytics:cleanup: Clean up old data based on retention settings
• analytics:stats: Display quick statistics from the command line
• analytics:realtime: Show real-time visitor count
• analytics:goals-list: List all configured goals
• analytics:clear-cache: Clear analytics cache

Data Management

• Data Retention: Configurable retention period with automatic cleanup
• Data Aggregation: Aggregate raw data into summary tables
• Data Export Service: Export analytics data to various formats
• Queue Processing: High-performance async tracking for busy sites

Events

• PageViewRecorded: Dispatched when a page view is recorded
• EventTracked: Dispatched when a custom event is tracked
• SessionStarted: Dispatched when a new session begins
• GoalConverted: Dispatched when a goal is completed
• ConsentGiven: Dispatched when user grants consent
• ConsentRevoked: Dispatched when user revokes consent

Services

• TrackingService: Record page views and events
• SessionManager: Manage visitor sessions
• VisitorResolver: Resolve and track unique visitors
• DeviceDetector: Detect device type, browser, and OS
• IpAnonymizer: Anonymize IP addresses for privacy
• GoalService: Manage and evaluate goals
• GoalMatcher: Match events and page views to goals
• ConsentService: Manage user consent
• FunnelAnalyzer: Analyze conversion funnels
• EventProcessor: Process and store events
• TenantManager: Manage multi-tenant site resolution
• DataDeletionService: Handle GDPR data deletion requests
• DataExportService: Export analytics data
• CrossTenantReporting: Generate cross-site reports

API & Controllers

• TrackerController: Handle tracking API requests
• ConsentController: Handle consent API requests
• SiteApiController: Site management API for multi-tenant
• AnalyticsQueryController: Query API for dashboard data
• API Key Authentication: Guard for API key-based access

Middleware

• PrivacyFilter: Apply privacy settings and consent checks
• TenantResolver: Resolve current site in multi-tenant mode
• AnalyticsThrottle: Rate limiting for tracking endpoints
• AuthenticateWithApiKey: API key authentication

Extensibility

• Filter Hooks: Modify tracking data before recording
• Custom Providers: Add new analytics provider integrations
• Custom Resolvers: Create custom site resolution strategies
• Publishable Views: Customize all Blade views
• Publishable Config: Full configuration customization

Infrastructure

• Comprehensive Test Suite: Full test coverage with Pest PHP
• Code Style: PHP-CS-Fixer and PHPCS with ArtisanPackUI standards
• Static Analysis: PHPStan analysis
• GitLab CI/CD: Multi-PHP version testing (8.2, 8.3, 8.4)
• Code Coverage: Coverage reporting with Cobertura format
• Security Scanning: SAST, Secret Detection, Dependency Scanning
• WordPress-Style Documentation: Full PHPDoc blocks on all classes and methods