README

ArtisanPack UI Analytics is a privacy-first analytics package for Laravel applications. Built on Livewire 3, it provides local database storage for complete data ownership, GDPR-compliant consent management, real-time dashboards, multi-tenant support, and optional integration with Google Analytics 4 and Plausible.

Quick Start

Installation

# Install the package
composer require artisanpack-ui/analytics

# Run the installer (migrations, config, assets)
php artisan analytics:install

# Or manually publish and migrate
php artisan vendor:publish --provider="ArtisanPackUI\Analytics\AnalyticsServiceProvider"
php artisan migrate

Basic Usage

<!-- Add tracking scripts to your layout -->
@analyticsScripts

<!-- Add consent banner (if consent required) -->
@analyticsConsentBanner

<!-- Embed the full dashboard -->
<livewire:artisanpack-analytics::analytics-dashboard />

// Track page views programmatically
trackPageView('/products', 'Products Page');

// Track custom events
trackEvent('button_click', ['button_id' => 'signup']);

// Get visitor statistics
$stats = analyticsStats(DateRange::last30Days());

Key Features

• 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
• Session Tracking: Track visitors, sessions, page views, and bounce rates
• Event Tracking: Custom event tracking with categories and values
• Goal Tracking: Set up conversion goals with progress tracking
• Multi-Tenant Support: Domain, subdomain, API key, and header-based resolution
• External Providers: Optional integration with Google Analytics 4 and Plausible
• Queue Processing: High-performance async tracking for busy sites
• Data Retention: Configurable retention with automatic cleanup and aggregation
• IP Anonymization: GDPR-compliant IP address handling
• Bot Filtering: Automatic exclusion of known bots and crawlers

AI features

