Analytics Laravel Package

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.

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.

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.

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)

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.

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

First Beta Release\nThis is the first beta release of ArtisanPack UI Analytics, a privacy-first analytics package for Laravel applications built on Livewire 3.\n### Highlights\n- Privacy First: Local database storage for complete data ownership\n- GDPR Compliant: Built-in consent management with Do Not Track support\n- Real-Time Dashboard: Beautiful Livewire dashboard with live visitor counts\n- Multi-Tenant Support: Domain, subdomain, API key, and header-based resolution\n- External Providers: Optional integration with Google Analytics 4 and Plausible\n- Laravel 11 and 12 Support: Compatible with current Laravel versions\n- Livewire 3.6+ Compatible: Built for the latest Livewire features\n### Added\n#### Core Features\n- Analytics Dashboard Component: Full-featured Livewire dashboard with all widgets\n- Page View Tracking: Track visitors, sessions, and page views with device/browser detection\n- Event Tracking: Custom event tracking with categories, actions, and values\n- Session Management: Track session duration, page depth, and bounce rates\n- Visitor Resolution: Fingerprint-based visitor identification with IP anonymization\n#### Livewire Components\n- AnalyticsDashboard: Full-featured analytics dashboard with all widgets\n- StatsCards: Summary statistics (page views, visitors, sessions, bounce rate)\n- VisitorsChart: Interactive line chart of visitors over time\n- TopPages: Most visited pages table with view counts\n- TrafficSources: Referrer breakdown with percentage charts\n- RealtimeVisitors: Live count of active visitors\n- GoalProgress: Goal completion tracking with progress bars\n- ConsentBanner: GDPR consent collection banner\n- SiteSelector: Multi-tenant site switcher\n- PageAnalytics: Per-page analytics view\n#### Goal Tracking\n- Goal Creation: Define conversion goals with URL patterns, events, or page views\n- Conversion Tracking: Automatic goal matching and conversion recording\n- Goal Progress: Track completion rates and target progress\n- Funnel Analysis: Analyze user paths through conversion funnels\n#### Multi-Tenant Support\n- Site Model: Multi-site support with domain configuration\n- Domain Resolver: Match sites by full domain\n- Subdomain Resolver: Match sites by subdomain prefix\n- API Key Resolver: Match sites by API key authentication\n- Header Resolver: Match sites by custom HTTP headers\n- Cross-Tenant Reporting: Aggregate data across multiple sites\n#### Privacy & Compliance\n- Consent Management: Configurable consent requirements before tracking\n- Do Not Track Support: Honor browser DNT headers\n- IP Anonymization: GDPR-compliant IP address handling\n- Data Deletion Service: Remove visitor data on request\n- Cookie Configuration: Customizable consent cookie settings\n#### External Providers\n- Local Provider: Built-in database storage provider\n- Google Analytics 4 Provider: Send data to GA4 via Measurement Protocol\n- Plausible Provider: Send data to Plausible Analytics\n- Provider Interface: Create custom providers for any analytics service\n#### Artisan Commands\n- analytics:install: Install the package with migrations, config, and assets\n- analytics:create-site: Create a new analytics site for multi-tenant setups\n- analytics:list-sites: List all configured analytics sites\n- analytics:regenerate-api-key: Regenerate API key for a site\n- analytics:cleanup: Clean up old data based on retention settings\n- analytics:stats: Display quick statistics from the command line\n- analytics:realtime: Show real-time visitor count\n- analytics:goals-list: List all configured goals\n- analytics:clear-cache: Clear analytics cache\n#### Data Management\n- Data Retention: Configurable retention period with automatic cleanup\n- Data Aggregation: Aggregate raw data into summary tables\n- Data Export Service: Export analytics data to various formats\n- Queue Processing: High-performance async tracking for busy sites\n#### Events\n- PageViewRecorded: Dispatched when a page view is recorded\n- EventTracked: Dispatched when a custom event is tracked\n- SessionStarted: Dispatched when a new session begins\n- GoalConverted: Dispatched when a goal is completed\n- ConsentGiven: Dispatched when user grants consent\n- ConsentRevoked: Dispatched when user revokes consent\n#### Services\n- TrackingService: Record page views and events\n- SessionManager: Manage visitor sessions\n- VisitorResolver: Resolve and track unique visitors\n- DeviceDetector: Detect device type, browser, and OS\n- IpAnonymizer: Anonymize IP addresses for privacy\n- GoalService: Manage and evaluate goals\n- GoalMatcher: Match events and page views to goals\n- ConsentService: Manage user consent\n- FunnelAnalyzer: Analyze conversion funnels\n- EventProcessor: Process and store events\n- TenantManager: Manage multi-tenant site resolution\n- DataDeletionService: Handle GDPR data deletion requests\n- DataExportService: Export analytics data\n- CrossTenantReporting: Generate cross-site reports\n#### API & Controllers\n- TrackerController: Handle tracking API requests\n- ConsentController: Handle consent API requests\n- SiteApiController: Site management API for multi-tenant\n- AnalyticsQueryController: Query API for dashboard data\n- API Key Authentication: Guard for API key-based access\n#### Middleware\n- PrivacyFilter: Apply privacy settings and consent checks\n- TenantResolver: Resolve current site in multi-tenant mode\n- AnalyticsThrottle: Rate limiting for tracking endpoints\n- AuthenticateWithApiKey: API key authentication\n#### Extensibility\n- Filter Hooks: Modify tracking data before recording\n- Custom Providers: Add new analytics provider integrations\n- Custom Resolvers: Create custom site resolution strategies\n- Publishable Views: Customize all Blade views\n- Publishable Config: Full configuration customization\n### Infrastructure\n- Comprehensive Test Suite: Full test coverage with Pest PHP\n- Code Style: PHP-CS-Fixer and PHPCS with ArtisanPackUI standards\n- Static Analysis: PHPStan analysis\n- GitLab CI/CD: Multi-PHP version testing (8.2, 8.3, 8.4)\n- Code Coverage: Coverage reporting with Cobertura format\n- Security Scanning: SAST, Secret Detection, Dependency Scanning\n- WordPress-Style Documentation: Full PHPDoc blocks on all classes and methods

