Problem/Motivation
Umami provides two separate tracking snippets per website: the standard
pageview/event tracker (script.js) and, for sites with session
replay/heatmaps enabled, a second recorder script
(recorder.js). Both are simple
<script defer src="..." data-website-id="..."> tags using
the same website ID, e.g.:
The Umami Analytics module currently only ever outputs the tracking script
tag. There is no way to also emit the recorder script, so site owners who
want session replay / heatmap data have no supported way to enable it
through this module.
Steps to reproduce
- Enable session recording/heatmaps for a website in Umami.
- Configure Umami Analytics on a Drupal site with a valid Umami
URL and Web site ID. - Note that there is no setting to add the corresponding
recorder.jsscript tag, so it must be added manually outside
the module.
Proposed resolution
Add an opt-in "Recorder" setting to the module:
- New config keys
recorder_enabled(boolean) and
recorder_src(string), alongside the existingsrc
/website_id. - A checkbox + URL field on the settings form (
/admin/config/services/umami-analytics)
to enable the recorder and specify its script URL, reusing the existing
website_idvalue. - Extend
hook_page_attachments()to emit a second
<script defer>tag for the recorder when enabled,
independent of whether the main tracking script is configured, so the two
features can be toggled separately. - The recorder script tag would honor the module's existing page/role
visibility settings, since it's attached in the same request-scoped hook.<
Remaining tasks
Implement config schema + form changes.Done in MR !6.ImplementDone in MR !6.hook_page_attachments()changes.Update README with recorder configuration instructions.Done in MR !6.- Add automated test coverage for the recorder (no existing test suite in this module to extend — would need a first Kernel test covering
hook_page_attachments()with the recorder enabled, disabled, and enabled standalone without the main tracking script). - Community/maintainer review of MR !6.
User interface changes
Adds a new "Recorder" section to the settings form: an enable checkbox and
a script URL text field, following the same pattern as the existing
tracking script settings.
API changes
None — this only adds new, optional configuration keys with sensible
(disabled) defaults. Existing installs are unaffected.
Data model changes
Adds two keys to umami_analytics.settings config:
recorder_enabled (boolean, default false) and
recorder_src (string, default empty). Config schema updated
accordingly.
Issue fork umami_analytics-3608039
Show commands
Start within a Git clone of the project using the version control instructions.
Or, if you do not have SSH keys set up on git.drupalcode.org:
Comments
Comment #2
davidsonjames commentedComment #3
davidsonjames commentedComment #5
davidsonjames commentedComment #6
davidsonjames commented