The Analytics package ships four AI agents that plug into artisanpack-ui/ai. Every feature is toggleable via the artisanpack.ai.features.{key}.enabled config (or the AI package's runtime registry) — Livewire, React, and Vue triggers all render a "disabled" state when a feature is off.

Livewire triggers

<livewire:artisanpack-analytics::ai.insight-summary
	:date-from="'2026-05-01'"
	:date-to="'2026-05-07'"
	:metrics="$weeklyMetrics"
/>

<livewire:artisanpack-analytics::ai.anomaly-explanation :anomaly="$anomaly" :context="$context" />
<livewire:artisanpack-analytics::ai.segment-insight ... />
<livewire:artisanpack-analytics::ai.digest-subscription />

React / Vue triggers

Publish the components alongside the analytics dashboards (analytics-react / analytics-vue publish tags) and mount them anywhere in your Inertia app:

import { InsightSummary } from '@/vendor/artisanpack-analytics/react/components/ai';

<InsightSummary
	api={ { baseUrl: '/api/analytics' } }
	dateRange={ { from: '2026-05-01', to: '2026-05-07' } }
	metrics={ weeklyMetrics }
/>

Enabling / disabling features

Every feature is opt-in per-app via config/artisanpack.php (merged from the AI package):

'ai' => [
	'features' => [
		'analytics.insight_summary' => [ 'enabled' => true ],
		'analytics.explain_anomaly' => [ 'enabled' => true ],
		'analytics.segment_insight' => [ 'enabled' => true ],
		'analytics.digest_email'    => [ 'enabled' => true ],
	],
],

Requests are gated by the analytics.ai.use gate. The ship default allows any authenticated user; override in your AuthServiceProvider for stricter policies.

Digest email opt-in

The analytics.digest_email feature is delivered via a queued job (SendDigestEmailJob) and honors a per-user preference stored in analytics_digest_preferences (off | weekly | monthly). Users pick their cadence via the DigestSubscription component; you schedule SendDigestEmailJob on your cadence of choice (the job is a no-op for users whose preference is off or missing).

use ArtisanPackUI\Analytics\Jobs\SendDigestEmailJob;

$schedule->call( function () {
	AnalyticsDigestPreference::where( 'cadence', 'weekly' )->each( function ( $preference ) {
		SendDigestEmailJob::dispatch(
			userId: $preference->user_id,
			email: $preference->user->email,
			items: $weeklyDigestItems( $preference->user ),
			periodLabel: 'Last 7 days',
		);
	} );
} )->weekly();

Components

Livewire Components

Widget Usage

<!-- Individual widgets -->
<livewire:artisanpack-analytics::stats-cards />
<livewire:artisanpack-analytics::visitors-chart />
<livewire:artisanpack-analytics::top-pages />
<livewire:artisanpack-analytics::traffic-sources />
<livewire:artisanpack-analytics::realtime-visitors />

<!-- With date range -->
<livewire:artisanpack-analytics::stats-cards
    :start-date="$startDate"
    :end-date="$endDate"
/>

<!-- Multi-tenant filtering -->
<livewire:artisanpack-analytics::analytics-dashboard
    :site-id="$tenant->site_id"
/>

Documentation

Comprehensive documentation is available at our Documentation Site:

• Getting Started - Quick start guide
• Installation Guide - Detailed setup instructions
• Configuration - All configuration options
• Tracking Page Views - Page view tracking
• Tracking Events - Custom event tracking
• Components - Dashboard and widget components
• Multi-Tenancy - Multi-tenant setup
• Privacy & Consent - GDPR compliance
• API Reference - Models, services, and events

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=analytics-config

Environment Variables

The package supports the following environment variables:

Configuration Options

Key configuration options in config/artisanpack/analytics.php:

return [
    // Enable/disable tracking
    'enabled' => env('ANALYTICS_ENABLED', true),

    // Active providers
    'active_providers' => ['local'], // Options: local, google, plausible

    // Local provider settings
    'local' => [
        'connection' => null,
        'table_prefix' => 'analytics_',
        'anonymize_ip' => true,
        'queue_processing' => true,
        'queue_name' => 'analytics',
    ],

    // Privacy settings
    'privacy' => [
        'consent_required' => false,
        'respect_dnt' => true,
        'cookie_name' => 'analytics_consent',
        'cookie_duration' => 365,
    ],

    // Data retention
    'retention' => [
        'period' => 90, // days, null = keep forever
        'aggregate_before_delete' => true,
    ],

    // Multi-tenant settings
    'multi_tenant' => [
        'enabled' => false,
        'resolver' => 'domain', // domain, subdomain, api_key, header
    ],

    // Dashboard settings
    'dashboard' => [
        'prefix' => 'analytics',
        'middleware' => ['web', 'auth'],
        'cache_duration' => 300,
    ],
];

Artisan Commands

# Install the package (migrations, config, assets)
php artisan analytics:install

# Create a new analytics site (multi-tenant)
php artisan analytics:create-site "Site Name" --domain=example.com

# List all configured sites
php artisan analytics:list-sites

# Regenerate API key for a site
php artisan analytics:regenerate-api-key {site_id}

# Clean up old data based on retention settings
php artisan analytics:cleanup

# Clean up data older than specific days
php artisan analytics:cleanup --days=30

# Preview cleanup without deleting
php artisan analytics:cleanup --dry-run

# Aggregate raw data into summary tables
php artisan analytics:aggregate

# Export analytics data
php artisan analytics:export --format=csv --output=analytics.csv

# Delete visitor data (GDPR compliance)
php artisan analytics:delete-visitor {visitor_id}

# Clear analytics cache
php artisan analytics:clear-cache

# Warm dashboard cache
php artisan analytics:warm-cache

# Display quick statistics
php artisan analytics:stats --period=month

Scheduling Commands

Add to your scheduler for automated maintenance:

// routes/console.php or bootstrap/app.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('analytics:cleanup')->daily();
Schedule::command('analytics:aggregate')->hourly();
Schedule::command('analytics:warm-cache')->hourly();

Requirements

• Laravel 11 or 12: PHP 8.2+
• Laravel 13: PHP 8.3+
• Livewire 3.6.4+

Dependencies

The package has minimal external dependencies:

• doctrine/dbal - Database abstraction
• nesbot/carbon - Date handling
• livewire/livewire - Reactive components

Optional integrations with the ArtisanPack UI ecosystem:

• artisanpack-ui/livewire-ui-components - UI components for dashboard
• artisanpack-ui/hooks - WordPress-style hooks for extensibility

Events

The package dispatches events for key actions:

use ArtisanPackUI\Analytics\Events\PageViewRecorded;
use ArtisanPackUI\Analytics\Events\EventTracked;
use ArtisanPackUI\Analytics\Events\SessionStarted;
use ArtisanPackUI\Analytics\Events\GoalCompleted;
use ArtisanPackUI\Analytics\Events\ConsentGiven;
use ArtisanPackUI\Analytics\Events\ConsentRevoked;

// Listen for page views
Event::listen(PageViewRecorded::class, function ($event) {
    // $event->pageView contains the page view model
});

// Listen for custom events
Event::listen(EventTracked::class, function ($event) {
    // $event->event contains the tracked event
});

// Listen for goal completions
Event::listen(GoalCompleted::class, function ($event) {
    // $event->goal contains the completed goal
    // $event->conversion contains the conversion record
});

Extensibility

Custom Analytics Providers

Create custom providers by implementing AnalyticsProviderInterface:

use ArtisanPackUI\Analytics\Contracts\AnalyticsProviderInterface;
use ArtisanPackUI\Analytics\Data\PageViewData;
use ArtisanPackUI\Analytics\Data\EventData;

class MixpanelProvider implements AnalyticsProviderInterface
{
    public function trackPageView(PageViewData $data): void
    {
        // Send to Mixpanel
    }

    public function trackEvent(EventData $data): void
    {
        // Send to Mixpanel
    }

    public function isEnabled(): bool
    {
        return config('services.mixpanel.enabled', false);
    }

    public function getName(): string
    {
        return 'mixpanel';
    }
}

// Register in a service provider
Analytics::extend('mixpanel', function ($app) {
    return new MixpanelProvider(config('services.mixpanel'));
});

Custom Site Resolvers (Multi-Tenant)

Create custom resolvers by implementing SiteResolverInterface:

use ArtisanPackUI\Analytics\Contracts\SiteResolverInterface;
use Illuminate\Http\Request;

class TeamResolver implements SiteResolverInterface
{
    public function resolve(Request $request): ?Site
    {
        $teamId = $request->user()?->current_team_id;
        return Site::where('team_id', $teamId)->first();
    }
}

// Register in config
'multi_tenant' => [
    'enabled' => true,
    'resolver' => App\Analytics\TeamResolver::class,
],

Filter Hooks

Extend functionality using filter hooks:

use function addFilter;

// Modify page view data before recording
addFilter('analytics.pageview.data', function (array $data) {
    $data['custom_dimension'] = 'value';
    return $data;
});

// Add custom excluded paths
addFilter('analytics.excluded_paths', function (array $paths) {
    $paths[] = '/internal/*';
    return $paths;
});

// Modify dashboard query
addFilter('analytics.dashboard.query', function ($query) {
    return $query->where('is_bot', false);
});

Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/your-feature)
3. Commit your changes (git commit -m 'Add feature')
4. Push to the branch (git push origin feature/your-feature)
5. Open a Merge Request

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting merge requests.

License

ArtisanPack UI Analytics is open-sourced software licensed under the MIT license.