- How do I install the Filament Umami plugin?
- Install it with Composer using composer require jeffersongoncalves/filament-umami, then register the plugin in your Filament panel provider. The package is a Filament plugin, so it is added to a panel rather than wired up by hand in a service provider. If your project pins filament-analytics-core below 3.1, upgrade that dependency first because release 3.5.0 expects 3.1 or higher.
- Which Filament versions does this Umami plugin support?
- It supports Filament v3, v4, and v5. That range covers Filament 3.x and 4.x projects as well as the v5 line. Check your panel's Filament constraint before installing, because plugin APIs can differ between major versions.
- Do I need filament-analytics-core installed for this plugin?
- Yes, the plugin builds on filament-analytics-core, and release 3.5.0 expects core 3.1 or newer. If your lockfile pins an older core version, Composer resolution or the newer navigationGroup behavior may not work as documented. Upgrade the core package and re-test the analytics panel after the bump.
- How do I configure Umami in my Filament panel?
- The plugin adds a Settings Page inside your Filament panel where you manage the Umami configuration. It also injects the Umami tracking script, so you do not have to edit your Blade layout manually. Open the settings page after registering the plugin and enter your Umami details there.
- Can I move the Umami settings page to a custom navigation group?
- Yes. Release 3.5.0 adds navigationGroup() to the plugin registration object, accepting either a string or a Closure. Chain it where you call Plugin::make(), alongside your existing navigation settings. If you do not set it, the plugin keeps its default translated navigation group.
- What arguments does the navigationGroup Closure receive?
- The release notes for 3.5.0 do not document the Closure signature, so the argument list and return semantics are not formally specified. Treat per-tenant or per-panel dynamic groups as unverified until you check the package source or tests. For predictable behavior, pass a plain string group name first and only move to a Closure when you can confirm how it is evaluated.
- What happens if the navigation group name I set does not exist?
- Filament accepts the string without a hard failure, so a typo can leave the settings page orphaned or oddly ordered rather than throwing an exception. This is a configuration-correctness risk, not a crash risk. Double-check the group name against the navigation groups registered in your panel.
- Is this plugin safe to run in production?
- The integration is low risk: it registers a Filament settings page and injects a client-side tracking script, with no migrations, config publishing, or asset rebuild implied. The main production concern is the dependency floor on filament-analytics-core 3.1 or newer. Run your analytics panel smoke test after upgrading and verify the tracking request in staging before deploying.
- How can I test that Umami tracking is working?
- Open your Filament panel after registering the plugin and confirm the Umami tracking request is sent from the page. Then check your Umami dashboard for the corresponding page view or event. If nothing appears, re-check the settings page configuration and confirm the script is being injected into the panel layout.
- Why use this plugin instead of adding the Umami script manually?
- Manually adding Umami means editing your panel layout or Blade views and managing the site ID yourself. This plugin packages the script injection with a Filament Settings Page, so configuration lives inside the admin panel. The trade-off is an extra Composer dependency on filament-analytics-core and a plugin registration in your panel provider.