First Stable Release\nThis is the first stable release of ArtisanPack UI Analytics.\n### Changes from Beta\n- No functional changes from 1.0.0-beta1\n- Production ready release\n---\n## [1.0.0-beta1] - 2026-01-12\n### First Beta Release\nThis is the first beta release of ArtisanPack UI Analytics, a privacy-first analytics package for Laravel applications built on Livewire 3.\n### Highlights\n- Privacy First: Local database storage for complete data ownership\n- GDPR Compliant: Built-in consent management with Do Not Track support\n- Real-Time Dashboard: Beautiful Livewire dashboard with live visitor counts\n- Multi-Tenant Support: Domain, subdomain, API key, and header-based resolution\n- External Providers: Optional integration with Google Analytics 4 and Plausible\n- Laravel 11 and 12 Support: Compatible with current Laravel versions\n- Livewire 3.6+ Compatible: Built for the latest Livewire features\n### Added\n#### Core Features\n- Analytics Dashboard Component: Full-featured Livewire dashboard with all widgets\n- Page View Tracking: Track visitors, sessions, and page views with device/browser detection\n- Event Tracking: Custom event tracking with categories, actions, and values\n- Session Management: Track session duration, page depth, and bounce rates\n- Visitor Resolution: Fingerprint-based visitor identification with IP anonymization\n#### Livewire Components\n- AnalyticsDashboard: Full-featured analytics dashboard with all widgets\n- StatsCards: Summary statistics (page views, visitors, sessions, bounce rate)\n- VisitorsChart: Interactive line chart of visitors over time\n- TopPages: Most visited pages table with view counts\n- TrafficSources: Referrer breakdown with percentage charts\n- RealtimeVisitors: Live count of active visitors\n- GoalProgress: Goal completion tracking with progress bars\n- ConsentBanner: GDPR consent collection banner\n- SiteSelector: Multi-tenant site switcher\n- PageAnalytics: Per-page analytics view\n#### Goal Tracking\n- Goal Creation: Define conversion goals with URL patterns, events, or page views\n- Conversion Tracking: Automatic goal matching and conversion recording\n- Goal Progress: Track completion rates and target progress\n- Funnel Analysis: Analyze user paths through conversion funnels\n#### Multi-Tenant Support\n- Site Model: Multi-site support with domain configuration\n- Domain Resolver: Match sites by full domain\n- Subdomain Resolver: Match sites by subdomain prefix\n- API Key Resolver: Match sites by API key authentication\n- Header Resolver: Match sites by custom HTTP headers\n- Cross-Tenant Reporting: Aggregate data across multiple sites\n#### Privacy & Compliance\n- Consent Management: Configurable consent requirements before tracking\n- Do Not Track Support: Honor browser DNT headers\n- IP Anonymization: GDPR-compliant IP address handling\n- Data Deletion Service: Remove visitor data on request\n- Cookie Configuration: Customizable consent cookie settings\n#### External Providers\n- Local Provider: Built-in database storage provider\n- Google Analytics 4 Provider: Send data to GA4 via Measurement Protocol\n- Plausible Provider: Send data to Plausible Analytics\n- Provider Interface: Create custom providers for any analytics service\n#### Artisan Commands\n- analytics:install: Install the package with migrations, config, and assets\n- analytics:create-site: Create a new analytics site for multi-tenant setups\n- analytics:list-sites: List all configured analytics sites\n- analytics:regenerate-api-key: Regenerate API key for a site\n- analytics:cleanup: Clean up old data based on retention settings\n- analytics:stats: Display quick statistics from the command line\n- analytics:realtime: Show real-time visitor count\n- analytics:goals-list: List all configured goals\n- analytics:clear-cache: Clear analytics cache\n#### Data Management\n- Data Retention: Configurable retention period with automatic cleanup\n- Data Aggregation: Aggregate raw data into summary tables\n- Data Export Service: Export analytics data to various formats\n- Queue Processing: High-performance async tracking for busy sites\n#### Events\n- PageViewRecorded: Dispatched when a page view is recorded\n- EventTracked: Dispatched when a custom event is tracked\n- SessionStarted: Dispatched when a new session begins\n- GoalConverted: Dispatched when a goal is completed\n- ConsentGiven: Dispatched when user grants consent\n- ConsentRevoked: Dispatched when user revokes consent\n#### Services\n- TrackingService: Record page views and events\n- SessionManager: Manage visitor sessions\n- VisitorResolver: Resolve and track unique visitors\n- DeviceDetector: Detect device type, browser, and OS\n- IpAnonymizer: Anonymize IP addresses for privacy\n- GoalService: Manage and evaluate goals\n- GoalMatcher: Match events and page views to goals\n- ConsentService: Manage user consent\n- FunnelAnalyzer: Analyze conversion funnels\n- EventProcessor: Process and store events\n- TenantManager: Manage multi-tenant site resolution\n- DataDeletionService: Handle GDPR data deletion requests\n- DataExportService: Export analytics data\n- CrossTenantReporting: Generate cross-site reports\n#### API & Controllers\n- TrackerController: Handle tracking API requests\n- ConsentController: Handle consent API requests\n- SiteApiController: Site management API for multi-tenant\n- AnalyticsQueryController: Query API for dashboard data\n- API Key Authentication: Guard for API key-based access\n#### Middleware\n- PrivacyFilter: Apply privacy settings and consent checks\n- TenantResolver: Resolve current site in multi-tenant mode\n- AnalyticsThrottle: Rate limiting for tracking endpoints\n- AuthenticateWithApiKey: API key authentication\n#### Extensibility\n- Filter Hooks: Modify tracking data before recording\n- Custom Providers: Add new analytics provider integrations\n- Custom Resolvers: Create custom site resolution strategies\n- Publishable Views: Customize all Blade views\n- Publishable Config: Full configuration customization\n### Infrastructure\n- Comprehensive Test Suite: Full test coverage with Pest PHP\n- Code Style: PHP-CS-Fixer and PHPCS with ArtisanPackUI standards\n- Static Analysis: PHPStan analysis\n- GitLab CI/CD: Multi-PHP version testing (8.2, 8.3, 8.4)\n- Code Coverage: Coverage reporting with Cobertura format\n- Security Scanning: SAST, Secret Detection, Dependency Scanning\n- WordPress-Style Documentation: Full PHPDoc blocks on all classes and methods