This is a preview of unreleased docs from main. View the published docs
Skip to main content

Interactions

Interactions deploy on-page experiences — templates, JavaScript, CSS, and cookies — configured in the Allegro dashboard. For what interactions are and how they are built, see the product documentation.

An interaction runs in one of two modes, and the SDK handles each differently:

ModeHow it fires on the page
Automatic targetingThe SDK asks Allegro which journeys the visitor matches on every page load and renders the results. No integration code.
Manual embedYour code calls allegro.interaction.trigger(slug).

Automatic Evaluation​

Once the SDK is ready it sends one evaluation request per page load, alongside the page_view event. The request carries the page's context; Allegro evaluates every published automatic interaction on the server and responds with the actions to render. Targeting rules, segment membership, and member profile data never reach the browser.

FieldSource
url, pathwindow.location
queryThe URL query string (first value wins for repeated keys)
referrerdocument.referrer
content_typeThe content_type page metadata field
sectionThe context page metadata field
timezoneIntl.DateTimeFormat().resolvedOptions().timeZone
customThe custom object from your SDK configuration (see Custom Data)
cookiesEvery _al_-prefixed cookie, keyed without the prefix (see Cookies)

If the visitor is signed in, the session token is sent as well, which is what lets member, segment, and entitlement conditions resolve. An identified-only session (for example after submitting an email form) is treated as anonymous.

Device and location are derived on the server from the request itself. The Content type and Section conditions read the same page metadata mappings tracking uses, so if your site uses custom pageData mappings, targeting follows them automatically.

Failures are silent: if the request fails, nothing renders and a console.debug line is written when debug mode is on.

Conflict rules set on the dashboard's Priority page are applied on the server before the response is built, so the response already leaves out interactions that a higher-ranked match hides. The SDK needs no extra handling.

The SDK sends the request to the public POST /api/interactions/evaluate endpoint; no API key is needed. Its request and response shapes are in the Session API reference.

Configuration​

Set these on window.__allegro before client.js loads. See Script Tag.

PropertyTypeDefaultDescription
interactionsbooleantrueRun the automatic evaluation on page load. Set false to rely on trigger() and manual evaluate() calls only.
interactionsSpabooleanfalseRe-evaluate on single-page-app navigation (pushState, replaceState, popstate). Ignored when interactions is false.
customobject—Key/value pairs sent as custom data for Custom data conditions. Values may be strings, numbers, or booleans.
<script>
    window.__allegro = {
        interactionsSpa: true,
        custom: {
            plan: 'trial',
        },
    };
</script>
<script src="https://acme.allegrocdp.com/client.js"></script>

Custom Data​

Anything in custom is available to editors as the Custom data attribute, keyed by property name. Use it to feed targeting with facts only your site knows — an A/B bucket or a CMS flag. Keys and values are sent with every evaluation, so keep them short and free of personal data.

Cookies​

The SDK reads every cookie whose name starts with _al_ and sends it with each evaluation, minus the prefix: _al_promo_seen=1 arrives as { promo_seen: '1' } and matches a Cookie condition keyed promo_seen. Readable cookie actions set these for you. Your own code can set one too when it wants editors to target it:

document.cookie = '_al_plan=trial; path=/; max-age=2592000';

Up to 50 cookies are sent, and values longer than 2,048 characters are skipped. Only use the prefix for values that are fine to send to Allegro; cookies without it are never read.

Single-Page Applications​

With interactionsSpa: true the SDK re-runs targeting on history navigation, removes interactions rendered for the previous route that no longer match, and renders the new matches. Hash-only changes are ignored. If your router does not use the History API, or you want control over timing, call evaluate() yourself instead.

// Vue Router
router.afterEach(() => window.allegro.interaction.evaluate());

Attribution in Tracked Events​

Templates rendered by automatic targeting record interaction_id and journey_id in their template_displayed and template_not_displayed events, so you can analyze which journey produced each impression. journey_id is null when the Everyone else default matched. See Display Tracking.

allegro.interaction Namespace​

Access these methods after allegro:ready, or from a callback pushed onto window.allegro.

evaluate()​

Re-run server-side targeting for the current page and render the matches. Idempotent: interactions rendered by an earlier evaluate() that no longer match are removed before the new matches render. Runs even when config.interactions is false; a no-op in preview mode and outside a browser. Never throws.

await allegro.interaction.evaluate();

trigger(slug, data?)​

Fetch a manual-embed interaction by slug and run its actions. data is passed into the Alpine.js x-data scope of any template the interaction renders, so your template logic can read it.

allegro.interaction.trigger('member-wall');

allegro.interaction.trigger('member-wall', {
    title: 'Join our membership program',
});
ParameterTypeDescription
slugstringThe interaction's slug, shown in the dashboard
dataobjectOptional data made available to the rendered template

Returns a promise resolving to the interaction record. Use the Show Snippet button in the dashboard to copy a ready-made call for a published manual interaction.

experiments()​

Returns the visitor's A/B test assignments from the most recent evaluation, as { "<test id>": "<variant id>" | null }; null means the visitor is not in that test. The map is persisted in localStorage and attached to every event the SDK sends as experiments. Variant ids are opaque labels, safe to forward to your own analytics.

const assignments = window.allegro.interaction.experiments();

remove(slug)​

Remove an active interaction's rendered output from the page.

allegro.interaction.remove('newsletter-signup');

ungate(slug)​

Reveal content that an interaction truncated or gated, for example after the visitor signs in.

allegro.interaction.ungate('paywall');

Rendering​

JavaScript and CSS actions apply to the whole page. Template actions render in a shadow root placed according to the action's area and placement settings; an action with no area appends to the end of <body>. Each action honors its own timing (immediate, timed, scroll-based, or truncation-based). See the templates guide for the host element, Alpine state, and CSS variables available inside a rendered template.