72 lines
3.8 KiB
Markdown
72 lines
3.8 KiB
Markdown
## ADDED Requirements
|
|
|
|
### Requirement: Umami pageview tracking
|
|
When Umami is enabled by configuration, the site MUST load Umami tracking on all indexable pages and MUST record pageviews.
|
|
|
|
When Umami is disabled or not configured, the site MUST still function and MUST NOT error in the browser due to missing analytics.
|
|
|
|
#### Scenario: Umami enabled
|
|
- **WHEN** Umami is enabled by configuration
|
|
- **THEN** the site includes the Umami script on `/`, `/videos`, `/podcast`, and `/about`
|
|
|
|
#### Scenario: Umami disabled
|
|
- **WHEN** Umami is not configured
|
|
- **THEN** the site renders normally and no analytics script is required
|
|
|
|
### Requirement: Custom event tracking
|
|
When Umami is enabled, the site MUST support custom event emission for:
|
|
- `cta_click`
|
|
- `outbound_click`
|
|
- `media_preview`
|
|
- `media_preview_close`
|
|
- a general click interaction event for all instrumented clickable items (per the site tracking taxonomy)
|
|
|
|
Each emitted event MUST include enough properties to segment reports by platform and placement when applicable.
|
|
|
|
All tracked clickable items MUST emit events with a unique, consistent set of data elements as defined by the site tracking taxonomy, including at minimum `target_id` and `placement`.
|
|
|
|
The site MUST instrument tracked clickables using Umami's supported Track Events data-attribute method:
|
|
- `data-umami-event="<event-name>"`
|
|
- optional event data using `data-umami-event-*`
|
|
|
|
For interactions that are triggered programmatically (e.g., modal close events where the close method must be recorded), the site MAY use Umami's JavaScript API (`umami.track()`) instead of data attributes when data attributes cannot express the required properties.
|
|
|
|
For content-related links (clickables representing a specific piece of content), the site MUST also provide the following Umami event data attributes:
|
|
- `data-umami-event-title`
|
|
- `data-umami-event-type`
|
|
|
|
#### Scenario: Emit outbound click event
|
|
- **WHEN** a user clicks a non-CTA outbound link from the homepage
|
|
- **THEN** the system emits an `outbound_click` event with a property identifying the destination domain
|
|
|
|
#### Scenario: Emit general click event for any clickable
|
|
- **WHEN** a user clicks an instrumented navigation link
|
|
- **THEN** the system emits a click interaction event with `target_id` and `placement`
|
|
|
|
#### Scenario: Content click includes title and type
|
|
- **WHEN** a user clicks an instrumented content link (video, podcast episode, blog post/page)
|
|
- **THEN** the emitted Umami event includes `title` and `type` properties via `data-umami-event-*` attributes
|
|
|
|
#### Scenario: Uninstrumented clicks do not break the page
|
|
- **WHEN** a user clicks an element with no tracking metadata
|
|
- **THEN** the system does not throw and navigation/interaction proceeds normally
|
|
|
|
#### Scenario: Media preview event emitted on card click
|
|
- **WHEN** a user clicks a video or podcast content card that opens a media modal
|
|
- **THEN** the system emits a `media_preview` event with `target_id`, `placement`, `title`, `type`, and `source`
|
|
|
|
#### Scenario: Media preview close event emitted
|
|
- **WHEN** a user closes the media modal
|
|
- **THEN** the system emits a `media_preview_close` event with the `target_id` of the content that was previewed and the `close_method` used
|
|
|
|
#### Scenario: Modal CTA click emitted
|
|
- **WHEN** a user clicks a CTA inside the media modal (e.g., "View on YouTube")
|
|
- **THEN** the system emits a `cta_click` event with `target_id`, `placement=media_modal`, `platform`, and `target_url`
|
|
|
|
### Requirement: Environment configuration
|
|
The site MUST support configuration of Umami parameters (at minimum: website ID and script URL) without requiring code changes.
|
|
|
|
#### Scenario: Configure Umami via environment
|
|
- **WHEN** Umami configuration values are provided via environment or config file
|
|
- **THEN** the site uses those values to initialize analytics without modifying source code
|