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

  1. Enable session recording/heatmaps for a website in Umami.
  2. Configure Umami Analytics on a Drupal site with a valid Umami
    URL
    and Web site ID.
  3. Note that there is no setting to add the corresponding
    recorder.js script 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 existing src
    / 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_id value.
  • Extend hook_page_attachments() to emit a second
    &lt;script defer&gt; 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.
  • Implement hook_page_attachments() changes. Done in MR !6.
  • 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.

Command icon 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

davidsonjames created an issue. See original summary.

davidsonjames’s picture

Issue summary: View changes
davidsonjames’s picture

Issue summary: View changes

davidsonjames’s picture

Status: Active » Needs review
davidsonjames’s picture

Issue summary: View changes