Audience Detection

Release Feature Liferay DXP 2026.Q3+

Audience detection runs in the visitor’s browser. Liferay DXP adds a bootstrap script to the page that fetches your instance’s audience definitions. The script evaluates each audience’s conditions against values the browser can observe. The Audiences JavaScript API module holds the matched audiences in memory, where element variations and your own JavaScript can read them.

The mechanics behind this process matter most when you are reading audiences from your own code, or troubleshooting why an audience is not matching.

Note

Audiences is a release feature behind the LPD-85746 feature flag. Once the flag is enabled, the Audiences application appears and Liferay DXP adds detection markup to the page.

Detection Markup

Liferay DXP writes the detection markup into the page’s top_head section, but only when the page is rendered in view mode. Detection does not run in the page editor.

Liferay DXP adds the markup even when no audiences exist. On an instance with none, the definition is empty:

{"audiences":[]}

Liferay DXP also writes a <meta> tag identifying the page’s element variations bundle, even when the page has no variations. Its content attribute holds the page layout ID, the segments experience ID, and the bundle’s hash, separated by colons:

<meta content="20125:41302:a1b2c3d4" name="audiences-variations">

The <script> tag carries the definition hash, the detection timeout, and the log setting as request parameters. It is also marked data-senna-track="permanent", so single page application navigation does not re-execute it:

<script data-senna-track="permanent" id="audiencesBootstrap" src="/o/audiences/bootstrap.(HASH).js?audiencesDefinitionHash=HASH&detectionTimeout=0&enableLog=false" type="module"></script>

The Detection Cycle

Detection runs when the page loads and again on each single page application (SPA) navigation. Each cycle executes these steps:

Read the page’s variations <meta> tag. If the page has no such tag, the cycle stops here.
Load the page’s element variations.
Clear the audiences matched by the previous cycle.
Download the audiences definition and filter out audiences whose scope excludes the current site.
Check that the remaining audiences are defined correctly.
Evaluate the remaining audiences’ conditions against values the browser can observe.
Apply the element variations associated with each matched audience.

If detection cycles overlap during rapid SPA navigation, only the most recent cycle applies its variations.

The Audiences Definition

The definition is a single JSON document served per instance at /o/audiences/definition.(HASH).json.

Each entry in the audiences array carries an id, a conjunction (i.e., AND / OR), an array of rules, and a scope array. A rule either compares a single attribute (attribute, operator, and value) or nests its own conjunction and rules to express a condition group.

Liferay DXP 2026.Q4+Thescopearray lists the group IDs of the sites the audience is limited to, each as a string. An empty array means the audience applies on every site. Detection evaluates only the audiences whose scope is empty or includes the current site's group ID (Liferay.ThemeDisplay.getSiteGroupId()). The other audiences are filtered out before validation and never match or apply variations.

An audience’s id is its external reference code. Everything that refers to an audience uses that code, including element variations and the values audiences.get() returns.

Validation only accepts the built-in attribute keys, such as device_type and batch_segments, and keys that start with custom:. Any other key in an in-scope audience fails validation. A validation failure or a failed definition download stops the cycle, so no element variation on the page applies. See Audience Attributes Reference.

Liferay DXP 2026.Q4+If a rule fails to evaluate, its audience doesn't match, even inside anOR group whose other rules match. Other audiences aren’t affected. A rule can fail this way when its custom attribute throws an error.

Liferay Data Platform Segment Membership

The Batch Segments and Real Time Segments attributes read one merged set of the external reference codes of the visitor’s segments. The codes come from the analytics JavaScript client, the Analytics global object. The client fetches real-time codes on every detection cycle and caches batch codes in the browser for three hours.

Detection waits for those codes before evaluating a segment condition. If the Analytics object never becomes available, the cycle blocks indefinitely under the default Detection Timeout of 0 and no variation on the page applies. If the segment fetch fails, no audience with a segment condition matches.

Audience Precedence

A visitor can match several audiences at once. When more than one of them has a variation on the same element, the oldest audience takes precedence by default. You can override this order for a page experience. In the element variations editor, click Edit next to Audiences Priority and drag the audiences into the order you want.

Each experience has one ordered list, and that list governs every element in the experience. There is no separate order for an individual element. Audiences in the saved order rank above audiences not in it (for example, audiences created after the order was last saved). Among those not in the order, the oldest takes precedence.

Reading Matched Audiences

To read the matched audiences from your own JavaScript, import the Audiences JavaScript API module from the URL the bootstrap script imports it from:

const {audiences} = await import('/o/frontend-js-audiences-web/__liferay__/index.js');

audiences.get() returns a Set of the matched audiences’ external reference codes. A detection cycle clears the set before downloading the definition and adds its matches when it finishes. A full page load clears it too. After an SPA navigation to a page with no <meta> tag, the cycle stops before clearing, so audiences.get() keeps returning the audiences matched on the last page with a <meta> tag.

Setting a Detection Timeout

Liferay DXP 2026.Q4+

Use the Detection Timeout setting to limit how long detection can spend downloading and evaluating the audiences definition. The value is in milliseconds, with a default of 0 for no timeout. Configure a timeout to apply the variations of already-matched audiences rather than block every variation on the page while detection waits for data such as segment codes. If it expires during evaluation, detection applies those variations and discards the rest. If it expires during the download, no audience matches.

Configure the Detection Timeout in the Global Menu () → Control Panel → Instance Settings → Infrastructure → Frontend Audiences Infrastructure. Reload the site page after you save a change.

Logging Detection to the Browser Console

To log detection to the browser console, select Enable Log in the Global Menu () → Control Panel → Instance Settings → Infrastructure → Frontend Audiences Infrastructure. Reload the site page after you save it. Messages are prefixed with @liferay/audiences:, so you can filter the console by that string. Keep this setting disabled outside of troubleshooting, since the messages are visible to any visitor who opens the browser console.

Feature Availability

Feature	Available as Beta	Available as Release
Audience Detection	Liferay DXP 2026.Q3 (LPD-85746)	Liferay DXP 2026.Q4 (LPD-85746)
Site-Scoped Audiences	-	Liferay DXP 2026.Q4 (LPD-85746)
Detection Timeout	-	Liferay DXP 2026.Q4 (LPD-85746)