README

Laravel Amplitude

This Laravel package seamlessly integrates the Amplitude Browser SDK into your Blade templates. Easily track user interactions, page views, and product usage directly within your Laravel application, with all configuration managed via database settings using spatie/laravel-settings.

Requirements

PHP 8.2+
Laravel 12+
spatie/laravel-settings configured (the settings table must exist)

Installation

Install the package via composer:

composer require jeffersongoncalves/laravel-amplitude

If you haven't already, publish the spatie/laravel-settings migration to create the settings table:

php artisan vendor:publish --provider="Spatie\LaravelSettings\LaravelSettingsServiceProvider" --tag="migrations"

Then publish and run the Amplitude settings migration:

php artisan vendor:publish --tag=amplitude-settings-migrations
php artisan migrate

Usage

Add the Amplitude script to your Blade layout (typically before </head>):

@include('amplitude::script')

Configuring Settings

Settings are stored in the database and can be managed via code:

use JeffersonGoncalves\Amplitude\Settings\AmplitudeSettings;

$settings = app(AmplitudeSettings::class);
$settings->api_key = 'YOUR_AMPLITUDE_API_KEY';
$settings->save();

Data Residency

Amplitude supports data residency in the US and EU. Set the server_zone accordingly:

// EU Data Residency
$settings->server_zone = 'EU';
$settings->save();

To route ingestion through your own endpoint instead, set server_url (this takes precedence over server_zone):

$settings->server_url = 'https://proxy.yourdomain.com';
$settings->save();

Proxy Configuration

To load the Amplitude loader script from your own proxy/self-hosted copy instead of https://cdn.amplitude.com/script/{api_key}.js:

$settings->custom_lib_url = 'https://proxy.yourdomain.com/amplitude.js';
$settings->save();

Available Settings

Property	Type	Default	Description
`api_key`	`?string`	`null`	Your Amplitude project API key (required for tracking)
`server_zone`	`string`	`'US'`	Data residency: `'US'` or `'EU'`
`server_url`	`?string`	`null`	Custom ingestion endpoint (proxy); overrides `server_zone` when set
`custom_lib_url`	`?string`	`null`	Self-hosted/proxy URL for the loader script, replacing `https://cdn.amplitude.com/script/{api_key}.js`
`autocapture`	`bool`	`true`	Enable Amplitude's built-in autocapture (page views, sessions, form interactions, file downloads, attribution)
`identity_storage`	`string`	`'cookie'`	`'cookie'`, `'localStorage'`, or `'none'`
`cookie_domain`	`?string`	`null`	Cookie domain, for cross-subdomain tracking
`cookie_expiration`	`int`	`365`	Cookie expiration in days
`secure_cookie`	`bool`	`false`	HTTPS-only cookies
`session_timeout_minutes`	`int`	`30`	Session timeout in minutes (converted to milliseconds in JS config)
`min_id_length`	`?int`	`null`	Minimum length for user/device IDs
`opt_out`	`bool`	`false`	Initialize with tracking opted out
`debug`	`bool`	`false`	Enable Amplitude debug logging (maps to `LogLevel.Debug`/`LogLevel.None`)
`flush_queue_size`	`int`	`30`	Batch size before auto-flush
`flush_interval_millis`	`int`	`1000`	Auto-flush interval in milliseconds

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

jeffersongoncalves / laravel-amplitude

Maintainers

Package info

Fund package maintenance!

Statistics

Security