> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/umbraco-engage/17.latest/release-notes.md).

# Release Notes

Get an overview of the changes and fixes in each version of Umbraco Engage.

This section summarizes the changes and fixes introduced in each version of Umbraco Engage. Each release includes a link to the [Engage issue tracker](https://github.com/umbraco/Umbraco.Engage.Issues/), where you can find a list of resolved issues. Individual issues are also linked for more details.

If there are any breaking changes or other issues to be aware of when upgrading, they are also noted here.

{% hint style="info" %}
If you are upgrading to a new major version, check the breaking changes in the [Version Specific Upgrade Notes](/umbraco-engage/17.latest/upgrading/version-specific-upgrade-notes.md) article.
{% endhint %}

## Release History

Below are the release notes for Umbraco Engage 17, detailing all changes in this version.

#### [17.5.0-rc1](https://www.nuget.org/packages/Umbraco.Engage/17.5.0-rc1) (September 18th 2026)

**Analytics and reporting**

* Report tables, charts and the comparison view now page and search on the server instead of loading the whole report into the browser. Large reports open faster, and search now filters the entire report rather than only the rows already loaded.
* Column totals and each cell's "% of total" are now computed by the server against the whole report. These values stay accurate while paging or searching, instead of reflecting only the loaded page.
* Fixed installations with report-data generation disabled sometimes serving realtime results instead of reporting results. One case returned a 500 error on the backoffice start page.
* Fixed the "% change" column in comparison mode showing the wrong row's value after paging, searching, or sorting ([Issue #91](https://github.com/umbraco/Umbraco.Engage.Issues/issues/91)).
* Fixed the Location report's country-to-city drill-down throwing an error, and fixed drill-down tables (including Goals) not reloading correctly when moving between levels ([Issue #96](https://github.com/umbraco/Umbraco.Engage.Issues/issues/96)).
* Fixed a SQL syntax error that made the "Applied segment insights" report fail on every request.
* Fixed incorrect goal-completion and applied-segment reporting caused by stale references to columns removed in earlier key-column migrations.
* Hardened comparison-mode paging against malformed requests, such as an omitted paging block or a large page number. These could previously return rows in the wrong order or cause a server error.

**Analytics: visual redesign**

* The chart and its data table are now combined into a single pane instead of two separate boxes.
* Annotations moved out of the chart into a compact popover in the pane header. The popover shows a bookmark icon, a count, and a list for creating or deleting annotations inline. Annotation markers are now pinned directly on the chart.
* Line/area and bar charts have been restyled to match the updated design. Fixed a memory leak where a chart's underlying Chart.js instance was not released when navigating away from a screen.
* Data tables have been restyled with a mini bar indicator per metric cell, colour-coded visitor-type rows, clearer "no results" messaging, and an improved loading state.
* Pagination footers now stay visible even when all rows fit on one page, showing a "1–10 of 14" style range. Fixed two-row breakdown tables, for example New and Returning visitors, show no footer.

**Heatmaps**

* Fixed heatmap rendering on invariant documents that have a defined culture/hostname, which previously requested heatmap data using the wrong culture ([Issue #97](https://github.com/umbraco/Umbraco.Engage.Issues/issues/97)).

**A/B testing and personalization**

* Added inline creation for Goals, Segments, and Projects, directly from their picker in the A/B test and personalization editors. A new goal, segment, or project can be created without leaving the workspace being edited.
* Deleting or stopping an A/B test, removing a single variant, or deleting a personalization now removes only the content it created. It no longer risks affecting unrelated content on other pages. A one-off migration cleans up any orphaned content left behind by earlier versions ([Issue #93](https://github.com/umbraco/Umbraco.Engage.Issues/issues/93)).
* Added the ability to copy a winning A/B test variant to the default (published) content. This can be done directly from the "select winner" dialog, with options to publish or save. The winner-selection and scoring-overview dialogs have also been streamlined.
* Fixed a rare cause of pageviews silently failing to record, caused by an A/B test variant iterator being re-evaluated outside its original request context.
* Restored a guard, lost between v13 and v17, that blocks deleting a segment still referenced by a personalization. It shows a dialog listing the personalizations using it ([Issue #106](https://github.com/umbraco/Umbraco.Engage.Issues/issues/106)).
* Fixed the Segments list "Applied" column always showing 0, caused by comparing the segment's GUID against a numeric ID that could never match. Segment usage is now counted correctly ([Issue #105](https://github.com/umbraco/Umbraco.Engage.Issues/issues/105)).

**Backoffice and platform**

* Fixed the Engage section crashing when duplicate user-group permission rows existed in the database; duplicate rows are also now prevented going forward.
* Fixed the Analytics and Profiles tabs sometimes being absent from the Engage section navigation on newer Umbraco CMS versions, with no error shown. The cause was a duplicate script load triggered by Umbraco CMS asset cache-busting ([Issue #101](https://github.com/umbraco/Umbraco.Engage.Issues/issues/101)). This also fixes the Suspicious Activity Profile ID panel hanging indefinitely on load, a symptom of the same issue ([Issue #104](https://github.com/umbraco/Umbraco.Engage.Issues/issues/104)).
* Added `Analytics:DataCollection:RequireAnalyticsPermissionForMemberTracking` (default `false`). When enabled, a pageview from a visitor without analytics consent is still recorded, but without their member identity attached.
* Fixed a migration that could silently record itself as completed even when it failed part-way through. This could leave a site stuck on an old schema after a failed upgrade. Two related legacy-format migrations were also tightened, so a genuine database error is no longer mistaken for "not applicable" and ignored.

#### [17.4.0](https://www.nuget.org/packages/Umbraco.Engage/17.4.0) (August 20th 2026)

* All changes from 17.4.0 release candidates

#### [17.4.0-rc](https://www.nuget.org/packages/Umbraco.Engage/17.4.0) (August 7th 2026)

**Previewing**

* Previewing A/B test variants now goes through Umbraco's native preview segment switcher, bringing it in line with how personalizations are previewed. Every test type can now be previewed, including the benchmark (control) variant, as can ContentType-scoped and MultiPage personalizations.
* The legacy `?EngagePreviewVariantId` and applied-personalization preview query string parameters have been removed, along with the endpoint that generated preview URLs from them. Any bookmarked or hand-built preview URLs relying on these parameters will no longer work.
* The `HasSegmentedPropertyContentTypes` endpoint has been removed. The backoffice now receives the Document Type key directly instead of asking the server about property variance.
* The A/B test variant picker now handles Umbraco variants that no longer exist, such as deleted or recycled pages. Preview is disabled for a test with no page variants or Document Types.
* Fixed the preview segment selector disappearing after switching culture and never reappearing.
* Fixed variant edit links silently losing their segment after any call made without one.
* Fixed the erroneous "Document Type does not support segmentation" warning shown when selecting an A/B test variant.
* Fixed the control group suppressing a personalized variant's CSS/JS in preview, even though the control group is deliberately ignored while previewing.
* The heatmap variant selector now drives the preview with a real Umbraco segment instead of legacy query string parameters.
* The heatmap preview session is correctly managed within the heatmap screen element lifecycle.

**Serving and content**

* Invariant A/B tests and personalizations are now applied on culture-specific pages. Culture matching previously tested for `null` rather than an empty string, so invariant configurations were skipped entirely. A `NormalizeInvariantCultureToNull` migration rewrites `culture = ''` to `NULL` across four configuration tables during upgrade.
  * **Behaviour change**: invariant A/B tests and personalizations that were previously inert will start serving variants after upgrading.
* Fixed the A/B variant segment placeholder only being created under the default culture. This prevented variants for other cultures being authored or served on multilingual sites.
* ContentType-scoped personalizations now appear on the Personalization tab. An integer ContentTypeId was being compared to a GUID, so they were never listed.
* Applied personalizations with an unresolvable node key no longer render a dead edit link or vanish from the Personalization tab.
* Document references in personalizations are no longer cached for the lifetime of the process. A deleted page now stops showing a dead link without needing a restart.
* The segment is now written to the analytics page variant table, so segmented traffic is attributed correctly.
* Fixed the Pageview goal picker storing a generated row identity instead of the Umbraco document key. This caused picked pages to show as "Not found" on reopen and the goal to never convert.
  * **Action required**: Pageview goals saved on 17.2.4, 17.3.0 or 17.3.1 hold unrecoverable values and must have their pages re-picked after upgrading.

**Analytics and reporting**

* Fixed segment reporting charts showing stale or empty data when switching segments, and the percentage toggle not redrawing.
* Replaced a nested row scan with a hash lookup when merging analytics tables, resolving browser timeouts on large data sets.

**Customer journeys and scoring**

* **Behaviour change**: the default minimum deviation for persona and customer journey scoring changed from 0 to 1. The value was previously written by hand at nine call sites and disagreed between them. It is applied when reading a group with no configured value, so no migration runs. A step that leads by no points no longer wins.

**Backoffice and platform**

* Backoffice endpoints that touch the database are now gated when the Engage schema is unhealthy or migrations have failed. They return a `503 Service Unavailable` with a descriptive problem detail instead of throwing or returning nonsense. Configuration-only endpoints — including the main switch — stay reachable so Engage can be re-enabled.
* Added validation highlighting properties whose variance does not align with their Document Type's variance. This is a common cause of A/B test variants failing to save or serve.
* The create-segment endpoints are now GUID-driven, removing the integer-to-GUID mapping previously performed in the API.
* Bumped the **Umbraco.Licenses** dependency to 17.0.4. License product IDs are now matched case-insensitively, so a license configured under a differently-cased key still resolves.

#### [17.3.1](https://www.nuget.org/packages/Umbraco.Engage/17.3.1) (July 24th 2026)

* Added the ability to mark a visitor as a bot from the **Suspicious Activity** overview. The activity-type filter is shown only when more than one option is available.
* Fixed a 404 when editing a personalized variant on an invariant document, and resolved previewing on invariant documents.

#### [17.3.0](https://www.nuget.org/packages/Umbraco.Engage/17.3.0) (July 24th 2026)

* Downgrading a license no longer leaves functionality running. A/B testing and personalization are now gated on their respective licenses in the request pipeline, on both the rendered and headless page-view paths.
* Custom event fields (category, action, label) are widened to 1000 characters. They were previously truncated to 50 characters silently.
* Fixed a `401` response on the Engage tab after a period of inactivity. The Engage backoffice client is now routed through the CMS `configureClient` on Umbraco CMS 17.3 and above.
* Segment options in the backoffice are now filtered to the A/B tests and personalizations configured for the document being edited or previewed. The CMS preview segment switcher is replaced with a document-scoped version.
* Fixed the A/B test preview button doing nothing, and prevented a previewing visitor from falling into A/B test buckets.
* The Engage Cockpit is now suppressed while Umbraco's own preview is active.
* Editing a Single Page A/B test variant now opens the segment-scoped editor.
* Fixed Split URL test page selection, matching test pages by node id rather than row key.
* Fixed filter mutation and redraw flicker in the analytics UI.
* The data retention card now reports only the cleanup tasks that ran. The **Database Schema Status** health check wording is aligned with the reduced-mode card.
* Fixed the start-page schema warning text not aligning with the warning message.

#### [17.2.4](https://www.nuget.org/packages/Umbraco.Engage/17.2.4) (June 29th 2026)

* Resolved preview issues for **multi-page A/B tests**, including stale previews caused by caching.
* Restored the **CSS/JS** editor button for single-page A/B tests.
* Fixed a node-key conflation in the A/B test **multi-variant picker**.
* Improved the A/B test editing flow with prompts to save the test before previewing or modifying variants.
* Resolved a `ChannelClosedException` that could occur when flushing visitor data during application shutdown.
* Resolved an error occurring on the **Profiles** section on installations with an **Analytics** license.
* Laid internal groundwork in preparation for upcoming **Umbraco.AI** support.

#### [17.2.3](https://www.nuget.org/packages/Umbraco.Engage/17.2.3) (June 2nd 2026)

* Resolved pageviews and associated data not getting flushed to the database on load-balanced (subscriber) setups.

#### [17.2.2](https://www.nuget.org/packages/Umbraco.Engage/17.2.2) (May 22nd 2026)

* Resolved a unique-key collision that occurred when adding a second personalization to the same page ([Issue #66](https://github.com/umbraco/Umbraco.Engage.Issues/issues/66)).
* Resolved personalizations migrated from v13 disappearing from the Personalizations tab ([Issue #67](https://github.com/umbraco/Umbraco.Engage.Issues/issues/67)).
* Fixed the same Key/document-key conflation in A/B Testing.

#### [17.2.1](https://www.nuget.org/packages/Umbraco.Engage/17.2.1) (May 19th 2026)

* Resolved a thread-safety issue in the personalization visitor profile that could corrupt profile state under concurrent pageviews.
* Resolved failed migration steps being silently masked at boot. Failures now surface without blocking application startup.
* Fixed duplicate-row replacement in the permissions dashboard, which previously caused "Duplicate permissions found for ContentTypeIds" errors when toggling `document-type` permissions that shared a default record.
* Added `ICampaignGroupService` for public access to campaign-group data, including `GetCampaignGroupIdsWithRecentActivity` documented in UTC calendar-day semantics.
* Added a `GetAll` method to `ISegmentService` for retrieving all configured segments.
* Added orphaned-record cleanup for personalization groups, removing stale references left behind by deleted personas and customer journey groups.
* Improved personalization cache invalidation by short-circuiting invalidated rules.
* Improved CPU efficiency by preventing recurring background jobs from hot-looping when no work is available.

#### [17.2.0](https://www.nuget.org/packages/Umbraco.Engage/17.2.0) (April 20th 2026)

* Rewritten analytics data cleanup with improved scheduling and performance:
  * Cleanup now processes all eligible records without a batch size limit (the `NumberOfRows` setting is no longer used).
  * New configuration settings: `Enabled`, `FirstRunTime` (crontab), `StartupDelay`, `Interval`, `CommandTimeout` — replacing deprecated `StartAfterSeconds`, `IntervalInSeconds`, `NumberOfRows`. See [configuration](/umbraco-engage/17.latest/developers/settings/configuration.md) for details.
  * Configurable first-run scheduling via crontab expression (`"0 2 * * *"` for 2 AM daily).
* Database schema alignment bringing existing installations in line with clean installs:
  * Adds missing foreign keys with `ON DELETE CASCADE`, indexes, and constraints.
  * Requires running the `EnsureDataConsistency.sql` script first to clean up any orphaned data, followed by the `CompleteAlignSchema.sql` script to add the constraints. Both scripts should be run during a maintenance window after upgrading (see below).
  * **Important**: Until the script is executed, only anonymization and visitor control group/raw data cleanup will run. Full analytics data cleanup (pageviews, sessions, visitors) requires the schema alignment to be completed.
  * Helper script included: `GetDeleteAnalyticsDataAfterDays.sql` (recommends safe initial configuration, see below).
* Added 'Database Schema Status' and 'Constraint Integrity' health checks to monitor upgrade completion.
* Aligned `culture` column length with Umbraco CMS.
* Fixed `Anonymize IP Address` setting not showing in the UI.
* Clean-up of orphaned page variants and bot visitor data.
* Fixed duplicate page variant rows being created per pageview instead of reusing existing data. A `DeduplicatePageVariants.sql` helper script is included to consolidate duplicates on existing installations (see below).
* Added wildcard domain support for licensing.
* Improved goal deserialization handling with caching and graceful error recovery.
* Security fix: server-side enforcement of `createdBy` on annotations and other entities — client-provided values are no longer trusted.
* Page variant segment nullability fixes.
* New `DeliveryApi.DisableVisitorCookie` configuration (default: `false`) — when `true`, suppresses the visitor cookie on headless API requests, requiring clients to use the `External-Visitor-Id` header instead. See [configuration](/umbraco-engage/17.latest/developers/settings/configuration.md) for details.
* Optimized annotation fetching using EntityService for improved performance.
* Fixed partial Urchin Tracking Module (UTM) data missing from Analytics Campaigns view.
* Fixed campaign group key management.
* Added a data cleanup log viewer in the backoffice, providing insight into cleanup job history, per-table statistics, and start-page data retention status.
* Added support for soft-deleting segments with automatic background cleanup. Deleted segments are now gracefully removed from the system without affecting historical analytics data. An `IsDeleted` column has been added to the segments table. Any direct SQL queries against segment tables must filter on this column to exclude soft-deleted records.
* Added a Suspicious Activity overview in the backoffice, allowing you to identify and review visitors with unusual pageview patterns. Includes configurable pageview thresholds and the ability to provide feedback on flagged activity.
* Enforced UTC date handling across the entire codebase, preventing timezone-related issues in analytics, A/B testing, and reporting.
* Fixed analytics POST requests being broken by trailing-slash URL rewrite rules.
* Fixed campaign graph not updating correctly when switching between campaigns.
* Replaced the IP Filters system with a new **Traffic Filters** system. Traffic Filters extend filtering beyond IP addresses to include user agent, URL, and custom rule matching with conditions such as Contains, Equals, List, and Regex. IP list filters support CIDR subnet notation. A compiled regex cache with configurable timeout prevents ReDoS attacks. Existing IP filter configurations will need to be migrated to the new Traffic Filter format.
* Renamed the headless Marketing API to **Engage API**.
* Added `EngageDataCleanupProcessors()` extension method for registering [custom data cleanup processors](/umbraco-engage/17.latest/developers/analytics/extending-analytics/custom-data-cleanup-processors.md).

See the [Schema Alignment Guide](/umbraco-engage/17.latest/upgrading/schema-alignment-guide.md) for detailed post-upgrade steps and script downloads.

#### [17.1.0](https://www.nuget.org/packages/Umbraco.Engage/17.1.0) (March 4th 2026)

* Added the ability to explicitly lock persona and customer journey scores for individual visitor profiles. This allows manual overriding of calculated scores, with optional expiration, managed from the profile insights view.
* Added the ability to reorder personas via drag-and-drop in the backoffice.
* Redesigned the reporting star schema by introducing a new `FctSessionNode` fact table, replacing the previous `DimNodeAncestor` table and pre-computed `withSubpages` approach. This reduces star generation time and TempDB usage for large datasets.
* Added the ability to view heatmaps for 'Other' (unknown) device types.
* Added an 'All cultures' option to the Pageview Goal picker, defaulting to all cultures when creating new pageview goals.
* Improved path handling for CM/CD server configurations in the Headless package, ensuring correct content retrieval based on specified culture.
* Refactored cockpit to prevent CSS leaks using custom elements, adopting UUI CSS for fonts, sizes, and colors.
* Refactored and simplified scoring UI elements, reducing network requests and centralizing populator logic.
* Resolved an issue where the `pagehide` event listener was not correctly handling page visibility changes in the analytics tracking script.
* Fixed extraction of the Membership Provider Key, resolving cases where the key was not correctly retrieved from the HTTP context.
* Fixed `HttpContext.Request` corruption in `UrlUmbracoPageVariantExtractor`, ensuring request state is preserved for downstream middleware.
* Resolved multiple UI interaction bugs in the analytics dashboard affecting chart rendering, table prefabs, and A/B testing save-and-publish visibility conditions.
* Fixed incorrect sum calculation by excluding `pageSessionsWithSubpages` from the analytics table aggregation.
* Resolved other smaller bugs and UI fixes.

#### [Engage Forms 17.1.2](https://www.nuget.org/packages/Umbraco.Engage.Forms/17.1.2) (April 2nd 2026)

* Fixed broken migration step regarding Goals table name misalignment.
* Fixed broken swagger documentation generation.

#### [Engage Forms 17.1.1](https://www.nuget.org/packages/Umbraco.Engage.Forms/17.1.1) (February 19th 2026)

* Fixed a security issue ([GHSA-86vq-ccwf-rm62](https://github.com/umbraco/Umbraco.Engage.Issues/security/advisories/GHSA-86vq-ccwf-rm62)).

#### [17.0.4](https://www.nuget.org/packages/Umbraco.Engage/17.0.4) (January 8th 2026)

* Resolved an issue where the YouTube IFrame Player was being overridden when already initialized on the page. The analytics script now reuses an existing YT Player instance instead of creating a new one. This prevents conflicts with sites that have their own YouTube player initialization.
* Resolved Swagger schema generation issues when used in combination with the Umbraco.DeliveryApiExtensions addon.
* Resolved cookie retention when using the headless `/trackpageview/server` endpoint ([Issue #42](https://github.com/umbraco/Umbraco.Engage.Issues/issues/42)).
* Resolved broken Pageview Goals migration when updating from Engage 13.x to 17.x ([Issue #43](https://github.com/umbraco/Umbraco.Engage.Issues/issues/43)).

#### [Engage Forms 17.1.0](https://www.nuget.org/packages/Umbraco.Engage.Forms/17.1.0) (January 8th 2026)

* Resolved Form Submission Goal Type migration when migrating from version 13.x.

#### [17.0.3](https://www.nuget.org/packages/Umbraco.Engage/17.0.3) (December 16th 2025)

* Implements additional validation checks before assigning the visitor cookie, improving cookie handling reliability across different request scenarios.
* Resolved an issue where headless API responses returned absolute URLs instead of relative paths for URL paths.
* Resolved multiple bugs regarding A/B Test UI, including the editing and previewing of segments and validation around enabled segmentation on content.
* Resolved an issue where starting an A/B test did not immediately start the test due to timezone conversion problems.
* Resolved multiple issues with reporting tabs, including segment personalization, goal performance, and segment potential displays.
* Resolved heatmap display issues by ensuring the default culture is used for invariant documents, with minor style improvements.
* Resolved `ProducesResponseType` attributes using the incorrect `StatusCodeResult` type.

#### [17.0.2](https://www.nuget.org/packages/Umbraco.Engage/17.0.2) (December 1st 2025)

* Resolved a broken dependency in the Cockpit, resulting in broken charts and an unresponsive cockpit.

#### [17.0.1](https://www.nuget.org/packages/Umbraco.Engage/17.0.1) (November 27th 2025)

* Resolves a 500 Internal Server Error that occurred when creating or saving a new or existing A/B test.

#### [Engage Forms 17.0.0](https://www.nuget.org/packages/Umbraco.Engage.Forms) (November 27th 2025)

* Adds the ability to store a visitor's unique key instead of the numeric ID when using the **Analytics Visitor ID** Form Field.

#### [17.0.0](https://www.nuget.org/packages/Umbraco.Engage/17.0.0) (November 27th 2025)

The major release of Engage V17 is here, including support for Umbraco Forms and Commerce add-ons. This release also introduces Deploy support for Engage, making it easier to move your setup between environments. You can transfer configuration items such as segments, personas, journey steps, and goals, while analytics data remains safely in each environment.

This release includes many automatic migrations and changes to the database structure. See [Version specific Upgrade Notes](/umbraco-engage/17.latest/upgrading/version-specific-upgrade-notes.md) for more information.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.umbraco.com/umbraco-engage/17.latest/release-notes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.