- How do I install the laravel-umami package?
- Install it with Composer by running composer require jeffersongoncalves/laravel-umami. Publish the package assets so its configuration and settings migrations land in your application, then run php artisan migrate to create the settings records. Finally, set your Umami script URL and website ID through the settings and place the tracking component in your Blade layout.
- Which Laravel versions does laravel-umami support?
- The package targets current Laravel releases that ship with the Vite integration, because the CSP nonce feature added in v3.1.0 reads the nonce exposed by Laravel's Vite facade. Check the composer.json constraints in the repository before upgrading, since a Laravel minor that does not expose that accessor could change behaviour or fail. If you are on an older Laravel version, confirm nonce handling in a test environment first.
- How do I track a pageview or send a custom event with Umami in Laravel?
- The package ships simple helpers so you can record a pageview or send a named event to Umami without writing your own JavaScript. Use the pageview helper for visits you want to log outside the automatic script tracking, and the event helper for actions such as signups, checkout steps, or downloads. Both helpers send to the Umami instance configured in your package settings.
- Where do I configure the Umami website ID and script URL?
- Configuration is database-driven through spatie/laravel-settings instead of a static config file, so the website ID, script URL, and related options can change at runtime. After publishing and running the migrations you edit the settings values directly in the database or through your own admin screen. That means you can point at a different Umami instance without redeploying the application.
- How do I add the Umami tracking script to my Blade layout?
- Render the package's tracking script component inside the head of your main Blade layout so every page is tracked automatically. Because it is a Blade component you can also include it in a smaller partial when only some pages should report to Umami. Keep it outside cached fragments where possible so the markup stays per-request.
- Does laravel-umami work with a self-hosted Umami instance?
- Yes. Umami is built to be self-hosted, and the package only needs the script URL and website ID of your instance, both of which are stored in the settings. Cloud Umami works the same way as long as you supply the correct script source and site identifier. Nothing in the package assumes a specific hosting provider.
- How does laravel-umami handle Content Security Policy nonces?
- Version 3.1.0 reads the nonce that Laravel's Vite integration exposes, so scripts emitted by the package carry the same nonce as your Vite assets when you call Vite::useCspNonce or use a headers package that does so for you. If your application does not set a Vite nonce, the script renders without one and behaviour is unchanged for non-CSP deployments. A nonce set through a custom mechanism outside Vite may not be picked up, so verify that path if you roll your own.
- Will the Umami tracking script break behind a full-page or CDN cache?
- Nonces are per-request values, so any full-page cache, response cache, or CDN edge that stores HTML containing the script will serve a stale nonce and the browser will block it. If you cache pages, exclude the fragment that renders the tracking script or bypass caching for those responses. Verify in a cached, production-like environment, since this failure is silent and never shows up in uncached local testing.
- Can I disable Umami tracking in local or testing environments?
- The usual approach is to gate rendering on the environment, for example only outputting the tracking component when the application is in production. Keeping analytics off during tests also avoids stray HTTP calls from CI runs. If the package exposes an enabled flag in its settings, switch that off rather than wrapping every layout in conditionals.
- What are the alternatives to laravel-umami for Laravel analytics?
- You can paste the raw Umami script tag into your layout yourself, which is fine until you need runtime configuration or server-side event tracking. Other options include broader analytics packages such as spatie/laravel-analytics for Google Analytics, or small helpers you write against the Umami API. laravel-umami is a good fit when you specifically want Umami with database-driven settings and Blade components.