# Allegro Audience

> Documentation for the Allegro Audience CDP, an open source API-driven customer data platform.

## Developer

### Developer Platform Overview

The Allegro SDK is a lightweight JavaScript library for event tracking, session management, and member authentication. It loads asynchronously and exposes its API on `window.allegro`.

#### Installation[​](#installation "Direct link to Installation")

Add the loader script to your page:

```html
<script src="https://your-allegro-instance.com/client.js"></script>

```

For more information, see [the script tag documentation](/developer/guides/script-tag.md).

#### Core Concepts[​](#core-concepts "Direct link to Core Concepts")

##### Async Queue[​](#async-queue "Direct link to Async Queue")

The SDK uses an async queue pattern so you can start using it before it finishes loading:

```html
<script>
    window.allegro = window.allegro || [];

    // Queue a callback
    window.allegro.push(function (allegro) {
        allegro.track('page_view');
    });
</script>

<script src="https://your-allegro-instance.com/client.js"></script>

```

When the SDK loads, it replaces the array with the full SDK, drains the queue, and executes each callback.

##### `allegro.push(callback)`[​](#allegropushcallback "Direct link to allegropushcallback")

Queue a function to run when the SDK is ready. If the SDK has already loaded, the callback executes immediately.

```js
window.allegro.push(function (allegro) {
    // SDK is ready — use allegro.track(), allegro.member, etc.
});

```

#### What's Available[​](#whats-available "Direct link to What's Available")

| Namespace             | Description                                               |
| --------------------- | --------------------------------------------------------- |
| `allegro.track()`     | Track events with automatic session and device management |
| `allegro.member`      | Authenticate members, get user info and entitlements      |
| `allegro.interaction` | Trigger interaction events                                |

See the [Quick Start](/developer/getting-started/quick-start.md) guide for a complete working example, or browse the [API Reference](/developer/api-reference.md) for full type documentation.

#### Session & Device Management[​](#session--device-management "Direct link to Session & Device Management")

The SDK manages two cookies automatically:

| Cookie               | Lifetime   | Purpose                                  |
| -------------------- | ---------- | ---------------------------------------- |
| `allegro_device_id`  | 10 years   | Persistent device identifier (UUID v4)   |
| `allegro_session_id` | 30 minutes | Session identifier, extended on activity |

Sessions are created automatically on the first `track()` or `member.login()` call.

#### Error Handling[​](#error-handling "Direct link to Error Handling")

API errors throw an `AllegroApiError` with the HTTP status and response body:

```js
try {
    await allegro.member.login('bad@email.com', 'wrong');
} catch (error) {
    console.error(error.status); // e.g. 401
    console.error(error.body); // server response
}

```

Errors inside `push()` callbacks are caught and logged to the console — they won't break the queue or prevent other callbacks from running.


---

### Browser Settings

Browser Settings control how the Allegro SDK is allowed to talk to the tenant API from a browser. They govern two things:

* **CORS Allowed Origins** — which sites may make cross-origin API requests.
* **Cookie Domain** — how far the SDK's session cookie is shared across your subdomains.

These are organization-wide settings configured under **Organization Settings → Browser** in the Allegro dashboard.

Administrator access required

Browser Settings are managed by an Allegro administrator. If your site cannot reach the API, or you need a session shared across subdomains, ask your administrator to update these values for you.

#### CORS Allowed Origins[​](#cors-allowed-origins "Direct link to CORS Allowed Origins")

The browser blocks cross-origin requests unless the API explicitly allows the requesting origin. Every site that embeds the SDK — and therefore calls the tenant API from the browser — must have its origin on the allowed list.

Origins are entered one per line. Two formats are supported:

| Format             | Example                   | Matches                             |
| ------------------ | ------------------------- | ----------------------------------- |
| Exact origin       | `https://app.example.com` | Only that exact scheme, host, port  |
| Subdomain wildcard | `https://*.example.com`   | Any single-level subdomain over TLS |

When the list is left blank, the application defaults apply. A configured [custom domain](/developer/administration/custom-domain.md) is always included automatically, so you do not need to add it here.

Origins also gate return URLs

The allowed-origin list is also used to validate return URLs. The `returnUrl` sent with [magic link](/developer/guides/authentication/magic-links.md) requests and the return URL passed to [checkout](/developer/guides/payment/purchases.md) must resolve to one of these origins, or the request is rejected. This prevents sign-in and purchase tokens from being redirected to domains you do not control.

#### Cookie Domain[​](#cookie-domain "Direct link to Cookie Domain")

The SDK stores its session in a cookie. By default that cookie is scoped to the exact hostname that served `client.js`, so a session created on `www.example.com` is not visible on `app.example.com`.

Set a parent domain to share the session across subdomains:

```text
.example.org

```

With `.example.org` configured, a member who signs in on `www.example.org` stays signed in on `app.example.org` and any other `*.example.org` subdomain running the SDK. Leave the field blank to keep the default (current hostname only).

#### Related[​](#related "Direct link to Related")

* [Custom Domain](/developer/administration/custom-domain.md) — Serve the SDK from your own domain
* [Script Tag](/developer/guides/script-tag.md) — Embedding the SDK on your site
* [Member Authentication](/developer/guides/authentication.md) — How sessions work


---

### Custom Domain

By default, the Allegro SDK loads from the tenant subdomain:

```text
https://acme.allegrocdp.com/client.js

```

A custom domain lets you serve the SDK and its API endpoints from a domain you control instead:

```text
https://cdn.acme.com/client.js

```

This keeps SDK traffic on your own brand and origin, which is useful when you want the embed and its API requests to appear first-party to the browser.

Set by your platform administrator

A custom domain is provisioned and assigned by a platform administrator from the Allegro Admin — as the tenant's own domain, or to one of its properties — and DNS is pointed at the Allegro instance as part of that setup. You cannot set it from the SDK or the browser. Once it is in place, the steps below describe how the SDK uses it. For how domains are provisioned and assigned, see [Custom Domain (Platform)](/developer/platform/setup/custom-domain.md).

#### How the SDK Uses It[​](#how-the-sdk-uses-it "Direct link to How the SDK Uses It")

The SDK determines its API base URL from the `src` attribute of the `<script>` tag that loads `client.js`. Load the script from your custom domain and every API call the SDK makes — authentication, event tracking, interactions, checkout — goes to that domain automatically. No extra SDK configuration is required:

```html
<!-- All SDK API requests go to cdn.acme.com -->
<script src="https://cdn.acme.com/client.js" data-tenant="acme"></script>

```

#### CORS and Return URLs[​](#cors-and-return-urls "Direct link to CORS and Return URLs")

When a custom domain is configured, Allegro automatically includes it in the list of allowed [browser origins](/developer/administration/browser-settings.md) alongside the subdomain — you do not need to add it manually. That same list validates the return URLs used by [magic link](/developer/guides/authentication/magic-links.md) and [checkout](/developer/guides/payment/purchases.md) flows, so those redirects work on the custom domain out of the box.

#### Related[​](#related "Direct link to Related")

* [Browser Settings](/developer/administration/browser-settings.md) — Allowed origins and cookie scope
* [Custom Domain (Platform)](/developer/platform/setup/custom-domain.md) — DNS, routing, and hosting configuration
* [Script Tag](/developer/guides/script-tag.md) — Embedding the SDK on your site


---

### API Authentication

The Allegro REST API authenticates requests using Bearer tokens. You generate these API keys in the Allegro admin UI.

API keys belong to the **organization**, not to an individual user. Everyone with the **Admin** role manages the same shared list of keys, and a key keeps working as team members come and go. A key is scoped to its own organization: it is rejected if used against another organization's domain. You narrow what a key can do by choosing which [scopes](#token-scopes) it carries.

#### Creating a key[​](#creating-a-key "Direct link to Creating a key")

1. Sign in to your Allegro instance as an organization **Admin**.
2. Open **Organization Settings → API Keys**.
3. Click **Create Key** and give it a descriptive name (e.g. `data-pipeline`).
4. Choose when the key should **expire** — 30 days (the default), 90 days, 1 year, a custom date, or never.
5. Choose the [scopes](#token-scopes) the key should carry, then confirm.
6. Copy the key value that appears — it is only shown once.

Prefer a dated expiry

A key set to expire stops authenticating at the end of its expiry day and cannot be extended. Give keys the shortest lifetime your integration can tolerate, and rotate them before they lapse rather than choosing **Never**.

Store your token securely

The token value is displayed only at creation time. If you lose it, delete the token and create a new one.

#### Token scopes[​](#token-scopes "Direct link to Token scopes")

A scope controls what a token is allowed to do. Scopes follow a `resource:action` shape — for example `audience-members:read` lets a token read audience members, and `products:write` lets it create and update products.

When you create a key, the form groups the available scopes by resource. For each resource you can select individual actions, or use **Select all** to grant the whole resource (a `resource:*` bucket that also covers any actions added to that resource later). Two toggles at the top of the form grant scopes in bulk:

* **Full access (all scopes)** carries `*` — every scope on every resource, read and write, including any added later.
* **Full read access (all read scopes)** carries `*:read` — every `:read` scope on every resource, including read scopes added later, and nothing that writes.

Selecting either toggle locks the per-resource checkboxes, since the wildcard already covers them. A key saved with **Full read access** stores just `*:read`: the individual read scopes it covers are dropped, while any resource buckets you also picked (which carry write access) are kept alongside it.

The scopes a key carries are shown as badges next to it in the key list, and you can edit a key later to change its name, expiration, or scopes. Once a key has expired it becomes read-only — replace it with a new key rather than editing it.

The resources you can scope to are:

| Resource          | Read scope               | Write scope               |
| ----------------- | ------------------------ | ------------------------- |
| Analytics         | `analytics:read`         | `analytics:write`         |
| Audience Members  | `audience-members:read`  | `audience-members:write`  |
| Events            | `events:read`            | —                         |
| Products          | `products:read`          | `products:write`          |
| Recommendations   | `recommendations:read`   | `recommendations:write`   |
| Entitlements      | `entitlements:read`      | `entitlements:write`      |
| External Profiles | `external-profiles:read` | `external-profiles:write` |
| Foreign Keys      | `foreign-keys:read`      | `foreign-keys:write`      |
| Templates         | `templates:read`         | —                         |
| Sessions          | `sessions:read`          | —                         |
| Health            | `health:read`            | —                         |

One scope has no read/write split. `authentication:passwordless` lets a key sign audience members in on their behalf: it requests and validates magic links and one-time passcodes through `/api/v1/authentication/*` and returns the member's JWT. Grant it only to a trusted server, such as your own sign-in gateway, because those endpoints skip the captcha check that the browser endpoints run. A **Full access** key also carries it.

The key-creation form always lists the scopes currently available, so treat that form as the source of truth if this table drifts.

Scopes bound what a key can reach

A key's scopes limit what it can do within its organization. A key minted with **Full access** can reach every endpoint the organization exposes; one minted with **Full read access** can reach every read endpoint but is refused on any write; a narrower key is limited to the resources and actions you granted it.

If a request uses a key that lacks the scope for the endpoint it calls, Allegro rejects it with a `403 Forbidden` response even though the key is otherwise valid.

#### Using the key[​](#using-the-key "Direct link to Using the key")

Include the key as a `Bearer` value in the `Authorization` header of every request:

```http
Authorization: Bearer <your-key>

```

**Example with curl:**

```bash
curl https://your-instance.allegrocdp.com/api/v1/audience-members \
  -H "Authorization: Bearer <your-key>" \
  -H "Accept: application/json"

```

#### Revoking a key[​](#revoking-a-key "Direct link to Revoking a key")

To revoke a key, return to **Organization Settings → API Keys**, find the key in the list, and click **Revoke**. The key stops working immediately, and the revocation is recorded in the page's activity log.

A key can also lapse on its own: when it reaches the expiration you set, it stops authenticating automatically and cannot be extended. Rotate keys before they expire to avoid an interruption.


---

### Allegro Platform API

Version: 1.0

Export

* [OpenAPI Spec](/openapi/landlord.json)

Endpoints for platform operators. These routes are served only from the platform host and require a platform-owned API key — organization API keys cannot access them.

#### Authentication[​](#authentication "Direct link to Authentication")

* HTTP: Bearer Auth

| Security Scheme Type:      | http   |
| -------------------------- | ------ |
| HTTP Authorization Scheme: | bearer |


---

### Platform Health Summary

Report the pending job count for each configured queue, plus the failed job count, for consumption by an external monitor. Returns a 503 when the queue backend cannot be reached so naive HTTP checks trip on a degraded state.

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401

Unauthenticated


---

### List Tenants

Return every tenant on the platform. Restricted to super admins and only available in the landlord context.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401

Array of `TenantResource`

Unauthenticated


---

### Platform API Access

The Platform API is for **platform operators** — the people who run an Allegro installation, not the organizations hosted on it. Its endpoints report on the platform as a whole: the tenants it hosts and the health of its queues.

Not part of the organization-facing API

These endpoints are not available to organizations. If you are integrating an application against a single organization's data, you want the [REST API](/rest-api/) instead.

#### Where it is served[​](#where-it-is-served "Direct link to Where it is served")

The Platform API is served only from the platform host, never from an organization subdomain:

```text
https://allegrocdp.com/api/v1/landlord/...

```

A request to an organization host such as `acme.allegrocdp.com` is rejected with `403 Forbidden`, even with a valid key.

#### Platform keys only[​](#platform-keys-only "Direct link to Platform keys only")

Every Platform API request must carry a **platform-owned** API key. Allegro rejects all other credentials with `403 Forbidden`:

| Credential                                              | Result          |
| ------------------------------------------------------- | --------------- |
| Platform key                                            | Allowed         |
| Organization key (**Organization Settings → API Keys**) | `403 Forbidden` |
| Key belonging to an individual user                     | `403 Forbidden` |

The last row applies even when that user is a super admin. Being a super admin grants access to the Allegro admin; it does not grant an individual's API key access to the Platform API.

#### Creating a platform key[​](#creating-a-platform-key "Direct link to Creating a platform key")

1. Sign in to the Allegro admin as a super admin.
2. Open **Global Settings → API Keys**.
3. Click **Create Key**, give it a descriptive name (e.g. `platform-monitor`), choose its scopes, and confirm.
4. Copy the key value that appears — it is only shown once.

Store your key securely

The key value is displayed only at creation time. If you lose it, revoke the key and create a new one.

Platform keys carry the same `resource:action` scopes described in [API Authentication](/developer/api/authentication.md#token-scopes). A key whose scopes do not cover the endpoint it calls is rejected with `403 Forbidden` even though it is otherwise valid.

#### Using the key[​](#using-the-key "Direct link to Using the key")

Send the key as a `Bearer` value in the `Authorization` header:

```bash
curl https://allegrocdp.com/api/v1/landlord/health \
  -H "Authorization: Bearer <your-key>" \
  -H "Accept: application/json"

```

#### Revoking a key[​](#revoking-a-key "Direct link to Revoking a key")

Return to **Global Settings → API Keys**, find the key, and click **Revoke**. It stops working immediately.


---

### Allegro Browser SDK API

Version: 0.0.1

Export

* [OpenAPI Spec](/openapi/session.json)

Endpoints used by the Allegro Browser SDK.

#### Authentication[​](#authentication "Direct link to Authentication")

* HTTP: Bearer Auth

| Security Scheme Type:      | http   |
| -------------------------- | ------ |
| HTTP Authorization Scheme: | bearer |
| Bearer format:             | JWT    |


---

### Record Heartbeat

Push the page\_view event id onto the tenant's Redis FIFO list with a server timestamp and the cumulative active time on the page. The event id is trusted (UUID format only — no lookup). Each beat carries the running total of active whole seconds, so the latest beat for an event id supersedes earlier ones. No-op (204, before validation) when the SdkHeartbeat feature is disabled, so the endpoint is unobservable while off.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 204
* 422

No content

Validation error


---

### allegro.interactionEvaluate

allegro.interactionEvaluate

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 422

Validation error


---

### allegro.interactionEvaluateDebug

allegro.interactionEvaluateDebug

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 403
* 422

An error

Validation error


---

### Entitlement Check

Check whether the authenticated member has an active entitlement for the given product slug.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200


---

### List Active Entitlements

List all active entitlements for the authenticated audience member.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200

Array of `EntitlementResource`


---

### Get a single external profile for the authenticated audience member by provider

Get a single external profile for the authenticated audience member by provider

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200

`AudienceMemberExternalProfileResource`


---

### Identify Session

Create or retrieve an audience device session for the given email and device ID. If the audience member does not exist, they will be created. Always returns an unauthenticated session JWT, even if the device was previously authenticated. A device already identified as a different member is moved to the member for the given email.

Optional `attributes` are stored against the member, keyed by user attribute slug. Because identify is unauthenticated, a value is only written when the member has no value for that attribute yet; existing values are never overwritten. Every slug must be a defined, member-editable attribute and every value must pass its type and rules, or the request fails before the member is created: a 404 `USER_ATTRIBUTE_NOT_FOUND`, a 403 `USER_ATTRIBUTE_NOT_EDITABLE`, or a 422 with errors keyed `attributes.<slug>`.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 422

Validation error


---

### Initiate Checkout

Creates a hosted checkout session for a term and returns the provider URL. JWT is optional — authenticated members get their details pre-filled. Returns a 422 with code CHECKOUT\_UNAVAILABLE when the tenant has no payment provider capable of checkout active.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 422

Validation error


---

### Exchange Purchase Token

Exchange a one-time allegro\_purchase\_token for a JWT and entitlement data. The token works once and expires 10 minutes after checkout returns. The JWT is for the purchase's device session, or a new unauthenticated session when the buyer checked out as a guest.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 422

Validation error


---

### Create Event

Record a new event with the provided request data.

#### Responses[​](#responses "Direct link to Responses")

* 201


---

### Get Form

Fetch a form definition by its slug for rendering in the browser. Fields are resolved against the tenant's user attributes: each field carries its effective label plus the attribute's type, options, and validation rules. Fields whose attribute no longer exists or is no longer user-editable are omitted.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200


---

### Submit Form

Submit values for a form on behalf of the authenticated audience member. Only fields whose display conditions are currently met are validated and written: required fields must be present, and each value must pass the attribute's type and configured validation rules. A `null` value clears the member's stored value. Returns the updated values for the form's fields and a refreshed JWT.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 422

Validation error


---

### Verifies a Fundraise Up delivery against the connection the request host resolves to and queues it for
processing by its identifiers only. Returns 404 without a connection, 400 (with an error log line) without a
signing secret, for a bad signature, or for a body without an id, type and data.object.id, and 200
otherwise; ping and test events, and events from the mode the connection is not in, are logged and not queued

### Verifies a Fundraise Up delivery against the connection the request host resolves to and queues it for processing by its identifiers only. Returns 404 without a connection, 400 (with an error log line) without a signing secret, for a bad signature, or for a body without an id, type and data.object.id, and 200 otherwise; ping and test events, and events from the mode the connection is not in, are logged and not queued

Verifies a Fundraise Up delivery against the connection the request host resolves to and queues it for processing by its identifiers only. Returns 404 without a connection, 400 (with an error log line) without a signing secret, for a bad signature, or for a body without an id, type and data.object.id, and 200 otherwise; ping and test events, and events from the mode the connection is not in, are logged and not queued

#### Responses[​](#responses "Direct link to Responses")

* 200
* 400
* 404

Not found


---

### Get Interaction

Retrieve a single interaction by its ID or slug. Published interactions are publicly accessible; unpublished interactions require authorization.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 403

`InteractionResource`

Authorization error


---

### Request a combined magic link and one-time code

Sends a single email containing both a magic sign-in link and a six-digit one-time code. The reader can click the link (in any browser) or enter the code on this device. Creates the audience member if they do not already exist. Rate limited to 3 requests per email per minute. Both the link and the code expire in 30 minutes. Issuing a new request invalidates any prior code for the session.

When `registration.form` names a form and the email has no account yet, nothing is created or sent: the response is `registration_required` with that form. Sending the form's answers in `registration.values` creates the account with them and continues.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 422

Validation error


---

### Request Magic Link

Send a magic link email to the provided address for passwordless authentication. Creates the audience member if they do not already exist. Rate limited to 3 requests per email per minute.

When `registration.form` names a form and the email has no account yet, nothing is created or sent: the response is `registration_required` with that form. Sending the form's answers in `registration.values` creates the account with them and continues.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 422

Validation error


---

### Validate Magic Link

Validate a magic link token and authenticate the device session. Only the device that opens the link is authenticated. The audience member's email is marked as verified upon success.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 422

Validation error


---

### Request OTP

Email a six-digit one-time passcode for passwordless authentication. Creates the audience member if they do not already exist. Rate limited to 3 requests per email per minute. Issuing a new code invalidates any prior code for the session.

When `registration.form` names a form and the email has no account yet, nothing is created or sent: the response is `registration_required` with that form. Sending the form's answers in `registration.values` creates the account with them and continues.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 422

Validation error


---

### Validate OTP

Validate a six-digit code against the latest unexpired code for the requesting device session and authenticate that session synchronously.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 422

Validation error


---

### Record Recommendation Click

Reports that the reader clicked one served recommendation, keyed to the `request_id` the serving call returned. Always answers 204: the reader is navigating away and has no recourse, so a failed report is logged rather than surfaced.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 204
* 422

No content

Validation error


---

### Get Recommendations

Ranked article recommendations for the reader's device, from the tenant's configured engine. Answers an empty set rather than an error when the engine is unreachable: a reader cannot act on the difference, and a dead widget is a visible defect where an empty one is not.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 422

Validation error


---

### Destroy Session

Log out and delete the current device session. A `logout` event is recorded before the session is removed.

#### Responses[​](#responses "Direct link to Responses")

* 204

No content


---

### Get Session

Retrieve the current authenticated device session details.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200

`AudienceDeviceSessionResource`


---

### Update Profile

Update the authenticated audience member's own record. Fields the request omits are left as they are, so a caller can send only what changed. Only `name` is writable; the member's email is changed through its own verification flow. A refreshed JWT carrying the updated `audience_member` claim is returned.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 422

Validation error


---

### Refresh Session Token

Generate a new JWT for the current device session.

#### Responses[​](#responses "Direct link to Responses")

* 200


---

### Delete User Attribute

Clear the authenticated audience member's stored value for a user attribute. The attribute itself remains defined for the tenant and will continue to be returned with a `null` value. A refreshed JWT is returned. Returns a 403 `USER_ATTRIBUTE_NOT_EDITABLE` error if the attribute is not editable by the member, or a 404 `USER_ATTRIBUTE_NOT_FOUND` error if it is not defined or is private.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200


---

### List User Attributes

List every user attribute defined for the tenant along with the authenticated audience member's value for it. Attributes the member has never been given a value for are returned with a `null` value. Private attributes are omitted.

#### Responses[​](#responses "Direct link to Responses")

* 200

Array of `UserAttributeResource`


---

### Set User Attribute

Set the value of a single user attribute for the authenticated audience member. The value is validated against the attribute's type: `string` accepts any string, `number` accepts any numeric value, `boolean` accepts a boolean, and `enum` accepts one of the attribute's configured options. A refreshed JWT containing the updated attribute claims is returned. Returns a 403 `USER_ATTRIBUTE_NOT_EDITABLE` error if the attribute is not editable by the member, or a 404 `USER_ATTRIBUTE_NOT_FOUND` error if it is not defined or is private.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200


---

### Set User Attributes

Set the values of several user attributes for the authenticated audience member in one request, keyed by attribute slug. A `null` value clears the member's stored value for that attribute. Every slug is resolved and every value validated against its attribute's type and configured rules before anything is written, so the whole request fails without saving if one entry is bad: a 404 `USER_ATTRIBUTE_NOT_FOUND` error listing the unknown slugs, a 403 `USER_ATTRIBUTE_NOT_EDITABLE` error listing the slugs the member may not edit, or a 422 with errors keyed `values.<slug>`. A refreshed JWT containing the updated attribute claims is returned.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200


---

### Exchange Social Login Code

Exchange the one-time `allegro_social_code` a redirect-based social login appends to the returning page for the member's JWT. Each code works once, expires after five minutes, and only for the device that started the login.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 422

Validation error


---

### Get a published template by its slug

Used by the SDK to resolve `<allegro-template ref="...">` children.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200

`TemplateResource`


---

### Describe the authenticated identity behind the current request

A first-party session or a legacy user token returns the user as before. Organization- and platform-owned API keys authenticate as the Tenant or Platform, so a whitelisted shape is returned instead of the raw model to avoid leaking internal fields (e.g. the tenant's database name).

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401

`User`

Unauthenticated


---

### Allegro REST API

Version: 1.0

Export

* [OpenAPI Spec](/openapi/token.json)

Endpoints that use authenticated user tokens.

#### Authentication[​](#authentication "Direct link to Authentication")

* HTTP: Bearer Auth

| Security Scheme Type:      | http   |
| -------------------------- | ------ |
| HTTP Authorization Scheme: | bearer |


---

### Get Story Analytics

Returns how one story performed, by its `path` (e.g. `/news/story`), over a `window`: `publish` (since it was published, capped at a year; the default), `24h` or `7d`. Sections are `details` (catalog entry, null when the page isn't indexed yet), `performance` (against the site baseline, with a series), `sources`, `time_on_page`, `next_pages` and `gates`. Narrow with `include`. The `range`, `start` and `end` filters don't apply; `meta.range` is the range the window resolved to.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

`AnalyticsResource`

Unauthenticated

Validation error


---

### List Analytics Events

Returns the explorer's event stream, newest first, 50 per page. Pass `next_cursor` back as `before` for the next page. Narrow with `types`, `where[]` filters, or a `session` UUID.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

`AnalyticsResource`

Unauthenticated

Validation error


---

### Explore Events

Returns the Events explorer's chart and breakdown: event counts per type (up to six types, bucketed by hour, day or week to suit the range) and event counts by the `by` dimension (top 10, default `referrer`). Narrow with comma-separated `types` and `where[]` filters (`where[0][dimension]`, `where[0][operator]`, `where[0][value]`).

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

`AnalyticsResource`

Unauthenticated

Validation error


---

### Run Analytics Query

Runs a report definition, the same shape saved reports store, and returns its totals and bucketed series. This is read-only; it is a POST only because the definition is a nested body. The definition's preset `range` is used unless `start` and `end` are given.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

`AnalyticsResource`

Unauthenticated

Validation error


---

### Get Reader Analytics

Returns one registered reader's sessions and the event timeline of the selected one, built from their latest 500 events (`timeline.truncated` is true when there are more). Pass a `session` UUID to select another of their sessions. The reader's `name` and `email` are included only when the key also has the `audience-members:read` scope.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

`AnalyticsResource`

Unauthenticated

Validation error


---

### Get Realtime Analytics

Returns the Pulse: `counts` (readers now, last-hour page views and sign-ups, and last-hour counts per event type against the same hour a week ago), `minutes` (page views and sessions for each of the last 60 minutes), `sources` (last-hour channels and referrers) and `spiking` (stories well above their typical traffic). Narrow with `include`, e.g. `include=counts,spiking`. The date range filters don't apply; realtime data always covers the last hour.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

`AnalyticsResource`

Unauthenticated

Validation error


---

### List Analytics Reports

Lists the built-in reports, each naming the API endpoint (and `include` section) that returns its data, and one page of the tenant's saved reports. `search` matches names and descriptions; `area` narrows the built-ins to one area. Saved reports are paginated with `per_page` (1-100, default 20) and `page`; `meta.saved` describes the page.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403
* 422

`AnalyticsResource`

Unauthenticated

Authorization error

Validation error


---

### Run Analytics Report

Runs a saved report and returns it with its result, over its own preset range unless `range` or `start` and `end` are given.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

`AnalyticsResource`

Unauthenticated

Validation error


---

### Get Analytics Report

Returns one saved report: its name, description, definition (the same shape `POST /analytics/query` accepts) and a one-line summary.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401

`AnalyticsResource`

Unauthenticated


---

### Create Analytics Report

Saves a report the whole team can open from Analytics → Reports: a `name`, an optional `description`, whether it is `pinned` to the Pulse, and a `definition` in the same shape `POST /analytics/query` runs. Run it afterwards with `GET /analytics/reports/{id}/results`.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 201
* 401
* 403
* 422

`AnalyticsResource`

Unauthenticated

Authorization error

Validation error


---

### Get Analytics Schema

Lists what analytics can be asked for: event types seen in the range (with event, session and reader counts, narrowed by `where[]` filters), plus the measures, dimensions, filter operators, report resolutions and preset ranges, and the tenant's properties and products.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

`AnalyticsResource`

Unauthenticated

Validation error


---

### Get Event Counts

Returns the event count behind each Events view over the range: the numbers on the Events tabs.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

`AnalyticsResource`

Unauthenticated

Validation error


---

### Get Content Gate Analytics

Returns `summary` (headline stats, a series by gate type, and gates by type and article) and `latest` (the 10 most recent gate views).

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

`AnalyticsResource`

Unauthenticated

Validation error


---

### Get Login Analytics

Returns headline stats, a daily login series, and logins by member level, device and article.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

`AnalyticsResource`

Unauthenticated

Validation error


---

### Get Purchase Analytics

Returns revenue, purchases and average order against the previous period, with purchases by day, status and product.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

`AnalyticsResource`

Unauthenticated

Validation error


---

### Get Sign-up Analytics

Returns headline stats, a sign-up series by gate type, the sign-up funnel, and sign-ups by article.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

`AnalyticsResource`

Unauthenticated

Validation error


---

### Get Time on Site Analytics

Returns `summary` (headline stats, a daily engaged time series and the session length distribution) and `top_stories` (top `limit` by engaged time, default 10, max 50).

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

`AnalyticsResource`

Unauthenticated

Validation error


---

### Get Traffic Analytics

Returns the page views view: `overview` (headline stats against the previous period, with a page view and session series), `reading_hours` (a day by hour-of-day grid of the last 28 days), `sections` and `top_stories` (top `limit` by engaged time, default 10, max 50).

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

`AnalyticsResource`

Unauthenticated

Validation error


---

### List Audience Device Sessions

Retrieve all device sessions for a given audience member.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403

Array of `AudienceDeviceSessionResource`

Unauthenticated

Authorization error


---

### List Audience Member Events

Retrieve a paginated timeline of tracked events for an audience member, newest first. Events are read from whichever store the tenant is configured to use, so the results always match the admin dashboard.

The page size can be controlled with `per_page` (1-100).

Note: for tenants whose events are served by the ClickHouse analytics API, the timeline covers the 500 most recent events. `meta.total` reflects that window rather than the member's lifetime event count, and pages beyond it are empty. Tenants served from the database have no such limit.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403
* 422

Paginated set of `AudienceEventResource`

Unauthenticated

Authorization error

Validation error


---

### Delete Audience Member

Soft-delete an audience member by their ID.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 204
* 401
* 403

No content

Unauthenticated

Authorization error


---

### Delete External Profile

Delete the external profile for the given audience member and provider key.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 204
* 401
* 403

No content

Unauthenticated

Authorization error


---

### List External Profiles

List all external profiles for the given audience member.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403

Array of `AudienceMemberExternalProfileResource`

Unauthenticated

Authorization error


---

### Get External Profile

Get a single external profile for the given audience member by provider key.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403

`AudienceMemberExternalProfileResource`

Unauthenticated

Authorization error


---

### Upsert External Profile

Create or update an external profile for the given audience member and provider key.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403
* 422

Unauthenticated

Authorization error

Validation error


---

### Delete Foreign Key

Remove a foreign key from an audience member by its key name.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 204
* 401
* 403

No content

Unauthenticated

Authorization error


---

### List Foreign Keys

Retrieve all foreign keys associated with an audience member.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403

Array of `AudienceMemberForeignKeyResource`

Unauthenticated

Authorization error


---

### Create Foreign Key

Add a new foreign key to an audience member.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 201
* 401
* 403
* 422

`AudienceMemberForeignKeyResource`

Unauthenticated

Authorization error

Validation error


---

### List Audience Members

Retrieve a paginated list of audience members. Supports filtering by `email`, `foreign_key`, `product` (the slug of a product the member holds an active entitlement for), and optionally including soft-deleted members via `include_deleted`. The page size can be controlled with `per_page` (1-1000).

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403
* 422

Paginated set of `AudienceMemberResource`

Unauthenticated

Authorization error

Validation error


---

### Patch Audience Member

Partially update an audience member's attributes and meta data. Meta values set to `null` will be removed; all other values will be merged.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403
* 422

`AudienceMemberResource`

Unauthenticated

Authorization error

Validation error


---

### Get Audience Member

Retrieve a single audience member by their ID.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403

`AudienceMemberResource`

Unauthenticated

Authorization error


---

### Create Audience Member

Create a new audience member with the provided attributes and optional meta data.

If a deleted audience member has the same email, they are restored and updated with the provided attributes instead.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 201
* 401
* 403
* 422

`AudienceMemberResource`

Unauthenticated

Authorization error

Validation error


---

### Update Audience Member

Fully replace an audience member's attributes and metadata.

If meta is passed, all existing meta except file attribute values will be removed and replaced with the provided values. Otherwise, it will be left alone.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403
* 422

`AudienceMemberResource`

Unauthenticated

Authorization error

Validation error


---

### Delete User Attribute

Clear the given audience member's stored value for a user attribute. The attribute itself remains defined for the tenant and will continue to be returned with a `null` value.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 204
* 401
* 403

No content

Unauthenticated

Authorization error


---

### List User Attributes

List every user attribute defined for the tenant along with the given audience member's value for it. Attributes the member has never been given a value for are returned with a `null` value. A public File attribute's value is the file's URL. Private File attributes are admin-only and are never listed.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403

Array of `UserAttributeResource`

Unauthenticated

Authorization error


---

### Set User Attribute

Set the value of a single user attribute for the given audience member. The value is validated against the attribute's type: `string` accepts any string, `number` accepts any numeric value, `boolean` accepts a boolean, and `enum` accepts one of the attribute's configured options.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403

Unauthenticated

Authorization error


---

### Revoke Entitlement

Revoke a specific entitlement from an audience member.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 204
* 401
* 403

No content

Unauthenticated

Authorization error


---

### List Entitlements

Retrieve all entitlements for a given audience member, including their associated resources. Supports optional ?status=active|inactive filter.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403
* 422

Array of `EntitlementResource`

Unauthenticated

Authorization error

Validation error


---

### Get Entitlement

Retrieve a specific entitlement for a given audience member.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403

`EntitlementResource`

Unauthenticated

Authorization error


---

### Create Entitlement

Grant a new entitlement to an audience member.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 201
* 401
* 403
* 422

`EntitlementResource`

Unauthenticated

Authorization error

Validation error


---

### Flush Queued Events

Remove exactly `count` events from the front of the Redis list. The caller must pass `?count=N` where N matches the count returned by the list endpoint to prevent deleting events that arrived after the read.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 204
* 401
* 422

No content

Unauthenticated

Validation error


---

### List Queued Events

Return up to 10,000 events from the front of the Redis list.

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401

`EventBatchResource`

Unauthenticated


---

### Flush Queued Heartbeats

Remove exactly `count` heartbeats from the front of the Redis list (oldest first). The caller must pass `?count=N` where N matches the count returned by the list endpoint to prevent deleting heartbeats that arrived after the read.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 204
* 401
* 422

No content

Unauthenticated

Validation error


---

### List Queued Heartbeats

Return up to 10,000 heartbeats from the front of the Redis list.

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401

`HeartbeatBatchResource`

Unauthenticated


---

### Archive Interaction

Soft-delete an interaction. It stops being served and stops being evaluated, but can be brought back with the restore endpoint.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 204
* 401
* 403

No content

Unauthenticated

Authorization error


---

### Duplicate Interaction

Copy an interaction — actions, journeys, and trigger mode — into a new draft with a generated slug.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 201
* 401
* 403

`InteractionManagementResource`

Unauthenticated

Authorization error


---

### Delete Interaction

Permanently delete an interaction and its revision history. This cannot be undone.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 204
* 401
* 403

No content

Unauthenticated

Authorization error


---

### List Interactions

Retrieve a paginated list of interactions, most recently updated first. Filter with `status` (draft, published), `trigger_mode` (manual, automatic), and `search` (matches title and slug). Archived interactions are excluded unless `include_deleted` is set. Page size is controlled with `per_page` (1-200).

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403
* 422

Paginated set of `InteractionManagementResource`

Unauthenticated

Authorization error

Validation error


---

### Restore Interaction

Bring an archived interaction back as a draft. It stays unpublished until its status is set explicitly, so restoring can never resume firing it.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403

`InteractionManagementResource`

Unauthenticated

Authorization error


---

### Get Interaction

Retrieve a single interaction, addressed by its ID or its slug, with its full targeting configuration. Archived interactions are included and carry a `deleted_at`.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403

`InteractionManagementResource`

Unauthenticated

Authorization error


---

### Create Interaction

Create an interaction. A manual interaction needs at least one action; an automatic one may have none, leaving visitors who match no journey untouched. Journeys are only deep-validated for automatic interactions — a manual interaction's journeys are dormant until it is switched over.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 201
* 401
* 403
* 422

`InteractionManagementResource`

Unauthenticated

Authorization error

Validation error


---

### Unpublish Interaction

Return a published interaction to draft, taking it out of the targeting snapshot without archiving it.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403
* 422

`InteractionManagementResource`

Unauthenticated

Authorization error

Validation error


---

### Update Interaction

Replace an interaction's configuration. Omitting `slug` keeps the current one. A `revision_note` is recorded against the revision this save creates.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403
* 422

`InteractionManagementResource`

Unauthenticated

Authorization error

Validation error


---

### Delete Milestone

Permanently delete a milestone by its ID.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 204
* 401
* 403

No content

Unauthenticated

Authorization error


---

### List Milestones

Retrieve milestones, newest date first. Milestones are dated notes shown on analytics charts, optionally limited to some properties. Filter by date range, or by property to get the milestones its charts show.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403
* 422

Array of `MilestoneResource`

Unauthenticated

Authorization error

Validation error


---

### Get Milestone

Retrieve a single milestone by its ID.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403

`MilestoneResource`

Unauthenticated

Authorization error


---

### Create Milestone

Create a milestone. Leave `property_ids` empty to show it on every property's charts.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 201
* 401
* 403
* 422

`MilestoneResource`

Unauthenticated

Authorization error

Validation error


---

### Update Milestone

Update a milestone. Omitted fields keep their values; `property_ids` replaces the whole list when given.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403
* 422

`MilestoneResource`

Unauthenticated

Authorization error

Validation error


---

### Request Magic Link

Email a magic link to the member for passwordless sign-in, creating the audience member if they do not already exist. `return_url` must be on an allowed origin. `data` is passed to `MagicLinkRequested` listeners, such as newsletter subscriptions. Rate limited to 3 requests per email per minute, shared with the browser endpoint.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

Unauthenticated

Validation error


---

### Request OTP

Email a six-digit one-time passcode to the member, creating the audience member if they do not already exist. A new code replaces any prior code for the device. `data` is passed to `OtpRequested` listeners. Rate limited to 3 requests per email per minute, shared with the browser endpoint.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

Unauthenticated

Validation error


---

### Validate Magic Link

Redeem a magic link token and authenticate the `device_id` session, returning the member JWT for that session. The member's email is marked as verified.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

Unauthenticated

Validation error


---

### Validate OTP

Check a six-digit code against the latest code issued to `email` on the `device_id` session and authenticate that session, returning the member JWT. A code locks after 5 incorrect attempts.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

Unauthenticated

Validation error


---

### Delete Product

Permanently delete a product by its ID.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 204
* 401
* 403

No content

Unauthenticated

Authorization error


---

### List Products

Retrieve all products ordered by most recently created.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403

Array of `ProductResource`

Unauthenticated

Authorization error


---

### Get Product

Retrieve a single product by its ID.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403

`ProductResource`

Unauthenticated

Authorization error


---

### Create Product

Create a new product with the provided attributes.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 201
* 401
* 403
* 422

`ProductResource`

Unauthenticated

Authorization error

Validation error


---

### Update Product

Update the name of an existing product.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403
* 422

`ProductResource`

Unauthenticated

Authorization error

Validation error


---

### Get Template

Retrieve a single template by its ID.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403

`TemplateResource`

Unauthenticated

Authorization error


---

### Tenant Health Summary

Report the current tenant's Redis queue depths and the age of the oldest queued item, for consumption by an external monitor. Returns a 503 when Redis cannot be reached so naive HTTP checks trip on a degraded state.

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 403

Unauthenticated

Authorization error


---

### Record Recommendation Click

Reports a click on one served recommendation, keyed to the `request_id` the serving call returned. Answers 502 when the engine is unreachable.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 204
* 401
* 422

No content

Unauthenticated

Validation error


---

### List Recommendations

Ranked article recommendations for a device or article, from the tenant's configured engine. Answers 502 when the engine is unreachable.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

Unauthenticated

Validation error


---

### Preview Recommendations

Ranked recommendations for a hypothetical reading history, without a real reader session behind it. Answers 501 when the tenant's configured engine cannot preview, and 502 when it can but is unreachable.

#### Request[​](#request "Direct link to request")

#### Responses[​](#responses "Direct link to Responses")

* 200
* 401
* 422

Unauthenticated

Validation error


---

### @alleyinteractive/allegro-platform

#### Functions[​](#functions "Direct link to Functions")

* [createAllegroSDK](/developer/api-reference/functions/createAllegroSDK.md)
* [enableDebugMode](/developer/api-reference/functions/enableDebugMode.md)
* [ensureComponentsLoaded](/developer/api-reference/functions/ensureComponentsLoaded.md)
* [hydrateQueue](/developer/api-reference/functions/hydrateQueue.md)

#### Interfaces[​](#interfaces "Direct link to Interfaces")

* [AllegroConfig](/developer/api-reference/interfaces/AllegroConfig.md)
* [AllegroSDK](/developer/api-reference/interfaces/AllegroSDK.md)
* [InteractionActionCookie](/developer/api-reference/interfaces/InteractionActionCookie.md)
* [InteractionActionCss](/developer/api-reference/interfaces/InteractionActionCss.md)
* [InteractionActionJavaScript](/developer/api-reference/interfaces/InteractionActionJavaScript.md)
* [InteractionActionTemplate](/developer/api-reference/interfaces/InteractionActionTemplate.md)
* [InteractionNamespace](/developer/api-reference/interfaces/InteractionNamespace.md)
* [InteractionResponse](/developer/api-reference/interfaces/InteractionResponse.md)
* [InteractionTemplateData](/developer/api-reference/interfaces/InteractionTemplateData.md)
* [MemberEntitlement](/developer/api-reference/interfaces/MemberEntitlement.md)
* [MemberNamespace](/developer/api-reference/interfaces/MemberNamespace.md)
* [MemberProfile](/developer/api-reference/interfaces/MemberProfile.md)
* [MetersNamespace](/developer/api-reference/interfaces/MetersNamespace.md)
* [MeterUsage](/developer/api-reference/interfaces/MeterUsage.md)
* [PageDataSource](/developer/api-reference/interfaces/PageDataSource.md)
* [PublicPlan](/developer/api-reference/interfaces/PublicPlan.md)
* [PurchaseNamespace](/developer/api-reference/interfaces/PurchaseNamespace.md)
* [PurchaseTokenExchangeResponse](/developer/api-reference/interfaces/PurchaseTokenExchangeResponse.md)
* [RecommendationItem](/developer/api-reference/interfaces/RecommendationItem.md)
* [RecommendationSet](/developer/api-reference/interfaces/RecommendationSet.md)
* [RecommendationsGetOptions](/developer/api-reference/interfaces/RecommendationsGetOptions.md)
* [ShowLoginOptions](/developer/api-reference/interfaces/ShowLoginOptions.md)
* [TenantConfig](/developer/api-reference/interfaces/TenantConfig.md)
* [TrackEventData](/developer/api-reference/interfaces/TrackEventData.md)
* [TrackResponse](/developer/api-reference/interfaces/TrackResponse.md)

#### Recommendations[​](#recommendations "Direct link to Recommendations")

* [RecommendationsNamespace](/developer/api-reference/interfaces/RecommendationsNamespace.md)

#### Type Aliases[​](#type-aliases "Direct link to Type Aliases")

* [AllegroCallback](/developer/api-reference/type-aliases/AllegroCallback.md)
* [AudienceMember](/developer/api-reference/type-aliases/AudienceMember.md)
* [IdentifySessionResponse](/developer/api-reference/type-aliases/IdentifySessionResponse.md)
* [InteractionAction](/developer/api-reference/type-aliases/InteractionAction.md)
* [MagicLinkRequestResponse](/developer/api-reference/type-aliases/MagicLinkRequestResponse.md)
* [MagicLinkValidateResponse](/developer/api-reference/type-aliases/MagicLinkValidateResponse.md)
* [MemberJwtPayload](/developer/api-reference/type-aliases/MemberJwtPayload.md)
* [MeterUsageMap](/developer/api-reference/type-aliases/MeterUsageMap.md)
* [SessionResponse](/developer/api-reference/type-aliases/SessionResponse.md)
* [SocialLoginResponse](/developer/api-reference/type-aliases/SocialLoginResponse.md)
* [UserAttributeValue](/developer/api-reference/type-aliases/UserAttributeValue.md)

#### Variables[​](#variables "Direct link to Variables")

* [logger](/developer/api-reference/variables/logger.md)


---

### Function: createAllegroSDK()

> **createAllegroSDK**(`config`): [`AllegroSDK`](/developer/api-reference/interfaces/AllegroSDK.md)

Defined in: [allegro.ts:46](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/allegro.ts#L46)

Allegro SDK

#### Parameters[​](#parameters "Direct link to Parameters")

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `config`  | [`AllegroConfig`](/developer/api-reference/interfaces/AllegroConfig.md) |

#### Returns[​](#returns "Direct link to Returns")

[`AllegroSDK`](/developer/api-reference/interfaces/AllegroSDK.md)


---

### Function: enableDebugMode()

> **enableDebugMode**(): `void`

Defined in: [logger.ts:39](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/logger.ts#L39)

Enable debug mode.

#### Returns[​](#returns "Direct link to Returns")

`void`

#### Todo[​](#todo "Direct link to Todo")

Consider using EventTarget.prototype.addEventListener instead here to catch all events.


---

### Function: ensureComponentsLoaded()

> **ensureComponentsLoaded**(): `Promise`<`void`>

Defined in: [components-loader.ts:47](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/components-loader.ts#L47)

Inject the components bundle, resolving once it has executed and defined the custom elements. Injected only once per page however many times this is called, and rejects when the tenant has no compiled bundle.

Injected as `type="module"`, because the bundle is an ES module whose top-level declarations would otherwise leak into the host page's global lexical scope and collide with its identifiers.

#### Returns[​](#returns "Direct link to Returns")

`Promise`<`void`>


---

### Function: hydrateQueue()

> **hydrateQueue**(`sdk`): `void`

Defined in: [queue.ts:4](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/queue.ts#L4)

#### Parameters[​](#parameters "Direct link to Parameters")

| Parameter | Type                                                              |
| --------- | ----------------------------------------------------------------- |
| `sdk`     | [`AllegroSDK`](/developer/api-reference/interfaces/AllegroSDK.md) |

#### Returns[​](#returns "Direct link to Returns")

`void`


---

### Interface: AllegroConfig

Defined in: [types.ts:81](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L81)

Configuration passed to [createAllegroSDK](/developer/api-reference/functions/createAllegroSDK.md).

You typically don't construct this yourself — it is embedded in the loader script generated by the platform and injected into the page automatically.

#### Properties[​](#properties "Direct link to Properties")

| Property               | Type                                                                                          | Description                                                                                                                                                                                                                                                                              | Defined in                                                                                                                                                         |
| ---------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| []()`apiBaseUrl`       | `string`                                                                                      | Base URL for API calls. Derived from the script tag's src attribute.                                                                                                                                                                                                                     | [types.ts:83](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L83)   |
| []()`custom?`          | `Record`<`string`, `string` | `number` | `boolean`>                                         | Custom key/value attributes sent to the evaluate endpoint's `custom` channel.                                                                                                                                                                                                            | [types.ts:114](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L114) |
| []()`debug?`           | `boolean`                                                                                     | Enable debug mode for verbose SDK logging and allegro:\* event tracing.                                                                                                                                                                                                                  | [types.ts:89](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L89)   |
| []()`interactions?`    | `boolean`                                                                                     | Automatic server-side interaction targeting (the `/interactions/evaluate` call fired once per page load). Defaults to `true`; set `false` to suppress the automatic evaluation (and the SPA watcher) and rely solely on manual `interaction.trigger()` / `interaction.evaluate()` calls. | [types.ts:96](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L96)   |
| []()`interactionsSpa?` | `boolean`                                                                                     | Opt into re-evaluating interactions on single-page-app navigation. When `true`, the SDK watches history navigation (pushState/replaceState/popstate) and re-runs targeting on route change. Defaults to `false`. Ignored when `interactions` is `false`.                                 | [types.ts:103](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L103) |
| []()`pageData?`        | `Record`<`string`, [`PageDataSource`](/developer/api-reference/interfaces/PageDataSource.md)> | Configurable page data source mappings. Merged over defaults.                                                                                                                                                                                                                            | [types.ts:85](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L85)   |
| []()`tenant?`          | [`TenantConfig`](/developer/api-reference/interfaces/TenantConfig.md)                         | Tenant configuration embedded by the ClientController loader script.                                                                                                                                                                                                                     | [types.ts:87](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L87)   |


---

### Interface: AllegroSDK

Defined in: [types.ts:135](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L135)

The top-level Allegro SDK instance, available as `window.allegro`.

#### Example[​](#example "Direct link to Example")

```ts
window.allegro.push((allegro) => {
  console.log(allegro.member.isAuthenticated());
});

```

#### Methods[​](#methods "Direct link to Methods")

##### debug()?[​](#debug "Direct link to debug()?")

> `optional` **debug**(): `void`

Defined in: [types.ts:225](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L225)

Enable SDK debug mode from the console: `window.allegro.debug()`

###### Returns[​](#returns "Direct link to Returns")

`void`

***

##### push()[​](#push "Direct link to push()")

> **push**(`callback`): `void`

Defined in: [types.ts:153](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L153)

Enqueue a callback to run once the SDK is ready.

If the SDK has already initialised, the callback is invoked synchronously. This mirrors the `window.allegro.push(fn)` usage pattern.

###### Parameters[​](#parameters "Direct link to Parameters")

| Parameter  | Type                                                                          | Description                                                |
| ---------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `callback` | [`AllegroCallback`](/developer/api-reference/type-aliases/AllegroCallback.md) | Function that receives the fully initialised SDK instance. |

###### Returns[​](#returns-1 "Direct link to Returns")

`void`

###### Example[​](#example-1 "Direct link to Example")

```ts
window.allegro.push((allegro) => {
  if (allegro.member.isAuthenticated()) {
    console.log('Logged in!');
  }
});

```

***

##### renderComponentsIn()[​](#rendercomponentsin "Direct link to renderComponentsIn()")

> **renderComponentsIn**(`root`): `void`

Defined in: [types.ts:238](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L238)

Render all registered Allegro components found within the given root. Use this to render components inside a shadow DOM or other non-document root.

###### Parameters[​](#parameters-1 "Direct link to Parameters")

| Parameter | Type                                    |
| --------- | --------------------------------------- |
| `root`    | `Element` | `Document` | `ShadowRoot` |

###### Returns[​](#returns-2 "Direct link to Returns")

`void`

###### Example[​](#example-2 "Direct link to Example")

```ts
window.allegro.push((allegro) => {
  allegro.renderComponentsIn(myShadowRoot);
});

```

***

##### track()[​](#track "Direct link to track()")

> **track**(`eventName`, `data?`): `Promise`<[`TrackResponse`](/developer/api-reference/interfaces/TrackResponse.md)>

Defined in: [types.ts:174](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L174)

Track a named event with optional metadata.

Page context (URL, title, referer) is collected automatically. Pass additional fields via `data` to enrich the event.

###### Parameters[​](#parameters-2 "Direct link to Parameters")

| Parameter   | Type                                                                      | Description                                                |
| ----------- | ------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `eventName` | `string`                                                                  | Descriptive snake\_case event name, e.g. `"article_read"`. |
| `data?`     | [`TrackEventData`](/developer/api-reference/interfaces/TrackEventData.md) | Optional event metadata.                                   |

###### Returns[​](#returns-3 "Direct link to Returns")

`Promise`<[`TrackResponse`](/developer/api-reference/interfaces/TrackResponse.md)>

Resolves with the recorded event ID.

###### Example[​](#example-3 "Direct link to Example")

```ts
await allegro.track('article_read', {
  content_id: '12345',
  content_type: 'article',
  publisher: 'newsroom',
});

```

#### Properties[​](#properties "Direct link to Properties")

| Property                     | Type                                                                                          | Description                                                                                                                                                                                                                                                                                                     | Defined in                                                                                                                                                         |
| ---------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| []()`components`             | `Record`<`string`, *typeof* `HTMLElement`>                                                    | Registered custom web components. Empty until the components bundle has loaded.                                                                                                                                                                                                                                 | [types.ts:219](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L219) |
| []()`forms`                  | `FormsNamespace`                                                                              | Form fetching and submission methods.                                                                                                                                                                                                                                                                           | [types.ts:213](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L213) |
| []()`http`                   | `HttpClient`                                                                                  | HTTP client pre-configured with the session JWT and base URL. Use this to make authenticated API calls to the Allegro backend from outside the SDK, the same way internal modules do. **Example** `window.allegro.push(async (allegro) => { const data = await allegro.http.get('/api/some-endpoint'); });`     | [types.ts:189](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L189) |
| []()`interaction`            | [`InteractionNamespace`](/developer/api-reference/interfaces/InteractionNamespace.md)         | Interaction trigger and management methods.                                                                                                                                                                                                                                                                     | [types.ts:195](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L195) |
| []()`magicLinkValidation?`   | `"authenticated"` | `"failed"` | `null`                                                     | The result of magic link token validation, if one was attempted on this page load. Set synchronously before the corresponding window event is dispatched, so components that load after the event fires can still read the outcome.                                                                             | [types.ts:246](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L246) |
| []()`member`                 | [`MemberNamespace`](/developer/api-reference/interfaces/MemberNamespace.md)                   | Member authentication and identity methods.                                                                                                                                                                                                                                                                     | [types.ts:192](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L192) |
| []()`meters`                 | [`MetersNamespace`](/developer/api-reference/interfaces/MetersNamespace.md)                   | Meter usage from the most recent interaction evaluation. **Example** `window.allegro.push((allegro) => { console.log(allegro.meters.get('monthly-articles')?.remaining); });`                                                                                                                                   | [types.ts:207](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L207) |
| []()`purchase`               | [`PurchaseNamespace`](/developer/api-reference/interfaces/PurchaseNamespace.md)               | Purchase initiation and token exchange methods.                                                                                                                                                                                                                                                                 | [types.ts:210](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L210) |
| []()`recommendations`        | [`RecommendationsNamespace`](/developer/api-reference/interfaces/RecommendationsNamespace.md) | Ranked recommendations and click reporting.                                                                                                                                                                                                                                                                     | [types.ts:216](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L216) |
| []()`socialLoginError?`      | `string` | `null`                                                                            | Why the redirect-based social login on this page load failed, e.g. `"auth_cancelled"`, `"no_email"`, `"auth_failed"` or `"exchange_failed"`. Set alongside `socialLoginValidation = 'failed'`.                                                                                                                  | [types.ts:261](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L261) |
| []()`socialLoginValidation?` | `"authenticated"` | `"failed"` | `"pending"` | `null`                                      | The result of exchanging a redirect-based social login's `?allegro_social_code=`, or of an `?allegro_social_error=` return, if one happened on this page load. Set synchronously before the corresponding window event is dispatched, so components that load after the event fires can still read the outcome. | [types.ts:255](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L255) |
| []()`tenant`                 | [`TenantConfig`](/developer/api-reference/interfaces/TenantConfig.md)                         | Tenant-specific configuration (login providers, cookie domain, etc.).                                                                                                                                                                                                                                           | [types.ts:222](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L222) |


---

### Interface: InteractionActionCookie

Defined in: [interaction/types.ts:222](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L222)

#### Extends[​](#extends "Direct link to Extends")

* `InteractionActionBase`

#### Properties[​](#properties "Direct link to Properties")

| Property                     | Type                                               | Description                                               | Inherited from                                | Defined in                                                                                                                                                                                 |
| ---------------------------- | -------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| []()`delay_scroll_selector?` | `string` | `null`                                 | -                                                         | `InteractionActionBase.delay_scroll_selector` | [interaction/types.ts:152](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L152) |
| []()`delay_scroll_unit?`     | `"px"` | `"percent"` | `null`                    | -                                                         | `InteractionActionBase.delay_scroll_unit`     | [interaction/types.ts:151](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L151) |
| []()`delay_type?`            | `"scroll"` | `"time"` | `"truncation"` | `null` | -                                                         | `InteractionActionBase.delay_type`            | [interaction/types.ts:149](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L149) |
| []()`delay_value?`           | `number` | `null`                                 | -                                                         | `InteractionActionBase.delay_value`           | [interaction/types.ts:150](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L150) |
| []()`domain`                 | `string` | `null`                                 | -                                                         | -                                             | [interaction/types.ts:229](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L229) |
| []()`expires_days`           | `number` | `null`                                 | -                                                         | -                                             | [interaction/types.ts:230](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L230) |
| []()`name`                   | `string`                                           | -                                                         | -                                             | [interaction/types.ts:224](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L224) |
| []()`path`                   | `string`                                           | -                                                         | -                                             | [interaction/types.ts:228](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L228) |
| []()`readable?`              | `boolean`                                          | Missing on actions saved before readable cookies existed. | -                                             | [interaction/types.ts:227](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L227) |
| []()`type`                   | `"cookie"`                                         | -                                                         | -                                             | [interaction/types.ts:223](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L223) |
| []()`value`                  | `string`                                           | -                                                         | -                                             | [interaction/types.ts:225](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L225) |


---

### Interface: InteractionActionCss

Defined in: [interaction/types.ts:217](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L217)

#### Extends[​](#extends "Direct link to Extends")

* `InteractionActionBase`

#### Properties[​](#properties "Direct link to Properties")

| Property                     | Type                                               | Inherited from                                | Defined in                                                                                                                                                                                 |
| ---------------------------- | -------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| []()`code`                   | `string`                                           | -                                             | [interaction/types.ts:219](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L219) |
| []()`delay_scroll_selector?` | `string` | `null`                                 | `InteractionActionBase.delay_scroll_selector` | [interaction/types.ts:152](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L152) |
| []()`delay_scroll_unit?`     | `"px"` | `"percent"` | `null`                    | `InteractionActionBase.delay_scroll_unit`     | [interaction/types.ts:151](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L151) |
| []()`delay_type?`            | `"scroll"` | `"time"` | `"truncation"` | `null` | `InteractionActionBase.delay_type`            | [interaction/types.ts:149](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L149) |
| []()`delay_value?`           | `number` | `null`                                 | `InteractionActionBase.delay_value`           | [interaction/types.ts:150](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L150) |
| []()`type`                   | `"css"`                                            | -                                             | [interaction/types.ts:218](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L218) |


---

### Interface: InteractionActionJavaScript

Defined in: [interaction/types.ts:212](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L212)

#### Extends[​](#extends "Direct link to Extends")

* `InteractionActionBase`

#### Properties[​](#properties "Direct link to Properties")

| Property                     | Type                                               | Inherited from                                | Defined in                                                                                                                                                                                 |
| ---------------------------- | -------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| []()`code`                   | `string`                                           | -                                             | [interaction/types.ts:214](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L214) |
| []()`delay_scroll_selector?` | `string` | `null`                                 | `InteractionActionBase.delay_scroll_selector` | [interaction/types.ts:152](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L152) |
| []()`delay_scroll_unit?`     | `"px"` | `"percent"` | `null`                    | `InteractionActionBase.delay_scroll_unit`     | [interaction/types.ts:151](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L151) |
| []()`delay_type?`            | `"scroll"` | `"time"` | `"truncation"` | `null` | `InteractionActionBase.delay_type`            | [interaction/types.ts:149](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L149) |
| []()`delay_value?`           | `number` | `null`                                 | `InteractionActionBase.delay_value`           | [interaction/types.ts:150](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L150) |
| []()`type`                   | `"javascript"`                                     | -                                             | [interaction/types.ts:213](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L213) |


---

### Interface: InteractionActionTemplate

Defined in: [interaction/types.ts:162](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L162)

#### Extends[​](#extends "Direct link to Extends")

* `InteractionActionBase`

#### Properties[​](#properties "Direct link to Properties")

| Property                     | Type                                                                                                  | Description                                                                                        | Inherited from                                | Defined in                                                                                                                                                                                 |
| ---------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| []()`delay_scroll_selector?` | `string` | `null`                                                                                    | -                                                                                                  | `InteractionActionBase.delay_scroll_selector` | [interaction/types.ts:152](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L152) |
| []()`delay_scroll_unit?`     | `"px"` | `"percent"` | `null`                                                                       | -                                                                                                  | `InteractionActionBase.delay_scroll_unit`     | [interaction/types.ts:151](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L151) |
| []()`delay_type?`            | `"scroll"` | `"time"` | `"truncation"` | `null`                                                    | -                                                                                                  | `InteractionActionBase.delay_type`            | [interaction/types.ts:149](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L149) |
| []()`delay_value?`           | `number` | `null`                                                                                    | -                                                                                                  | `InteractionActionBase.delay_value`           | [interaction/types.ts:150](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L150) |
| []()`field_values`           | `TemplateFieldValueEntry`\[]                                                                          | -                                                                                                  | -                                             | [interaction/types.ts:166](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L166) |
| []()`html_fields?`           | `string`\[]                                                                                           | Dotted paths of rich text fields, whose values the server has cleaned and the SDK inserts as HTML. | -                                             | [interaction/types.ts:168](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L168) |
| []()`placement_method`       | `"replace"` | `"append"` | `"prepend"` | `"before"` | `"after"` | `"truncate"` | `null`         | -                                                                                                  | -                                             | [interaction/types.ts:169](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L169) |
| []()`plans?`                 | [`PublicPlan`](/developer/api-reference/interfaces/PublicPlan.md)\[]                                  | The selected offer's plans, in offer order; present only when the template supports plans.         | -                                             | [interaction/types.ts:175](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L175) |
| []()`target_selector`        | `string` | `null`                                                                                    | -                                                                                                  | -                                             | [interaction/types.ts:165](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L165) |
| []()`template`               | [`InteractionTemplateData`](/developer/api-reference/interfaces/InteractionTemplateData.md) | `null` | -                                                                                                  | -                                             | [interaction/types.ts:173](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L173) |
| []()`template_id`            | `string`                                                                                              | -                                                                                                  | -                                             | [interaction/types.ts:164](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L164) |
| []()`truncation_count?`      | `number` | `null`                                                                                    | -                                                                                                  | -                                             | [interaction/types.ts:171](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L171) |
| []()`truncation_style?`      | `"cut"` | `"blur"` | `null`                                                                         | -                                                                                                  | -                                             | [interaction/types.ts:172](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L172) |
| []()`truncation_unit?`       | `"paragraphs"` | `"words"` | `null`                                                                 | -                                                                                                  | -                                             | [interaction/types.ts:170](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L170) |
| []()`type`                   | `"template"`                                                                                          | -                                                                                                  | -                                             | [interaction/types.ts:163](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L163) |


---

### Interface: InteractionNamespace

Defined in: [interaction/types.ts:17](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L17)

Methods for triggering and managing on-page interactions.

Access this namespace via `allegro.interaction`.

#### Methods[​](#methods "Direct link to Methods")

##### evaluate()[​](#evaluate "Direct link to evaluate()")

> **evaluate**(): `Promise`<`void`>

Defined in: [interaction/types.ts:86](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L86)

Re-run server-side interaction targeting for the current page and render the matches. Safe to call manually — e.g. from a single-page-app router hook after navigation.

Idempotent across calls: interactions rendered by a previous `evaluate()` that no longer match are removed before the new matches render, so stale content from a prior route does not linger.

Runs even when `config.interactions` is `false` — that flag only suppresses the automatic on-load evaluation, not manual calls. No-op in preview mode and non-browser contexts.

###### Returns[​](#returns "Direct link to Returns")

`Promise`<`void`>

###### Example[​](#example "Direct link to Example")

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

```

***

##### experiments()[​](#experiments "Direct link to experiments()")

> **experiments**(): `Record`<`string`, `string` | `null`>

Defined in: [interaction/types.ts:93](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L93)

The visitor's A/B test assignments from the most recent evaluation: experiment id → variant id, or `null` when they are not in that test. Opaque labels, safe to forward to your own analytics.

###### Returns[​](#returns-1 "Direct link to Returns")

`Record`<`string`, `string` | `null`>

***

##### remove()[​](#remove "Direct link to remove()")

> **remove**(`slug`): `void`

Defined in: [interaction/types.ts:105](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L105)

Remove an active interaction from the DOM.

###### Parameters[​](#parameters "Direct link to Parameters")

| Parameter | Type     | Description                            |
| --------- | -------- | -------------------------------------- |
| `slug`    | `string` | The slug of the interaction to remove. |

###### Returns[​](#returns-2 "Direct link to Returns")

`void`

###### Example[​](#example-1 "Direct link to Example")

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

```

***

##### renderActions()[​](#renderactions "Direct link to renderActions()")

> **renderActions**(`actions`, `options?`): `Promise`<`void`>

Defined in: [interaction/types.ts:57](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L57)

Execute a pre-built set of interaction actions directly.

This is the rendering half of [trigger](#trigger). Use it when you have already constructed the actions array (e.g. from local files in allegro-preview) and want to run them through the real SDK pipeline without fetching from the API.

###### Parameters[​](#parameters-1 "Direct link to Parameters")

| Parameter              | Type                                                                                                                            | Description                                                                                                                                                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `actions`              | [`InteractionAction`](/developer/api-reference/type-aliases/InteractionAction.md)\[]                                            | The actions to execute.                                                                                                                                                                                                          |
| `options?`             | { `attribution?`: `TemplateAttribution`; `data?`: `Record`<`string`, `unknown`>; `skipDelays?`: `boolean`; `slug?`: `string`; } | -                                                                                                                                                                                                                                |
| `options.attribution?` | `TemplateAttribution`                                                                                                           | Decision attribution for interactions matched by server-side targeting evaluation. Threaded into template-view tracking events as `interaction_id`/`journey_id` for later analysis. Omitted for manually triggered interactions. |
| `options.data?`        | `Record`<`string`, `unknown`>                                                                                                   | Arbitrary data passed to Alpine template context.                                                                                                                                                                                |
| `options.skipDelays?`  | `boolean`                                                                                                                       | When true, skip scroll/time delays. Defaults to auto-detecting magic-link / allegro\_token in URL.                                                                                                                               |
| `options.slug?`        | `string`                                                                                                                        | Optional slug used for cleanup and Alpine context.                                                                                                                                                                               |

###### Returns[​](#returns-3 "Direct link to Returns")

`Promise`<`void`>

***

##### trigger()[​](#trigger "Direct link to trigger()")

> **trigger**(`slug`, `data?`): `Promise`<[`InteractionResponse`](/developer/api-reference/interfaces/InteractionResponse.md)>

Defined in: [interaction/types.ts:37](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L37)

Trigger an interaction by its slug.

Fetches the interaction from the API and executes its configured actions (template injection, CSS, JavaScript, cookies, etc.) on the current page.

###### Parameters[​](#parameters-2 "Direct link to Parameters")

| Parameter | Type                          | Description                                                                                |
| --------- | ----------------------------- | ------------------------------------------------------------------------------------------ |
| `slug`    | `string`                      | The interaction's unique slug as configured in the dashboard.                              |
| `data?`   | `Record`<`string`, `unknown`> | Arbitrary data passed to the interaction for use in template field values or action logic. |

###### Returns[​](#returns-4 "Direct link to Returns")

`Promise`<[`InteractionResponse`](/developer/api-reference/interfaces/InteractionResponse.md)>

The interaction record returned by the API.

###### Example[​](#example-2 "Direct link to Example")

```ts
await allegro.interaction.trigger('newsletter-signup');

// With extra data
await allegro.interaction.trigger('welcome-banner', { source: 'homepage' });

```

***

##### ungate()[​](#ungate "Direct link to ungate()")

> **ungate**(`slug`): `void`

Defined in: [interaction/types.ts:117](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L117)

Reveal content that was gated by an interaction.

###### Parameters[​](#parameters-3 "Direct link to Parameters")

| Parameter | Type     | Description                                              |
| --------- | -------- | -------------------------------------------------------- |
| `slug`    | `string` | The slug of the interaction whose gate should be lifted. |

###### Returns[​](#returns-5 "Direct link to Returns")

`void`

###### Example[​](#example-3 "Direct link to Example")

```ts
allegro.interaction.ungate('paywall');

```


---

### Interface: InteractionResponse

Defined in: [interaction/types.ts:131](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L131)

API response shape returned by [InteractionNamespace.trigger](/developer/api-reference/interfaces/InteractionNamespace.md#trigger).

#### Properties[​](#properties "Direct link to Properties")

| Property      | Type                                                                                 | Description                                                              | Defined in                                                                                                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| []()`actions` | [`InteractionAction`](/developer/api-reference/type-aliases/InteractionAction.md)\[] | Actions to execute on the page. The SDK handles execution automatically. | [interaction/types.ts:136](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L136) |
| []()`id`      | `string`                                                                             | -                                                                        | [interaction/types.ts:132](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L132) |
| []()`slug`    | `string`                                                                             | -                                                                        | [interaction/types.ts:134](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L134) |
| []()`title`   | `string`                                                                             | -                                                                        | [interaction/types.ts:133](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L133) |


---

### Interface: InteractionTemplateData

Defined in: [interaction/types.ts:178](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L178)

#### Properties[​](#properties "Direct link to Properties")

| Property                | Type        | Defined in                                                                                                                                                                                 |
| ----------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| []()`css`               | `string`    | [interaction/types.ts:183](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L183) |
| []()`external_css_urls` | `string`\[] | [interaction/types.ts:185](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L185) |
| []()`html`              | `string`    | [interaction/types.ts:182](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L182) |
| []()`id`                | `string`    | [interaction/types.ts:179](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L179) |
| []()`js`                | `string`    | [interaction/types.ts:184](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L184) |
| []()`slug`              | `string`    | [interaction/types.ts:181](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L181) |
| []()`title`             | `string`    | [interaction/types.ts:180](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L180) |


---

### Interface: MemberEntitlement

Defined in: [types.ts:1351](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1351)

A single entitlement record for an audience member.

#### Indexable[​](#indexable "Direct link to Indexable")

> \[`key`: `string`]: `unknown`

#### Properties[​](#properties "Direct link to Properties")

| Property   | Type     | Defined in                                                                                                                                                           |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| []()`id`   | `string` | [types.ts:1352](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1352) |
| []()`name` | `string` | [types.ts:1353](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1353) |


---

### Interface: MemberNamespace

Defined in: [types.ts:340](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L340)

Methods for authenticating and identifying audience members.

Access this namespace via `allegro.member`.

#### Example[​](#example "Direct link to Example")

```ts
window.allegro.push((allegro) => {
  if (allegro.member.isAuthenticated()) {
    const payload = allegro.member.sessionFromJwt();
    console.log('Hello,', payload?.audience_member.name);
  }
});

```

#### Authentication[​](#authentication "Direct link to Authentication")

Logs the current member out, clears the session JWT, and dispatches `allegro:logout`.

##### logout()[​](#logout "Direct link to logout()")

> **logout**(): `Promise`<`void`>

Defined in: [types.ts:428](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L428)

###### Returns[​](#returns "Direct link to Returns")

`Promise`<`void`>

###### Example[​](#example-1 "Direct link to Example")

```ts
await allegro.member.logout();

```

#### Authentication[​](#authentication-1 "Direct link to Authentication")

Returns `true` if the current session has a valid, authenticated JWT.

An authenticated session means the member has completed a login flow (magic link, social login, etc.). An identified-but-not-authenticated session only has an email association.

##### isAuthenticated()[​](#isauthenticated "Direct link to isAuthenticated()")

> **isAuthenticated**(): `boolean`

Defined in: [types.ts:362](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L362)

###### Returns[​](#returns-1 "Direct link to Returns")

`boolean`

###### Example[​](#example-2 "Direct link to Example")

```ts
if (allegro.member.isAuthenticated()) {
  showMemberContent();
} else {
  showLoginPrompt();
}

```

#### Authentication[​](#authentication-2 "Direct link to Authentication")

Returns `true` if the session has a stored JWT — either identified or fully authenticated.

Use this to check whether an email has been associated with the session without requiring a completed login.

##### isIdentified()[​](#isidentified "Direct link to isIdentified()")

> **isIdentified**(): `boolean`

Defined in: [types.ts:371](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L371)

###### Returns[​](#returns-2 "Direct link to Returns")

`boolean`

#### Authentication[​](#authentication-3 "Direct link to Authentication")

Returns the raw session JWT string, or `null` if no valid JWT is present or the token has expired.

Use this to authenticate against your own backend: send the token as a bearer header and verify it against the tenant's JWKS endpoint.

##### getJwt()[​](#getjwt "Direct link to getJwt()")

> **getJwt**(): `string` | `null`

Defined in: [types.ts:404](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L404)

###### Returns[​](#returns-3 "Direct link to Returns")

`string` | `null`

###### Example[​](#example-3 "Direct link to Example")

```ts
const jwt = allegro.member.getJwt();
if (jwt) {
  fetch('/api/user', { headers: { Authorization: `Bearer ${jwt}` } });
}

```

#### Authentication[​](#authentication-4 "Direct link to Authentication")

Stores the given JWT as the active session, persisting it to both the in-memory store and the device session cookie.

Use this when your application obtains a JWT through its own flow and needs to hand it to the SDK.

##### setJwt()[​](#setjwt "Direct link to setJwt()")

> **setJwt**(`jwt`): `void`

Defined in: [types.ts:386](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L386)

###### Parameters[​](#parameters "Direct link to Parameters")

| Parameter | Type     |
| --------- | -------- |
| `jwt`     | `string` |

###### Returns[​](#returns-4 "Direct link to Returns")

`void`

###### Example[​](#example-4 "Direct link to Example")

```ts
allegro.member.setJwt(jwtFromMyServer);

```

#### Entitlements[​](#entitlements "Direct link to Entitlements")

Returns `true` if the member's JWT contains the given product slug in the `products` claim.

##### hasProduct()[​](#hasproduct "Direct link to hasProduct()")

> **hasProduct**(`slug`): `boolean`

Defined in: [types.ts:417](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L417)

###### Parameters[​](#parameters-1 "Direct link to Parameters")

| Parameter | Type     |
| --------- | -------- |
| `slug`    | `string` |

###### Returns[​](#returns-5 "Direct link to Returns")

`boolean`

###### Example[​](#example-5 "Direct link to Example")

```ts
if (allegro.member.hasProduct('voter-game-plan')) {
  // show gated content
}

```

#### External Profiles[​](#external-profiles "Direct link to External Profiles")

Fetches the external profile data for the authenticated member from the given OAuth provider (e.g. `"google"`).

Returns the raw attributes stored for that provider. The shape varies by provider — cast the result to a more specific type when needed.

Throws if the member is not authenticated or no profile exists for the provider.

##### externalProfile()[​](#externalprofile "Direct link to externalProfile()")

> **externalProfile**(`provider`): `Promise`<`ExternalProfileAttributes`>

Defined in: [types.ts:775](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L775)

###### Parameters[​](#parameters-2 "Direct link to Parameters")

| Parameter  | Type     | Description                     |
| ---------- | -------- | ------------------------------- |
| `provider` | `string` | Provider slug, e.g. `"google"`. |

###### Returns[​](#returns-6 "Direct link to Returns")

`Promise`<`ExternalProfileAttributes`>

###### Example[​](#example-6 "Direct link to Example")

```ts
const profile = await allegro.member.externalProfile('google');
console.log(profile.email, profile.name);

```

#### Login Modal[​](#login-modal "Direct link to Login Modal")

Closes the dialog {@link MemberNamespace.showLogin} opened, which resolves its promise with `null`. Does nothing when no dialog is open.

##### hideLogin()[​](#hidelogin "Direct link to hideLogin()")

> **hideLogin**(): `void`

Defined in: [types.ts:664](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L664)

###### Returns[​](#returns-7 "Direct link to Returns")

`void`

#### Login Modal[​](#login-modal-1 "Direct link to Login Modal")

Opens a dialog holding an `<allegro-login-form>`, and resolves with the session payload once the reader signs in, or `null` if they close the dialog.

The dialog closes itself on sign-in, and every usual event fires, including `allegro:authenticated` and the `allegro:login-form:*` events. The form's success screen is skipped. Resolves at once when the reader is already signed in. While a dialog is open, another call returns the same promise and ignores its options. Rejects when the components bundle can't load.

##### showLogin()[​](#showlogin "Direct link to showLogin()")

> **showLogin**(`options?`): `Promise`<[`MemberJwtPayload`](/developer/api-reference/type-aliases/MemberJwtPayload.md) | `null`>

Defined in: [types.ts:657](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L657)

###### Parameters[​](#parameters-3 "Direct link to Parameters")

| Parameter  | Type                                                                          |
| ---------- | ----------------------------------------------------------------------------- |
| `options?` | [`ShowLoginOptions`](/developer/api-reference/interfaces/ShowLoginOptions.md) |

###### Returns[​](#returns-8 "Direct link to Returns")

`Promise`<[`MemberJwtPayload`](/developer/api-reference/type-aliases/MemberJwtPayload.md) | `null`>

###### Example[​](#example-7 "Direct link to Example")

```ts
const session = await allegro.member.showLogin({ heading: 'Sign in to keep reading' });

if (session) {
  console.log('Signed in as', session.sub);
}

```

#### Magic Link[​](#magic-link "Direct link to Magic Link")

Request a magic link email for the given address.

Sends an email containing a one-time login link. The session is also marked as "identified" so the member can be associated with future events before they click the link.

After calling this, the SDK automatically polls for authentication in the background — no manual polling is needed.

##### requestMagicLink()[​](#requestmagiclink "Direct link to requestMagicLink()")

###### Call Signature[​](#call-signature "Direct link to Call Signature")

> **requestMagicLink**(`email`, `returnUrl?`, `data?`, `captchaToken?`): `Promise`<[`MagicLinkRequestResponse`](/developer/api-reference/type-aliases/MagicLinkRequestResponse.md)>

Defined in: [types.ts:465](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L465)

###### Parameters[​](#parameters-4 "Direct link to Parameters")

| Parameter       | Type                          | Description                                                                                        |
| --------------- | ----------------------------- | -------------------------------------------------------------------------------------------------- |
| `email`         | `string`                      | The member's email address.                                                                        |
| `returnUrl?`    | `string`                      | URL the member is redirected to after clicking the link. Defaults to the current page URL.         |
| `data?`         | `Record`<`string`, `unknown`> | Arbitrary key/value data to store on the resulting session (e.g. referral source, plan selection). |
| `captchaToken?` | `string`                      | -                                                                                                  |

###### Returns[​](#returns-9 "Direct link to Returns")

`Promise`<[`MagicLinkRequestResponse`](/developer/api-reference/type-aliases/MagicLinkRequestResponse.md)>

###### Example[​](#example-8 "Direct link to Example")

```ts
await allegro.member.requestMagicLink('user@example.com');

// With a custom return URL and extra data
await allegro.member.requestMagicLink(
  'user@example.com',
  'https://example.com/dashboard',
  { plan: 'pro', source: 'homepage' },
);

```

###### Call Signature[​](#call-signature-1 "Direct link to Call Signature")

> **requestMagicLink**(`email`, `returnUrl`, `data`, `captchaToken`, `registration`): `Promise`<[`MagicLinkRequestResponse`](/developer/api-reference/type-aliases/MagicLinkRequestResponse.md) | `RegistrationRequiredResponse`>

Defined in: [types.ts:471](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L471)

###### Parameters[​](#parameters-5 "Direct link to Parameters")

| Parameter      | Type                                         |
| -------------- | -------------------------------------------- |
| `email`        | `string`                                     |
| `returnUrl`    | `string` | `undefined`                      |
| `data`         | `Record`<`string`, `unknown`> | `undefined` |
| `captchaToken` | `string` | `undefined`                      |
| `registration` | `LoginRegistration`                          |

###### Returns[​](#returns-10 "Direct link to Returns")

`Promise`<[`MagicLinkRequestResponse`](/developer/api-reference/type-aliases/MagicLinkRequestResponse.md) | `RegistrationRequiredResponse`>

#### Magic Link[​](#magic-link-1 "Direct link to Magic Link")

Validate a magic link token from the URL query string.

You typically don't call this directly — the SDK validates the `?allegro_token=` query parameter automatically on page load.

##### validateMagicLink()[​](#validatemagiclink "Direct link to validateMagicLink()")

> **validateMagicLink**(`token`): `Promise`<[`MagicLinkValidateResponse`](/developer/api-reference/type-aliases/MagicLinkValidateResponse.md)>

Defined in: [types.ts:495](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L495)

###### Parameters[​](#parameters-6 "Direct link to Parameters")

| Parameter | Type     | Description                                 |
| --------- | -------- | ------------------------------------------- |
| `token`   | `string` | The one-time token from the magic link URL. |

###### Returns[​](#returns-11 "Direct link to Returns")

`Promise`<[`MagicLinkValidateResponse`](/developer/api-reference/type-aliases/MagicLinkValidateResponse.md)>

###### Example[​](#example-9 "Direct link to Example")

```ts
const token = new URLSearchParams(location.search).get('allegro_token') ?? '';
const result = await allegro.member.validateMagicLink(token);
console.log(result.return_url);

```

#### OTP[​](#otp "Direct link to OTP")

Request a combined magic link and one-time code in a single email.

Emails both a magic sign-in link and a six-digit code. Unlike {@link requestLoginCode}, this DOES start background auth polling so that clicking the link in any browser authenticates this session while the code input is shown.

##### requestMagicLinkOtp()[​](#requestmagiclinkotp "Direct link to requestMagicLinkOtp()")

###### Call Signature[​](#call-signature-2 "Direct link to Call Signature")

> **requestMagicLinkOtp**(`email`, `returnUrl?`, `data?`, `captchaToken?`): `Promise`<`MagicLinkOtpRequestResponse`>

Defined in: [types.ts:550](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L550)

###### Parameters[​](#parameters-7 "Direct link to Parameters")

| Parameter       | Type                          | Description                                                                                                                                 |
| --------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`         | `string`                      | The member's email address.                                                                                                                 |
| `returnUrl?`    | `string`                      | URL the member is redirected to after authenticating. Defaults to the current page URL.                                                     |
| `data?`         | `Record`<`string`, `unknown`> | Arbitrary key/value data to store on the resulting session.                                                                                 |
| `captchaToken?` | `string`                      | Captcha token, when the tenant has a provider configured. Omitting it against a captcha-protected tenant is rejected with `CAPTCHA_FAILED`. |

###### Returns[​](#returns-12 "Direct link to Returns")

`Promise`<`MagicLinkOtpRequestResponse`>

###### Call Signature[​](#call-signature-3 "Direct link to Call Signature")

> **requestMagicLinkOtp**(`email`, `returnUrl`, `data`, `captchaToken`, `registration`): `Promise`<`RegistrationRequiredResponse` | `MagicLinkOtpRequestResponse`>

Defined in: [types.ts:556](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L556)

###### Parameters[​](#parameters-8 "Direct link to Parameters")

| Parameter      | Type                                         |
| -------------- | -------------------------------------------- |
| `email`        | `string`                                     |
| `returnUrl`    | `string` | `undefined`                      |
| `data`         | `Record`<`string`, `unknown`> | `undefined` |
| `captchaToken` | `string` | `undefined`                      |
| `registration` | `LoginRegistration`                          |

###### Returns[​](#returns-13 "Direct link to Returns")

`Promise`<`RegistrationRequiredResponse` | `MagicLinkOtpRequestResponse`>

#### OTP[​](#otp-1 "Direct link to OTP")

Request a one-time passcode email for the given address.

Emails a six-digit code. Unlike {@link requestMagicLink}, this does NOT start background auth polling — the user enters the code on this device and {@link validateLoginCode} completes authentication synchronously.

##### requestLoginCode()[​](#requestlogincode "Direct link to requestLoginCode()")

###### Call Signature[​](#call-signature-4 "Direct link to Call Signature")

> **requestLoginCode**(`email`, `returnUrl?`, `data?`, `captchaToken?`): `Promise`<`OtpRequestResponse`>

Defined in: [types.ts:518](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L518)

###### Parameters[​](#parameters-9 "Direct link to Parameters")

| Parameter       | Type                          | Description                                                                                                                                 |
| --------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`         | `string`                      | The member's email address.                                                                                                                 |
| `returnUrl?`    | `string`                      | URL the member is redirected to after authenticating. Defaults to the current page URL.                                                     |
| `data?`         | `Record`<`string`, `unknown`> | Arbitrary key/value data to store on the resulting session.                                                                                 |
| `captchaToken?` | `string`                      | Captcha token, when the tenant has a provider configured. Omitting it against a captcha-protected tenant is rejected with `CAPTCHA_FAILED`. |

###### Returns[​](#returns-14 "Direct link to Returns")

`Promise`<`OtpRequestResponse`>

###### Call Signature[​](#call-signature-5 "Direct link to Call Signature")

> **requestLoginCode**(`email`, `returnUrl`, `data`, `captchaToken`, `registration`): `Promise`<`RegistrationRequiredResponse` | `OtpRequestResponse`>

Defined in: [types.ts:524](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L524)

###### Parameters[​](#parameters-10 "Direct link to Parameters")

| Parameter      | Type                                         |
| -------------- | -------------------------------------------- |
| `email`        | `string`                                     |
| `returnUrl`    | `string` | `undefined`                      |
| `data`         | `Record`<`string`, `unknown`> | `undefined` |
| `captchaToken` | `string` | `undefined`                      |
| `registration` | `LoginRegistration`                          |

###### Returns[​](#returns-15 "Direct link to Returns")

`Promise`<`RegistrationRequiredResponse` | `OtpRequestResponse`>

#### OTP[​](#otp-2 "Direct link to OTP")

Validate a one-time passcode entered by the member. On success the session JWT is stored and an `allegro:authenticated` event is dispatched. On failure an {@link AllegroApiError} is thrown with `errorCode` one of `INVALID_OTP`, `OTP_LOCKED`.

##### validateLoginCode()[​](#validatelogincode "Direct link to validateLoginCode()")

> **validateLoginCode**(`code`): `Promise`<`OtpValidateResponse`>

Defined in: [types.ts:573](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L573)

###### Parameters[​](#parameters-11 "Direct link to Parameters")

| Parameter | Type     | Description                               |
| --------- | -------- | ----------------------------------------- |
| `code`    | `string` | The six-digit code entered by the member. |

###### Returns[​](#returns-16 "Direct link to Returns")

`Promise`<`OtpValidateResponse`>

#### Profile[​](#profile "Direct link to Profile")

Updates the authenticated member's own record. Only the fields passed are written; the rest are left as they are. Returns the stored profile, which can differ from what was sent — the server trims surrounding whitespace. The session JWT is refreshed automatically.

##### updateProfile()[​](#updateprofile "Direct link to updateProfile()")

> **updateProfile**(`profile`): `Promise`<[`MemberProfile`](/developer/api-reference/interfaces/MemberProfile.md)>

Defined in: [types.ts:795](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L795)

###### Parameters[​](#parameters-12 "Direct link to Parameters")

| Parameter | Type                                                                               | Description          |
| --------- | ---------------------------------------------------------------------------------- | -------------------- |
| `profile` | `Partial`<[`MemberProfile`](/developer/api-reference/interfaces/MemberProfile.md)> | The fields to write. |

###### Returns[​](#returns-17 "Direct link to Returns")

`Promise`<[`MemberProfile`](/developer/api-reference/interfaces/MemberProfile.md)>

###### Example[​](#example-10 "Direct link to Example")

```ts
await allegro.member.updateProfile({ name: 'Alex Jones' });

```

#### Session[​](#session "Direct link to Session")

Associates an email address with the current anonymous session without requiring a full login.

Use this to identify a member before they authenticate — for example, when they enter their email on a registration form. The session will appear as "identified" but not "authenticated".

Pass `attributes` to store user attribute values against the member, keyed by slug. A value is only stored when the member has none for that attribute yet, so existing values are never overwritten. The whole call is rejected if a slug is undefined or not editable, or a value fails its type or validation rules.

##### identifyByEmail()[​](#identifybyemail "Direct link to identifyByEmail()")

> **identifyByEmail**(`email`, `data?`, `attributes?`): `Promise`<[`IdentifySessionResponse`](/developer/api-reference/type-aliases/IdentifySessionResponse.md)>

Defined in: [types.ts:698](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L698)

###### Parameters[​](#parameters-13 "Direct link to Parameters")

| Parameter     | Type                          | Description                                                            |
| ------------- | ----------------------------- | ---------------------------------------------------------------------- |
| `email`       | `string`                      | The email address to associate with this session.                      |
| `data?`       | `Record`<`string`, `unknown`> | Extra request data passed to integrations, such as newsletter signups. |
| `attributes?` | `Record`<`string`, `unknown`> | User attribute values to store, keyed by attribute slug.               |

###### Returns[​](#returns-18 "Direct link to Returns")

`Promise`<[`IdentifySessionResponse`](/developer/api-reference/type-aliases/IdentifySessionResponse.md)>

###### Example[​](#example-11 "Direct link to Example")

```ts
await allegro.member.identifyByEmail('user@example.com');

await allegro.member.identifyByEmail('user@example.com', undefined, {
    'wants-newsletter': true,
});

```

#### Session[​](#session-1 "Direct link to Session")

Fetches live session data from the API.

Includes authentication status, timestamps, and the associated audience member record if the session is identified.

##### session()[​](#session-2 "Direct link to session()")

> **session**(): `Promise`<[`SessionResponse`](/developer/api-reference/type-aliases/SessionResponse.md)>

Defined in: [types.ts:717](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L717)

###### Returns[​](#returns-19 "Direct link to Returns")

`Promise`<[`SessionResponse`](/developer/api-reference/type-aliases/SessionResponse.md)>

###### Example[​](#example-12 "Direct link to Example")

```ts
const { data } = await allegro.member.session();
console.log(data.is_authenticated, data.audience_member?.email);

```

#### Session[​](#session-3 "Direct link to Session")

Fetches the member's active entitlements.

##### entitlements()[​](#entitlements-1 "Direct link to entitlements()")

> **entitlements**(): `Promise`<[`MemberEntitlement`](/developer/api-reference/interfaces/MemberEntitlement.md)\[]>

Defined in: [types.ts:746](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L746)

###### Returns[​](#returns-20 "Direct link to Returns")

`Promise`<[`MemberEntitlement`](/developer/api-reference/interfaces/MemberEntitlement.md)\[]>

###### Example[​](#example-13 "Direct link to Example")

```ts
const entitlements = await allegro.member.entitlements();
const hasPro = entitlements.some((e) => e.name === 'pro');

```

#### Session[​](#session-4 "Direct link to Session")

Reads session data from the JWT stored in the browser cookie — no network request required.

Returns `null` if no valid JWT is present or the token has expired.

##### sessionFromJwt()[​](#sessionfromjwt "Direct link to sessionFromJwt()")

> **sessionFromJwt**(): [`MemberJwtPayload`](/developer/api-reference/type-aliases/MemberJwtPayload.md) | `null`

Defined in: [types.ts:734](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L734)

###### Returns[​](#returns-21 "Direct link to Returns")

[`MemberJwtPayload`](/developer/api-reference/type-aliases/MemberJwtPayload.md) | `null`

###### Example[​](#example-14 "Direct link to Example")

```ts
const payload = allegro.member.sessionFromJwt();
if (payload) {
  console.log('Member ID:', payload.sub);
}

```

#### Session[​](#session-5 "Direct link to Session")

Silently refreshes the JWT if it was issued more than 24 hours ago.

Called automatically on SDK initialisation. Safe to call manually if needed — it is a no-op when the token is still fresh.

##### refreshJwtIfNeeded()[​](#refreshjwtifneeded "Direct link to refreshJwtIfNeeded()")

> **refreshJwtIfNeeded**(): `Promise`<`void`>

Defined in: [types.ts:755](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L755)

###### Returns[​](#returns-22 "Direct link to Returns")

`Promise`<`void`>

#### Social Login[​](#social-login "Direct link to Social Login")

Authenticate via a third-party OAuth provider by navigating the current window, instead of opening a popup. Use it where popups don't work: mobile browsers, in-app browsers, or a page that is itself a popup.

The provider redirects back to `returnUrl` once authentication completes; this method never resolves because the current page navigates away. `returnUrl` must be on one of the tenant's or property's allowed origins. On return the SDK signs the member in automatically and dispatches `allegro:social:authenticated`, or `allegro:social:failed`.

##### loginWithProviderRedirect()[​](#loginwithproviderredirect "Direct link to loginWithProviderRedirect()")

> **loginWithProviderRedirect**(`provider`, `returnUrl`, `data?`): `void`

Defined in: [types.ts:619](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L619)

###### Parameters[​](#parameters-14 "Direct link to Parameters")

| Parameter   | Type                          | Description                                                 |
| ----------- | ----------------------------- | ----------------------------------------------------------- |
| `provider`  | `string`                      | Provider slug, e.g. `"google"` or `"apple"`.                |
| `returnUrl` | `string`                      | The URL to redirect back to once authentication completes.  |
| `data?`     | `Record`<`string`, `unknown`> | Arbitrary key/value data to store on the resulting session. |

###### Returns[​](#returns-23 "Direct link to Returns")

`void`

#### Social Login[​](#social-login-1 "Direct link to Social Login")

Authenticate via a third-party OAuth provider using a popup window.

The list of available providers is configured per tenant (`allegro.tenant.loginProviders`). The calling page's origin must be one of the tenant's or property's allowed origins, or the popup cannot hand the result back.

##### loginWithProvider()[​](#loginwithprovider "Direct link to loginWithProvider()")

> **loginWithProvider**(`provider`, `data?`): `Promise`<[`SocialLoginResponse`](/developer/api-reference/type-aliases/SocialLoginResponse.md)>

Defined in: [types.ts:602](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L602)

###### Parameters[​](#parameters-15 "Direct link to Parameters")

| Parameter  | Type                          | Description                                                 |
| ---------- | ----------------------------- | ----------------------------------------------------------- |
| `provider` | `string`                      | Provider slug, e.g. `"google"` or `"apple"`.                |
| `data?`    | `Record`<`string`, `unknown`> | Arbitrary key/value data to store on the resulting session. |

###### Returns[​](#returns-24 "Direct link to Returns")

`Promise`<[`SocialLoginResponse`](/developer/api-reference/type-aliases/SocialLoginResponse.md)>

###### Example[​](#example-15 "Direct link to Example")

```ts
try {
  const result = await allegro.member.loginWithProvider('google');
  console.log('Logged in, token:', result.token);
} catch (err) {
  // err.name is 'PopupBlockedError' when the browser refused to open the popup;
  // fall back to loginWithProviderRedirect() in that case.
  console.error('Login failed or popup was blocked:', err);
}

```

#### Social Login[​](#social-login-2 "Direct link to Social Login")

Exchange the one-time code a redirect-based social login appends to the returning page for the member's JWT, and store it.

You typically don't call this directly — the SDK exchanges the `?allegro_social_code=` query parameter automatically on page load.

##### exchangeSocialLoginCode()[​](#exchangesociallogincode "Direct link to exchangeSocialLoginCode()")

> **exchangeSocialLoginCode**(`code`): `Promise`<`SocialLoginExchangeResponse`>

Defined in: [types.ts:631](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L631)

###### Parameters[​](#parameters-16 "Direct link to Parameters")

| Parameter | Type     | Description                                                       |
| --------- | -------- | ----------------------------------------------------------------- |
| `code`    | `string` | The one-time code from the `allegro_social_code` query parameter. |

###### Returns[​](#returns-25 "Direct link to Returns")

`Promise`<`SocialLoginExchangeResponse`>

#### User Attributes[​](#user-attributes "Direct link to User Attributes")

Clears the authenticated member's value for a user attribute. The session JWT is refreshed automatically.

##### deleteUserAttribute()[​](#deleteuserattribute "Direct link to deleteUserAttribute()")

> **deleteUserAttribute**(`slug`): `Promise`<`void`>

Defined in: [types.ts:876](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L876)

###### Parameters[​](#parameters-17 "Direct link to Parameters")

| Parameter | Type     | Description         |
| --------- | -------- | ------------------- |
| `slug`    | `string` | The attribute slug. |

###### Returns[​](#returns-26 "Direct link to Returns")

`Promise`<`void`>

#### User Attributes[​](#user-attributes-1 "Direct link to User Attributes")

Lists the user attributes defined by the organization together with the authenticated member's current value for each (`null` when unset).

##### getUserAttributes()[​](#getuserattributes "Direct link to getUserAttributes()")

> **getUserAttributes**(): `Promise`<[`UserAttributeValue`](/developer/api-reference/type-aliases/UserAttributeValue.md)\[]>

Defined in: [types.ts:807](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L807)

###### Returns[​](#returns-27 "Direct link to Returns")

`Promise`<[`UserAttributeValue`](/developer/api-reference/type-aliases/UserAttributeValue.md)\[]>

###### Example[​](#example-16 "Direct link to Example")

```ts
const attributes = await allegro.member.getUserAttributes();

```

#### User Attributes[​](#user-attributes-2 "Direct link to User Attributes")

Returns the authenticated member's attribute values keyed by slug, read synchronously from a localStorage cache — no network request. Returns `null` when the member is not authenticated or nothing is cached yet.

The SDK fills the cache on login and on boot when it is missing or more than five minutes old, and clears and refetches it after every attribute write. Each fill or clear fires `allegro:user-attributes:updated` with `{ values }` in `detail` (`null` when cleared).

##### userAttributesFromCache()[​](#userattributesfromcache "Direct link to userAttributesFromCache()")

> **userAttributesFromCache**(): `Record`<`string`, `unknown`> | `null`

Defined in: [types.ts:826](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L826)

###### Returns[​](#returns-28 "Direct link to Returns")

`Record`<`string`, `unknown`> | `null`

###### Example[​](#example-17 "Direct link to Example")

```ts
const attributes = allegro.member.userAttributesFromCache();
const firstName = attributes?.name_first;

```

#### User Attributes[​](#user-attributes-3 "Direct link to User Attributes")

Sets the authenticated member's value for a user attribute. The server validates the value against the attribute's declared type and returns the stored (cast) value. The session JWT is refreshed automatically.

##### setUserAttribute()[​](#setuserattribute "Direct link to setUserAttribute()")

> **setUserAttribute**(`slug`, `value`): `Promise`<`unknown`>

Defined in: [types.ts:842](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L842)

###### Parameters[​](#parameters-18 "Direct link to Parameters")

| Parameter | Type      | Description         |
| --------- | --------- | ------------------- |
| `slug`    | `string`  | The attribute slug. |
| `value`   | `unknown` | The value to store. |

###### Returns[​](#returns-29 "Direct link to Returns")

`Promise`<`unknown`>

###### Example[​](#example-18 "Direct link to Example")

```ts
await allegro.member.setUserAttribute('wants-newsletter', true);

```

#### User Attributes[​](#user-attributes-4 "Direct link to User Attributes")

Sets the authenticated member's values for several user attributes at once, and resolves with the stored (cast) values keyed by slug. A `null` value clears the member's value for that attribute. The session JWT is refreshed automatically.

The server validates every value before writing any of them, so the whole call is rejected without saving anything if one slug is undefined, one attribute is not editable, or one value fails its type or validation rules.

##### setUserAttributes()[​](#setuserattributes "Direct link to setUserAttributes()")

> **setUserAttributes**(`values`): `Promise`<`Record`<`string`, `unknown`>>

Defined in: [types.ts:867](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L867)

###### Parameters[​](#parameters-19 "Direct link to Parameters")

| Parameter | Type                          | Description                                   |
| --------- | ----------------------------- | --------------------------------------------- |
| `values`  | `Record`<`string`, `unknown`> | The values to store, keyed by attribute slug. |

###### Returns[​](#returns-30 "Direct link to Returns")

`Promise`<`Record`<`string`, `unknown`>>

###### Example[​](#example-19 "Direct link to Example")

```ts
await allegro.member.setUserAttributes({
    'wants-newsletter': true,
    'display-name': 'Jane',
    color: null, // clears the stored value
});

```


---

### Interface: MemberProfile

Defined in: [types.ts:321](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L321)

The writable fields of a member's own audience-member record.

The member's email is absent deliberately: changing it goes through its own verification flow, not a profile update.

#### Properties[​](#properties "Direct link to Properties")

| Property   | Type     | Defined in                                                                                                                                                         |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| []()`name` | `string` | [types.ts:322](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L322) |


---

### Interface: MetersNamespace

Defined in: [interaction/meters.ts:22](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/meters.ts#L22)

Read access to the meter usage returned by the most recent interaction evaluation.

Access this namespace via `allegro.meters`.

#### Methods[​](#methods "Direct link to Methods")

##### all()[​](#all "Direct link to all()")

> **all**(): [`MeterUsageMap`](/developer/api-reference/type-aliases/MeterUsageMap.md)

Defined in: [interaction/meters.ts:24](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/meters.ts#L24)

Every meter's usage from the latest evaluation, keyed by meter slug.

###### Returns[​](#returns "Direct link to Returns")

[`MeterUsageMap`](/developer/api-reference/type-aliases/MeterUsageMap.md)

***

##### get()[​](#get "Direct link to get()")

> **get**(`slug`): [`MeterUsage`](/developer/api-reference/interfaces/MeterUsage.md) | `null`

Defined in: [interaction/meters.ts:27](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/meters.ts#L27)

One meter's usage, or `null` when the visitor has none for it.

###### Parameters[​](#parameters "Direct link to Parameters")

| Parameter | Type     |
| --------- | -------- |
| `slug`    | `string` |

###### Returns[​](#returns-1 "Direct link to Returns")

[`MeterUsage`](/developer/api-reference/interfaces/MeterUsage.md) | `null`


---

### Interface: MeterUsage

Defined in: [interaction/meters.ts:2](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/meters.ts#L2)

One meter's usage for the current visitor, as returned by the evaluate endpoint.

#### Properties[​](#properties "Direct link to Properties")

| Property        | Type                                            | Description                                                                                                                                | Defined in                                                                                                                                                                                 |
| --------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| []()`counted`   | `boolean`                                       | Whether this page view raised `used`: false on a page that doesn't qualify, a repeat of an already-counted page, or for an exempt visitor. | [interaction/meters.ts:9](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/meters.ts#L9)   |
| []()`limit`     | `number`                                        | -                                                                                                                                          | [interaction/meters.ts:6](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/meters.ts#L6)   |
| []()`name`      | `string`                                        | -                                                                                                                                          | [interaction/meters.ts:3](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/meters.ts#L3)   |
| []()`remaining` | `number` | `null`                              | -                                                                                                                                          | [interaction/meters.ts:7](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/meters.ts#L7)   |
| []()`resets_at` | `string` | `null`                              | -                                                                                                                                          | [interaction/meters.ts:10](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/meters.ts#L10) |
| []()`status`    | `"under_limit"` | `"over_limit"` | `"exempt"` | -                                                                                                                                          | [interaction/meters.ts:4](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/meters.ts#L4)   |
| []()`used`      | `number` | `null`                              | -                                                                                                                                          | [interaction/meters.ts:5](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/meters.ts#L5)   |


---

### Interface: PageDataSource

Defined in: [page-data-source.ts:1](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/page-data-source.ts#L1)

#### Properties[​](#properties "Direct link to Properties")

| Property     | Type                                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                            | Defined in                                                                                                                                                                           |
| ------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| []()`key`    | `string`                                                                 | The key used to look up the value. - meta: the `name` attribute of the <!-- -->tag - dataLayer: the property name inside the <!-- -->JSON - selector: a CSS selector whose textContent is read - attribute: a "selector@attribute" string (e.g. "body@data-publisher") - jsonLd: a dot-path like `publisher.name` to traverse nested objects, with optional pipe-delimited fallbacks like \`headline | name`(tries`headline`first, falls back to`name\`)                                                                                                                                    |
| []()`source` | `"meta"` | `"dataLayer"` | `"selector"` | `"attribute"` | `"jsonLd"` | How to read the value from the page.                                                                                                                                                                                                                                                                                                                                                                   | [page-data-source.ts:3](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/page-data-source.ts#L3) |


---

### Interface: PublicPlan

Defined in: [interaction/field-values.ts:22](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/field-values.ts#L22)

A plan as delivered to visitors, with only its public custom field values.

#### Properties[​](#properties "Direct link to Properties")

| Property              | Type                                                              | Defined in                                                                                                                                                                                             |
| --------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| []()`currency`        | `string`                                                          | [interaction/field-values.ts:27](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/field-values.ts#L27) |
| []()`description`     | `string` | `null`                                                | [interaction/field-values.ts:25](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/field-values.ts#L25) |
| []()`duration_label`  | `string`                                                          | [interaction/field-values.ts:29](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/field-values.ts#L29) |
| []()`fields`          | `Record`<`string`, `string` | `number` | `boolean` | `null`>   | [interaction/field-values.ts:32](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/field-values.ts#L32) |
| []()`formatted_price` | `string`                                                          | [interaction/field-values.ts:28](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/field-values.ts#L28) |
| []()`id`              | `string`                                                          | [interaction/field-values.ts:23](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/field-values.ts#L23) |
| []()`is_unlimited`    | `boolean`                                                         | [interaction/field-values.ts:30](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/field-values.ts#L30) |
| []()`name`            | `string`                                                          | [interaction/field-values.ts:24](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/field-values.ts#L24) |
| []()`price`           | `number`                                                          | [interaction/field-values.ts:26](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/field-values.ts#L26) |
| []()`product`         | { `id`: `string`; `name`: `string`; `slug`: `string`; } | `null` | [interaction/field-values.ts:31](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/field-values.ts#L31) |


---

### Interface: PurchaseNamespace

Defined in: [types.ts:1481](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1481)

Methods for initiating and completing purchases.

Access this namespace via `allegro.purchase`.

#### Example[​](#example "Direct link to Example")

```ts
window.allegro.push((allegro) => {
  allegro.purchase.initiate('term-uuid-here');
});

```

#### Methods[​](#methods "Direct link to Methods")

##### exchangeToken()[​](#exchangetoken "Direct link to exchangeToken()")

> **exchangeToken**(`token`): `Promise`<[`PurchaseTokenExchangeResponse`](/developer/api-reference/interfaces/PurchaseTokenExchangeResponse.md)>

Defined in: [types.ts:1496](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1496)

Exchange an `allegro_purchase_token` query param for a JWT + entitlement.

Called automatically on page load when the param is detected.

###### Parameters[​](#parameters "Direct link to Parameters")

| Parameter | Type     |
| --------- | -------- |
| `token`   | `string` |

###### Returns[​](#returns "Direct link to Returns")

`Promise`<[`PurchaseTokenExchangeResponse`](/developer/api-reference/interfaces/PurchaseTokenExchangeResponse.md)>

***

##### initiate()[​](#initiate "Direct link to initiate()")

> **initiate**(`termId`, `returnUrl?`): `Promise`<`void`>

Defined in: [types.ts:1489](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1489)

Initiate a purchase for a term.

Calls the backend to create a hosted checkout session, then redirects the browser to the provider's checkout page. If `returnUrl` is omitted, the current page URL is used.

###### Parameters[​](#parameters-1 "Direct link to Parameters")

| Parameter    | Type     |
| ------------ | -------- |
| `termId`     | `string` |
| `returnUrl?` | `string` |

###### Returns[​](#returns-1 "Direct link to Returns")

`Promise`<`void`>

#### Properties[​](#properties "Direct link to Properties")

| Property         | Type                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Defined in                                                                                                                                                           |
| ---------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| []()`validation` | `"failed"` | `"completed"` | `null` | The result of purchase token validation on this page load. - `'completed'` — purchase was verified and entitlement created - `'failed'` — payment failed or was cancelled - `null` — no purchase token present on this page load **Async timing note:** This value may still be `null` when `allegro:ready` fires, because token exchange is asynchronous. Do not read `validation` at ready time. Instead, listen for the `allegro:purchase:completed` or `allegro:purchase:failed` events to react to the outcome. | [types.ts:1510](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1510) |


---

### Interface: PurchaseTokenExchangeResponse

Defined in: [types.ts:1514](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1514)

Response returned after a successful purchase token exchange.

#### Properties[​](#properties "Direct link to Properties")

| Property                    | Type               | Description                                                                                   | Defined in                                                                                                                                                           |
| --------------------------- | ------------------ | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| []()`entitlement`           | `object`           | The newly-created entitlement.                                                                | [types.ts:1518](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1518) |
| `entitlement.ended_at`      | `string` | `null` | -                                                                                             | [types.ts:1526](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1526) |
| `entitlement.id`            | `string`           | -                                                                                             | [types.ts:1519](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1519) |
| `entitlement.is_active`     | `boolean`          | -                                                                                             | [types.ts:1527](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1527) |
| `entitlement.resource`      | `object`           | -                                                                                             | [types.ts:1520](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1520) |
| `entitlement.resource.id`   | `string`           | -                                                                                             | [types.ts:1521](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1521) |
| `entitlement.resource.name` | `string`           | -                                                                                             | [types.ts:1523](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1523) |
| `entitlement.resource.slug` | `string`           | -                                                                                             | [types.ts:1522](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1522) |
| `entitlement.started_at`    | `string` | `null` | -                                                                                             | [types.ts:1525](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1525) |
| []()`jwt`                   | `string`           | JWT for the purchase's device session. Unauthenticated when the buyer checked out as a guest. | [types.ts:1516](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1516) |


---

### Interface: RecommendationItem

Defined in: [types.ts:1234](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1234)

One recommended article.

Field names are camelCase here and snake\_case on the wire; the recommendations module is the only place that converts.

#### Properties[​](#properties "Direct link to Properties")

| Property          | Type               | Description                                                                                        | Defined in                                                                                                                                                           |
| ----------------- | ------------------ | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| []()`imageUrl`    | `string` | `null` | -                                                                                                  | [types.ts:1240](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1240) |
| []()`pagePath`    | `string`           | Root-relative path of the article, e.g. `"/news/food/story-slug"`.                                 | [types.ts:1236](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1236) |
| []()`publishedAt` | `string` | `null` | ISO 8601 publish timestamp, or `null` for undated articles.                                        | [types.ts:1242](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1242) |
| []()`score`       | `number`           | Ranking score. Comparable within a strategy but not across them, so never sort a mixed list by it. | [types.ts:1247](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1247) |
| []()`section`     | `string`           | Content section, or `""` when the catalog has none for this article.                               | [types.ts:1239](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1239) |
| []()`strategy`    | `string`           | Which rung of the serving ladder produced this item, e.g. `"taste"`.                               | [types.ts:1249](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1249) |
| []()`title`       | `string`           | -                                                                                                  | [types.ts:1237](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1237) |


---

### Interface: RecommendationSet

Defined in: [types.ts:1253](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1253)

One page's worth of recommendations, plus the id that keys click reports.

#### Properties[​](#properties "Direct link to Properties")

| Property        | Type                                                                                 | Description                                                                                                                                                             | Defined in                                                                                                                                                           |
| --------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| []()`items`     | [`RecommendationItem`](/developer/api-reference/interfaces/RecommendationItem.md)\[] | -                                                                                                                                                                       | [types.ts:1262](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1262) |
| []()`requestId` | `string` | `null`                                                                   | Keys the impressions logged for this call; `trackClick()` echoes it. `null` when no engine is configured or the engine was unreachable, in which case `items` is empty. | [types.ts:1259](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1259) |
| []()`tookMs`    | `number`                                                                             | Server-side engine time in milliseconds.                                                                                                                                | [types.ts:1261](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1261) |


---

### Interface: RecommendationsGetOptions

Defined in: [types.ts:1266](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1266)

Optional overrides for a recommendations request.

#### Properties[​](#properties "Direct link to Properties")

| Property          | Type     | Description                                                               | Defined in                                                                                                                                                           |
| ----------------- | -------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| []()`device?`     | `string` | Reader's device id. Defaults to the SDK's own device cookie.              | [types.ts:1274](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1274) |
| []()`limit?`      | `number` | How many articles to ask for. Defaults to 6 upstream; 24 is the maximum.  | [types.ts:1268](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1268) |
| []()`maxAgeDays?` | `number` | Publish-recency cap in days. `0`, the default, means no cap.              | [types.ts:1272](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1272) |
| []()`path?`       | `string` | Article to anchor on. Defaults to the current `window.location.pathname`. | [types.ts:1270](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1270) |


---

### Interface: RecommendationsNamespace

Defined in: [types.ts:1283](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1283)

Recommendation fetching and click reporting methods, available as `allegro.recommendations`.

#### Methods[​](#methods "Direct link to Methods")

##### get()[​](#get "Direct link to get()")

> **get**(`options?`): `Promise`<[`RecommendationSet`](/developer/api-reference/interfaces/RecommendationSet.md)>

Defined in: [types.ts:1292](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1292)

Fetch ranked recommendations for this reader.

###### Parameters[​](#parameters "Direct link to Parameters")

| Parameter  | Type                                                                                            |
| ---------- | ----------------------------------------------------------------------------------------------- |
| `options?` | [`RecommendationsGetOptions`](/developer/api-reference/interfaces/RecommendationsGetOptions.md) |

###### Returns[​](#returns "Direct link to Returns")

`Promise`<[`RecommendationSet`](/developer/api-reference/interfaces/RecommendationSet.md)>

###### Example[​](#example "Direct link to Example")

```ts
const { items } = await allegro.recommendations.get({ limit: 6 });

```

***

##### trackClick()[​](#trackclick "Direct link to trackClick()")

> **trackClick**(`item`, `options?`): `Promise`<`void`>

Defined in: [types.ts:1312](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1312)

Report that the reader clicked one of the items `get()` returned.

Pass the item object itself — the SDK remembers which request served it, so nothing else is needed. `options.position` is the only field the caller can override — useful when the item was re-rendered or reordered and the caller knows its displayed position better than the SDK's original index; `requestId`, `device`, `sourcePath`, and `strategy` always come from the recorded origin, not from `options`.

###### Parameters[​](#parameters-1 "Direct link to Parameters")

| Parameter           | Type                                                                              |
| ------------------- | --------------------------------------------------------------------------------- |
| `item`              | [`RecommendationItem`](/developer/api-reference/interfaces/RecommendationItem.md) |
| `options?`          | { `position?`: `number`; }                                                        |
| `options.position?` | `number`                                                                          |

###### Returns[​](#returns-1 "Direct link to Returns")

`Promise`<`void`>

###### Throws[​](#throws "Direct link to Throws")

AllegroApiError when the item cannot be traced to a request, or when its path appears in two different result sets on this page.

###### Example[​](#example-1 "Direct link to Example")

```ts
link.addEventListener('click', () => allegro.recommendations.trackClick(item));

```


---

### Interface: ShowLoginOptions

Defined in: [types.ts:1361](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1361)

Options for [MemberNamespace.showLogin](/developer/api-reference/interfaces/MemberNamespace.md#showlogin). The login form options match the `<allegro-login-form>` attributes of the same name.

#### Properties[​](#properties "Direct link to Properties")

| Property                | Type                                                                      | Description                                                                                                                                                                                     | Defined in                                                                                                                                                           |
| ----------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| []()`buttonText?`       | `string`                                                                  | Label for the submit button.                                                                                                                                                                    | [types.ts:1378](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1378) |
| []()`closeOnBackdrop?`  | `boolean`                                                                 | Close the dialog when the reader clicks the backdrop. Defaults to `false`.                                                                                                                      | [types.ts:1374](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1374) |
| []()`description?`      | `string`                                                                  | Short text shown under the heading, styled with `::part(description)` or `--loginForm--description--*`.                                                                                         | [types.ts:1368](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1368) |
| []()`email?`            | `string`                                                                  | Email address to prefill. The reader can still change it.                                                                                                                                       | [types.ts:1390](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1390) |
| []()`formLabelText?`    | `string`                                                                  | Label text for the email field.                                                                                                                                                                 | [types.ts:1382](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1382) |
| []()`heading?`          | `string`                                                                  | Heading shown above the email field, styled with `allegro-login-form::part(heading)` or the `--loginForm--heading--*` variables. Without one, the dialog is named "Sign in" for screen readers. | [types.ts:1366](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1366) |
| []()`hideThirdParty?`   | `boolean`                                                                 | Hide the social login buttons.                                                                                                                                                                  | [types.ts:1386](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1386) |
| []()`loginMethod?`      | `"magic-link"` | `"otp"` | `"magic-link-otp"`                           | How readers sign in. Defaults to `magic-link`.                                                                                                                                                  | [types.ts:1376](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1376) |
| []()`placeholderText?`  | `string`                                                                  | Placeholder shown inside the email field.                                                                                                                                                       | [types.ts:1384](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1384) |
| []()`position?`         | `"center"` | `"top"`                                                     | Where the dialog sits: `center` (the default), or `top` with `--modal--top-offset` of space above it.                                                                                           | [types.ts:1372](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1372) |
| []()`registrationForm?` | `string`                                                                  | Slug of a form whose fields a new reader fills in before their account is created. No email is sent until they answer.                                                                          | [types.ts:1392](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1392) |
| []()`registrationText?` | `string`                                                                  | Text shown above the registration fields and announced to screen readers when they appear. Pass `''` to hide it; a default message is still announced.                                          | [types.ts:1394](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1394) |
| []()`showFormLabel?`    | `boolean`                                                                 | Show the email field's label. When off, the label is still read by screen readers.                                                                                                              | [types.ts:1380](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1380) |
| []()`showLastUsed?`     | `boolean`                                                                 | Show a "Last used" badge on the login method the reader last used on this browser.                                                                                                              | [types.ts:1388](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1388) |
| []()`size?`             | `"small"` | `"medium"` | `"large"` | `"full"`                          | The dialog's maximum width. Defaults to `small`.                                                                                                                                                | [types.ts:1370](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1370) |
| []()`trackingData?`     | [`TrackEventData`](/developer/api-reference/interfaces/TrackEventData.md) | Custom data merged into every event the dialog and form track.                                                                                                                                  | [types.ts:1396](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1396) |


---

### Interface: TenantConfig

Defined in: [types.ts:15](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L15)

#### Indexable[​](#indexable "Direct link to Indexable")

> \[`packageKey`: `string`]: `unknown`

Namespaced configuration contributed by an installed package, via the server-side `PackageServiceProvider::addClientConfig()` hook (e.g. `worldpay`). A key is absent whenever that package is not installed or not fully configured for the tenant, so always treat a missing key as "this integration is unavailable" rather than assuming a default. Never contains credentials — this object is serialized into a script-tag attribute on a public page.

#### Properties[​](#properties "Direct link to Properties")

| Property             | Type                  | Description                                                                                                                                                                                                                                                                                                          | Defined in                                                                                                                                                       |
| -------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| []()`assets?`        | `TenantAssets`        | URLs of the bundles the SDK loads on demand. Absent when the tenant has no compiled builds.                                                                                                                                                                                                                          | [types.ts:31](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L31) |
| []()`canonicalUrl?`  | `string`              | Canonical URL for the tenant (e.g. '<https://example.org>'). When the tenant has a custom domain configured, this is the custom domain URL; otherwise it falls back to the platform subdomain. Used as the base URL for third-party login popups and other flows that should originate from the tenant's own domain. | [types.ts:25](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L25) |
| []()`captcha?`       | `CaptchaTenantConfig` | Captcha provider and its public configuration. Present only when a provider is selected and fully configured.                                                                                                                                                                                                        | [types.ts:29](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L29) |
| []()`cookieDomain?`  | `string`              | Cookie domain to scope SDK cookies (e.g. '.example.org'). When set, cookies are readable across all subdomains.                                                                                                                                                                                                      | [types.ts:19](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L19) |
| []()`heartbeat?`     | `HeartbeatConfig`     | Heartbeat/beacon configuration. Present only when the SdkHeartbeat feature is active for the tenant.                                                                                                                                                                                                                 | [types.ts:27](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L27) |
| []()`loginProviders` | `string`\[]           | Slugs of OAuth providers enabled for this tenant (e.g. \['google', 'apple']).                                                                                                                                                                                                                                        | [types.ts:17](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L17) |


---

### Interface: TrackEventData

Defined in: [types.ts:274](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L274)

Optional metadata to attach to a tracked event.

Standard fields are collected automatically from the page, but you can override or extend them here.

#### Indexable[​](#indexable "Direct link to Indexable")

> \[`key`: `string`]: `unknown`

#### Properties[​](#properties "Direct link to Properties")

| Property                | Type                          | Description                                                     | Defined in                                                                                                                                                         |
| ----------------------- | ----------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| []()`content_id?`       | `string`                      | CMS identifier for the content on this page.                    | [types.ts:284](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L284) |
| []()`content_type?`     | `string`                      | Content type of the current page (e.g. `"article"`, `"video"`). | [types.ts:282](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L282) |
| []()`context?`          | `string`                      | Arbitrary context string for grouping or filtering events.      | [types.ts:292](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L292) |
| []()`conversion_pv_id?` | `string`                      | Pageview ID to attribute a conversion to.                       | [types.ts:294](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L294) |
| []()`data?`             | `Record`<`string`, `unknown`> | Arbitrary additional key/value data.                            | [types.ts:298](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L298) |
| []()`object_id?`        | `string`                      | Identifier of the primary object the event relates to.          | [types.ts:290](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L290) |
| []()`object_type?`      | `string`                      | Type of the primary object the event relates to.                | [types.ts:288](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L288) |
| []()`page_title?`       | `string`                      | Page title. Defaults to `document.title`.                       | [types.ts:280](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L280) |
| []()`publisher?`        | `string`                      | Publisher or site identifier.                                   | [types.ts:286](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L286) |
| []()`referer?`          | `string`                      | Referring URL. Defaults to `document.referrer`.                 | [types.ts:278](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L278) |
| []()`url?`              | `string`                      | Page URL. Defaults to `window.location.href`.                   | [types.ts:276](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L276) |
| []()`url_in_click?`     | `string`                      | URL contained in a clicked element.                             | [types.ts:296](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L296) |


---

### Interface: TrackResponse

Defined in: [types.ts:303](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L303)

Response returned after a successful event track call.

#### Properties[​](#properties "Direct link to Properties")

| Property       | Type     | Description                               | Defined in                                                                                                                                                         |
| -------------- | -------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| []()`event_id` | `string` | Unique identifier for the recorded event. | [types.ts:305](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L305) |


---

### Type Alias: AllegroCallback

> **AllegroCallback** = (`allegro`) => `void`

Defined in: [types.ts:123](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L123)

#### Parameters[​](#parameters "Direct link to Parameters")

| Parameter | Type                                                              |
| --------- | ----------------------------------------------------------------- |
| `allegro` | [`AllegroSDK`](/developer/api-reference/interfaces/AllegroSDK.md) |

#### Returns[​](#returns "Direct link to Returns")

`void`


---

### Type Alias: AudienceMember

> **AudienceMember** = `object`

Defined in: [types.ts:943](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L943)

An audience member record as returned by the API.

#### Properties[​](#properties "Direct link to Properties")

| Property             | Type               | Defined in                                                                                                                                                         |
| -------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| []()`created_at`     | `string`           | [types.ts:948](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L948) |
| []()`deleted_at`     | `string` | `null` | [types.ts:950](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L950) |
| []()`email`          | `string`           | [types.ts:945](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L945) |
| []()`email_verified` | `boolean`          | [types.ts:947](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L947) |
| []()`id`             | `string`           | [types.ts:944](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L944) |
| []()`meta`           | `object`           | [types.ts:951](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L951) |
| []()`name`           | `string`           | [types.ts:946](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L946) |
| []()`updated_at`     | `string`           | [types.ts:949](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L949) |


---

### Type Alias: IdentifySessionResponse

> **IdentifySessionResponse** = `object`

Defined in: [types.ts:1067](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1067)

Response returned by [MemberNamespace.identifyByEmail](/developer/api-reference/interfaces/MemberNamespace.md#identifybyemail).

#### Properties[​](#properties "Direct link to Properties")

| Property  | Type     | Defined in                                                                                                                                                           |
| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| []()`jwt` | `string` | [types.ts:1068](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1068) |


---

### Type Alias: InteractionAction

> **InteractionAction** = [`InteractionActionTemplate`](/developer/api-reference/interfaces/InteractionActionTemplate.md) | `InteractionActionComponent` | [`InteractionActionJavaScript`](/developer/api-reference/interfaces/InteractionActionJavaScript.md) | [`InteractionActionCss`](/developer/api-reference/interfaces/InteractionActionCss.md) | [`InteractionActionCookie`](/developer/api-reference/interfaces/InteractionActionCookie.md)

Defined in: [interaction/types.ts:140](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/types.ts#L140)

Union of all possible interaction action types.


---

### Type Alias: MagicLinkRequestResponse

> **MagicLinkRequestResponse** = `object`

Defined in: [types.ts:961](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L961)

Response returned after requesting a magic link.

#### Properties[​](#properties "Direct link to Properties")

| Property      | Type      | Defined in                                                                                                                                                         |
| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| []()`created` | `boolean` | [types.ts:962](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L962) |
| []()`jwt`     | `string`  | [types.ts:963](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L963) |
| []()`status`  | `"ok"`    | [types.ts:964](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L964) |


---

### Type Alias: MagicLinkValidateResponse

> **MagicLinkValidateResponse** = `object`

Defined in: [types.ts:968](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L968)

Response returned after successfully validating a magic link token.

#### Properties[​](#properties "Direct link to Properties")

| Property                     | Type        | Description                             | Defined in                                                                                                                                                         |
| ---------------------------- | ----------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| []()`jwt`                    | `string`    | -                                       | [types.ts:970](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L970) |
| []()`message`                | `string`    | -                                       | [types.ts:969](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L969) |
| []()`return_url`             | `string`    | URL the member should be redirected to. | [types.ts:972](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L972) |
| []()`sessions_authenticated` | `string`\[] | -                                       | [types.ts:973](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L973) |


---

### Type Alias: MemberJwtPayload

> **MemberJwtPayload** = `object`

Defined in: [types.ts:1408](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1408)

Decoded payload of the Allegro session JWT.

Read via [MemberNamespace.sessionFromJwt](/developer/api-reference/interfaces/MemberNamespace.md#sessionfromjwt) — no network request required.

#### Indexable[​](#indexable "Direct link to Indexable")

> \[`key`: `string`]: `unknown`

#### Properties[​](#properties "Direct link to Properties")

| Property                                     | Type                                                                                          | Description                                                                                                                                                                                                                                                                         | Defined in                                                                                                                                                           |
| -------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| []()`aud`                                    | `string`                                                                                      | -                                                                                                                                                                                                                                                                                   | [types.ts:1410](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1410) |
| []()`audience_member`                        | `Omit`<[`AudienceMember`](/developer/api-reference/type-aliases/AudienceMember.md), `"meta"`> | -                                                                                                                                                                                                                                                                                   | [types.ts:1442](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1442) |
| []()`authenticated`                          | `boolean`                                                                                     | Whether the session has been fully authenticated (not just identified).                                                                                                                                                                                                             | [types.ts:1418](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1418) |
| []()`exp`                                    | `number`                                                                                      | Expiry timestamp (Unix seconds).                                                                                                                                                                                                                                                    | [types.ts:1414](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1414) |
| []()`iat`                                    | `number`                                                                                      | Issued-at timestamp (Unix seconds).                                                                                                                                                                                                                                                 | [types.ts:1412](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1412) |
| []()`iss`                                    | `string`                                                                                      | -                                                                                                                                                                                                                                                                                   | [types.ts:1409](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1409) |
| []()`partner_affiliation?`                   | `object`                                                                                      | The partner organization this member belongs to. Present only for a member with an active partner affiliate entitlement and an organization on record. Each branding key is present only when the organization has that value on record. Image paths are resolved to absolute URLs. | [types.ts:1433](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1433) |
| `partner_affiliation.favicon_url?`           | `string`                                                                                      | -                                                                                                                                                                                                                                                                                   | [types.ts:1440](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1440) |
| `partner_affiliation.id`                     | `string`                                                                                      | -                                                                                                                                                                                                                                                                                   | [types.ts:1434](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1434) |
| `partner_affiliation.logo_background_color?` | `string`                                                                                      | -                                                                                                                                                                                                                                                                                   | [types.ts:1437](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1437) |
| `partner_affiliation.logo_url?`              | `string`                                                                                      | -                                                                                                                                                                                                                                                                                   | [types.ts:1436](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1436) |
| `partner_affiliation.name`                   | `string`                                                                                      | -                                                                                                                                                                                                                                                                                   | [types.ts:1435](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1435) |
| `partner_affiliation.primary_image_alt?`     | `string`                                                                                      | -                                                                                                                                                                                                                                                                                   | [types.ts:1439](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1439) |
| `partner_affiliation.primary_image_url?`     | `string`                                                                                      | -                                                                                                                                                                                                                                                                                   | [types.ts:1438](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1438) |
| []()`products`                               | `string`\[]                                                                                   | Slugs of products the user has an active entitlement to.                                                                                                                                                                                                                            | [types.ts:1424](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1424) |
| []()`session`                                | `object`                                                                                      | -                                                                                                                                                                                                                                                                                   | [types.ts:1419](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1419) |
| `session.authenticated_at`                   | `string` | `null`                                                                            | -                                                                                                                                                                                                                                                                                   | [types.ts:1421](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1421) |
| `session.id`                                 | `string`                                                                                      | -                                                                                                                                                                                                                                                                                   | [types.ts:1420](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1420) |
| []()`sub`                                    | `string`                                                                                      | Audience Member ID.                                                                                                                                                                                                                                                                 | [types.ts:1416](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1416) |


---

### Type Alias: MeterUsageMap

> **MeterUsageMap** = `Record`<`string`, [`MeterUsage`](/developer/api-reference/interfaces/MeterUsage.md)>

Defined in: [interaction/meters.ts:14](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/interaction/meters.ts#L14)

Meter usage keyed by meter slug.


---

### Type Alias: SessionResponse

> **SessionResponse** = `object`

Defined in: [types.ts:1036](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1036)

Response returned by [MemberNamespace.session](/developer/api-reference/interfaces/MemberNamespace.md#session).

#### Properties[​](#properties "Direct link to Properties")

| Property                                      | Type                         | Defined in                                                                                                                                                           |
| --------------------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| []()`data`                                    | `object`                     | [types.ts:1037](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1037) |
| `data.attributes`                             | `object`                     | [types.ts:1040](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1040) |
| `data.attributes.authenticated_at`            | `string` | `null`           | [types.ts:1042](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1042) |
| `data.attributes.created_at`                  | `string`                     | [types.ts:1043](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1043) |
| `data.attributes.is_authenticated`            | `boolean`                    | [types.ts:1041](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1041) |
| `data.attributes.updated_at`                  | `string`                     | [types.ts:1044](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1044) |
| `data.id`                                     | `string`                     | [types.ts:1038](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1038) |
| `data.relationships`                          | `object`                     | [types.ts:1046](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1046) |
| `data.relationships.audienceMember`           | `object`                     | [types.ts:1047](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1047) |
| `data.relationships.audienceMember.data`      | `object`                     | [types.ts:1048](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1048) |
| `data.relationships.audienceMember.data.id`   | `string`                     | [types.ts:1049](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1049) |
| `data.relationships.audienceMember.data.type` | `"audience_members"`         | [types.ts:1050](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1050) |
| `data.type`                                   | `"audience_device_sessions"` | [types.ts:1039](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1039) |
| []()`included`                                | `object`\[]                  | [types.ts:1055](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1055) |


---

### Type Alias: SocialLoginResponse

> **SocialLoginResponse** = `object`

Defined in: [types.ts:912](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L912)

Response returned after a successful social login.

#### Properties[​](#properties "Direct link to Properties")

| Property         | Type      | Defined in                                                                                                                                                         |
| ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| []()`created`    | `boolean` | [types.ts:913](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L913) |
| []()`session_id` | `string`  | [types.ts:914](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L914) |
| []()`token`      | `string`  | [types.ts:915](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L915) |


---

### Type Alias: UserAttributeValue

> **UserAttributeValue** = `object`

Defined in: [types.ts:1121](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1121)

A single user attribute defined by the organization, together with the authenticated member's current value (`null` when the member has not set it). Attributes the organization marked private are never returned here.

#### Properties[​](#properties "Direct link to Properties")

| Property               | Type                                       | Description                                                                 | Defined in                                                                                                                                                           |
| ---------------------- | ------------------------------------------ | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| []()`description`      | `string` | `null`                         | -                                                                           | [types.ts:1124](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1124) |
| []()`name`             | `string`                                   | -                                                                           | [types.ts:1123](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1123) |
| []()`options`          | `string`\[] | `null`                      | -                                                                           | [types.ts:1126](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1126) |
| []()`private`          | `boolean`                                  | Always `false` here: private attributes are not exposed to the session API. | [types.ts:1131](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1131) |
| []()`slug`             | `string`                                   | -                                                                           | [types.ts:1122](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1122) |
| []()`type`             | `string`                                   | -                                                                           | [types.ts:1125](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1125) |
| []()`user_editable`    | `boolean`                                  | Whether the member may update this attribute through the session API.       | [types.ts:1129](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1129) |
| []()`validation_rules` | `UserAttributeValidationRule`\[] | `null` | -                                                                           | [types.ts:1132](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1132) |
| []()`value`            | `unknown`                                  | -                                                                           | [types.ts:1127](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/types.ts#L1127) |


---

### Variable: logger

> `const` **logger**: `object`

Defined in: [logger.ts:12](https://github.com/alleyinteractive/allegro/blob/dd6a4ea554121f94a356441632916a4ab6caabd2/packages/allegro-platform/resources/js/sdk/logger.ts#L12)

#### Type Declaration[​](#type-declaration "Direct link to Type Declaration")

##### debug()[​](#debug "Direct link to debug()")

> **debug**(...`args`): `void`

###### Parameters[​](#parameters "Direct link to Parameters")

| Parameter | Type         |
| --------- | ------------ |
| ...`args` | `unknown`\[] |

###### Returns[​](#returns "Direct link to Returns")

`void`

##### error()[​](#error "Direct link to error()")

> **error**(...`args`): `void`

###### Parameters[​](#parameters-1 "Direct link to Parameters")

| Parameter | Type         |
| --------- | ------------ |
| ...`args` | `unknown`\[] |

###### Returns[​](#returns-1 "Direct link to Returns")

`void`

##### log()[​](#log "Direct link to log()")

> **log**(...`args`): `void`

###### Parameters[​](#parameters-2 "Direct link to Parameters")

| Parameter | Type         |
| --------- | ------------ |
| ...`args` | `unknown`\[] |

###### Returns[​](#returns-2 "Direct link to Returns")

`void`

##### warn()[​](#warn "Direct link to warn()")

> **warn**(...`args`): `void`

###### Parameters[​](#parameters-3 "Direct link to Parameters")

| Parameter | Type         |
| --------- | ------------ |
| ...`args` | `unknown`\[] |

###### Returns[​](#returns-3 "Direct link to Returns")

`void`


---

### Web Components

Allegro ships a set of custom HTML elements you can drop into any page. Each component handles its own markup, behavior, and styles — just add the script tag and use the element wherever you need it.

| Component                                                           | Element                         | Description                                                                        |
| ------------------------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------- |
| [Login Form](/developer/components/login-form.md)                   | `<allegro-login-form>`          | Authenticates readers via magic link or OAuth                                      |
| [Email Form](/developer/components/email-form.md)                   | `<allegro-email-form>`          | Collects email addresses with a confirmation state                                 |
| [Content Gate](/developer/components/content-gate.md)               | `<allegro-content-gate>`        | Blocks content behind a full-page registration or paywall prompt                   |
| [Content Gate Inline](/developer/components/content-gate-inline.md) | `<allegro-content-gate-inline>` | Hides inline article content at a specific position until the reader authenticates |
| [Form](/developer/components/form.md)                               | `<allegro-form>`                | Renders an admin-composed form of user attributes for the authenticated member     |
| [Modal](/developer/components/modal.md)                             | `<allegro-modal>`               | Shows a centered dialog, such as a welcome note, that the reader closes            |
| [Bottom Drawer](/developer/components/bottom-drawer.md)             | `<allegro-bottom-drawer>`       | Raises a panel from the bottom of the screen that does not block the page          |

#### Previewing components[​](#previewing-components "Direct link to Previewing components")

The Allegro admin includes a **Component Previews** page under the **Developer** section. It renders each component in isolation so you can tweak attributes and see results without deploying to your site.

Navigate to `/developer/components` in your Allegro instance to open the preview tool.

![Component Previews page showing five component cards](/assets/images/components-preview-037618146cad3ad63f125b87b728fefa.png)

##### Previewing as a signed-in member[​](#previewing-as-a-signed-in-member "Direct link to Previewing as a signed-in member")

Some components behave differently for an authenticated reader — the [Form](/developer/components/form.md) component, for example, renders the current member's saved values. The preview sandbox includes a **Preview as** selector so you can render a component as if a specific audience member were signed in, without leaving the admin or touching your live site.

Pick a member from the selector (search by email or display name) to render the component inside an authenticated session for that member. Choose **Logged out** to return to the anonymous view.

Previews use the member's real record

A component previewed as a member acts on that member's real data. If you submit the Form component while previewing as someone, their stored attribute values are updated for real.

The selector only appears for roles that can edit audience members, and outside a production environment it is limited to super admins.

##### Attribute suggestions[​](#attribute-suggestions "Direct link to Attribute suggestions")

Text attributes that map to existing data offer autocomplete suggestions as you fill them in. The Form component's `slug` attribute, for instance, suggests the slugs of forms already defined in your organization, so you can preview a real form without copying its slug by hand.


---

### BottomDrawer

`<allegro-bottom-drawer>` is a panel that rises from the bottom of the screen and sits over the page without blocking it, such as a donation or newsletter prompt. The reader can keep reading and scrolling, collapse the panel to a short bar, or close it.

The Bottom Drawer opens as soon as it renders. It has no delay, trigger or frequency options: the [interaction](/developer/guides/interactions.md) that places it decides whether and when it shows. Once the reader dismisses it, it stays closed for the rest of the visit, and it reopens collapsed or expanded as the reader left it (see [Remembering state for the visit](#remembering-state-for-the-visit)). It never takes focus when it opens, never traps focus and never locks page scroll.

#### Usage[​](#usage "Direct link to Usage")

```html
<allegro-bottom-drawer>
    <h2>Support Acme News</h2>
    <p>Your gift keeps local reporting free for everyone.</p>
    <a href="/donate">Donate</a>
</allegro-bottom-drawer>

```

A Bottom Drawer that can collapse to a one-line bar, and starts collapsed:

```html
<allegro-bottom-drawer collapsed>
    <h2>Support Acme News</h2>
    <p>Your gift keeps local reporting free for everyone.</p>
    <a href="/donate">Donate</a>

    <div slot="collapsed">
        <p>Support Acme News</p>
        <button type="button" data-allegro-expand>Donate</button>
    </div>
</allegro-bottom-drawer>

```

The panel always spans the width of the screen, up to a maximum width set in Branding. Its height follows the content up to `--bottomDrawer--max-height`, and taller content scrolls inside the panel. The component does not lay out its content. Style the slotted markup in the template's CSS field.

##### Accessibility[​](#accessibility "Direct link to Accessibility")

The Bottom Drawer is a labelled region, so screen reader users can reach it from the landmarks list. It names itself from the first of these that exists:

1. The `label` attribute.
2. An element in its content marked `data-allegro-title`.
3. The first `h1`–`h6` in its content.

When it opens, it announces itself once, politely, as "{name}, panel opened at the bottom of the page", where {name} is its accessible name. It does not announce collapse or expand: the toggle's `aria-expanded` covers that. The toggle is named "Collapse" or "Expand", and the close button, when there is one, "Close".

While it is on the page, the Bottom Drawer sets `scroll-padding-bottom` on the page to its own height, so an element the reader tabs to is not hidden under the panel. It restores the page's previous value when it closes.

When the Bottom Drawer closes with focus inside it, focus returns to the element on the page the reader came from, so keyboard users don't land at the top of the page.

When a collapse or expand hides the element that has focus, such as a `data-allegro-expand` button in the collapsed bar, focus moves to the toggle.

##### Closing[​](#closing "Direct link to Closing")

Every close records a `method`, which says how the Bottom Drawer was closed. It is sent with the `dismiss_bottom_drawer` event and the `allegro:bottom-drawer:closed` event.

| Method         | Cause                                                                                         |
| -------------- | --------------------------------------------------------------------------------------------- |
| `escape`       | The reader presses Escape while focus is inside the Bottom Drawer.                            |
| `close-button` | The reader clicks the built-in close button.                                                  |
| `action`       | A click on or inside a `data-allegro-close` element, or a slotted form's **Continue** button. |
| `api`          | `close()` or the `allegro:bottom-drawer:close` event.                                         |

The Bottom Drawer does not close when the reader logs in.

```js
const bottomDrawer = document.querySelector('allegro-bottom-drawer');

bottomDrawer.collapse();
bottomDrawer.expand();
bottomDrawer.close();

```

With `dismissible="false"`, the Bottom Drawer has no close button and ignores Escape, so only `action` and `api` closes happen. Give it a `data-allegro-close` button or a form so the reader can still close it.

```html
<allegro-bottom-drawer dismissible="false">
    <h2>Support Acme News</h2>
    <p>Your gift keeps local reporting free for everyone.</p>
    <a href="/donate" data-allegro-close>Donate</a>
    <button type="button" data-allegro-close>Maybe later</button>
</allegro-bottom-drawer>

```

##### Remembering state for the visit[​](#remembering-state-for-the-visit "Direct link to Remembering state for the visit")

When an interaction places the Bottom Drawer, it remembers what the reader did until the browser closes:

| Reader action      | On later pages in the same visit                                              |
| ------------------ | ----------------------------------------------------------------------------- |
| Closes it          | It doesn't open, so it doesn't announce itself or track `view_bottom_drawer`. |
| Collapses it       | It opens collapsed, even without the `collapsed` attribute.                   |
| Expands it         | It opens expanded, even with the `collapsed` attribute.                       |
| Nothing remembered | It opens collapsed or expanded as the `collapsed` attribute says.             |

Every close method counts, and so do `collapse()` and `expand()` calls from site code.

* Each interaction is remembered separately, by its slug. Closing one interaction's Bottom Drawer does not hide another's.
* The state is kept in a session cookie named `allegro_bottom-drawer_{slug}`, shared across tabs and set on your organization's cookie domain when it has one.
* A Bottom Drawer that your site's code or theme renders directly, rather than through an interaction, has no slug and remembers nothing.

To see a closed Bottom Drawer again while testing, close the browser or delete its cookie.

note

The interaction still runs on later pages, so its frequency caps still count those deliveries even though the Bottom Drawer does not show.

#### Attributes[​](#attributes "Direct link to Attributes")

Components read their attributes once, when they connect. Changing `collapsed` after the Bottom Drawer opens has no effect: use `expand()` and `collapse()`.

| Attribute       | Type      | Default   | Description                                                                                                                                                                                                   |
| --------------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `collapsed`     | `boolean` | `false`   | Start collapsed. Ignored when there is no `collapsed` slot, and when the reader already collapsed or expanded it earlier in the visit. The component then keeps the attribute in step with the current state. |
| `dismissible`   | `boolean` | `true`    | Show the close button and close on Escape. Turn off to keep the Bottom Drawer open until a `data-allegro-close` element, a slotted form's **Continue** button or site code closes it.                         |
| `label`         | `text`    | *(empty)* | Accessible name. Overrides the title element and the first heading.                                                                                                                                           |
| `tracking-data` | `text`    | *(empty)* | JSON object of custom data merged into every tracked event, e.g. `"{'campaign': 'donate'}"`.                                                                                                                  |

#### States[​](#states "Direct link to States")

| State     | Trigger                                                                                                                         | Description                                |
| --------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| Expanded  | Opening without `collapsed` or after the reader expanded it earlier in the visit, the toggle, `data-allegro-expand`, `expand()` | Shows the default slot.                    |
| Collapsed | Opening with `collapsed` or after the reader collapsed it earlier in the visit, the toggle, `collapse()`                        | Shows the `collapsed` slot as a short bar. |

Only the toggle button collapses or expands the panel. Clicks elsewhere in the panel do not.

#### Slots[​](#slots "Direct link to Slots")

| Slot        | Appears in | Description                                                                                                                              |
| ----------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| *(default)* | Expanded   | The expanded content.                                                                                                                    |
| `collapsed` | Collapsed  | The short bar. Without it, the Bottom Drawer cannot collapse and shows only the close button, or no controls with `dismissible="false"`. |

```html
<div slot="collapsed">
    <p>Support Acme News</p>
    <button type="button" data-allegro-expand>Donate</button>
</div>

```

#### Events[​](#events "Direct link to Events")

##### Dispatched[​](#dispatched "Direct link to Dispatched")

| Event                          | Bubbles | Detail                   | Description                                                |
| ------------------------------ | ------- | ------------------------ | ---------------------------------------------------------- |
| `allegro:bottom-drawer:open`   | yes     | *(none)*                 | Fired on the element once the Bottom Drawer opens.         |
| `allegro:bottom-drawer:toggle` | yes     | `{ collapsed: boolean }` | Fired on the element after each collapse or expand.        |
| `allegro:bottom-drawer:closed` | no      | `{ method: string }`     | Fired on `window` once the Bottom Drawer has been removed. |

##### Listened to[​](#listened-to "Direct link to Listened to")

| Event                         | Detail   | Description                                                          |
| ----------------------------- | -------- | -------------------------------------------------------------------- |
| `allegro:bottom-drawer:close` | *(none)* | Dispatch on the element, or from inside it, to close it.             |
| `allegro:content-gate:close`  | *(none)* | A slotted Email Form's **Continue** button closes the Bottom Drawer. |
| `allegro:login-form:continue` | *(none)* | A slotted Login Form's **Continue** button closes the Bottom Drawer. |

```js
document
    .querySelector('allegro-bottom-drawer')
    .dispatchEvent(new CustomEvent('allegro:bottom-drawer:close'));

```

#### Tracked Events[​](#tracked-events "Direct link to Tracked Events")

The component records the following events via the Allegro SDK.

| Event                    | When                                                                                 | Data                                     |
| ------------------------ | ------------------------------------------------------------------------------------ | ---------------------------------------- |
| `view_bottom_drawer`     | Fired when it opens.                                                                 | `{ collapsed: boolean }`                 |
| `dismiss_bottom_drawer`  | Fired when it closes.                                                                | `{ collapsed: boolean, method: string }` |
| `collapse_bottom_drawer` | Fired when the reader collapses it with the toggle.                                  | *(none)*                                 |
| `expand_bottom_drawer`   | Fired when the reader expands it with the toggle or a `data-allegro-expand` element. | *(none)*                                 |

`expand()` and `collapse()` dispatch `allegro:bottom-drawer:toggle` but are not tracked, so changes made from site code don't count as reader actions.

#### CSS Variables[​](#css-variables "Direct link to CSS Variables")

Set the variables in the template's CSS field. All of them can also be set for your whole organization in [Branding](/product/administration/branding.md).

```css
allegro-bottom-drawer {
    --bottomDrawer--background: #fffaf0;
    --bottomDrawer--max-width: 48rem;
}

```

Don't set them with a `style` attribute on the element. Components accept only their own attributes and log an error for `style`, `class` and `id`.

Defaults written below as `u(n)` mean `n` times `--bottomDrawer--base-font-size`, the component's sizing unit: `u(0.5)` is half that unit, `u(1.5)` is one and a half. The unit defaults to `--allegro--font-size`, then the page's `rem`. If the host page sets a root `font-size` other than the usual 16px, pin it so the Bottom Drawer sizes the same either way:

```css
allegro-bottom-drawer {
    --bottomDrawer--base-font-size: 16px;
}

```

##### Panel[​](#panel "Direct link to Panel")

| Variable                              | Default                           | Description                                                                |
| ------------------------------------- | --------------------------------- | -------------------------------------------------------------------------- |
| `--bottomDrawer--base-font-size`      | `var(--allegro--font-size, 1rem)` | Base sizing unit for the component.                                        |
| `--bottomDrawer--background`          | `#fff`                            | Panel background. Falls back to `--allegro--color-background`.             |
| `--bottomDrawer--color`               | `#000`                            | Panel text color. Falls back to `--allegro--color-text`.                   |
| `--bottomDrawer--font-family`         | *(none)*                          | Panel font family. Falls back to `--allegro--font-family`.                 |
| `--bottomDrawer--padding`             | `u(1.5)`                          | Padding around the content.                                                |
| `--bottomDrawer--border-radius`       | `u(0.375)`                        | Radius of the top corners. Falls back to `--allegro--radius`.              |
| `--bottomDrawer--max-width`           | `u(64)`                           | Maximum panel width. Use `none` with a `0` gutter for an edge-to-edge bar. |
| `--bottomDrawer--max-height`          | `calc(100dvh - u(3))`             | Maximum panel height. Leaves a strip of page visible above it.             |
| `--bottomDrawer--gutter`              | `u(1)`                            | Space between the panel and the sides of the screen.                       |
| `--bottomDrawer--z-index`             | `9997`                            | Stacking order.                                                            |
| `--bottomDrawer--transition-duration` | `0.35s`                           | Length of the slide animation. Capped at `0.15s` under reduced motion.     |

##### Close button[​](#close-button "Direct link to Close button")

These also size and color the collapse and expand toggle.

| Variable                       | Default        | Description       |
| ------------------------------ | -------------- | ----------------- |
| `--bottomDrawer--close--size`  | `u(2.5)`       | Width and height. |
| `--bottomDrawer--close--color` | `currentColor` | Icon color.       |

##### Buttons in your content[​](#buttons-in-your-content "Direct link to Buttons in your content")

The Bottom Drawer does not style your buttons. It resolves a button color for you to use in the template's CSS, from `--bottomDrawer--button--background` and `--bottomDrawer--button--color`, then the global button tokens.

| Variable                             | Default | Description                                                                           |
| ------------------------------------ | ------- | ------------------------------------------------------------------------------------- |
| `--bottomDrawer--button--background` | `#000`  | Set in Branding. Read it as `var(--bottom-drawer-button-background)` in template CSS. |
| `--bottomDrawer--button--color`      | `#fff`  | Set in Branding. Read it as `var(--bottom-drawer-button-color)` in template CSS.      |

##### Parts[​](#parts "Direct link to Parts")

Style the component's own elements with `::part()`.

| Part        | Element                                                    |
| ----------- | ---------------------------------------------------------- |
| `panel`     | The panel.                                                 |
| `body`      | The area around the expanded content.                      |
| `collapsed` | The area around the collapsed bar.                         |
| `controls`  | The group of buttons in the top corner.                    |
| `toggle`    | The collapse and expand button.                            |
| `close`     | The close button. Not rendered with `dismissible="false"`. |

##### Motion[​](#motion "Direct link to Motion")

The panel slides up from below the screen and slides back down on close. When the reader has asked for reduced motion, it only fades. Browsers without `@starting-style` show it without animation.

#### Example: Edge-to-edge bar[​](#example-edge-to-edge-bar "Direct link to Example: Edge-to-edge bar")

```css
allegro-bottom-drawer {
    --bottomDrawer--gutter: 0;
    --bottomDrawer--max-width: none;
    --bottomDrawer--border-radius: 0;
    --bottomDrawer--background: #1f2937;
    --bottomDrawer--color: #f9fafb;
}

```


---

### ContentGate

`<allegro-content-gate>` is a full-page dialog that renders immediately and blocks interaction with the page beneath it. Slotted children are displayed inside the dialog. Use it to build registration walls, subscription prompts, or any other gated experience.

#### Usage[​](#usage "Direct link to Usage")

```html
<allegro-content-gate>
    <div>
        <h2>Subscribe to continue reading</h2>
        <allegro-login-form></allegro-login-form>
    </div>
</allegro-content-gate>

```

With a dismiss button and centered position:

```html
<allegro-content-gate dismissible="true" position="center">
    <p>Sign in to access premium content.</p>
</allegro-content-gate>

```

The dialog is modal: focus stays inside it and the page beneath is inert. Give it a name with `label`, or start the slotted content with a heading. When the dialog closes, focus returns to whatever had it before the dialog opened. A non-dismissible dialog (a roadblock) ignores Escape.

#### Revealing gated content after login[​](#revealing-gated-content-after-login "Direct link to Revealing gated content after login")

When a content gate sits inside an [interaction](/developer/guides/interactions.md) that also blurred or truncated the article behind it, closing the gate after a successful login reveals that content instead of leaving it hidden. The gate finds its host interaction, removes the blur or truncation, and the full article is shown in place. To react to this yourself, listen for [`allegro:interaction:ungated`](/developer/guides/javascript-events.md) on `window`.

#### Attributes[​](#attributes "Direct link to Attributes")

| Attribute       | Type      | Default   | Description                                                                                                    |
| --------------- | --------- | --------- | -------------------------------------------------------------------------------------------------------------- |
| `allow-scroll`  | `boolean` | `false`   | Leave the page scrollable while the dialog is open. By default the page scroll is locked.                      |
| `dismissible`   | `boolean` | `false`   | Show a close button allowing the user to dismiss the dialog. Escape also dismisses it.                         |
| `label`         | `text`    | *(empty)* | Name screen readers announce for the dialog. Defaults to the first slotted heading, then "Continue reading".   |
| `position`      | `text`    | `bottom`  | Dialog position on screen. `bottom` anchors to the bottom edge; `center` floats in the middle of the viewport. |
| `tracking-data` | `text`    | *(empty)* | JSON object of custom data merged into every tracked event, e.g. `"{'placement': 'article'}"`.                 |

#### Events[​](#events "Direct link to Events")

##### Dispatched[​](#dispatched "Direct link to Dispatched")

| Event                       | Bubbles | Detail   | Description                                                     |
| --------------------------- | ------- | -------- | --------------------------------------------------------------- |
| `allegro:content-gate:open` | yes     | *(none)* | Fired immediately after the dialog renders and becomes visible. |

##### Listened to[​](#listened-to "Direct link to Listened to")

| Event                        | Detail   | Description                                                     |
| ---------------------------- | -------- | --------------------------------------------------------------- |
| `allegro:content-gate:close` | *(none)* | Dispatch on the element to programmatically dismiss the dialog. |

```js
document
    .querySelector('allegro-content-gate')
    .dispatchEvent(new CustomEvent('allegro:content-gate:close'));

```

#### Tracked Events[​](#tracked-events "Direct link to Tracked Events")

The component records the following events via the Allegro SDK.

| Event                  | When                                                                    | Data                                                                  |
| ---------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `view_content_gate`    | Fired when the dialog first renders.                                    | `{ position: string, interactionType: 'dismissible' \| 'roadblock' }` |
| `dismiss_content_gate` | Fired when the user dismisses the dialog via the close button or event. | `{ position: string }`                                                |

#### CSS Variables[​](#css-variables "Direct link to CSS Variables")

All visual properties are exposed as CSS custom properties so the component can be themed from the host page without piercing the shadow DOM.

```css
allegro-content-gate {
    --contentGate--background: #fff;
    --contentGate--max-width: 40rem;
}

```

##### General[​](#general "Direct link to General")

| Variable                      | Default  | Description                                                        |
| ----------------------------- | -------- | ------------------------------------------------------------------ |
| `--contentGate--background`   | `#fff`   | Dialog background color.                                           |
| `--contentGate--color`        | `#000`   | Dialog text color. Also used as the close button icon color.       |
| `--contentGate--font-family`  | *(none)* | Dialog font family. Falls back to `--allegro--font-family` if set. |
| `--contentGate--margin`       | `0`      | Dialog margin.                                                     |
| `--contentGate--max-width`    | `100%`   | Max width of the dialog content wrapper.                           |
| `--contentGate--padding`      | `0`      | Dialog padding.                                                    |
| `--contentGate--children-gap` | `1rem`   | Gap between slotted children inside the dialog.                    |


---

### ContentGateInline

`<allegro-content-gate-inline>` is placed directly inside an article body to hide the content that follows it. Readers see a registration or login prompt inline; once they authenticate the hidden content is revealed and the gate removes itself from the DOM.

#### Usage[​](#usage "Direct link to Usage")

Place the component at the point in the article where you want content to be gated:

```html
<div class="article-body">
    <p>This paragraph is always visible.</p>

    <allegro-content-gate-inline>
        <h2>Sign in to keep reading</h2>
        <allegro-login-form></allegro-login-form>
    </allegro-content-gate-inline>

    <p>This paragraph and everything below is hidden until the reader authenticates.</p>
</div>

```

Speedbump (dismissible) mode with a specific position and container:

```html
<allegro-content-gate-inline
    dismissible="true"
    element-position="3"
    article-body-selector=".article-body"
>
    <p>Create a free account to continue reading.</p>
    <allegro-login-form></allegro-login-form>
</allegro-content-gate-inline>

```

#### Attributes[​](#attributes "Direct link to Attributes")

| Attribute               | Type      | Default   | Description                                                                                                                                                            |
| ----------------------- | --------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dismissible`           | `boolean` | `false`   | Show a close button allowing the reader to dismiss the gate without authenticating. When `false` the gate is a roadblock; when `true` it is a speedbump.               |
| `element-position`      | `text`    | *(empty)* | Zero-based index of the child element inside the article body after which content should be hidden. When omitted, all next siblings after the gate element are hidden. |
| `article-body-selector` | `text`    | *(empty)* | CSS selector for the article body container used when `element-position` is set. When omitted, the gate's direct parent is used.                                       |
| `tracking-data`         | `text`    | *(empty)* | JSON object of custom data merged into every tracked event, e.g. `"{'placement': 'article'}"`.                                                                         |

#### States[​](#states "Direct link to States")

| State     | Trigger               | Description                                                                                     |
| --------- | --------------------- | ----------------------------------------------------------------------------------------------- |
| Roadblock | `dismissible="false"` | Host class `gate-is-roadblock` is applied. No close button is rendered.                         |
| Speedbump | `dismissible="true"`  | Host class `gate-is-speedbump` is applied. A close button lets the reader dismiss without auth. |

The hidden content is moved into a `<div class="allegro-content-gate-overlay" inert>` after the gate. `inert` keeps keyboard and screen-reader users out of it until it is released, whichever way you style the overlay (hidden, faded, or blurred).

#### Slots[​](#slots "Direct link to Slots")

| Slot        | Appears in | Description                                                                       |
| ----------- | ---------- | --------------------------------------------------------------------------------- |
| *(default)* | Always     | Content rendered inside the gate — typically a heading and a login or email form. |

```html
<allegro-content-gate-inline>
    <h2>Subscribe to keep reading</h2>
    <allegro-login-form></allegro-login-form>
</allegro-content-gate-inline>

```

#### Events[​](#events "Direct link to Events")

##### Dispatched[​](#dispatched "Direct link to Dispatched")

| Event                              | Bubbles | Detail   | Description                                                 |
| ---------------------------------- | ------- | -------- | ----------------------------------------------------------- |
| `allegro:content-gate-inline:open` | yes     | *(none)* | Fired immediately after the gate renders and hides content. |

##### Listened to[​](#listened-to "Direct link to Listened to")

| Event                        | Detail   | Description                                                                                                                                                                         |
| ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allegro:content-gate:close` | *(none)* | Dispatch on the element to programmatically release content and remove the gate. Also fired automatically by child login and email form components after successful authentication. |

```js
document
    .querySelector('allegro-content-gate-inline')
    .dispatchEvent(new CustomEvent('allegro:content-gate:close'));

```

#### Tracked Events[​](#tracked-events "Direct link to Tracked Events")

The component records the following events via the Allegro SDK.

| Event                         | When                                | Data                                                |
| ----------------------------- | ----------------------------------- | --------------------------------------------------- |
| `view_content_gate_inline`    | Fired when the gate renders.        | `{ interactionType: 'dismissible' \| 'roadblock' }` |
| `dismiss_content_gate_inline` | Fired when the reader clicks Close. | `{ interactionType: 'dismissible' }`                |

#### CSS Variables[​](#css-variables "Direct link to CSS Variables")

All visual properties are exposed as CSS custom properties so the component can be themed from the host page without piercing the shadow DOM.

```css
allegro-content-gate-inline {
    --contentGateInline--background: #fff;
    --contentGateInline--max-width: 40rem;
}

```

##### General[​](#general "Direct link to General")

| Variable                            | Default  | Description                                                      |
| ----------------------------------- | -------- | ---------------------------------------------------------------- |
| `--contentGateInline--background`   | `#fff`   | Gate background color.                                           |
| `--contentGateInline--color`        | `#000`   | Gate text color.                                                 |
| `--contentGateInline--font-family`  | *(none)* | Gate font family. Falls back to `--allegro--font-family` if set. |
| `--contentGateInline--margin`       | `0`      | Gate margin.                                                     |
| `--contentGateInline--max-width`    | *(none)* | Max width of the gate content wrapper.                           |
| `--contentGateInline--padding`      | `0`      | Gate padding.                                                    |
| `--contentGateInline--children-gap` | `1rem`   | Gap between slotted children inside the gate.                    |

#### Example: Dark Background[​](#example-dark-background "Direct link to Example: Dark Background")

```css
allegro-content-gate-inline {
    --contentGateInline--background: #111;
    --contentGateInline--color: #f5f5f5;
}

```


---

### EmailForm

`<allegro-email-form>` is a web component that renders an email subscription form. On success it transitions to a confirmation state. Both states are fully customizable via attributes, slots, CSS variables, and shadow parts.

#### Usage[​](#usage "Direct link to Usage")

```html
<allegro-email-form></allegro-email-form>

```

With custom attributes:

```html
<allegro-email-form
    form-label-text="Enter your email address"
    show-form-label="false"
    placeholder-text="Your email address"
    submit-text="Subscribe"
    show-disclaimer="true"
    disclaimer-text="We'll never share your email."
    confirmation-heading="You're in!"
    confirmation-text="Thanks for subscribing."
    continue-text="Continue"
></allegro-email-form>

```

#### Attributes[​](#attributes "Direct link to Attributes")

| Attribute              | Type      | Default                            | Description                                                                                                                                                                                                                               |
| ---------------------- | --------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `show-form-label`      | `boolean` | `true`                             | Whether to show the email field's label. When `false`, the label is still rendered for screen readers but visually hidden. If `placeholder-text` is empty, the label text is used as the placeholder so the field still has visible text. |
| `form-label-text`      | `text`    | `Email Address`                    | Label text for the email input field.                                                                                                                                                                                                     |
| `placeholder-text`     | `text`    | `Enter your email`                 | Placeholder text for the email input field.                                                                                                                                                                                               |
| `submit-text`          | `text`    | `Submit`                           | Label for the submit button.                                                                                                                                                                                                              |
| `show-disclaimer`      | `boolean` | `false`                            | Whether to show the disclaimer paragraph below the form.                                                                                                                                                                                  |
| `disclaimer-text`      | `text`    | *(empty)*                          | HTML for the disclaimer paragraph. Links and inline formatting are kept; other markup is stripped.                                                                                                                                        |
| `confirmation-heading` | `text`    | `Thank you!`                       | Heading shown in the confirmation state.                                                                                                                                                                                                  |
| `confirmation-text`    | `text`    | `Thanks for providing your email.` | Body text shown in the confirmation state.                                                                                                                                                                                                |
| `continue-text`        | `text`    | `Continue`                         | Label for the continue button in the confirmation state.                                                                                                                                                                                  |
| `user-attributes`      | `text`    | *(empty)*                          | JSON object of user attribute values stored against the reader on submit, e.g. `"{'wants-newsletter': true}"`.                                                                                                                            |
| `tracking-data`        | `text`    | *(empty)*                          | JSON object of custom data merged into every tracked event, e.g. `"{'campaign': 'footer'}"`.                                                                                                                                              |

##### Storing user attributes[​](#storing-user-attributes "Direct link to Storing user attributes")

`user-attributes` sets user attribute values on the reader when they submit their email, keyed by attribute slug. A value is only stored when the reader doesn't already have one for that attribute, so existing values are never overwritten. Every slug must be an attribute readers can edit; if one isn't, or a value fails the attribute's rules, the form shows the error and nothing is saved.

```html
<allegro-email-form
    user-attributes="{'signup-source': 'footer', 'wants-newsletter': true}"
></allegro-email-form>

```

#### States[​](#states "Direct link to States")

| State          | Trigger                    | Description                                      |
| -------------- | -------------------------- | ------------------------------------------------ |
| `email`        | Initial render             | The default state showing the email input form.  |
| `confirmation` | Successful form submission | Shown after the email is successfully submitted. |

#### Slots[​](#slots "Direct link to Slots")

| Slot           | Appears in     | Description                                                                                                                 |
| -------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `header`       | `email`        | Rendered above the email input. Use for a title or description. Hidden once the form transitions to the confirmation state. |
| `after-form`   | `email`        | Rendered below the email input and above the disclaimer. Use for supplementary inputs such as newsletter opt-in checkboxes. |
| `footer`       | `email`        | Rendered below the disclaimer. Use for supplementary links. Hidden once the form transitions to the confirmation state.     |
| `success`      | `confirmation` | Replaces the default confirmation state UI. When present, the default content is not rendered.                              |
| `confirmation` | `confirmation` | Same as `success`, kept for existing pages. If both are present, `success` is used.                                         |

```html
<allegro-email-form submit-text="Subscribe">
    <div slot="header">
        <h2>Get the morning newsletter</h2>
    </div>
    <label slot="after-form">
        <input type="checkbox" name="wants-weekly" value="yes" />
        Also send me the weekly roundup
    </label>
    <p slot="footer"><a href="/privacy">Privacy policy</a></p>
    <div slot="success">
        <h2>You're on the list</h2>
        <p>Check your inbox.</p>
    </div>
</allegro-email-form>

```

##### Submitting slotted inputs[​](#submitting-slotted-inputs "Direct link to Submitting slotted inputs")

Named `<input>`, `<select>`, and `<textarea>` elements inside the `header`, `after-form`, and `footer` slots are sent with the email as request data, keyed by `name`. A checkbox sends its `value` when checked (or `true` when it has no `value`) and `false` when unchecked. Inputs without a `name` are ignored. Slotted values are merged over any request data the form already sends, so a slotted input wins when the names match.

Slotted inputs are part of your page, not the component, so give each one its own label. The component does not validate them before submitting.

When the confirmation slot has a heading, focus moves to it after a successful submit; otherwise its text is announced to screen readers.

#### Shadow Parts[​](#shadow-parts "Direct link to Shadow Parts")

For styling beyond what the CSS variables make available, elements can be targeted directly with the CSS [`::part()`](https://developer.mozilla.org/en-US/docs/Web/CSS/::part) selector.

```css
allegro-email-form::part(email-field-input) {
    margin-bottom: 2rem;
}

```

| Part                    | Appears in     | Description                               |
| ----------------------- | -------------- | ----------------------------------------- |
| `email-form`            | `email`        | The email input + submit button `<form>`. |
| `email-field`           | `email`        | Wrapper around the email label and input. |
| `email-field-label`     | `email`        | The email input's `<label>` element.      |
| `email-field-input`     | `email`        | The email `<input>` element.              |
| `email-form-submit`     | `email`        | The submit button.                        |
| `disclaimer`            | `email`        | The disclaimer paragraph.                 |
| `confirmation`          | `confirmation` | Wrapper around the confirmation elements. |
| `confirmation-icon`     | `confirmation` | The confirmation icon.                    |
| `confirmation-heading`  | `confirmation` | The confirmation heading.                 |
| `confirmation-body`     | `confirmation` | The confirmation body text.               |
| `confirmation-continue` | `confirmation` | The continue button.                      |

#### Events[​](#events "Direct link to Events")

##### Dispatched[​](#dispatched "Direct link to Dispatched")

| Event                        | Bubbles | Detail                             | Description                                          |
| ---------------------------- | ------- | ---------------------------------- | ---------------------------------------------------- |
| `allegro:email-form:success` | yes     | `{ email: string }`                | Fired when the form is successfully submitted.       |
| `allegro:email-form:error`   | yes     | `{ email: string, error: string }` | Fired when there is an error during form submission. |

#### Tracked Events[​](#tracked-events "Direct link to Tracked Events")

The component records the following events via the Allegro SDK.

| Event                  | When                                      | Data     |
| ---------------------- | ----------------------------------------- | -------- |
| `email_form_submitted` | Fired after a successful form submission. | *(none)* |

#### CSS Variables[​](#css-variables "Direct link to CSS Variables")

All visual properties are exposed as CSS custom properties so the component can be themed from the host page without piercing the shadow DOM.

```css
allegro-email-form {
    --emailForm--button--background: #1a1a1a;
    --emailForm--input--border: 1px solid #ccc;
}

```

##### General[​](#general "Direct link to General")

| Variable                   | Default                 | Description                    |
| -------------------------- | ----------------------- | ------------------------------ |
| `--emailForm--font-family` | `system-ui, sans-serif` | Font family for the component. |

##### Form Layout[​](#form-layout "Direct link to Form Layout")

| Variable                     | Default      | Description                              |
| ---------------------------- | ------------ | ---------------------------------------- |
| `--emailForm--form--gap`     | `0.8rem`     | Gap between the field and submit button. |
| `--emailForm--label--margin` | `0 0 0.4rem` | Margin around the email field's label.   |

##### Input[​](#input "Direct link to Input")

| Variable                                 | Default             | Description                  |
| ---------------------------------------- | ------------------- | ---------------------------- |
| `--emailForm--input--background`         | `#fff`              | Input background color.      |
| `--emailForm--input--border`             | `1px solid #8c8c8c` | Input border.                |
| `--emailForm--input--border-radius`      | `0.375rem`          | Input border radius.         |
| `--emailForm--input--font-size`          | `1rem`              | Input font size.             |
| `--emailForm--input--padding`            | `0.75rem 1rem`      | Input padding.               |
| `--emailForm--input--focus-border-color` | `#555`              | Border color on input focus. |

##### Submit Button[​](#submit-button "Direct link to Submit Button")

| Variable                              | Default           | Description              |
| ------------------------------------- | ----------------- | ------------------------ |
| `--emailForm--button--background`     | `#000`            | Button background color. |
| `--emailForm--button--color`          | `#fff`            | Button text color.       |
| `--emailForm--button--border-radius`  | `0.375rem`        | Button border radius.    |
| `--emailForm--button--font-size`      | `0.875rem`        | Button font size.        |
| `--emailForm--button--font-weight`    | `700`             | Button font weight.      |
| `--emailForm--button--padding`        | `0.75rem 1.25rem` | Button padding.          |
| `--emailForm--button--text-transform` | `uppercase`       | Button text transform.   |

##### Error Message[​](#error-message "Direct link to Error Message")

| Variable                            | Default             | Description                     |
| ----------------------------------- | ------------------- | ------------------------------- |
| `--emailForm--error--background`    | `#fef2f2`           | Error background color.         |
| `--emailForm--error--border`        | `1px solid #fecaca` | Error border.                   |
| `--emailForm--error--accent-color`  | `#dc2626`           | Error left accent border color. |
| `--emailForm--error--border-radius` | `0.375rem`          | Error border radius.            |
| `--emailForm--error--color`         | `#b91c1c`           | Error text color.               |
| `--emailForm--error--icon-color`    | `currentColor`      | Error icon color.               |
| `--emailForm--error--padding`       | `0.625rem 0.875rem` | Error padding.                  |

##### Confirmation State[​](#confirmation-state "Direct link to Confirmation State")

| Variable                                  | Default     | Description                          |
| ----------------------------------------- | ----------- | ------------------------------------ |
| `--emailForm--state-icon--background`     | `#111`      | Confirmation icon circle background. |
| `--emailForm--state-heading--color`       | `#111`      | Confirmation heading color.          |
| `--emailForm--state-heading--font-size`   | `1.25rem`   | Confirmation heading font size.      |
| `--emailForm--state-heading--font-weight` | `700`       | Confirmation heading font weight.    |
| `--emailForm--state-body--color`          | `#555`      | Confirmation body text color.        |
| `--emailForm--state-body--font-size`      | `0.9375rem` | Confirmation body font size.         |

##### Disclaimer[​](#disclaimer "Direct link to Disclaimer")

| Variable                               | Default     | Description                                                      |
| -------------------------------------- | ----------- | ---------------------------------------------------------------- |
| `--emailForm--disclaimer--color`       | `#555`      | Disclaimer text color.                                           |
| `--emailForm--disclaimer--font-size`   | `0.8125rem` | Disclaimer text size.                                            |
| `--emailForm--disclaimer--link--color` | `inherit`   | Color of links inside the disclaimer HTML. Links are underlined. |

#### Example: Dark Background[​](#example-dark-background "Direct link to Example: Dark Background")

```css
allegro-email-form {
    --emailForm--input--background: #1a1a1a;
    --emailForm--input--border: 1px solid #444;
    --emailForm--input--focus-border-color: #888;
    --emailForm--button--background: #fff;
    --emailForm--button--color: #000;
    --emailForm--state-icon--background: #fff;
    --emailForm--state-heading--color: #fff;
    --emailForm--state-body--color: #aaa;
}

```


---

### Form

`<allegro-form>` renders a form composed in the Allegro admin (under **Forms**) from your organization's user attributes. The authenticated member's current values are prefilled, submissions are validated against each attribute's validation rules, and the member's profile is updated in place.

The component only renders for authenticated members. If no member is signed in, the element stays empty — pair it with [`<allegro-content-gate>`](/developer/components/content-gate.md) or [`<allegro-login-form>`](/developer/components/login-form.md) to prompt visitors to sign in first.

#### Usage[​](#usage "Direct link to Usage")

```html
<allegro-form slug="profile-basics"></allegro-form>

```

Customized, with a custom success state:

```html
<allegro-form slug="profile-basics" submit-text="Update profile">
    <div slot="success">
        <h2>All set!</h2>
        <p>Your profile has been updated.</p>
    </div>
</allegro-form>

```

#### Attributes[​](#attributes "Direct link to Attributes")

| Attribute         | Type      | Default                           | Description                                                                                                                                      |
| ----------------- | --------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `slug`            | `text`    | *(none)*                          | Slug of the form to render, as defined under **Forms**.                                                                                          |
| `submit-text`     | `text`    | *(the form's setting)*            | Overrides the submit button label set on the form in the admin. Without it, the form's own submit text is used, which itself defaults to `Save`. |
| `success-heading` | `text`    | `Thank you!`                      | Heading shown in the default success state.                                                                                                      |
| `success-text`    | `text`    | `Your responses have been saved.` | Body text shown in the default success state.                                                                                                    |
| `preview`         | `boolean` | `false`                           | Render a static sample form and success state for style previews instead of fetching a real form.                                                |
| `tracking-data`   | `text`    | *(none)*                          | JSON object of custom data merged into every tracked event.                                                                                      |

#### States[​](#states "Direct link to States")

| State     | Trigger                                     | Description                                                         |
| --------- | ------------------------------------------- | ------------------------------------------------------------------- |
| `form`    | Successful load for an authenticated member | The form's fields, prefilled with the member's current values.      |
| `success` | Successful submission                       | The `success` slot when provided, otherwise a default confirmation. |

Fields with display conditions show and hide live as the member fills out the form: a field configured to appear only when another field is checked, unchecked, has a value, or equals a specific value is re-evaluated on every change. Hidden fields are not submitted.

#### Slots[​](#slots "Direct link to Slots")

| Slot      | Appears in | Description                                           |
| --------- | ---------- | ----------------------------------------------------- |
| `success` | `success`  | Replaces the default confirmation after a submission. |

```html
<allegro-form slug="profile-basics">
    <div slot="success">
        <h2>Saved!</h2>
        <a href="/account">Back to your account</a>
    </div>
</allegro-form>

```

#### Shadow Parts[​](#shadow-parts "Direct link to Shadow Parts")

For styling beyond what the CSS variables make available, elements can be targeted directly with the CSS [`::part()`](https://developer.mozilla.org/en-US/docs/Web/CSS/::part) selector.

```css
allegro-form::part(submit) {
    margin-bottom: 2rem;
}

```

| Part           | Appears in | Description                                                                            |
| -------------- | ---------- | -------------------------------------------------------------------------------------- |
| `form`         | `form`     | The rendered `<form>` element.                                                         |
| `submit`       | `form`     | The submit button.                                                                     |
| `success`      | `success`  | Wrapper around the success elements. Not rendered when the `success` slot is provided. |
| `success-icon` | `success`  | The success icon.                                                                      |

#### Events[​](#events "Direct link to Events")

##### Dispatched[​](#dispatched "Direct link to Dispatched")

| Event                  | Bubbles | Detail                                              | Description                                                 |
| ---------------------- | ------- | --------------------------------------------------- | ----------------------------------------------------------- |
| `allegro:form:success` | Yes     | `{ slug: string; values: Record<string, unknown> }` | Fired after a successful submission.                        |
| `allegro:form:error`   | Yes     | `{ slug: string; error: string }`                   | Fired when a submission fails, including validation errors. |

Both events are `composed`, so they cross shadow DOM boundaries.

```js
document.addEventListener('allegro:form:success', (event) => {
    console.log('Form saved:', event.detail.slug, event.detail.values);
});

```

#### Tracked Events[​](#tracked-events "Direct link to Tracked Events")

The component records the following events via the Allegro SDK.

| Event            | When                          | Data                    |
| ---------------- | ----------------------------- | ----------------------- |
| `form_submitted` | After a successful submission | `{ form_slug: string }` |

#### Validation[​](#validation "Direct link to Validation")

Values are validated server-side on submission:

* Fields marked **required** in the form builder must be filled in (when visible).
* Each value must pass the attribute's type check and any validation rules configured on the attribute (length, regex, contains, email, numeric bounds).
* Error messages configured on the form field or on the attribute's validation rules are shown next to the failing field.

A `max_length` rule also sets a `maxlength` hint on the rendered input.

#### CSS Variables[​](#css-variables "Direct link to CSS Variables")

Style the form through CSS custom properties on the element.

```css
allegro-form {
    --form--button--background: #0f766e;
    --form--input--border-radius: 0;
}

```

Defaults written below as `u(n)` mean `n` times `--form--base-font-size`, the component's sizing unit: `u(0.5)` is half that unit, `u(1.25)` is one and a quarter. The unit defaults to the page's `rem`. If the host page sets a root `font-size` other than the usual 16px, pin it so the form sizes the same either way:

```css
allegro-form {
    --form--base-font-size: 16px;
}

```

##### Layout & Typography[​](#layout--typography "Direct link to Layout & Typography")

| Variable                 | Default                                              | Description                         |
| ------------------------ | ---------------------------------------------------- | ----------------------------------- |
| `--form--base-font-size` | `var(--allegro--font-size, 1rem)`                    | Base sizing unit for the component. |
| `--form--font-family`    | `var(--allegro--font-family, system-ui, sans-serif)` | Font family.                        |
| `--form--color`          | `var(--allegro--color-text, black)`                  | Text color.                         |
| `--form--gap`            | `u(1)`                                               | Vertical gap between fields.        |

##### Labels & Inputs[​](#labels--inputs "Direct link to Labels & Inputs")

| Variable                            | Default                                  | Description                      |
| ----------------------------------- | ---------------------------------------- | -------------------------------- |
| `--form--label--font-size`          | `u(0.875)`                               | Label font size.                 |
| `--form--label--font-weight`        | `600`                                    | Label font weight.               |
| `--form--required--color`           | `var(--allegro--color-error, #b91c1c)`   | Color of the required asterisk.  |
| `--form--input--background`         | `white`                                  | Input background.                |
| `--form--input--border`             | `1px solid #8c8c8c`                      | Input border.                    |
| `--form--input--border-radius`      | `var(--allegro--radius, u(0.375))`       | Input border radius.             |
| `--form--input--font-size`          | `u(1)`                                   | Input font size.                 |
| `--form--input--padding`            | `u(0.5) u(0.75)`                         | Input padding.                   |
| `--form--input--focus-border-color` | `var(--allegro--color-primary, #171717)` | Border color of a focused input. |
| `--form--checkbox--accent-color`    | `var(--allegro--color-primary, #171717)` | Checkbox accent color.           |
| `--form--tooltip--color`            | `#737373`                                | Tooltip text color.              |
| `--form--tooltip--font-size`        | `u(0.75)`                                | Tooltip font size.               |

##### Errors[​](#errors "Direct link to Errors")

| Variable                   | Default                                | Description              |
| -------------------------- | -------------------------------------- | ------------------------ |
| `--form--error--color`     | `var(--allegro--color-error, #b91c1c)` | Error message color.     |
| `--form--error--font-size` | `u(0.875)`                             | Error message font size. |

##### Button & Success State[​](#button--success-state "Direct link to Button & Success State")

| Variable                             | Default                                  | Description                     |
| ------------------------------------ | ---------------------------------------- | ------------------------------- |
| `--form--button--background`         | `var(--allegro--color-primary, #171717)` | Submit button background.       |
| `--form--button--color`              | `white`                                  | Submit button text color.       |
| `--form--button--border-radius`      | `var(--allegro--radius, u(0.375))`       | Submit button border radius.    |
| `--form--button--font-size`          | `u(1)`                                   | Submit button font size.        |
| `--form--button--padding`            | `u(0.5) u(1.25)`                         | Submit button padding.          |
| `--form--success--padding`           | `u(1.5) 0`                               | Default success state padding.  |
| `--form--success--icon-background`   | `var(--allegro--color-success, #16a34a)` | Success icon circle background. |
| `--form--success--heading-font-size` | `u(1.25)`                                | Success heading font size.      |
| `--form--success--body-color`        | `#525252`                                | Success body text color.        |
| `--form--success--body-font-size`    | `u(0.9375)`                              | Success body font size.         |

#### Example: Dark Background[​](#example-dark-background "Direct link to Example: Dark Background")

```css
.dark-section allegro-form {
    --form--color: #f5f5f5;
    --form--input--background: #262626;
    --form--input--border: 1px solid #404040;
    --form--tooltip--color: #a3a3a3;
    --form--button--background: #f5f5f5;
    --form--button--color: #171717;
}

```


---

### LoginForm

`<allegro-login-form>` is a web component that authenticates readers via a magic login link sent to their email, a six-digit one-time code, or via Google, Apple, or Facebook OAuth. The email-based method is chosen with the [`login-method`](#attributes) attribute — magic link by default. The email input and submit button always stack vertically; social login buttons sit side by side when the form is wide enough to give each at least 12.5rem, and stack otherwise.

Set `login-method="magic-link-otp"` to send a single email containing both a magic link and a six-digit code. The form has one submit button, just like the single-method layouts; submitting it emails the reader both options and shows the code-entry screen. Clicking the link in the email authenticates directly (the form polls for that in the background), or the reader can type the code instead — whichever they do first signs them in.

#### Usage[​](#usage "Direct link to Usage")

```html
<allegro-login-form></allegro-login-form>

```

Customise the text labels via HTML attributes:

```html
<allegro-login-form
    form-label-text="Your email"
    show-form-label="false"
    placeholder-text="Your email"
    button-text="Get my link"
    publisher-name="Example News"
    continue-text="Keep Reading"
    hide-third-party="true"
></allegro-login-form>

```

Send a magic link and a one-time code together from a single form:

```html
<allegro-login-form
    login-method="magic-link-otp"
    button-text="Sign in securely"
></allegro-login-form>

```

#### Attributes[​](#attributes "Direct link to Attributes")

| Attribute              | Type      | Default                                                | Description                                                                                                                                                                                                                               |
| ---------------------- | --------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `heading`              | `text`    | *(empty)*                                              | Heading shown above the email field in the `email` state. Style it with the `heading` part or the [heading variables](#heading).                                                                                                          |
| `description`          | `text`    | *(empty)*                                              | Short text shown under the heading in the `email` state.                                                                                                                                                                                  |
| `show-form-label`      | `boolean` | `true`                                                 | Whether to show the email field's label. When `false`, the label is still rendered for screen readers but visually hidden. If `placeholder-text` is empty, the label text is used as the placeholder so the field still has visible text. |
| `form-label-text`      | `text`    | `Email Address`                                        | Label text for the email input field.                                                                                                                                                                                                     |
| `placeholder-text`     | `text`    | `Enter your email`                                     | Placeholder shown inside the email input.                                                                                                                                                                                                 |
| `email`                | `text`    | *(empty)*                                              | Email address to prefill in the email input. The reader can still change it.                                                                                                                                                              |
| `button-text`          | `text`    | `Sign in`                                              | Label for the submit button in every login method. Defaults to `Continue` when `registration-form` is set.                                                                                                                                |
| `login-method`         | `select`  | `magic-link`                                           | Authentication method: `magic-link` (emails a login link), `otp` (emails a 6-digit code), or `magic-link-otp` (emails both a link and a code).                                                                                            |
| `registration-form`    | `text`    | *(empty)*                                              | Slug of a form whose fields a new reader fills in before their account is created. See [Registration fields](#registration-fields).                                                                                                       |
| `register-button-text` | `text`    | `Create account`                                       | Label for the submit button once registration fields are showing.                                                                                                                                                                         |
| `registration-text`    | `text`    | `Tell us a bit about yourself to create your account.` | Text shown above the registration fields and announced to screen readers when they appear. Set it to an empty value to hide it; screen readers still hear the default message.                                                            |
| `hide-third-party`     | `boolean` | `false`                                                | Set to `true` to hide all social login buttons (Google, Apple, Facebook).                                                                                                                                                                 |
| `publisher-name`       | `text`    | *(empty)*                                              | Publisher name shown in the success state, e.g. "Welcome back to Example News!"                                                                                                                                                           |
| `continue-text`        | `text`    | *(empty)*                                              | Override the continue button label in the success state.                                                                                                                                                                                  |
| `learn-more-url`       | `text`    | *(empty)*                                              | http or https URL to navigate to when the continue button is clicked in success state. Other URLs are ignored.                                                                                                                            |
| `show-last-used`       | `boolean` | `false`                                                | Set to `true` to show a "Last used" badge on the login method (social provider or email) the reader most recently used to sign in. Recorded per-browser in `localStorage`. See [Last used badge](#last-used-badge).                       |
| `tracking-data`        | `text`    | *(empty)*                                              | JSON object of custom data merged into every tracked event, e.g. `"{'campaign': 'header'}"`.                                                                                                                                              |

#### Captcha[​](#captcha "Direct link to Captcha")

When the organization — or the property serving the page — has a captcha provider configured in **Organization Settings › Access & Identity › Captcha**, this component loads it and verifies every sign-in request automatically. Your markup does not change: the provider's script is fetched on demand and the resulting token is attached to the request.

Google reCAPTCHA v3 is invisible, so readers are scored in the background and never see a challenge. Google appends its own floating badge to the page, which its [branding terms](https://developers.google.com/recaptcha/docs/faq#id-like-to-hide-the-recaptcha-badge-what-is-allowed) require you to keep or replace with the prescribed attribution text near your submit button.

There is no per-element opt-out. A form that could switch the check off from the page would let any caller do the same, so captcha is controlled entirely in organization settings. When no provider is configured, the component behaves exactly as it did before — no extra script, no extra request.

##### Failure modes worth handling[​](#failure-modes-worth-handling "Direct link to Failure modes worth handling")

A request whose token is missing or scores below the organization's threshold is rejected before any email is sent:

```json
{ "data": { "code": "CAPTCHA_FAILED", "message": "…" }, "status": 422 }

```

That surfaces through the SDK's usual `AllegroApiError` path, so an `allegro:login-form:error` listener sees it like any other failure. The component already renders the message inline; you only need to handle it if you have replaced the default error display.

If the provider itself is unreachable, the request is **allowed through** rather than rejected, so a Google outage cannot lock readers out.

A reader whose browser blocks Google's script is rejected, since a client able to skip the check by reporting failure would make it decorative. The script loader does not cache a failed load, so pressing the button again genuinely retries rather than replaying the failure.

##### Content Security Policy[​](#content-security-policy "Direct link to Content Security Policy")

Loading the provider adds a script origin. A publisher with a strict CSP needs:

```text
script-src https://www.google.com/recaptcha/ https://www.gstatic.com/recaptcha/;
frame-src  https://www.google.com/recaptcha/;

```

Without these the script is blocked silently and sign-in fails for every reader on that page while captcha is switched on.

note

Alpine-driven interactions already load from `https://cdn.jsdelivr.net`, which a strict `script-src` must also allow. That requirement predates captcha and is easy to miss when auditing a policy.

#### Last used badge[​](#last-used-badge "Direct link to Last used badge")

Set `show-last-used` to display a small "Last used" badge over the login method the reader most recently used, helping returning readers pick the same method again:

```html
<allegro-login-form show-last-used></allegro-login-form>

```

The last-used method is recorded in the browser's `localStorage` (key `allegro:login-form:last-used`) at the moment the reader initiates a login — clicking a social provider button or submitting the email form. Recording only happens when `show-last-used` is set, and the badge appears on the reader's next visit. Because it is stored per browser, the badge does not follow the reader across devices. If the last-used social provider is later disabled for the tenant, no badge is shown.

Style the badge with the `last-used-badge` shadow part and the `--loginForm--last-used--*` [CSS variables](#last-used-badge-1) listed below.

#### Registration fields[​](#registration-fields "Direct link to Registration fields")

Set `registration-form` to the slug of a form built under **Forms** to ask new readers a few questions, like their name, as part of creating their account.

```html
<allegro-login-form registration-form="signup"></allegro-login-form>

```

1. The reader enters their email and presses **Continue**. While the email is checked, a spinner shows inside the field.
2. If the email belongs to an existing account, the login email goes out as usual and nothing else changes.
3. If the email is new, **no email is sent yet**. The form's fields open below the email field, focus moves to the first one, and the button changes to **Create account**.
4. When the reader submits, the answers are validated against the form's rules. Errors show next to each field. Once the answers are valid, the account is created with them and the magic link or code is sent.

Changing the email while the fields are showing closes them, so the next press checks the new address.

Use `registration-text` to change the line above the fields, and the `registration-footer` slot for anything that should sit under the **Create account** button:

```html
<allegro-login-form
    registration-form="signup"
    registration-text="Just two quick questions and you're in."
>
    <p slot="registration-footer">
        By creating an account you agree to our
        <a href="https://acme.com/terms">terms</a>.
    </p>
</allegro-login-form>

```

Only fields backed by user-editable attributes appear. Sign-ins through Google, Apple, or Facebook skip the questions. To ask those readers too, place an [`<allegro-form>`](/developer/components/form.md) in the `success` slot.

note

If no form matches the slug, the component signs readers in without asking any questions.

#### States[​](#states "Direct link to States")

The component moves through several states as the chosen sign-in flow advances. `link-sent` appears for the magic-link method, and `code-entry` for the one-time-code method (`login-method="otp"`) and for the combined `login-method="magic-link-otp"` method — submitting the combined form always sends the single email and moves straight to `code-entry`, since the reader can either type the code there or click the link in the email. The `expired` state adapts its wording to match whichever method was last used.

| State        | Trigger                                                                                                                      | Description                                           |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `email`      | Initial render (unauthenticated, no token in URL)                                                                            | Email input + social login buttons.                   |
| `loading`    | Initial render when `allegro_token` is present in the URL, or while the SDK exchanges a social login's `allegro_social_code` | Spinner shown while the SDK validates the token.      |
| `link-sent`  | `allegro:login-form:magic-link:sent` fires (magic-link method)                                                               | "Check your email inbox" with a resend option.        |
| `code-entry` | A one-time code was requested successfully (`otp` or `magic-link-otp` method)                                                | Six code-input boxes where the reader types the code. |
| `success`    | Initial render (already authenticated), or a magic link / one-time code is validated successfully                            | Checkmark + "Welcome back" with a continue button.    |
| `expired`    | `allegro:magic-link:failed` fires, or an entered one-time code has expired or been locked                                    | "Your link has expired" with a send-new-link button.  |

If the user is already signed in when the component renders, it skips straight to the `success` state.

#### Events[​](#events "Direct link to Events")

##### Dispatched by this component[​](#dispatched-by-this-component "Direct link to Dispatched by this component")

| Name                                           | Bubbles | Detail                                                    | Description                                                                                                                                                                                                                                                |
| ---------------------------------------------- | ------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allegro:login-form:magic-link:sent`           | yes     | `{ email: string, data?: Record<string, unknown> }`       | Fired after a magic link is successfully sent. Triggers the `link-sent` state.                                                                                                                                                                             |
| `allegro:login-form:authenticated`             | yes     | *(none)*                                                  | Fired on every auth flow (magic link, one-time code, and social), before any flow-specific event. Also fired on its own when a magic-link or redirect social login finished before the form loaded.                                                        |
| `allegro:login-form:magic-link:authenticated`  | yes     | *(none)*                                                  | Fired after a magic link is validated successfully. Follows `allegro:login-form:authenticated`.                                                                                                                                                            |
| `allegro:login-form:third-party:authenticated` | yes     | `{ provider: string, session_id: string, token: string }` | Fired after a successful social login, through the popup or the [redirect flow](/developer/guides/authentication/social-login.md#mobile-and-in-app-browsers). Follows `allegro:login-form:authenticated`. `provider` is the provider name (e.g. `google`). |
| `allegro:login-form:continue`                  | yes     | *(none)*                                                  | Fired when the user clicks the continue button in the success state.                                                                                                                                                                                       |

##### Listened to by this component (on `window`)[​](#listened-to-by-this-component-on-window "Direct link to listened-to-by-this-component-on-window")

| Name                               | Detail                                                                      | Description                                                                                                        |
| ---------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `allegro:magic-link:authenticated` | *(none)*                                                                    | Dispatched by the SDK after a magic link is validated successfully. Transitions to the `success` state.            |
| `allegro:magic-link:failed`        | `{ error: string }`                                                         | Dispatched by the SDK when magic link validation fails (e.g. expired token). Transitions to the `expired` state.   |
| `allegro:social:authenticated`     | `{ provider: string, created: boolean, session_id: string, token: string }` | Dispatched by the SDK after a redirect-based social login signs the member in. Transitions to the `success` state. |
| `allegro:social:failed`            | `{ error: string }`                                                         | Dispatched by the SDK when a redirect-based social login fails or is canceled. Shows the email form with an error. |

#### Slots[​](#slots "Direct link to Slots")

| Slot name             | Appears in state | Description                                                                                                                                                                                                              |
| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `header`              | `email`          | Rendered above the email input. Use for a title or description. Hidden once the form transitions to another state.                                                                                                       |
| `footer`              | `email`          | Rendered below the email input (and social buttons when present). Use for supplementary links. Hidden once the form transitions to another state.                                                                        |
| `after-form`          | `email`          | Rendered between the email input and the social login buttons. Use for supplementary inputs such as newsletter opt-in checkboxes. Values from named inputs inside this slot are included in the magic link request data. |
| `registration-footer` | `email`          | Rendered directly below the **Create account** button, only while the registration fields show. Use for terms or privacy text. Values from named inputs inside this slot are included in the request data.               |
| `success`             | `success`        | Replaces the entire success state UI (icon, heading, body, and continue button). When omitted, the default success UI is shown as fallback content.                                                                      |
| `after-continue`      | `success`        | Rendered directly below the continue button in the default success UI. Ignored when the `success` slot is provided.                                                                                                      |

```html
<allegro-login-form publisher-name="Example News">
    <div slot="header">
        <h2>Sign in to continue</h2>
        <p>Access your account below.</p>
    </div>
    <p slot="footer">
        <a href="/register">Don't have an account? Sign up</a>
    </p>
</allegro-login-form>

```

To override the entire success state:

```html
<allegro-login-form publisher-name="Example News">
    <div slot="success">
        <h2>You're in!</h2>
        <p>Redirecting you now…</p>
    </div>
</allegro-login-form>

```

#### Shadow Parts[​](#shadow-parts "Direct link to Shadow Parts")

For styling beyond what the CSS variables make available, elements can be targeted directly with the CSS [`::part()`](https://developer.mozilla.org/en-US/docs/Web/CSS/::part) selector.

```css
allegro-login-form::part(email-field-input) {
    margin-bottom: 2rem;
}

```

| Part                      | Appears in state | Description                                                                                                 |
| ------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------- |
| `heading`                 | `email`          | The `<h2>` from the `heading` attribute. Only rendered when `heading` is set.                               |
| `description`             | `email`          | The text from the `description` attribute. Only rendered when `description` is set.                         |
| `email-form`              | `email`          | The email input + submit button `<form>`.                                                                   |
| `email-field`             | `email`          | Wrapper around the email label and input.                                                                   |
| `email-field-label`       | `email`          | The email input's `<label>` element.                                                                        |
| `email-field-input`       | `email`          | The email `<input>` element.                                                                                |
| `email-form-submit`       | `email`          | The email submit button.                                                                                    |
| `registration`            | `email`          | Wrapper around the registration fields. Only rendered for a new reader when `registration-form` is set.     |
| `registration-intro`      | `email`          | The line of text above the registration fields.                                                             |
| `social-divider`          | `email`          | The "OR" divider between the email form and social buttons.                                                 |
| `social-row`              | `email`          | Wrapper around the social provider buttons.                                                                 |
| `social-btn`              | `email`          | Every social provider button. Combined with a provider-specific part, e.g. `social-btn social-btn-google`.  |
| `last-used-badge`         | `email`          | The "Last used" badge. Only rendered when `show-last-used` is set. See [Last used badge](#last-used-badge). |
| `link-sent`               | `link-sent`      | Wrapper around the link-sent state UI.                                                                      |
| `link-sent-icon`          | `link-sent`      | The icon.                                                                                                   |
| `link-sent-heading`       | `link-sent`      | The heading.                                                                                                |
| `link-sent-body`          | `link-sent`      | The body text.                                                                                              |
| `link-sent-resend`        | `link-sent`      | The resend button.                                                                                          |
| `code-entry`              | `code-entry`     | Wrapper around the code-entry elements.                                                                     |
| `code-entry-icon`         | `code-entry`     | The icon.                                                                                                   |
| `code-entry-heading`      | `code-entry`     | The heading.                                                                                                |
| `code-entry-body`         | `code-entry`     | The body text.                                                                                              |
| `code-entry-input`        | `code-entry`     | The six-digit code input box.                                                                               |
| `code-entry-error`        | `code-entry`     | The error message under the code input.                                                                     |
| `code-entry-submit`       | `code-entry`     | The verify button.                                                                                          |
| `code-entry-resend`       | `code-entry`     | The resend button.                                                                                          |
| `success`                 | `success`        | Wrapper around the success elements. Not rendered when the `success` slot is provided.                      |
| `success-icon`            | `success`        | The icon.                                                                                                   |
| `success-heading`         | `success`        | The heading.                                                                                                |
| `success-body`            | `success`        | The body text.                                                                                              |
| `success-continue-button` | `success`        | The continue button.                                                                                        |
| `expired-heading`         | `expired`        | The heading.                                                                                                |
| `expired-body`            | `expired`        | The body text.                                                                                              |
| `expired-btn`             | `expired`        | The send-new-link / send-new-code button.                                                                   |

#### Tracked Events[​](#tracked-events "Direct link to Tracked Events")

The component records the following analytics events via the Allegro SDK.

| Event                  | When                                                                                          | Data                   |
| ---------------------- | --------------------------------------------------------------------------------------------- | ---------------------- |
| `magic_link_requested` | A magic link is requested — on the initial submit, or when resent from the `link-sent` state. | `{ created: boolean }` |
| `otp_requested`        | A one-time code is requested — on the initial submit, or when resent from a code-entry state. | `{ created: boolean }` |
| `otp_validated`        | A submitted one-time code is accepted and the device is authenticated.                        | *(none)*               |
| `login`                | Authentication completes through a social / SSO provider.                                     | `{ provider: string }` |

`created` is `true` when a new audience member was created for the email address, and `false` when an existing member was matched.

note

Magic link *validation* is tracked separately as `magic_link_validated` by the SDK when the link is opened, since that happens on the page the link points to rather than within the form.

#### CSS Variables[​](#css-variables "Direct link to CSS Variables")

All visual properties are exposed as CSS custom properties so the component can be themed from the host page without piercing the shadow DOM.

```css
allegro-login-form {
    --loginForm--input--background: #fff;
    --loginForm--submit--background: #1a1a1a;
}

```

##### General[​](#general "Direct link to General")

| Variable                      | Default                 | Description                                                                                          |
| ----------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------- |
| `--loginForm--base-font-size` | `1rem`                  | Base unit all internal sizing is derived from. Defaults to the document's `rem`. See the note below. |
| `--loginForm--color`          | `black`                 | Base text colour for the component.                                                                  |
| `--loginForm--font-family`    | `system-ui, sans-serif` | Font family applied to the entire component.                                                         |

Sizing on pages with a non-16px root

Internally the form scales every dimension — padding, font sizes, spacing — from `--loginForm--base-font-size`, which defaults to the page's `rem`. If the host page sets a root `font-size` other than the usual 16px (for example a 10px root), the form renders too small or too large. Pin the base to a fixed value so the form sizes consistently regardless of the host page:

```css
allegro-login-form {
    --loginForm--base-font-size: 16px;
}

```

##### Heading[​](#heading "Direct link to Heading")

Applies to the `heading` and `description` attributes.

| Variable                              | Default      | Description                                                  |
| ------------------------------------- | ------------ | ------------------------------------------------------------ |
| `--loginForm--heading--color`         | *(inherits)* | Heading text color. Follows `--loginForm--color` by default. |
| `--loginForm--heading--font-family`   | *(inherits)* | Heading font family.                                         |
| `--loginForm--heading--font-size`     | `1.5rem`     | Heading font size.                                           |
| `--loginForm--heading--font-weight`   | `700`        | Heading font weight.                                         |
| `--loginForm--heading--line-height`   | `1.2`        | Heading line height.                                         |
| `--loginForm--description--color`     | `#555`       | Description text color.                                      |
| `--loginForm--description--font-size` | `1rem`       | Description font size.                                       |

##### Form Layout[​](#form-layout "Direct link to Form Layout")

| Variable                     | Default      | Description                              |
| ---------------------------- | ------------ | ---------------------------------------- |
| `--loginForm--form--gap`     | `0.8rem`     | Gap between the field and submit button. |
| `--loginForm--label--margin` | `0 0 0.4rem` | Margin around the email field's label.   |

##### Input[​](#input "Direct link to Input")

| Variable                                 | Default             | Description                              |
| ---------------------------------------- | ------------------- | ---------------------------------------- |
| `--loginForm--input--background`         | `#fff`              | Input background colour.                 |
| `--loginForm--input--border`             | `1px solid #8c8c8c` | Input border shorthand.                  |
| `--loginForm--input--border-radius`      | `0.375rem`          | Corner radius applied to the input.      |
| `--loginForm--input--font-size`          | `1rem`              | Input text size.                         |
| `--loginForm--input--padding`            | `0.75rem 1rem`      | Input padding shorthand.                 |
| `--loginForm--input--focus-border-color` | `#555`              | Border colour when the input is focused. |

##### Submit button[​](#submit-button "Direct link to Submit button")

| Variable                              | Default           | Description                                                   |
| ------------------------------------- | ----------------- | ------------------------------------------------------------- |
| `--loginForm--submit--background`     | `#000`            | Button background colour.                                     |
| `--loginForm--submit--color`          | `#fff`            | Button text colour.                                           |
| `--loginForm--submit--border-radius`  | `0.375rem`        | Corner radius applied to the button.                          |
| `--loginForm--submit--font-size`      | `0.875rem`        | Button text size.                                             |
| `--loginForm--submit--font-weight`    | `700`             | Button font weight.                                           |
| `--loginForm--submit--letter-spacing` | `0`               | Button letter spacing.                                        |
| `--loginForm--submit--font-family`    | `inherit`         | Button font family. Inherits the surrounding font by default. |
| `--loginForm--submit--padding`        | `0.75rem 1.25rem` | Button padding shorthand.                                     |
| `--loginForm--submit--text-transform` | `uppercase`       | CSS `text-transform` applied to button label.                 |

##### Registration fields[​](#registration-fields-1 "Direct link to Registration fields")

The registration fields use the same `--loginForm--input--*` variables as the email input.

| Variable                                     | Default    | Description                                                             |
| -------------------------------------------- | ---------- | ----------------------------------------------------------------------- |
| `--loginForm--status--color`                 | `#000`     | Color of the spinner inside the email field while the email is checked. |
| `--loginForm--status--success-color`         | `#15803d`  | Color of the check mark shown when the email is new.                    |
| `--loginForm--registration-intro--color`     | `#555`     | Color of the line of text above the registration fields.                |
| `--loginForm--registration-intro--font-size` | `0.875rem` | Size of the line of text above the registration fields.                 |
| `--loginForm--label--font-size`              | `inherit`  | Size of each registration field's label.                                |
| `--loginForm--label--font-weight`            | `inherit`  | Weight of each registration field's label.                              |
| `--loginForm--required--color`               | `#b91c1c`  | Color of the required-field asterisk.                                   |
| `--loginForm--checkbox--accent-color`        | `#171717`  | Accent color of checkbox fields.                                        |
| `--loginForm--tooltip--color`                | `#737373`  | Color of a field's hint text.                                           |
| `--loginForm--tooltip--font-size`            | `0.75rem`  | Size of a field's hint text.                                            |
| `--loginForm--error--font-size`              | `0.875rem` | Size of a field's error message.                                        |

##### Divider[​](#divider "Direct link to Divider")

| Variable                           | Default        | Description                                  |
| ---------------------------------- | -------------- | -------------------------------------------- |
| `--loginForm--divider--color`      | `#333`         | Text and line colour for the "OR" divider.   |
| `--loginForm--divider--line-color` | `currentColor` | Override only the line colour independently. |
| `--loginForm--divider--margin`     | `1rem 0`       | Vertical spacing around the divider.         |

##### Social buttons[​](#social-buttons "Direct link to Social buttons")

| Variable                                | Default             | Description                                                                                      |
| --------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------ |
| `--loginForm--social--background`       | `#fff`              | Social button background colour.                                                                 |
| `--loginForm--social--hover-background` | `#f9fafb`           | Social button background on hover.                                                               |
| `--loginForm--social--border`           | `1px solid #d1d5db` | Social button border shorthand.                                                                  |
| `--loginForm--social--border-radius`    | `0.5rem`            | Social button corner radius.                                                                     |
| `--loginForm--social--color`            | `#111`              | Social button text colour.                                                                       |
| `--loginForm--social--font-family`      | `inherit`           | Social button font family. Inherits the surrounding font by default.                             |
| `--loginForm--social--font-size`        | `1rem`              | Social button text size. When unset, labels shrink to fit narrow buttons (down to 0.75rem).      |
| `--loginForm--social--line-height`      | `1.25`              | Social button line height.                                                                       |
| `--loginForm--social--height`           | `42px`              | Minimum button height when the buttons are stacked.                                              |
| `--loginForm--social--height-desktop`   | `48px`              | Minimum button height when the buttons sit side by side.                                         |
| `--loginForm--social--padding`          | `0.5rem 1rem`       | Social button padding shorthand. Defaults to `0.5rem 0.75rem` when the buttons sit side by side. |
| `--loginForm--social--gap`              | `0.5rem`            | Gap between social buttons when stacked; same value applies in the side-by-side layout.          |

##### Last used badge[​](#last-used-badge-1 "Direct link to Last used badge")

Only rendered when the `show-last-used` attribute is set. Also exposed as the `last-used-badge` shadow `part` for full style overrides.

| Variable                                | Default                         | Description                                                  |
| --------------------------------------- | ------------------------------- | ------------------------------------------------------------ |
| `--loginForm--last-used--background`    | `#dbeafe`                       | Badge background colour.                                     |
| `--loginForm--last-used--color`         | `#1e40af`                       | Badge text colour.                                           |
| `--loginForm--last-used--border`        | `1px solid #bfdbfe`             | Badge border shorthand.                                      |
| `--loginForm--last-used--shadow`        | `0 1px 2px rgba(0, 0, 0, 0.15)` | Badge drop shadow (`box-shadow`).                            |
| `--loginForm--last-used--border-radius` | `999px`                         | Badge corner radius.                                         |
| `--loginForm--last-used--font-family`   | `inherit`                       | Badge font family.                                           |
| `--loginForm--last-used--font-size`     | `0.6875rem`                     | Badge text size.                                             |
| `--loginForm--last-used--font-weight`   | `500`                           | Badge font weight.                                           |
| `--loginForm--last-used--padding`       | `0.125rem 0.5rem`               | Badge padding shorthand.                                     |
| `--loginForm--last-used--offset-x`      | `-0.5rem`                       | Horizontal offset of the badge from the button's right edge. |
| `--loginForm--last-used--offset-y`      | `-0.5rem`                       | Vertical offset of the badge from the button's top edge.     |

##### Loading spinner[​](#loading-spinner "Direct link to Loading spinner")

| Variable                            | Default        | Description                                                    |
| ----------------------------------- | -------------- | -------------------------------------------------------------- |
| `--loginForm--loading--track-color` | `currentColor` | Spinner colour. Inherits the component text colour by default. |

##### State screens (link-sent, success, expired)[​](#state-screens-link-sent-success-expired "Direct link to State screens (link-sent, success, expired)")

| Variable                                  | Default     | Description                                                                   |
| ----------------------------------------- | ----------- | ----------------------------------------------------------------------------- |
| `--loginForm--state-icon--background`     | `#111`      | Background colour of the circular state icon.                                 |
| `--loginForm--state-heading--color`       | `#111`      | Heading text colour.                                                          |
| `--loginForm--state-heading--font-size`   | `1.25rem`   | Heading font size.                                                            |
| `--loginForm--state-heading--font-weight` | `700`       | Heading font weight.                                                          |
| `--loginForm--state-body--color`          | `#555`      | Body and disclaimer text colour.                                              |
| `--loginForm--state-body--font-size`      | `0.9375rem` | Body text size.                                                               |
| `--loginForm--resend--color`              | `#555`      | Resend link text colour.                                                      |
| `--loginForm--resend--hover-color`        | `#111`      | Resend link text colour on hover.                                             |
| `--loginForm--resend--font-size`          | `0.875rem`  | Resend link font size.                                                        |
| `--loginForm--resend-error--color`        | `#b91c1c`   | Text colour for the inline error shown below the resend/send-new-link button. |

##### Error message[​](#error-message "Direct link to Error message")

| Variable                            | Default             | Description                                          |
| ----------------------------------- | ------------------- | ---------------------------------------------------- |
| `--loginForm--error--background`    | `#fef2f2`           | Error container background colour.                   |
| `--loginForm--error--border`        | `1px solid #fecaca` | Error container border shorthand.                    |
| `--loginForm--error--accent-color`  | `#dc2626`           | Left accent border colour.                           |
| `--loginForm--error--border-radius` | `0.375rem`          | Error container corner radius.                       |
| `--loginForm--error--color`         | `#b91c1c`           | Error message text colour.                           |
| `--loginForm--error--icon-color`    | `currentColor`      | Error icon colour (inherits text colour by default). |
| `--loginForm--error--padding`       | `0.625rem 0.875rem` | Error container padding.                             |

#### Example: Dark Background[​](#example-dark-background "Direct link to Example: Dark Background")

When placing the component on a dark or coloured background, override the divider and social button colours so they read clearly:

```css
allegro-login-form {
    --loginForm--divider--color: rgba(255, 255, 255, 0.7);
    --loginForm--social--background: transparent;
    --loginForm--social--border: 1px solid rgba(255, 255, 255, 0.4);
    --loginForm--social--color: #fff;
    --loginForm--social--hover-background: rgba(255, 255, 255, 0.08);
}

```


---

### Modal

`<allegro-modal>` is a centered dialog over the whole page, with a backdrop. Use it for a welcome note, an announcement or a short prompt that the reader reads and then closes. A Modal is always dismissible. To block reading until the reader signs up, use a [Content Gate](/developer/components/content-gate.md) instead.

The Modal opens as soon as it renders. It has no delay, trigger or frequency options: the [interaction](/developer/guides/interactions.md) that places it decides whether and when it shows. Once the reader dismisses it, it stays closed for the rest of the visit (see [Remembering a dismiss](#remembering-a-dismiss)). While it is open, the rest of the page is inert, focus stays inside the dialog, and page scroll is locked.

#### Usage[​](#usage "Direct link to Usage")

```html
<allegro-modal>
    <h2>Welcome to Acme News</h2>
    <p>Here is what is new this week.</p>
    <button type="button" data-allegro-close>Get started</button>
</allegro-modal>

```

A large Modal holding a form, so a stray backdrop click does not close it:

```html
<allegro-modal size="large" close-on-backdrop="false">
    <h2 data-allegro-title>Get our weekly newsletter</h2>
    <p>The best of our reporting, every Friday.</p>
    <allegro-email-form></allegro-email-form>
</allegro-modal>

```

The component does not lay out its content. Style the slotted markup in the template's CSS field.

##### Accessibility[​](#accessibility "Direct link to Accessibility")

The Modal names itself from the first of these that exists:

1. The `label` attribute.
2. An element in its content marked `data-allegro-title`.
3. The first `h1`–`h6` in its content.

The close button is named "Close". Mark decorative elements `aria-hidden="true"`.

On open, focus moves to the first focusable element in the content, or to the close button when there is none. Add `autofocus` to any element to focus it instead, including a heading with `tabindex="-1"`. On close, focus returns to the element that had it before the Modal opened.

##### Closing[​](#closing "Direct link to Closing")

Every close records a `method`, which says how the Modal was closed. It is sent with the `dismiss_modal` event and the `allegro:modal:closed` event.

| Method         | Cause                                                                                         |
| -------------- | --------------------------------------------------------------------------------------------- |
| `escape`       | The reader presses Escape.                                                                    |
| `close-button` | The reader clicks the built-in close button.                                                  |
| `backdrop`     | The reader clicks the backdrop, unless `close-on-backdrop="false"`.                           |
| `action`       | A click on or inside a `data-allegro-close` element, or a slotted form's **Continue** button. |
| `api`          | `close()` or the `allegro:modal:close` event.                                                 |

A `data-allegro-close` link closes the Modal and is then followed as normal. The Modal does not close when the reader logs in.

```js
// From site code or an Alpine template.
document.querySelector('allegro-modal').close();

```

##### Remembering a dismiss[​](#remembering-a-dismiss "Direct link to Remembering a dismiss")

When an interaction places the Modal, a dismiss is remembered until the browser closes. On later pages in the same visit, the Modal doesn't open, so it doesn't lock scroll or track `view_modal`. Every close method counts.

* Each interaction is remembered separately, by its slug. Dismissing one interaction's Modal does not hide another's.
* The state is kept in a session cookie named `allegro_modal_{slug}`, shared across tabs and set on your organization's cookie domain when it has one.
* A Modal that your site's code or theme renders directly, rather than through an interaction, has no slug and remembers nothing.

To see a dismissed Modal again while testing, close the browser or delete its cookie.

note

The interaction still runs on later pages, so its frequency caps still count those deliveries even though the Modal does not show.

#### Attributes[​](#attributes "Direct link to Attributes")

| Attribute           | Type      | Default   | Description                                                                                                                                     |
| ------------------- | --------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `size`              | `text`    | `medium`  | The dialog's maximum width: `small` (`u(28)`), `medium` (`u(36)`), `large` (`u(52)`) or `full`. See [CSS Variables](#css-variables) for `u(n)`. |
| `position`          | `text`    | `center`  | Where the dialog sits: `center`, or `top`, which places it near the top of the screen with `--modal--top-offset` of space above it.             |
| `close-on-backdrop` | `boolean` | `true`    | Close the Modal when the reader clicks the backdrop. Turn off for Modals that hold a form.                                                      |
| `label`             | `text`    | *(empty)* | Accessible name. Overrides the title element and the first heading.                                                                             |
| `tracking-data`     | `text`    | *(empty)* | JSON object of custom data merged into every tracked event, e.g. `"{'campaign': 'welcome'}"`.                                                   |

#### Events[​](#events "Direct link to Events")

##### Dispatched[​](#dispatched "Direct link to Dispatched")

| Event                  | Bubbles | Detail               | Description                                        |
| ---------------------- | ------- | -------------------- | -------------------------------------------------- |
| `allegro:modal:open`   | yes     | *(none)*             | Fired on the element once the Modal opens.         |
| `allegro:modal:closed` | no      | `{ method: string }` | Fired on `window` once the Modal has been removed. |

##### Listened to[​](#listened-to "Direct link to Listened to")

| Event                         | Detail   | Description                                                  |
| ----------------------------- | -------- | ------------------------------------------------------------ |
| `allegro:modal:close`         | *(none)* | Dispatch on the element, or from inside it, to close it.     |
| `allegro:content-gate:close`  | *(none)* | A slotted Email Form's **Continue** button closes the Modal. |
| `allegro:login-form:continue` | *(none)* | A slotted Login Form's **Continue** button closes the Modal. |

```js
document
    .querySelector('allegro-modal')
    .dispatchEvent(new CustomEvent('allegro:modal:close'));

window.addEventListener('allegro:modal:closed', (event) => {
    console.log('Modal closed:', event.detail.method);
});

```

#### Tracked Events[​](#tracked-events "Direct link to Tracked Events")

The component records the following events via the Allegro SDK.

| Event           | When                  | Data                               |
| --------------- | --------------------- | ---------------------------------- |
| `view_modal`    | Fired when it opens.  | `{ size: string }`                 |
| `dismiss_modal` | Fired when it closes. | `{ size: string, method: string }` |

#### CSS Variables[​](#css-variables "Direct link to CSS Variables")

Set the variables in the template's CSS field. Most can also be set for your whole organization in [Branding](/product/administration/branding.md).

```css
allegro-modal {
    --modal--background: #fffaf0;
    --modal--max-width: 40rem;
}

```

Don't set them with a `style` attribute on the element. Components accept only their own attributes and log an error for `style`, `class` and `id`.

Defaults written below as `u(n)` mean `n` times `--modal--base-font-size`, the component's sizing unit: `u(0.5)` is half that unit, `u(2.5)` is two and a half. The unit defaults to `--allegro--font-size`, then the page's `rem`. If the host page sets a root `font-size` other than the usual 16px, pin it so the Modal sizes the same either way:

```css
allegro-modal {
    --modal--base-font-size: 16px;
}

```

##### Dialog[​](#dialog "Direct link to Dialog")

| Variable                       | Default                           | Description                                                                                                                    |
| ------------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `--modal--base-font-size`      | `var(--allegro--font-size, 1rem)` | Base sizing unit for the component.                                                                                            |
| `--modal--max-width`           | *(from `size`)*                   | An exact dialog width. Overrides `size`. Not a Branding variable.                                                              |
| `--modal--background`          | `#fff`                            | Dialog background. Falls back to `--allegro--color-background`.                                                                |
| `--modal--color`               | `#000`                            | Dialog text color. Falls back to `--allegro--color-text`.                                                                      |
| `--modal--font-family`         | *(none)*                          | Dialog font family. Falls back to `--allegro--font-family`.                                                                    |
| `--modal--padding`             | `u(2)`                            | Padding around the content. Content can sit under the close button; pad your own markup to keep it clear.                      |
| `--modal--border-radius`       | `u(0.375)`                        | Dialog corner radius. Falls back to `--allegro--radius`.                                                                       |
| `--modal--max-height`          | `100%`                            | Maximum dialog height. The default is the screen height less `u(1)` above and below. Taller content scrolls inside the dialog. |
| `--modal--top-offset`          | `u(4)`                            | Space above the dialog when `position` is `top`.                                                                               |
| `--modal--transition-duration` | `0.25s`                           | Length of the open and close animation. Capped at `0.15s` under reduced motion.                                                |

##### Overlay[​](#overlay "Direct link to Overlay")

| Variable                       | Default            | Description     |
| ------------------------------ | ------------------ | --------------- |
| `--modal--overlay--background` | `rgb(0 0 0 / 0.6)` | Backdrop color. |

##### Close button[​](#close-button "Direct link to Close button")

| Variable                | Default        | Description       |
| ----------------------- | -------------- | ----------------- |
| `--modal--close--size`  | `u(2.5)`       | Width and height. |
| `--modal--close--color` | `currentColor` | Icon color.       |

##### Buttons in your content[​](#buttons-in-your-content "Direct link to Buttons in your content")

The Modal does not style your buttons. It resolves a button color for you to use in the template's CSS, from `--modal--button--background` and `--modal--button--color`, then the global button tokens.

| Variable                      | Default | Description                                                                   |
| ----------------------------- | ------- | ----------------------------------------------------------------------------- |
| `--modal--button--background` | `#000`  | Set in Branding. Read it as `var(--modal-button-background)` in template CSS. |
| `--modal--button--color`      | `#fff`  | Set in Branding. Read it as `var(--modal-button-color)` in template CSS.      |

```css
.welcome-button {
    background: var(--modal-button-background);
    color: var(--modal-button-color);
}

```

##### Parts[​](#parts "Direct link to Parts")

Style the component's own elements with `::part()`.

| Part       | Element                                 |
| ---------- | --------------------------------------- |
| `dialog`   | The visible dialog box.                 |
| `backdrop` | The backdrop behind it.                 |
| `close`    | The close button.                       |
| `body`     | The scrolling area around your content. |

##### Motion[​](#motion "Direct link to Motion")

The dialog fades in and scales up slightly, and the backdrop fades in. Both reverse on close. When the reader has asked for reduced motion, the Modal only fades. Browsers without `@starting-style` show it without animation.

#### Example: Dark announcement[​](#example-dark-announcement "Direct link to Example: Dark announcement")

```css
allegro-modal {
    --modal--background: #111827;
    --modal--color: #f9fafb;
    --modal--overlay--background: rgb(17 24 39 / 0.8);
    --modal--border-radius: 1rem;
}

allegro-modal::part(dialog) {
    box-shadow: none;
}

```


---

### Recommendations

`<allegro-recommendations>` is a web component that fetches ranked article recommendations for the current reader via [`allegro.recommendations`](/developer/guides/recommendations.md) and renders them as a "Read Next" or "More Like This" list, reporting clicks automatically. The common case needs no JavaScript from the publisher — just place the tag.

When no recommendations are available — no engine configured for the tenant, the engine unreachable, or the SDK call fails — the component renders nothing at all rather than an empty container.

#### Usage[​](#usage "Direct link to Usage")

```html
<allegro-recommendations></allegro-recommendations>

```

With custom attributes:

```html
<allegro-recommendations
    limit="4"
    heading="Read Next"
    layout="grid"
></allegro-recommendations>

```

#### Attributes[​](#attributes "Direct link to Attributes")

| Attribute          | Type      | Default   | Description                                                                                                            |
| ------------------ | --------- | --------- | ---------------------------------------------------------------------------------------------------------------------- |
| `limit`            | `number`  | *(empty)* | How many articles to request. Defaults to 6 upstream; 24 is the maximum.                                               |
| `max-age-days`     | `number`  | *(empty)* | Excludes articles published more than this many days ago. Defaults to no cap.                                          |
| `path`             | `text`    | *(empty)* | Article to anchor the recommendations on. Defaults to the current page path.                                           |
| `heading`          | `text`    | *(empty)* | Heading shown above the list. When omitted, no heading is rendered.                                                    |
| `layout`           | `select`  | `list`    | Layout for the rendered items: `list` or `grid`.                                                                       |
| `show-placeholder` | `boolean` | `true`    | Whether to reserve space with placeholder rows while loading. Set to `false` to render nothing until the items arrive. |
| `tracking-data`    | `text`    | *(empty)* | JSON object of custom data merged into every tracked event, e.g. `"{'campaign': 'sidebar'}"`.                          |

#### Loading Placeholder[​](#loading-placeholder "Direct link to Loading Placeholder")

While the request is in flight the component renders a grid of gray placeholder rows matching the requested `limit` and `layout`, and carries `aria-busy="true"` until the request settles. This reserves the space the items will occupy so the surrounding page does not shift when they arrive.

```html
<allegro-recommendations show-placeholder="false"></allegro-recommendations>

```

Set `show-placeholder="false"` for placements where an empty gap is preferable to a visible skeleton — a sidebar that should collapse when the engine returns nothing, for instance. The component then stays empty until the items render.

#### Click Attribution[​](#click-attribution "Direct link to Click Attribution")

Each rendered item's link click calls [`allegro.recommendations.trackClick(item)`](/developer/guides/recommendations.md#click-attribution) with the exact item object the component rendered from, so attribution is resolved by identity rather than by path matching.

#### Shadow Parts[​](#shadow-parts "Direct link to Shadow Parts")

For styling beyond what the CSS variables make available, elements can be targeted directly with the CSS [`::part()`](https://developer.mozilla.org/en-US/docs/Web/CSS/::part) selector.

```css
allegro-recommendations::part(item-title) {
    text-transform: uppercase;
}

```

| Part         | Description                                         |
| ------------ | --------------------------------------------------- |
| `wrapper`    | Wrapper around the heading and item list.           |
| `heading`    | The heading element, when `heading` is set.         |
| `items`      | The `<ul>` of rendered items.                       |
| `item`       | Each `<li>` item wrapper.                           |
| `item-link`  | Each item's `<a>` element.                          |
| `item-image` | Each item's `<img>` element, when the item has one. |
| `item-title` | Each item's title text.                             |

#### CSS Variables[​](#css-variables "Direct link to CSS Variables")

All visual properties are exposed as CSS custom properties so the component can be themed from the host page without piercing the shadow DOM.

```css
allegro-recommendations {
    --recommendations--grid--columns: 4;
    --recommendations--item-title--font-weight: 700;
}

```

| Variable                                       | Default                 | Description                                                                                                                          |
| ---------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `--recommendations--font-family`               | `system-ui, sans-serif` | Font family for the component.                                                                                                       |
| `--recommendations--heading--color`            | `#111`                  | Heading text color.                                                                                                                  |
| `--recommendations--heading--font-size`        | `1.125rem`              | Heading font size.                                                                                                                   |
| `--recommendations--heading--font-weight`      | `700`                   | Heading font weight.                                                                                                                 |
| `--recommendations--items--gap`                | `1rem`                  | Gap between rendered items.                                                                                                          |
| `--recommendations--grid--columns`             | `3`                     | Number of columns in `grid` layout.                                                                                                  |
| `--recommendations--grid--columns-mobile`      | `1`                     | Number of columns in `grid` layout below 40em.                                                                                       |
| `--recommendations--item-image--aspect-ratio`  | `16 / 9`                | Aspect ratio of each item image in `grid` layout, so every image is cropped to a uniform height regardless of its source dimensions. |
| `--recommendations--item-image--border-radius` | `0.375rem`              | Item image border radius.                                                                                                            |
| `--recommendations--item-image--list-size`     | `4.5rem`                | Item image size in `list` layout.                                                                                                    |
| `--recommendations--item-title--color`         | `#111`                  | Item title text color.                                                                                                               |
| `--recommendations--item-title--font-size`     | `0.9375rem`             | Item title font size.                                                                                                                |
| `--recommendations--item-title--font-weight`   | `600`                   | Item title font weight.                                                                                                              |

#### Related[​](#related "Direct link to Related")

* [Recommendations guide](/developer/guides/recommendations.md) — How ranking works, the `allegro.recommendations` API, and click attribution details.


---

### Quick Start

This guide walks you through adding the Allegro SDK to your site and sending your first custom event.

#### 1. Add the Script Tag[​](#1-add-the-script-tag "Direct link to 1. Add the Script Tag")

Add the Allegro loader to the `<head>` or before `</body>` of your HTML:

```html
<script src="https://your-allegro-instance.com/client.js"></script>

```

Replace `your-allegro-instance.com` with your actual Allegro domain.

#### 2. Track a Custom Event[​](#2-track-a-custom-event "Direct link to 2. Track a Custom Event")

Page views are tracked automatically. To track a custom event, initialize the queue and push a callback:

```html
<script>
    window.allegro = window.allegro || [];

    window.allegro.push(function (allegro) {
        allegro.track('article_share', { method: 'email' });
    });
</script>

```

#### 3. Setup Page Metadata[​](#3-setup-page-metadata "Direct link to 3. Setup Page Metadata")

The SDK automatically collects page metadata from `application/ld+json` structured data on the page. Add a JSON-LD block to your `<head>`:

```html
<script type="application/ld+json">
    {
        "@context": "https://schema.org",
        "@type": "NewsArticle",
        "headline": "City Council Approves New Housing Plan",
        "identifier": "story-12345",
        "publisher": {
            "@type": "Organization",
            "name": "Example News"
        },
        "articleSection": "Local Government"
    }
</script>

```

The SDK maps these fields to its own automatically. You can also source metadata from `<meta>` tags, a GTM data layer, or CSS selectors — see the [Page Metadata guide](/developer/guides/page-metadata.md) for all field mappings and source types.

Or pass metadata explicitly to `track()`:

```js
allegro.track('page_view', {
    content_id: 'story-12345',
    content_type: 'NewsArticle',
    publisher: 'Example News',
});

```

#### Complete Example[​](#complete-example "Direct link to Complete Example")

```html
<!DOCTYPE html>
<html>
    <head>
        <script type="application/ld+json">
            {
                "@context": "https://schema.org",
                "@type": "NewsArticle",
                "headline": "City Council Approves New Housing Plan",
                "identifier": "story-12345",
                "publisher": {
                    "@type": "Organization",
                    "name": "Example News"
                },
                "articleSection": "Local Government"
            }
        </script>
    </head>
    <body>
        <script>
            window.allegro = window.allegro || [];

            // Track a custom event (queued until SDK loads)
            window.allegro.push(function (allegro) {
                allegro.track('article_share', { method: 'email' });
            });
        </script>

        <script src="https://your-allegro-instance.com/client.js"></script>
    </body>
</html>

```

#### Next Steps[​](#next-steps "Direct link to Next Steps")

* [Event Tracking guide](/developer/guides/event-tracking.md) — all `track()` options and page data collection
* [Member Authentication guide](/developer/guides/authentication.md) — authenticate readers with the SDK
* [Web Components](/developer/components/login-form.md) — drop-in UI components for login and email capture


---

### Alpine State Reference

The Allegro SDK registers two Alpine primitives that every template has access to:

* **`$store.allegro`** — a shared, reactive store that holds the current session state. It is automatically kept in sync whenever the member logs in, logs out, or their JWT refreshes.
* **`allegroInteraction(slug, data)`** — a reusable component factory registered on the root container of every rendered template. It exposes the interaction's slug, any extra data passed by the trigger call, and reactive shortcut getters into `$store.allegro`.

Because both primitives use Alpine's reactivity system, any `x-text`, `x-show`, or `x-if` bound to session fields re-renders automatically — no page reload, no manual event listeners required.

#### `$store.allegro`[​](#storeallegro "Direct link to storeallegro")

| Field             | Type                                                       | Description                                                                                                                                                                                      |
| ----------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `session`         | `{ id: string; authenticated_at: string \| null } \| null` | The member's current session, or `null` if no session exists.                                                                                                                                    |
| `audienceMember`  | `AudienceMember \| null`                                   | The authenticated member's profile, or `null` if the member has not logged in.                                                                                                                   |
| `isAuthenticated` | `boolean`                                                  | `true` when the session has been fully authenticated (not just identified by email).                                                                                                             |
| `products`        | `string[]`                                                 | Slugs of the products the member currently holds active entitlements for. Empty array when unauthenticated.                                                                                      |
| `userAttributes`  | `Record<string, unknown>`                                  | The member's [user attribute](/developer/guides/user-attributes.md#reading-values-at-page-load) values keyed by slug, from the SDK's cache. Empty object when unauthenticated or not yet cached. |

`AudienceMember` is defined in the [SDK type reference](/developer/api-reference/type-aliases/AudienceMember.md).

The store also exposes a helper method:

| Method                     | Returns   | Description                                                                          |
| -------------------------- | --------- | ------------------------------------------------------------------------------------ |
| `hasProduct(slug: string)` | `boolean` | Returns `true` if the member holds an active entitlement for the given product slug. |

```html
<!-- Show premium content only to members with an active "premium" entitlement -->
<div x-show="$store.allegro.hasProduct('premium')">
    <p>Thanks for being a subscriber!</p>
</div>

```

You can read the store directly from template HTML:

```html
<p x-text="$store.allegro.audienceMember?.email"></p>

```

Or from template JavaScript:

```js
const store = Alpine.store('allegro');
if (store.isAuthenticated) {
    console.log('Logged in as', store.audienceMember.email);
}

```

#### `allegroInteraction(slug, data)`[​](#allegrointeractionslug-data "Direct link to allegrointeractionslug-data")

Every template's root container is bound to `allegroInteraction` via `x-data`. You do not call this factory yourself — the SDK sets the `x-data` attribute automatically when the template renders.

The resulting Alpine component scope exposes:

| Property          | Type             | Description                                                                                                          |
| ----------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- |
| `slug`            | `string \| null` | The slug of the Interaction that triggered this template.                                                            |
| `session`         | `object \| null` | Reactive shortcut — proxies `$store.allegro.session`.                                                                |
| `audienceMember`  | `object \| null` | Reactive shortcut — proxies `$store.allegro.audienceMember`.                                                         |
| `isAuthenticated` | `boolean`        | Reactive shortcut — proxies `$store.allegro.isAuthenticated`.                                                        |
| `plans`           | `array`          | The offer's plans, for a template that supports plans. See [Plans](/developer/guides/templates.md#plans).            |
| *(extra data)*    | any              | Any key/value pairs passed as the second argument to `allegro.interaction.trigger()` are available at the top level. |

The shortcut properties let you write concise template expressions without the `$store.allegro.` prefix:

```html
<!-- shortcut -->
<div x-show="isAuthenticated">
    Hello, <span x-text="audienceMember.name"></span>
</div>

<!-- equivalent using the store directly -->
<div x-show="$store.allegro.isAuthenticated">
    Hello, <span x-text="$store.allegro.audienceMember.name"></span>
</div>

```

#### Reactivity Model[​](#reactivity-model "Direct link to Reactivity Model")

The store is updated in response to the following window events, which the SDK dispatches automatically during session transitions:

| Event                             | When it fires                                         |
| --------------------------------- | ----------------------------------------------------- |
| `allegro:authenticated`           | A user is authenticated with the SDK.                 |
| `allegro:logout`                  | `allegro.member.logout()` completes.                  |
| `allegro:jwt-refreshed`           | The session JWT is refreshed in the background.       |
| `allegro:jwt-refresh-failed`      | A JWT refresh attempt fails (session likely expired). |
| `allegro:user-attributes:updated` | The user attribute cache is filled or cleared.        |

When any of these fires, the SDK re-reads the current JWT and writes the new values into `$store.allegro`. Alpine's reactivity then propagates the change to any bound template expression.

#### Recipes[​](#recipes "Direct link to Recipes")

##### Gate content on authentication[​](#gate-content-on-authentication "Direct link to Gate content on authentication")

```html
<div x-show="isAuthenticated">
    <p>Welcome back, <span x-text="audienceMember.name"></span>!</p>
</div>

<div x-show="!isAuthenticated">
    <p>Sign in to continue reading.</p>
    <allegro-login-form></allegro-login-form>
</div>

```

##### Read extra data passed to `trigger`[​](#read-extra-data-passed-to-trigger "Direct link to read-extra-data-passed-to-trigger")

If you trigger the interaction with extra data:

```js
allegro.interaction.trigger('paywall', { plan: 'basic', articleId: '123' });

```

Those keys are available directly in the template scope:

```html
<p x-text="plan"></p>
<p x-text="articleId"></p>

```

##### Subscribe to a session event without the store[​](#subscribe-to-a-session-event-without-the-store "Direct link to Subscribe to a session event without the store")

If you need to react to a specific transition in template JavaScript rather than using Alpine bindings, listen directly on `window`:

```js
window.addEventListener('allegro:logout', () => {
    // e.g. redirect or show a goodbye message
});

```

##### Add per-instance state with nested `x-data`[​](#add-per-instance-state-with-nested-x-data "Direct link to add-per-instance-state-with-nested-x-data")

The root `x-data` is managed by Allegro. To add your own local state, use `x-data` on a child element — Alpine merges scopes through the component tree:

```html
<div x-data="{ open: false }">
    <button @click="open = !open">Read more</button>
    <p x-show="open" x-text="audienceMember?.name ?? 'Guest'"></p>
</div>

```


---

### Member Authentication

The `allegro.member` namespace provides methods to authenticate members, retrieve user info, and check entitlements.

#### `allegro.member.isAuthenticated()`[​](#allegromemberisauthenticated "Direct link to allegromemberisauthenticated")

Synchronously returns whether the stored JWT represents an authenticated user.

```js
if (allegro.member.isAuthenticated()) {
    // show authenticated UI
}

```

#### `allegro.member.isIdentified()`[​](#allegromemberisidentified "Direct link to allegromemberisidentified")

Synchronously returns whether the session has a stored JWT. A session is identified once the user has provided their email (e.g. via a magic link request), but may not yet be fully authenticated.

```js
if (allegro.member.isIdentified()) {
    // user is known but may not be authenticated
}

```

#### `allegro.member.sessionFromJwt()`[​](#allegromembersessionfromjwt "Direct link to allegromembersessionfromjwt")

Synchronously returns the parsed JWT payload from the stored token, or `null` if no token is stored. Does not make a network request.

```js
const payload = allegro.member.sessionFromJwt();

if (payload) {
    console.log(payload.sub); // Audience Member ID
    console.log(payload.authenticated); // boolean
    console.log(payload.session.id);
    console.log(payload.audience_member);
}

```

**Response shape:**

```ts
{
    iss: string;
    aud: string;
    iat: number;
    exp: number;
    sub: string;           // Audience Member ID
    authenticated: boolean;
    session: {
        id: string;
        authenticated_at: string | null;
    };
    audience_member: AudienceMember;
    [key: string]: unknown;
} | null

```

#### `allegro.member.session()`[​](#allegromembersession "Direct link to allegromembersession")

Fetches the current session from the API. Use this when you need a fresh, server-verified session rather than decoding the stored JWT locally.

```js
const { data } = await allegro.member.session();

console.log(data.id);
console.log(data.is_authenticated);
console.log(data.authenticated_at);
console.log(data.audience_member);

```

**Response shape:**

```ts
{
    data: {
        id: string;
        is_authenticated: boolean;
        authenticated_at: string | null;
        created_at: string;
        updated_at: string;
        audience_member: AudienceMember;
    }
}

```

#### `allegro.member.user()`[​](#allegromemberuser "Direct link to allegromemberuser")

Get the currently logged-in user. Returns a promise that resolves with the user object, or `null` if no one is logged in. This does not make a network request — it decodes the stored JWT locally.

```js
const user = await allegro.member.user();

if (user) {
    console.log(user.id);
    console.log(user.email);
    console.log(user.name);
    console.log(user.email_verified);
} else {
    console.log('No user logged in');
}

```

**Response shape:**

```ts
{
    id: string;
    email: string;
    name?: string;
    email_verified: boolean;
} | null

```

#### `allegro.member.identifyByEmail(email)`[​](#allegromemberidentifybyemailemail "Direct link to allegromemberidentifybyemailemail")

Identifies a user by email address and stores the resulting session JWT. Useful for associating tracking events with a known email before full authentication.

```js
const { jwt } = await allegro.member.identifyByEmail('user@example.com');

```

Pass user attribute values as the third argument to store them against the member, keyed by attribute slug:

```js
await allegro.member.identifyByEmail('user@example.com', undefined, {
    'wants-newsletter': true,
    color: 'blue',
});

```

Because identifying doesn't prove the visitor owns the email address, a value is only stored when the member doesn't already have one for that attribute. Existing values are never overwritten; use `setUserAttributes()` after the member signs in to change them. Every slug must be an attribute members can edit, and every value must pass the attribute's type and validation rules, or the whole call fails and nothing is saved.

#### `allegro.member.entitlements()`[​](#allegromemberentitlements "Direct link to allegromemberentitlements")

Get the current user's entitlements. Returns a promise that resolves with an array.

```js
const entitlements = await allegro.member.entitlements();

for (const entitlement of entitlements) {
    console.log(entitlement.id, entitlement.name);
}

```

**Response shape:**

```ts
{ id: string; name: string; [key: string]: unknown }[]

```

#### `allegro.member.logout()`[​](#allegromemberlogout "Direct link to allegromemberlogout")

Clears the stored JWT and stops any active authentication polling.

```js
await allegro.member.logout();

```

#### Related[​](#related "Direct link to Related")

* [Magic Links guide](/developer/guides/authentication/magic-links.md) — passwordless authentication via email
* [One-Time Codes guide](/developer/guides/authentication/one-time-codes.md) — passwordless authentication via an emailed six-digit code
* [Social Login guide](/developer/guides/authentication/social-login.md) — OAuth with Google, Apple, and Facebook
* [allegro-login-form component](/developer/components/login-form.md) — drop-in UI for the full auth flow


---

### Magic Links

Magic links provide passwordless authentication — the user enters their email, receives a link, and clicking it authenticates them without a password.

Just want a login form?

If you don't need to build the UI yourself, the [`<allegro-login-form>`](/developer/components/login-form.md) web component handles the entire magic link flow out of the box — drop one tag on your page and you're done.

#### How It Works[​](#how-it-works "Direct link to How It Works")

1. Call `allegro.member.requestMagicLink(email)` — Allegro sends a magic link to that address and starts polling for authentication in the background
2. The user clicks the link, which includes a short-lived token in the URL
3. The SDK automatically detects `allegro_token` in the URL and validates it
4. On success, a JWT session is issued and `allegro:magic-link:authenticated` fires on `window`

#### Requesting a Magic Link[​](#requesting-a-magic-link "Direct link to Requesting a Magic Link")

```js
await allegro.member.requestMagicLink(
    'user@example.com',
    'https://example.com/account', // optional: where to redirect after auth
    { plan: 'monthly' }, // optional: custom data attached to the request
);

```

| Parameter   | Type                      | Required | Description                                                                         |
| ----------- | ------------------------- | -------- | ----------------------------------------------------------------------------------- |
| `email`     | `string`                  | Yes      | The user's email address                                                            |
| `returnUrl` | `string`                  | No       | URL to redirect to after the magic link is validated. Defaults to the current page. |
| `data`      | `Record<string, unknown>` | No       | Custom data to attach to the request                                                |

important

`returnUrl` must be an allowed origin

For security, `returnUrl` must point at an origin the tenant has allowed — its Allegro subdomain, its [custom domain](/developer/platform/setup/custom-domain.md), or any origin in the `cors_allowed_origins` tenant setting. A request whose `returnUrl` is on any other origin is rejected with a validation error and no magic link is sent. This stops the sign-in token from being delivered to a domain you do not control.

Because `returnUrl` defaults to the current page, embeds served from your own site work without extra configuration. You only need to add origins when you redirect to a different host.

Calling `requestMagicLink` automatically starts cross-tab polling so that if the user opens the magic link in a different browser tab or window, the original tab authenticates without a page reload.

Requesting a link does not sign anyone in

Requesting a magic link never returns an authenticated session — the member is only signed in after the link's token is validated. Don't treat any token returned by the request call as a signed-in session.

#### Validating a Token Manually[​](#validating-a-token-manually "Direct link to Validating a Token Manually")

The SDK validates `allegro_token` from the URL automatically on page load. If you need to validate a token yourself:

```js
const { jwt } = await allegro.member.validateMagicLink(token);

```

#### SDK Events[​](#sdk-events "Direct link to SDK Events")

All events are dispatched on `window` as `CustomEvent` instances.

| Event                              | Detail              | When                                                                  |
| ---------------------------------- | ------------------- | --------------------------------------------------------------------- |
| `allegro:magic-link:authenticated` | *(none)*            | Token validated successfully, or polling detected auth in another tab |
| `allegro:magic-link:failed`        | `{ error: string }` | Token validation failed (expired or invalid)                          |
| `allegro:jwt-refreshed`            | `MemberJwtPayload`  | JWT was refreshed successfully                                        |
| `allegro:jwt-refresh-failed`       | `{ error: string }` | JWT refresh failed                                                    |
| `allegro:logout`                   | *(none)*            | User was logged out                                                   |
| `allegro:ready`                    | *(none)*            | SDK fully initialized (fires before magic link validation)            |

```js
window.addEventListener('allegro:magic-link:authenticated', () => {
    // User is now authenticated — update your UI
});

window.addEventListener('allegro:magic-link:failed', (event) => {
    console.error('Magic link failed:', event.detail.error);
});

```

#### Checking Validation Outcome After Page Load[​](#checking-validation-outcome-after-page-load "Direct link to Checking Validation Outcome After Page Load")

If your code runs after the `allegro:magic-link:authenticated` or `allegro:magic-link:failed` events have already fired, read the synchronous `magicLinkValidation` property instead of listening for events:

```js
// 'authenticated' | 'failed' | null
const result = allegro.magicLinkValidation;

```

#### Using the allegro-login-form Component[​](#using-the-allegro-login-form-component "Direct link to Using the allegro-login-form Component")

The [`<allegro-login-form>`](/developer/components/login-form.md) web component handles the full magic link flow automatically — no manual SDK calls needed:

```html
<allegro-login-form publisher-name="Example News"></allegro-login-form>

```

#### Related[​](#related "Direct link to Related")

* [One-Time Codes guide](/developer/guides/authentication/one-time-codes.md) — passwordless auth via an emailed six-digit code
* [Social Login guide](/developer/guides/authentication/social-login.md) — OAuth with Google and Apple
* [allegro-login-form component](/developer/components/login-form.md) — full UI for magic link + social login


---

### One-Time Codes

One-time codes provide passwordless authentication — the user enters their email, receives a six-digit code, and types it back in to authenticate without a password.

Unlike [magic links](/developer/guides/authentication/magic-links.md), the code is entered on the same device that requested it, so authentication completes synchronously. There is no cross-tab polling — the device that requests the code is the device that signs in.

Just want a login form?

If you don't need to build the UI yourself, the [`<allegro-login-form>`](/developer/components/login-form.md) web component handles the entire one-time code flow out of the box — drop one tag on your page and you're done.

#### How It Works[​](#how-it-works "Direct link to How It Works")

1. Call `allegro.member.requestLoginCode(email)` — Allegro emails a six-digit code to that address and creates the audience member if they do not already exist
2. The user enters the code into your UI
3. Call `allegro.member.validateLoginCode(code)` to verify it
4. On success, a JWT session is issued and `allegro:authenticated` fires on `window` with `detail.method === 'otp'`

#### Requesting a Code[​](#requesting-a-code "Direct link to Requesting a Code")

```js
await allegro.member.requestLoginCode(
    'user@example.com',
    'https://example.com/account', // optional: where to redirect after auth
    { plan: 'monthly' }, // optional: custom data attached to the session
);

```

| Parameter   | Type                      | Required | Description                                                                   |
| ----------- | ------------------------- | -------- | ----------------------------------------------------------------------------- |
| `email`     | `string`                  | Yes      | The user's email address                                                      |
| `returnUrl` | `string`                  | No       | URL to redirect to after the code is validated. Defaults to the current page. |
| `data`      | `Record<string, unknown>` | No       | Custom data to attach to the resulting session                                |

**Response shape:**

```ts
{
    created: boolean; // true if a new audience member was created
    jwt: string;
    status: 'ok';
}

```

note

The request `jwt` is not authenticated

The `jwt` returned when you *request* a code represents an unauthenticated device session. It is never signed in, even if the same device was signed in before. The member is only authenticated after you call `validateLoginCode` with a correct code — don't treat the request-time `jwt` as a signed-in session.

Codes expire and resends invalidate older codes

Each code is valid for 30 minutes. Requesting a new code invalidates any previous code for the session — only the most recently emailed code works.

Requests are rate limited

Requesting a code is limited to **3 requests per email per minute**. Beyond that, the request is rejected with a rate-limit error. Surface a "try again shortly" message rather than retrying automatically.

#### Validating a Code[​](#validating-a-code "Direct link to Validating a Code")

```js
const { jwt, return_url, audience_member_created } =
    await allegro.member.validateLoginCode('123456');

```

| Parameter | Type     | Required | Description                       |
| --------- | -------- | -------- | --------------------------------- |
| `code`    | `string` | Yes      | The six-digit code the user typed |

**Response shape:**

```ts
{
    message: string;
    jwt: string;
    return_url: string | null; // the returnUrl from the original request, if any
    audience_member_created: boolean;
    sessions_authenticated: string[];
}

```

On success the session JWT is stored automatically and an `allegro:authenticated` event fires. On failure, validation throws an `AllegroApiError` whose `errorCode` is one of:

| `errorCode`   | Meaning                                                             |
| ------------- | ------------------------------------------------------------------- |
| `INVALID_OTP` | The code is wrong, or no valid code exists for this device          |
| `OTP_EXPIRED` | The code has expired — request a new one                            |
| `OTP_LOCKED`  | Too many incorrect attempts — the code is locked, request a new one |

```js
try {
    await allegro.member.validateLoginCode(code);
} catch (error) {
    if (error.errorCode === 'OTP_LOCKED') {
        // Prompt the user to request a fresh code
    } else {
        // Show "that code wasn't right" and let them retry
    }
}

```

#### SDK Events[​](#sdk-events "Direct link to SDK Events")

All events are dispatched on `window` as `CustomEvent` instances.

| Event                   | Detail              | When                              |
| ----------------------- | ------------------- | --------------------------------- |
| `allegro:authenticated` | `{ method: 'otp' }` | A code was validated successfully |
| `allegro:jwt-refreshed` | `MemberJwtPayload`  | JWT was refreshed successfully    |
| `allegro:logout`        | *(none)*            | User was logged out               |

```js
window.addEventListener('allegro:authenticated', (event) => {
    if (event.detail.method === 'otp') {
        // User is now authenticated — update your UI
    }
});

```

#### Using the allegro-login-form Component[​](#using-the-allegro-login-form-component "Direct link to Using the allegro-login-form Component")

The [`<allegro-login-form>`](/developer/components/login-form.md) web component handles the full one-time code flow automatically — no manual SDK calls needed:

```html
<allegro-login-form publisher-name="Example News"></allegro-login-form>

```

#### Related[​](#related "Direct link to Related")

* [Magic Links guide](/developer/guides/authentication/magic-links.md) — passwordless authentication via an emailed link
* [Social Login guide](/developer/guides/authentication/social-login.md) — OAuth with Google, Apple, and Facebook
* [allegro-login-form component](/developer/components/login-form.md) — full UI for the auth flow


---

### Social Login

On desktop, social login uses a **popup window flow**. The popup navigates through the OAuth redirect loop and communicates the result back to the parent window via `window.postMessage`, keeping the JWT out of the browser's URL history, server logs, and referrer headers.

On mobile, and anywhere the browser refuses to open the popup, it uses a **redirect flow** instead: the current page navigates to the provider and comes back when the reader has signed in. See [Mobile and in-app browsers](#mobile-and-in-app-browsers).

#### Supported Providers[​](#supported-providers "Direct link to Supported Providers")

Providers must be configured by the tenant administrator in **Organization Settings → Login Providers**. Supported providers include Google, Apple, and Facebook.

#### Using the allegro-login-form Component[​](#using-the-allegro-login-form-component "Direct link to Using the allegro-login-form Component")

The [`<allegro-login-form>`](/developer/components/login-form.md) web component includes social login buttons automatically:

```html
<allegro-login-form></allegro-login-form>

```

To hide the social buttons:

```html
<allegro-login-form hide-third-party="true"></allegro-login-form>

```

The component fires `allegro:login-form:third-party:authenticated` with `{ provider, session_id, token }` on successful OAuth login, whether it used the popup or the redirect flow. On mobile, and when the browser blocks the popup, the component switches to the redirect flow automatically.

#### Using the SDK[​](#using-the-sdk "Direct link to Using the SDK")

Call `allegro.member.loginWithProvider(provider)` to open the OAuth popup and await the result:

```js
try {
    const { session_id, token } =
        await allegro.member.loginWithProvider('google');
    console.log('Authenticated, session:', session_id);
} catch (error) {
    console.error('Auth failed:', error);
}

```

Pass the provider slug as a string — for example `'google'`, `'apple'`, or `'facebook'`. The method opens the popup, waits for the OAuth flow to complete, and resolves with the session on success or rejects on failure.

**Response shape:**

```ts
{
    session_id: string; // UUID of the newly created audience member session
    token: string; // Signed JWT for the session
}

```

#### Mobile and in-app browsers[​](#mobile-and-in-app-browsers "Direct link to Mobile and in-app browsers")

Many mobile browsers, and especially the in-app browsers that open links inside apps, can't open a popup or can't pass a message back from one. The redirect flow avoids popups entirely:

1. The page navigates to the provider in the same window.
2. After the reader signs in, the provider returns to Allegro, and Allegro redirects back to the original page with a one-time `allegro_social_code` query parameter.
3. On page load, the SDK exchanges the code for the member's JWT, removes the parameter from the URL, and signs the member in.

When the page comes back, the SDK scrolls to where the reader was, and interactions skip their time and scroll delays. A login form inside a delayed interaction, such as a content gate that opens at a scroll depth, opens at once and shows the result.

`<allegro-login-form>` uses the redirect flow on phones and tablets, and falls back to it whenever `loginWithProvider` rejects because the popup was blocked. To start it yourself, call `loginWithProviderRedirect` with the URL to return to:

```js
allegro.member.loginWithProviderRedirect('facebook', window.location.href);

```

The return URL must be on one of the origins allowed in your [browser settings](/developer/administration/browser-settings.md). Because the page reloads, listen for the result on `window` rather than awaiting a promise:

```js
window.addEventListener('allegro:social:authenticated', (event) => {
    const { provider, created } = event.detail;
    console.log(`Signed in with ${provider}`, created ? '(new member)' : '');
});

window.addEventListener('allegro:social:failed', (event) => {
    console.warn('Social login failed:', event.detail.error);
});

```

| Event                          | Detail                                                                      | When                                                                                                                                         |
| ------------------------------ | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `allegro:authenticated`        | `{ method: 'social', provider: string }`                                    | The SDK signed the member in after a redirect.                                                                                               |
| `allegro:social:authenticated` | `{ provider: string, created: boolean, session_id: string, token: string }` | Same moment, with the session details.                                                                                                       |
| `allegro:social:failed`        | `{ error: string }`                                                         | The reader canceled (`auth_cancelled`), the provider returned no email (`no_email`), or the login failed (`auth_failed`, `exchange_failed`). |

The SDK also records the outcome on `allegro.socialLoginValidation` (`'pending'`, `'authenticated'` or `'failed'`) and the error code on `allegro.socialLoginError`, so code that runs after the event has fired can still read it.

To catch a blocked popup in your own code, check the error's `name`:

```js
try {
    await allegro.member.loginWithProvider('google');
} catch (error) {
    if (error.name === 'PopupBlockedError') {
        allegro.member.loginWithProviderRedirect(
            'google',
            window.location.href,
        );
    }
}

```

Google in embedded app webviews

Google blocks sign-in inside embedded webviews, such as a native app's `WKWebView` or Android `WebView`, and shows a `403 disallowed_useragent` error whichever flow you use. Facebook, Apple, and the other providers work there with the redirect flow. For Google to work inside your own app, open your pages in `SFSafariViewController` (iOS) or Chrome Custom Tabs (Android) instead of an embedded webview.

#### Reading the Provider Profile[​](#reading-the-provider-profile "Direct link to Reading the Provider Profile")

After a member authenticates with a provider, Allegro stores the raw profile data returned by that provider (name, email, avatar URL, etc.). You can fetch this data in your templates using `allegro.member.externalProfile(provider)`:

```js
window.allegro.push(async (allegro) => {
    if (!allegro.member.isAuthenticated()) return;

    try {
        const profile = await allegro.member.externalProfile('google');
        console.log(profile.name, profile.email, profile.picture);
    } catch (error) {
        // Member has no Google profile, the request failed, or the session expired
        console.error('Profile not found:', error);
    }
});

```

Pass the provider slug as a string (e.g. `'google'`, `'apple'`, `'facebook'`). The method returns the raw attributes stored for that provider — the exact shape depends on what each provider includes in their response. The method throws if the member has no linked profile for the given provider, so always wrap the call in a `try/catch`.

#### Related[​](#related "Direct link to Related")

* [Magic Links guide](/developer/guides/authentication/magic-links.md) — passwordless authentication via email
* [allegro-login-form component](/developer/components/login-form.md) — drop-in UI for social + magic link login


---

### Event Tracking

Use `allegro.track()` to record events. The SDK handles session creation, device identification, and page metadata collection automatically.

#### Basic Usage[​](#basic-usage "Direct link to Basic Usage")

```js
window.allegro.push(function (allegro) {
    allegro.track('page_view');
});

```

#### `allegro.track(eventName, data?)`[​](#allegrotrackeventname-data "Direct link to allegrotrackeventname-data")

Track an event. Returns a promise that resolves with `{ event_id: string }`.

The SDK automatically:

* Creates a session if one doesn't exist
* Includes device ID, session ID, and CSRF token
* Collects page metadata from the DOM (title, content type, publisher, etc.)
* Attaches the logged-in customer ID if available

##### With event data[​](#with-event-data "Direct link to With event data")

```js
allegro.track('article_read', {
    content_id: 'article-456',
    content_type: 'premium',
    publisher: 'Daily News',
});

```

##### With custom data[​](#with-custom-data "Direct link to With custom data")

```js
allegro.track('purchase', {
    data: {
        product_id: 'sku-789',
        price: 9.99,
        currency: 'USD',
    },
});

```

##### Available fields[​](#available-fields "Direct link to Available fields")

| Field              | Type                      | Description                          |
| ------------------ | ------------------------- | ------------------------------------ |
| `url`              | `string`                  | Page URL (auto-collected by default) |
| `referer`          | `string`                  | Referring URL                        |
| `page_title`       | `string`                  | Page title                           |
| `content_type`     | `string`                  | Content type (e.g. article, video)   |
| `content_id`       | `string`                  | Content identifier                   |
| `publisher`        | `string`                  | Publisher name                       |
| `object_type`      | `string`                  | Object type                          |
| `object_id`        | `string`                  | Object identifier                    |
| `context`          | `string`                  | Context or category                  |
| `conversion_pv_id` | `string`                  | Conversion page view ID              |
| `url_in_click`     | `string`                  | Clicked URL                          |
| `data`             | `Record<string, unknown>` | Arbitrary custom data                |

For more information, see [Page Metadata](/developer/guides/page-metadata.md).

#### Session & Device Management[​](#session--device-management "Direct link to Session & Device Management")

The SDK manages two cookies:

| Cookie               | Lifetime   | Purpose                                  |
| -------------------- | ---------- | ---------------------------------------- |
| `allegro_device_id`  | 10 years   | Persistent device identifier (UUID v4)   |
| `allegro_session_id` | 30 minutes | Session identifier, extended on activity |

Sessions are created automatically on the first `track()` or `member.login()` call. Each `track()` call extends the session timeout.


---

### 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](/product/interactions.md).

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

| Mode                    | How it fires on the page                                                                                                 |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Automatic targeting** | The SDK asks Allegro which journeys the visitor matches on every page load and renders the results. No integration code. |
| **Manual embed**        | Your code calls `allegro.interaction.trigger(slug)`.                                                                     |

#### Automatic Evaluation[​](#automatic-evaluation "Direct link to 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.

| Field          | Source                                                                            |
| -------------- | --------------------------------------------------------------------------------- |
| `url`, `path`  | `window.location`                                                                 |
| `query`        | The URL query string (first value wins for repeated keys)                         |
| `referrer`     | `document.referrer`                                                               |
| `content_type` | The `content_type` [page metadata](/developer/guides/page-metadata.md) field      |
| `section`      | The `context` [page metadata](/developer/guides/page-metadata.md) field           |
| `timezone`     | `Intl.DateTimeFormat().resolvedOptions().timeZone`                                |
| `custom`       | The `custom` object from your SDK configuration (see [Custom Data](#custom-data)) |
| `cookies`      | Every `_al_`-prefixed cookie, keyed without the prefix (see [Cookies](#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](/developer/guides/script-tag.md#debug-mode) is on.

Conflict rules set on the dashboard's [Priority](/product/interactions/priority.md) 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](/developer/api/session/allegro-interaction-evaluate.md).

##### Configuration[​](#configuration "Direct link to Configuration")

Set these on `window.__allegro` before `client.js` loads. See [Script Tag](/developer/guides/script-tag.md#window__allegro-configuration).

| Property          | Type      | Default | Description                                                                                                                  |
| ----------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `interactions`    | `boolean` | `true`  | Run the automatic evaluation on page load. Set `false` to rely on `trigger()` and manual `evaluate()` calls only.            |
| `interactionsSpa` | `boolean` | `false` | Re-evaluate on single-page-app navigation (`pushState`, `replaceState`, `popstate`). Ignored when `interactions` is `false`. |
| `custom`          | `object`  | —       | Key/value pairs sent as custom data for **Custom data** conditions. Values may be strings, numbers, or booleans.             |

```html
<script>
    window.__allegro = {
        interactionsSpa: true,
        custom: {
            plan: 'trial',
        },
    };
</script>
<script src="https://acme.allegrocdp.com/client.js"></script>

```

##### Custom Data[​](#custom-data "Direct link to 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[​](#cookies "Direct link to 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:

```js
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[​](#single-page-applications "Direct link to 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.

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

```

##### Attribution in Tracked Events[​](#attribution-in-tracked-events "Direct link to 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](/developer/guides/templates.md#display-tracking).

#### `allegro.interaction` Namespace[​](#allegrointeraction-namespace "Direct link to allegrointeraction-namespace")

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

##### `evaluate()`[​](#evaluate "Direct link to 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.

```js
await allegro.interaction.evaluate();

```

##### `trigger(slug, data?)`[​](#triggerslug-data "Direct link to triggerslug-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.

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

allegro.interaction.trigger('member-wall', {
    title: 'Join our membership program',
});

```

| Parameter | Type     | Description                                           |
| --------- | -------- | ----------------------------------------------------- |
| `slug`    | `string` | The interaction's slug, shown in the dashboard        |
| `data`    | `object` | Optional 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()`[​](#experiments "Direct link to experiments")

Returns the visitor's [A/B test](/product/interactions/ab-tests.md) 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.

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

```

##### `remove(slug)`[​](#removeslug "Direct link to removeslug")

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

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

```

##### `ungate(slug)`[​](#ungateslug "Direct link to ungateslug")

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

```js
allegro.interaction.ungate('paywall');

```

#### Rendering[​](#rendering "Direct link to 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](/developer/guides/templates.md) for the host element, Alpine state, and CSS variables available inside a rendered template.

#### Related[​](#related "Direct link to Related")

* [Templates guide](/developer/guides/templates.md) — Host element, Alpine state, display tracking
* [Page Metadata](/developer/guides/page-metadata.md) — Where `content_type` and `section` come from
* [Event Tracking guide](/developer/guides/event-tracking.md) — Full `track()` API reference
* [API Reference](/developer/api-reference.md) — TypeScript type definitions for `InteractionNamespace`


---

### JavaScript Events

The Allegro SDK dispatches custom events on `window` at key points in the member lifecycle. Listen for these events to react to authentication state changes without polling.

#### `allegro:authenticated`[​](#allegroauthenticated "Direct link to allegroauthenticated")

Fired when a member successfully authenticates. This happens across several flows:

* A magic link is clicked and the token in the URL is validated on page load
* A magic link is detected during background polling (cross-tab)
* A magic link is detected from a cookie when the page regains focus or visibility
* A social login (Google, Apple, etc.) completes
* A purchase token is exchanged on return from checkout and the member was not already authenticated

##### Detail[​](#detail "Direct link to Detail")

| Field      | Type                                     | Description                                                        |
| ---------- | ---------------------------------------- | ------------------------------------------------------------------ |
| `method`   | `'magic-link' \| 'social' \| 'purchase'` | Which authentication flow triggered the event                      |
| `provider` | `string`                                 | The OAuth provider name — only present when `method` is `'social'` |

##### Example[​](#example "Direct link to Example")

```js
window.addEventListener('allegro:authenticated', (event) => {
    const { method, provider } = event.detail;

    if (method === 'social') {
        console.log('Signed in via', provider); // e.g. "google"
    }

    // Re-render gated content, update nav, etc.
});

```

#### `allegro:logout`[​](#allegrologout "Direct link to allegrologout")

Fired after a member is logged out via `allegro.member.logout()`. The member's JWT has already been cleared by the time this event fires.

##### Detail[​](#detail-1 "Direct link to Detail")

None — `event.detail` is `null`.

##### Example[​](#example-1 "Direct link to Example")

```js
window.addEventListener('allegro:logout', () => {
    // Redirect, clear local state, re-render gated content, etc.
});

```

#### `allegro:interaction:ungated`[​](#allegrointeractionungated "Direct link to allegrointeractionungated")

Fired after an interaction reveals content it had gated — for example when an [`allegro-content-gate`](/developer/components/content-gate.md) closes following a successful login and the blurred or truncated article behind it is restored.

##### Detail[​](#detail-2 "Direct link to Detail")

| Field  | Type     | Description                           |
| ------ | -------- | ------------------------------------- |
| `slug` | `string` | The slug of the interaction revealed. |

##### Example[​](#example-2 "Direct link to Example")

```js
window.addEventListener('allegro:interaction:ungated', (event) => {
    console.log('Revealed interaction', event.detail.slug);
    // Re-run layout, lazy-load images now in view, etc.
});

```

#### Listening to both events[​](#listening-to-both-events "Direct link to Listening to both events")

A common pattern is to sync UI state whenever authentication changes in either direction:

```js
function syncAuthState() {
    window.allegro.push(function (allegro) {
        const isAuthenticated = allegro.member.isAuthenticated();
        document.body.classList.toggle('is-authenticated', isAuthenticated);
    });
}

window.addEventListener('allegro:authenticated', syncAuthState);
window.addEventListener('allegro:logout', syncAuthState);

```

note

These events fire on `window` and bubble is `false`. Add listeners directly to `window` — attaching to `document` or a child element will not work.


---

### JWT Verification

Allegro issues signed JSON Web Tokens (JWTs) for every member session. Because these tokens are signed with an asymmetric RS256 key, you can verify them in your own infrastructure — AWS API Gateway, Cloudflare Workers, custom middleware — without any shared secret.

#### Getting the token in the browser[​](#getting-the-token-in-the-browser "Direct link to Getting the token in the browser")

When you want your own backend to trust the visitor's Allegro session, read the raw JWT from the SDK and send it along as a bearer token. `allegro.member.getJwt()` returns the current session JWT as a string, or `null` when there is no valid token (the visitor is signed out, or the token is missing, malformed, or expired):

```js
window.allegro.push(function (allegro) {
    const jwt = allegro.member.getJwt();

    if (jwt) {
        fetch('/api/user', {
            headers: { Authorization: `Bearer ${jwt}` },
        });
    }
});

```

Your backend then verifies the token against the tenant's public keys, exactly as described in the sections below — you don't need to share a secret with Allegro or call back to it to trust the token.

#### Token Structure[​](#token-structure "Direct link to Token Structure")

Every Allegro JWT has the following standard claims:

| Claim | Description                                              |
| ----- | -------------------------------------------------------- |
| `iss` | Issuer — your tenant domain (e.g. `https://example.com`) |
| `aud` | Audience — same as `iss`                                 |
| `sub` | Subject — the member's UUID                              |
| `iat` | Issued at (Unix timestamp)                               |
| `exp` | Expires at (Unix timestamp, 1 year from issue)           |
| `jti` | Unique token ID (UUID v4)                                |

In addition, Allegro includes these custom claims:

| Claim                      | Description                                                                                                                                                                                                                                                                                                       |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `authenticated`            | `true` if the member has completed authentication                                                                                                                                                                                                                                                                 |
| `session.id`               | UUID of the `AudienceDeviceSession`                                                                                                                                                                                                                                                                               |
| `session.authenticated_at` | ISO 8601 timestamp of when the session was authenticated                                                                                                                                                                                                                                                          |
| `audience_member`          | Member object with `id`, `email`, `name`, `email_verified`, `created_at` and `updated_at`. Member meta is not included; read attribute values with `getUserAttributes()`                                                                                                                                          |
| `products`                 | Array of product slugs the member currently holds active entitlements for                                                                                                                                                                                                                                         |
| `user_attributes`          | Object of the member's [user attribute](/developer/guides/user-attributes.md) values, keyed by slug and cast to each attribute's type. Only attributes with a value appear; [private](/developer/guides/user-attributes.md#private-attributes) attributes never appear; omitted entirely when the member has none |

#### Token lifetime and revocation[​](#token-lifetime-and-revocation "Direct link to Token lifetime and revocation")

A token stays valid until its `exp` claim — one year from when it was issued. Allegro also revokes a token as soon as the member logs out: the token's `jti` is recorded so it can no longer be used against Allegro's own session API.

The distinction matters if you verify tokens yourself:

* **Calls to the Allegro session API** (including anything the SDK does on the member's behalf) reject a revoked token immediately after logout.
* **Your own stateless verification** against the JWKS endpoint only checks the signature and `exp`. It has no way to know the member has since logged out, so a token you have already read stays cryptographically valid until it expires.

If your backend caches or trusts a JWT beyond a single request, treat the [`allegro:logout` event](/developer/guides/javascript-events.md#allegrologout) as the signal to drop the token rather than relying on `exp` alone.

#### OIDC Discovery[​](#oidc-discovery "Direct link to OIDC Discovery")

Allegro exposes a standard OpenID Connect discovery document:

```text
GET https://<your-tenant-domain>/.well-known/openid-configuration

```

This returns the issuer, JWKS URI, and supported algorithms. Most OIDC-aware services read this endpoint automatically.

#### JWKS Endpoint[​](#jwks-endpoint "Direct link to JWKS Endpoint")

Public keys used to verify token signatures are available at:

```text
GET https://<your-tenant-domain>/.well-known/jwks.json

```

The response is a standard [JWK Set](https://www.rfc-editor.org/rfc/rfc7517) containing one or more RSA public keys. Multiple keys may appear during key rotation — consumers must select the key matching the `kid` in the token header.

#### Example: AWS API Gateway JWT Authorizer[​](#example-aws-api-gateway-jwt-authorizer "Direct link to Example: AWS API Gateway JWT Authorizer")

1. In your API Gateway HTTP API, add a JWT authorizer.
2. Set **Issuer** to your tenant domain: `https://<your-tenant-domain>`
3. Set **Audience** to your tenant domain: `https://<your-tenant-domain>`
4. Set **JWKS URI** to: `https://<your-tenant-domain>/.well-known/jwks.json`

AWS will automatically fetch the public keys and verify incoming tokens. No secret sharing required.


---

### Local Template Preview

![The allegro-preview UI showing a Membership CTA template injected mid-article using the Article · Cut context, alongside the field editor sidebar](/assets/images/local-preview-8703a4a910e2c83fdf93c2d49c20d4cd.png)

`allegro-preview` is a local dev server that renders your Allegro templates exactly as they appear in production — including field substitution, shadow DOM isolation, and [preview scenarios](/developer/guides/scenarios.md). Changes to your template files reload the preview instantly.

#### Usage[​](#usage "Direct link to Usage")

Run from inside any template folder:

```sh
npx @allegrocdp/preview@dev

```

Or point it at a folder explicitly:

```sh
npx @allegrocdp/preview@dev ./path/to/my-template

```

The server starts, prints its URL, and opens your browser automatically.

##### Options[​](#options "Direct link to Options")

| Option                | Default               | Description                              |
| --------------------- | --------------------- | ---------------------------------------- |
| `path`                | Current directory     | Path to the template folder              |
| `-p, --port <number>` | Random available port | Port to listen on                        |
| `--tenant <url>`      | *(none)*              | Tenant base URL for Allegro API requests |

**Example with options:**

```sh
npx @allegrocdp/preview@dev ./my-template --port 3000 --tenant https://allegro.example.com

```

#### Template Folder Structure[​](#template-folder-structure "Direct link to Template Folder Structure")

The preview server expects a folder with the following files:

```text
my-template/
├── index.html       # Template markup
├── index.css        # Template styles
├── index.js         # Template JavaScript (optional)
└── template.json    # Field definitions and metadata (optional)

```

`index.html` supports `{% field_slug %}` placeholders — see [Field Placeholders](/developer/guides/templates.md#field-placeholders) for full details on the substitution syntax.

#### Defining Fields[​](#defining-fields "Direct link to Defining Fields")

Add a `template.json` file alongside `index.html` to define the template's name and editable fields. Each field becomes an input in the preview sidebar, and changing a value re-renders the preview immediately without a full page reload.

See [template.json](/developer/guides/template-json.md) for the full manifest schema and field types.

#### Previewing Plans[​](#previewing-plans "Direct link to Previewing Plans")

A template that declares `"supports": ["plans"]` renders two sample plans, so its `{% for plan in plans %}` loop, its Alpine `plans`, and its `index.js` `plans` all have data. To preview your own plans, add a preview-only `plans` list to `template.json`. The sync ignores it.

```json
{
    "name": "Plan Picker",
    "supports": ["plans"],
    "fields": [],
    "plans": [
        {
            "id": "monthly",
            "name": "Monthly",
            "formatted_price": "$9.99",
            "duration_label": "1 month",
            "fields": { "badge": null }
        },
        {
            "id": "annual",
            "name": "Annual",
            "formatted_price": "$99.00",
            "duration_label": "1 year",
            "fields": { "badge": "Best value" }
        }
    ]
}

```

Keys you leave out render as empty strings. See [Plans](/developer/guides/templates.md#plans) for every key a plan has.

#### Scenarios[​](#scenarios "Direct link to Scenarios")

The toolbar lets you preview your template across different **scenarios** — built-in article placements and your own custom host pages. See [Preview Scenarios](/developer/guides/scenarios.md) for the built-in scenarios and how to define custom ones.

#### Device Breakpoints[​](#device-breakpoints "Direct link to Device Breakpoints")

The toolbar also includes a device selector for testing responsive layouts:

| Device  | Viewport width           |
| ------- | ------------------------ |
| Full    | Fills available width    |
| Desktop | 1280px                   |
| Tablet  | 768px                    |
| Mobile  | 390px (max-height 812px) |

#### Live Reload[​](#live-reload "Direct link to Live Reload")

The server watches `index.html`, `index.css`, `index.js`, and `template.json` for changes. Any edit triggers an automatic refresh of the preview — no manual reload needed.

#### Multiple Templates[​](#multiple-templates "Direct link to Multiple Templates")

If your project contains multiple template subfolders (each with their own `index.html`), the preview server detects them all and shows a template selector in the sidebar. The URL hash updates to reflect the active template, so you can bookmark or share a direct link.

For example, a project with this structure:

```text
my-project/
├── header-banner/
│   ├── index.html
│   └── index.css
└── inline-cta/
    ├── index.html
    ├── index.css
    └── template.json

```

Run from the project root and switch between templates in the UI:

```sh
npx @allegrocdp/preview@dev ./my-project

```

#### Tenant URL[​](#tenant-url "Direct link to Tenant URL")

Pass `--tenant` when you need the preview to load Allegro web components that make API requests (for example, `<allegro-login-form>`). The value is injected into the SDK loader, which normally reads it from the script tag served by Allegro itself.

```sh
npx @allegrocdp/preview@dev --tenant https://allegro.example.com

```

Without a tenant URL, static templates render fine, but components that call the Allegro API will fail silently.

note

Your tenant URL preference is saved to `localStorage` so you don't need to pass it every time you restart the server on the same machine.


---

### MCP Server

Every Allegro tenant exposes a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server at `https://acme.allegrocdp.com/mcp`, on the tenant's platform subdomain. Custom domains and per-property hostnames don't serve MCP. This lets AI clients — Claude Desktop, Cursor, custom agents, or any MCP-compatible tool — interact with your audience data, templates, and products through a structured, authenticated interface.

#### Authentication[​](#authentication "Direct link to Authentication")

The MCP server accepts two kinds of credentials:

| Credential | Best for                                                        | Acts as                            |
| ---------- | --------------------------------------------------------------- | ---------------------------------- |
| OAuth      | AI clients such as Claude, Cursor, and VS Code used by a person | The person who signed in           |
| API key    | Scripts, servers, and agents without a person signing in        | The organization that owns the key |

For OAuth, add the MCP URL to your client and sign in when it asks. There is no key to paste. See [Connecting an MCP client with OAuth](/developer/guides/mcp-oauth.md).

An API key authenticates the same way as the [REST API](/developer/api/authentication.md). Include it as a Bearer header on every request:

```http
Authorization: Bearer <your-token>

```

The key must grant **read access (`*:read`) or full access (`*`)**. A key limited to individual resource scopes (for example `products:read` or `events:write`) is rejected with a `403 Forbidden` — MCP tools read across every resource, so a narrowly-scoped key can't be used here. Write tools and admin reads still require a full-access (`*`) key on top of this, as described under [Permissions](#permissions).

A token or key from one tenant cannot be used against a different tenant's MCP endpoint — the server checks the tenant on every request.

#### Connecting a Client[​](#connecting-a-client "Direct link to Connecting a Client")

##### Claude Desktop / Cursor / MCP Inspector[​](#claude-desktop--cursor--mcp-inspector "Direct link to Claude Desktop / Cursor / MCP Inspector")

To use an API key, add the following entry to your client's MCP server configuration, replacing `acme` and `<your-token>` with your actual values:

```json
{
    "mcpServers": {
        "allegro": {
            "url": "https://acme.allegrocdp.com/mcp",
            "headers": {
                "Authorization": "Bearer <your-token>"
            }
        }
    }
}

```

##### Opening the URL in a browser[​](#opening-the-url-in-a-browser "Direct link to Opening the URL in a browser")

The `/mcp` URL is meant for AI assistants, not browsers, but opening it in a browser while signed in to the dashboard shows a **Connect your assistant** page with copy-paste setup instructions for the common clients. An MCP client that requests the URL directly still gets the transport responses it expects, so the page never interferes with a real connection.

#### Finding and Calling Tools[​](#finding-and-calling-tools "Direct link to Finding and Calling Tools")

The server lists two tools, no matter how many tenant tools exist:

| Tool            | Input                                                                         | Returns                                                                     |
| --------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `search_tools`  | `query` (search terms; empty browses the catalog), `limit` (1–50, default 10) | Matching tools with their exact names, descriptions, and full input schemas |
| `execute_tools` | `calls`: up to 10 `{ "name": "<tool>", "arguments": { ... } }` objects        | Each call's result, in order                                                |

Search for what you want to do, then call the tool by the exact name the search returned:

```json
{ "query": "export purchases", "limit": 3 }

```

```json
{
    "calls": [
        {
            "name": "create-export-tool",
            "arguments": {
                "type": "purchases",
                "filters": { "status": "completed" }
            }
        }
    ]
}

```

Calls in one `execute_tools` request run one after another and stop at the first error. Each call is checked on its own, so a write in the batch still needs the admin role. A response is capped at 64 KB.

#### Available Tools[​](#available-tools "Direct link to Available Tools")

Tools marked **admin** below require the admin role even to read, because they expose access control, delivery, or export data. Every write tool requires the admin role.

| Area                       | Read                                                                                                                                                                                                                                                                                                                  | Write                                                                                                                                                                                                                                                                        |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Audience members           | `search-audience-members-tool`, `get-audience-member-tool`, `list-audience-member-events-tool`, `get-audience-member-attributes-tool`                                                                                                                                                                                 | `create-audience-member-tool`, `update-audience-member-tool`, `delete-audience-member-tool`, `trigger-audience-member-sync-tool`, `set-audience-member-attribute-tool`                                                                                                       |
| Entitlements and purchases | `list-purchases-tool`, `get-purchase-tool`                                                                                                                                                                                                                                                                            | `grant-entitlement-tool`, `revoke-entitlement-tool`, `refund-purchase-tool`                                                                                                                                                                                                  |
| Catalog                    | `list-products-tool`, `get-product-tool`, `list-plans-tool`, `get-plan-tool`, `list-offers-tool`, `get-offer-tool`, `list-plan-fields-tool`                                                                                                                                                                           | `create-product-tool`, `update-product-tool`, `delete-product-tool`, `create-plan-tool`, `update-plan-tool`, `delete-plan-tool`, `create-offer-tool`, `update-offer-tool`, `delete-offer-tool`, `create-plan-field-tool`, `update-plan-field-tool`, `delete-plan-field-tool` |
| Forms                      | `list-forms-tool`, `get-form-tool`                                                                                                                                                                                                                                                                                    | `create-form-tool`, `update-form-tool`, `delete-form-tool`                                                                                                                                                                                                                   |
| Templates                  | `list-templates-tool`, `get-template-tool`, `list-template-revisions-tool`, `get-template-revision-tool`, `list-template-library-tool`                                                                                                                                                                                | `create-template-tool`, `update-template-tool`, `duplicate-template-tool`, `delete-template-tool`, `restore-template-tool`, `restore-template-revision-tool`, `import-template-from-library-tool`                                                                            |
| Email                      | `list-email-templates-tool`, `get-email-template-tool`, `list-email-template-revisions-tool`                                                                                                                                                                                                                          | `update-email-template-tool`, `reset-email-template-tool`, `restore-email-template-revision-tool`, `send-test-email-tool`                                                                                                                                                    |
| Recommendations            | `list-recommendation-engines-tool`, `serve-recommendations-tool`, `preview-recommendations-tool`                                                                                                                                                                                                                      | `update-recommendation-engine-tool`, `delete-recommendation-engine-tool`                                                                                                                                                                                                     |
| Branding and embed snippet | `get-branding-tool`, `list-branding-revisions-tool`, `get-embed-snippet-tool`, `list-embed-snippet-revisions-tool`                                                                                                                                                                                                    | `update-branding-tool`, `rollback-branding-tool`, `update-embed-snippet-tool`, `rollback-embed-snippet-tool`                                                                                                                                                                 |
| Properties                 | `list-properties-tool`, `get-property-tool`, `get-property-domain-health-tool` (admin)                                                                                                                                                                                                                                | `create-property-tool`, `update-property-tool`, `delete-property-tool`, `update-property-settings-tool`                                                                                                                                                                      |
| Webhooks                   | `list-webhooks-tool` (admin), `get-webhook-tool` (admin), `list-webhook-deliveries-tool` (admin), `get-webhook-delivery-tool` (admin)                                                                                                                                                                                 | `create-webhook-tool`, `update-webhook-tool`, `delete-webhook-tool`, `ping-webhook-tool`, `retry-webhook-delivery-tool`, `regenerate-webhook-secret-tool`                                                                                                                    |
| User attributes            | `list-user-attributes-tool`, `test-user-attribute-validation-tool`                                                                                                                                                                                                                                                    | `create-user-attribute-tool`, `update-user-attribute-tool`, `delete-user-attribute-tool`, `sync-user-attribute-tool`                                                                                                                                                         |
| Analytics                  | `get-analytics-schema-tool`, `get-analytics-realtime-tool`, `get-analytics-view-tool`, `query-analytics-tool`, `list-analytics-events-tool`, `get-content-analytics-tool`, `get-reader-analytics-tool`, `list-analytics-reports-tool`, `get-analytics-report-tool`, `list-analytics-report-subscriptions-tool`        | `create-analytics-report-tool`, `update-analytics-report-tool`, `delete-analytics-report-tool`, `subscribe-analytics-report-tool`, `unsubscribe-analytics-report-tool`                                                                                                       |
| Settings and operations    | `get-settings-tool`, `get-dashboard-stats-tool`, `list-exports-tool`, `get-export-download-url-tool` (admin), `list-activity-log-tool` (admin)                                                                                                                                                                        | `update-settings-tool`, `trigger-github-sync-tool`, `create-export-tool`                                                                                                                                                                                                     |
| Interactions               | `get-targeting-catalog-tool`, `get-component-attributes-tool`, `list-interactions-tool`, `get-interaction-tool`, `list-interaction-revisions-tool`, `get-interaction-revision-tool`, `get-interaction-report-tool`, `project-interaction-reach-tool`, `simulate-interaction-tool`, `get-interaction-preview-url-tool` | `create-interaction-tool`, `update-interaction-tool`, `duplicate-interaction-tool`, `unpublish-interaction-tool`, `delete-interaction-tool`, `restore-interaction-tool`, `force-delete-interaction-tool`, `restore-interaction-revision-tool`, `scan-page-selectors-tool`    |
| Cohorts and meters         | `list-cohorts-tool`, `get-cohort-tool`, `list-cohort-revisions-tool`, `get-cohort-revision-tool`, `list-meters-tool`                                                                                                                                                                                                  | `create-cohort-tool`, `update-cohort-tool`, `delete-cohort-tool`, `restore-cohort-revision-tool`, `create-meter-tool`, `update-meter-tool`, `delete-meter-tool`                                                                                                              |
| Segments                   | `list-segments-tool`, `get-segment-tool`, `sample-segment-members-tool`, `preview-segment-tool`                                                                                                                                                                                                                       | `create-segment-tool`, `update-segment-tool`, `duplicate-segment-tool`, `delete-segment-tool`                                                                                                                                                                                |
| A/B tests                  | `list-experiments-tool`, `get-experiment-tool`, `get-experiment-results-tool`                                                                                                                                                                                                                                         | `create-experiment-tool`, `update-experiment-tool`, `delete-experiment-tool`, `start-experiment-tool`, `end-experiment-tool`, `roll-out-experiment-variant-tool`                                                                                                             |
| Access                     | `list-tenant-users-tool` (admin), `list-api-keys-tool` (admin)                                                                                                                                                                                                                                                        | `invite-tenant-user-tool`, `update-tenant-user-role-tool`, `remove-tenant-user-tool`, `resend-invitation-tool`                                                                                                                                                               |
| OAuth clients              | `list-o-auth-clients-tool` (admin), `get-oauth-client-tool` (admin)                                                                                                                                                                                                                                                   | `create-oauth-client-tool`, `update-oauth-client-tool`, `regenerate-oauth-client-secret-tool`, `delete-oauth-client-tool`                                                                                                                                                    |
| Geo, GitHub, and content   | `list-content-tool`, `get-geo-provider-settings-tool` (admin), `get-github-sync-log-tool` (admin), `list-github-repositories-tool` (admin)                                                                                                                                                                            | `update-geo-provider-settings-tool`                                                                                                                                                                                                                                          |

`search_tools` returns each tool's description and input schema, so it is the reference for arguments. The analytics tools are covered in [Analytics API and MCP](/product/analytics/api-and-mcp.md).

The report-subscription tools — `subscribe-analytics-report-tool` and `unsubscribe-analytics-report-tool` — are the one exception to the admin-only rule for writes stated above and under [Permissions](#permissions). They follow the report's own access instead: anyone who can view a report may subscribe or unsubscribe their own address, and members and admins may manage other addresses. A write-access connection (OAuth with write access, or a full-access key) is still required.

Delete tools take a required `confirm` boolean. Without `confirm: true` they return an error naming what would be deleted and change nothing. `delete-template-tool` archives a template, and `restore-template-tool` brings it back. Permanent deletion stays in the dashboard.

note

GitHub-synced templates are read-only and cannot be modified through the MCP server.

##### Integration tools[​](#integration-tools "Direct link to Integration tools")

These tools only appear in `search_tools` while their package is enabled for the tenant. Every one of them except `get-property-edge-settings-tool` requires the admin role. Connecting or disconnecting a Cloudflare, Fundraise Up, or SFMC account stays in the dashboard, and credentials are never returned.

| Package         | Read                                                                | Write                                                                                                                         |
| --------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Allegro Edge    | `get-edge-settings-tool` (admin), `get-property-edge-settings-tool` | `update-edge-settings-tool`, `update-property-edge-settings-tool`, `deploy-property-edge-tool`, `rollback-property-edge-tool` |
| Fundraise Up    |                                                                     | `sync-fundraise-up-tool`                                                                                                      |
| Marketing Cloud |                                                                     | `update-sfmc-settings-tool`, `update-property-sfmc-settings-tool`, `refresh-sfmc-columns-tool`                                |

`deploy-property-edge-tool` and `rollback-property-edge-tool` take a required `confirm` boolean and queue nothing without `confirm: true`. `sync-fundraise-up-tool` shares the dashboard's limit of one sync every 15 minutes per connection. `update-sfmc-settings-tool` accepts the SFMC client id and secret but only reports whether each is set.

##### Building interactions[​](#building-interactions "Direct link to Building interactions")

The interaction tools give a client the same abilities as the interaction builder in the dashboard: write interactions with their actions and journeys, save reusable cohorts, set up content meters, and run A/B tests. The recommended flow is:

1. Call `get-targeting-catalog-tool` to see the attributes, operators, segments, cohorts, meters, A/B tests, products, templates, and saved page areas you can target with.
2. Call `create-interaction-tool` or `update-interaction-tool` to save the interaction as a draft.
3. Check the audience with `project-interaction-reach-tool`, which estimates how many visitors the journeys would reach, and `simulate-interaction-tool`, which runs the journeys against visitor attributes you supply and shows which journey matched and why.
4. Use `get-interaction-preview-url-tool` for a 30-minute link that previews the draft on a page of your site.
5. Publish by calling `update-interaction-tool` with `status` set to `published`. Use `unpublish-interaction-tool` to take it back to a draft.

`scan-page-selectors-tool` suggests page areas for a public URL and a short description, and saves the verified ones so you can target them. Edits to interactions and cohorts record a revision, and `update-interaction-tool` and `update-cohort-tool` accept a `revision_note`. Use the revision tools to review history or restore an earlier version.

note

Interaction, cohort, meter, and A/B test writes need the admin role. Writes to an interaction or cohort are refused while someone else is editing it in the dashboard, the same as in the dashboard itself; try again once they finish. The server never takes over or releases a dashboard edit lock.

note

`project-interaction-reach-tool`, `get-interaction-report-tool`, and `get-experiment-results-tool` read from analytics. When analytics isn't configured for your tenant they return `available: false` with a reason instead of numbers. Reach projections also need the targeting projections feature turned on for your tenant.

##### `get-audience-member-tool` includes[​](#get-audience-member-tool-includes "Direct link to get-audience-member-tool-includes")

`get-audience-member-tool` always returns the member's core profile, including `last_seen_at` (the ISO 8601 timestamp of their most recent event, or `null` when they have no events). Pass any of the following in `include` to expand the response:

| Include             | Adds                                                                                                     |
| ------------------- | -------------------------------------------------------------------------------------------------------- |
| `entitlements`      | The member's entitlements.                                                                               |
| `purchases`         | The member's purchases.                                                                                  |
| `events`            | The member's recent events.                                                                              |
| `meta`              | The member's stored metadata.                                                                            |
| `external_profiles` | Linked external profiles, each with `provider` and the raw `data` synced from that provider.             |
| `foreign_keys`      | The member's external identifiers as `key`/`value` pairs.                                                |
| `sync_status`       | Per-provider sync state: `last_synced_at`, `next_run_at`, `cadence`, `max_age_on_login`, and `is_fresh`. |
| `sessions`          | The member's sessions, each with `is_authenticated`, `authenticated_at`, and `created_at`.               |

##### `get-settings-tool` sections[​](#get-settings-tool-sections "Direct link to get-settings-tool-sections")

`get-settings-tool` returns tenant configuration grouped into sections so you only fetch what you need. Pass `sections` to choose which groups to return. When omitted, all lightweight sections are returned. The two heavy sections — `preview_css` and `embed_snippet` — are never returned by default and must be requested explicitly.

| Section         | Returns                                                                                                                                                | In default response |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- |
| `general`       | Tenant `name` and `timezone`                                                                                                                           | Yes                 |
| `web`           | `cors_allowed_origins` and `cookie_domain`                                                                                                             | Yes                 |
| `email`         | Email `provider` name and `mail_from_address` / `mail_from_name`                                                                                       | Yes                 |
| `auth`          | Enabled `login_providers` in display order, plus each provider's configuration status — which fields are set, and non-secret values such as client IDs | Yes                 |
| `captcha`       | The selected captcha `provider`, whether captcha is `enabled`, and each provider's configuration status and non-secret values                          | Yes                 |
| `branding`      | Whether branding is `configured`, the `logo_url`, and the design `tokens` and per-component overrides                                                  | Yes                 |
| `payments`      | The `active` payment provider and the list of `available` providers                                                                                    | Yes                 |
| `packages`      | The `available` packages and the names of those `enabled`                                                                                              | Yes                 |
| `github_sync`   | Whether templates sync with GitHub (`enabled`) and the `repository`                                                                                    | Yes                 |
| `sign_in_page`  | The sign-in page `header_html` and `footer_html` (sanitized)                                                                                           | Yes                 |
| `preview_css`   | The tenant preview CSS `content`                                                                                                                       | No (opt in)         |
| `embed_snippet` | The current embed snippet `content` and `updated_at`                                                                                                   | No (opt in)         |

The sections above are the core set. Installed packages may contribute additional sections, so the tool's input schema (its `sections` enum) is the authoritative list of what's available on a given tenant.

note

Secrets are never returned. The `email` section excludes the SES key, secret, and region; the `auth` section returns provider names and non-secret configuration such as client IDs, but never encrypted credentials. Use `get-embed-snippet-tool` when you need embed snippet revision history.

#### Writing settings[​](#writing-settings "Direct link to Writing settings")

The `update-settings-tool` tool changes tenant configuration, mirroring the settings an admin can edit in the dashboard. It takes a section key and a `values` object, and returns the updated section in the same shape `get-settings-tool` would — so you can read the result back without a second call.

Only some sections are writable:

| Section        | Writable fields                                                                                                                          |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `general`      | `name`, `timezone`                                                                                                                       |
| `web`          | `cors_allowed_origins`, `cookie_domain`                                                                                                  |
| `email`        | `mail_from_address`, `mail_from_name`                                                                                                    |
| `auth`         | `login_providers` — the display order, as a list of provider slugs                                                                       |
| `captcha`      | `provider` (a provider slug, or `none` to turn captcha off) and `providers` (`{ "recaptcha": { "site_key": "...", "min_score": 0.5 } }`) |
| `sign_in_page` | `header_html`, `footer_html`                                                                                                             |
| `packages`     | `enabled` — the full list of enabled package names, which replaces the current list                                                      |
| `preview_css`  | `content`                                                                                                                                |

Each writer runs the same validation rules as the matching admin form and persists the value the same way, so `update-settings-tool` can't put a tenant into a state the dashboard couldn't. Secrets stay in the dashboard: login provider credentials, the captcha secret key, and SES keys are rejected. A login provider counts as enabled once its credentials are complete, so turning one on also happens in the dashboard. `payments`, `github_sync`, and `branding` have no writer here; use `update-branding-tool` for branding.

Field names are the ones `get-settings-tool` returns, which are not always the admin form's labels. An unknown field is rejected with an error listing the accepted fields — so sending `organization_name` to the `general` section returns an error naming `name` rather than silently doing nothing.

note

`update-settings-tool` requires the **admin** role, like every other write tool.

#### Built-in Prompts[​](#built-in-prompts "Direct link to Built-in Prompts")

The server ships three prompts that instruct the AI on how to complete common workflows:

| Prompt             | Input                | What it does                                                   |
| ------------------ | -------------------- | -------------------------------------------------------------- |
| `summarize-member` | Email address        | Fetches the full member profile and writes a summary           |
| `grant-access`     | Email + product name | Walks through lookup → check → grant with duplicate protection |
| `review-templates` | *(none)*             | Lists all templates, groups by status, and flags issues        |

#### Permissions[​](#permissions "Direct link to Permissions")

Write tools, and the read tools marked admin above, require the authenticated user to have the **admin** role on the tenant, or a full-access organization or platform API key. Other read tools are available to all authenticated tenant members. A caller without the admin role gets a tool error ("You do not have admin permission to modify data in this tenant.") instead of the result.

When you sign in with OAuth, the client also needs the write access you can grant on the consent screen; a read-only connection gets an error from every write tool, even for an admin.

A tenant always keeps at least one admin: `remove-tenant-user-tool` and `update-tenant-user-role-tool` refuse to remove or demote the last one.

#### Landlord MCP[​](#landlord-mcp "Direct link to Landlord MCP")

In addition to each tenant's own server, the platform exposes a landlord MCP server for managing tenants across the platform, at `https://<platform-domain>/mcp`. It's the same `/mcp` path as a tenant server, but on the platform domain instead of a tenant host — tenant hosts continue to reach their own tenant's server as described above.

##### Platform API Keys[​](#platform-api-keys "Direct link to Platform API Keys")

The landlord MCP server accepts a super admin signed in with [OAuth](/developer/guides/mcp-oauth.md), or a platform API key created under **Global Settings → API Keys** in the landlord admin. Include a key as a Bearer header on every request:

```http
Authorization: Bearer <platform-token>

```

Organization keys and user-owned API keys are rejected with a `403 Forbidden` ("This endpoint requires a platform-owned API key or OAuth sign-in as a super admin."). The platform key must also grant read access (`*:read`) or full access (`*`); a platform key scoped to individual resources is rejected with a `403 Forbidden`.

##### Connecting a Client[​](#connecting-a-client-1 "Direct link to Connecting a Client")

Add an entry to your client's MCP server configuration, replacing `<platform-domain>` and `<platform-token>` with your actual values:

```json
{
    "mcpServers": {
        "allegro-landlord": {
            "url": "https://<platform-domain>/mcp",
            "headers": {
                "Authorization": "Bearer <platform-token>"
            }
        }
    }
}

```

##### Landlord Tools[​](#landlord-tools "Direct link to Landlord Tools")

| Tool                  | Input                                                                                                                                                         | Returns                                                                                                                                                            |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `list-tenants`        | *(none)*                                                                                                                                                      | `items` — each tenant's `id`, `name`, `slug`, `domain`, and `created_at`, ordered by name — and `count`                                                            |
| `create-tenant`       | `name` (required; letters, numbers, spaces, and dashes); `slug` (optional — derived from `name` when omitted, always slugified, minimum 3 characters, unique) | The created tenant's `id`, `name`, `slug`, `domain`, and `created_at`                                                                                              |
| `search-tenant-tools` | `tenant` (slug, required); `query` (optional — case-insensitive filter on tool name and description)                                                          | `items` — each matching tool's `name`, `title`, `description`, `inputSchema`, `outputSchema` (included when the tool defines one), and `annotations` — and `count` |
| `call-tenant-tool`    | `tenant` (slug); `tool` (tenant tool name); `arguments` (object, optional)                                                                                    | The tenant tool's own result                                                                                                                                       |

`list-tenants` and `search-tenant-tools` are read-only. `create-tenant` always writes. Tools called through `call-tenant-tool` read or write depending on the tenant tool.

##### Workflow[​](#workflow "Direct link to Workflow")

The landlord tools are designed to be chained: call `list-tenants` to find a tenant's slug, `search-tenant-tools` with that slug to discover what the tenant's own server offers, then `call-tenant-tool` with the slug, tool name, and arguments to run it.

```json
{
    "tenant": "example-tenant",
    "tool": "list-products-tool",
    "arguments": {
        "search": "digital"
    }
}

```

`call-tenant-tool` only runs tools that exist on the target tenant's own server. Landlord tool names and unknown tool names both return an error.

##### Landlord Permissions[​](#landlord-permissions "Direct link to Landlord Permissions")

`create-tenant` and any tenant write tool called through `call-tenant-tool` require a full-access (`*`) platform key, or an OAuth connection with write access. A read-only key or connection receives an error — for tenant writes, the tenant's own message: "You do not have admin permission to modify data in this tenant."

`call-tenant-tool` returns an error while the target tenant is in maintenance mode.

All platform keys share one MCP rate limit (120 requests per minute). Each signed-in user has their own.

#### Related[​](#related "Direct link to Related")

* [Connecting an MCP client with OAuth](/developer/guides/mcp-oauth.md) — Signing in without an API key
* [API Authentication](/developer/api/authentication.md) — Generating the PAT used to authenticate MCP requests


---

### Connecting an MCP Client with OAuth

AI clients that support MCP authorization — Claude, Cursor, and VS Code among them — can sign in to Allegro's [MCP server](/developer/guides/mcp.md) with OAuth. You add the server's URL, the client opens a browser window, you sign in to Allegro and approve the connection, and the client receives a token that acts as you. There is no API key to create, paste, or rotate.

#### Server URLs[​](#server-urls "Direct link to Server URLs")

| Server   | URL                               | Who can connect                                       |
| -------- | --------------------------------- | ----------------------------------------------------- |
| Tenant   | `https://acme.allegrocdp.com/mcp` | Members of the `acme` organization (and super admins) |
| Landlord | `https://allegrocdp.com/mcp`      | Super admins                                          |

Use the platform subdomain, not a custom domain. Custom domains such as `members.acme.com` serve your audience's sign-in, not MCP.

#### Connecting[​](#connecting "Direct link to Connecting")

1. Add the URL to your client as a remote MCP server. Leave the authentication settings empty — the client discovers everything it needs from the URL.
2. When the client asks you to sign in, it opens Allegro in your browser. Sign in to the dashboard if you aren't already.
3. Review the consent screen. It names the client, the organization (or **Allegro platform** for the landlord server), your account, and the website Allegro will send you back to. Only continue if you recognize that website.
4. Choose what the client can do, then click **Allow**.

Claude Desktop, for example, only needs the URL:

```json
{
    "mcpServers": {
        "allegro": {
            "url": "https://acme.allegrocdp.com/mcp"
        }
    }
}

```

#### Read and write access[​](#read-and-write-access "Direct link to Read and write access")

| Access      | Scope       | Who can grant it                                                            |
| ----------- | ----------- | --------------------------------------------------------------------------- |
| Read data   | `mcp:read`  | Everyone who can connect; always included                                   |
| Change data | `mcp:write` | Organization admins on a tenant server; super admins on the landlord server |

The consent screen only offers **Change data** when the client asks for it and you are allowed to grant it. Leave it unticked to keep the client read-only.

A connection never has more access than you do. Write tools check your role on every call, so a client you connected as an admin loses write access as soon as you are no longer an admin, even if you granted **Change data**.

#### Tokens and sessions[​](#tokens-and-sessions "Direct link to Tokens and sessions")

Access tokens last one hour, and clients refresh them on their own. A connection stays signed in as long as the client is used at least once every 30 days; after 30 days without use, you sign in again. Each connection only works on the server you connected it to: a token for `acme.allegrocdp.com` is refused by every other organization's server and by the landlord server.

#### Disconnecting[​](#disconnecting "Direct link to Disconnecting")

Open **Settings → Connected apps** in the dashboard to see each client you've connected, which organization it can reach, whether it can change data, and when it was last used. Click **Disconnect** to revoke it immediately.

Allegro also revokes connections for you when:

* you are removed from an organization (its connections end),
* you lose super admin access (landlord connections end), or
* your account is deleted (all connections end).

#### How discovery works[​](#how-discovery-works "Direct link to How discovery works")

You don't need this to connect a client, but it helps when debugging one. The server follows the [MCP authorization specification](https://modelcontextprotocol.io/specification/draft/basic/authorization):

1. An unauthenticated request to `/mcp` returns `401` with a `WWW-Authenticate` header pointing at `/.well-known/oauth-protected-resource/mcp`.
2. That document names the same host as the authorization server.
3. The client reads `/.well-known/oauth-authorization-server` on that host for the authorize, token, and registration endpoints.
4. The client registers itself at `/oauth/register` (dynamic client registration) and signs you in with the authorization code flow and PKCE (`S256` only).

Registration is open and grants nothing by itself; a client can only act as you after you approve it on the consent screen.

API keys still work

OAuth is an addition, not a replacement. Organization and platform API keys keep working as described in the [MCP Server](/developer/guides/mcp.md) guide, and are still the right choice for unattended scripts and servers. Like OAuth, they only work on the platform subdomain: a custom-domain or per-property `/mcp` URL returns `404`.

#### Related[​](#related "Direct link to Related")

* [MCP Server](/developer/guides/mcp.md) — Tools, permissions, and API key authentication


---

### OAuth 2.0

Allegro lets your service sign a member in through Allegro and receive that member's session token — the same RS256 JWT the browser SDK uses to act as the member. This is the flow to reach for when you run your own application (a mobile app, a companion site, a partner portal) and want "Sign in with Allegro" without building your own login for the tenant's audience.

Allegro implements the standard **OAuth 2.0 Authorization Code flow**, with PKCE supported and strongly recommended. PKCE is optional by default; a tenant can require it for your client (see [PKCE](#pkce)). The member authenticates on an Allegro-hosted page, which emails a sign-in link and a one-time code in the same message — the member can either click the link or type the code back into the page — alongside any social providers the tenant has enabled. Your backend then exchanges a short-lived code for the member's JWT.

Why both a link and a code

A member who opens the emailed link in a different browser than the one holding the authorization request would otherwise be stranded, because the request lives in the original tab. Offering the one-time code gives them a way to finish in the tab they started in.

The token never travels through the browser

Only a short-lived, single-use authorization code passes through the redirect URL, and that code is useless without your client secret (and your PKCE verifier when PKCE is in use). The JWT itself is only ever returned to your backend over a direct server-to-server request.

#### Before you begin[​](#before-you-begin "Direct link to Before you begin")

A tenant administrator registers an OAuth client for you from the tenant's admin settings and gives you:

| Value           | Description                                                                                                                               |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id`     | Public identifier for your integration. Safe to include in browser redirects.                                                             |
| `client_secret` | Secret shown **once** at creation. Store it securely on your backend; it is never exposed in the browser.                                 |
| Redirect URI(s) | The exact URLs Allegro is allowed to send the member back to.                                                                             |
| Allowed origins | The exact browser origins allowed to call the [session probe](/developer/guides/oauth-silent-sign-in.md). Only needed for silent sign-in. |

Redirect URIs are matched **exactly** — no wildcards, no trailing-slash flexibility, no query-string variance. Each URI you use must be registered with the client ahead of time and must be HTTPS (except `http://localhost` and `http://127.0.0.1` during local development).

A tenant administrator can edit a client after creation — updating its redirect URIs, renaming it, enabling or disabling it, and toggling whether PKCE is required — from the tenant's OAuth client settings. The client secret is not editable; it can only be regenerated (which invalidates the previous secret).

Everything below happens against the tenant's **custom domain**, for example `https://members.acme.com`, or a property's custom domain when you sign members in to a specific property. OAuth is only available once a custom domain is set up; the `acme.allegrocdp.com` platform hostnames don't serve it. You can confirm the endpoints programmatically from the [discovery documents](#discovery), and you should — see [Custom domain and issuer](#custom-domain-and-issuer).

If your integration also needs to know whether a visitor is *already* signed in — without sending them through the sign-in page — see [Silent sign-in](/developer/guides/oauth-silent-sign-in.md).

#### The flow[​](#the-flow "Direct link to The flow")

```text
Your app / backend            Member's browser              Allegro (tenant domain)
     │                              │                               │
     │  1. redirect to authorize    │                               │
     │─────────────────────────────>│  GET /oauth/authorize         │
     │                              │──────────────────────────────>│  validate client_id
     │                              │  2. member signs in            │  + redirect_uri
     │                              │<───────── login page ──────────│
     │                              │                               │
     │                              │  3. redirect back with code    │
     │  redirect_uri?code=&state=   │<──────────────────────────────│
     │<─────────────────────────────│                               │
     │                              │                               │
     │  4. POST /oauth/token  (server-to-server, no browser)         │
     │───────────────────────────────────────────────────────────────>│  verify secret,
     │                                                               │  code + PKCE
     │  5. { access_token: <member JWT>, token_type, expires_in }    │
     │<───────────────────────────────────────────────────────────────│

```

#### Step 1 — Redirect the member to the authorize endpoint[​](#step-1--redirect-the-member-to-the-authorize-endpoint "Direct link to Step 1 — Redirect the member to the authorize endpoint")

```text
GET https://<your-tenant-domain>/oauth/authorize

```

Generate a random `state` value and store it so you can verify it when the member returns. If you are using PKCE — recommended, and required when the tenant has enabled it for your client — generate the code verifier and challenge first; see [PKCE](#pkce).

Send the member's browser to the authorize endpoint with the following query parameters:

| Parameter               | Required   | Description                                                                                                                                                                  |
| ----------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id`             | Yes        | Your client identifier.                                                                                                                                                      |
| `redirect_uri`          | Yes        | One of your registered redirect URIs. Matched exactly.                                                                                                                       |
| `response_type`         | Yes        | Must be `code`.                                                                                                                                                              |
| `code_challenge`        | If enabled | The PKCE challenge (see [PKCE](#pkce)). Required unless PKCE is disabled for your client.                                                                                    |
| `code_challenge_method` | If enabled | Must be `S256` when `code_challenge` is present.                                                                                                                             |
| `state`                 | No         | An opaque value round-tripped back to you unchanged. Use it for CSRF protection.                                                                                             |
| `scope`                 | No         | Reserved for future use.                                                                                                                                                     |
| `provider`              | No         | A login provider slug, such as `google`. Skips the sign-in page and sends the member straight to that provider. See [Skipping the sign-in page](#skipping-the-sign-in-page). |
| `login_hint`            | No         | The member's email address, if you already know it. Prefills the email field on the sign-in page. Ignored if it is not a valid email address.                                |

```js
const params = new URLSearchParams({
    client_id: CLIENT_ID,
    redirect_uri: 'https://your-app.example.com/callback',
    response_type: 'code',
    // Include code_challenge / code_challenge_method only when using PKCE.
    code_challenge: codeChallenge,
    code_challenge_method: 'S256',
    state,
});

const authorizeUrl = `https://<your-tenant-domain>/oauth/authorize?${params}`;
// Redirect the member's browser to authorizeUrl.

```

Allegro renders a sign-in page hosting the tenant's configured login methods. If the member already has a valid session on the tenant domain, they see a "Continue as {email}" prompt instead. Either way the member takes one explicit action, after which Allegro redirects the browser back to your `redirect_uri`.

##### Skipping the sign-in page[​](#skipping-the-sign-in-page "Direct link to Skipping the sign-in page")

If your app shows its own "Sign in with Google" button, send `provider=google` and Allegro redirects the member to Google without rendering its own page. After Google, the member comes back to Allegro and on to your `redirect_uri` without a further click. This uses full-page redirects throughout, so it works where popups are unreliable, such as in-app browsers on iOS.

`provider` is a hint, not a requirement. Allegro shows its usual sign-in page instead when the provider is unknown or not enabled for the tenant, and shows the "Continue as {email}" prompt when the member is already signed in. It has no effect with `prompt=none`.

Invalid requests never redirect

If the `client_id` is unknown or disabled, or the `redirect_uri` is not on the client's allowlist, Allegro renders an error page and **does not redirect**. This is deliberate — it prevents an attacker from using a malformed request to bounce a code to an unapproved destination. Double-check that the exact redirect URI you send is registered.

#### Step 2 — Handle the redirect back[​](#step-2--handle-the-redirect-back "Direct link to Step 2 — Handle the redirect back")

Once the member authenticates, Allegro redirects the browser to:

```text
https://your-app.example.com/callback?code=<authorization-code>&state=<state>

```

Verify that `state` matches the value you generated in step 1, then take the `code`. The code is single-use and expires **10 minutes** after it is issued. Exchange it as soon as the member lands on your callback; nothing is gained by holding it.

#### Step 3 — Exchange the code for a token[​](#step-3--exchange-the-code-for-a-token "Direct link to Step 3 — Exchange the code for a token")

From your **backend** (never the browser — this request carries your client secret), POST to the token endpoint:

```text
POST https://<your-tenant-domain>/oauth/token
Content-Type: application/x-www-form-urlencoded

```

| Parameter       | Required   | Description                                                                                     |
| --------------- | ---------- | ----------------------------------------------------------------------------------------------- |
| `grant_type`    | Yes        | Must be `authorization_code`.                                                                   |
| `code`          | Yes        | The authorization code from step 2.                                                             |
| `redirect_uri`  | Yes        | The same redirect URI used in step 1. Matched exactly.                                          |
| `client_id`     | Yes        | Your client identifier.                                                                         |
| `client_secret` | Yes        | Your client secret.                                                                             |
| `code_verifier` | If enabled | The PKCE verifier (see [PKCE](#pkce)). Required whenever you sent a `code_challenge` in step 1. |

Credentials go in the form body

The only supported client authentication method is `client_secret_post`: send `client_id` and `client_secret` as form fields. An HTTP `Authorization: Basic` header is not read, so a library configured for `client_secret_basic` will fail with `invalid_client`.

```bash
curl https://<your-tenant-domain>/oauth/token \
  -d grant_type=authorization_code \
  -d code="<authorization-code>" \
  -d redirect_uri="https://your-app.example.com/callback" \
  -d client_id="<your-client-id>" \
  -d client_secret="<your-client-secret>" \
  -d code_verifier="<your-code-verifier>"

```

On success you receive the member's JWT:

```json
{
    "access_token": "<member-jwt>",
    "token_type": "Bearer",
    "expires_in": 31536000
}

```

| Field          | Description                                         |
| -------------- | --------------------------------------------------- |
| `access_token` | The member's RS256 JWT. Use it as a `Bearer` token. |
| `token_type`   | Always `Bearer`.                                    |
| `expires_in`   | Token lifetime in seconds.                          |

Those three fields are the whole response. There is no `refresh_token` and no `id_token` — start a new authorization request when the token expires, and read the member's identity from the JWT's own claims.

The token represents a **fresh, independent session** minted for your integration. It appears among the member's sessions and can be revoked without affecting the member's own browser session. The token also carries an `azp` (authorized party) claim set to your `client_id`, so a partner-issued token is distinguishable from a browser SDK session token.

#### Step 4 — Use the token[​](#step-4--use-the-token "Direct link to Step 4 — Use the token")

The `access_token` is a standard Allegro member JWT. Send it as a bearer token to the [Browser SDK API](/session-api/), or verify it yourself against the tenant's public keys. See the [JWT Verification guide](/developer/guides/jwt.md) for the token structure, the JWKS endpoint, and verification examples.

##### What a partner token cannot do[​](#what-a-partner-token-cannot-do "Direct link to What a partner token cannot do")

A token carrying `azp` acts **as** the member but may not manage the session it rides on. Two Session API endpoints refuse it:

| Endpoint                    | Why it is refused                                                                        |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| `DELETE /api/session`       | Signing out would end the member's own session on the tenant, not just your integration. |
| `POST /api/session/refresh` | The re-minted token would drop `azp`, turning a partner token into a first-party one.    |

Both answer `403` with the error code `PARTNER_TOKEN_NOT_PERMITTED`:

```json
{
    "data": {
        "message": "This endpoint cannot be called with a partner-issued token.",
        "code": "PARTNER_TOKEN_NOT_PERMITTED"
    },
    "status": 403
}

```

Every other endpoint that hands you back a JWT — form submission, setting a user attribute — re-mints it with `azp` intact, so a partner token stays a partner token for its whole life. Get a new token by running the authorization flow again.

#### Discovery[​](#discovery "Direct link to Discovery")

Allegro advertises its endpoints in two discovery documents, so OAuth-aware libraries can configure themselves automatically:

| Document                                  | Specification                                     |
| ----------------------------------------- | ------------------------------------------------- |
| `/.well-known/openid-configuration`       | OpenID Connect Discovery 1.0                      |
| `/.well-known/oauth-authorization-server` | RFC 8414, OAuth 2.0 Authorization Server Metadata |

Fetch whichever one your library reaches for. They are generated from the same source and agree on every field except `subject_types_supported`, which only the OpenID document carries.

```text
GET https://<your-tenant-domain>/.well-known/oauth-authorization-server

```

```json
{
    "issuer": "https://<your-tenant-domain>",
    "authorization_endpoint": "https://<your-tenant-domain>/oauth/authorize",
    "token_endpoint": "https://<your-tenant-domain>/oauth/token",
    "jwks_uri": "https://<your-tenant-domain>/.well-known/jwks.json",
    "response_types_supported": ["code"],
    "grant_types_supported": ["authorization_code"],
    "token_endpoint_auth_methods_supported": ["client_secret_post"],
    "code_challenge_methods_supported": ["S256"],
    "prompt_values_supported": ["none"]
}

```

Both documents are cacheable for a day (`Cache-Control: public, max-age=86400`).

Every value is claimed on behalf of something the server really implements. `response_types_supported` is `["code"]` alone: the implicit flow is not supported, and `response_type=token` is rejected. `prompt_values_supported` is `["none"]`, covered in [Silent sign-in](/developer/guides/oauth-silent-sign-in.md).

note

No `id_token` is issued, and no signing algorithm is advertised

Allegro is an OAuth 2.0 authorization server that serves the OpenID discovery document for the convenience of clients that look there first. It issues no `id_token`, so both documents deliberately omit `id_token_signing_alg_values_supported` even though OpenID Connect Discovery lists that field as required. A strict OIDC client library may reject the document for that reason; treat Allegro as a plain OAuth 2.0 server and read the member's identity from the access token instead. The algorithm behind the tokens Allegro does issue is discoverable from the `alg` on each key at `/.well-known/jwks.json` — see the [JWT Verification guide](/developer/guides/jwt.md).

#### Custom domain and issuer[​](#custom-domain-and-issuer "Direct link to Custom domain and issuer")

OAuth runs only on a custom domain: the tenant's, or a property's when you sign members in to that property. That domain serves the OAuth and discovery endpoints, and it is the `issuer` in both discovery documents and the `iss` and `aud` claims in every token Allegro issues, which is what lets a client verify a token against the document it discovered.

The platform hostnames (`acme.allegrocdp.com` and the per-property `acme--news.allegrocdp.com`) don't serve audience OAuth at all. Every OAuth and discovery path answers `404` there, except `/.well-known/jwks.json`.

The **key set is the exception**: it names no host, so it is served everywhere, including the platform hostnames.

The issuer changes when a tenant's custom domain changes

If you pin `iss` when verifying tokens, a tenant that adds, changes, or removes its custom domain changes the value you are pinning, and every token verification starts failing. Operators should tell integrators before making that change; on your side, prefer reading `issuer` from discovery over hard-coding it.

#### Errors[​](#errors "Direct link to Errors")

The token endpoint returns a `400` response with an OAuth-style error code:

| Error            | Cause                                                                                                                                                     |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_client` | The `client_id` is unknown or disabled, or the `client_secret` is wrong.                                                                                  |
| `invalid_grant`  | The code is unknown, expired, or already used; the `redirect_uri` does not match the one bound to the code; or the `code_verifier` fails PKCE validation. |

```json
{ "error": "invalid_grant" }

```

Because codes are single-use and short-lived, a retried or double-submitted exchange returns `invalid_grant`. Start a new authorization request if that happens. Two concurrent exchanges of the same code are resolved the same way: exactly one gets a token and the other gets `invalid_grant`.

The authorize endpoint reports its errors differently. Once the `client_id` and `redirect_uri` are known-good, a malformed request is reported back to your callback as a query parameter, echoing `state`:

```text
https://your-app.example.com/callback?error=invalid_request&state=<state>

```

| Error             | Cause                                                                                                                            |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_request` | An unsupported `prompt` value, or a missing `code_challenge` on a client that requires PKCE.                                     |
| `login_required`  | A `prompt=none` request on a browser with no signed-in session. See [Silent sign-in](/developer/guides/oauth-silent-sign-in.md). |

An unknown or disabled `client_id`, or a `redirect_uri` that is not registered, never redirects at all — see the warning in [step 1](#step-1--redirect-the-member-to-the-authorize-endpoint).

#### PKCE[​](#pkce "Direct link to PKCE")

PKCE (`S256`) is **strongly recommended**. It is optional by default; a tenant administrator can require it for an individual client from the client's settings. Leaving it optional accommodates a server-side integration that authenticates with its client secret and cannot generate a verifier. Regardless of the requirement, if you send a `code_challenge` it is always enforced at the token endpoint (you cannot start a PKCE-protected flow and then drop the verifier), so we recommend using PKCE whenever your integration can.

When you use PKCE, generate a random **code verifier** and derive its **code challenge** before you redirect the member in [step 1](#step-1--redirect-the-member-to-the-authorize-endpoint).

* The verifier is a random string between 43 and 128 characters.
* The challenge is the base64url-encoded SHA-256 hash of the verifier, with padding removed. The `S256` method is required.

```js
import crypto from 'node:crypto';

const base64url = (buffer) =>
    buffer
        .toString('base64')
        .replace(/\+/g, '-')
        .replace(/\//g, '_')
        .replace(/=+$/, '');

const codeVerifier = base64url(crypto.randomBytes(32));
const codeChallenge = base64url(
    crypto.createHash('sha256').update(codeVerifier).digest(),
);

```

Send `code_challenge` (with `code_challenge_method=S256`) on the authorize request in [step 1](#step-1--redirect-the-member-to-the-authorize-endpoint), and keep the `code_verifier` on your backend (or in secure session storage) to send on the token exchange in [step 3](#step-3--exchange-the-code-for-a-token).

#### Security notes[​](#security-notes "Direct link to Security notes")

* **PKCE (`S256`) is strongly recommended.** It is optional by default; a tenant can require it for your client. Whenever a `code_challenge` is sent, a matching `code_verifier` is required at the token endpoint.
* Authorization codes are single-use, expire in 10 minutes, and are bound to the client, the exact `redirect_uri`, and the PKCE challenge.
* Redirect URIs use **exact-match** allowlisting — register every URI you intend to use.
* Always send and verify `state` to protect against CSRF.
* Keep the `client_secret` and `code_verifier` on your backend. The only value that legitimately passes through the browser is the authorization code.
* Read the endpoints from a [discovery document](#discovery) rather than hard-coding them, so a tenant's move to a custom domain does not break your integration.

#### Related[​](#related "Direct link to Related")

* [Silent sign-in](/developer/guides/oauth-silent-sign-in.md) — Find out whether a visitor is already signed in, without sending them to the sign-in page
* [JWT Verification](/developer/guides/jwt.md) — Token structure, JWKS, and verification examples
* [Member Authentication](/developer/guides/authentication.md) — How Allegro sessions work


---

### Silent sign-in

A visitor lands on your site. They already signed in to Allegro somewhere else — another site under the same parent domain, or an earlier visit — and you want to greet them as a member rather than showing them a sign-in prompt they do not need. Silent sign-in answers "is anyone signed in on this browser?" without interrupting the visitor.

The answer, when it is yes, is a short-lived authorization code that your backend redeems for the member's JWT through the normal [OAuth token endpoint](/developer/guides/oauth.md#step-3--exchange-the-code-for-a-token). Read the [OAuth 2.0 guide](/developer/guides/oauth.md) first — everything here builds on the client registration and the code exchange described there.

#### Two mechanisms[​](#two-mechanisms "Direct link to Two mechanisms")

| Mechanism                           | How it runs                                         | Use it when                                                                                           |
| ----------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [Session probe](#the-session-probe) | Cross-origin `fetch` from your page. No navigation. | Your site and the Allegro host are on different origins. **This is the usual choice.**                |
| [`prompt=none`](#promptnone)        | Top-level redirect through `/oauth/authorize`.      | You already own a full-page redirect in your flow, or your page is same-origin with the Allegro host. |

Both depend on the same prerequisite, and it is the one thing that most often makes silent sign-in look broken.

#### Prerequisite: the session cookie[​](#prerequisite-the-session-cookie "Direct link to Prerequisite: the session cookie")

Allegro's browser SDK stores the member's session JWT in a cookie named `_ALLEGROT`, written client-side with `SameSite=Lax`. Silent sign-in works by reading that cookie on the Allegro host, so the browser has to be willing to send it there.

A `SameSite=Lax` cookie is only attached to a cross-origin request when the two hosts are **same-site** — that is, when they share a registrable domain. And the cookie is only visible to the Allegro host at all if it was written with a `Domain` covering both hosts.

That means an operator must set the tenant's **Cookie Domain** to the shared parent domain. With Cookie Domain set to `.acme.com`, a member who signs in on `community.acme.com` has a cookie the browser will send to `members.acme.com`, and silent sign-in works. Left blank, the cookie is scoped to the exact hostname that served the SDK, and the Allegro host never sees it.

The single most common failure

If the probe returns `unauthenticated` for a visitor you know is signed in, check Cookie Domain before anything else. There is no error and no warning — the browser simply does not send a cookie, and Allegro correctly reports that nobody is signed in on this browser.

Ask the operator to set **Organization Settings → Browser → Cookie Domain** to the parent domain shared by your site and the Allegro host. See [Browser Settings](/developer/administration/browser-settings.md).

Silent sign-in therefore cannot work at all when Allegro is served from a domain unrelated to your site — `app.example.com` calling `members.acme.com` will get `unauthenticated` forever, no matter who is signed in. Those visitors need the [interactive flow](/developer/guides/oauth.md).

#### The session probe[​](#the-session-probe "Direct link to The session probe")

```text
GET https://<your-tenant-domain>/oauth/session?client_id=<your-client-id>

```

The probe is **read-only in every path**. It creates no member, mints no session, and modifies nothing — a visitor who loads your page and leaves has changed nothing in Allegro.

##### The request[​](#the-request "Direct link to The request")

Send it as a credentialed cross-origin `fetch`. The browser supplies `Origin` itself; you cannot set it.

```js
const response = await fetch(
    `https://<your-tenant-domain>/oauth/session?client_id=${CLIENT_ID}`,
    { credentials: 'include' },
);

const session = await response.json();

if (session.status === 'authenticated') {
    // Hand session.code to your own backend to redeem.
    await fetch('/allegro/adopt-session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ code: session.code }),
    });
}

```

`credentials: 'include'` is required. Without it the browser sends no cookie and you will always be told nobody is signed in.

Call the tenant's **custom domain**. The platform hostnames answer with a `404`, which carries no CORS headers, so the fetch fails as a CORS error. See [Custom domain and issuer](/developer/guides/oauth.md#custom-domain-and-issuer).

##### The responses[​](#the-responses "Direct link to The responses")

Somebody is signed in:

```http
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Access-Control-Allow-Origin: https://community.acme.com
Access-Control-Allow-Credentials: true
Vary: Origin

{
    "status": "authenticated",
    "code": "aB3…64-characters…9zQ",
    "expires_in": 30
}

```

Nobody is signed in:

```http
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Access-Control-Allow-Origin: https://community.acme.com
Access-Control-Allow-Credentials: true
Vary: Origin

{ "status": "unauthenticated" }

```

Both are `200`. Nobody being signed in is a normal answer, not an error, so do not treat a non-`authenticated` status as a failure to retry. `Cache-Control: no-store` is set on both, because the first response carries a credential and the second would otherwise be cached as a permanent "no".

| Field        | Present when    | Description                                             |
| ------------ | --------------- | ------------------------------------------------------- |
| `status`     | Always          | `authenticated` or `unauthenticated`.                   |
| `code`       | `authenticated` | A single-use authorization code. Redeem it immediately. |
| `expires_in` | `authenticated` | Seconds the code stays redeemable. Always `30`.         |

##### Why a code and not a token[​](#why-a-code-and-not-a-token "Direct link to Why a code and not a token")

Anything your page can read, a script on your page can steal. A member JWT is a bearer credential: whoever holds it can act as the member until it expires. A 30-second single-use authorization code cannot be spent by whoever holds it, because redeeming it requires the client secret — which only your backend has. So the probe hands the browser the weakest possible thing that still gets your backend a token.

##### Registered origins[​](#registered-origins "Direct link to Registered origins")

The probe only answers a request whose `Origin` header is on the calling client's **allowed origins** list. Origins are matched byte for byte: no wildcards, no suffix matching, no trailing slash. Every site that probes needs its own entry, and a parent domain does not cover its subdomains.

A refusal is a `403` **with no CORS headers at all**:

```http
HTTP/1.1 403 Forbidden
Content-Type: application/json

{ "error": "invalid_request" }

```

Because the CORS headers are absent, the browser surfaces this to your JavaScript as a generic CORS failure and your page cannot tell what was wrong. That is deliberate — a distinguishable response would let anyone enumerate which clients and origins exist. The same `403` covers all of it:

* No `Origin` header on the request
* No `client_id`, or a `client_id` that does not exist
* A client that is disabled
* A client with no registered origins
* An origin that is not registered against **this** client
* An origin that is a suffix of a registered one

When you hit this, the fix is on the Allegro side: ask the operator to add your exact origin to the client's allowed origins.

##### Preflight[​](#preflight "Direct link to Preflight")

A plain credentialed `GET` with no custom headers is a simple request and is not preflighted, so most integrations never see an `OPTIONS`. If yours does add a header that triggers one, the endpoint answers it:

```http
OPTIONS /oauth/session?client_id=<your-client-id> HTTP/1.1
Host: <your-tenant-domain>
Origin: https://community.acme.com
Access-Control-Request-Method: GET

```

```http
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://community.acme.com
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET
Access-Control-Allow-Headers: Content-Type
Access-Control-Max-Age: 600
Vary: Origin

```

`Access-Control-Allow-Origin` always echoes the exact requesting origin rather than `*`, which credentialed requests forbid. An unregistered origin gets the same headerless `403` as above.

##### Redeeming the code[​](#redeeming-the-code "Direct link to Redeeming the code")

Hand the code to your own backend and exchange it exactly as you would a code from the interactive flow — same endpoint, same `grant_type`, same client credentials:

```bash
curl https://<your-tenant-domain>/oauth/token \
  -d grant_type=authorization_code \
  -d code="<probe-code>" \
  -d redirect_uri="<your-first-registered-redirect-uri>" \
  -d client_id="<your-client-id>" \
  -d client_secret="<your-client-secret>"

```

Two differences from a redirect-issued code:

* **`redirect_uri` is your registered value, not one you chose.** A probe code never traveled through a redirect, so there is no URI to echo back. It is stamped with the client's **first registered redirect URI**, and the token endpoint still compares them exactly, so send that value.
* **No `code_verifier`.** A probe code carries no PKCE challenge, so none is required — including for a client that requires PKCE on the interactive flow.

You receive the same response as the interactive flow:

```json
{
    "access_token": "<member-jwt>",
    "token_type": "Bearer",
    "expires_in": 31536000
}

```

The token rides the visitor's **existing** device session rather than a new one, so a probe on every page load does not multiply that visitor's sessions, and a sign-out on the Allegro side invalidates the token you were issued.

Codes expire in 30 seconds and are single-use. Redeem immediately; a second attempt with the same code returns `invalid_grant`.

##### Rate limits[​](#rate-limits "Direct link to Rate limits")

The probe is expected to run once per visitor per page load, so the per-browser limit is generous while a second ceiling still bounds any single host:

| Limit                   | Scope                   |
| ----------------------- | ----------------------- |
| 120 requests per minute | Per browser, per client |
| 600 requests per minute | Per IP address          |

Exceeding either returns `429`. Probe once per page load and cache the answer for the life of the page; do not poll.

#### `prompt=none`[​](#promptnone "Direct link to promptnone")

The authorize endpoint also accepts `prompt=none`, which asks it to answer from the existing session or not at all — it renders no page in either outcome.

```text
GET https://<your-tenant-domain>/oauth/authorize
    ?client_id=<your-client-id>
    &redirect_uri=https://your-app.example.com/callback
    &response_type=code
    &prompt=none
    &state=<state>

```

Signed in, you get the same callback redirect as the interactive flow:

```text
https://your-app.example.com/callback?code=<authorization-code>&state=<state>

```

Not signed in, you get an error back at the same place:

```text
https://your-app.example.com/callback?error=login_required&state=<state>

```

`none` is the only supported `prompt` value, and OpenID Connect forbids combining it with any other, so `prompt=none login` is rejected with `error=invalid_request`. A `prompt=none` request against a client that requires PKCE and without a `code_challenge` also comes back as `error=invalid_request` rather than an error page, since there is no person to read one.

Codes issued this way get the full 10-minute lifetime, ride the visitor's existing device session, and redeem with the `redirect_uri` you sent — an ordinary code exchange in every respect.

note

`prompt=none` needs a top-level navigation, not a frame

Two separate things rule out the hidden-iframe pattern, and it is worth knowing both, because fixing one does not fix the other.

The `SameSite=Lax` cookie described above rides along on a top-level navigation, so a full-page redirect works. It is **not** sent on a cross-site subresource load, so `prompt=none` in an iframe on a page that is not same-site with the Allegro host gets you a permanent `login_required`.

Being same-site is not enough either. Allegro is served behind an `X-Frame-Options` response header, so the browser refuses to render the frame at all for any origin but Allegro's own — and a sibling host under the same parent domain is still a different origin. The cookie would be sent; the frame is blocked before that matters.

Use a top-level redirect, or use the session probe. The probe needs no navigation and no frame, and `X-Frame-Options` does not apply to it: it governs framing, not `fetch`.

#### Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

| Symptom                                                            | Cause                                                                                                        |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `{"status":"unauthenticated"}` for a visitor you know is signed in | Cookie Domain is not set to the shared parent domain, or `credentials: 'include'` is missing.                |
| A CORS error in the console, `403` in the network tab              | Your origin is not registered against this client, or `client_id` is wrong or disabled.                      |
| A CORS error with a `404` in the network tab                       | You are calling a platform hostname. Use the tenant's custom domain.                                         |
| `invalid_grant` when redeeming a probe code                        | The code expired (30 seconds), was already used, or `redirect_uri` is not the client's first registered URI. |
| `error=login_required` every time on `prompt=none`                 | A hidden iframe. Use a top-level redirect or the session probe.                                              |
| `429`                                                              | Polling. Probe once per page load.                                                                           |

#### Related[​](#related "Direct link to Related")

* [OAuth 2.0](/developer/guides/oauth.md) — Client registration, the interactive flow, and the token endpoint
* [Browser Settings](/developer/administration/browser-settings.md) — Cookie Domain and CORS allowed origins
* [JWT Verification](/developer/guides/jwt.md) — Verifying the token you receive


---

### Page Metadata

The SDK automatically collects page metadata from the DOM on every `track()` call. By default it reads from `application/ld+json` structured data embedded in the page.

#### Default Field Mappings[​](#default-field-mappings "Direct link to Default Field Mappings")

| SDK Field      | JSON-LD Key           | Notes                                       |
| -------------- | --------------------- | ------------------------------------------- |
| `page_title`   | `headline` or `name`  | Falls back to `document.title` if not found |
| `content_type` | `@type`               |                                             |
| `content_id`   | `identifier` or `@id` | Tries `identifier` first                    |
| `publisher`    | `publisher.name`      | Nested object path                          |
| `object_type`  | `@type`               |                                             |
| `object_id`    | `identifier` or `@id` | Tries `identifier` first                    |
| `context`      | `articleSection`      |                                             |

`url` and `referer` are always collected automatically from `window.location.href` and `document.referrer`.

#### JSON-LD Examples[​](#json-ld-examples "Direct link to JSON-LD Examples")

##### NewsArticle[​](#newsarticle "Direct link to NewsArticle")

For article pages, include a `NewsArticle` block with all relevant fields:

```html
<script type="application/ld+json">
    {
        "@context": "https://schema.org",
        "@type": "NewsArticle",
        "headline": "City Council Approves New Housing Plan",
        "identifier": "story-12345",
        "publisher": {
            "@type": "Organization",
            "name": "Example News"
        },
        "articleSection": "Local Government"
    }
</script>

```

##### WebPage[​](#webpage "Direct link to WebPage")

For non-article pages, use a `WebPage` block:

```html
<script type="application/ld+json">
    {
        "@context": "https://schema.org",
        "@type": "WebPage",
        "name": "About Us",
        "@id": "https://example.com/about",
        "publisher": {
            "@type": "Organization",
            "name": "Example News"
        }
    }
</script>

```

Note that for `WebPage`, the `context` field will be `null` since there is no `articleSection`.

##### @graph format[​](#graph-format "Direct link to @graph format")

Some SEO plugins (such as Yoast SEO) emit a single JSON-LD block using the `@graph` format rather than one block per type:

```html
<script type="application/ld+json">
    {
        "@context": "https://schema.org",
        "@graph": [
            {
                "@type": "NewsArticle",
                "headline": "City Council Approves New Housing Plan",
                "identifier": "story-12345",
                "publisher": {
                    "@type": "Organization",
                    "name": "Example News"
                },
                "articleSection": "Local Government"
            },
            {
                "@type": "WebSite",
                "name": "Example News",
                "url": "https://example.com/"
            }
        ]
    }
</script>

```

The SDK handles this automatically — it searches within `@graph` and applies the same type priority to pick the best item.

**Type priority:** If multiple JSON-LD blocks (or items within `@graph`) exist on the page, the SDK picks the one with the highest priority: `NewsArticle` > `Article` > `WebPage` > any other type.

#### Article Metadata for Targeting[​](#article-metadata-for-targeting "Direct link to Article Metadata for Targeting")

When the SDK asks which interactions to show, it also sends the viewed article's tags, authors, and publish date, so interactions can target them. These come from the first JSON-LD block whose `@type` is an article type (`Article`, `NewsArticle`, `BlogPosting`, and their subtypes), searched across every block and inside `@graph`. They are not added to tracked events.

| Targeting value | JSON-LD key     | Fallback                                | Notes                                                                |
| --------------- | --------------- | --------------------------------------- | -------------------------------------------------------------------- |
| Tags            | `keywords`      | `article:tag`, then `keywords` meta tag | A comma-separated string is split; an array keeps every value        |
| Authors         | `author`        | `author` meta tag                       | Accepts a string, a list, or `Person` objects (their `name` is used) |
| Published date  | `datePublished` | `article:published_time` meta tag       | Any ISO 8601 date; an unparseable value is ignored                   |

```html
<script type="application/ld+json">
    {
        "@context": "https://schema.org",
        "@type": "NewsArticle",
        "headline": "City Council Approves New Housing Plan",
        "keywords": "Housing, City Council, Local Government",
        "author": [{ "@type": "Person", "name": "Jane Doe" }],
        "datePublished": "2026-10-12T08:00:00-04:00"
    }
</script>

```

Allegro reads the same fields when it catalogs your content for reach estimates, so keep them in the JSON-LD rather than adding them with script after the page loads. These fields cannot be remapped with `pageData`.

#### Overriding Defaults[​](#overriding-defaults "Direct link to Overriding Defaults")

Any field mapping can be overridden via the `pageData` property of `window.__allegro`, set before `client.js` loads. This is useful for publishers that use a GTM data layer or other data sources instead of JSON-LD.

##### Data layer source[​](#data-layer-source "Direct link to Data layer source")

The `dataLayer` source reads a JSON object from a `<meta name="gtm-dataLayer" content='{"key":"value"}'>` tag. The property names inside that object are entirely up to the publisher's own data layer conventions, so each `key` you map depends on your setup.

The example below shows **one way** a publisher might wire this up — a site whose data layer uses `gtm*` field names:

```html
<script>
    window.__allegro = {
        pageData: {
            page_title: { source: 'dataLayer', key: 'gtmStoryTitle' },
            content_type: { source: 'dataLayer', key: 'gtmPageType' },
            content_id: { source: 'dataLayer', key: 'gtmBspStoryId' },
            publisher: { source: 'dataLayer', key: 'gtmSiteName' },
            object_type: { source: 'dataLayer', key: 'gtmPageType' },
            object_id: { source: 'dataLayer', key: 'gtmBspStoryId' },
            context: { source: 'dataLayer', key: 'gtmCategory' },
        },
    };
</script>
<script src="https://your-allegro-instance.com/client.js"></script>

```

Your own data layer will expose whatever field names your CMS or tag manager emits — map each Allegro field to the matching `key`.

##### Meta tag source[​](#meta-tag-source "Direct link to Meta tag source")

Individual fields can also be pulled from `<meta>` tags:

```html
<script>
    window.__allegro = {
        pageData: {
            content_id: { source: 'meta', key: 'article:id' },
            publisher: { source: 'meta', key: 'og:site_name' },
        },
    };
</script>
<script src="https://your-allegro-instance.com/client.js"></script>

```

#### All Source Types[​](#all-source-types "Direct link to All Source Types")

| Source      | How it reads                                | `key` format                                                                   |
| ----------- | ------------------------------------------- | ------------------------------------------------------------------------------ |
| `jsonLd`    | `<script type="application/ld+json">`       | Dot-path like `publisher.name`; pipe-separated fallbacks like `headline\|name` |
| `meta`      | `<meta name="..." content="...">`           | The `name` attribute value                                                     |
| `dataLayer` | `<meta name="gtm-dataLayer" content='...'>` | Property name in the JSON object                                               |
| `selector`  | CSS selector → `textContent`                | Any valid CSS selector                                                         |
| `attribute` | CSS selector → element attribute            | `selector@attribute` e.g. `body@data-publisher`                                |

#### Per-Call Overrides[​](#per-call-overrides "Direct link to Per-Call Overrides")

Any field can also be passed directly to `track()`. Per-call values take precedence over auto-collected page data:

```js
allegro.track('article_read', {
    content_id: '12345',
    content_type: 'article',
});

```


---

### One-off Purchases

The Allegro SDK provides `allegro.purchase.initiate()` to start a Stripe Checkout session for a plan. After the member completes payment, Stripe redirects them back to your site and the SDK automatically exchanges the result for a JWT and entitlement data.

#### Prerequisites[​](#prerequisites "Direct link to Prerequisites")

* A Stripe account connected in the admin. See [Payment Provider](/product/entitlements/payment-provider.md).
* The [Stripe webhook](/developer/platform/integrations/stripe-webhooks.md) configured on the platform (recommended for reliable fulfillment).
* The plan ID for the offer plan you want to sell. Find plan IDs in the admin under **Entitlements → Offers**.

#### Initiating Checkout[​](#initiating-checkout "Direct link to Initiating Checkout")

Call `allegro.purchase.initiate(planId)` to redirect the member to Stripe Checkout:

```js
window.allegro.push(function (allegro) {
    allegro.purchase.initiate('plan_abc123');
});

```

The member is redirected to Stripe. After payment, Stripe redirects them back to the current page URL by default.

##### Custom Return URL[​](#custom-return-url "Direct link to Custom Return URL")

Pass a second argument to control where Stripe redirects after checkout:

```js
window.allegro.push(function (allegro) {
    allegro.purchase.initiate('plan_abc123', 'https://example.com/thank-you');
});

```

Use this if you want to send members to a dedicated confirmation page after checkout rather than the page they were on.

Return URL must be an allowed origin

The return URL must point at an origin the tenant has allowed — its Allegro subdomain, its [custom domain](/developer/platform/setup/custom-domain.md), or any origin in the `cors_allowed_origins` tenant setting. A request whose return URL is on any other origin is rejected with a validation error. Since it defaults to the current page, your own embed origin works without extra configuration.

##### Triggering from a Button[​](#triggering-from-a-button "Direct link to Triggering from a Button")

A typical integration attaches the call to a button click:

```html
<button id="subscribe-btn">Subscribe — $9.99/mo</button>

<script>
    document
        .getElementById('subscribe-btn')
        .addEventListener('click', function () {
            window.allegro.push(function (allegro) {
                allegro.purchase.initiate('plan_abc123');
            });
        });
</script>

```

#### Handling the Return[​](#handling-the-return "Direct link to Handling the Return")

After checkout, Stripe redirects the member back to your site. The SDK detects the result automatically on page load.

**Success** — Stripe appends `allegro_purchase_token` to the return URL. The SDK exchanges it for a JWT and entitlement, then:

* Grants the entitlement and dispatches `allegro:purchase:completed` on `window`.
* Carries a signed-in buyer's session through unchanged. A **guest purchase does not sign the member in** — the checkout email is unverified — so `allegro:authenticated` does **not** fire. To sign a guest buyer in afterward, send them through [magic links](/developer/guides/authentication/magic-links.md) or [one-time codes](/developer/guides/authentication/one-time-codes.md).
* Removes `allegro_purchase_token` from the URL.

**Failure or cancellation** — Stripe appends `allegro_purchase_error=payment_failed`. The SDK:

* Dispatches `allegro:purchase:failed` on `window`.
* Removes the error param from the URL.

##### Listening for Completion[​](#listening-for-completion "Direct link to Listening for Completion")

```js
window.addEventListener('allegro:purchase:completed', function (event) {
    // event.detail.entitlement contains the newly granted entitlement
    const entitlement = event.detail.entitlement;
    console.log('Access granted to:', entitlement.resource.name);
    // e.g. show a confirmation banner, unlock content, etc.
});

window.addEventListener('allegro:purchase:failed', function (event) {
    // event.detail.reason is 'payment_failed' or similar
    console.log('Purchase failed:', event.detail.reason);
});

```

##### The `allegro:purchase:completed` Event[​](#the-allegropurchasecompleted-event "Direct link to the-allegropurchasecompleted-event")

The `detail` object on `allegro:purchase:completed` contains:

| Property      | Type     | Description                                |
| ------------- | -------- | ------------------------------------------ |
| `method`      | `string` | Always `'purchase'`.                       |
| `entitlement` | `object` | The newly created entitlement (see below). |

The `entitlement` object:

| Property        | Type             | Description                                   |
| --------------- | ---------------- | --------------------------------------------- |
| `id`            | `string`         | Entitlement ID.                               |
| `resource.id`   | `string`         | Product ID.                                   |
| `resource.slug` | `string`         | Product slug.                                 |
| `resource.name` | `string`         | Human-readable product name.                  |
| `started_at`    | `string \| null` | ISO 8601 start date, or `null` if indefinite. |
| `ended_at`      | `string \| null` | ISO 8601 end date, or `null` if indefinite.   |
| `is_active`     | `boolean`        | Whether the entitlement is currently active.  |

##### Checking Validation State[​](#checking-validation-state "Direct link to Checking Validation State")

`allegro.purchase.validation` reflects the outcome of token exchange for the current page load:

| Value         | Meaning                                         |
| ------------- | ----------------------------------------------- |
| `'completed'` | Purchase was verified and entitlements granted. |
| `'failed'`    | Payment failed or was cancelled.                |
| `null`        | No purchase token present on this page load.    |

warning

Do not read `validation` at `allegro:ready` time

Token exchange is asynchronous. `allegro.purchase.validation` may still be `null` when `allegro:ready` fires. Listen for `allegro:purchase:completed` or `allegro:purchase:failed` instead.

#### Complete Example[​](#complete-example "Direct link to Complete Example")

```html
<!DOCTYPE html>
<html>
    <head>
        <script src="https://your-allegro-instance.com/client.js"></script>
    </head>
    <body>
        <div id="content-gate">
            <p>Subscribe for full access.</p>
            <button id="subscribe-btn">Subscribe — $9.99/mo</button>
        </div>

        <div id="confirmation" style="display:none">
            <p>Thanks for subscribing! You now have access.</p>
        </div>

        <script>
            document
                .getElementById('subscribe-btn')
                .addEventListener('click', function () {
                    window.allegro.push(function (allegro) {
                        allegro.purchase.initiate('plan_abc123');
                    });
                });

            window.addEventListener('allegro:purchase:completed', function () {
                document.getElementById('content-gate').style.display = 'none';
                document.getElementById('confirmation').style.display = 'block';
            });

            window.addEventListener('allegro:purchase:failed', function () {
                alert('Payment was not completed. Please try again.');
            });
        </script>
    </body>
</html>

```

#### What Happens Server-Side[​](#what-happens-server-side "Direct link to What Happens Server-Side")

When a purchase is fulfilled:

1. Allegro creates a `Purchase` record linked to the member, plan, and Stripe session.
2. For each product on the plan, Allegro creates an `Entitlement` for the member with the plan's configured duration.
3. A `purchase` event is recorded in the member's event history.

If the webhook fires before the member returns to your site (e.g., the browser was closed), fulfillment is still completed via the webhook. The token exchange on the return page detects the already-fulfilled purchase without creating duplicates.

#### Pending Purchases[​](#pending-purchases "Direct link to Pending Purchases")

Checkout sessions that are initiated but never completed (e.g., the member abandons the Stripe checkout page) are recorded as `pending` purchases. Pending purchases are automatically pruned after 24 hours — matching Stripe's checkout session expiry — via the `allegro:prune` scheduler command. Pending purchases do not appear in the admin purchases list.

#### Related[​](#related "Direct link to Related")

* [Stripe Webhook Setup](/developer/platform/integrations/stripe-webhooks.md) — Platform-level webhook configuration for reliable fulfillment
* [Payment Provider (Product)](/product/entitlements/payment-provider.md) — Connecting a payment provider as an operator
* [Entitlements (Product)](/product/entitlements.md) — What members receive after purchase
* [Offers and Plans (Product)](/product/entitlements/offers.md) — Configuring plans and offers


---

### Properties

A single Allegro organization can run multiple **properties** — distinct brands that share the organization's members, entitlements, and templates but present their own web address, CORS rules, cookie domain, and email identity. When an organization uses properties, each property is reachable at its own host, and the Allegro SDK targets a property **by the host it is loaded from** — no extra configuration in your embed code.

For configuring properties in the dashboard, see the [Properties product guide](/product/administration/properties.md). This page covers what changes for a developer embedding the SDK on a property.

#### Property Hosts[​](#property-hosts "Direct link to Property Hosts")

Each property has a dedicated subdomain that combines the organization slug and the property slug with a double-hyphen separator:

```text
https://{organization}--{property}.allegrocdp.com

```

For example, an organization `acme` with a property `magazine` is served at:

```text
https://acme--magazine.allegrocdp.com

```

The double hyphen (`--`) is the reserved separator between the organization and the property. This is why property and organization slugs cannot contain consecutive hyphens. A plain organization host with no `--` (for example `acme.allegrocdp.com`) refers to the organization itself, not to any property.

#### Targeting a Property from the SDK[​](#targeting-a-property-from-the-sdk "Direct link to Targeting a Property from the SDK")

The SDK determines which property it operates as **entirely from the host that serves `client.js`**. There is no `data-property` attribute — you select a property by loading the SDK from that property's host:

```html
<!-- All SDK and API traffic is scoped to the "magazine" property -->
<script
    src="https://acme--magazine.allegrocdp.com/client.js"
    data-tenant="acme"
></script>

```

The SDK's API base URL defaults to the origin of `client.js`, so every request it makes — authentication, event tracking, interactions, checkout — is automatically scoped to the property. Loading `client.js` from the plain organization host instead targets the organization with no property context.

No SDK code changes

Switching a page from the organization host to a property host — or between two properties — requires changing only the `src` of the script tag. The SDK, web components, and API calls behave identically; only the property context differs.

#### Custom Domains for a Property[​](#custom-domains-for-a-property "Direct link to Custom Domains for a Property")

A property can be served from a domain you control instead of the default `{organization}--{property}` subdomain. Choose the property's **Custom Domain** from the dashboard's list of domains already available to your organization — a platform administrator provisions a domain and points its DNS at your Allegro instance before it appears in that list; the property settings page only assigns an already-provisioned domain, it does not accept an arbitrary one. Once assigned, load the SDK from the custom domain:

```html
<script src="https://members.acme.com/client.js" data-tenant="acme"></script>

```

A property custom domain works like a tenant [Custom Domain](/developer/platform/setup/custom-domain.md): audience-facing SDK and API paths are served on it, and all other paths redirect to the organization dashboard. A custom domain must be unique across the entire Allegro instance — it cannot collide with another organization's or another property's domain.

#### What the Property Changes[​](#what-the-property-changes "Direct link to What the Property Changes")

Once a request resolves to a property, Allegro layers the property's configuration on top of the organization's. From an integration standpoint, three things differ:

##### CORS[​](#cors "Direct link to CORS")

The property's allowed origins are **merged on top of** the organization's — the property extends the origin list, it never replaces it. The property's own web address (subdomain and custom domain) is always allowed. Configure additional origins, including `https://*.acme.com` wildcard patterns, in the property's **Browser Settings**.

The same allowed-origin list governs return URLs. The `returnUrl` passed to [magic link](/developer/guides/authentication/magic-links.md) requests and the return URL passed to [checkout](/developer/guides/payment/purchases.md) must resolve to an allowed origin, otherwise the request is rejected.

##### Cookie Domain[​](#cookie-domain "Direct link to Cookie Domain")

The SDK's client configuration reports the property's cookie domain when one is set, falling back to the organization's cookie domain when the property leaves it blank. This controls the domain the member session cookie is scoped to.

##### Email Templates[​](#email-templates "Direct link to Email Templates")

Transactional emails triggered on a property host render that property's template if one exists, falling back to the organization's template, then to Allegro's built-in default. This resolution is preserved even for emails sent from a queue — the property context is captured when the email is created.

#### API Behavior[​](#api-behavior "Direct link to API Behavior")

The API on a property host behaves identically to any organization host. Requests under `/api/*` always return JSON, including a structured error envelope:

| Code                | HTTP status | Meaning                                              |
| ------------------- | ----------- | ---------------------------------------------------- |
| `NO_CURRENT_TENANT` | 404         | The host did not resolve to an organization.         |
| `VALIDATION_ERROR`  | 422         | The request failed validation.                       |
| `UNAUTHENTICATED`   | 401         | Authentication is required or the token is invalid.  |
| `FORBIDDEN`         | 403         | The authenticated member may not perform the action. |
| `NOT_FOUND`         | 404         | The resource does not exist.                         |

The property only augments the request's CORS, cookie, and email/template context — it does not change the API surface, authentication, or response shapes.

#### Related[​](#related "Direct link to Related")

* [Properties (Product)](/product/administration/properties.md) — creating and configuring properties in the dashboard
* [Custom Domain](/developer/platform/setup/custom-domain.md) — serving the SDK from your own domain
* [Script Tag](/developer/guides/script-tag.md) — embedding the SDK on your site


---

### Recommendations

`allegro.recommendations` fetches ranked article recommendations for the current reader and reports clicks on them, so you can build a "Read Next" or "More Like This" module on your site.

#### How ranking works[​](#how-ranking-works "Direct link to How ranking works")

Recommendations come from a ladder of strategies, tried in order until enough articles are found:

1. **Taste** — articles matched to the reader's own reading history.
2. **Similar** — articles similar to the one they're currently on.
3. **Trending** — articles currently getting the most engagement site-wide.

Articles the reader has already read are excluded at every rung. Each returned item's `strategy` field tells you which rung produced it.

#### Basic usage[​](#basic-usage "Direct link to Basic usage")

```js
window.allegro.push(async function (allegro) {
    const { items } = await allegro.recommendations.get({ limit: 6 });

    const list = document.querySelector('#recommendations');

    items.forEach(function (item) {
        const link = document.createElement('a');
        link.href = item.pagePath;
        link.textContent = item.title;
        link.addEventListener('click', function () {
            allegro.recommendations.trackClick(item).catch(function (error) {
                console.error(error);
            });
        });

        list.appendChild(link);
    });
});

```

Call `allegro.recommendations.get()` to fetch a set, render the items, and call `allegro.recommendations.trackClick(item)` when the reader clicks one — pass the same `item` object `get()` gave you, not a copy. See [Click attribution](#click-attribution) for why that matters.

`trackClick()` returns a promise that rejects if the click report fails — a rate limit or a network error mid-navigation are both plausible — so always attach a `.catch()`. An unhandled rejection surfaces as an SDK error in your own site's monitoring, not ours.

#### Options[​](#options "Direct link to Options")

`get()` takes an options object; every field is optional:

| Option       | Type     | Default                     | Description                                               |
| ------------ | -------- | --------------------------- | --------------------------------------------------------- |
| `limit`      | `number` | `6` upstream                | How many articles to ask for. 24 is the maximum.          |
| `path`       | `string` | `window.location.pathname`  | Article to anchor the "similar" strategy on.              |
| `maxAgeDays` | `number` | `0` (no cap)                | Excludes articles published more than this many days ago. |
| `device`     | `string` | the SDK's own device cookie | Reader's device id.                                       |

Override `path` when you're rendering recommendations for an article other than the one currently loaded — a widget on an article's own page, for example, that recommends off a different anchor article. Override `device` only if you're managing device identity yourself outside the SDK's cookie; otherwise leave it to the default so click attribution and taste ranking stay tied to the same reader.

#### Sorting and comparing scores[​](#sorting-and-comparing-scores "Direct link to Sorting and comparing scores")

Each item carries a `score`, but it's only comparable **within** a strategy, not across strategies. Taste and similar scores are a similarity value times a recency decay; trending scores are engaged hours. Sorting a mixed list of items by `score` produces a meaningless order — mixing a similarity fraction against a count of hours. If you want a single ordering, keep the order `get()` returned, which is already ranked by the ladder above.

#### Click attribution[​](#click-attribution "Direct link to Click attribution")

`trackClick(item)` needs to know which request served `item` so the click can be attributed to the right recommendation set. Passing the exact item object `get()` returned always works — the SDK tracks it by identity.

If you pass a copy instead — the result of a JSON round-trip, or an item that went through a state library that serializes it — the SDK falls back to matching by `pagePath` across the 10 most recent `get()` calls on the page. That works as long as the path is unique among those calls, but **throws** if it isn't: two recommendation widgets on the same page could otherwise recommend the same article and cross-attribute a click between them, silently corrupting your click-through data.

Guidance

Pass the item you rendered. Don't reconstruct it from a path or id, and don't let it pass through `JSON.stringify`/`JSON.parse` or a store that serializes props before it reaches `trackClick()`.

#### No recommendations available[​](#no-recommendations-available "Direct link to No recommendations available")

When no engine is configured for your tenant, or the engine is unreachable, `get()` doesn't throw — it resolves with an empty `items` array and a `null` `requestId`:

```js
const { requestId, items } = await allegro.recommendations.get();

if (requestId === null) {
    return;
}

```

Check for this and render nothing rather than an empty container, so a missing recommendation set doesn't leave a visible hole in your layout.

#### Server-to-server[​](#server-to-server "Direct link to Server-to-server")

Everything above runs from the browser through the SDK. If you need recommendations from your own backend — a build step, a newsletter generator, a batch job — there's a token-authenticated equivalent under `/api/v1`:

| Endpoint                               | Scope                   | Equivalent to                          |
| -------------------------------------- | ----------------------- | -------------------------------------- |
| `GET /api/v1/recommendations`          | `recommendations:read`  | `allegro.recommendations.get()`        |
| `POST /api/v1/recommendations/click`   | `recommendations:write` | `allegro.recommendations.trackClick()` |
| `POST /api/v1/recommendations/preview` | `recommendations:read`  | No SDK equivalent — see below.         |

See [API Authentication](/developer/api/authentication.md) for how to create a key with these scopes, and the generated [REST API reference](/developer/api/token/token-recommendation-index.md) for full request and response schemas.

This API reports failures instead of degrading

The browser SDK answers an empty `items` array when the engine is unreachable — a reader can't act on the difference, and a dead widget is worse than an empty one. The token API takes the opposite position: `GET /recommendations` and `POST /recommendations/click` answer `502 Bad Gateway` instead, because a server-to-server caller can retry or alert on that, and silently swallowing the failure would just hide an outage from you.

##### Preview[​](#preview "Direct link to Preview")

`POST /api/v1/recommendations/preview` has no SDK equivalent. It ranks recommendations against a hypothetical reading history you supply, rather than a real visitor's session — useful for testing how the ranking engine responds to a given history, or for building tooling around it. Send up to 50 `reads`, oldest first:

```bash
curl https://acme.allegrocdp.com/api/v1/recommendations/preview \
  -H "Authorization: Bearer <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "reads": [
      { "path": "/news/first-article", "seconds": 45 },
      { "path": "/news/second-article", "seconds": 120 }
    ],
    "limit": 6
  }'

```

An empty `reads` array previews what a just-arrived visitor with no history would see. The response echoes back each read's contribution to the taste vector (`weight`, `share`, and whether the path was `found` in the catalog) alongside the `items` that history would produce.

Preview depends on the tenant's configured recommendation engine supporting it. A tenant with no engine configured gets `501 Not Implemented` rather than a crash or an empty response — check for that status before assuming the request failed for another reason.

#### Related[​](#related "Direct link to Related")

* [`RecommendationsNamespace`](/developer/api-reference/interfaces/RecommendationsNamespace.md) — Full SDK method reference.
* [`RecommendationItem`](/developer/api-reference/interfaces/RecommendationItem.md) — Shape of one recommended article.
* [REST API reference](/developer/api/token/token-recommendation-index.md) — Full server-to-server endpoint documentation.


---

### Preview Scenarios

A **scenario** is a real-world surface your template appears in. In [Local Template Preview](/developer/guides/local-preview.md), the toolbar lets you switch between scenarios, each pairing a host page with a placement config (the parameters passed to the production SDK's `renderActions()`).

`allegro-preview` ships three built-in scenarios:

| Tab                  | Description                                                                                 |
| -------------------- | ------------------------------------------------------------------------------------------- |
| **Standalone**       | Template rendered on its own in an isolated iframe                                          |
| **Article · Append** | Template injected after the full content of a mock article                                  |
| **Article · Cut**    | Template injected after paragraph 3 of a mock article using the `truncate` placement method |

#### Custom Scenarios[​](#custom-scenarios "Direct link to Custom Scenarios")

Define your own scenarios to preview templates inside the real surfaces of your site — a paywalled article, a homepage rail, a newsletter shell. Create an `.allegro-preview/` folder at the root of your templates directory, with one subfolder per scenario:

```text
.allegro-preview/
├── paywalled-article/
│   ├── scenario.json     # required: name + placement config
│   ├── host.html         # optional: your mock host page markup
│   └── host.css          # optional: host page styles
└── homepage-rail/
    ├── scenario.json
    └── host.html

```

Each `scenario.json` mirrors the production SDK's placement parameters:

```json
{
  "name": "Paywalled Article",
  "target_selector": "#article-body",
  "placement_method": "truncate",
  "truncation_unit": "paragraphs",
  "truncation_count": 4,
  "truncation_style": "cut"
}

```

| Key                | Required                    | Notes                                          |
| ------------------ | --------------------------- | ---------------------------------------------- |
| `name`             | Yes                         | Label shown on the scenario tab.               |
| `target_selector`  | When `host.html` is present | CSS selector in your host page to inject into. |
| `placement_method` | When injecting              | `truncate` or `append`.                        |
| `truncation_unit`  | When `truncate`             | e.g. `paragraphs`.                             |
| `truncation_count` | When `truncate`             | Whole number.                                  |
| `truncation_style` | When `truncate`             | e.g. `cut`.                                    |

How the host page is chosen:

* **With `host.html`** — your markup is the page, and the template is injected into `target_selector` using `placement_method`. `host.css` is included automatically.
* **Without `host.html`** — the template renders standalone, and `target_selector` is ignored.

Custom scenarios appear as additional tabs alongside the built-in ones and live-reload when you edit them.

#### Example: a custom host page[​](#example-a-custom-host-page "Direct link to Example: a custom host page")

A scenario is a folder of up to three files. The `host.html` file is the full page your template is injected into — it is plain HTML, styled with `host.css`, with behavior added through an inline `<script>` (there is no separate `host.js` file; host-page JavaScript lives inside `host.html`).

`.allegro-preview/paywalled-article/scenario.json`:

```json
{
  "name": "Paywalled Article",
  "target_selector": "#article-body",
  "placement_method": "truncate",
  "truncation_unit": "paragraphs",
  "truncation_count": 4,
  "truncation_style": "cut"
}

```

`.allegro-preview/paywalled-article/host.html`:

```html
<article class="post">
  <h1>The Future of Local News</h1>
  <p class="byline">By Jordan Ellison · March 14, 2026</p>

  <div id="article-body">
    <p>The city council voted unanimously Tuesday to approve a sweeping new transit plan.</p>
    <p>Mayor Ellison called the decision a turning point for how the region gets around.</p>
    <p>The plan upgrades 14 bus lines and adds three new light-rail corridors downtown.</p>
    <p>Critics warn the projected cost may climb once land acquisition is factored in.</p>
  </div>

  <script>
    // Host-page JS runs in the preview exactly as it would on your real site —
    // useful for mimicking a paywall, lazy-loaded content, or analytics hooks.
    const body = document.getElementById('article-body');
    body.querySelectorAll('p').forEach((p, index) => {
      p.dataset.paragraph = String(index + 1);
    });
    console.log(`[host] article rendered with ${body.children.length} paragraphs`);
  </script>
</article>

```

`.allegro-preview/paywalled-article/host.css`:

```css
.post {
  max-width: 680px;
  margin: 0 auto;
  padding: 32px 24px;
  font-family: Georgia, serif;
  line-height: 1.7;
}

.post .byline {
  color: #6b7280;
  font-family: system-ui, sans-serif;
  font-size: 0.85rem;
}

```

With this `scenario.json`, the template is injected into `#article-body` using the `truncate` method after the fourth paragraph — reproducing how it appears mid-article on your site, including any host-page scripts and styles.

note

The `.allegro-preview/` folder is ignored by the GitHub template sync — it never becomes a template and never produces a sync warning. Keep your scenarios in your repo without affecting what syncs to Allegro.


---

### Script Tag

Add the following tag to your page to load the Allegro SDK:

```html
<script src="https://your-allegro-instance.com/client.js"></script>

```

Replace `your-allegro-instance.com` with your Allegro domain.

#### How It Works[​](#how-it-works "Direct link to How It Works")

`client.js` is a tiny loader script served by Allegro. When it runs, it creates a new `<script>` element pointing at the compiled SDK, injects two attributes automatically (`data-csrf-token` and `data-tenant-config`), and appends it to `<head>`. Any attributes you add to the original tag are forwarded to the injected script.

On load the SDK:

1. Reads configuration from the script tag attributes and `window.__allegro`.
2. Creates or restores device and session identifiers.
3. Registers the built-in web components.
4. Fires a `page_view` event.
5. Dispatches `allegro:ready` on `window`.

#### `window.__allegro` Configuration[​](#window__allegro-configuration "Direct link to window__allegro-configuration")

If you need to configure the SDK without adding attributes to the script tag, set `window.__allegro` to a plain object **before** `client.js` loads:

```html
<script>
    window.__allegro = {
        debug: true,
    };
</script>
<script src="https://your-allegro-instance.com/client.js"></script>

```

| Property | Type      | Description                                                                      |
| -------- | --------- | -------------------------------------------------------------------------------- |
| `debug`  | `boolean` | Enable debug mode. See [Debug Mode](#debug-mode).                                |
| `apiUrl` | `string`  | Override the API base URL. Defaults to the origin of `client.js`. Rarely needed. |

note

Security-sensitive values (`csrfToken`, `tenant`) are always injected by the server and cannot be overridden from the page.

#### Attributes[​](#attributes "Direct link to Attributes")

| Attribute            | Injected automatically | Description                                                                                           |
| -------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------- |
| `data-tenant-config` | Yes                    | JSON object with tenant settings (enabled login providers, cookie domain, etc.).                      |
| `data-debug`         | No                     | Enable debug mode. Presence of the attribute (or `="true"`) is enough. See [Debug Mode](#debug-mode). |
| `data-api-url`       | No                     | Override the API base URL. Defaults to the origin of `client.js`. Rarely needed.                      |

#### Debug Mode[​](#debug-mode "Direct link to Debug Mode")

Debug mode writes verbose SDK logs to the browser console. Enable it in any of four ways:

**`window.__allegro` (set before the script tag):**

```html
<script>window.__allegro = { debug: true };</script>
<script src="https://your-allegro-instance.com/client.js"></script>

```

**Attribute on the script tag:**

```html
<script src="https://your-allegro-instance.com/client.js" data-debug></script>

```

**URL parameter** (persisted to `localStorage` for the session):

```text
https://example.com/article?allegro_debug=1

```

Pass `allegro_debug=0` to clear it.

**Browser console** (takes effect immediately, persists across page loads):

```js
window.allegro.debug();

```

#### `allegro:ready` Event[​](#allegroready-event "Direct link to allegroready-event")

The SDK dispatches `allegro:ready` on `window` once initialization is complete. Use this if you need to interact with the SDK after it has loaded but cannot guarantee the callback queue has been set up:

```js
window.addEventListener('allegro:ready', function () {
    window.allegro.push(function (allegro) {
        // SDK is ready
    });
});

```

For most use cases the [event queue pattern](/developer/platform/event-streaming/event-queue.md) is simpler — callbacks pushed to `window.allegro` before the SDK loads are replayed automatically.

#### Embed Snippet[​](#embed-snippet "Direct link to Embed Snippet")

Allegro administrators can inject custom JavaScript into every page that loads `client.js` via **Organization Settings → Embed Snippet**. The snippet is appended directly to the loader and executes in the same context as the SDK, after initialization is complete.

A typical snippet uses the [event queue pattern](/developer/platform/event-streaming/event-queue.md) to run code once the SDK is ready:

```js
window.allegro.push((allegro) => {
    // Runs after Allegro initializes on every page
});

```

The snippet is served as part of `client.js` and is cached for up to 5 minutes. Changes made in the admin may not appear on your site immediately — allow up to 5 minutes for the cache to expire.

Version history

Every save creates a revision. Administrators can browse diffs and restore any previous version from the Version History panel in the Embed Snippet settings page.

#### Async Loading[​](#async-loading "Direct link to Async Loading")

The loader script is injected with `async = true` by default so it does not block page rendering. To load the SDK synchronously (for example, in a server-side rendering environment where you need it available before paint), add `?async=false` to the `client.js` URL:

```html
<script src="https://your-allegro-instance.com/client.js?async=false"></script>

```


---

### template.json

Every template directory may include a `template.json` manifest alongside `index.html`. It defines the template's display **name** and its editable **fields**. When a template is synced from GitHub, the `name` becomes the template's title and each field becomes an editable input.

Templates built in Allegro have one too: open the template's **Options** tab and click **Edit template.json** to view or edit it, or read `template_json` from the REST API's get template endpoint. See [Editing template.json](/product/interactions/templates.md#editing-templatejson).

A machine-readable [JSON Schema](https://docs.allegroaudience.com/template.schema.json) is published for editor autocompletion and validation. Reference it from your file with `$schema`:

```json
{
    "$schema": "https://docs.allegroaudience.com/template.schema.json",
    "name": "Newsletter Signup",
    "fields": [
        {
            "slug": "headline",
            "type": "text",
            "label": "Headline",
            "default_value": "Stay in the know"
        }
    ]
}

```

#### Top-level properties[​](#top-level-properties "Direct link to Top-level properties")

| Property   | Type     | Required | Description                                                               |
| ---------- | -------- | -------- | ------------------------------------------------------------------------- |
| `name`     | `string` | Yes      | Display name (title) of the template. Used as the template title on sync. |
| `fields`   | `array`  | Yes      | The editable fields exposed by the template. May be empty.                |
| `supports` | `array`  | No       | Capabilities the template declares. See [Supports](#supports).            |
| `plans`    | `array`  | No       | Preview only. Sample plans for the local preview. Ignored on sync.        |

#### Field properties[​](#field-properties "Direct link to Field properties")

| Property        | Type      | Required    | Description                                                                                                                                       |
| --------------- | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `slug`          | `string`  | Yes         | Placeholder identifier. Lowercase letters, numbers, `-`, and `_` only (`^[a-z0-9_-]+$`).                                                          |
| `type`          | `string`  | Yes         | One of `text`, `textarea`, `richtext`, `number`, `checkbox`, `enum`, `group`.                                                                     |
| `label`         | `string`  | No          | Name shown to editors. Defaults to the slug in words (`faq_sections` → "Faq sections").                                                           |
| `description`   | `string`  | No          | Help text shown under the label.                                                                                                                  |
| `tab`           | `string`  | No          | Top-level fields only. The tab the field appears in when editors fill it in; fields without one appear under "General".                           |
| `formats`       | `array`   | No          | `richtext` only. Any of `bold`, `italic`, `link`, `bulleted_list`, `numbered_list`; all five when omitted.                                        |
| `repeatable`    | `boolean` | No          | Lets editors enter a list of values instead of one. A `group` is always repeatable.                                                               |
| `options`       | `array`   | For `enum`  | The choices of an `enum` field: a string (used as both value and label) or `{ "value", "label" }`.                                                |
| `fields`        | `array`   | For `group` | The subfields of a `group`. Subfields take every property except `tab` and `default_value`, and can be groups themselves up to three levels deep. |
| `default_value` | any       | No          | Value an interaction uses until it saves its own, and the preview editor's initial value. Use an array for a repeatable field.                    |

Default values on interactions

An interaction action that uses the template renders `default_value` for any field it has no saved value for, including fields added to the template later. A saved value wins, even an empty one. A checkbox default of `true` or `false` is stored as the text `"true"` or `"false"`, and a default that doesn't match the field's shape (an array on a single field, or text on a repeatable one) is dropped on sync.

#### Field types[​](#field-types "Direct link to Field types")

| Type       | Editors see                                       | Value                                    |
| ---------- | ------------------------------------------------- | ---------------------------------------- |
| `text`     | Single-line text input                            | The text                                 |
| `textarea` | Multi-line text input                             | The text                                 |
| `richtext` | Editor with the field's `formats`                 | Cleaned HTML                             |
| `number`   | Number input                                      | The number, as text                      |
| `checkbox` | Toggle                                            | `"true"` or `"false"`                    |
| `enum`     | Select of the field's `options`                   | The chosen option's `value`              |
| `group`    | A list of items, each with one input per subfield | A list of objects keyed by subfield slug |

`text`, `number`, `checkbox`, and `enum` values are limited to 200 characters; `textarea` and `richtext` values to 10,000. A repeatable field holds up to 50 items. Every value except `richtext` is inserted into the page as escaped text. A `richtext` value keeps only paragraphs, line breaks, and its allowed formats, and links must use `http`, `https`, or `mailto`.

#### Repeatable fields and groups[​](#repeatable-fields-and-groups "Direct link to Repeatable fields and groups")

Mark a field `repeatable` to let editors add as many values as they need, such as a list of links. Use a `group` when each item needs several values, such as newsletters that each have a title, image, and ID. A group's subfields can be repeatable, and can be groups themselves, up to three levels deep (a top-level field, a group inside it, and a group inside that).

```json
{
    "fields": [
        {
            "slug": "links",
            "type": "text",
            "label": "Links",
            "repeatable": true
        },
        {
            "slug": "newsletters",
            "type": "group",
            "label": "Newsletters",
            "fields": [
                { "slug": "id", "type": "text", "label": "List ID" },
                { "slug": "title", "type": "text", "label": "Title" },
                { "slug": "image", "type": "text", "label": "Image URL" },
                {
                    "slug": "frequency",
                    "type": "enum",
                    "options": ["daily", "weekly"]
                }
            ]
        }
    ]
}

```

Loop over a repeatable field in the template HTML with `{% for item in slug %}…{% endfor %}`. See [Repeatable fields](/developer/guides/templates.md#repeatable-fields) for the full syntax.

#### Supports[​](#supports "Direct link to Supports")

`supports` lists the capabilities a template declares. `plans` is the only one today: it marks the template as showing plans from an offer.

```json
{
    "name": "Plan Picker",
    "supports": ["plans"],
    "fields": []
}

```

When a template supports `plans`:

* Every interaction that uses the template must choose an offer. The interaction editor shows an **Offer** picker for it, and saving without one fails.
* No field may use the slug `plans`. The sync skips a field with that slug and records a warning in the sync log.

Values other than `plans` are ignored on sync and recorded as warnings, so a typo doesn't stop the rest of the template from syncing.

See [Plans](/developer/guides/templates.md#plans) for how the template renders the offer's plans in HTML, Alpine.js, and `index.js`.

#### In local preview[​](#in-local-preview "Direct link to In local preview")

[Local Template Preview](/developer/guides/local-preview.md) reads `template.json` and renders an editor input per field in its sidebar, seeded with `default_value`. Repeatable fields and groups get **Add item**, reorder, and **Remove** buttons. Seed them with an array:

```json
{
    "slug": "newsletters",
    "type": "group",
    "fields": [{ "slug": "title", "type": "text" }],
    "default_value": [
        { "title": "Morning Briefing" },
        { "title": "Weekend Reads" }
    ]
}

```

The local preview renders a plans template with two sample plans. To preview your own, add a top-level `plans` list in the shape a template receives. The sync ignores it. See [Previewing Plans](/developer/guides/local-preview.md#previewing-plans).

```json
{
    "name": "Plan Picker",
    "supports": ["plans"],
    "fields": [],
    "plans": [
        {
            "id": "annual",
            "name": "Annual",
            "formatted_price": "$99.00",
            "duration_label": "1 year",
            "fields": { "badge": "Best value" }
        }
    ]
}

```

#### Complete example[​](#complete-example "Direct link to Complete example")

```json
{
    "$schema": "https://docs.allegroaudience.com/template.schema.json",
    "name": "Newsletter Signup",
    "fields": [
        {
            "slug": "headline",
            "type": "text",
            "label": "Headline",
            "default_value": "Stay in the know"
        },
        { "slug": "intro", "type": "textarea", "label": "Intro" },
        {
            "slug": "theme",
            "type": "enum",
            "label": "Theme",
            "options": [
                { "value": "light", "label": "Light" },
                { "value": "dark", "label": "Dark" }
            ],
            "default_value": "light"
        },
        {
            "slug": "newsletters",
            "type": "group",
            "label": "Newsletters",
            "fields": [
                { "slug": "id", "type": "text", "label": "List ID" },
                { "slug": "title", "type": "text", "label": "Title" }
            ],
            "default_value": [{ "id": "morning", "title": "Morning Briefing" }]
        },
        {
            "slug": "show_privacy_note",
            "type": "checkbox",
            "label": "Show privacy note"
        }
    ]
}

```


---

### Templates

This guide covers the technical details of how Allegro templates are rendered on the page. For an overview of creating and managing templates, see [Templates](/product/interactions/templates.md) in the product docs.

Claude skill available

If you use Claude Code, install the `allegro-templates` skill for in-editor guidance on file structure, Alpine.js patterns, field placeholders, and local preview:

```sh
npx skills add alleyinteractive/allegro@allegro-templates

```

#### Rendering Model[​](#rendering-model "Direct link to Rendering Model")

When an Interaction triggers, Allegro creates a host `<div>` and attaches an **open shadow root** to it. All of the template's markup, styles, and external stylesheets are injected inside that shadow root before the host is placed in the DOM at the configured target position.

The shadow DOM provides full CSS isolation — styles defined in the template don't leak out to the host page, and the host page's styles don't bleed in.

The host element carries a `data-allegro-interaction` attribute set to the Interaction's slug, which you can use for external targeting if needed:

```css
/* from the host page — selects the template host element */
[data-allegro-interaction='my-interaction'] {
    margin-top: 2rem;
}

```

#### Alpine.js[​](#alpinejs "Direct link to Alpine.js")

[Alpine.js](https://alpinejs.dev) v3 is loaded automatically the first time a template renders — no `<script>` tag required. It is served from your Allegro domain, not a third-party CDN, so no external request leaves the page. If Alpine is already present on the page, Allegro uses it directly.

Alpine is initialized on the shadow root, so directives in your template HTML work as expected.

##### `x-data` Scope[​](#x-data-scope "Direct link to x-data-scope")

Every template's root container is wired up with the `allegroInteraction` [Alpine component](/developer/guides/alpine-state.md), which gives you reactive access to the current session state and any data passed to the Interaction trigger.

| Property          | Type             | Description                                                                                                            |
| ----------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `slug`            | `string \| null` | The slug of the Interaction that triggered this template.                                                              |
| `session`         | `object \| null` | Reactive shortcut to `$store.allegro.session` — updates automatically on login or logout without a page reload.        |
| `audienceMember`  | `object \| null` | Reactive shortcut to `$store.allegro.audienceMember` — the authenticated member's profile, or `null` if not logged in. |
| `isAuthenticated` | `boolean`        | Reactive shortcut to `$store.allegro.isAuthenticated`.                                                                 |
| `plans`           | `array`          | The offer's plans, for a template that supports plans. See [Plans](#plans).                                            |
| *(extra data)*    | any              | Any additional data passed when the Interaction was triggered is available at the top level.                           |

Example — personalizing content based on authentication state:

```html
<div x-show="isAuthenticated">
    Welcome back, <span x-text="audienceMember.name"></span>!
</div>

<div x-show="!isAuthenticated">
    <p>Sign in to continue reading.</p>
    <allegro-login-form></allegro-login-form>
</div>

```

Example — reading extra data passed by the Interaction trigger:

```html
<!-- if the interaction was triggered with { articleId: '123' } -->
<p x-text="`Reading article ${articleId}`"></p>

```

The session state is reactive — if the member logs in after the template is already on the page, Alpine re-renders any bound expressions automatically. See [Alpine State Reference](/developer/guides/alpine-state.md) for the full store shape, the reactivity model, and more recipes.

For the full list of Alpine directives and features, see the [Alpine.js documentation](https://alpinejs.dev/start-here).

#### Web Components[​](#web-components "Direct link to Web Components")

Allegro's built-in web components are registered on the page by the SDK and are available inside templates:

| Component                | Description                                     |
| ------------------------ | ----------------------------------------------- |
| `<allegro-login-form>`   | Login form with email/password and social login |
| `<allegro-email-form>`   | Email capture form                              |
| `<allegro-content-gate>` | Paywall / content gate                          |

See the [Components](/developer/components/login-form.md) section for each component's attributes, events, and CSS variables.

#### Field Placeholders[​](#field-placeholders "Direct link to Field Placeholders")

Field values defined on the Interaction are substituted into the template HTML before rendering. Reference a field by its slug wrapped in `{% %}`. Values are inserted as text, with `<`, `>`, `&`, and quotes escaped, except for a rich text field, whose cleaned HTML is inserted as-is:

```html
<h2>{% headline %}</h2>
<p>{% bodyText %}</p>
<a href="{% ctaUrl %}">{% ctaLabel %}</a>

```

Substitution runs before Alpine.js initializes, so field values are baked into the HTML and can be used inside Alpine expressions:

```html
<div x-data="{ open: false }">
    <button @click="open = !open">{% toggleLabel %}</button>
    <p x-show="open">{% bodyText %}</p>
</div>

```

##### Repeatable Fields[​](#repeatable-fields "Direct link to Repeatable Fields")

A repeatable field holds a list of values. Repeat part of the HTML once per item with `{% for item in slug %}…{% endfor %}`, where `item` is any name you choose for the current item:

```html
<ul>
    {% for link in links %}
    <li><a href="{% link %}">{% link %}</a></li>
    {% endfor %}
</ul>

```

For a group, each item has one value per subfield. Reference a subfield with `{% item.subslug %}`:

```html
{% for newsletter in newsletters %}
<label>
    <input type="checkbox" value="{% newsletter.id %}" />
    <strong>{% newsletter.title %}</strong>
    <img src="{% newsletter.image %}" alt="" />
</label>
{% endfor %}

```

A group's subfield can be a list or a group itself. Loop over it from inside the item with `{% for entry in item.subslug %}`:

```html
{% for section in sections %}
<h3>{% section.heading %}</h3>
<dl>
    {% for q in section.questions %}
    <dt>{% q.question %}</dt>
    <dd>{% q.answer %}</dd>
    {% endfor %}
</dl>
{% endfor %}

```

Other fields can be used inside a loop as usual. A few rules:

* Loops nest at most three levels, matching how deep groups can go.
* A loop variable with the same name as a field hides that field inside the loop.
* A loop over a field with no items renders nothing.
* An item's empty or missing subfield renders as an empty string.
* `{% slug %}` for a repeatable field (outside a loop) renders as an empty string.

##### Meter Placeholders[​](#meter-placeholders "Direct link to Meter Placeholders")

`{% meter.<slug>.<field> %}` renders the visitor's usage for a meter, where `<field>` is `used`, `limit`, `remaining`, `status`, or `counted`. Meter values are substituted after field values, so a field value can contain a meter placeholder too. An unknown meter or an empty value renders as an empty string.

```html
<p x-show="'{% meter.monthly-articles.status %}' === 'under_limit'">
    {% meter.monthly-articles.remaining %} free articles left
</p>

```

See [Meters](/product/interactions/meters.md#showing-a-meter-in-a-template) for what each field means.

#### Plans[​](#plans "Direct link to Plans")

A template that declares `"supports": ["plans"]` in its [`template.json`](/developer/guides/template-json.md#supports) shows the plans of an offer. Each Interaction that uses the template chooses the offer, and the template receives that offer's plans in the offer's order. If the Interaction has no offer, or the offer has no plans, the template is not rendered at all.

##### In HTML[​](#in-html "Direct link to In HTML")

Repeat part of the HTML once per plan with `{% for plan in plans %}…{% endfor %}`. `plan` is any name you choose:

```html
<ul class="plans">
    {% for plan in plans %}
    <li class="plan">
        <span class="plan__badge">{% plan.fields.badge %}</span>
        <h3>{% plan.name %}</h3>
        <p>{% plan.formatted_price %} / {% plan.duration_label %}</p>
        <p>{% plan.description %}</p>
        <button type="button" data-plan="{% plan.id %}">
            Choose {% plan.name %}
        </button>
    </li>
    {% endfor %}
</ul>

```

| Placeholder                  | Value                                                              |
| ---------------------------- | ------------------------------------------------------------------ |
| `{% plan.id %}`              | The plan's ID, for `allegro.purchase.initiate()`.                  |
| `{% plan.name %}`            | The plan's name.                                                   |
| `{% plan.description %}`     | The plan's description.                                            |
| `{% plan.price %}`           | The price in the currency's smallest unit, e.g. `9900`.            |
| `{% plan.currency %}`        | Lowercase ISO 4217 code, e.g. `usd`.                               |
| `{% plan.formatted_price %}` | The price formatted for its currency, e.g. `$99.00`.               |
| `{% plan.duration_label %}`  | How long the plan lasts, e.g. `1 year`.                            |
| `{% plan.is_unlimited %}`    | `true` or `false`.                                                 |
| `{% plan.product.<key> %}`   | The plan's product: `id`, `name`, or `slug`.                       |
| `{% plan.fields.<slug> %}`   | A public [plan field](/product/entitlements/plan-fields.md) value. |

Plan values are inserted as text: `<`, `>`, `&`, and quotes are escaped, so a plan named `<b>Annual</b>` shows the tags rather than bold text. Numbers and booleans render as text, and an empty value, a private plan field, or an unknown key renders as an empty string. Plan placeholders only work inside the loop, and the plans loop can't be nested inside another loop or contain one.

Plan placeholders are text substitutions. Don't put them inside Alpine expressions or other attributes evaluated as JavaScript, such as `x-show` or `@click`; use the Alpine `plans` data there instead.

Templates embedded with [`<allegro-template>`](#embedding-other-templates) don't receive plans. Put the plans loop in the template the Interaction uses.

##### In Alpine.js[​](#in-alpinejs "Direct link to In Alpine.js")

The same list is available as `plans` in the template's [`x-data` scope](#x-data-scope), with numbers and booleans kept as their real types:

```html
<template x-for="plan in plans" :key="plan.id">
    <button type="button" @click="allegro.purchase.initiate(plan.id)">
        <span x-text="plan.name"></span>
        <span x-show="plan.fields.badge" x-text="plan.fields.badge"></span>
    </button>
</template>

```

##### In `index.js`[​](#in-indexjs "Direct link to in-indexjs")

For a template that supports plans, `index.js` runs with `plans` in scope alongside `shadowRoot` and `hostElement`. Don't declare your own `plans` variable in such a script. `plans` is not defined for templates that don't support plans, so their scripts are unaffected.

```js
shadowRoot.querySelectorAll('[data-plan]').forEach((button) => {
    button.addEventListener('click', () =>
        allegro.purchase.initiate(button.dataset.plan),
    );
});

console.log(`${plans.length} plans`);

```

Checkout is up to the template: Allegro renders the plans but adds no buttons or click handlers. Start a checkout with [`allegro.purchase.initiate(planId)`](/developer/guides/payment/purchases.md).

Each plan has this shape:

```json
{
    "id": "9f1c2d3e-…",
    "name": "Annual",
    "description": "Best value",
    "price": 9900,
    "currency": "usd",
    "formatted_price": "$99.00",
    "duration_label": "1 year",
    "is_unlimited": false,
    "product": {
        "id": "…",
        "name": "Digital Access",
        "slug": "digital-access"
    },
    "fields": { "badge": "Most popular", "ribbon": null }
}

```

`product` is `null` when the plan has no product. `fields` holds every public plan field, with `null` for one the plan has no value for.

#### Embedding Other Templates[​](#embedding-other-templates "Direct link to Embedding Other Templates")

A template can embed another template inline with the `<allegro-template>` element. Reference the template you want to embed by its slug with the `ref` attribute:

```html
<allegro-template ref="newsletter-cta"></allegro-template>

```

At render time the element is replaced by the referenced template's markup. The embedded template's styles are injected into the same shadow root (once, even if you embed it multiple times), and any script it carries runs after its markup is inlined.

##### Passing Field Values[​](#passing-field-values "Direct link to Passing Field Values")

Any attribute other than the reserved `ref` and `eager` is passed to the embedded template as a field value, filling its `{% %}` [placeholders](#field-placeholders) by slug:

```html
<allegro-template
    ref="newsletter-cta"
    headline="Subscribe today"
    ctaLabel="Sign up"
></allegro-template>

```

Placeholders the parent does not supply are left blank, and loops over them render nothing.

To pass a [repeatable field](#repeatable-fields), write its items as a JSON array in single quotes:

```html
<allegro-template
    ref="link-list"
    links='["https://acme.com/news", "https://acme.com/sports"]'
></allegro-template>

```

##### Lazy vs. Eager Loading[​](#lazy-vs-eager-loading "Direct link to Lazy vs. Eager Loading")

By default an embedded template is **lazy** — it loads and expands only when it scrolls into the viewport. Add the `eager` attribute to expand it immediately as the parent renders:

```html
<allegro-template ref="hero" eager></allegro-template>

```

##### Attributes[​](#attributes "Direct link to Attributes")

| Attribute     | Type    | Default | Description                                                                                                                                  |
| ------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref`         | text    | —       | Slug of the template to embed. Required.                                                                                                     |
| `eager`       | boolean | `false` | Expand immediately on render instead of waiting until the element scrolls into view.                                                         |
| *(any other)* | text    | —       | Passed to the embedded template as a field value, substituting its matching `{% slug %}` placeholder. A JSON array fills a repeatable field. |

note

Embedded templates may themselves embed others, up to a depth of 10 levels. A missing or unknown `ref`, or a cyclic reference (a template that embeds itself, directly or indirectly), is skipped — the element is removed and a warning is logged to the console.

#### Display Tracking[​](#display-tracking "Direct link to Display Tracking")

When an Interaction offers a template, the SDK automatically records whether that template was actually seen by the visitor and emits one of two events. You don't need to wire anything up — these fire on their own.

| Event                    | When it fires                                                                                                                                             |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `template_displayed`     | The first time any part of the rendered template scrolls into the viewport.                                                                               |
| `template_not_displayed` | When the visitor leaves the page having never seen an offered template — including when a scroll delay was never reached, so the template never rendered. |

Each template offered on the page reports at most one of these events per page load. Both events carry the template's ID as `object_id` and identify the Interaction in the event `data`:

| Field                   | Description                                                                                         |
| ----------------------- | --------------------------------------------------------------------------------------------------- |
| `object_type`           | Always `template`.                                                                                  |
| `object_id`             | The ID of the template that was offered.                                                            |
| `data.interaction_slug` | The slug of the Interaction that offered the template.                                              |
| `data.template_name`    | The name of the template that was offered, or `null` if it has no title.                            |
| `data.action_index`     | The position of the template's action within the Interaction.                                       |
| `data.interaction_id`   | The ID of the Interaction, when it was matched by automatic targeting. Omitted for manual triggers. |
| `data.journey_id`       | The ID of the journey that matched, or `null` for **Everyone else**. Omitted for manual triggers.   |

note

Display tracking is suppressed in preview and token-redirect flows (where delays are skipped), so previewing a template does not generate display events.

See the [Event Tracking guide](/developer/guides/event-tracking.md) for how events are sent and the fields each one carries.


---

### User Attributes

User attributes are typed profile fields your organization defines in the Allegro admin — things like a newsletter opt-in, a favorite topic, or any preference you want a member to control. This guide covers reading and writing them from the browser with the SDK, which is how you'd build a preference center on your site.

Attributes are defined by an operator first. See the [User Attributes product guide](/product/audience/user-attributes.md) for how to create them and what the types mean.

Requires a signed-in member

These methods act on the currently authenticated member. Call them after the member has signed in — an unauthenticated visitor has no profile to read or write.

#### Reading a member's attributes[​](#reading-a-members-attributes "Direct link to Reading a member's attributes")

`allegro.member.getUserAttributes()` returns every defined attribute merged with the current member's value, so you can render a whole preference form from one call:

```js
window.allegro.push(async function (allegro) {
    const attributes = await allegro.member.getUserAttributes();

    attributes.forEach(function (attribute) {
        console.log(attribute.slug, attribute.value);
    });
});

```

Each entry has the attribute's definition plus the member's current value:

| Field              | Type                                                                                        | Description                                                                                                                            |
| ------------------ | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `slug`             | `string`                                                                                    | The attribute key.                                                                                                                     |
| `name`             | `string`                                                                                    | The human-readable label.                                                                                                              |
| `description`      | `string \| null`                                                                            | The optional description.                                                                                                              |
| `type`             | `string`                                                                                    | `string`, `number`, `boolean`, `enum`, or `color`.                                                                                     |
| `options`          | `string[] \| null`                                                                          | The allowed choices, when the type is `enum`.                                                                                          |
| `value`            | `unknown`                                                                                   | The member's current value, or `null` when none is set.                                                                                |
| `user_editable`    | `boolean`                                                                                   | Whether the member may set or clear this attribute themselves.                                                                         |
| `private`          | `boolean`                                                                                   | Always `false` here. [Private attributes](#private-attributes) are never returned by the session API.                                  |
| `validation_rules` | `Array<{ type: string; value: string \| number \| null; message: string \| null }> \| null` | The validation rules configured on the attribute, or `null` when none are set. Mirror these client-side to validate before submitting. |

Every defined attribute appears in the list, whether or not the member has set a value for it — except attributes the organization marked **private**, which are never returned.

#### Reading values at page load[​](#reading-values-at-page-load "Direct link to Reading values at page load")

`getUserAttributes()` makes a request. To read values as soon as the SDK has loaded, without waiting on the network, use `allegro.member.userAttributesFromCache()`. It returns the signed-in member's values keyed by slug from a small `localStorage` cache, or `null` when the member isn't signed in or nothing is cached yet:

```js
window.allegro.push(function (allegro) {
    const attributes = allegro.member.userAttributesFromCache();

    if (attributes?.name_first) {
        greeting.textContent = 'Welcome back, ' + attributes.name_first;
    }
});

```

The SDK keeps the cache current on its own:

* It fills the cache when the member signs in, and on page load when the cache is missing or more than five minutes old. A stale value is still returned while the refresh runs.
* It clears the cache after every [write](#setting-a-value) from the SDK and fetches the new values in the background.
* It clears the cache on logout, and ignores a cache left by a different member.

Every fill or clear fires `allegro:user-attributes:updated` on `window`, with `{ values }` in `detail` (`null` after a clear). In Alpine templates the same values are on [`$store.allegro.userAttributes`](/developer/guides/alpine-state.md).

The cache is per origin, so `www.example.org` and `plus.example.org` each keep their own copy. A change made somewhere else, such as in the admin or on another device, shows up within five minutes.

#### Private attributes[​](#private-attributes "Direct link to Private attributes")

An organization can mark an attribute private. The session API then behaves as if that attribute does not exist:

* It is left out of `getUserAttributes()`.
* Reading or writing it by slug fails with a `404` `USER_ATTRIBUTE_NOT_FOUND` error — the same error you get for a slug that was never defined.
* Its value is absent from the session token's `user_attributes` claim.
* It cannot be placed on an `<allegro-form>`.

There is no way to tell a private attribute from an undefined one through the session API, so nothing in the browser needs to handle the case specially. The organization's own systems still read and write the value through the token API, and it is still delivered on webhooks.

#### File attributes[​](#file-attributes "Direct link to File attributes")

Organizations can define `file` attributes that hold an uploaded file. Only admins can set them, so the session API, the Browser SDK, and the token API reject every write to one.

A private file attribute is hidden everywhere: the session API, the Browser SDK, and the session token treat it as if it doesn't exist, and the token API doesn't list it. A public file attribute reads like any other attribute, and its value is the file's full public URL (or `null` when the member has no file):

```js
window.allegro.push(async function (allegro) {
    const attributes = await allegro.member.getUserAttributes();
    const headshot = attributes.find(function (attribute) {
        return attribute.slug === 'headshot';
    });

    // headshot.value: "https://cdn.example.com/user-attributes/.../1a2b3c4d-portrait.png"
});

```

The URL changes when an admin replaces the file.

#### Setting a value[​](#setting-a-value "Direct link to Setting a value")

`allegro.member.setUserAttribute(slug, value)` sets the value for the current member and resolves with the stored value:

```js
window.allegro.push(async function (allegro) {
    await allegro.member.setUserAttribute('wants-newsletter', true);
});

```

The value must match the attribute's type — a boolean for a boolean attribute, one of the defined options for an `enum` attribute, a hex string such as `#1a2b3c` or `#abc` for a `color` attribute (stored and returned as lowercase six-digit hex), and so on. `<allegro-form>` renders a `color` attribute with the browser's native color picker. Text and number attributes can also carry [validation rules](/product/audience/user-attributes.md#validation-rules) an operator configures (length, pattern, numeric bounds, and so on). A value that fails the type check or any of these rules is rejected with a `422` `VALIDATION_ERROR`, and the operator's configured (or default) message is returned under `data.errors.value`:

```json
{
    "data": {
        "code": "VALIDATION_ERROR",
        "errors": { "value": ["Keep it under 5 characters."] }
    }
}

```

Because that message is the one the operator wrote for the rule, you can surface it directly to the member. Writing to a `slug` that isn't a defined attribute — or is [private](#private-attributes) — is rejected with a `404` `USER_ATTRIBUTE_NOT_FOUND` error.

If the attribute's `user_editable` flag is off, the request is rejected with a 403 `USER_ATTRIBUTE_NOT_EDITABLE` error — check the flag from `getUserAttributes()` before showing the field as writable in a preference form.

#### Setting several values at once[​](#setting-several-values-at-once "Direct link to Setting several values at once")

`allegro.member.setUserAttributes(values)` takes the values keyed by attribute slug and resolves with the stored values, so a preference form saves in one round trip. A `null` value clears the member's stored value:

```js
window.allegro.push(async function (allegro) {
    const stored = await allegro.member.setUserAttributes({
        'wants-newsletter': true,
        'display-name': 'Jane',
        color: null, // clears the stored value
    });
});

```

The call is all-or-nothing: every slug is resolved and every value validated before anything is written, so nothing is saved if any single entry is bad. The three ways a call can fail each name the slugs responsible:

| Failure                                    | Response                                                                  |
| ------------------------------------------ | ------------------------------------------------------------------------- |
| A slug isn't a defined attribute           | 404 `USER_ATTRIBUTE_NOT_FOUND`, with the unknown slugs in `data.slugs`    |
| An attribute's `user_editable` flag is off | 403 `USER_ATTRIBUTE_NOT_EDITABLE`, with the blocked slugs in `data.slugs` |
| A value fails its type or validation rules | 422 `VALIDATION_ERROR`, with messages keyed `values.<slug>`               |

Validation errors carry the operator's configured message for the rule, the same as the single-value endpoint, keyed by the attribute they belong to so a form can show each message against its own field:

```json
{
    "data": {
        "code": "VALIDATION_ERROR",
        "errors": {
            "values.display-name": ["Keep it under 5 characters."],
            "values.color": ["The selected color is invalid."]
        }
    }
}

```

#### Setting attributes when a member identifies[​](#setting-attributes-when-a-member-identifies "Direct link to Setting attributes when a member identifies")

You can seed attribute values at the moment a member first identifies, before they reach a preference form — for example to record where a signup came from. Pass them to `allegro.member.identifyByEmail(email, data?, attributes?)`, or set the [`user-attributes`](/developer/components/email-form.md) attribute on an `<allegro-email-form>`.

These values **only fill attributes the member has no value for yet** — an existing value is never overwritten. The same validation and editability rules as [`setUserAttributes`](#setting-several-values-at-once) apply: an unknown slug fails with `404 USER_ATTRIBUTE_NOT_FOUND`, a non-editable one with `403 USER_ATTRIBUTE_NOT_EDITABLE`, and a bad value with `422 VALIDATION_ERROR` keyed by slug.

#### Clearing a value[​](#clearing-a-value "Direct link to Clearing a value")

`allegro.member.deleteUserAttribute(slug)` removes the member's value for an attribute:

```js
window.allegro.push(async function (allegro) {
    await allegro.member.deleteUserAttribute('wants-newsletter');
});

```

Clearing is subject to the same `user_editable` check as setting a value, and fails with the same 403 `USER_ATTRIBUTE_NOT_EDITABLE` error when the attribute isn't editable by the member, or a 404 `USER_ATTRIBUTE_NOT_FOUND` error when it is [private](#private-attributes).

#### Keeping the session token current[​](#keeping-the-session-token-current "Direct link to Keeping the session token current")

Setting or clearing values changes the member's [session token](/developer/guides/jwt.md) — attribute values are carried in its `user_attributes` claim. The SDK stores the freshly-issued token automatically after each write, so a subsequent `allegro.member.getJwt()` returns a token that reflects the change.

#### Related[​](#related "Direct link to Related")

* [User Attributes product guide](/product/audience/user-attributes.md) — Define attributes and their types in the admin.
* [JWT Verification](/developer/guides/jwt.md) — Read attribute values from the session token.
* [`MemberNamespace`](/developer/api-reference/interfaces/MemberNamespace.md) — Full SDK member API reference.


---

### Platform

Configuration and infrastructure guides for operators deploying and maintaining an Allegro instance. These guides are intended for platform administrators and developers responsible for deployment, rather than developers building on top of the SDK.

#### [🗃Setup & Configuration](/developer/platform/setup/tenants.md)

[3 items](/developer/platform/setup/tenants.md)

#### [🗃Security](/developer/platform/security/jwt.md)

[1 item](/developer/platform/security/jwt.md)

#### [🗃Integrations](/developer/platform/integrations/audience-member-sync.md)

[4 items](/developer/platform/integrations/audience-member-sync.md)

#### [🗃Event Streaming](/developer/platform/event-streaming/event-queue.md)

[3 items](/developer/platform/event-streaming/event-queue.md)

#### [🗃Operations & Monitoring](/developer/platform/operations/queue-management.md)

[5 items](/developer/platform/operations/queue-management.md)


---

### Event Queue

The event queue is a Redis List-based pipeline for delivering events from Allegro to external consumers in real time. When enabled, every event tracked by the SDK is pushed onto a per-tenant Redis List. External consumers poll the queue to read events, then issue a separate delete call to remove them.

Each destination that receives a tracked event is independent, and each is controlled by its own feature flag: the Redis queue described here is gated by `UseRedisEvents`, while writing events to the database is gated separately by `StoreEventsInDatabase`. A tenant streaming events off Redis can therefore turn off database storage without affecting the queue.

#### How It Works[​](#how-it-works "Direct link to How It Works")

##### Feature Flag[​](#feature-flag "Direct link to Feature Flag")

The queue is opt-in per tenant via the `UseRedisEvents` Pennant feature flag.

##### Event Ingestion[​](#event-ingestion "Direct link to Event Ingestion")

When an event is tracked via the SDK and the `UseRedisEvents` flag is active, Allegro pushes it onto the tenant's event queue. Each tenant has its own isolated queue. Storing the same event in the database is handled independently by the `StoreEventsInDatabase` flag, so the queue receives events whether or not database storage is enabled.

##### Reading Events (`get`)[​](#reading-events-get "Direct link to reading-events-get")

Consumers call `GET /api/platform/events` to read up to 10,000 events from the front of the queue. This is a **non-destructive** read — events remain in the queue until you explicitly delete them.

##### Deleting Events (`delete`)[​](#deleting-events-delete "Direct link to deleting-events-delete")

After processing the events, call `DELETE /api/platform/events?count=N` where `N` is the `count` value returned by the preceding `GET`. Passing the exact count prevents a race condition: any events that arrived between the `GET` and the `DELETE` are left untouched and will be returned on the next `GET`.

***

#### API Endpoints[​](#api-endpoints "Direct link to API Endpoints")

All endpoints are under the `/api/platform` prefix and require Sanctum authentication (`api` middleware + `auth:sanctum`).

***

##### `GET /api/platform/events`[​](#get-apiplatformevents "Direct link to get-apiplatformevents")

Read up to 10,000 events from the front of the queue. Non-destructive — events are not removed until `DELETE` is called.

If the `UseRedisEvents` feature flag is not active for the current tenant, returns an empty result.

**Response `200 OK`:**

```json
{
    "data": {
        "count": 2,
        "events": [
            {
                "id": "9b1f...",
                "type": "page_view",
                "session_id": "7c2a...",
                "audience_member_id": "4d8e...",
                "device_id": "1a6b...",
                "page_hostname": "example.com",
                "page_path": "/articles/hello",
                "page_title": "Hello, world",
                "property_slug": "magazine",
                "utm_source": "newsletter",
                "user_agent": "Mozilla/5.0 ...",
                "ip_address": "1.2.3.4",
                "data": { "any": "event-specific values" },
                "created_at": "2026-02-25T18:00:00+00:00",
                "updated_at": "2026-02-25T18:00:00+00:00"
            }
        ]
    }
}

```

The exact set of keys varies per event — see [Event Payload](#event-payload) below for the full field list and which fields are always present.

**Empty queue response:**

```json
{
    "data": {
        "count": 0,
        "events": []
    }
}

```

***

#### Event Payload[​](#event-payload "Direct link to Event Payload")

Each entry in the `events` array is the event as it was recorded at tracking time, serialized directly from its stored attributes. The queue carries this **raw** event — not an enriched or derived form.

Fields are included only when set

A field appears in the payload **only if it was set on the event at tracking time** — not based on whether the value is meaningful. Required and always-derived fields are set on every event (though some, such as `user_agent` and `ip_address`, may be `null`). Optional fields are set only when the SDK sent them, or when they were derived from data that was sent; an optional field that was never sent is **omitted entirely** rather than emitted as `null`. (A field a client explicitly sends as `null` is still present, as `null`.) As a result, payloads vary in shape from one event to the next.

##### Always present[​](#always-present "Direct link to Always present")

| Field           | Type            | Description                                                                                                                                                       |
| --------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`            | uuid            | Unique event identifier.                                                                                                                                          |
| `type`          | string          | Event type (e.g. `page_view`, `click`, `purchase`).                                                                                                               |
| `session_id`    | uuid            | The customer session the event belongs to.                                                                                                                        |
| `user_agent`    | string | null  | Request `User-Agent` header. `null` if the request had none.                                                                                                      |
| `ip_address`    | string | null  | Originating IP address. `null` if it could not be determined.                                                                                                     |
| `property_slug` | string | null  | Slug of the [property](/developer/guides/properties.md) the request was made on. `null` when the request used a plain organization host with no property context. |
| `created_at`    | ISO 8601 string | When the event was recorded.                                                                                                                                      |
| `updated_at`    | ISO 8601 string | Equal to `created_at` for queued events.                                                                                                                          |

##### Present when set[​](#present-when-set "Direct link to Present when set")

These appear only when the tracking call supplied them (directly or via the tracked URL).

| Field                | Type   | Source                                                                |
| -------------------- | ------ | --------------------------------------------------------------------- |
| `audience_member_id` | uuid   | The authenticated audience member, when known.                        |
| `device_id`          | uuid   | The originating device, when known.                                   |
| `page_hostname`      | string | Host parsed from the tracked URL.                                     |
| `page_path`          | string | Path parsed from the tracked URL.                                     |
| `page_title`         | string | Page title.                                                           |
| `utm_source`         | string | UTM parameter parsed from the tracked URL's query string.             |
| `utm_medium`         | string | UTM parameter parsed from the tracked URL's query string.             |
| `utm_campaign`       | string | UTM parameter parsed from the tracked URL's query string.             |
| `utm_term`           | string | UTM parameter parsed from the tracked URL's query string.             |
| `utm_content`        | string | UTM parameter parsed from the tracked URL's query string.             |
| `content_type`       | string | Type of content the event relates to.                                 |
| `content_id`         | string | Identifier of the content the event relates to.                       |
| `publisher`          | string | Publisher associated with the content.                                |
| `referer`            | string | Referring URL.                                                        |
| `object_type`        | string | Type of the object the event acted on.                                |
| `object_id`          | string | Identifier of the object the event acted on.                          |
| `context`            | string | Free-form context label supplied by the integration.                  |
| `conversion_pv_id`   | string | Page-view event ID attributed as the conversion source.               |
| `url_in_click`       | string | Destination URL for click / link-click events.                        |
| `data`               | object | Arbitrary event-specific key/value data, returned as a nested object. |

note

There is no `url` field

The tracked page URL is never stored or emitted as-is. It is broken apart into `page_hostname`, `page_path`, and any `utm_*` query parameters, and the original URL is then discarded.

Raw, not enriched

The queue reflects the event exactly as captured. Attributes populated by later, asynchronous processing — such as the parsed user-agent breakdown stored in `user_agent_parsed` — are **not** part of the queue payload.

***

##### `DELETE /api/platform/events`[​](#delete-apiplatformevents "Direct link to delete-apiplatformevents")

Remove exactly `count` events from the front of the queue. The `count` parameter is **required** and must match the `count` returned by the preceding `GET` call — this prevents accidentally deleting events that arrived after the read.

**Query parameters:**

| Parameter | Type        | Required | Description                                                                |
| --------- | ----------- | -------- | -------------------------------------------------------------------------- |
| `count`   | integer ≥ 1 | Yes      | Number of events to remove. Use the `count` value from the `GET` response. |

**Response `204 No Content`** — events removed.

**Response `422 Unprocessable Content`** — `count` is missing or invalid.

***

#### Recommended Consumer Pattern[​](#recommended-consumer-pattern "Direct link to Recommended Consumer Pattern")

```text
loop:
    GET /api/platform/events
    if count == 0 → sleep, continue

    process each event

    DELETE /api/platform/events?count={count}

```

Read all events first, process them, then delete — passing the exact `count` from the `GET` response. Because `GET` is non-destructive, events are safe to re-read if your consumer needs to retry before issuing the `DELETE`. Using the explicit count ensures events that arrived between your `GET` and `DELETE` are never accidentally removed.


---

### Heartbeat Queue

The heartbeat queue is a Redis List-based pipeline for delivering page engagement signals from Allegro to external consumers. When enabled, the SDK tracks how long each page is actively open and periodically POSTs that running total to the platform, which pushes it onto a per-tenant Redis List. External consumers poll the queue to read heartbeats, then issue a separate delete call to remove them.

It mirrors the [Event Queue](/developer/platform/event-streaming/event-queue.md) — same per-tenant FIFO List, same read-then-delete consumer contract — but carries engagement heartbeats rather than tracked events.

Standalone service

Ingest and the read/flush API are also served by the standalone [Heartbeat Service](/developer/platform/event-streaming/heartbeat-service.md). The queue contract on this page is shared by both.

#### How It Works[​](#how-it-works "Direct link to How It Works")

##### Feature Flag[​](#feature-flag "Direct link to Feature Flag")

The queue is opt-in per tenant via the `SdkHeartbeat` Pennant feature flag. The same flag also surfaces the heartbeat configuration to the SDK, so enabling it both starts the client loop and opens the queue.

##### Active Time Tracking[​](#active-time-tracking "Direct link to Active Time Tracking")

When the SDK loads, it fires a `page_view` event and starts measuring **cumulative engaged time**: the time the page is visible *and* the window has focus. Time spent backgrounded, or in a visible window that does not have focus, is not counted.

The SDK sends the running total (whole seconds) to `/api/heartbeat` on a checkpoint schedule rather than a fixed timer:

* The first checkpoint is due 15 seconds after engagement starts.
* After a checkpoint with no interaction (pointer, key, scroll, or touch) the delay doubles: 30 s, 60 s, 120 s, up to a 5 minute cap. Any interaction returns the delay to 15 s and, if a beat is more than 15 s away, pulls it forward.
* A checkpoint is only sent when the total grew since the last beat, so an idle page produces no traffic.
* After 30 minutes with no interaction the SDK sends one final beat and stops. The next interaction restarts the clock and the schedule.

Each beat carries the page\_view `event_id` and the running `active_seconds` total, so the **latest beat for an event id supersedes earlier ones**.

* Beats are sent with `navigator.sendBeacon` (falling back to `fetch` with `keepalive`) so they survive the page being backgrounded or unloaded.
* When the page is hidden or unloaded, or the window loses focus, the SDK flushes one beat with the accumulated time and pauses. When the page becomes visible and focused again, accrual resumes from where it left off.
* On SPA navigation the SDK flushes the outgoing page, then fires a new `page_view` and resets the counter for the new page.
* Every beat is also stored in the browser. If a final beat never reaches the platform (roughly one exit in ten across browsers), the next page load on the same site re-sends the stored total. Consumers keep the largest `active_seconds` per `event_id`, so a replayed total that already arrived, or one smaller than a total already received, is harmless.
* Beats that round to **0 active seconds** are not sent, so every queued heartbeat has `active_seconds` ≥ 1.

Engaged time now requires focus

As of September 2026, engaged time excludes visible-but-unfocused windows. Totals recorded before that date counted any visible page and run higher for the same behavior.

##### Heartbeat Ingestion[​](#heartbeat-ingestion "Direct link to Heartbeat Ingestion")

Each accepted heartbeat is pushed onto the tenant's heartbeat queue with a server-stamped receipt timestamp. Each tenant has its own isolated queue.

Best-effort ingestion

If Redis is unreachable when a heartbeat arrives, Allegro logs a warning and drops that beat rather than failing the request. A transient Redis outage never surfaces as an error on the client-facing beacon endpoint. Heartbeats are engagement telemetry, so an occasional dropped beat during an outage is an acceptable trade-off for keeping ingestion responsive.

##### Reading Heartbeats (`get`)[​](#reading-heartbeats-get "Direct link to reading-heartbeats-get")

Consumers call `GET /api/v1/platform/heartbeats` to read up to 10,000 heartbeats from the front of the queue. This is a **non-destructive** read — heartbeats remain in the queue until you explicitly delete them.

##### Deleting Heartbeats (`delete`)[​](#deleting-heartbeats-delete "Direct link to deleting-heartbeats-delete")

After processing the heartbeats, call `DELETE /api/v1/platform/heartbeats?count=N` where `N` is the `count` value returned by the preceding `GET`. Passing the exact count prevents a race condition: any heartbeats that arrived between the `GET` and the `DELETE` are left untouched and will be returned on the next `GET`.

***

#### API Endpoints[​](#api-endpoints "Direct link to API Endpoints")

All endpoints are under the `/api/v1/platform` prefix and require Sanctum authentication (`auth:sanctum`).

***

##### `GET /api/v1/platform/heartbeats`[​](#get-apiv1platformheartbeats "Direct link to get-apiv1platformheartbeats")

Read up to 10,000 heartbeats from the front of the queue. Non-destructive — heartbeats are not removed until `DELETE` is called.

If the `SdkHeartbeat` feature flag is not active for the current tenant, returns an empty result.

**Response `200 OK`:**

```json
{
    "data": {
        "count": 2,
        "heartbeats": [
            {
                "event_id": "9b5c1f2e-9c3a-4f1b-8a2d-1e2f3a4b5c6d",
                "active_seconds": 5,
                "received_at": "2026-02-25T18:00:05+00:00",
                "property_slug": "magazine"
            },
            {
                "event_id": "9b5c1f2e-9c3a-4f1b-8a2d-1e2f3a4b5c6d",
                "active_seconds": 10,
                "received_at": "2026-02-25T18:00:10+00:00",
                "property_slug": "magazine"
            }
        ]
    }
}

```

**Empty queue response:**

```json
{
    "data": {
        "count": 0,
        "heartbeats": []
    }
}

```

###### Heartbeat Payload[​](#heartbeat-payload "Direct link to Heartbeat Payload")

Each entry in the queue is the exact object stored at ingestion time — there is no enrichment or lookup.

| Field            | Type           | Description                                                                                                                                                               |
| ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event_id`       | string         | UUID of the `page_view` event this heartbeat belongs to. Repeated across beats; the latest wins.                                                                          |
| `active_seconds` | integer        | Cumulative active time on the page in whole seconds. Excludes time the page was backgrounded.                                                                             |
| `received_at`    | string         | ISO 8601 timestamp stamped server-side when the beat was received.                                                                                                        |
| `property_slug`  | string | null | Slug of the [property](/developer/guides/properties.md) the heartbeat was recorded on. `null` when the beat came from a plain organization host with no property context. |

Largest total wins

Multiple beats share the same `event_id` as active time grows. To compute final engagement per page view, keep the **largest `active_seconds`** for each `event_id`. Do not use the latest `received_at` as a proxy: a replayed beat can arrive minutes or days after the page view, and it may carry a total smaller than one already received, so the maximum is the only correct reducer.

***

##### `DELETE /api/v1/platform/heartbeats`[​](#delete-apiv1platformheartbeats "Direct link to delete-apiv1platformheartbeats")

Remove exactly `count` heartbeats from the front of the queue (oldest first). The `count` parameter is **required** and must match the `count` returned by the preceding `GET` call — this prevents accidentally deleting heartbeats that arrived after the read.

**Query parameters:**

| Parameter | Type        | Required | Description                                                                    |
| --------- | ----------- | -------- | ------------------------------------------------------------------------------ |
| `count`   | integer ≥ 1 | Yes      | Number of heartbeats to remove. Use the `count` value from the `GET` response. |

**Response `204 No Content`** — heartbeats removed.

**Response `422 Unprocessable Content`** — `count` is missing or invalid.

***

#### Recommended Consumer Pattern[​](#recommended-consumer-pattern "Direct link to Recommended Consumer Pattern")

```text
loop:
    GET /api/v1/platform/heartbeats
    if count == 0 → sleep, continue

    process each heartbeat (keep the largest active_seconds per event_id)

    DELETE /api/v1/platform/heartbeats?count={count}

```

Read all heartbeats first, process them, then delete — passing the exact `count` from the `GET` response. Because `GET` is non-destructive, heartbeats are safe to re-read if your consumer needs to retry before issuing the `DELETE`. Using the explicit count ensures heartbeats that arrived between your `GET` and `DELETE` are never accidentally removed.

***

#### Configuration[​](#configuration "Direct link to Configuration")

| Config key                   | Default   | Description                                                                                                                                     |
| ---------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `heartbeat.redis_connection` | `default` | Laravel Redis connection the heartbeat list lives on. Set `HEARTBEAT_REDIS_CONNECTION=heartbeats` to use the dedicated `heartbeats` connection. |


---

### Heartbeat Service

Heartbeats are the platform's highest-volume request. They are handled by a standalone Node.js service, `@allegrocdp/heartbeat`, rather than the Laravel application. The service accepts beats from the SDK, batches them onto the same per-tenant Redis list described in [Heartbeat Queue](/developer/platform/event-streaming/heartbeat-queue.md), and serves the queue's read and flush API. Laravel keeps reading the list for health reporting and its own queue API.

#### How a beat is attributed[​](#how-a-beat-is-attributed "Direct link to How a beat is attributed")

The SDK loader embeds a `heartbeat` block in the tenant config when the `SdkHeartbeat` feature is active:

```json
{
    "enabled": true,
    "intervalMs": 15000,
    "maxIntervalMs": 300000,
    "endpoint": "https://hb.example.org/v1/beat",
    "token": "1.eyJ0…"
}

```

`token` is an HMAC-SHA256 claim of the tenant slug and property slug, signed by Laravel with `HEARTBEAT_SIGNING_KEYS`. The service verifies it with the same keys, so no Host header, database, or feature flag check happens on ingest. Turning the flag off removes the block and the SDK stops beating.

#### Endpoints[​](#endpoints "Direct link to Endpoints")

| Method   | Path                                          | Auth                                                | Purpose                                                                                                                       |
| -------- | --------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `POST`   | `/v1/beat`                                    | ingest token in body                                | Accept one beat. Form or JSON body with `token`, `event_id`, `active_seconds`. Returns `204`.                                 |
| `GET`    | `/v1/heartbeats?tenant=<tenant_slug>`         | `Authorization: Bearer <HEARTBEAT_CONSUMER_SECRET>` | Same response as `GET /api/v1/platform/heartbeats`. Optional `?limit=` from 1 to 10,000; omitted or empty defaults to 10,000. |
| `DELETE` | `/v1/heartbeats?tenant=<tenant_slug>&count=N` | same bearer                                         | Removes `N` (required, 1–10,000) from the front. Returns `200 {"data":{"removed":N}}`.                                        |
| `GET`    | `/healthz`                                    | none                                                | `200` with buffer counters and per-tenant queue lengths, `503` when Redis is unreachable.                                     |

`/healthz` reports two different things. `buffer` holds this worker's in-memory counters: `buffered` is beats waiting on the next Redis write, `flushedTotal` and `droppedTotal` count up from when the process started and reset on restart. `queue` is read from Redis: `tenants` maps each tenant slug to the length of its list, and `total` sums them. It is the backlog the consumer has not drained yet, so it rises and falls. A tenant appears once the service has written a beat for it; the slugs are tracked in the `heartbeat:tenants` set under the same key prefix.

The consumer routes use one static secret shared with the CDP rather than Sanctum keys; `?tenant=` is required because the secret names no organization. When `HEARTBEAT_CONSUMER_SECRET` is unset the routes are not registered. Organization-scoped API keys continue to work against Laravel's `/api/v1/platform/heartbeats`.

##### Errors[​](#errors "Direct link to Errors")

Every error body is `{"data":{"message","code"}}`.

| Endpoint                      | Status | `code`                    | Cause                                                                        |
| ----------------------------- | ------ | ------------------------- | ---------------------------------------------------------------------------- |
| `POST /v1/beat`               | `401`  | `INVALID_HEARTBEAT_TOKEN` | `token` is missing, malformed, or fails signature verification.              |
| `POST /v1/beat`               | `422`  | `VALIDATION_ERROR`        | `event_id` is not a UUID, or `active_seconds` is not a non-negative integer. |
| `GET`/`DELETE /v1/heartbeats` | `401`  | `UNAUTHENTICATED`         | The bearer token is missing or does not match `HEARTBEAT_CONSUMER_SECRET`.   |
| `GET`/`DELETE /v1/heartbeats` | `400`  | `TENANT_REQUIRED`         | `?tenant=` is missing or blank.                                              |
| `GET`/`DELETE /v1/heartbeats` | `422`  | `VALIDATION_ERROR`        | `limit` or `count` is not an integer from 1 to 10,000.                       |

`POST /v1/beat` and its `OPTIONS` preflight always carry `Access-Control-Allow-Origin: *` (and the matching `Access-Control-Allow-Methods`/`-Headers`), including on error responses, because the SDK calls it directly from the browser. The `/v1/heartbeats` consumer routes are server-to-server and set no CORS headers.

#### Configuration[​](#configuration "Direct link to Configuration")

| Variable                                                    | Default                    | Description                                                                                           |
| ----------------------------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------- |
| `PORT`, `HOST`                                              | `8787`, `::`               | Listen address. `::` accepts both IPv6 and IPv4.                                                      |
| `REDIS_URL`                                                 | `redis://127.0.0.1:6379/0` | The heartbeat Redis. Laravel must point `HEARTBEAT_REDIS_CONNECTION=heartbeats` at the same instance. |
| `REDIS_KEY_PREFIX`                                          | `allegro-database-`        | Must equal Laravel's `REDIS_PREFIX` (derived from `APP_NAME` when unset).                             |
| `HEARTBEAT_SIGNING_KEYS`                                    | required                   | Comma-separated. Must match Laravel's value.                                                          |
| `HEARTBEAT_CONSUMER_SECRET`                                 | unset                      | Static bearer for the consumer routes. When unset they are disabled.                                  |
| `BUFFER_FLUSH_MS`, `BUFFER_MAX_BATCH`, `BUFFER_MAX_PENDING` | `25`, `1000`, `100000`     | Batching: flush interval, early-flush size, and the cap beyond which beats are dropped and counted.   |
| `WEB_CONCURRENCY`                                           | CPU count                  | Worker processes.                                                                                     |
| `TRUST_PROXY`, `LOG_LEVEL`                                  | `true`, `info`             | Proxy headers and Pino level.                                                                         |

On the Laravel side set `HEARTBEAT_INGEST_URL` to the service's `/v1/beat` URL, `HEARTBEAT_SIGNING_KEYS` to the same keys, and `HEARTBEAT_REDIS_CONNECTION=heartbeats` with `HEARTBEAT_REDIS_URL` pointing at the service's Redis. Leaving `HEARTBEAT_INGEST_URL` empty keeps heartbeats on `POST /api/heartbeat`. If `HEARTBEAT_SIGNING_KEYS` is empty, the SDK also stays on that legacy route even when `HEARTBEAT_INGEST_URL` is set, since a beat sent to the service without a token would only get a `401`.

#### Running locally[​](#running-locally "Direct link to Running locally")

```bash
HEARTBEAT_SIGNING_KEYS=local-dev-heartbeat-key HEARTBEAT_CONSUMER_SECRET=local-dev-consumer-secret npm run heartbeat:dev

```

Then set `HEARTBEAT_INGEST_URL=http://127.0.0.1:8787/v1/beat` in `.env` and reload a page with the SDK embedded. `redis-cli LRANGE allegro-database-tenant:<tenant_slug>:heartbeats 0 -1` shows the beats.

#### Deployment[​](#deployment "Direct link to Deployment")

The service runs as its own Laravel Cloud application, using the Node.js runtime, with `packages/allegro-platform/packages/allegro-heartbeat` as the application's root directory. The package is not an npm workspace of the repository root, so it has its own `package-lock.json` and installs on its own.

| Setting       | Value                                      |
| ------------- | ------------------------------------------ |
| Node.js       | 24                                         |
| Build command | `npm ci && npm run build`                  |
| Start command | `npm start`                                |
| Cache         | A Valkey cache attached to the environment |

Cloud sets `PORT` and routes traffic to it. Leave `HOST` unset: Cloud's startup probes connect over IPv6, so binding `0.0.0.0` fails them. Cloud injects `REDIS_URL` for the attached cache; set `HEARTBEAT_SIGNING_KEYS`, `HEARTBEAT_CONSUMER_SECRET`, and `REDIS_KEY_PREFIX` on the environment yourself. Keep Scale-to-Zero off, since the SDK expects the ingest endpoint to answer immediately.

`WEB_CONCURRENCY` caps how many workers the service forks. Keep it low. Each worker keeps its own Redis connection and its own buffer, so raising it splits the same beats across more buffers and costs Redis batching efficiency — one worker already sustains tens of thousands of beats per second (see the package `README.md`'s Benchmark section). Scale out with replicas instead; the service holds nothing across requests beyond the in-flight buffer, which drains on `SIGTERM`.

The package also includes a `Dockerfile`, built with the package directory as its context, for hosts that run containers.


---

### Audience Member Sync

The audience member sync system gives packages a standard way to pull external data (CRM membership status, donor records, email lists, etc.) into Allegro and keep it fresh. Providers register once; the platform handles scheduling, queueing, login-path freshness, and failure isolation.

#### How It Works[​](#how-it-works "Direct link to How It Works")

Each external integration is a **sync provider** — a class implementing `Allegro\Contracts\SyncProvider`. Providers declare:

* **What to sync** — a `membersToSync()` query scoping which audience members are in scope for scheduled runs.
* **How fresh** — a `refreshInterval()` for scheduled cadence, and an optional `maxAgeOnLogin()` for how stale data can be before a login triggers a synchronous sync.
* **When to run** — the platform runs a single global 5-minute heartbeat (`allegro-audience:sync:tick`) that fans out a per-tenant evaluation job. Per provider, the evaluator checks the `audience_sync_runs` row for the last dispatch time against `refreshInterval()` before dispatching a new set of sync jobs.

At JWT generation time, `SyncProfilesOrchestrator::ensureFreshForLogin()` runs synchronously before the `JsonWebTokenGenerating` event fires. Listeners that add membership claims to the JWT are therefore guaranteed up-to-date data. Scheduled runs page through the member base with `DispatchAudienceSyncChunkJob` and enqueue work onto the `bulk` queue — one rate-limited `SyncAudienceMemberBatchJob` per 50 members for providers implementing `PoolableSyncProvider`, or one `SyncAudienceMemberJob` per member otherwise.

***

#### Quick Start[​](#quick-start "Direct link to Quick Start")

Extend `Allegro\Services\AudienceSync\AbstractSyncProvider` — it provides sensible defaults so you only override what you need.

```php
namespace Acme\Sync;

use Allegro\Models\AudienceMember;
use Allegro\Services\AudienceSync\AbstractSyncProvider;
use Carbon\CarbonInterval;
use Illuminate\Database\Eloquent\Builder;

class AcmeMembershipSync extends AbstractSyncProvider
{
    public function name(): string
    {
        return 'acme_membership'; // matches the audience_member_external_profiles.provider key
    }

    public function refreshInterval(): CarbonInterval
    {
        return CarbonInterval::hours(6);
    }

    public function maxAgeOnLogin(): ?CarbonInterval
    {
        // Sync synchronously on login when the row is older than 30 minutes.
        // Return null to make this a background-only provider.
        return CarbonInterval::minutes(30);
    }

    public function membersToSync(): Builder
    {
        // Only queue jobs for members active in the last 30 days.
        return $this->membersLoggedInWithin(30);
    }

    public function sync(AudienceMember $member): void
    {
        $data = app(AcmeApiClient::class)->fetchMember($member->email);

        $member->externalProfiles()->updateOrCreate(
            ['provider' => $this->name()],
            ['data' => $data],
        );

        // Grant or revoke entitlements based on $data...
    }
}

```

`AbstractSyncProvider` defaults:

| Method                   | Default                  |
| ------------------------ | ------------------------ |
| `maxAgeOnLogin()`        | `null` (background-only) |
| `isAvailableForTenant()` | `true`                   |

***

#### Registering a Provider[​](#registering-a-provider "Direct link to Registering a Provider")

Call `SyncProviderRegistry::register()` once in your package's `ServiceProvider::boot()`:

```php
use Allegro\Services\AudienceSync\SyncProviderRegistry;

public function boot(SyncProviderRegistry $registry): void
{
    $registry->register(AcmeMembershipSync::class);
}

```

`register()` is idempotent — calling it twice with the same class is safe (e.g., under Octane). Registering two *different* classes with the same `name()` throws `DuplicateSyncProviderException` at boot time.

***

#### Scoping Members[​](#scoping-members "Direct link to Scoping Members")

##### `membersLoggedInWithin(int $days)`[​](#membersloggedinwithinint-days "Direct link to membersloggedinwithinint-days")

`AbstractSyncProvider` provides this helper for the common case:

```php
public function membersToSync(): Builder
{
    return $this->membersLoggedInWithin(30); // members who logged in within 30 days
}

```

It queries `audience_members.last_active_at`, a denormalized column updated whenever a member authenticates or refreshes their JWT. Use this to avoid dispatching jobs for inactive members.

##### Custom queries[​](#custom-queries "Direct link to Custom queries")

Return any `Builder<AudienceMember>` from `membersToSync()`. Return a query that matches zero rows (e.g., `AudienceMember::query()->whereRaw('0 = 1')`) to disable scheduled sync entirely while still allowing on-login sync.

***

#### Staleness Configuration[​](#staleness-configuration "Direct link to Staleness Configuration")

Two knobs control freshness:

| Method              | Type              | Purpose                                                                                       |
| ------------------- | ----------------- | --------------------------------------------------------------------------------------------- |
| `refreshInterval()` | `CarbonInterval`  | How old a row can be before the scheduled job re-syncs it                                     |
| `maxAgeOnLogin()`   | `?CarbonInterval` | How old a row can be before a login triggers a synchronous sync; `null` = never sync on login |

##### Background-only provider[​](#background-only-provider "Direct link to Background-only provider")

Return `null` from `maxAgeOnLogin()` (the default). The provider runs on the scheduler cadence only. Use when upstream latency is too high for the login path, or when data does not affect the JWT.

```php
public function maxAgeOnLogin(): ?CarbonInterval
{
    return null; // background only; login never blocks on this provider
}

```

##### Combined (most common)[​](#combined-most-common "Direct link to Combined (most common)")

Use both: schedule a background refresh and also sync on login when data is stale relative to `maxAgeOnLogin()`. The login threshold is typically tighter than `refreshInterval()` so a member always gets fresh data even if the last scheduled run was hours ago.

***

#### Tenant Availability[​](#tenant-availability "Direct link to Tenant Availability")

Override `isAvailableForTenant()` to gate a provider on tenant-level configuration:

```php
public function isAvailableForTenant(): bool
{
    return config('acme.enabled', false);
}

```

The platform evaluates this predicate at every entry point: the login orchestrator, the Artisan command, and inside the queued job. A provider that returns `false` here is silently skipped — no error, no job dispatched.

***

#### Side Effects in `sync()`[​](#side-effects-in-sync "Direct link to side-effects-in-sync")

`sync()` may do more than write the primary `audience_member_external_profiles` row. Common patterns:

**Write member meta:**

```php
$member->meta()->updateOrCreate(
    ['key' => 'total_donations'],
    ['value' => $data['total_donations']],
);

```

**Grant or revoke entitlements:**

```php
if ($data['is_active_member']) {
    $member->entitlements()->updateOrCreate(
        ['source_provider' => $this->name(), 'resource_id' => $resourceId],
        ['expires_at' => null],
    );
} else {
    $member->entitlements()
        ->where('source_provider', $this->name())
        ->delete();
}

```

Idempotency is required

`sync()` may be called multiple times for the same member. Use upserts keyed on `source_provider` for entitlement writes and `updateOrCreate` for profile rows. Wrap writes in a `DB::transaction()` so a throw mid-sync rolls back partial state.

***

#### Login Path[​](#login-path "Direct link to Login Path")

`JsonWebToken::generate()` calls `SyncProfilesOrchestrator::ensureFreshForLogin($member)` before dispatching `JsonWebTokenGenerating`. The orchestrator:

1. Iterates providers registered for the current tenant where `maxAgeOnLogin() !== null`.
2. For each, checks whether the primary `audience_member_external_profiles` row is younger than `maxAgeOnLogin()`.
3. If stale or missing, calls `sync()` synchronously — taking the same `Cache::lock` used by `SyncAudienceMemberJob` to prevent concurrent writes.
4. Catches and logs any exceptions (provider failures as `warning`, unexpected infrastructure failures as `error`). The JWT is issued regardless of sync failures.

The `JsonWebTokenGenerating` event fires only after all login-path providers have run, so JWT claim listeners always see the freshest available data.

***

#### Scheduled Runs[​](#scheduled-runs "Direct link to Scheduled Runs")

Scheduling is driven by a single global entry — there is no per-provider cron registration. The platform registers **one** scheduler entry in `routes/console.php`:

```text
allegro-audience:sync:tick   →   every 5 minutes

```

Provider authors implement `refreshInterval()` as the single source of truth for cadence. Do **not** implement a `scheduleCron()` method — it was removed from the contract. The scheduler does not look at your provider individually.

##### How the tick works[​](#how-the-tick-works "Direct link to How the tick works")

1. **`allegro-audience:sync:tick`** iterates every registered tenant and dispatches an `EvaluateTenantSyncsJob` for each via `$tenant->execute(...)`, so the evaluation runs bound to that tenant's context.

2. Inside the job, for each provider returned by `SyncProviderRegistry::availableForTenant()`:

   * The job loads (or creates) the `audience_sync_runs` row keyed on `provider`. The table is tenant-scoped via `UsesTenantConnection`, so each tenant has its own row per provider.
   * **Mid-flight guard** — a non-null `last_synced_id` means a paging chain is running; a fresh heartbeat (`updated_at`) leaves it alone, a stale one resumes the chain from the saved cursor.
   * **Due-check guard** — if `last_dispatched_at + refreshInterval()` is still in the future, the provider isn't due yet; skip.
   * Otherwise the job claims the run window (`last_dispatched_at = now()`) and starts a `DispatchAudienceSyncChunkJob` chain. The chain pages through `membersToSync()` with a keyset cursor, 10,000 members per page, and enqueues the page's sync jobs via `Bus::bulk` — batch jobs for poolable providers, per-member jobs otherwise — before chaining itself to the next page.

3. Workers on the `bulk` queue then process the sync jobs. Each job re-checks freshness per member before syncing, so a synchronous login sync between dispatch and execution is respected — no double-sync.

The evaluator does not track run completion. Gating on `last_dispatched_at + refreshInterval()` alone means the worst case is a re-dispatch before the prior run has fully drained — harmless because syncs are idempotent per `(member, provider)` and skipped when the profile is fresh. The trade-off avoids the stuck-forever failure mode where a missing "finished" signal would permanently block re-evaluation.

##### Continuous syncing[​](#continuous-syncing "Direct link to Continuous syncing")

Everything above describes the default **burst** pacing: a provider claims its run window and the chunk chain pages the member base as fast as backpressure and the rate limiter allow, finishing well inside the interval and idling out the rest of it.

Continuous mode changes the rate and nothing else. It is opt-in per tenant — the switch is on the landlord tenant's **Audience Sync** page, and it writes the `audience_sync.continuous` tenant setting:

```php
TenantSetting::set(ContinuousSyncPlanner::SETTING_KEY, true);

```

With it on, `EvaluateTenantSyncsJob` claims the same run window against the same `audience_sync_runs` row, but instead of starting a self-chaining `DispatchAudienceSyncChunkJob`, each tick advances the cursor itself by `ContinuousSyncPlanner::sliceSize()` members:

```text
membersToSync()->where('id', '>', $run->last_synced_id)->orderBy('id')->limit($slice)

```

That is the burst pager's own query, so a lap covers exactly the members the provider asked for. The slice is the provider's member count divided by the number of 5-minute ticks in its `refreshInterval()`, plus half again as slack so a lap finishes a little early rather than drifting past the interval it is meant to fit in. The count is cached for an hour — it only paces the lap — except for a zero, which is never cached, so a provider whose window fills up after an empty count is not left crawling a member a tick until the entry expires.

An empty page ends the lap and clears the cursor, which hands the provider back to the ordinary interval gate: the next lap opens once `refreshInterval()` has passed since this one began. So a lap takes about one refresh interval, and laps do not overlap.

Providers need no changes, and everything the sync dashboards read keeps its meaning: the cursor is the lap's position, `last_dispatched_at` is when the lap started, and the statuses are the real ones.

###### Why the cursor, and not staleness ordering[​](#why-the-cursor-and-not-staleness-ordering "Direct link to Why the cursor, and not staleness ordering")

Selecting the least-recently-synced members each tick is the obvious design and it has a trap. Ordering by a profile's timestamp means reading from `audience_member_external_profiles` and then filtering by `membersToSync()`, and a member who has a profile row but has fallen out of the provider's scope — past the activity window, holding no entitlement — is never selected, so nothing ever advances their timestamp. Those rows accumulate at the head of the ordering permanently. Once there are more of them than one slice's worth, every tick selects nothing but ineligible rows and the sync stops dead, silently, with the run row still looking healthy.

Walking the member query by cursor has no such state to get stuck on. The cursor advances past whatever it selected, ineligible members are never in the result to begin with, and a member whose sync fails is simply retried on the next lap.

Ordering by staleness buys little in exchange: a lap reaches every member once per interval either way, and a member synced on login meanwhile costs one row in a `SELECT` rather than an API call, because the sync jobs re-check freshness per member before calling out.

###### Concurrency and backpressure[​](#concurrency-and-backpressure "Direct link to Concurrency and backpressure")

Ticks for one tenant can overlap when the `bulk` queue is congested, and two of them would read the same cursor and dispatch the same members twice. The run row is read, advanced and saved inside a per-tenant, per-provider cache lock — the read included, so an overlapping tick cannot act on a cursor that has already moved; a tick that cannot take the lock waits for the next one.

The slice reaches the queue before the cursor moves past it, so an enqueue that fails is retried from the same cursor on the next tick rather than leaving those members unsynced for the rest of the lap. A tick is skipped outright while the `bulk` queue holds more than `MAX_QUEUE_BACKLOG` pending jobs, the same backpressure the chunk chain applies: a slice sized off a large member base, or paced against a short `refreshInterval()`, can still outrun the workers and the rate limiter. The pacing slack absorbs the skipped ticks.

###### Switching modes[​](#switching-modes "Direct link to Switching modes")

The switch takes effect on the next tick and nothing needs restarting. The paced tick is the cursor's only writer while continuous mode is on: a `DispatchAudienceSyncChunkJob` that runs — from a chain already in flight when the switch was flipped, or from a manual CLI run — stops without touching the cursor, and the paced ticks take over the rest of the lap from where it stands.

Turning it off hands the cursor back to the chunk chain, which resumes paging it at full speed — but not immediately. A paced lap in progress leaves a fresh heartbeat on the run row, which the evaluator cannot tell from a live chain, so the chain resumes only once that heartbeat crosses the stall window (`STALL_AFTER_MINUTES`, an hour). Turning the switch off mid-lap therefore costs up to an hour before full-speed paging picks up from the cursor.

##### Backpressure and failure semantics[​](#backpressure-and-failure-semantics "Direct link to Backpressure and failure semantics")

The chunk chain is built so a very large member base (1M+) or a failing page can never flood the queue:

* **Backpressure** — before paging, the chunk job checks the `bulk` queue depth. Above `MAX_QUEUE_BACKLOG` pending jobs it defers itself for a few minutes (bumping the run heartbeat so the evaluator doesn't mistake the pause for a stall) instead of enqueueing another page. A run therefore never sits more than a couple of pages ahead of what the workers and rate limiter drain, regardless of member count.
* **Transient failures** — the chunk job retries in place (3 tries, 30s backoff). Re-running a page is safe: dispatch is idempotent downstream.
* **Terminal failures** — after exhausting retries, `failed()` clears the cursor and reports a descriptive exception. The run ends visibly instead of the evaluator resuming the same failing page every stall window, and the already-claimed `last_dispatched_at` defers the next full run to the provider's regular interval.
* **Silent deaths** (deploy kill, OOM) never reach `failed()`; those are the case the evaluator's stall-gate resume exists for.

Because cadence is just `refreshInterval()` + the row-based guards, a provider that wants "daily" simply returns `CarbonInterval::day()`; one that wants "every 15 minutes" returns `CarbonInterval::minutes(15)`. The next tick (within 5 minutes) will pick it up.

##### Running manually[​](#running-manually "Direct link to Running manually")

The manual CLI still works for backfills and debugging. It bypasses the refresh-interval throttle, claims the same `audience_sync_runs` row, and starts the same `DispatchAudienceSyncChunkJob` chain. Claiming the row is what stops the scheduler double-dispatching the provider for that tenant, and the command refuses to start while a chain is already mid-flight. Under continuous syncing the claim is the whole of a manual run: it opens a lap now, past the interval gate, and the paced ticks walk it — no chain is started, because the cursor must have a single writer.

```bash
# Sync all available providers for one tenant
php artisan allegro-audience:sync --tenant=42

# Sync one provider only for one tenant
php artisan allegro-audience:sync acme_membership --tenant=42

```

***

#### Queue Configuration[​](#queue-configuration "Direct link to Queue Configuration")

`EvaluateTenantSyncsJob` and every member sync job — `SyncAudienceMemberJob`, `SyncAudienceMemberBatchJob` and `SyncUserAttributeFromExternalProfilesJob` — run on the `bulk` queue, which has its own Laravel Cloud managed queue and its own worker pool — see [Queue Management](/developer/platform/operations/queue-management.md). Locally the queue is covered by the workers `composer run dev` starts.

`DispatchAudienceSyncChunkJob` is the exception: it runs on `default`, above the queue it feeds, so the dispatcher never starves behind the member jobs it enqueues.

Keeping the member jobs off `high` and `default` means a CRM outage that backs up retries, or a tick that fans out a job per member across every tenant, cannot delay a login email. `bulk` runs on the Pro compute class because it carries jobs well past the 90-second Flex cap.

`SyncAudienceMemberJob` properties (non-poolable providers, one job per member):

| Property     | Value | Description                                                                 |
| ------------ | ----- | --------------------------------------------------------------------------- |
| `$tries`     | 3     | Retried up to 3 times before landing in `failed_jobs`                       |
| `$backoff`   | 60s   | Seconds between retries                                                     |
| `$uniqueFor` | 600s  | `ShouldBeUnique` window — deduplicates queued jobs per `(member, provider)` |

`SyncAudienceMemberBatchJob` properties (poolable providers, up to 50 members per job, requests pooled 10 at a time):

| Property       | Value                                           | Description                                                                                  |
| -------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `middleware`   | `RateLimitedWithRedis('audience-sync-batches')` | Per-provider batches-per-minute cap (`allegro.audience_sync.batches_per_minute`, default 10) |
| `retryUntil()` | 24h                                             | Time-bounded retries — rate-limiter releases consume attempts, so no tries count             |
| `$backoff`     | 60s                                             | Seconds between retries                                                                      |

Batch jobs are deliberately **not** unique: per-job unique lock writes at member volume have exhausted Redis memory before, and duplicates are absorbed by the per-member freshness check.

***

#### Testing[​](#testing "Direct link to Testing")

Use `Allegro\Testing\FakeSyncProvider` in feature tests:

```php
use Allegro\Services\AudienceSync\SyncProviderRegistry;
use Allegro\Testing\FakeSyncProvider;
use Carbon\CarbonInterval;

beforeEach(function () {
    // Reset the singleton so registrations from real boot don't bleed in.
    app()->forgetInstance(SyncProviderRegistry::class);
});

it('dispatches a sync job for active members', function () {
    $provider = new FakeSyncProvider(
        providerName: 'fake',
        refresh: CarbonInterval::hour(),
        loginAge: CarbonInterval::minutes(30),
    );

    app()->instance(FakeSyncProvider::class, $provider);
    app(SyncProviderRegistry::class)->register(FakeSyncProvider::class);

    // ...assert jobs dispatched, sync call count, etc.
});

```

`SyncProviderRegistry::register()` takes a class string and resolves the provider from the container. Bind your configured instance with `app()->instance(...)` first so the registry resolves your instance instead of constructing a fresh one with defaults.

`FakeSyncProvider` constructor parameters (in order):

| Parameter             | Default  | Description                                                                                         |
| --------------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `$providerName`       | `'fake'` | Return value of `name()`                                                                            |
| `$refresh`            | `null`   | `refreshInterval()`; when `null`, falls through to `CarbonInterval::hour()` via `refreshInterval()` |
| `$loginAge`           | `null`   | `maxAgeOnLogin()`                                                                                   |
| `$availableForTenant` | `true`   | `isAvailableForTenant()`                                                                            |
| `$membersQuery`       | `null`   | Closure returning a `Builder`; defaults to empty                                                    |

`$onSync` is a public property (not a constructor argument) — assign directly: `$fake->onSync = fn ($member) => ...`. `FakeSyncProvider::$syncCallCount` tracks how many times `sync()` was called.

##### Simulating staleness[​](#simulating-staleness "Direct link to Simulating staleness")

Use `Carbon::setTestNow()` to move time forward past an interval:

```php
use Carbon\Carbon;

it('re-syncs stale data on login', function () {
    $member = AudienceMember::factory()->create();
    $member->externalProfiles()->create([
        'provider' => 'fake',
        'data' => [],
        'updated_at' => now()->subHour(),
    ]);

    Carbon::setTestNow(now()->addHours(2));

    // trigger login path...
});

```

##### Asserting dispatched jobs[​](#asserting-dispatched-jobs "Direct link to Asserting dispatched jobs")

```php
use Allegro\Jobs\SyncAudienceMemberJob;
use Illuminate\Support\Facades\Queue;

it('dispatches jobs on scheduled run', function () {
    Queue::fake();

    $this->artisan('allegro-audience:sync', ['provider' => 'fake']);

    Queue::assertPushed(SyncAudienceMemberJob::class);
});

```

***

#### End-to-End Flow[​](#end-to-end-flow "Direct link to End-to-End Flow")

```text
Login path
----------
JsonWebToken::generate($member)
  └─ SyncProfilesOrchestrator::ensureFreshForLogin($member)
       └─ foreach provider where maxAgeOnLogin() !== null
            └─ EnsureFreshProfile::for($member, $providerName)
                 ├─ row fresh? → return true (no sync)
                 └─ stale/missing → Cache::lock → provider->sync($member)
  └─ event(JsonWebTokenGenerating)  ← listeners see fresh data

Scheduled path
--------------
scheduler fires allegro-audience:sync:tick  (every 5 minutes)
  └─ foreach tenant
       └─ EvaluateTenantSyncsJob (dispatched via $tenant->execute(...))
            └─ foreach provider in registry->availableForTenant()
                 ├─ load audience_sync_runs row
                 ├─ due-check (last_dispatched_at + refreshInterval() <= now)? skip
                 └─ SyncAudienceMemberJob::dispatch per member
                      ├─ update last_dispatched_at = now()
                      └─ worker picks up each job
                           └─ Cache::lock → freshness re-check → provider->sync($member)

```

The `Cache::lock` is shared between the login path and the queued job path. If a login sync is in progress when a worker picks up a job (or vice versa), one path blocks for up to 5 seconds then yields.

***

#### Operations[​](#operations "Direct link to Operations")

##### Force-resyncing a member[​](#force-resyncing-a-member "Direct link to Force-resyncing a member")

From the audience member detail page in the admin UI, the **Sync Status** panel lists every registered provider with its last-synced timestamp and a **Re-sync now** button. Clicking it dispatches `SyncAudienceMemberJob` with the `$force = true` flag, bypassing the freshness check.

##### Verifying freshness[​](#verifying-freshness "Direct link to Verifying freshness")

Query `audience_member_external_profiles` for the member and provider:

```sql
SELECT provider, updated_at
FROM audience_member_external_profiles
WHERE audience_member_id = ?
ORDER BY provider;

```

The `updated_at` column is the staleness anchor. Compare it against the provider's `refreshInterval()` to determine whether a job will re-sync on the next scheduled run.

##### Checking sync status for a tenant[​](#checking-sync-status-for-a-tenant "Direct link to Checking sync status for a tenant")

Each tenant has a read-only **Audience Sync** page that reports what the next scheduled tick will do, without you querying the database. Reach it from **Global Settings → Tenants → \[tenant] → Audience Sync**.

The page lists every registered provider with its last run, next run, cadence, the number of members due on the next run (the `bulk` backlog), and profile freshness. Providers gated behind a package the tenant has not enabled are listed separately, since they never run for that tenant.

Each provider carries an overall status derived from the same `audience_sync_runs` state the scheduler reads, so it always matches what the next tick will do:

| Status    | Meaning                                                                                                                    |
| --------- | -------------------------------------------------------------------------------------------------------------------------- |
| Running   | A paging run is mid-flight and its heartbeat is recent — the provider is actively syncing members in chunks.               |
| Stalled   | A paging run has a saved cursor but no chunk activity for over an hour. The next tick resumes it from the cursor.          |
| Never run | The provider has never been dispatched for this tenant.                                                                    |
| Overdue   | The refresh window has opened but no dispatch followed — either there is nothing to sync, or the scheduler is not ticking. |
| Idle      | The provider has run, is within its refresh window, and has nothing due yet. This is the healthy resting state.            |
| Inactive  | The provider is not available for this tenant (resolved but switched off — for example, no email provider is configured).  |

note

Profile freshness and the members-due backlog are the expensive columns on a large tenant, so they load a moment after the rest of the page.

##### Rolling out a new provider[​](#rolling-out-a-new-provider "Direct link to Rolling out a new provider")

1. Implement `SyncProvider` (or extend `AbstractSyncProvider`) in your package.
2. Register in your `ServiceProvider::boot()`.
3. Gate the provider with `isAvailableForTenant()` if rollout should be gradual.
4. Deploy. The next tick (within 5 minutes) will pick up the provider and evaluate it per tenant.
5. To backfill immediately: `php artisan allegro-audience:sync your_provider_name --tenant={id}`.

##### Recovering from failed jobs[​](#recovering-from-failed-jobs "Direct link to Recovering from failed jobs")

Failed jobs land in `failed_jobs` after 3 retries. Once the upstream service recovers, flush and re-dispatch:

```bash
php artisan queue:retry all

```

Or let the next scheduled run naturally re-queue jobs for members still in scope — `failed_jobs` can safely be flushed after upstream recovery.


---

### Cloudflare OAuth for Allegro Edge

Allegro Edge deploys a worker into each organization's own Cloudflare account. Organizations grant that access from **Organization Settings → Allegro Edge**. With a platform OAuth client configured, they click **Connect Cloudflare** and approve Allegro on Cloudflare's consent screen. Without one, the page only offers the API token fallback, where an admin creates a token in Cloudflare and pastes it in.

You register one OAuth client for the whole Allegro instance. Every organization authorizes that same client.

#### Environment Variables[​](#environment-variables "Direct link to Environment Variables")

| Variable                        | Required | Description                                                                         |
| ------------------------------- | -------- | ----------------------------------------------------------------------------------- |
| `EDGE_CLOUDFLARE_CLIENT_ID`     | Yes      | The client ID Cloudflare shows after you create the client.                         |
| `EDGE_CLOUDFLARE_CLIENT_SECRET` | Yes      | The client secret. Cloudflare shows it once, so copy it when the client is created. |
| `EDGE_CLOUDFLARE_AUTHORIZE_URL` | No       | Consent URL. Defaults to `https://dash.cloudflare.com/oauth2/auth`.                 |
| `EDGE_CLOUDFLARE_TOKEN_URL`     | No       | Token URL. Defaults to `https://dash.cloudflare.com/oauth2/token`.                  |
| `EDGE_CLOUDFLARE_REVOKE_URL`    | No       | Revocation URL. Defaults to `https://dash.cloudflare.com/oauth2/revoke`.            |
| `EDGE_CLOUDFLARE_SCOPE_ACCOUNT` | No       | Scope for reading accounts. Defaults to `account-settings.read`.                    |
| `EDGE_CLOUDFLARE_SCOPE_ZONES`   | No       | Scope for reading zones. Defaults to `zone.read`.                                   |
| `EDGE_CLOUDFLARE_SCOPE_SCRIPTS` | No       | Scope for editing Workers scripts. Defaults to `workers-scripts.edit`.              |
| `EDGE_CLOUDFLARE_SCOPE_ROUTES`  | No       | Scope for editing Workers routes. Defaults to `workers-routes.write`.               |
| `EDGE_CLOUDFLARE_SCOPE_REFRESH` | No       | Scope that issues a refresh token. Defaults to `offline_access`.                    |

When `EDGE_CLOUDFLARE_CLIENT_ID` or `EDGE_CLOUDFLARE_CLIENT_SECRET` is missing, **Connect Cloudflare** is hidden and organizations can only connect with an API token.

#### Redirect URL[​](#redirect-url "Direct link to Redirect URL")

Cloudflare redirects every organization back to one URL on your instance's main domain, not the organization's own subdomain:

```text
https://your-allegro-instance.com/edge/oauth/callback

```

The domain is your `APP_URL`. Allegro reads the organization from the signed `state` parameter, forwards the request to that organization's settings page, and finishes the connection there under the signed-in admin's session.

#### Creating the OAuth Client[​](#creating-the-oauth-client "Direct link to Creating the OAuth Client")

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select the account that owns the Allegro instance.

2. Go to **Manage Account → OAuth clients** and click **Create client**.

3. Fill in the client details:

   * **Client name**: the name organizations see on the consent screen, such as `Allegro Edge`.
   * **Response type**: `code`.
   * **Grant type**: Authorization Code, with Refresh Token.
   * **Token authentication method**: `client_secret_basic`.
   * **Redirect URLs**: `https://your-allegro-instance.com/edge/oauth/callback`.

4. Click **Continue** and add the scopes below. Leave all of them required.

5. Click **Create client**, then copy the client ID and client secret into the environment variables above.

| Dashboard scope        | Scope ID                | Why Allegro needs it                                          |
| ---------------------- | ----------------------- | ------------------------------------------------------------- |
| Account Settings: Read | `account-settings.read` | Lists the accounts the grant covers so an admin can pick one. |
| Zone: Read             | `zone.read`             | Matches each property's hostname to a zone.                   |
| Workers: Edit          | `workers-scripts.edit`  | Uploads and updates each property's edge worker.              |
| Workers Routes: Edit   | `workers-routes.write`  | Binds each worker to its property's hostname.                 |

Allegro also requests `offline_access` so Cloudflare issues a refresh token and deploys keep working after the access token expires. It is not one of the dashboard checkboxes; the Refresh Token grant type covers it.

Check the scope names

Cloudflare lists the exact scope IDs at `GET https://api.cloudflare.com/client/v4/oauth/scopes`. If they differ from the defaults above, set the `EDGE_CLOUDFLARE_SCOPE_*` variables to match. Allegro requests exactly those IDs and checks the granted scopes against them.

#### Making the Client Public[​](#making-the-client-public "Direct link to Making the Client Public")

New clients are private. A private client can only be authorized by members of the Cloudflare account that created it, which is enough for testing against your own zones.

Before other organizations can connect, make the client public:

1. Verify ownership of the client's domain, as described in Cloudflare's [client domain verification](https://developers.cloudflare.com/fundamentals/oauth/create-an-oauth-client/#client-url-domain-ownership-verification) guide.
2. Fill in the fields Cloudflare requires for public clients, such as the logo, privacy policy, and terms of service URLs.
3. In **OAuth clients**, open the client's action menu and choose **Change Visibility**.

Public is permanent

Cloudflare cannot switch a public client back to private. Finalize the client name, logo, and scopes before you make it public.

#### Connection Lifetime[​](#connection-lifetime "Direct link to Connection Lifetime")

An OAuth grant belongs to the Cloudflare user who approved it. If that person leaves the organization's Cloudflare account or loses access to it, Cloudflare stops honoring the grant. The Allegro Edge settings page then shows **Needs reconnect**, and deploys stop until someone connects again.

The settings page shows who connected the account and when, so you can trace a broken connection to a person. Organizations that want a connection that doesn't depend on one person can use an account-owned API token instead.

#### API Token Fallback[​](#api-token-fallback "Direct link to API Token Fallback")

The API token option stays available whether or not OAuth is configured. **Create token in Cloudflare** opens Cloudflare's token form with the needed permissions selected. The admin creates the token and pastes it into Allegro.

API tokens don't report their permissions. Allegro checks read access to Workers scripts and routes, and marks edit access as unverified until the first deploy tries it.


---

### GitHub Template Sync

Allegro supports syncing templates from a GitHub repository. When connected, templates are automatically synced whenever commits are pushed to the configured default branch.

#### How It Works[​](#how-it-works "Direct link to How It Works")

1. An organization admin installs the Allegro GitHub App on their GitHub account or organization.
2. After installation, Allegro records a sync link pointing the tenant at that installation.
3. The admin selects a repository and default branch to sync from, which completes the link and registers a push webhook on the repository.
4. On every push to that branch, a sync job is queued to update templates from the repository.

A single GitHub App installation can serve **many** repositories across **many** tenants. Each tenant syncs from at most one repository, but the same repository can be shared by several tenants. The installation, the per-tenant sync link, and the per-repository webhook are stored separately so one installation (for example on an `alleyinteractive` organization) can map different repositories to different tenants. See [Mapping Repositories at the Platform Level](#mapping-repositories-at-the-platform-level).

***

#### Setting Up the GitHub App[​](#setting-up-the-github-app "Direct link to Setting Up the GitHub App")

##### 1. Create a GitHub App[​](#1-create-a-github-app "Direct link to 1. Create a GitHub App")

In your GitHub organization or personal account, go to **Settings → Developer settings → GitHub Apps** and create a new app with the following settings:

| Setting                                    | Value                                                             |
| ------------------------------------------ | ----------------------------------------------------------------- |
| **GitHub App name**                        | Your app name (e.g. `Allegro Template Sync`)                      |
| **Homepage URL**                           | Your Allegro instance URL                                         |
| **Webhook URL**                            | `https://your-app.com/github/webhooks`                            |
| **Webhook secret**                         | A random secret string (set as `GITHUB_WEBHOOK_SECRET` in `.env`) |
| **Post installation → Setup URL**          | `https://your-app.com/github/callback`                            |
| **Post installation → Redirect on update** | ✅ Enabled                                                        |

**Permissions required:**

* Repository contents: Read-only

**Subscribe to events:**

* Push
* Installation
* Installation repositories

##### 2. Configure Environment Variables[​](#2-configure-environment-variables "Direct link to 2. Configure Environment Variables")

After creating the GitHub App, add these values to your `.env`:

```dotenv
# GitHub App credentials
GITHUB_APP_ID=<your_app_id>
GITHUB_APP_PRIVATE_KEY="<your_pem_private_key>"
GITHUB_WEBHOOK_SECRET=<your_webhook_secret>

# The installation URL shown on the GitHub Sync settings page
# Format: https://github.com/apps/<app-slug>/installations/new
GITHUB_APP_URL=https://github.com/apps/your-app-name/installations/new

```

note

`GITHUB_APP_PRIVATE_KEY` should be the full PEM content of the private key generated in your GitHub App settings.

***

#### Installation Flow[​](#installation-flow "Direct link to Installation Flow")

When an admin visits **Organization Settings → GitHub Sync** and clicks **Connect GitHub Repository**:

1. They are sent to `GITHUB_APP_URL?state={encrypted_tenant_id}` on GitHub.
2. They install the app on their GitHub account/organization.
3. GitHub fires an `installation.created` webhook to `/github/webhooks`, which creates a tenant-less `GitHubAppInstallation` record on the landlord database.
4. GitHub redirects the user back to `/github/callback?installation_id=XXX&state={encrypted_tenant_id}`.
5. The callback decrypts the state to identify the tenant and records a `GitHubRepoSync` row linking that tenant to the installation (with no repository selected yet).
6. The admin is redirected to the GitHub Sync settings page where they select the repository and default branch.
7. Upon submitting the form, the sync link is completed, a push webhook is registered on the repository, and an initial sync is queued.

important

The `Setup URL` in your GitHub App settings **must** be set to `https://your-app.com/github/callback`. Without this, the installation cannot be linked to the tenant.

***

#### Mapping Repositories at the Platform Level[​](#mapping-repositories-at-the-platform-level "Direct link to Mapping Repositories at the Platform Level")

The self-serve flow above always returns the admin to the tenant they started from, so it can only ever connect one repository to that one tenant. To map several repositories from a single shared installation to several tenants — for example, when one organization's installation hosts a separate template repository per tenant — super admins use the Allegro Admin tenant pages.

From **Tenants** in the Global Settings navigation, open a tenant's detail page. The GitHub Template Sync section lists every known installation; pick an installation, choose one of its repositories, set the branch, and connect. This creates the same `GitHubRepoSync` link as the self-serve flow, without a GitHub round-trip, so different repositories under one installation can be assigned to different tenants.

Installations only appear here after the GitHub App has been installed on the organization (which fires the `installation.created` webhook). There is no manual way to register an installation ID.

***

#### Sync Process[​](#sync-process "Direct link to Sync Process")

Template sync is handled by the `SyncGitHubTemplates` job. It:

* Fetches each top-level directory containing an `index.html` from the repository at the configured branch (with optional `index.css`, `index.js`, and `template.json`).
* Creates or updates corresponding `Template` records (matched by `github_path`).
* Force-deletes synced templates no longer present in the repository.

Syncs are triggered:

* **Automatically** when a push arrives on a configured default branch (via webhook). A push to a shared repository **fans out**: the job is dispatched once for every tenant whose sync link points at that repository and whose branch matches.
* **Manually** via the **Sync Now** button on the GitHub Sync settings page (rate-limited to once per minute).

***

#### Disconnecting[​](#disconnecting "Direct link to Disconnecting")

Admins can disconnect GitHub sync from **Organization Settings → GitHub Sync → Disconnect**. This:

* Deletes the tenant's `GitHubRepoSync` link.
* Deletes the repository's push webhook **only if no other tenant still syncs that repository** (the webhook is reference-counted per repository).
* Removes the `sync_source` from all templates, making them editable again.

Templates are **not deleted** when disconnecting.

Disconnecting a tenant from the Allegro Admin removes the sync link and reference-counted webhook the same way, but leaves that tenant's templates untouched.

Lifecycle teardown

When the GitHub App is uninstalled (`installation.deleted`) or loses access to a repository (`installation_repositories` removed), Allegro tears down the affected sync links and webhooks but never deletes synced templates — they remain in each tenant exactly as they were.

***

#### Database Schema[​](#database-schema "Direct link to Database Schema")

All three tables live on the landlord database. The installation, the per-tenant sync link, and the per-repository webhook are stored separately so one installation can map many repositories to many tenants.

##### `github_app_installations`[​](#github_app_installations "Direct link to github_app_installations")

The GitHub App installation itself — one row per GitHub account/organization.

| Column            | Type                | Description                   |
| ----------------- | ------------------- | ----------------------------- |
| `installation_id` | `bigint` (unique)   | GitHub's installation ID      |
| `account_login`   | `string` (nullable) | GitHub account/org login name |

##### `github_repo_syncs`[​](#github_repo_syncs "Direct link to github_repo_syncs")

The tenant ↔ repository link — one row per tenant. `repository` and `default_branch` are null between installing the app and selecting a repository.

| Column             | Type                   | Description                            |
| ------------------ | ---------------------- | -------------------------------------- |
| `tenant_id`        | `bigint` (unique)      | The linked Allegro tenant              |
| `installation_id`  | `bigint`               | GitHub installation this link uses     |
| `repository`       | `string` (nullable)    | Full repository name (e.g. `org/repo`) |
| `default_branch`   | `string` (nullable)    | Branch to sync from                    |
| `last_sync_at`     | `timestamp` (nullable) | Time of last successful sync           |
| `last_sync_hash`   | `string` (nullable)    | Commit SHA of last sync                |
| `last_sync_errors` | `json` (nullable)      | Errors from the last sync attempt      |

##### `github_repo_webhooks`[​](#github_repo_webhooks "Direct link to github_repo_webhooks")

The push webhook registered on a repository — one row per `(installation, repository)`, shared by every tenant syncing that repository and reference-counted on disconnect.

| Column            | Type     | Description                            |
| ----------------- | -------- | -------------------------------------- |
| `installation_id` | `bigint` | GitHub installation that owns it       |
| `repository`      | `string` | Full repository name (e.g. `org/repo`) |
| `webhook_id`      | `bigint` | GitHub's webhook ID on the repository  |


---

### Stripe Webhook Setup

Allegro fulfills purchases — creating entitlements and recording the transaction — when it receives a `checkout.session.completed` event from Stripe. Without a webhook configured, fulfillment only happens when the member is redirected back to your site after checkout. Configuring the webhook makes fulfillment reliable regardless of what the member does after paying.

#### Environment Variables[​](#environment-variables "Direct link to Environment Variables")

Before setting up the webhook endpoint, make sure the following environment variables are set in your Allegro instance:

| Variable                   | Description                                                                                      |
| -------------------------- | ------------------------------------------------------------------------------------------------ |
| `STRIPE_CONNECT_CLIENT_ID` | The client ID of your Stripe Connect application (from the Stripe Dashboard → Connect settings). |
| `STRIPE_SECRET_KEY`        | Your Stripe platform secret key (`sk_live_...` or `sk_test_...`).                                |
| `STRIPE_PUBLISHABLE_KEY`   | Your Stripe publishable key (`pk_live_...` or `pk_test_...`).                                    |
| `STRIPE_WEBHOOK_SECRET`    | The signing secret for the webhook endpoint (see below). Set this after creating the endpoint.   |

#### Webhook URL[​](#webhook-url "Direct link to Webhook URL")

Allegro exposes a single webhook endpoint for all payment providers:

```text
POST /api/webhooks/stripe

```

The full URL for your instance is:

```text
https://your-allegro-instance.com/api/webhooks/stripe

```

Replace `your-allegro-instance.com` with your actual domain.

#### Creating the Webhook Endpoint[​](#creating-the-webhook-endpoint "Direct link to Creating the Webhook Endpoint")

1. Log in to the [Stripe Dashboard](https://dashboard.stripe.com).
2. Go to **Developers → Webhooks**.
3. Click **Add endpoint**.
4. Set **Endpoint URL** to `https://your-allegro-instance.com/api/webhooks/stripe`.
5. Under **Listen to**, choose **Events on Connected accounts**.
6. Click **Select events**, then find and check `checkout.session.completed`.
7. Click **Add events**, then click **Add endpoint**.

Use Connected Account events

Allegro uses Stripe Connect. The webhook must be set to listen for events on **Connected accounts**, not just your platform account. If you configure it for your platform account only, checkout completions from connected Stripe accounts will not trigger the webhook.

#### Setting the Signing Secret[​](#setting-the-signing-secret "Direct link to Setting the Signing Secret")

After creating the endpoint, Stripe displays a **Signing secret** (starts with `whsec_`).

1. Copy the signing secret.
2. Set it as the `STRIPE_WEBHOOK_SECRET` environment variable in your Allegro deployment.
3. Restart the application to pick up the new value.

Allegro uses this secret to verify that incoming webhook requests are genuinely from Stripe. Requests with an invalid or missing signature are silently ignored.

#### How It Works[​](#how-it-works "Direct link to How It Works")

When Stripe sends a `checkout.session.completed` event to your endpoint:

1. Allegro verifies the `Stripe-Signature` header against `STRIPE_WEBHOOK_SECRET`.
2. Allegro resolves the tenant from the session metadata.
3. Allegro fulfills the checkout: creates the purchase record, grants entitlements to the audience member, and records any associated events.
4. Allegro returns `200 OK`.

The controller always returns `200` regardless of outcome — this prevents Stripe from retrying on transient application errors that should not be retried.

note

If a `checkout.session.completed` event arrives before the member has been redirected back (which can happen if the redirect is slow), Allegro handles it gracefully. The token exchange on the return page detects the already-fulfilled purchase and skips duplicate fulfillment.

#### Testing with the Stripe CLI[​](#testing-with-the-stripe-cli "Direct link to Testing with the Stripe CLI")

During local development you can forward webhook events from Stripe to your local instance using the Stripe CLI:

```bash
stripe listen --forward-to http://localhost:8000/api/webhooks/stripe

```

The CLI prints a temporary webhook signing secret on startup. Set this as `STRIPE_WEBHOOK_SECRET` in your local `.env` while testing:

```text
STRIPE_WEBHOOK_SECRET=whsec_...

```

Trigger a test event to verify the endpoint is working:

```bash
stripe trigger checkout.session.completed

```

Check your application logs for the fulfillment result.

#### Related[​](#related "Direct link to Related")

* [One-off Purchases](/developer/guides/payment/purchases.md) — Initiating checkout from the SDK
* [Payment Provider (Product)](/product/entitlements/payment-provider.md) — Connecting a payment provider as an operator


---

### Emergency Banner

The emergency banner is a full-width strip shown at the top of every tenant and landlord dashboard — useful for announcing an incident or scheduled maintenance. It is platform-wide: one message, read the same everywhere. It appears only in the dashboard, never on a reader-facing site.

Only super admins can set it. From the Allegro Admin, open **Settings → Banner**:

| Field            | What it does                                                                                                   |
| ---------------- | -------------------------------------------------------------------------------------------------------------- |
| **Enabled**      | Turns the banner on or off. A message is required while it is on.                                              |
| **Message**      | The text shown in the banner (up to 300 characters).                                                           |
| **Details link** | An optional `http` or `https` URL. When set, the banner shows a **View details** link that opens in a new tab. |

Changes apply immediately across the whole installation — no deploy or cache-clear. Each person can dismiss the banner, and it stays hidden for them until the message or link changes, at which point it reappears.

The on/off state is the **Emergency banner** platform feature flag; see [Feature Flags](/developer/platform/setup/feature-flags.md) for how platform-wide flags work.


---

### Health Checks

Allegro exposes two read-only HTTP endpoints designed to be polled by an external monitor (an uptime checker, a metrics scraper, or an on-call alerting system). One reports the health of a single tenant's queues; the other reports the health of the platform-wide job queues. Both return an HTTP `503` when their backing service can't be reached, so even a naive "is the status code 200?" check trips on a degraded state.

These endpoints are part of the REST API — see the [REST API reference](/rest-api/) for the authoritative request and response schemas. This guide explains what they report and how to wire up monitoring against them.

#### Tenant health[​](#tenant-health "Direct link to Tenant health")

```text
GET /api/v1/health

```

Authenticated with a Sanctum bearer token; the token's user must be able to view the tenant. The endpoint reports the depth and oldest-item age of that tenant's Redis-backed queues — the [Event Queue](/developer/platform/event-streaming/event-queue.md) and the [Heartbeat Queue](/developer/platform/event-streaming/heartbeat-queue.md).

```json
{
    "status": "ok",
    "tenant": "tenant_123",
    "redis": { "reachable": true },
    "queues": {
        "events": { "depth": 0, "oldest_age_seconds": null },
        "heartbeats": { "depth": 12, "oldest_age_seconds": 34 }
    }
}

```

| Field                         | Meaning                                                                             |
| ----------------------------- | ----------------------------------------------------------------------------------- |
| `status`                      | `ok` when Redis is reachable, `degraded` otherwise.                                 |
| `redis.reachable`             | Whether the queue's Redis backend responded.                                        |
| `queues.*.depth`              | Number of items currently waiting in the queue.                                     |
| `queues.*.oldest_age_seconds` | Age in seconds of the oldest item still waiting, or `null` when the queue is empty. |

When Redis cannot be reached, `status` is `degraded`, every queue value is `null`, and the response status code is `503`.

A steadily rising `depth` or `oldest_age_seconds` means a consumer has fallen behind and is no longer draining the queue fast enough — see the [Event Queue](/developer/platform/event-streaming/event-queue.md) and [Heartbeat Queue](/developer/platform/event-streaming/heartbeat-queue.md) guides for how consumers read and delete items.

#### Platform health[​](#platform-health "Direct link to Platform health")

```text
GET /api/v1/landlord/health

```

Authenticated with a Sanctum bearer token belonging to a **super admin**, and served only in the landlord context. It reports the backlog of every background queue listed in `allegro.queues`, plus the failed-job count.

```json
{
    "status": "ok",
    "queue": { "reachable": true },
    "queues": {
        "high": { "pending": 0 },
        "default": { "pending": 2 },
        "bulk": { "pending": 0 }
    },
    "failed_jobs": 0
}

```

| Field              | Meaning                                                                                                            |
| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `status`           | `ok` when the queue backend is reachable, `degraded` otherwise.                                                    |
| `queue.reachable`  | Whether the queue backend responded.                                                                               |
| `queues.*.pending` | Number of jobs waiting on that queue. On managed queues this is SQS's approximate count, which lags a few seconds. |
| `failed_jobs`      | Failed jobs across all queues in the last 7 days, or `null` if the failed-job driver cannot be counted.            |

Each queue is reported separately, keyed by its name. For what the `high`, `default`, and `bulk` queues carry, see [Queue Management](/developer/platform/operations/queue-management.md). When the backend is unreachable, `status` is `degraded`, `queues` is empty, `failed_jobs` is `null`, and the response status code is `503`.

To enumerate the tenants a monitor should poll for tenant-level health, a super admin can list them with `GET /api/v1/landlord/tenants`.

Failed job window

`queue:prune-failed --hours=168` runs daily, so `failed_jobs` is a rolling seven-day count rather than a lifetime total. Failures older than that are removed from the `failed_jobs` table and are no longer retryable.

#### Setting up monitoring[​](#setting-up-monitoring "Direct link to Setting up monitoring")

* **Alert on the status code.** Treat any non-`200` (especially `503`) as a page-worthy event — the endpoints are built so a plain HTTP check is enough.
* **Trend the depths.** A single high reading can be a momentary spike; a depth or backlog age that climbs across consecutive polls is a stuck consumer.
* **Watch `failed_jobs`.** A non-zero, growing count signals jobs erroring out rather than simply queuing.

note

Both endpoints require authentication, so configure your monitor with a Sanctum token. See [REST API Authentication](/developer/api/authentication.md) for how to issue one.


---

### Mail Forwarding

Mail forwarding redirects an outgoing message to a single inbox instead of its real recipients. It replaces the recipients rather than copying them — there is no bcc or "copy" mode, so a forwarded message's original recipients receive nothing.

Applies in every environment, including production

Nothing in the forwarding path checks the environment. A tenant whose override is set to "Always forward" stops its real members from receiving any mail — in production, exactly as it would in staging. There is no safety net beyond the configuration itself.

#### Configuration[​](#configuration "Direct link to Configuration")

Forwarding has two levels: a platform-wide default, and a per-tenant override that wins over it.

##### Platform default[​](#platform-default "Direct link to Platform default")

Open **Settings → Mail** (landlord admin) to configure the platform-wide default:

| Field                         | Description                                                                                                                                          |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Forward all outgoing mail** | The default used by any tenant that has not overridden it.                                                                                           |
| **Forward to**                | The inbox used by tenants that have not set their own forward address.                                                                               |
| **Bypass addresses**          | One address per line. Recipients matching every entry are delivered normally instead of forwarded. Used by tenants that have not set their own list. |

##### Tenant override[​](#tenant-override "Direct link to Tenant override")

Open **Tenants → \<tenant> → Mail Forwarding** to configure a specific tenant:

| Field                | Description                                                                                             |
| -------------------- | ------------------------------------------------------------------------------------------------------- |
| **Forwarding**       | A three-way choice: use the platform default, always forward, or never forward.                         |
| **Forward to**       | This tenant's forward address. Leave blank to use the platform address.                                 |
| **Bypass addresses** | This tenant's bypass allowlist, which replaces the platform list. Leave blank to use the platform list. |

Set the override from this screen rather than by writing the underlying `mail_forward_override` tenant setting directly. The three choices map to a stored boolean, or to no stored value at all for "use the platform default", and that distinction is what the mail path reads. A value written by hand through a generic settings command is stored as text, which is not the same thing.

##### Resolution[​](#resolution "Direct link to Resolution")

The tenant override wins whenever it is set to something other than "use the platform default":

| Platform default | Tenant override          | Result        |
| ---------------- | ------------------------ | ------------- |
| Off              | Use the platform default | Not forwarded |
| Off              | Always forward           | **Forwarded** |
| Off              | Never forward            | Not forwarded |
| On               | Use the platform default | **Forwarded** |
| On               | Always forward           | **Forwarded** |
| On               | Never forward            | Not forwarded |

Mail sent outside any tenant context — landlord notifications, for example — has no tenant override to read, so it follows the platform default and the platform address.

#### Choosing a forward address[​](#choosing-a-forward-address "Direct link to Choosing a forward address")

The tenant's forward address wins whenever it is set. An empty tenant address falls back to the platform address rather than disabling forwarding — it means "use the platform address," not "don't forward." If neither the tenant nor the platform has an address configured, nothing is forwarded, even when forwarding is otherwise enabled.

#### Bypass addresses[​](#bypass-addresses "Direct link to Bypass addresses")

A bypass allowlist is configured platform-wide under **Settings → Mail**, and each tenant may configure its own under **Tenants → (tenant) → Mail Forwarding**. A tenant's list **replaces** the platform list rather than adding to it, so a tenant can narrow the allowlist as well as widen it. A tenant that leaves its list empty uses the platform list.

Only the platform list can be emptied to mean "bypass nothing" — an empty tenant list means "use the platform list," the same way an empty tenant forward address does.

Entries are one per line and may be literal addresses or `*` wildcard patterns:

```text
qa@example.com
*@example.com
qa-*@example.com

```

A message is delivered normally only when **every** recipient (To, Cc, and Bcc) matches an entry on the list. A single recipient that doesn't match is enough to forward the whole message.

Both the message recipients and the bypass entries are normalized before they're compared:

* Addresses are lowercased.
* `+` sub-address tags are stripped, so `jane+test@example.com` matches a bypass entry of `jane@example.com`.
* Gmail addresses are canonicalized further: dots in the local part are removed and `googlemail.com` is treated as an alias of `gmail.com`, so `jane.doe@googlemail.com` matches a bypass entry of `janedoe@gmail.com`. This applies only to `gmail.com` and `googlemail.com` addresses.

#### What a forwarded message looks like[​](#what-a-forwarded-message-looks-like "Direct link to What a forwarded message looks like")

When a message is forwarded, its Cc and Bcc recipients are cleared and the original recipients are surfaced three ways so they're easy to spot in a shared forwarding inbox:

* **Subject prefix** — the subject is prefixed with the original recipients in brackets, for example `[user@example.com] Your magic link`.
* **Body banner** — a `Forwarded — originally to: …` banner is prepended to the message body.
* **`X-Original-To` header** — the original recipients are also preserved in an `X-Original-To` header.

The original recipients are shown exactly as they were addressed — the normalization described above is used only for bypass matching, not for these labels.


---

### Maintenance Mode

Maintenance mode freezes a single tenant during planned maintenance. While it is active, every one of that tenant's web and API requests returns HTTP `503` until you turn it back off. Use it for work that must not run against live traffic — database migrations, a data backfill, or any change where in-flight requests would see an inconsistent state.

Maintenance mode is scoped to one tenant. Putting one organization into maintenance has no effect on any other tenant, and the Allegro Admin itself is never affected — so the dashboard you use to turn maintenance off stays reachable the whole time.

#### Enabling maintenance mode[​](#enabling-maintenance-mode "Direct link to Enabling maintenance mode")

Maintenance mode is a per-tenant feature flag, toggled from the Allegro Admin (Global Settings → Tenants):

1. Open **Tenants** and select the tenant you want to freeze.
2. Switch to the **Features** tab.
3. Toggle **Maintenance mode** on.

The change applies immediately — there is no deploy or cache-clear step. Turn the toggle off from the same screen to restore normal traffic.

Super admins only

Managing a tenant's feature flags from the Allegro Admin requires super-admin access.

#### What visitors and integrations see[​](#what-visitors-and-integrations-see "Direct link to What visitors and integrations see")

While the flag is on, the tenant behaves as follows:

| Surface                       | Behavior                                                          |
| ----------------------------- | ----------------------------------------------------------------- |
| Tenant web pages              | Return HTTP `503 Service Unavailable`.                            |
| Tenant API (REST and session) | Return HTTP `503 Service Unavailable`.                            |
| `503` responses               | Include a `Retry-After: 120` header so clients know to try again. |
| Allegro Admin                 | Unaffected — remains reachable so you can turn maintenance off.   |

Because both the REST and session APIs return `503`, embedded SDK components and any external integrations that call the tenant will pause rather than act on partial data. The `Retry-After` header lets well-behaved clients and monitors back off and retry automatically once maintenance ends.

Downtime is real

Maintenance mode is a hard stop, not a read-only mode. Enable it only for as long as the underlying work takes, and confirm the toggle is off before considering the maintenance window closed.

#### Related[​](#related "Direct link to Related")

* [Feature Flags](/developer/platform/setup/feature-flags.md) — how platform-wide and per-tenant flags work.
* [Health Checks](/developer/platform/operations/health-checks.md) — monitor a tenant's queues before and after a maintenance window.


---

### Queue Management

Allegro runs background jobs on [Laravel Cloud managed queues](https://laravel.com/cloud/docs/queues). Laravel Cloud provisions each queue, runs its workers on dedicated instances separate from web traffic, and scales the worker pool to the work waiting to be processed — including down to zero.

There is no supervisor to configure and no worker process count to tune. Queues are created and sized in the Laravel Cloud canvas, not in this repository.

#### Queues[​](#queues "Direct link to Queues")

Allegro routes jobs across three queues. **A managed queue serves exactly one queue name**, so each of these needs its own managed queue in every Cloud environment.

| Queue     | Compute class | Purpose                                                                                                                                                                  |
| --------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `high`    | Flex          | Magic link and OTP email — the only jobs a person is waiting on                                                                                                          |
| `default` | Flex          | General background work: profile pre-warming, webhook deliveries, event backfill, domain polling, newsletter subscribes, template sync, and the audience sync dispatcher |
| `bulk`    | Pro           | Long-running work: the audience sync member jobs, and CSV exports                                                                                                        |

Jobs are routed by the `#[Queue]` attribute on the job class, or by `onQueue()` in a Mailable's constructor. A job with neither lands on `default`, which is where most of them belong.

The same list lives in `allegro.queues` (`packages/allegro-platform/config/allegro.php`), which is what the [health endpoint](/developer/platform/operations/health-checks.md) reports pending counts for. Adding a queue means adding it there **and** creating the managed queue in Cloud — a job routed to a name with no managed queue behind it is accepted and then never processed.

##### Compute class[​](#compute-class "Direct link to Compute class")

Flex workers scale to zero and wake in under a second, but cap a job at 90 seconds. Pro workers are always on with a minimum of one worker and have no runtime limit.

Two jobs declare a `$timeout` above the Flex cap, and they are why `bulk` is Pro: `SyncUserAttributeFromExternalProfilesJob` (3600s) and `GenerateExportJob` (3600s). Every other queued class runs at or below the framework default of 60s, so `high` and `default` are both Flex and both scale to zero between bursts.

`bulk` also carries the only workload that can fan out without bound — one sync tick can page through every member of every tenant. Both reasons point the same way: keep the slow, wide work off the queues that serve logins.

`DispatchAudienceSyncChunkJob` is the deliberate exception: it runs on `default` at a 60s timeout, above the queue it feeds, so the dispatcher never starves behind the member jobs it enqueues.

Priority is per-queue, not across queues

`high`, `default` and `bulk` each have their own managed queue and their own independent worker pool, so `high` does not preempt `default` — but it also cannot be starved by a `bulk` flood, which is the failure that strict priority exists to prevent. The name is a description of the latency budget, not a rank.

#### Configuration[​](#configuration "Direct link to Configuration")

Deploying a managed queue sets `QUEUE_CONNECTION=cloud` for the environment automatically. The `cloud` connection itself is injected at runtime by the framework from `LARAVEL_CLOUD_MANAGED_QUEUES_CONFIG`, which is why `config/queue.php` does not define one.

| Variable           | Where                | Description                                                        |
| ------------------ | -------------------- | ------------------------------------------------------------------ |
| `QUEUE_CONNECTION` | Set by Laravel Cloud | `cloud` on Cloud environments; `redis` locally                     |
| `REDIS_HOST`       | Local                | Still required — the event and heartbeat queues use Redis directly |
| `REDIS_PORT`       | Local                | Redis port (default: `6379`)                                       |

#### Local development[​](#local-development "Direct link to Local development")

Managed queues exist only on Laravel Cloud. Locally, jobs run through the `redis` connection with plain workers:

```bash
composer run dev

```

That runs `php artisan dev`, which starts one worker per queue named in `allegro.queues` alongside Octane, Pail, and Vite. A worker each mirrors Cloud, where every managed queue has its own workers, and keeps a long-running `bulk` job from stalling the `high` queue that OTP and magic-link mail rides on. Adding a queue to `allegro.queues` adds its worker automatically.

To run one in isolation:

```bash
php artisan queue:work --queue=high --tries=1

```

A single worker can also drain several queues in priority order by passing a comma-separated list, which is a `queue:work` feature:

```bash
php artisan queue:work --queue=high,default,bulk --tries=1

```

That list is **not** valid as a managed queue name — commas are not permitted, and a managed queue serves one name.

#### Monitoring[​](#monitoring "Direct link to Monitoring")

Queue depth, throughput, memory, and worker counts are on the **Queues** dashboard under an environment's **Monitoring** tab in Laravel Cloud. Failed jobs are listed there too, with retry and bulk actions.

Failed jobs are pruned after 7 days

A scheduled `queue:prune-failed --hours=168` command runs daily, so failed jobs older than 7 days drop off the list automatically. Retry or inspect a failed job before then.

Allegro also exposes a machine-readable summary at the platform [health endpoint](/developer/platform/operations/health-checks.md) for external monitors.

Slow and failing jobs are tracked in [Nightwatch](https://laravel.com/docs/nightwatch), which is where alerting belongs.

#### Pausing and purging[​](#pausing-and-purging "Direct link to Pausing and purging")

To stop a queue from processing during an incident or downstream maintenance, pause it from the queue's dropdown menu on the Cloud canvas. Workers scale to zero, in-flight jobs finish gracefully, and dispatched jobs accumulate until you resume.

warning

`queue:pause` is not supported

The `queue:pause` Artisan command does not work against managed queues. Pause from the Laravel Cloud canvas instead.

Purging a queue from the same menu discards every waiting job. It cannot be undone and does not affect jobs already being processed.

#### Job design constraints[​](#job-design-constraints "Direct link to Job design constraints")

Managed queues are backed by SQS, which imposes limits the previous Redis backend did not:

* **At-least-once delivery.** A job whose worker crashes or is terminated becomes visible again and runs on another worker. Jobs must tolerate running more than once.
* **Delays cap at 15 minutes.** Requesting longer from `->delay()` throws.
* **Releases cap at 12 hours.** `SendWebhookDeliveryJob` clamps a receiver's `Retry-After` to this ceiling.
* **Payloads cap at 256 KB.** Pass scalar identifiers to job constructors rather than models or large arrays.


---

### JWT Key Management

Allegro signs member session tokens with per-tenant RSA-2048 key pairs using RS256. This page covers the key lifecycle and how to manage keys in production.

#### Key Lifecycle[​](#key-lifecycle "Direct link to Key Lifecycle")

```text
active → retiring → expired

```

| Status     | Description                                                                                                                                                             |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `active`   | The current signing key. All new tokens are signed with this key. Appears in JWKS.                                                                                      |
| `retiring` | A previously active key after rotation. Still appears in JWKS until `retires_at`. Allegro accepts tokens signed by this key indefinitely (until the token's own `exp`). |
| `expired`  | No longer appears in JWKS. Allegro still accepts tokens signed by this key until the token's own `exp` (1-year TTL).                                                    |

Retiring keys stay in JWKS for 1 year (matching the JWT TTL) so that external consumers like AWS API Gateway can always verify any valid token.

#### Commands[​](#commands "Direct link to Commands")

##### Generate Initial Keys[​](#generate-initial-keys "Direct link to Generate Initial Keys")

Run once per tenant after provisioning (automatically called by `tenant:create`):

```bash
php artisan jwt:keys:generate --tenant=*

```

Idempotent — skips tenants that already have an active key. Omit `--tenant=*` to run for the current tenant context.

##### Rotate Keys[​](#rotate-keys "Direct link to Rotate Keys")

Generates a new active key and moves the current active key to `retiring`:

```bash
php artisan jwt:keys:rotate --tenant=*

```

All new tokens are signed with the new key immediately. Old tokens remain verifiable via JWKS for 1 year.

##### Prune Expired Keys[​](#prune-expired-keys "Direct link to Prune Expired Keys")

Marks retiring keys as `expired` once `retires_at` has passed. Runs daily via the scheduler — you should not need to run this manually:

```bash
php artisan jwt:keys:prune --tenant=*

```

Expired keys are **not deleted** — Allegro continues to accept tokens signed by them until the token's own `exp`. Only JWKS visibility is removed.

#### Scheduler[​](#scheduler "Direct link to Scheduler")

`jwt:keys:prune` is registered in the Laravel scheduler and runs daily automatically. No additional configuration is required.

#### Emergency Key Revocation[​](#emergency-key-revocation "Direct link to Emergency Key Revocation")

There is no automated revocation. If a private key is compromised:

1. Run `php artisan jwt:keys:rotate --tenant=<id>` to immediately stop signing new tokens with the compromised key. Existing tokens signed by the compromised key remain verifiable via JWKS until you complete step 3.
2. The compromised key enters `retiring` status and continues to appear in JWKS for up to 1 year (its `retires_at`). External consumers will still accept tokens signed by it during this window.
3. If immediate revocation is needed, manually update the compromised key's `status` to `expired` in the tenant database. This removes it from JWKS immediately. However, external consumers (e.g., AWS API Gateway) cache JWKS responses — typically for up to 1 hour — so tokens signed by the compromised key may continue to be accepted until those caches expire. Clear JWKS caches on your external consumers where possible.


---

### Custom Domain

By default, the Allegro SDK is loaded from a tenant subdomain:

```text
https://acme.allegrocdp.com/client.js

```

A custom domain lets you serve the SDK and its API endpoints from a domain you control — for example:

```text
https://cdn.acme.com/client.js

```

When a member's browser loads `client.js` from your domain, the SDK uses that same origin for all subsequent API requests. The custom domain and the subdomain are kept in sync: the subdomain always stays active and continues to serve your admin dashboard and all other platform traffic.

Hosting the platform

This page covers configuring a custom domain when you host Allegro yourself. If you are embedding the SDK on your site and just need to understand how a custom domain affects your integration, see [Custom Domain](/developer/administration/custom-domain.md) under Administration.

#### Domain Inventory[​](#domain-inventory "Direct link to Domain Inventory")

Domains are no longer typed directly into a tenant or property field. Instead, each tenant has an **inventory** of domains, managed from the Allegro Admin: open a tenant and go to its **Domains** tab.

Adding a domain there provisions it at your configured hosting provider — DNS records are created for it and a certificate is requested — but **assigns it to nothing**. A newly added domain does not yet serve any traffic. This separates "this domain is ready to use" from "this domain is in use," so a domain can be fully provisioned and verified ahead of a cutover with no window where it serves without HTTPS.

##### Assigning a Domain[​](#assigning-a-domain "Direct link to Assigning a Domain")

A domain in the inventory routes only once it is assigned, in one of two ways:

* **As the tenant's own domain.** From the Domains tab, choose **Set as tenant domain** on a domain's row. This is now the only way to set a tenant's domain — it must come from the tenant's own inventory rather than being typed in directly.
* **To a property.** From that property's own settings page, its Custom Domain field is a select populated from the tenant's inventory, offering only domains not already assigned elsewhere in the tenant.

An unassigned domain in the inventory does not route: a request against it returns a 404 until it is assigned as the tenant's domain or to a property.

A property's domain must stay in the inventory

If a property's assigned domain is ever removed from the tenant's inventory — for example, deleted from the Domains tab — that property's settings page can no longer be saved at all, not even for unrelated fields, until the domain is re-added to the inventory or the property's Custom Domain is cleared. This is enforced server-side, so it cannot be bypassed from a hand-crafted request either.

#### DNS Records[​](#dns-records "Direct link to DNS Records")

Provisioning a domain from the Domains tab produces at least two DNS records, shown in that domain's row (expand it to see them). Create both at your DNS provider:

1. **An origin record** (typically an `A` record) that points the domain's traffic at your hosting provider.
2. **An SSL validation record** (a `CNAME` at `_acme-challenge.<domain>`, under Let's Encrypt's DNS-01 verification) that the certificate authority uses to prove you control the domain.

Some hosting providers also require a third **ownership record** before the origin record takes effect. Copy the exact values from the Domains tab rather than guessing — they are specific to your provider and this provisioning.

The SSL validation CNAME is permanent

Unlike a one-time ownership check, the SSL validation CNAME is re-checked on every certificate renewal. Removing it after the domain goes live will not break the domain immediately, but the next renewal will fail and the domain will eventually serve without a valid certificate. Leave it in place for as long as the domain is in use.

#### Verification[​](#verification "Direct link to Verification")

After you create the DNS records, Allegro verifies the domain in the background — you do not have to trigger anything. Each domain's row on the Domains tab shows its progress across the checks that apply to your provider:

| Status           | Meaning                                                              |
| ---------------- | -------------------------------------------------------------------- |
| **Pending**      | The check has not passed yet — usually waiting for DNS to propagate. |
| **Verified**     | The check passed.                                                    |
| **Failed**       | The check could not be completed; the row shows the error returned.  |
| **Not required** | The check does not apply to this provider.                           |

Allegro re-checks a pending domain often at first and less frequently as time passes. A domain that stays unverified for more than a week is marked **stalled** — Allegro stops re-checking it, but nothing is lost: fix the DNS records and re-check the domain from its row to resume. The domain is considered ready once every applicable check has passed.

#### Hosting Provider Configuration[​](#hosting-provider-configuration "Direct link to Hosting Provider Configuration")

Provisioning requires a hosting provider to be configured:

```dotenv
ALLEGRO_HOSTING_PROVIDER=laravel-forge

```

Set it to a registered provider name (`laravel-forge` or `laravel-cloud`), then configure that provider package's own environment variables — see `packages/allegro-laravel-forge` or `packages/allegro-laravel-cloud`. Until `ALLEGRO_HOSTING_PROVIDER` and the provider's own variables are all set, the Domains tab renders a disabled state and existing inventory rows are shown but cannot be added to, verified, or assigned.

Existing domains still appear

A domain that was already set as a tenant's or property's domain before this inventory model existed is backfilled into the tenant's inventory automatically, so it appears on the Domains tab without any manual step. If your deployment has not yet configured a hosting provider, those backfilled domains still display, just without live provisioning until the provider is configured.

HTTPS only

Custom domains must be served over HTTPS. Allegro generates redirect and CORS URLs using `https://` unconditionally.

#### Request Routing[​](#request-routing "Direct link to Request Routing")

Not all paths are available on the custom domain. Allegro routes requests as follows:

| Path                   | Custom domain | Notes                                 |
| ---------------------- | ------------- | ------------------------------------- |
| `/client.js`           | Served        | SDK loader entry point                |
| `/assets/*`            | Served        | Compiled SDK bundles                  |
| `/api/*`               | Served        | All SDK API endpoints                 |
| `/third-party/*`       | Served        | Social login popups opened by the SDK |
| `/checkout/processing` | Served        | Post-checkout processing page         |
| `/.well-known/*`       | Served        | OIDC discovery and JWKS endpoints     |
| All other paths        | Redirected    | Permanent (301) redirect to subdomain |

Any request on the custom domain that does not match one of the served paths is permanently redirected to the equivalent path on the tenant's subdomain. This keeps the admin dashboard and authentication flows on the canonical subdomain regardless of which domain the SDK is loaded from.

Subdomain stays active

The subdomain (`acme.allegrocdp.com`) is never disabled. All operator traffic — the dashboard, login, settings — continues to work there. The custom domain is an additional entry point for audience-facing requests only.

#### CORS[​](#cors "Direct link to CORS")

When a custom domain is configured, Allegro automatically includes it in the list of allowed CORS origins alongside the subdomain. No additional configuration is needed.

If your deployment requires additional allowed origins (for example, a preview environment), add them to the `cors_allowed_origins` tenant setting.

The same allowed-origin list also governs return URLs. The `returnUrl` passed to [magic link](/developer/guides/authentication/magic-links.md) requests and the return URL passed to [checkout](/developer/guides/payment/purchases.md) must resolve to one of these origins, otherwise the request is rejected. This prevents sign-in and purchase tokens from being redirected to domains the tenant does not control.

#### How the SDK Uses the Custom Domain[​](#how-the-sdk-uses-the-custom-domain "Direct link to How the SDK Uses the Custom Domain")

The SDK determines its API base URL from the `src` attribute of the `<script>` tag that loads `client.js`. If you load the script from your custom domain, all API calls the SDK makes — authentication, event tracking, interactions, checkout — go to the custom domain automatically. No additional configuration in the SDK embed code is required.

```html
<!-- All SDK API requests go to cdn.acme.com -->
<script src="https://cdn.acme.com/client.js" data-tenant="acme"></script>

```

#### Local Development[​](#local-development "Direct link to Local Development")

By default, Allegro permanently redirects any request on the custom domain that does not match an allowed path to the equivalent path on the tenant's subdomain. This can interfere with local or staging setups where you need to access the admin dashboard through a custom domain.

Set `ALLEGRO_DISABLED_REDIRECT_CANONICAL=true` in your environment to disable this redirect entirely. When set, requests to non-SDK paths on the custom domain are served directly rather than being redirected to the subdomain. Allegro also automatically scopes the session cookie to the custom domain for that tenant so authentication works correctly.

warning

Do not set `ALLEGRO_DISABLED_REDIRECT_CANONICAL=true` in production. It disables a security boundary that prevents audience-facing custom-domain traffic from reaching the operator dashboard.

#### Related[​](#related "Direct link to Related")

* [Custom Domain (Administration)](/developer/administration/custom-domain.md) — How a custom domain affects your SDK integration
* [Script Tag](/developer/guides/script-tag.md) — Embedding the SDK on your site
* [Stripe Webhook Setup](/developer/platform/integrations/stripe-webhooks.md) — Configuring the Stripe webhook endpoint


---

### Feature Flags

Allegro has two kinds of feature flags:

* **Tenant flags** belong to a single tenant and are evaluated per organization.
* **Platform-wide (landlord) flags** are global. They live on the landlord rather than on any tenant, and read the same value everywhere — across every tenant, the Allegro Admin, queued jobs, and console commands.

This page covers the platform-wide flags. They are managed by a super admin and are kept completely separate from a tenant's own flags.

#### Managing platform-wide flags[​](#managing-platform-wide-flags "Direct link to Managing platform-wide flags")

From the Allegro Admin, open **Global Settings → Settings → Feature Flags**. The page lists every platform-wide flag with its description and a toggle. Switching a flag on or off applies immediately across the whole installation — there's no deploy or cache-clear step.

Only super admins can view or change platform-wide flags.

note

Platform-wide flags are stored on the landlord connection, in a `features` table separate from each tenant's flags. Turning a platform flag on or off has no effect on any tenant-level flag of the same name, and vice versa.

#### Defining a platform-wide flag[​](#defining-a-platform-wide-flag "Direct link to Defining a platform-wide flag")

Platform-wide flags are defined in code and then toggled from the settings page. To add one, create a class in the `Allegro\Features\Landlord` namespace (under `src/Features/Landlord/`) that exposes a `resolve()` method returning the flag's default value. Allegro discovers the class automatically and it appears on the **Feature Flags** page.

```php
namespace Allegro\Features\Landlord;

use Allegro\Features\Attributes\FeatureDescription;
use Allegro\Features\LandlordFeature;

#[FeatureDescription(
    'Enable the experimental analytics dashboard across every tenant.',
    label: 'Experimental analytics',
)]
class ExperimentalAnalytics
{
    public function resolve(mixed $scope = null): bool
    {
        return false;
    }

    public static function isActive(): bool
    {
        return LandlordFeature::active(self::class);
    }
}

```

The `#[FeatureDescription]` attribute supplies the label and description shown on the settings page. The `resolve()` method returns the value a flag starts with before anyone toggles it — return `false` for a flag that ships off by default.

Read the flag anywhere in the application with `LandlordFeature::active()`, or expose a small helper on the flag class (such as the `isActive()` method above) for readability:

```php
if (ExperimentalAnalytics::isActive()) {
    // …
}

```

Because the value is resolved against a single global scope, it reads the same whether you check it inside a tenant request, the Allegro Admin, a queued job, or a scheduled command.


---

### Tenants

A **tenant** is a single, isolated Allegro organization running on your instance. Each tenant has its own database, its own JWT signing keys, and its own audience, templates, and settings. The **Allegro Admin** is the control plane where super administrators manage every tenant on the instance.

Super administrators only

Creating and managing tenants is restricted to super administrators. Regular operators sign in to a single tenant and never see the Allegro Admin. Super admins can jump into any tenant — and back to the Allegro Dashboard — from the tenant switcher.

#### Creating a tenant[​](#creating-a-tenant "Direct link to Creating a tenant")

1. Open **Global Settings → Tenants**.

2. Click **New tenant**.

3. Fill in the dialog:

   | Field    | Rules                                                                                                                                |
   | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
   | **Name** | Required. Up to 255 characters. Letters, numbers, spaces, and dashes only — e.g. `Acme News`.                                        |
   | **Slug** | Required. 3–255 characters, URL-safe (letters, numbers, dashes, underscores). Must be unique across the instance — e.g. `acme-news`. |

   The slug is generated automatically from the name as you type, until you edit the slug field yourself. Whatever you enter is normalized to a URL-safe value before it is saved, so a name like `Acme News` becomes the slug `acme-news`.

4. Click **Create**. Allegro provisions the tenant and takes you to its detail page.

#### What provisioning does[​](#what-provisioning-does "Direct link to What provisioning does")

Tenant creation is synchronous — by the time you land on the new tenant's page, it is ready to use. Provisioning:

* **Creates and migrates the tenant's database**, giving it an isolated schema separate from every other tenant.
* **Generates the tenant's initial JWT signing key** — an RS256 (RSA-2048) key pair used to sign member session tokens. The public half is served from the tenant's [JWKS endpoint](/developer/guides/jwt.md) so you can verify those tokens in your own infrastructure.
* **Loads the compiled `client.js` asset** into the tenant so the browser SDK is immediately available.

Loading the client asset is best-effort: if the compiled asset isn't available when the tenant is created, provisioning still succeeds and the asset is loaded on the next build or asset refresh.

Give the tenant a domain

A new tenant is reachable at its subdomain (for example `acme-news.allegrocdp.com`). To serve the SDK from a domain you control, follow the [Custom Domain](/developer/platform/setup/custom-domain.md) guide.


---

### SDK Reference

The Allegro SDK is a browser JavaScript library that loads via a `<script>` tag and exposes its API on `window.allegro`. It handles event tracking, member authentication, and on-page interactions.

#### Quick Example[​](#quick-example "Direct link to Quick Example")

```html
<script>
    window.allegro = window.allegro || [];

    window.allegro.push(function (allegro) {
        // Track an event
        allegro.track('article_read', {
            content_id: '123',
            content_type: 'article',
        });

        // Check if the current visitor is authenticated
        if (allegro.member.isAuthenticated()) {
            const payload = allegro.member.sessionFromJwt();
            console.log('Hello,', payload.audience_member.name);
        }
    });
</script>

<script src="https://your-allegro-instance.com/client.js"></script>

```

`window.allegro.push()` queues callbacks that run as soon as the SDK is ready. If the SDK has already loaded by the time `push()` is called, the callback runs immediately.

#### Namespaces[​](#namespaces "Direct link to Namespaces")

| Namespace                                                                                    | Description                                                    |
| -------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| [`allegro.track()`](/developer/api-reference/interfaces/AllegroSDK.md)                       | Track named events with automatic page context collection      |
| [`allegro.member`](/developer/api-reference/interfaces/MemberNamespace.md)                   | Authenticate and identify audience members                     |
| [`allegro.interaction`](/developer/api-reference/interfaces/InteractionNamespace.md)         | Trigger and manage on-page interactions                        |
| `allegro.forms`                                                                              | Fetch and submit admin-composed forms of user attributes       |
| [`allegro.recommendations`](/developer/api-reference/interfaces/RecommendationsNamespace.md) | Fetch ranked article recommendations and report clicks on them |


---

### Webhook Events Reference

This page lists every event you can subscribe to, grouped by the entity that changed, with an example delivery for each payload shape.

For the delivery envelope format, property scoping, and signature verification, see [Webhooks Overview](/developer/webhooks/overview.md).

#### Payload Shape[​](#payload-shape "Direct link to Payload Shape")

The envelope is the same for every event. Only `data` changes:

```json
{
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "event": "audience_member.created",
    "created_at": "2026-08-12T14:32:00+00:00",
    "property": "magazine",
    "data": { ... }
}

```

For every event except [`ping`](#system), `data` is a single JSON:API resource object:

| Key          | Description                                                                                   |
| ------------ | --------------------------------------------------------------------------------------------- |
| `id`         | The record's identifier.                                                                      |
| `type`       | The resource type, fixed per event group (for example `audience_members`).                    |
| `attributes` | The record's fields. This is the part that differs between the shapes documented below.       |
| `meta`       | Present only where noted below. Carries information about the record rather than its content. |

Events that share a shape share an example. All twenty-three subscribable events resolve to one of eight shapes, plus `ping`.

Two timestamp formats appear in payloads

The envelope's `created_at`, and any field the platform explicitly formats (entitlement `started_at` and `ended_at`, and the ping's `created_at`), use an offset — `2026-08-12T14:32:00+00:00`. Record timestamps inside `attributes` use the microsecond form — `2026-08-12T14:32:00.000000Z`. Both are UTC and both parse as ISO 8601; parse them, don't string-compare them.

Treat unrecognized keys as optional

Payloads are additive. A future release can add attributes, and `data` may carry extra top-level keys such as `relationships` depending on how the record was loaded when the event fired. Read the keys you need and ignore the rest.

#### Audience Member[​](#audience-member "Direct link to Audience Member")

These events fire when an audience member record is created, updated, or deleted, and when a member joins a property.

| Event                             | Trigger                                                                    |
| --------------------------------- | -------------------------------------------------------------------------- |
| `audience_member.created`         | Fired when a new audience member is created.                               |
| `audience_member.updated`         | Fired when an audience member is updated (excludes activity-only changes). |
| `audience_member.deleted`         | Fired when an audience member is deleted.                                  |
| `audience_member.property.joined` | Fired the first time an audience member signs in on a property.            |

note

`audience_member.updated` is **not** fired for activity-only changes such as `last_active_at` updates. It fires only when meaningful profile data changes.

`meta` inside `attributes` holds the member's raw meta values, keyed by meta key and sorted alphabetically. Every value is a string, including numbers and booleans. For the tenant-defined subset of these values, subscribe to the [user attribute](#user-attribute) events instead.

`properties` lists every property the member has joined, with when they first signed in on it and whether that sign-in created their account. For `audience_member.property.joined`, the joined property is also the envelope's `property`.

```json
{
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "event": "audience_member.created",
    "created_at": "2026-08-12T14:32:00+00:00",
    "property": "magazine",
    "data": {
        "id": "9d5c1f2a-8b3e-4a17-9f6d-2c4b8e1a7d30",
        "type": "audience_members",
        "attributes": {
            "name": "Jane Doe",
            "email": "jane@example.com",
            "email_verified": true,
            "meta": {
                "newsletter_opt_in": "1",
                "postal_code": "90210"
            },
            "properties": [
                {
                    "id": "3b2e9c4d-1f7a-4e8b-9c6d-5a4f3e2d1c0b",
                    "slug": "magazine",
                    "name": "Magazine",
                    "joined_at": "2026-08-12T14:32:00+00:00",
                    "signed_up": true
                }
            ],
            "created_at": "2026-08-12T14:32:00.000000Z",
            "updated_at": "2026-08-12T14:32:00.000000Z"
        }
    }
}

```

#### External Profile[​](#external-profile "Direct link to External Profile")

External profiles store data from third-party providers (such as a CRM or identity provider) attached to a member.

| Event                                      | Trigger                                              |
| ------------------------------------------ | ---------------------------------------------------- |
| `audience_member.external_profile.created` | Fired when an external profile is added to a member. |
| `audience_member.external_profile.updated` | Fired when an external profile is updated.           |
| `audience_member.external_profile.deleted` | Fired when an external profile is removed.           |

`attributes` is the provider's stored payload verbatim, so its keys are whatever that provider supplies — the example below is illustrative, not a schema. Record timestamps are under `meta` rather than `attributes`, because `attributes` is entirely provider-controlled.

For the same reason, neither the member nor the provider name is in the payload: `data.id` identifies the profile row, so key your records on it. If you need the member, subscribe to the [user attribute](#user-attribute) events as well — any user attribute configured to read from this provider is re-synced when the profile changes, and those events do carry `audience_member_id`.

```json
{
    "id": "b9f1c7d2-4a8e-4b03-9c15-6d2e8f3a1b47",
    "event": "audience_member.external_profile.updated",
    "created_at": "2026-08-12T14:35:12+00:00",
    "property": "magazine",
    "data": {
        "id": "3f1b9c04-6d2e-4c8a-b5f7-1a9e3d7c2b48",
        "type": "audience_member_external_profiles",
        "attributes": {
            "contact_id": "C-0031982",
            "membership_level": "sustainer",
            "lifetime_giving": 240,
            "tags": ["donor", "event-attendee"]
        },
        "meta": {
            "created_at": "2026-07-02T09:14:05.000000Z",
            "updated_at": "2026-08-12T14:35:12.000000Z"
        }
    }
}

```

#### Foreign Key[​](#foreign-key "Direct link to Foreign Key")

Foreign keys link an audience member to an identifier in an external system (for example, a CRM contact ID or a subscriber ID in your publishing platform).

| Event                                 | Trigger                                           |
| ------------------------------------- | ------------------------------------------------- |
| `audience_member.foreign_key.created` | Fired when a foreign key is attached to a member. |
| `audience_member.foreign_key.updated` | Fired when a foreign key is updated.              |
| `audience_member.foreign_key.deleted` | Fired when a foreign key is removed.              |

The payload carries the `key` and `value` pair but not the member it belongs to, so key your records on `data.id`.

```json
{
    "id": "c1d4e8a2-7b39-4f65-8a02-3e9c5b1d7f84",
    "event": "audience_member.foreign_key.created",
    "created_at": "2026-08-12T14:36:40+00:00",
    "property": "magazine",
    "data": {
        "id": "7e2a5c81-9d34-4b6f-a017-8c3e2f9b5d60",
        "type": "audience_member_foreign_keys",
        "attributes": {
            "key": "contact_id",
            "value": "C-0031982",
            "created_at": "2026-08-12T14:36:40.000000Z",
            "updated_at": "2026-08-12T14:36:40.000000Z"
        }
    }
}

```

#### User Attribute[​](#user-attribute "Direct link to User Attribute")

User attributes are the tenant-defined profile fields configured in the admin. These events fire only for keys defined in the tenant's user attribute registry — internal and unmapped member meta keys are ignored.

| Event                                    | Trigger                                                                  |
| ---------------------------------------- | ------------------------------------------------------------------------ |
| `audience_member.user_attribute.created` | Fired when a user attribute value is set on a member for the first time. |
| `audience_member.user_attribute.updated` | Fired when a user attribute value changes.                               |
| `audience_member.user_attribute.deleted` | Fired when a user attribute value is removed from a member.              |

`slug` is the attribute's slug from the registry, and `value` is always a string regardless of the attribute's configured type. Unlike every other shape on this page, `id` is a numeric string rather than a UUID — it identifies the stored value, not the attribute definition, so key your own records on `audience_member_id` plus `slug`.

```json
{
    "id": "a48f2d19-6c05-4e73-b8d1-9f27a3e5c064",
    "event": "audience_member.user_attribute.updated",
    "created_at": "2026-08-12T14:38:02+00:00",
    "property": "magazine",
    "data": {
        "id": "1842",
        "type": "audience_member_user_attributes",
        "attributes": {
            "audience_member_id": "9d5c1f2a-8b3e-4a17-9f6d-2c4b8e1a7d30",
            "slug": "newsletter_opt_in",
            "value": "1"
        }
    }
}

```

#### Entitlement[​](#entitlement "Direct link to Entitlement")

Entitlement events fire when a member's access to a product changes.

| Event                 | Trigger                               |
| --------------------- | ------------------------------------- |
| `entitlement.created` | Fired when an entitlement is granted. |
| `entitlement.updated` | Fired when an entitlement is updated. |
| `entitlement.deleted` | Fired when an entitlement is deleted. |

`is_active` is computed from `started_at` and `ended_at` at the moment the event fired: an entitlement is active once `started_at` has passed and until `ended_at` does. A `null` `ended_at` means indefinite access. Revoking an entitlement sets `ended_at` and fires `entitlement.updated`, not `entitlement.deleted`.

The entitlement's `id` is repeated inside `attributes` as well as at the top of `data`. `audience_member_id` names the member whose access changed, and `product` carries the product it grants — `id`, `name`, and `slug` — so a delivery can be routed without a follow-up API call. That matters most for `entitlement.deleted`, which names a row that no longer exists to read back.

```json
{
    "id": "d7c93b15-2e48-4a06-91f5-7b3c8d2e6a19",
    "event": "entitlement.created",
    "created_at": "2026-08-12T14:40:18+00:00",
    "property": "magazine",
    "data": {
        "id": "c8e40a72-5d16-4f39-8b2c-1e7a9d4f3b05",
        "type": "entitlements",
        "attributes": {
            "id": "c8e40a72-5d16-4f39-8b2c-1e7a9d4f3b05",
            "audience_member_id": "9d5c1f2a-8b3e-4a17-9f6d-2c4b8e1a7d30",
            "product": {
                "id": "3f8b2c91-7d64-4e05-a1b8-5c2f9e4d7a63",
                "name": "Magazine Digital",
                "slug": "magazine-digital"
            },
            "started_at": "2026-08-12T00:00:00+00:00",
            "ended_at": null,
            "note": "Granted by support",
            "is_active": true,
            "created_at": "2026-08-12T14:40:18.000000Z",
            "updated_at": "2026-08-12T14:40:18.000000Z"
        }
    }
}

```

#### Purchase[​](#purchase "Direct link to Purchase")

Purchase events fire when a member's purchase is created or changes (for example, a refund). Purchases are not hard-deleted, so there is no `purchase.deleted` event.

| Event              | Trigger                                                   |
| ------------------ | --------------------------------------------------------- |
| `purchase.created` | Fired when a purchase is created.                         |
| `purchase.updated` | Fired when a purchase is updated (for example, refunded). |

`status` is one of `pending`, `completed`, `failed`, or `refunded`. `amount` is an integer in the currency's smallest unit — `999` with a `currency` of `usd` means $9.99. The `provider_*` fields are the payment provider's own identifiers.

A purchase is created as `pending`, and an anonymous checkout is created with a `null` `audience_member_id` and `entitlement_id`; both are filled in when the payment is fulfilled. Expect every `purchase.created` to be followed by a `purchase.updated` that carries the settled record.

```json
{
    "id": "e2a6f483-9c71-4d50-b8e3-4f1a7c9d2b60",
    "event": "purchase.updated",
    "created_at": "2026-08-12T14:42:55+00:00",
    "property": "magazine",
    "data": {
        "id": "7a1e5b39-4c82-4067-9d1f-3b8e2a6c5d40",
        "type": "purchase_webhooks",
        "attributes": {
            "id": "7a1e5b39-4c82-4067-9d1f-3b8e2a6c5d40",
            "audience_member_id": "9d5c1f2a-8b3e-4a17-9f6d-2c4b8e1a7d30",
            "device_session_id": "5b2f8c14-7a63-4e09-8d25-1f9c3b7a2e58",
            "plan_id": "e91d4a07-3b56-4c82-9f14-6d2e8a5c1b73",
            "entitlement_id": "c8e40a72-5d16-4f39-8b2c-1e7a9d4f3b05",
            "provider": "stripe",
            "provider_session_id": "cs_test_a1b2c3d4e5f6",
            "provider_payment_id": "pi_3Q1a2b3c4d5e6f7g",
            "provider_refund_id": null,
            "status": "completed",
            "amount": 999,
            "currency": "usd",
            "metadata": null,
            "return_url": "https://acme.com/thank-you",
            "created_at": "2026-08-12T14:41:03.000000Z",
            "updated_at": "2026-08-12T14:42:55.000000Z"
        }
    }
}

```

#### Interaction[​](#interaction "Direct link to Interaction")

Interaction events fire when an interaction is created, updated, or deleted.

| Event                 | Trigger                               |
| --------------------- | ------------------------------------- |
| `interaction.created` | Fired when an interaction is created. |
| `interaction.updated` | Fired when an interaction is updated. |
| `interaction.deleted` | Fired when an interaction is deleted. |

`status` is `draft` or `published`. `trigger_mode` is `manual` or `automatic`. `actions` is the interaction's ordered action list — in automatic mode, the actions of the **Everyone else** default journey; every entry has a `type`, and the remaining keys depend on it. `journeys` is the ordered list of targeting journeys (`null` for interactions that never had any), each with its `id`, `name`, `condition_groups`, and `actions`. Interactions are soft-deleted, so `interaction.deleted` carries the record with `deleted_at` set rather than omitting it.

```json
{
    "id": "f5b81e27-6a94-4c13-8d70-2e9f4a1c6b38",
    "event": "interaction.updated",
    "created_at": "2026-08-12T14:45:20+00:00",
    "property": null,
    "data": {
        "id": "2c9e7f14-8b05-4a63-91d8-5f3a2e7c4b19",
        "type": "interaction_webhooks",
        "attributes": {
            "id": "2c9e7f14-8b05-4a63-91d8-5f3a2e7c4b19",
            "title": "Sustainer Upsell",
            "slug": "sustainer-upsell",
            "status": "published",
            "trigger_mode": "manual",
            "journeys": null,
            "actions": [
                {
                    "type": "template",
                    "template_id": "8d1f4a92-3c67-4b05-a2e8-7f9c1d5b3a26",
                    "target_selector": "#article-body",
                    "field_values": [
                        {
                            "slug": "headline",
                            "value": "Support independent reporting"
                        }
                    ],
                    "placement_method": "before",
                    "truncation_unit": null,
                    "truncation_count": null,
                    "truncation_style": null,
                    "delay_type": null,
                    "delay_value": null,
                    "delay_scroll_unit": null,
                    "delay_scroll_selector": null
                }
            ],
            "created_at": "2026-08-01T10:02:44.000000Z",
            "updated_at": "2026-08-12T14:45:20.000000Z",
            "deleted_at": null
        }
    }
}

```

#### Template[​](#template "Direct link to Template")

Template events fire when a template is created, updated, or deleted.

| Event              | Trigger                           |
| ------------------ | --------------------------------- |
| `template.created` | Fired when a template is created. |
| `template.updated` | Fired when a template is updated. |
| `template.deleted` | Fired when a template is deleted. |

The payload includes the template's full `html`, `js`, and `css` bodies, so template deliveries are the largest ones Allegro sends. `fields` describes the template's field definitions, and the `sync_source` and `github_*` fields are populated only for templates kept in sync with a Git repository. Templates are soft-deleted, so `template.deleted` carries the record with `deleted_at` set.

```json
{
    "id": "0a3d9c76-4e18-4b52-8f01-6c7a2e9d5b34",
    "event": "template.updated",
    "created_at": "2026-08-12T14:48:07+00:00",
    "property": null,
    "data": {
        "id": "8d1f4a92-3c67-4b05-a2e8-7f9c1d5b3a26",
        "type": "template_webhooks",
        "attributes": {
            "id": "8d1f4a92-3c67-4b05-a2e8-7f9c1d5b3a26",
            "title": "Sustainer Banner",
            "slug": "sustainer-banner",
            "status": "published",
            "html": "<div class=\"banner\"><h2>{{ headline }}</h2></div>",
            "js": "",
            "css": ".banner { padding: 1rem; }",
            "fields": [
                {
                    "slug": "headline",
                    "description": "Banner headline",
                    "type": "text"
                }
            ],
            "external_css_urls": [],
            "created_at": "2026-07-28T16:20:11.000000Z",
            "updated_at": "2026-08-12T14:48:07.000000Z",
            "deleted_at": null,
            "sync_source": "github",
            "github_path": "templates/sustainer-banner.html",
            "github_sha": "9f2c1d7e8a3b4c5d6e7f8091a2b3c4d5e6f70819",
            "github_commit_sha": "1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d",
            "synced_at": "2026-08-12T14:48:07.000000Z"
        }
    }
}

```

#### System[​](#system "Direct link to System")

| Event  | Trigger                                                                                           |
| ------ | ------------------------------------------------------------------------------------------------- |
| `ping` | A test event sent when an active webhook is created, or on demand from the webhook's detail page. |

`ping` is not subscribable — it is sent automatically, or on demand from the dashboard, and cannot be selected when configuring event subscriptions.

The ping is the one delivery whose `data` is **not** a JSON:API resource object. It echoes the webhook's own `id`, subscribed `events`, and `created_at`. Pings ignore property scoping and, because webhooks are created from the organization dashboard, normally carry `property: null`.

```json
{
    "id": "6d0f8a13-2b47-4e95-8c26-1a3f7d9b5e02",
    "event": "ping",
    "created_at": "2026-08-12T14:30:00+00:00",
    "property": null,
    "data": {
        "id": "4b7e1c29-8d53-4a06-9f18-2e6c5b3a7d94",
        "events": ["audience_member.created", "entitlement.created"],
        "created_at": "2026-08-12T14:29:58+00:00"
    }
}

```

#### Adding New Events[​](#adding-new-events "Direct link to Adding New Events")

The subscribable event list is generated from the event registry in the platform. New event types registered there become immediately available in the webhook subscription UI and in this reference.

#### Related[​](#related "Direct link to Related")

* [Webhooks Overview](/developer/webhooks/overview.md) — creating webhooks, property scoping, delivery envelope, signature verification, and retries
* [Properties](/developer/guides/properties.md) — property hosts and the request context that populates the envelope's `property` field
* [Entitlements](/product/entitlements.md) — how entitlements and products work
* [Audience Members](/product/audience.md) — member profiles and data


---

### Webhooks

Webhooks let your systems react to events in Allegro in real time. When something happens — a new audience member joins, an entitlement is granted, a foreign key is attached — Allegro sends an HTTP `POST` request to a URL you control. You don't need to poll the API; Allegro pushes changes to you.

#### Creating a Webhook[​](#creating-a-webhook "Direct link to Creating a Webhook")

1. Go to **Organization Settings → Developer → Webhooks**.
2. Click **Add Webhook**.
3. Enter the **Endpoint URL** — the HTTPS URL on your server that will receive deliveries.
4. Enter a **Description** to help you identify the webhook later.
5. Choose which **Events** to subscribe to. You can subscribe to individual events or to all events.
6. Optionally choose which **Properties** the webhook is scoped to, and whether to include **Organization** events that have no property. Leave everything unchecked to receive events from the whole organization — see [Property Scoping](#property-scoping).
7. Click **Create**. Allegro immediately sends a [ping event](#ping) to your endpoint to confirm it is reachable.

Endpoint URLs must be publicly reachable

The endpoint must be a public `https://` URL. Allegro rejects URLs whose host resolves to a private, loopback, link-local, or otherwise reserved address — including cloud metadata endpoints such as `169.254.169.254`. This is checked both when you save the webhook and again before every delivery. Allegro also does not follow redirects, so the URL you register is the exact URL that receives each `POST`.

note

Each organization can have up to **5 webhooks**. If you need more, delete an existing one first.

##### Activating and Deactivating[​](#activating-and-deactivating "Direct link to Activating and Deactivating")

Every webhook has an **Active** toggle. Deactivating a webhook suspends deliveries without deleting the webhook or its delivery history. Reactivate it at any time to resume.

#### Property Scoping[​](#property-scoping "Direct link to Property Scoping")

If your organization uses [properties](/developer/guides/properties.md), you can limit a webhook to a subset of them. Open the webhook's **Properties** section (**Organization Settings → Developer → Webhooks → your webhook**) and check the properties whose events you want.

Leaving **everything unchecked means organization-wide** — the webhook receives every matching event, with or without a property. That is the default, and it is how all existing webhooks behave, so adding properties to your organization never changes an existing webhook's deliveries.

Every delivery reports the property it came from in the envelope's `property` field, so an organization-wide webhook can still tell properties apart without being scoped to any of them.

##### Events Without a Property[​](#events-without-a-property "Direct link to Events Without a Property")

The originating property comes from the **request context the event fired in**, not from the record itself. Audience members, entitlements, purchases, interactions, and templates belong to the organization, not to a property — so an event fired outside a property host has `property: null`.

Events with no property include:

* Changes made in the Allegro dashboard.
* API requests made against the organization host rather than a [property host](/developer/guides/properties.md), which includes most API key traffic.
* Console commands, bulk imports, and queued background work.

Check **Organization** in the webhook's **Properties** section to receive these events:

| Properties checked | Organization checked | The webhook receives                                             |
| ------------------ | -------------------- | ---------------------------------------------------------------- |
| None               | No                   | Every event (organization-wide)                                  |
| None               | Yes                  | Only events with no property                                     |
| Some               | No                   | Only events from the checked properties                          |
| Some               | Yes                  | Events from the checked properties, plus events with no property |

A scoped webhook skips events with no property unless Organization is checked

A webhook scoped to one or more properties does not receive dashboard changes, organization-host API traffic, or background work unless **Organization** is also checked.

#### Delivery Payload[​](#delivery-payload "Direct link to Delivery Payload")

Every delivery is an HTTP `POST` with a JSON body in the following envelope format:

```json
{
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "event": "audience_member.created",
    "created_at": "2026-08-12T14:32:00+00:00",
    "property": "magazine",
    "data": { ... }
}

```

| Field        | Type           | Description                                                                                                                                                                   |
| ------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`         | string         | Unique identifier for the event (UUID). Matches the `X-Allegro-Event-Id` header.                                                                                              |
| `event`      | string         | The event type (e.g. `audience_member.created`).                                                                                                                              |
| `created_at` | string         | ISO 8601 timestamp of when the event occurred.                                                                                                                                |
| `property`   | string | null | Slug of the [property](/developer/guides/properties.md) the event fired on. `null` when the event fired without property context — see [Property Scoping](#property-scoping). |
| `data`       | object         | The resource representation of the entity that changed. Shape varies by event — see [Events Reference](/developer/webhooks/events.md).                                        |

note

`property` is additive

The `property` field was added to every envelope, including on webhooks that are not scoped to any property. Existing consumers keep parsing deliveries unchanged.

##### Request Headers[​](#request-headers "Direct link to Request Headers")

Every delivery includes the following HTTP headers:

| Header                    | Description                                                                                                 |
| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `Content-Type`            | `application/json`                                                                                          |
| `User-Agent`              | `Allegro-Webhooks`                                                                                          |
| `X-Allegro-Event`         | The event type (e.g. `audience_member.created`).                                                            |
| `X-Allegro-Event-Id`      | The UUID of the event that triggered this delivery.                                                         |
| `X-Allegro-Delivery`      | Identifier for the delivery record. Stays the same across retries and manual redeliveries of that delivery. |
| `X-Allegro-Attempt`       | Which attempt this request is, starting at `1`. Increments on every automatic retry and manual redelivery.  |
| `X-Allegro-Signature-256` | An HMAC-SHA256 signature of the request body (see below).                                                   |

#### Signature Verification[​](#signature-verification "Direct link to Signature Verification")

Allegro signs every delivery using HMAC-SHA256. The signature is sent in the `X-Allegro-Signature-256` header in the format `sha256=<hex-digest>`.

The signature is computed over the **raw request body** using your webhook's **signing secret** as the key.

Always verify signatures

Verify the signature before processing any webhook payload. Without verification, your endpoint could accept forged requests from anyone on the internet.

##### Finding Your Signing Secret[​](#finding-your-signing-secret "Direct link to Finding Your Signing Secret")

Open the webhook detail page (**Organization Settings → Developer → Webhooks → your webhook**). The signing secret is displayed there. Treat it like a password — do not commit it to source control.

##### PHP Example[​](#php-example "Direct link to PHP Example")

```php
function verifyAllegroSignature(string $rawBody, string $secret, ?string $signatureHeader): bool
{
    // Header format: "sha256=<hex-digest>". Reject a missing or malformed header.
    if ($signatureHeader === null || !str_starts_with($signatureHeader, 'sha256=')) {
        return false;
    }

    $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);

    return hash_equals($expected, $signatureHeader);
}

// Usage (e.g. in a Laravel controller):
$rawBody = $request->getContent();
$signature = $request->header('X-Allegro-Signature-256');

if (!verifyAllegroSignature($rawBody, config('services.allegro.webhook_secret'), $signature)) {
    abort(401, 'Invalid signature');
}

```

##### Node.js Example[​](#nodejs-example "Direct link to Node.js Example")

```js
import { createHmac, timingSafeEqual } from 'node:crypto';

function verifyAllegroSignature(rawBody, secret, signatureHeader) {
    if (!signatureHeader?.startsWith('sha256=')) return false;

    const expected =
        'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
    const actual = Buffer.from(signatureHeader);
    const expectedBuf = Buffer.from(expected);

    if (actual.length !== expectedBuf.length) return false;
    return timingSafeEqual(actual, expectedBuf);
}

// Usage (e.g. in an Express handler):
const rawBody = req.rawBody; // requires bodyParser with verify option
const signature = req.headers['x-allegro-signature-256'];

if (
    !verifyAllegroSignature(
        rawBody,
        process.env.ALLEGRO_WEBHOOK_SECRET,
        signature,
    )
) {
    return res.status(401).send('Invalid signature');
}

```

note

Use a **constant-time comparison** (`hash_equals` in PHP, `timingSafeEqual` in Node.js) to prevent timing attacks.

#### Retries[​](#retries "Direct link to Retries")

When a delivery fails — your endpoint returns a non-2xx status code or does not respond within 10 seconds — Allegro retries automatically:

| Attempt | Delay after previous attempt |
| ------- | ---------------------------- |
| Initial | Immediate                    |
| Retry 1 | 60 seconds                   |
| Retry 2 | 300 seconds (5 minutes)      |

After **3 total attempts** (the initial delivery plus 2 retries), the delivery is marked **Failed** and no further retries occur. The webhook itself remains active and continues to receive future events.

Every attempt is recorded individually. Each one keeps its own response status, response headers, response body, duration, and failure reason, so a delivery that failed twice before succeeding still shows both failures rather than only its final outcome. The full attempt history for a delivery is visible in the dashboard under the webhook's deliveries list.

Use `X-Allegro-Attempt` to tell a retry from a new event. `X-Allegro-Delivery` stays constant for every attempt of the same delivery, so it remains the right header to key idempotency on.

tip

Respond to deliveries as quickly as possible. If processing takes time, accept the delivery immediately (return `200 OK`) and handle it in a background job.

#### Viewing and Managing Deliveries[​](#viewing-and-managing-deliveries "Direct link to Viewing and Managing Deliveries")

Open a webhook from **Organization Settings → Developer → Webhooks** to see its recent deliveries. Deliveries are kept for **180 days**.

At the top of the page, a summary shows the **Deliveries**, **Success rate**, and **Failed** counts across every retained delivery — the full 180-day window, not only the sample listed below. Each delivery is counted once, by the outcome of its latest attempt, so a delivery that failed and then succeeded on redelivery counts as a success. The list underneath shows the most recent deliveries; when there are more than it displays, its header notes how many of the total are shown.

Each delivery record shows:

* The event type and delivery timestamp
* The property the event fired on, when it had one
* HTTP response status returned by your endpoint
* The full request payload and response body

The property shown on a delivery is read back out of the delivered payload, so it always matches what your endpoint received. Deliveries cannot be filtered by property.

##### Redelivery[​](#redelivery "Direct link to Redelivery")

You can manually redeliver any past delivery from the delivery detail view. This is useful for replaying events after you fix a bug in your endpoint or if your server was temporarily unavailable.

##### Ping[​](#ping "Direct link to Ping")

When you create an active webhook, Allegro sends a `ping` event to your endpoint to verify that it is reachable. The ping's `data` payload echoes the webhook's `id`, subscribed `events`, and `created_at` timestamp. Webhooks created inactive are not pinged.

You can also send a ping at any time from the webhook's detail page with **Send ping**, which is the quickest way to test an endpoint after you change it. The button is disabled while the webhook is inactive, and pings are limited to three per webhook per minute.

Pings ignore [property scoping](#property-scoping) — a property-scoped webhook is still pinged, so you can confirm the endpoint is reachable before any real event arrives. Because webhooks are created from the organization dashboard, a ping normally carries `property: null`.

#### Related[​](#related "Direct link to Related")

* [Events Reference](/developer/webhooks/events.md) — full list of subscribable events and their payload shapes
* [Settings](/product/administration/settings.md) — how to access Organization Settings


---

## Getting Started

### Allegro Audience

Allegro Audience is an open source, API-driven audience engagement platform. It gives publishers the tools to understand their readers, authenticate them without passwords, and deliver personalized content — all from infrastructure they control.

#### What Allegro Audience does[​](#what-allegro-audience-does "Direct link to What Allegro Audience does")

At its core, Allegro connects three things: **who your readers are**, **what they do**, and **what you show them**.

##### Track audience behavior[​](#track-audience-behavior "Direct link to Track audience behavior")

Allegro captures what readers do on your site — page views, article reads, clicks, conversions — and builds a profile of each person over time. You see it all in the Audience and Analytics sections of the admin.

##### Authenticate readers[​](#authenticate-readers "Direct link to Authenticate readers")

Readers sign in via magic link or social login (Google, Apple) — no passwords. Once signed in, Allegro knows who they are and what they have access to, so you can tailor what each member sees.

##### Deliver dynamic content[​](#deliver-dynamic-content "Direct link to Deliver dynamic content")

Templates let you build interactive components in HTML, CSS, and JavaScript — subscription banners, paywalls, email capture forms — and deploy them as Interactions on your site without a code release.

***

#### Two ways to work with Allegro Audience[​](#two-ways-to-work-with-allegro-audience "Direct link to Two ways to work with Allegro Audience")

| If you are...                                               | Start here                  |
| ----------------------------------------------------------- | --------------------------- |
| **An operator** setting up and managing an Allegro instance | You are in the right place! |
| **A developer** embedding Allegro on an external site       | [SDK docs →](/developer.md) |

***

#### What you can do in Allegro[​](#what-you-can-do-in-allegro "Direct link to What you can do in Allegro")

The Allegro admin is organized around a handful of areas. Here's what each one lets you do.

##### Understand your audience[​](#understand-your-audience "Direct link to Understand your audience")

* **[Dashboard](/product/dashboard.md)** — Your home screen. See audience growth and key metrics at a glance the moment you sign in.
* **[Analytics](/product/analytics.md)** — Dig deeper into how members engage with your content and membership programs over time.
* **[Members](/product/audience.md)** — Your contact database. Browse, search, and manage everyone who has signed up or been identified on your site.

##### Sign your readers in[​](#sign-your-readers-in "Direct link to Sign your readers in")

* **[Authentication](/product/audience/authentication.md)** — Let readers sign in with a magic link or social login (Google, Apple) — no passwords to manage.

##### Sell access and manage entitlements[​](#sell-access-and-manage-entitlements "Direct link to Sell access and manage entitlements")

* **[Entitlements](/product/entitlements.md)** — Control what your audience can access: digital subscriptions, gated content, event access, and more.
* **[Offers and Plans](/product/entitlements/offers.md)** — Package what you sell and set pricing for one-time purchases or recurring plans.
* **[Purchases](/product/entitlements/purchases.md)** — Review what members have bought and the access each purchase grants.

##### Build on-site experiences[​](#build-on-site-experiences "Direct link to Build on-site experiences")

* **[Interactions](/product/interactions.md)** — Deploy experiences to your site — paywalls, subscription banners, email capture forms — and trigger them by name, no code release required.
* **[Templates](/product/interactions/templates.md)** — Design the reusable building blocks that Interactions display, and publish them when they're ready.

##### Reach members over email[​](#reach-members-over-email "Direct link to Reach members over email")

* **[Email Templates](/product/email-templates.md)** — Create and manage the emails Allegro sends to your members.

##### Manage your team[​](#manage-your-team "Direct link to Manage your team")

* **[Users & Permissions](/product/administration/users.md)** — Invite teammates, assign roles, and control who can do what inside your organization.

***

#### Where to start[​](#where-to-start "Direct link to Where to start")

New to Allegro? This path walks you through the admin in the order most teams set things up:

1. **[Invite your team](/product/administration/users.md)** so the right people have access.
2. **[Turn on authentication](/product/audience/authentication.md)** so readers can sign in.
3. **[Build your first Interaction](/product/interactions.md)** — start with a [Template](/product/interactions/templates.md), then deploy it to your site.
4. **[Set up entitlements](/product/entitlements.md)** if you sell subscriptions or gate content.
5. **[Watch your Dashboard](/product/dashboard.md)** to see members and engagement grow.

Embedding Allegro on your site

Connecting Allegro to your website — installing the SDK, adding web components, and tracking events — is a developer task. Hand your developers the [SDK documentation](/developer.md) to get the integration in place.

***

#### Open source[​](#open-source "Direct link to Open source")

Allegro Audience is developed by [Alley Interactive](https://alley.com) and will be open sourced on GitHub. The platform is built on Laravel and designed to be self-hosted.


---

## Product

### Activity Log

The Activity Log is a running record of the meaningful changes made across your organization — who did what, and when. Use it to answer questions like "who revoked this API key?", "when was this member's entitlement granted?", or "what changed in our settings last week?".

Go to **Activity Log** in the navigation to open it. The Activity Log is available to administrators only.

Who can see the Activity Log

Viewing the Activity Log requires the **Admin** role — the same access that governs organization settings. Members and Viewers do not see it. See [Permissions](/product/administration/permissions.md).

#### Reading the log[​](#reading-the-log "Direct link to Reading the log")

Each row is one recorded change. The list is newest-first and shows:

| Column       | What it shows                                                                                     |
| ------------ | ------------------------------------------------------------------------------------------------- |
| **When**     | How long ago the change happened (for example, "2 hours ago").                                    |
| **Actor**    | Who made the change — a team member's name, an **API key**, or **System** for automated activity. |
| **Category** | The area of the product the change belongs to (see [Categories](#categories)).                    |
| **Activity** | A one-line description of what happened, along with the specific item it affected.                |
| **Details**  | A button that opens the full entry.                                                               |

When a team member acts through an API token rather than the dashboard, the **Actor** column shows their name with a **· via API** marker.

##### Viewing the details of a change[​](#viewing-the-details-of-a-change "Direct link to Viewing the details of a change")

Many rows include an inline summary of the fields that changed. Click **Details** on any row to open the full entry, which shows:

* **When**, **Actor**, **Category**, and the specific **Event**.
* The **Subject** — the item that was changed.
* **Attribute changes** — a before-and-after value for each field that changed.
* **Context** — any extra information recorded with the event.

Sensitive values are never shown

Some changes touch secrets — an API key's value, a signing key, an OAuth client secret. The Activity Log records that the value changed, but the value itself is replaced with a **hidden** marker and is never displayed.

#### Filtering the log[​](#filtering-the-log "Direct link to Filtering the log")

The filters at the top of the page narrow the list as you change them. You can combine any of them:

| Filter               | What it does                                                                       |
| -------------------- | ---------------------------------------------------------------------------------- |
| **Search**           | Matches text in the activity description or the name of the item that was changed. |
| **Category**         | Limits the list to a single [category](#categories).                               |
| **Actor**            | Limits the list to changes made by a **User**, an **API key**, or the **System**.  |
| **Event**            | Limits the list to a single kind of event.                                         |
| **Start / End date** | Limits the list to a date range.                                                   |

The list paginates at 25 entries per page, with a running count of how many entries match your filters.

#### Categories[​](#categories "Direct link to Categories")

Every entry is filed under one category so you can narrow the log to the area you care about:

| Category           | Covers changes to…                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Settings**       | Organization settings and organization-wide branding.                                                                                             |
| **Content**        | Templates, email templates, and interactions — including when they are published, unpublished, duplicated, imported, or restored from a revision. |
| **Commerce**       | Products, plans, offers, and purchase refunds.                                                                                                    |
| **Properties**     | Properties and property-level branding overrides.                                                                                                 |
| **Security**       | Signing keys and OAuth clients.                                                                                                                   |
| **Authentication** | Staff sign-ins, two-factor and passkey changes, password and profile changes, and connected-app removals (see below).                             |
| **Developer**      | Webhooks and the embed snippet.                                                                                                                   |
| **GitHub Sync**    | Template changes applied by a sync from your connected repository.                                                                                |
| **Audience**       | Audience-member changes made from the dashboard, the API, or an AI assistant (see below).                                                         |
| **Exports**        | Data exports that were created.                                                                                                                   |
| **Users**          | Team-member invitations sent, resent, and accepted; role changes; and removals.                                                                   |

##### Account security[​](#account-security "Direct link to Account security")

The **Authentication** category records what your team members do with their own accounts, so you can see sign-in activity and security changes across your organization. It captures:

* Successful and failed sign-ins, sign-outs, and sign-ins that were locked out after too many failed attempts.
* Turning two-factor authentication on or off, regenerating recovery codes, a failed two-factor challenge, and signing in with a recovery code.
* Adding or removing a passkey.
* Changing or resetting a password.
* Changing a name or email address, or deleting an account.
* Disconnecting a connected app.

Sign-in and lockout entries record the IP address they came from. Because these changes follow a person wherever they work, each one appears in the log of every organization that person belongs to.

##### Audience activity[​](#audience-activity "Direct link to Audience activity")

The **Audience** category records the deliberate changes you or your tools make to an audience member — from the dashboard, through the API, or through an AI assistant. It captures:

* Creating, restoring, or deleting a member.
* Changing a member's name or email address.
* Marking a member as verified or unverified.
* Granting or revoking an entitlement.
* Updating a member's profile fields (which fields changed is recorded; the values are not).
* Linking or unlinking an external profile or an external ID.
* Starting a sync of a member with a connected provider.
* Generating a session to sign in as a member (impersonation).

A member's own everyday activity — signing in, or updating their own profile — is not recorded here, so the log stays focused on changes made on their behalf.

#### Retention[​](#retention "Direct link to Retention")

Entries are kept for one year and then removed automatically. The Activity Log is a record of recent change, not a permanent archive.

#### Related Links[​](#related-links "Direct link to Related Links")

* [Permissions](/product/administration/permissions.md) — who can see the Activity Log
* [Settings](/product/administration/settings.md) — the organization settings whose changes are logged
* [Users](/product/administration/users.md) — the team members who appear as actors


---

### Branding

Branding is where you give the Allegro components on your site your own visual identity — your logo, colors, fonts, and shape — without writing any CSS. You set a small number of **global design tokens** once, and every embedded component (login forms, email forms, content gates) inherits them automatically. When you need finer control, you can override a single detail on a single component without disturbing the rest.

Go to **Organization Settings → Branding** to open the editor. Branding is an organization-wide setting, so it is available to administrators.

![Branding](/assets/images/branding-79d567eec83bc8940aa76a04a9885983.png)

***

#### How the design system works[​](#how-the-design-system-works "Direct link to How the design system works")

Allegro's branding is built as a small **design system**: a layered set of variables where broad, brand-wide choices flow down into the specific pieces of each component. There are three levels, from most general to most specific:

| Level                            | What it is                                                                            | Example                                     |
| -------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------- |
| **Global design tokens**         | A handful of brand-wide defaults — your primary color, body font, corner radius, etc. | **Primary** color = your brand teal         |
| **Component-specific variables** | Individual settings exposed by each component, grouped by the part they affect.       | Login form → **Submit button** → Background |
| **Built-in defaults**            | The values a component ships with, used when you haven't set anything.                | Black button on a white background          |

The key idea is **inheritance**. Most component-specific variables don't have a value of their own until you give them one — instead they *inherit* from a global token. So when you change a global token, every component that inherits it updates at once. You only reach for a component-specific override when you want one spot to differ from the brand-wide default.

note

Everything in branding is optional. Until you change something, components render with their built-in defaults, exactly as they did before you set up branding. There's no need to fill in every field.

##### The inheritance chain[​](#the-inheritance-chain "Direct link to The inheritance chain")

When a component renders, each of its settings resolves in this order and uses the first value it finds:

1. **A component-specific override** you set (for example, the login form's submit-button background).
2. Otherwise, the **global token** that setting inherits (for example, your **Primary** color).
3. Otherwise, the component's **built-in default**.

This is why setting a single global token can restyle several components at once, and why an override only ever affects the one place you set it.

***

#### The editor at a glance[​](#the-editor-at-a-glance "Direct link to The editor at a glance")

The Branding editor has two columns:

* **Controls** on the left, where you edit tokens and overrides.
* A **live preview** on the right that re-renders the real components with your in-progress changes, so you can see the effect before saving.

At the top of the controls is a **scope switcher** that decides what you're editing:

| Scope                   | What you edit                                                       |
| ----------------------- | ------------------------------------------------------------------- |
| **Global**              | Your logo and the global design tokens (colors, fonts, shape).      |
| **Login form**          | Per-part variables for the `allegro-login-form` component.          |
| **Email form**          | Per-part variables for the `allegro-email-form` component.          |
| **Form**                | Per-part variables for the `allegro-form` component.                |
| **Content gate**        | Per-part variables for the `allegro-content-gate` component.        |
| **Inline content gate** | Per-part variables for the `allegro-content-gate-inline` component. |
| **Modal**               | Per-part variables for the `allegro-modal` component.               |
| **Bottom drawer**       | Per-part variables for the `allegro-bottom-drawer` component.       |
| **OAuth page**          | The full look of your hosted sign-in and error pages.               |

A small dot next to a field indicates it has been changed from its default.

***

#### Global design tokens[​](#global-design-tokens "Direct link to Global design tokens")

Switch to the **Global** scope to edit the brand-wide tokens. These are the defaults that flow into every component through inheritance. They are grouped into **Colors**, **Typography**, and **Shape & spacing**.

##### Colors[​](#colors "Direct link to Colors")

| Token            | Default   | What it controls                                                          |
| ---------------- | --------- | ------------------------------------------------------------------------- |
| **Primary**      | `#000`    | Your main brand color — buttons, focus states, accents.                   |
| **Primary text** | `#fff`    | Text and icons that sit on top of the primary color (e.g. button labels). |
| **Background**   | `#fff`    | Component and input backgrounds.                                          |
| **Text**         | `#000`    | Default body text color.                                                  |
| **Muted text**   | `#6b7280` | Secondary text — hints, dividers, help copy.                              |
| **Border**       | `#d1d5db` | Input and container borders.                                              |
| **Error**        | `#b91c1c` | Validation errors and error messages.                                     |

Each color has both a hex text field and a color picker.

##### Typography[​](#typography "Direct link to Typography")

| Token            | Default                 | What it controls                                           |
| ---------------- | ----------------------- | ---------------------------------------------------------- |
| **Body font**    | `system-ui, sans-serif` | The default font family for component text.                |
| **Heading font** | *(same as body)*        | The font family for headings; falls back to the body font. |
| **Base size**    | `1rem`                  | The base font size components scale from.                  |

Font fields accept any valid CSS `font-family` value (for example, `Georgia, serif`). As you type, a list of common font suggestions appears — the suggestions are a convenience, not a limit, so you can enter any font your site already loads.

note

Branding does not host or load web fonts for you. Enter fonts that are already available on the pages where your components appear.

##### Shape & spacing[​](#shape--spacing "Direct link to Shape & spacing")

| Token             | Default    | What it controls                                      |
| ----------------- | ---------- | ----------------------------------------------------- |
| **Corner radius** | `0.375rem` | How rounded buttons, inputs, and containers are.      |
| **Spacing unit**  | `1rem`     | The base spacing components use for gaps and padding. |

***

#### Component-specific variables[​](#component-specific-variables "Direct link to Component-specific variables")

Switch the scope to a component (for example, **Login form**) to fine-tune its individual parts. Variables are organized into collapsible groups by the part of the component they affect — the login form, for instance, groups its variables into **General**, **Email input**, **Submit button**, **One-time code**, **Social buttons**, **Divider**, **Errors**, **State screens**, **Resend link**, and **Loading & disabled**.

Each group header shows either how many variables it contains or, once you've customized some, how many are **overridden**. A **filter** box at the top of the scope lets you search variables by name.

##### Inheriting vs. overriding[​](#inheriting-vs-overriding "Direct link to Inheriting vs. overriding")

Every component variable is in one of two states:

* **Inheriting** — the default. The row shows a label like **Inherits Primary**, meaning it takes its value from that global token. You don't have to do anything; if you change the global token later, this variable follows along.
* **Overridden** — you clicked **Override** and gave it a specific value. It now ignores the global token for this one spot. Click **Reset** to return it to inheriting.

When you click **Override**, the field is pre-filled with the value it was already inheriting, so you start from what's currently showing rather than from a blank field.

Not every variable inherits a global token. Structural, one-off settings (such as a button's padding or letter-spacing) show **Component default** instead of an "Inherits" label — there's no brand-wide token that would make sense for them, so they simply use the component's built-in value until you override them.

##### A worked example[​](#a-worked-example "Direct link to A worked example")

Suppose you set the global **Primary** color to your brand's teal. Because they all inherit **Primary** by default, the following update at once:

* the login form's **Submit button** background,
* the email form's **Button** background, and
* the content gate's action **Button** background.

Now suppose you want the email form's button to be a slightly darker teal than everything else. Switch to the **Email form** scope, open the **Button** group, click **Override** on **Background**, and enter the darker value. Only the email form button changes — the login form and content gate buttons still follow the global **Primary** token.

This is the whole point of the cascade: broad changes are one edit, and exceptions stay local.

tip

If you want a brand-wide change, edit a **global token** — not each component. Reach for a component override only when one specific spot needs to differ.

***

#### The components you can brand[​](#the-components-you-can-brand "Direct link to The components you can brand")

| Scope                   | Component                       | Where it appears                                             |
| ----------------------- | ------------------------------- | ------------------------------------------------------------ |
| **Login form**          | `<allegro-login-form>`          | Member sign-in, including one-time codes and social buttons. |
| **Email form**          | `<allegro-email-form>`          | Email capture / newsletter sign-up.                          |
| **Form**                | `<allegro-form>`                | Admin-composed profile forms members fill out.               |
| **Content gate**        | `<allegro-content-gate>`        | The modal gate that blocks content until a member acts.      |
| **Inline content gate** | `<allegro-content-gate-inline>` | The inline (non-modal) variant of the content gate.          |
| **Modal**               | `<allegro-modal>`               | A centered dialog, like a welcome note, that readers close.  |
| **Bottom drawer**       | `<allegro-bottom-drawer>`       | A bottom panel that sits over the page without blocking it.  |

For the full list of variables each component exposes, see the developer [Web Components](/developer/components.md) reference.

***

#### The OAuth page[​](#the-oauth-page "Direct link to The OAuth page")

The **OAuth page** scope is different from the four above: it brands a page rather than a component. Your hosted sign-in page (and its error page) lives on your Allegro domain, so there is no host site whose CSS your developers can adjust. Everything about how that page looks is therefore controlled here.

The scope is organized into seven groups:

| Group               | What it controls                                                                                              |
| ------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Page**            | Page background, font family, base font size, and the two text colors.                                        |
| **Panel**           | The card the form sits in: background, border color and width, corner radius, padding, max width, and shadow. |
| **Logo**            | Maximum height of your logo and the space beneath it.                                                         |
| **Continue button** | Background, text color, corner radius, padding, font size, weight, and text transform.                        |
| **Secondary link**  | The "Use a different account" link: color, hover color, and font size.                                        |
| **Header text**     | Text color, font family, font size, and link color for your header copy.                                      |
| **Footer text**     | The same four controls for your footer copy.                                                                  |

Header and footer copy is edited elsewhere

The **Header text** and **Footer text** groups control only how that copy *looks*. The words themselves live in **Organization Settings › Sign-in page**, because they are content rather than design. See [Sign-in page](/product/administration/sign-in-page.md).

Every variable falls back to the matching global token, so a page you never touch still follows your brand. Two are worth calling out:

* **Page background** does not inherit the global **Background** token. That token is the panel's surface, so sharing it would flatten the panel into the page. Page background defaults to a light grey instead.
* The sign-in form inside the page is styled by the **Login form** scope, not this one.

***

#### Logo[​](#logo "Direct link to Logo")

In the **Global** scope, upload your logo from the **Logo** field.

* Accepted formats: **SVG, PNG, WebP, or JPEG**, up to **2 MB**.
* Add **Alt text** describing the logo for screen readers. Alt text is applied when the logo is uploaded or replaced.
* Once a logo is set, use **Replace** to swap it or **Remove** to clear it.

Your logo appears on your organization's hosted **OAuth sign-in page** (and the matching error page), and is made available to the SDK for use in templates.

note

Uploaded SVG files are sanitized on the server — scripts and remote references are stripped — so an SVG logo is safe to display.

***

#### Live preview[​](#live-preview "Direct link to Live preview")

The preview panel on the right renders the actual components with your in-progress values, updating as you type. It follows the scope switcher, so selecting **Login form** previews the login form, and so on. The **Global** scope also previews a representative sign-in card so you can judge your tokens against a realistic layout. Nothing in the preview is saved until you click **Save**.

Two scopes offer extra preview controls:

* **Content gate** lets you switch the gate between its **bottom** and **center** positions.
* **OAuth page** lets you switch between the three states the page can be in: the **sign-in form**, the **continue as** prompt shown to a member who is already signed in, and the **error** page. The preview uses the same stylesheet the real page uses, so what you see is what gets served.

***

#### Saving and revisions[​](#saving-and-revisions "Direct link to Saving and revisions")

Click **Save** to publish your branding. You can add an optional **Change note** describing what changed; it's recorded with the revision.

Every save creates a **revision**. Open the **Version History** panel (from the button beside **Save**) to:

* **Browse** past revisions, with the author and time of each.
* **Compare** a revision against the one before it to see exactly what changed.
* **Roll back** to any earlier revision in one click, which immediately restores that version everywhere.

***

#### Where branding appears[​](#where-branding-appears "Direct link to Where branding appears")

Your branding is applied to the Allegro components embedded on your own site, and to your hosted OAuth sign-in and error pages. It is delivered as a small stylesheet that is cached for performance, so a change may take a few minutes to appear on live pages.

Crucially, branding only sets **defaults**. Your site's own stylesheet, and any CSS inside an interaction template, always takes precedence over branding — so branding will never fight with, or override, the styles you ship yourself. A tenant that hasn't set any branding is served nothing extra at all.

***

#### Per-property branding[​](#per-property-branding "Direct link to Per-property branding")

If your organization runs multiple [properties](/product/administration/properties.md), each property can override this organization-wide branding with its own logo, tokens, and component variables. Overrides are per value: anything a property leaves unset inherits the organization's branding, so a change you make here still flows through to every property automatically unless that property has overridden the specific value. Each property serves its own merged stylesheet on its own web address.

See [Properties → Branding](/product/administration/properties.md#branding) for how to edit a property's branding.

***

#### Related Links[​](#related-links "Direct link to Related Links")

* [Settings](/product/administration/settings.md) — other organization-wide configuration
* [Properties](/product/administration/properties.md) — override branding per property
* [Permissions](/product/administration/permissions.md) — who can edit organization settings
* [Web Components](/developer/components.md) — the full CSS variable reference for each component


---

### Captcha

Allegro's sign-in is passwordless, so there is no password for an attacker to guess. The thing worth protecting is different: every sign-in request creates an audience member if one does not exist and sends an email. A script rotating through addresses can fill your audience with junk records and bill you for the mail, and heavy bounce or complaint rates from those sends put email delivery at risk for everyone on the sending domain.

Turning on captcha makes each sign-in attempt prove it came from a person before any of that happens.

**Organization Settings › Access & Identity › Captcha** is where you switch it on. It is off until you configure it, and an organization that never visits this screen behaves exactly as it always has.

#### What readers see[​](#what-readers-see "Direct link to What readers see")

Nothing. Google reCAPTCHA v3 scores each attempt in the background rather than showing a puzzle or a checkbox. Google does add a small badge to the corner of pages where the login form appears; its terms require you either to leave that badge in place or to display a short attribution line near your sign-in button instead.

#### Setting it up[​](#setting-it-up "Direct link to Setting it up")

You bring your own reCAPTCHA keys rather than using a shared Allegro account. That is deliberate: reCAPTCHA's free tier is capped per Google account across every site using it, so a shared key would run out for everyone at once.

1. In the [reCAPTCHA admin console](https://www.google.com/recaptcha/admin), create a key of type **reCAPTCHA v3**.
2. Register every domain your login form appears on. A domain you forget will fail verification for readers on that domain.
3. Copy the **Site key** and **Secret key** into the Captcha settings screen.
4. Set **Provider** to Google reCAPTCHA v3 and save.

The secret key is encrypted and never sent to a browser. The site key is public by design — it appears in the page source, which is normal and safe.

#### Choosing a minimum score[​](#choosing-a-minimum-score "Direct link to Choosing a minimum score")

reCAPTCHA returns a score from 0.0 to 1.0, where lower means more bot-like. The **Minimum score** slider sets the point below which a sign-in attempt is rejected.

| Score | Meaning                                                  |
| ----- | -------------------------------------------------------- |
| 0.0   | Almost certainly automated.                              |
| 0.5   | Google's suggested starting point, and the default here. |
| 1.0   | Almost certainly a person.                               |

Raise it only after watching real traffic. This is a genuine trade-off rather than a dial that goes from "less safe" to "more safe": every legitimate reader who scores below your threshold is turned away, sees only a generic error, and has no way to prove otherwise. A threshold that is too high looks to you like a quiet drop in sign-ups, not like an error.

#### When Google is unreachable[​](#when-google-is-unreachable "Direct link to When Google is unreachable")

If reCAPTCHA cannot be reached, or your credentials are rejected, sign-in requests are allowed through and the failure is logged. A Google outage or a mistyped secret key must never lock readers out of your site, and during one you are back to the protection you had before turning captcha on.

A reader whose browser blocks Google's script — an ad blocker, a privacy extension, or a strict corporate network — is a different case. That attempt is rejected, because a sign-in that can simply decline to be checked would make the whole feature pointless. This is the main cost of switching captcha on, and it is worth weighing against how much automated traffic you are actually seeing.

#### Properties[​](#properties "Direct link to Properties")

A property can use the organization's setup, supply its own key pair, or turn captcha off for itself. Credentials are all-or-nothing per property: a property either provides every field or inherits every field, so its site key can never be paired with the organization's secret.

One thing to watch: a property-level selection covers that property's domains only. If the organization itself has no provider selected, sign-in requests to your main Allegro domain stay unprotected even while a property is covered. Select a provider at the organization level to cover everything.

#### Turning it off[​](#turning-it-off "Direct link to Turning it off")

Set **Provider** to Off. Your keys stay saved, so switching back on later does not mean fetching them from Google again.


---

### Connected apps

AI clients such as Claude, Cursor, and VS Code can connect to Allegro's MCP server by having you sign in, instead of using an API key. Each one you approve appears under **Settings → Connected apps**, so you can see what can act as you and cut it off at any time.

#### Connect a client[​](#connect-a-client "Direct link to Connect a client")

1. In your AI client, add your organization's MCP URL, `https://acme.allegrocdp.com/mcp`, as a remote MCP server.
2. When the client opens Allegro in your browser, sign in to the dashboard.
3. Check the consent screen: the client's name, the organization, and the website you'll be sent back to. Only continue if you recognize them.
4. Leave **Change data** unticked for a read-only connection, or tick it to let the client create and update records. Only admins see this option.
5. Click **Allow**.

#### What the list shows[​](#what-the-list-shows "Direct link to What the list shows")

Each connected client shows:

| Detail              | Meaning                                                                                |
| ------------------- | -------------------------------------------------------------------------------------- |
| Name                | The name the client gave itself when it connected                                      |
| Organization        | The organization the client can reach, or **Allegro platform** for the landlord server |
| **Read**, **Write** | Whether the client can only read data, or also change it                               |
| Connected           | When you first approved it                                                             |
| Last used           | The last time it made a request                                                        |

#### Disconnect a client[​](#disconnect-a-client "Direct link to Disconnect a client")

Click **Disconnect** next to the client and confirm. It loses access straight away; you can connect it again later by signing in from the client.

Allegro also disconnects clients for you when you're removed from an organization, when you lose super admin access, or when your account is deleted.

#### Related[​](#related "Direct link to Related")

* [OAuth clients](/product/administration/oauth-clients.md) — Partner integrations that sign your *members* in, which are separate from the apps you connect for yourself


---

### Geolocation

Every visitor's country is available for targeting at no cost, along with their continent and the privacy laws decided by country. Anything more precise than the country, such as a visitor's state, city, or ZIP / postal code, comes from an IP geolocation lookup. Allegro doesn't run those lookups for you. You connect an account with one of the supported providers, and lookups are billed to that account.

**Organization Settings › Geolocation** is where you connect a provider. Until you do, your organization targets by country only.

#### What a provider unlocks[​](#what-a-provider-unlocks "Direct link to What a provider unlocks")

| Condition             | Without a provider                             | With a provider |
| --------------------- | ---------------------------------------------- | --------------- |
| **Country**           | Available                                      | Available       |
| **Continent**         | Available                                      | Available       |
| **Privacy law**       | Every law except CCPA, which is shown disabled | Every law       |
| **Region**            | Shown disabled                                 | Available       |
| **City**              | Shown disabled                                 | Available       |
| **ZIP / postal code** | Shown disabled                                 | Available       |

CCPA needs a provider because it applies to visitors in California, so it depends on the visitor's state, not only their country. Disabled conditions and options are marked **Needs geo provider** in the condition picker.

Journeys you built before removing a provider keep their Region, City, ZIP / postal code, and CCPA conditions, and you can still edit or remove them, but they don't match until you connect a provider again.

#### Supported providers[​](#supported-providers "Direct link to Supported providers")

Allegro supports the providers below because each one reports a visitor's state or province as a standard code (`CA`, `ON`), which is how Region conditions are stored.

| Provider                                                               | Credentials                | Get credentials                                                         |
| ---------------------------------------------------------------------- | -------------------------- | ----------------------------------------------------------------------- |
| [ipdata](https://ipdata.co/)                                           | API key                    | [ipdata documentation](https://docs.ipdata.co/)                         |
| [MaxMind GeoIP2](https://www.maxmind.com/en/geoip2-precision-services) | Account ID and license key | [MaxMind web services](https://dev.maxmind.com/geoip/docs/web-services) |
| [IP-API Pro](https://members.ip-api.com/)                              | API key                    | [IP-API Pro documentation](https://members.ip-api.com/docs)             |
| [ipapi.co](https://ipapi.co/)                                          | API key                    | [ipapi.co documentation](https://ipapi.co/api/)                         |

Check the provider's terms before you choose a plan. Several providers prohibit commercial use on their free tiers.

#### Connecting a provider[​](#connecting-a-provider "Direct link to Connecting a provider")

1. Sign up with one of the providers above and copy your credentials.
2. Go to **Organization Settings › Geolocation**.
3. Choose the provider under **Provider** and paste in its credentials.
4. Click **Save changes**.

Allegro makes one test lookup when you save. If the provider rejects the credentials or your plan doesn't include the API, you see an error and nothing is saved.

Credentials are encrypted and never shown again. To keep a saved credential while changing something else, leave its field blank.

To switch providers, choose the new one and enter its credentials. Allegro removes the previous provider's credentials when you save.

#### Disconnecting[​](#disconnecting "Direct link to Disconnecting")

Set **Provider** to **None (country only)** and save. Allegro deletes the stored credentials and goes back to country-only targeting.

#### What lookups cost[​](#what-lookups-cost "Direct link to What lookups cost")

A lookup runs only when a journey reaches a Region, City, ZIP / postal code, or CCPA condition and the visitor's location isn't already known. Journeys that only check the country never trigger one. Each visitor's result is reused for a day, so a visitor counts as at most one lookup per day no matter how many pages they view or how many conditions use their location.


---

### OAuth clients

An **OAuth client** is a registration for one outside integration that signs your members in through Allegro. A partner's mobile app, a companion site, a community platform, a member portal your team runs separately — each gets its own client, its own credentials, and its own allowlists.

Once a client is registered, the integration can send a member to your hosted sign-in page and, when the member signs in, receive a token that acts as that member. Nothing else on your side needs to change: the member's session, profile, and entitlements are the same ones the rest of Allegro sees.

Manage clients from **Organization Settings → OAuth Clients**.

OAuth needs a custom domain

Members can only sign in through OAuth on a custom domain, such as `members.acme.com`. If neither your organization nor any of your properties has one, the OAuth Clients page says so, and your clients won't work until a domain is set up. Add one from a property's settings, or ask an Allegro admin to set one for your organization.

#### Register a client[​](#register-a-client "Direct link to Register a client")

1. Go to **Organization Settings → OAuth Clients** and click **Create client**.
2. Give it a **Name** that identifies the integration, not the person who asked for it. The name appears on your sign-in page, so members will read it.
3. Add each **Redirect URI** the integration will send members back to.
4. Add each **Allowed origin**, if the integration needs to detect existing sessions. Leave this empty otherwise.
5. Leave **Require PKCE** on unless the integration tells you it cannot support it.
6. Click **Create client**.

Allegro then shows the **Client ID** and the **Client secret**. Send both to the integration through a channel you trust.

The secret is shown once

The client secret is displayed only on the screen that follows creation. Allegro stores a hash of it and cannot show it again. If it is lost, use **Regenerate secret** — which invalidates the old one and breaks the integration until they deploy the new value.

#### What each field controls[​](#what-each-field-controls "Direct link to What each field controls")

| Field               | What it does                                                                                                                 |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Name**            | Identifies the client in this list, in the [Activity Log](/product/administration/activity-log.md), and on the sign-in page. |
| **Redirect URIs**   | The only URLs Allegro will send a member back to after they sign in.                                                         |
| **Allowed origins** | The only websites allowed to ask Allegro whether a visitor is already signed in.                                             |
| **Require PKCE**    | Forces the integration to prove, at the end of the flow, that it started the flow.                                           |
| **Active**          | Turns the client off without deleting it. An inactive client cannot start a sign-in.                                         |

##### Redirect URIs[​](#redirect-uris "Direct link to Redirect URIs")

A redirect URI is where a member's browser goes once they have signed in, and it carries a one-time code the integration exchanges for a token. Allegro will only use a URI on this list, which is what stops someone from crafting a sign-in link that delivers a member's code somewhere you have not approved.

URIs are matched **exactly**. `https://app.acme.com/callback` and `https://app.acme.com/callback/` are two different values, and a query string that differs by one character will not match. Ask the integration for the precise URL rather than deriving it, and add every environment they need. HTTPS is required.

##### Allowed origins[​](#allowed-origins "Direct link to Allowed origins")

Allowed origins are for a different job than redirect URIs. They control which websites may call Allegro to ask *"does this visitor already have a session?"* — so the integration can greet a returning member instead of showing a sign-in prompt they do not need. If the integration is not doing that, leave this list empty; a client with no allowed origins cannot make that request at all.

An origin is a scheme, a host, and an optional port, with nothing after it:

```text
https://community.acme.com

```

Origins are matched **exactly**, and a wildcard cannot be entered here at all. Add each site individually — one entry per community, property, or subdomain that needs it. A parent domain does not cover the hosts beneath it.

Never try to cover a family of subdomains

This request reveals whether a particular person is signed in. If Allegro matched `https://*.acme.com`, then anyone who took over any one unused subdomain could ask that question about your members. Exact matching means a compromised host has to already be on your list.

The same reasoning is why this list is separate from the CORS allowed origins in [Browser Settings](/developer/administration/browser-settings.md), which do accept wildcards.

##### Require PKCE[​](#require-pkce "Direct link to Require PKCE")

PKCE is an extra check that ties the end of a sign-in to the beginning of it, so a stolen one-time code cannot be redeemed by whoever stole it. Leave it on.

Turn it off only when an integration tells you it cannot generate the value — typically an older server-side integration that authenticates with its client secret alone. Turning it off weakens that one client and nothing else.

#### Managing an existing client[​](#managing-an-existing-client "Direct link to Managing an existing client")

Open a client from the list to rename it, change its allowlists, toggle **Require PKCE** or **Active**, regenerate its secret, or delete it.

| Action                | Effect                                                                                          |
| --------------------- | ----------------------------------------------------------------------------------------------- |
| **Save**              | Applies immediately. A removed redirect URI or origin stops working on the next request.        |
| **Regenerate secret** | Invalidates the current secret at once. The integration is broken until it deploys the new one. |
| **Active** off        | The client can no longer start a sign-in. Tokens it already holds are unaffected.               |
| **Delete**            | Permanent. Use **Active** instead when you may want the integration back.                       |

Changes to a client are recorded in the [Activity Log](/product/administration/activity-log.md) under the **Security** category, including the before and after values of the redirect URI list. Secret rotations are logged as an event, but the secret itself is never recorded.

#### Related[​](#related "Direct link to Related")

* [Sign-in page](/product/administration/sign-in-page.md) — Header and footer copy on the page members see
* [Branding](/product/administration/branding.md) — The look of the sign-in page
* [Activity Log](/product/administration/activity-log.md) — The record of client changes
* [OAuth 2.0](/developer/guides/oauth.md) — The developer guide to send your integration partner


---

### Permissions

Every user in your organization has a role — **Admin**, **Member**, or **Viewer**. Each role determines what that person can see and do across Allegro.

For details on managing users and assigning roles, see [Users](/product/administration/users.md).

#### Role overview[​](#role-overview "Direct link to Role overview")

| Role       | Best for                                                                         |
| ---------- | -------------------------------------------------------------------------------- |
| **Admin**  | People who manage the organization, invite users, and configure settings.        |
| **Member** | Content creators who build templates, interactions, and manage audience members. |
| **Viewer** | Stakeholders who need read-only access to review content and data.               |

#### Templates[​](#templates "Direct link to Templates")

| Action                       | Viewer | Member | Admin |
| ---------------------------- | ------ | ------ | ----- |
| View templates               | ✅     | ✅     | ✅    |
| Create templates             | ❌     | ✅     | ✅    |
| Edit templates               | ❌     | ✅     | ✅    |
| Archive templates            | ❌     | ✅     | ✅    |
| Restore archived templates   | ❌     | ✅     | ✅    |
| Permanently delete templates | ❌     | ❌     | ✅    |

#### Interactions[​](#interactions "Direct link to Interactions")

| Action                          | Viewer | Member | Admin |
| ------------------------------- | ------ | ------ | ----- |
| View interactions               | ✅     | ✅     | ✅    |
| Create interactions             | ❌     | ✅     | ✅    |
| Edit interactions               | ❌     | ✅     | ✅    |
| Publish / unpublish             | ❌     | ✅     | ✅    |
| Archive interactions            | ❌     | ✅     | ✅    |
| Restore archived interactions   | ❌     | ✅     | ✅    |
| Permanently delete interactions | ❌     | ❌     | ✅    |

#### Segments[​](#segments "Direct link to Segments")

| Action                                       | Viewer | Member | Admin |
| -------------------------------------------- | ------ | ------ | ----- |
| View segments, counts, and sample members    | ✅     | ✅     | ✅    |
| Export segment members                       | ✅     | ✅     | ✅    |
| Create, edit, duplicate, and delete segments | ❌     | ✅     | ✅    |

#### Email Templates[​](#email-templates "Direct link to Email Templates")

| Action                  | Viewer | Member | Admin |
| ----------------------- | ------ | ------ | ----- |
| View email templates    | ✅     | ✅     | ✅    |
| Edit and save templates | ❌     | ✅     | ✅    |
| Send test emails        | ❌     | ✅     | ✅    |
| Reset to default        | ❌     | ✅     | ✅    |

#### Users[​](#users "Direct link to Users")

| Action               | Viewer | Member | Admin |
| -------------------- | ------ | ------ | ----- |
| View users           | ✅     | ✅     | ✅    |
| Invite and add users | ❌     | ❌     | ✅    |
| Change user roles    | ❌     | ❌     | ✅    |
| Remove users         | ❌     | ❌     | ✅    |

#### Organization Settings[​](#organization-settings "Direct link to Organization Settings")

| Action                       | Viewer | Member | Admin |
| ---------------------------- | ------ | ------ | ----- |
| View settings                | ✅     | ✅     | ✅    |
| Update organization settings | ❌     | ❌     | ✅    |
| Configure login providers    | ❌     | ❌     | ✅    |
| Manage packages              | ❌     | ❌     | ✅    |
| View the Activity Log        | ❌     | ❌     | ✅    |

#### Audience[​](#audience "Direct link to Audience")

| Action                        | Viewer | Member | Admin |
| ----------------------------- | ------ | ------ | ----- |
| View audience members         | ✅     | ✅     | ✅    |
| Edit audience members         | ❌     | ✅     | ✅    |
| Delete audience members       | ❌     | ✅     | ✅    |
| Grant and revoke entitlements | ❌     | ✅     | ✅    |


---

### Properties

Properties let a single organization operate more than one property from one Allegro account. A media company might run two publications as separate properties under one organization; a publisher might separate a flagship publication from a newsletter product. Each property has its own web address and its own browser and email configuration, while sharing the organization's members, entitlements, templates, and reporting.

You do not need properties to use Allegro. If your organization is a single brand, the organization-level settings are all you need. Add properties only when you have distinct properties that must present a different domain or send email under a different identity.

#### How Properties Relate to Your Organization[​](#how-properties-relate-to-your-organization "Direct link to How Properties Relate to Your Organization")

A property is scoped to your organization and inherits everything the organization defines. It layers a small number of property-specific overrides on top:

| Area                             | Behavior with properties                                                                                                                                                        |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Members, entitlements, purchases | Shared across the whole organization — a member is the same person on every property.                                                                                           |
| Templates and interactions       | Shared across the whole organization.                                                                                                                                           |
| Reporting and analytics          | Shared across the whole organization.                                                                                                                                           |
| Web address                      | Each property has its own subdomain, and optionally its own custom domain.                                                                                                      |
| CORS allowed origins             | The property **adds** its origins on top of the organization's — it never removes them.                                                                                         |
| Cookie domain                    | The property can **replace** the organization's, or inherit it when left blank.                                                                                                 |
| Email sender (name & address)    | The property can **override** the name and address email is sent from, or inherit the organization's when left blank.                                                           |
| Email templates                  | Resolved per property, then falling back to the organization, then the built-in default.                                                                                        |
| Branding                         | Each token, component variable, and the logo can be overridden per property, inheriting the organization's value otherwise.                                                     |
| Login providers                  | A property can override any provider with its own OAuth credentials, reorder them, or hide one the organization has configured — inheriting the organization's setup otherwise. |

#### The Properties List[​](#the-properties-list "Direct link to The Properties List")

Go to **Organization Settings → Properties** to see every property in your organization. The list shows each property's name, slug, and custom domain (if one is set).

Who can manage properties

Managing properties requires the same permission as managing the organization. Anyone who can edit organization settings can create, configure, and delete properties. See [Permissions](/product/administration/permissions.md).

#### Creating a Property[​](#creating-a-property "Direct link to Creating a Property")

Click **New Property** from the Properties list and provide:

| Field             | Description                                                                                                          |
| ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Name**          | The display name shown throughout the dashboard. You can change this later.                                          |
| **Slug**          | The permanent identifier used in the property's web address.                                                         |
| **Custom Domain** | *(Optional)* Choose from the domains already added to your organization. Leave unset to use the default web address. |

Choosing a domain

Custom Domain is a list, not free text — it only offers domains already added to your organization and not already assigned elsewhere. Adding a new domain is not a self-service action from Property Settings; if the domain you need isn't listed, ask your platform administrator to add it.

##### Slug Rules[​](#slug-rules "Direct link to Slug Rules")

The slug becomes part of the property's web address, so it has strict formatting rules:

* Lowercase letters, numbers, and single hyphens only.
* **No consecutive hyphens.** A double hyphen (`--`) is reserved as the separator between your organization and the property in the web address.
* Up to 63 characters.
* Must be unique within your organization.

Slugs are permanent

A property's slug **cannot be changed after the property is created**. It is baked into the property's web address and its saved configuration. Choose it carefully. To use a different slug, delete the property and create a new one.

Once created, you are taken to the property's **General** settings, where the rest of its configuration lives.

#### Property Settings[​](#property-settings "Direct link to Property Settings")

Each property has its own settings area, reached by clicking a property in the Properties list. The left navigation has six sections: **General**, **Branding**, **Browser Settings**, **Login Providers**, **Email Settings**, and **Email Templates**.

##### General[​](#general "Direct link to General")

The General page shows the property's name, its (read-only) slug, and its custom domain.

| Field             | Description                                                                                                                                                       |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**          | Editable display name.                                                                                                                                            |
| **Slug**          | Read-only. Set at creation and permanent.                                                                                                                         |
| **Custom Domain** | The domain that serves this property's audience-facing traffic, chosen from the domains available to your organization. Leave unset to use the default subdomain. |

A custom domain is provisioned by your platform administrator before it can be selected here — this page only lets you assign an already-available domain to this property, not add a new one. DNS and certificate setup are handled when the domain is added to your organization; this page never asks you to configure DNS. For how custom domains are served and routed, see the developer guide on [Properties](/developer/guides/properties.md).

This field must stay valid to save the page

Every setting on this page saves together. If this property's custom domain is ever no longer available to your organization (for example, it was removed from your organization's inventory), you cannot save **any** change here — not just the domain — until you select a currently available domain or clear the field. Ask your platform administrator to re-add the domain if you need to keep using it.

##### Branding[​](#branding "Direct link to Branding")

The Branding page lets a property override the organization's branding — its logo, global design tokens, and per-component variables — so the Allegro components embedded on that property's pages can carry a distinct visual identity. It uses the same editor as organization branding, with one difference: anything a property leaves unset **inherits** the organization's value.

Inheritance works per value:

* Every design token and component variable falls through to the organization's value (and then the built-in default) until you give it a property-specific value. Inherited values appear as placeholders, and a small dot marks the ones you have overridden for this property.
* The **logo** is atomic: a property logo replaces the organization's entirely when set, and removing it falls back to the organization's logo.
* Clearing a value returns it to inheriting, so an organization rebrand still flows through to a property automatically for anything the property hasn't overridden.

The live preview renders the true merged result — the property's overrides layered on top of the organization's branding — and each property's branding keeps its own revision history, so you can browse, compare, and roll back a property's branding independently of the organization's.

For how the branding design system, inheritance, and revisions work in general, see [Branding](/product/administration/branding.md).

##### Browser Settings[​](#browser-settings "Direct link to Browser Settings")

The Browser Settings page controls how this property's pages interact with the Allegro SDK in a member's browser. These mirror the organization's browser settings but apply only to this property.

| Setting                  | Description                                                           |
| ------------------------ | --------------------------------------------------------------------- |
| **CORS Allowed Origins** | The web origins allowed to call this property's API from the browser. |
| **Cookie Domain**        | The domain the session cookie is scoped to for this property.         |

###### CORS Allowed Origins[​](#cors-allowed-origins "Direct link to CORS Allowed Origins")

Each origin is a full origin such as `https://acme.com`. Wildcard subdomain origins are supported in the form `https://*.acme.com`.

The property's origins are **added on top of** the organization's allowed origins — configuring them here never removes origins the organization already allows. The property's own web address is always allowed automatically.

###### Cookie Domain[​](#cookie-domain "Direct link to Cookie Domain")

Set a cookie domain (for example `.acme.com`) so member sessions are shared across that property's subdomains. If you leave this blank, the property **inherits the organization's cookie domain**. Setting a value here replaces the organization's value for this property only.

##### Login Providers[​](#login-providers "Direct link to Login Providers")

The Login Providers page controls how audience members sign in on this property — which OAuth providers appear, in what order, and whether each one uses the organization's OAuth app or the property's own. Everything inherits the organization's [Login Providers](/product/administration/settings.md#login-providers) configuration until you override it here.

Each provider is a card with its own controls:

| Control                   | What it does                                                                                                                                             |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Show on this property** | Turn a provider off to hide it on this property's login form, even when the organization has it configured.                                              |
| **Credentials**           | Choose **Organization's** to use the organization's OAuth app (the default), or **This property's** to authenticate with an OAuth app for this property. |

When a provider uses **This property's** credentials, every credential field comes from the property — nothing is inherited — and the page shows a **Redirect URL** to register as the authorized redirect URI on that property's OAuth app. Because a property is served from its own host, this URL differs from the organization's, so a property with its own OAuth app needs its own redirect URI registered with the provider.

A provider's badge reflects its state on this property: **Enabled**, **Not configured**, **Turned off**, or **Own credentials**. To change the order providers appear on the login form, drag them into place in the list at the top of the page.

Inheriting an unconfigured provider

If you leave a provider set to the organization's credentials but the organization has not configured it, the provider stays unavailable on this property until you supply the property's own credentials.

##### Email Settings[​](#email-settings "Direct link to Email Settings")

The Email Settings page controls the **sender identity** for email sent through this property — the name and address it comes from. This lets each property send under its own identity while still using the organization's email delivery configuration.

| Field            | Description                                               |
| ---------------- | --------------------------------------------------------- |
| **From Name**    | The display name recipients see (e.g. `Acme News`).       |
| **From Address** | The address email is sent from (e.g. `noreply@acme.com`). |

Leave a field **blank to inherit** the organization's value — when it inherits, the page shows the organization value it is falling back to. The resolution is the familiar three tiers: **property → organization → built-in default**.

Click **Send test email** to send a test message to your own email address using this property's **saved** sender settings, so you can confirm the identity looks right before real email goes out. Save any changes first — the test uses the saved values, and a provider rejection (such as an unverified From Address) is reported to you directly.

Where sender credentials live

Only the sender **name and address** are set per property. The underlying email delivery credentials (AWS SES) remain an organization-wide setting — see [Settings → Email](/product/administration/settings.md#email-aws-ses).

##### Email Templates[​](#email-templates "Direct link to Email Templates")

Each property can customize the transactional emails Allegro sends — such as magic sign-in links — so they match that property's brand. The Email Templates page lists every email type and shows where its current content comes from:

| Source           | Meaning                                                                                           |
| ---------------- | ------------------------------------------------------------------------------------------------- |
| **Property**     | This property has its own customized template.                                                    |
| **Organization** | No property override; the organization's template is used.                                        |
| **Default**      | Neither the property nor the organization has customized it; Allegro's built-in template is used. |

When you edit a template, the editor shows the inherited content (the organization's version, or the built-in default) alongside your property-specific version so you can see what you are overriding.

* **Send Test** sends a preview of the property's rendered template to your own email address.
* **Reset** removes the property override. The template then falls back to the organization's version, or the built-in default if the organization has not customized it either.

This three-tier resolution — **property → organization → default** — means you only need to override the emails that differ for a given property. Everything else inherits automatically.

For the organization-wide equivalent of this page, see [Email Templates](/product/email-templates.md).

#### Deleting a Property[​](#deleting-a-property "Direct link to Deleting a Property")

Delete a property from its settings. Deleting a property removes its property-specific configuration — its browser settings, email template overrides, and custom domain mapping. It does **not** affect members, entitlements, or templates, which belong to the organization.

Deletion is permanent

Deleting a property permanently removes its configuration and frees its slug and custom domain. Any embed code pointing at the deleted property's web address will stop resolving.

#### Related Links[​](#related-links "Direct link to Related Links")

* [Properties (Developer)](/developer/guides/properties.md) — host format, custom domains, and how the SDK targets a property
* [Settings](/product/administration/settings.md) — organization-wide configuration
* [Email Templates](/product/email-templates.md) — organization-wide transactional email
* [Permissions](/product/administration/permissions.md) — who can manage properties


---

### Settings

Settings is where you configure how your organization works and customize your own account. There are two areas: **Organization Settings** control tenant-wide behavior, while **Personal Settings** apply only to you.

![Settings](/assets/images/settings-aa4273b6e06e19169bb1e786dabd0b23.png)

***

#### Organization Settings[​](#organization-settings "Direct link to Organization Settings")

Organization settings are available to administrators. They control how the tenant operates for everyone.

##### General[​](#general "Direct link to General")

Go to **Organization Settings → General** to update your organization's basic information.

| Field                 | Description                                     |
| --------------------- | ----------------------------------------------- |
| **Organization Name** | The name shown throughout the application.      |
| **Timezone**          | The timezone used for scheduling and reporting. |

Click **Save** to apply changes.

***

##### Email (AWS SES)[​](#email-aws-ses "Direct link to Email (AWS SES)")

Go to **Organization Settings → Email** to configure AWS Simple Email Service (SES). Allegro uses SES to send transactional email on behalf of your organization.

| Field                 | Description                                                             |
| --------------------- | ----------------------------------------------------------------------- |
| **Access Key ID**     | Your AWS IAM access key ID with SES send permissions.                   |
| **Secret Access Key** | The corresponding AWS secret access key.                                |
| **Region**            | The AWS region where your SES service is configured (e.g. `us-east-1`). |

If a credential is already saved, the field shows a masked placeholder (`••••••••`). Enter a new value to replace it.

info

Allegro stores your SES credentials encrypted. You can update them at any time by entering new values and saving.

tip

Before saving, make sure your IAM user or role has the `ses:SendEmail` and `ses:SendRawEmail` permissions in the configured region.

###### Sender identity[​](#sender-identity "Direct link to Sender identity")

The same page controls the name and address your organization's email is sent **from**:

| Field            | Description                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------------- |
| **From Name**    | The display name recipients see in their inbox (e.g. `Acme News`).                            |
| **From Address** | The address email is sent from (e.g. `noreply@acme.com`). It must be verified in SES to send. |

Individual [properties](/product/administration/properties.md#email-settings) can override this sender identity so each property sends under its own name and address.

###### Send a test email[​](#send-a-test-email "Direct link to Send a test email")

Click **Send test email** to send a short test message to your own email address using the **saved** settings, so you can confirm delivery works end to end. If you have unsaved changes, save them first — the test always uses the saved values.

If the mail provider rejects the message — for example, because the From Address is not verified in SES — the error is shown to you directly rather than failing silently in the background.

***

##### Login Providers[​](#login-providers "Direct link to Login Providers")

Go to **Organization Settings → Login Providers** to set up OAuth login for your audience members. Each provider shows whether it is **Enabled** or **Not configured**.

Supported providers include **Google**, **Apple**, **Facebook**, and **GitHub**.

###### Setting Up a Provider[​](#setting-up-a-provider "Direct link to Setting Up a Provider")

Each provider requires a **Client ID** and **Client Secret** (and sometimes additional fields). To configure one:

1. Create an OAuth application in the provider's developer console.
2. Copy the **Redirect URL** shown on the Login Providers page and add it as an authorized redirect URI in your OAuth app.
3. Enter the credentials into the corresponding fields and click **Save**.

Once saved, the provider badge changes to **Enabled** and audience members can sign in with that provider.

Per-property overrides

Organizations that run multiple [properties](/product/administration/properties.md) can override these providers per property — using a property's own OAuth app, reordering them, or hiding one on a specific property. See [Properties → Login Providers](/product/administration/properties.md#login-providers).

note

Encrypted fields such as Client Secret show a masked placeholder once saved. To update a secret, enter a new value. To remove a saved secret, use the **remove it** link below the field.

###### Apple Sign In[​](#apple-sign-in "Direct link to Apple Sign In")

Apple Sign In requires a few extra steps compared to other providers:

* **Client ID** — Your Apple Services ID (e.g. `com.example.allegro`). This is the Service ID you create in the Apple Developer portal, not your App ID.
* **Client Secret** — A signed JWT you generate using a private key downloaded from Apple. Apple client secrets have a maximum lifetime of 6 months and must be regenerated before they expire.

When your client secret is approaching expiration, generate a new one in the Apple Developer portal and update it in **Organization Settings → Login Providers → Apple**.

***

##### GitHub Sync[​](#github-sync "Direct link to GitHub Sync")

Go to **Organization Settings → GitHub Sync** to connect a GitHub repository as the template source for your organization. When connected, templates sync automatically on every push to the configured branch.

For full setup instructions — including creating the GitHub App, configuring environment variables, and the installation flow — see the [GitHub Sync](/developer/platform/integrations/github-sync.md) guide.

###### Managing an Existing Connection[​](#managing-an-existing-connection "Direct link to Managing an Existing Connection")

Once connected, the page shows:

| Detail                | Description                                                    |
| --------------------- | -------------------------------------------------------------- |
| **Connected Account** | The GitHub account or organization the app is installed under. |
| **Repository**        | The full repository name (e.g. `org/repo`) being synced from.  |
| **Default Branch**    | The branch that triggers syncs on push.                        |
| **Last Sync**         | Timestamp and short commit SHA of the most recent sync.        |

From this page you can:

* **Sync Now** — Manually trigger a sync (rate-limited to once every 5 minutes).
* **Change Repository** — Opens the GitHub App settings to adjust which repositories are accessible.
* **Disconnect** — Stops syncing. Existing templates remain but become editable.

warning

Disconnecting does not delete your templates. However, if you later connect a new repository to an organization that already has templates, Allegro will permanently delete all existing templates to replace them with the repository contents. You must type `DELETE` to confirm this action.

###### Latest Sync Status[​](#latest-sync-status "Direct link to Latest Sync Status")

Below the connection details, Allegro shows the most recent sync status:

| Status                | Meaning                                                                     |
| --------------------- | --------------------------------------------------------------------------- |
| **Pending / Running** | The sync job is queued or actively processing.                              |
| **Success**           | All templates were synced from the repository.                              |
| **Failed**            | The sync encountered an error. The error message is shown below the status. |

Warnings (e.g. skipped files) are also listed when present.

***

##### Packages[​](#packages "Direct link to Packages")

Go to **Organization Settings → Packages** to manage which integration packages are enabled for your organization. Packages are grouped by category.

Check or uncheck a package to enable or disable it, then click **Save**.

note

Packages marked with a **Global** badge are always enabled and cannot be toggled from this page.

***

##### Developer Tools[​](#developer-tools "Direct link to Developer Tools")

The **Developer Tools** section groups settings that are relevant to technical integrations and local development — API keys, GitHub template sync, the embed snippet, preview CSS, and webhooks. It appears at the bottom of the Organization Settings sidebar, below the **Access & Identity** section (login providers, OAuth clients, and the sign-in page).

###### API Keys[​](#api-keys "Direct link to API Keys")

Go to **Organization Settings → API Keys** to create and manage the API keys your organization uses to authenticate with the Allegro REST API.

API keys belong to the **organization**, not to an individual user. Everyone who manages them sees the same shared list, and a key keeps working as people join or leave the team. Managing keys requires the **Admin** role — members without it cannot view or change this page.

Organization-scoped

An organization API key only works against its own organization. A key from one organization is rejected if it is used against another organization's domain.

###### Creating a key[​](#creating-a-key "Direct link to Creating a key")

1. Click **Create Key** and give it a descriptive name (e.g. `data-pipeline`).
2. Choose when the key should **expire** — **30 days** (the default), **90 days**, **1 year**, a **custom date**, or **Never**. A dated key stops working at the end of the chosen day, so prefer a dated expiry over **Never** wherever you can.
3. Choose the [scopes](/developer/api/authentication.md#token-scopes) the key should carry.
4. Confirm. The generated key value is shown once — **copy it now**, because it is never displayed again.

###### Managing existing keys[​](#managing-existing-keys "Direct link to Managing existing keys")

Each key in the list shows its **name**, the **scopes** it carries, when it was **created**, when it **expires** (or **Never**), and when it was **last used** (or **Never**). A key approaching its expiry date is highlighted, and one that has already lapsed is marked **Expired**. From the list you can:

* **Edit** a key to rename it, change its expiration, or change its scopes.
* **Revoke** a key to stop it working immediately. Revoked keys cannot be recovered.

Expired keys cannot be extended

An expired key stops working on its own and can no longer be edited. There is no way to extend it — create a new key to replace it.

Creating, updating, and revoking keys is recorded in an **activity log** on the page — showing who made each change and when — so the organization has a clear audit trail.

warning

Treat API keys like passwords. Do not share them or commit them to source control. If a key is compromised, revoke it immediately and create a new one.

###### Embed Snippet[​](#embed-snippet "Direct link to Embed Snippet")

Go to **Organization Settings → Embed Snippet** to inject custom JavaScript into every page that loads the Allegro SDK via `client.js`. The snippet is appended to the loader and executes after the SDK initializes.

A typical snippet uses the event queue to run code on every page load:

```js
window.allegro.push((allegro) => {
    // Runs after Allegro initializes on every page
});

```

Every save creates a new revision. You can browse the diff history and restore any previous version from the **Version History** panel on the same page.

note

The snippet is cached as part of `client.js` for up to 5 minutes. Changes may not appear on your site immediately after saving.

For more details on how the snippet is served and how to use it, see the [Script Tag](/developer/guides/script-tag.md#embed-snippet) guide.

###### Preview CSS[​](#preview-css "Direct link to Preview CSS")

Go to **Organization Settings → Preview CSS** to add custom CSS that is applied when previewing templates with the [Allegro Preview](/developer/guides/local-preview.md) tool. This lets you approximate the look of your site's stylesheet without having to embed Allegro in a live page.

note

This field accepts CSS only. Allegro rejects any value containing a `<` character, so markup such as a `<style>` tag cannot be saved here.

###### GitHub Template Sync[​](#github-template-sync "Direct link to GitHub Template Sync")

Go to **Organization Settings → GitHub Sync** to connect a GitHub repository as the source for your interaction templates. When connected, templates sync automatically on every push to the configured branch.

For full configuration details, see the [GitHub Sync](#github-sync) section above.

***

#### Personal Settings[​](#personal-settings "Direct link to Personal Settings")

Personal settings apply only to your own account. They do not affect other users in your organization.

##### Profile[​](#profile "Direct link to Profile")

Go to **Personal Settings → Profile** to update your account details.

| Field             | Description                                                  |
| ----------------- | ------------------------------------------------------------ |
| **Name**          | Your display name shown throughout the application.          |
| **Email address** | The email address used to sign in and receive notifications. |

Click **Save** to apply changes.

If your email address has not been verified, a prompt appears with a link to resend the verification email.

danger

Your profile page also contains an option to permanently delete your account. This action cannot be undone.

***

##### Password[​](#password "Direct link to Password")

Go to **Personal Settings → Password** to change your account password.

Enter your **current password**, then provide a **new password** and a matching **confirmation**. Click **Save password** to apply.

tip

Use a long, randomly generated password. A password manager can help you generate and store one securely.

***

##### Two-Factor Authentication[​](#two-factor-authentication "Direct link to Two-Factor Authentication")

Go to **Personal Settings → Two-Factor Authentication** to enable or disable 2FA on your account.

###### Enabling 2FA[​](#enabling-2fa "Direct link to Enabling 2FA")

1. Click **Enable 2FA**. A setup modal appears with a QR code.
2. Scan the QR code with a TOTP-compatible authenticator app (such as Google Authenticator, Authy, or 1Password). If you cannot scan the code, a manual setup key is also provided.
3. Enter the one-time code from your authenticator app to confirm setup.

Once enabled, you are prompted for a TOTP code on every login.

###### Recovery Codes[​](#recovery-codes "Direct link to Recovery Codes")

After enabling 2FA, you can view your **recovery codes**. Store these somewhere safe — they let you regain access if you lose your authenticator device.

###### Disabling 2FA[​](#disabling-2fa "Direct link to Disabling 2FA")

When 2FA is enabled, a **Disable 2FA** button appears. Click it to remove the two-factor requirement from your account.

warning

Disabling 2FA reduces the security of your account. Only disable it if you have a specific reason to do so.

***

##### Appearance[​](#appearance "Direct link to Appearance")

Go to **Personal Settings → Appearance** to control the color scheme of the Allegro admin interface.

| Option     | Description                                                |
| ---------- | ---------------------------------------------------------- |
| **Light**  | Always use the light theme.                                |
| **Dark**   | Always use the dark theme.                                 |
| **System** | Follow your operating system's light/dark mode preference. |

Your preference is saved automatically when you select an option.

***

#### Related Links[​](#related-links "Direct link to Related Links")

* [Users](/product/administration/users.md) — manage team members and invitations
* [Permissions](/product/administration/permissions.md) — understand roles and what each can access


---

### Sign-in page

When a partner application signs a member in through Allegro, the member lands on your organization's **hosted sign-in page**. That page is served from your Allegro domain, so unlike an embedded component there is no surrounding site whose markup your developers control.

**Organization Settings › Sign-in page** is where you add your own copy to it — most commonly the Terms of Service and Privacy Policy links a sign-up flow needs to display.

#### Header and footer[​](#header-and-footer "Direct link to Header and footer")

| Field      | Where it appears                                                                                         |
| ---------- | -------------------------------------------------------------------------------------------------------- |
| **Header** | Above the sign-in form only.                                                                             |
| **Footer** | Below the sign-in form, and below the "Continue as …" prompt shown to a member who is already signed in. |

Neither appears while the page is loading, and neither appears on the sign-in error page.

#### What HTML is allowed[​](#what-html-is-allowed "Direct link to What HTML is allowed")

The fields accept HTML, but only a deliberately small subset survives:

| Allowed        | Purpose     |
| -------------- | ----------- |
| `<a href="…">` | Links       |
| `<strong>`     | Bold text   |
| `<em>`         | Italic text |

Everything else is removed when you save:

* Any other tag is stripped, but the words inside it are kept — `<p>Read the terms</p>` saves as `Read the terms`. Structure collapses to one run of text, so a pasted list saves as its items separated by spaces rather than as bullets. Copy that needs to read as separate lines belongs on your own site, behind a link.
* `<script>` and `<style>` are removed along with their contents.
* All attributes are removed, including `class`, `style`, and any `on…` event handler.
* Link destinations must be `https:` or `mailto:`. A link to anything else — including `http:`, a relative path, or `javascript:` — loses its link and becomes plain text.

Because saving rewrites your input to the cleaned version, the editor always shows exactly what the page will render. If something disappears after you save, it was not in the list above.

Why the restrictions are this tight

This is the one page in Allegro that completes an authorization and briefly handles the member's signed-in session. Markup that could run script there could capture a member's session, so the page accepts only what a legal footer genuinely needs.

##### Links always open in a new tab[​](#links-always-open-in-a-new-tab "Direct link to Links always open in a new tab")

Every link is given `target="_blank"` automatically. The authorization request lives in the tab the member started in, so a member who navigated away to read your terms would otherwise have to begin signing in again.

#### Example[​](#example "Direct link to Example")

```html
By continuing you agree to our
<a href="https://example.org/terms">Terms of Service</a>
and <a href="https://example.org/privacy">Privacy Policy</a>.

```

#### Styling it[​](#styling-it "Direct link to Styling it")

This page controls the words. Their appearance — text color, font, size, and link color — is set in the **OAuth page** scope of the [Branding editor](/product/administration/branding.md), under the **Header text** and **Footer text** groups. The branding preview renders your saved copy, so you can switch to the **OAuth page** scope there to see the result in place.


---

### Users

The Users page is where you control who on your team can access your Allegro organization and what they're allowed to do. Use it to invite new team members, assign roles, and remove people who no longer need access.

Team members vs. audience members

**Users** are your internal team — the people who log in to the Allegro admin and manage content. They are distinct from **Audience members**, who are the end-users your organization sends interactions to. This page covers team members only.

![Users](/assets/images/users-d4af77dc700d069e31186761bb774c96.png)

#### Viewing Users[​](#viewing-users "Direct link to Viewing Users")

Go to **Users** in the main navigation to see everyone in your organization. The list shows each person's name, email, role, and the date they joined. It is sorted alphabetically by name and paginates at 25 per page.

#### Roles[​](#roles "Direct link to Roles")

Every user has one of three roles:

* **Viewer** — Read-only access. Great for stakeholders who need visibility but won't edit content.
* **Member** — Can create, edit, and manage content. Assign this to anyone who actively builds interactions and templates.
* **Admin** — Full access, including user management and organization settings. Reserve this for people who need to manage the organization itself.

For a full breakdown of what each role can do, see [Permissions](/product/administration/permissions.md).

tip

Assign the most restrictive role that still lets each person do their job. Start with **Viewer** and escalate only when needed.

#### Adding a User[​](#adding-a-user "Direct link to Adding a User")

Only Admins can add users.

1. Go to **Users** and click **Add User**.
2. Fill in the person's **name**, **email**, and choose a **role**.

What happens next depends on whether that email already has an Allegro account:

* **New to Allegro** — Allegro creates an account and sends a welcome email with a link to set their password. The subject line reads: *Welcome to \[your organization name]*.
* **Already has an account** — Allegro adds them to your organization and sends a notification. The subject line reads: *You've been added to \[your organization name]*.

You cannot add someone who is already a member of your organization.

note

The invitation email includes a password-reset link so new users can set their own password. No one needs to share a temporary one.

#### Changing a User's Role[​](#changing-a-users-role "Direct link to Changing a User's Role")

Only Admins can change roles, and you cannot change your own.

1. Go to **Users**.
2. Find the user whose role you want to change.
3. Select the new role from the role selector next to their name.

The change takes effect immediately.

#### Removing a User[​](#removing-a-user "Direct link to Removing a User")

Only Admins can remove users, and you cannot remove yourself.

1. Go to **Users**.
2. Find the user you want to remove.
3. Click the remove action next to their name and confirm.

Removing a user revokes their access to your organization. It does not delete their Allegro account — if they belong to other organizations, those memberships are unaffected.

#### Related[​](#related "Direct link to Related")

* [Permissions](/product/administration/permissions.md) — Full role-by-role permission breakdown


---

### Analytics

Analytics shows how readers find, read, and act on your site, built from the events the Allegro SDK records on every page. Open it from **Analytics** in the sidebar. Its pages:

| Page                                     | What it answers                                                    |
| ---------------------------------------- | ------------------------------------------------------------------ |
| **Pulse** (this page)                    | What is happening on the site in the last hour?                    |
| [Events](/product/analytics/events.md)   | What happened over a period, and what did each reader do?          |
| [Reports](/product/analytics/reports.md) | Which views does your team come back to? Build and share your own. |

Anyone in your organization can view Analytics, including viewers.

tip

Analytics data comes from events sent by the Allegro SDK. Make sure the [Script Tag](/developer/guides/script-tag.md) is loaded on every page you want to track.

#### The Pulse[​](#the-pulse "Direct link to The Pulse")

The Pulse is the page you land on when you click **Analytics**. A green **Live** badge sits beside the title, and the page refreshes itself every 30 seconds, so you can leave it open on a second screen.

![The Pulse: readers now, page views in the last hour, readers per minute, traffic sources, and the last hour by event](/assets/images/pulse-996e3e9401c7c21d7a1fee42016ff193.png)

##### Headline numbers[​](#headline-numbers "Direct link to Headline numbers")

| Number                       | What it counts                                                             |
| ---------------------------- | -------------------------------------------------------------------------- |
| **Readers now**              | Sessions active in the last 5 minutes.                                     |
| **Page views · last hour**   | Page views in the last 60 minutes, compared with the same hour a week ago. |
| **Avg engaged time · today** | Average engaged time since midnight.                                       |
| **Sign-ups · last hour**     | New member sign-ups in the last 60 minutes, compared with last week.       |

Comparing with the same hour last week, rather than the hour before, keeps the normal rise and fall of a day from looking like a trend.

##### Cards[​](#cards "Direct link to Cards")

| Card                   | What it shows                                                                                                                                                                                                 |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Readers per Minute** | Page views in each of the last 60 minutes.                                                                                                                                                                    |
| **Traffic Sources**    | Each source's share of page views in the last hour, grouped into [traffic channels](#traffic-channels).                                                                                                       |
| **Last Hour by Event** | Page views, content gates, sign-ups, logins, magic link requests, and purchases in the last hour, each against the same hour last week. Click a tile to open its [Events](/product/analytics/events.md) view. |
| **Spiking**            | Stories running furthest above their usual pace: views in the last 30 minutes, the typical count, and the lift (for example **3.2×**). Click a story to open its [story view](/product/content/story.md).     |
| **Top Referrers**      | The external sites sending readers in the last hour, with their channel, page views, and sessions.                                                                                                            |
| **Pinned Reports**     | Links to the [saved reports](/product/analytics/reports.md#pin-to-pulse) your team pinned. The card appears once a report is pinned.                                                                          |

#### Filters shared across Analytics[​](#filters-shared-across-analytics "Direct link to Filters shared across Analytics")

##### Property[​](#property "Direct link to Property")

If your organization has more than one [property](/product/administration/properties.md), a property selector appears in the page header. Pick a property to scope every number on the page to it, or **All properties** to see the whole organization. The choice carries over as you move between Analytics pages.

##### Product[​](#product "Direct link to Product")

On the [Events](/product/analytics/events.md) views, a second selector, **All readers**, lets you narrow the numbers to members of one [product](/product/entitlements.md). Use it to compare how paying members read against everyone else.

##### Date range[​](#date-range "Direct link to Date range")

The Events views share a range control: **7d**, **30d** (the default), **90d**, **1y**, or **Custom** for any start and end date up to a year apart. Ranges are whole calendar days in your organization's time zone and include today.

Every stat compares the range with the period of the same length just before it, so **30d** compares the last 30 days with the 30 days before that. Charts show hours for ranges of two days or less, days up to about four months, and weeks beyond that.

tip

Today is still in progress, so the last bar of a chart is usually shorter than the rest. Pick a **Custom** range that ends yesterday when you want only complete days.

#### Traffic channels[​](#traffic-channels "Direct link to Traffic channels")

Analytics groups every referrer into a channel so you can see at a glance where readers come from.

| Channel              | Includes                                                                                                        |
| -------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Direct**           | Visits with no referrer, such as typed URLs, bookmarks, and many app links.                                     |
| **Search**           | Google, Bing, DuckDuckGo, Yahoo, Ecosia, Brave, Baidu, and Yandex. Shown by engine, such as **Google Search**.  |
| **News aggregators** | Google News, Yahoo News, Flipboard, Apple News, MSN, NewsBreak, and SmartNews. Shown by name.                   |
| **Social**           | Facebook, Instagram, X (Twitter), LinkedIn, Reddit, Threads, Bluesky, Pinterest, TikTok, YouTube, and Nextdoor. |
| **Other sites**      | Every other referring site.                                                                                     |

Subdomains count toward their site, so `m.facebook.com` is Social. News aggregators win over search, so a visit from `news.google.com` is Google News, not Google Search.

#### When data is unavailable[​](#when-data-is-unavailable "Direct link to When data is unavailable")

If the analytics service can't be reached, each affected card shows an **Unavailable** message instead of its numbers. The rest of the page keeps working; reload in a minute to try again.

#### Related[​](#related "Direct link to Related")

* [Dashboard](/product/dashboard.md) — At-a-glance growth metrics on the main dashboard
* [Content](/product/content.md) — The stories Allegro has cataloged, and the engines that recommend them
* [Audience](/product/audience.md) — Browse and filter individual member records


---

### Analytics API and MCP

Every number on the Analytics pages is also available outside the dashboard. A script can read it from the REST API, and an AI assistant such as Claude can read it through the [MCP server](/developer/guides/mcp.md). All three read the same data through the same code. For the same filters and dates, the API, the MCP server, and the dashboard return the same numbers.

You can read everything and create saved reports. Editing and deleting saved reports stays in the dashboard.

#### Giving a key access[​](#giving-a-key-access "Direct link to Giving a key access")

API keys need the **Analytics** read scope, `analytics:read`. Creating saved reports needs the write scope, `analytics:write`. Add it when you [create or edit a key](/product/administration/settings.md) in **Organization Settings → API Keys**. Keys with **Full read access** or **Full access** already include it.

The reader timeline includes a reader's name and email only when the key also has `audience-members:read`. Without it, readers are identified by ID only.

MCP clients need no extra setup. Anyone who can view the Analytics pages can read analytics through the MCP server.

#### What you can read[​](#what-you-can-read "Direct link to What you can read")

The API is organized around the data rather than the pages. Each Analytics page maps to these endpoints, all under `/api/v1/analytics`:

| In the dashboard                            | API endpoint                                     | MCP tool                                                                  |
| ------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------- |
| Event types, filters, properties            | `GET /schema`                                    | `get-analytics-schema-tool`                                               |
| **Pulse**                                   | `GET /realtime`                                  | `get-analytics-realtime-tool`                                             |
| **Events → Page views**                     | `GET /traffic`                                   | `get-analytics-view-tool` with `view: traffic`                            |
| **Events → Time on site**                   | `GET /time-on-site`                              | `get-analytics-view-tool` with `view: time-on-site`                       |
| **Events → Content gates**                  | `GET /gates`                                     | `get-analytics-view-tool` with `view: gates`                              |
| **Events → Sign-ups, Logins, Purchases**    | `GET /sign-ups`, `GET /logins`, `GET /purchases` | `get-analytics-view-tool` with `view: sign-ups`, `logins`, or `purchases` |
| Event counts on the **Events** tabs         | `GET /event-counts`                              | `get-analytics-view-tool` with `view: event-counts`                       |
| **Events → All events** chart and breakdown | `GET /explore`                                   | `get-analytics-view-tool` with `view: explore`                            |
| **Events → All events** event list          | `GET /events`                                    | `list-analytics-events-tool`                                              |
| A story's performance                       | `GET /content?path=/news/story`                  | `get-content-analytics-tool`                                              |
| A reader's timeline                         | `GET /readers/{id}`                              | `get-reader-analytics-tool`                                               |
| **Reports** list                            | `GET /reports`                                   | `list-analytics-reports-tool`                                             |
| A saved report and its result               | `GET /reports/{id}`, `GET /reports/{id}/results` | `get-analytics-report-tool`                                               |
| The report builder's preview                | `POST /query`                                    | `query-analytics-tool`                                                    |

Each built-in report in the reports list names the endpoint that returns its data. The API reference lists every parameter and response field for each endpoint.

#### Creating saved reports[​](#creating-saved-reports "Direct link to Creating saved reports")

A script can save a report with `POST /api/v1/analytics/reports`, and an assistant can save one with `create-analytics-report-tool`. Either way, the report takes a name, an optional description, whether it is pinned to the Pulse, and a definition in the same shape `POST /query` runs. Use the same values the report builder offers: measures, event types, filters, a breakdown, a time bucket, a preset range, and a chart type. The new report appears under **Saved Reports** for the whole team.

Through the API, any key with `analytics:write` can save a report. Through the MCP server, saving a report requires the admin role. (Managing report email subscriptions is the exception — see [Report email subscriptions](#report-email-subscriptions).) A signed-in team member is recorded as the report's creator. A report saved with an organization key has no creator.

#### Report email subscriptions[​](#report-email-subscriptions "Direct link to Report email subscriptions")

An assistant can manage who gets a report by email, the same subscriptions the **Subscribe** dialog sets up in the dashboard. These are available over the MCP server only — the REST API does not expose them.

| MCP tool                                   | What it does                                                                                                         |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| `list-analytics-report-subscriptions-tool` | Lists who gets a report and how often.                                                                               |
| `subscribe-analytics-report-tool`          | Emails a report to an address, `weekly` or `monthly`. Subscribing an address that already gets it changes how often. |
| `unsubscribe-analytics-report-tool`        | Stops emailing a report to one address. Requires `confirm: true`.                                                    |

For `list-analytics-report-subscriptions-tool` and `subscribe-analytics-report-tool`, name the report with `report_id` for a saved report or `built_in_report` for a built-in one. `unsubscribe-analytics-report-tool` instead takes the subscription's own `id`, which `list-analytics-report-subscriptions-tool` returns. Permissions mirror the dashboard: anyone who can view the report may subscribe their own address, while admins and members may subscribe or remove others. See [Report emails](/product/analytics/reports.md#report-emails) for the dashboard side and the schedule.

#### Filters[​](#filters "Direct link to Filters")

The endpoints and tools accept the same filters as the Analytics page header:

| Filter         | What it does                                                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `range`        | A preset window ending today: `7d`, `30d` (the default), `90d`, or `1y`.                                                                               |
| `start`, `end` | Custom dates (`2026-10-01`) in your organization's time zone. As in the dashboard, the end can't be later than today and the window is at most a year. |
| `property`     | Limits the data to one property.                                                                                                                       |
| `product`      | Limits purchase and conversion data to one product.                                                                                                    |
| `include`      | Returns only some sections of a larger response, for example `include=counts,spiking` on the Pulse.                                                    |

Numbers are always compared with the previous window of the same length, as they are in the dashboard. Every response says which dates it covers, which window it was compared against, and when it was generated.

Saved reports run over their own date range unless you pass `range` or `start` and `end`. With the API you can run a saved report over any dates, even though the dashboard only offers its preset ranges.

#### Limits and errors[​](#limits-and-errors "Direct link to Limits and errors")

Each API key or MCP connection can make **60 analytics requests a minute**. The API and the MCP server share cached results with the dashboard, so repeated requests for the same data come back quickly.

| Response                         | Meaning                                                                                                  |
| -------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `503` `ANALYTICS_UNAVAILABLE`    | The analytics service didn't answer. Retry after the number of seconds in the `Retry-After` header (60). |
| `503` `ANALYTICS_NOT_CONFIGURED` | Analytics isn't set up for your organization. Retrying won't help.                                       |
| `422` `ANALYTICS_REJECTED_INPUT` | The analytics service rejected the filters. Check them against `GET /schema`.                            |
| `422` validation error           | A filter or section name isn't one of the allowed values.                                                |
| `429`                            | Over the 60-a-minute limit.                                                                              |

A story whose page hasn't been indexed yet isn't an error. It returns its numbers with empty `details`, as the dashboard does.

Results from the MCP server are shorter

To keep answers small enough for an assistant, MCP tools return at most 25 rows in each ranked list, such as top stories or referrers. Each list that was cut includes a note with the full count. Charts over time are always complete. Use the API when you need every row.


---

### Analytics Assistant

The assistant answers questions about your analytics from whichever Analytics page you're on. Ask "all logins that came from social in the last 30 days" and it finds the answer, tells you the key numbers, and changes the page so the page itself shows the result. When you want to keep something, ask it to make a report and it opens the report builder already filled in.

#### Open the assistant[​](#open-the-assistant "Direct link to Open the assistant")

Click **Assistant** in the header of any Analytics page: Pulse, any Events view, Reports, a saved report, the report builder, or a reader's page. The panel opens on the right and the rest of the app makes room for it.

The panel stays open, and keeps the conversation, as you move between Analytics pages in the same browser tab. An answer still being written keeps going while you change pages. **New conversation** starts over; closing the tab ends it.

If you move to a different Analytics page and come back to the conversation, the panel offers **Start a new conversation**, and the assistant suggests the same when your next question doesn't follow on from the earlier ones. Changing filters on the same page doesn't count as moving.

#### What it can do[​](#what-it-can-do "Direct link to What it can do")

| You ask                                                                            | The assistant                                                                                    |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| A question about the page you're on ("what stands out here?", "only show members") | Reads the page's current filters, answers, and adjusts them                                      |
| A question with several conditions ("logins from social in the last 30 days")      | Sets the event type, filters, and range on the Events page so the page lists the matching events |
| A loose term like "social", "search", or "newsletter"                              | Looks up the real sources your site records and tells you which ones it used                     |
| An ambiguous question ("top content")                                              | Picks a sensible measure, says which, and offers the alternatives                                |
| "What data do we have about …?"                                                    | Lists the event types, measures, and dimensions your site actually records                       |
| Something your data can't answer (email open rate)                                 | Says plainly what isn't tracked and offers the closest question it can answer                    |
| "Make this a report"                                                               | Opens the report builder filled in with a name, description, and the query                       |

Every change it makes to the page is listed in the panel with an **Undo** that returns you to the page you were on before. If you change a filter yourself, the assistant works from your version on the next question.

#### Reports[​](#reports "Direct link to Reports")

The assistant never saves a report. Asking it to make a report opens the report builder with the fields filled in; the ones the assistant set are outlined until you edit them. Check the preview, then click **Save report**.

On a saved report, asking for a change ("show this weekly") opens that report's edit builder with the change applied. Nothing changes until you save.

Date ranges stay relative: a report drafted over "last 30 days" always shows the latest 30 days. The assistant works with the same ranges as reports (7 days, 30 days, 90 days, 12 months). For anything else, such as "last month", it uses the nearest one and says which.

Members with the Viewer role can ask questions and change what they see, but the assistant can't draft or change reports for them.

#### Privacy[​](#privacy "Direct link to Privacy")

The assistant uses the same data and limits as the Analytics pages. It never receives anything that identifies an individual reader: event lists reach it without reader IDs, email addresses, IP addresses, or user agents, and on a reader's page it only knows it's on a reader page.

#### Limits and availability[​](#limits-and-availability "Direct link to Limits and availability")

Each person can send 20 questions a minute and 200 an hour. Past that, the assistant asks you to wait.

The assistant is on for every organization by default. It can be turned off for an organization with the **Analytics AI assistant** feature flag.

If analytics data is temporarily unavailable, the assistant says it couldn't run the question and leaves the page as it was.


---

### Events

Events is where you look at a period rather than the last hour. Open it from **Analytics → Events** in the sidebar. A row of tabs across the top switches between the explorer and six views built for the events that matter most:

| Tab               | What it covers                                                                 |
| ----------------- | ------------------------------------------------------------------------------ |
| **All events**    | Every tracked event, filterable, with a breakdown by any field.                |
| **Page views**    | How much your site is read, when, and what.                                    |
| **Time on site**  | How long readers stay.                                                         |
| **Content gates** | How often readers meet a gate, and how often that leads to a login or sign-up. |
| **Sign-ups**      | Readers who became members, and what they saw first.                           |
| **Logins**        | Members signing back in, and where they do it.                                 |
| **Purchases**     | Revenue from completed checkouts.                                              |

Each tab shows its event count for the selected range. The [date range](/product/analytics.md#date-range) control sits at the right of the tabs, and your range, [property](/product/analytics.md#property), and [product](/product/analytics.md#product) choices carry over as you switch tabs.

Every view compares its headline numbers with the period just before the range, marked **vs previous period**.

#### All events[​](#all-events "Direct link to All events")

The explorer lists every event Allegro has recorded, newest first, and lets you narrow it down until you find the pattern or the single event you're after.

![The Events explorer: event type and filter controls, a tile per event type, Matching Events stacked by type, and Break Down By referrer](/assets/images/events-1ebd9977fee6f7dfdd440d2bb6a9e3f5.png)

##### Choosing events[​](#choosing-events "Direct link to Choosing events")

Under **Event types**, add the events you want to see. Suggestions come from the events recorded in the range, and you can type any custom event name your site sends, such as `video_play`. With nothing selected you see **All events**.

The tiles below the controls show the busiest event types. Click a tile to add or remove that type.

##### Filtering[​](#filtering "Direct link to Filtering")

Click **Add filter** under **Where** to keep only events that match a field. Pick the field, a match (**is**, **is not**, **contains**, or **does not contain**), and a value. You can add up to 10 filters; click a filter's chip to remove it.

| Area        | Fields you can filter and break down by                                    |
| ----------- | -------------------------------------------------------------------------- |
| Event       | Event type                                                                 |
| Page        | Page path, Page title, Section, Content type, Hostname, Property           |
| Source      | Referrer, UTM source, UTM medium, UTM campaign                             |
| Interaction | Interaction type, Gate type, Object type, Object ID                        |
| Reader      | Device, Browser, Operating system, Reader status (registered or anonymous) |

##### Breaking down[​](#breaking-down "Direct link to Breaking down")

**Matching Events** charts the events over the range, stacked by type. **Break Down By** ranks the top values of any field, **Referrer** by default. Click **Only** beside a value to add it as a filter, which is the quickest way to drill from "where is traffic coming from" to "what did readers from that site do".

##### Event Stream[​](#event-stream "Direct link to Event Stream")

The **Event Stream** lists matching events newest first, 50 at a time, showing the time, event, page, source, and whether the reader was registered or anonymous. Bots are excluded. Use **Older events** to page back and **Back to newest** to return.

Turn on **Live** to refresh the stream and tiles every 15 seconds.

##### Event details[​](#event-details "Direct link to Event details")

Click any event to open its details.

![The details of a page view: reader, page, source, interaction, client, and raw data](/assets/images/event-drawer-66bb0244e236a87aab734e5ba5df2f81.png)

The panel shows the reader, the page, the source, any interaction or gate involved, the browser and device, and the raw event data. From there you can:

* **Show this session** to filter the explorer to every event in the same visit. A banner reads **Showing one session**; click **Show all sessions** to go back.
* Open the [reader timeline](#reader-timeline) for a registered reader.
* Open the [story view](/product/content/story.md) for a page event.

##### Turning a search into a report[​](#turning-a-search-into-a-report "Direct link to Turning a search into a report")

Once the explorer shows what you want to keep, click **Turn into report**. The [report builder](/product/analytics/reports.md#building-a-report) opens with your event types, filters, and breakdown already filled in, counted per day.

#### Page views[​](#page-views "Direct link to Page views")

![The Page views view over a custom range, with page views, sessions, readers, and logged-in share all up on the previous period](/assets/images/page-views-e113f9cb48a7b888eed4c5be86944b7a.png)

| Stat                | What it counts                                |
| ------------------- | --------------------------------------------- |
| **Page views**      | Every page view in the range.                 |
| **Sessions**        | Visits, however many pages each one viewed.   |
| **Readers**         | Unique readers.                               |
| **Logged-in share** | The share of page views by signed-in members. |

Below the stats:

* **Page Views** charts views per hour, day, or week.
* **When Readers Show Up** is a heat map of average page views by weekday and hour over the last four weeks, in your organization's time zone. Use it to time newsletters and publishing.
* **Performance by Section** lists each section's pages, views, engaged time, and average engaged time, with a trend line and the change against the previous period.
* **Top Content by Engaged Time** ranks stories by total engaged time. Click a story to open its [story view](/product/content/story.md).

![When Readers Show Up as a weekday-by-hour heat map, and Performance by Section with every section trending up](/assets/images/reading-hours-ecf872a8d176abb0bcca2b92760d1166.png)

#### Time on site[​](#time-on-site "Direct link to Time on site")

Time on site is measured from the heartbeat each page sends while it's open and in front of the reader, so time in a background tab doesn't count.

![The Time on site view: engaged time per session, median session, sessions, and bounce rate, with Engaged Time per Session and Session Length](/assets/images/time-on-site-764e6708c30da06471d3c581e8173178.png)

| Stat                         | What it counts                                                                         |
| ---------------------------- | -------------------------------------------------------------------------------------- |
| **Engaged time per session** | Average engaged time across sessions.                                                  |
| **Median session**           | The middle session, which a few very long visits can't skew.                           |
| **Sessions**                 | Visits in the range.                                                                   |
| **Bounce rate**              | Sessions under 10 seconds on a single page. Lower is better, so a drop shows in green. |

**Session Length** splits sessions into bands from **Bounce** to **10m+**, and **Engaged Time by Story** ranks stories against the site average.

#### Content gates[​](#content-gates "Direct link to Content gates")

![The Content gates view over a custom range: gate views, sessions that met a gate, converted sessions, and conversion rate, with gate views by interaction type](/assets/images/gates-a0cefc53b511d1b95a0f77c765bba542.png)

| Stat                         | What it counts                                                    |
| ---------------------------- | ----------------------------------------------------------------- |
| **Gate views**               | Every time a gate was shown.                                      |
| **Sessions that met a gate** | Visits that saw at least one gate.                                |
| **Converted sessions**       | Visits where a reader met a gate and then logged in or signed up. |
| **Conversion rate**          | Converted sessions as a share of sessions that met a gate.        |

**Gate Views** stacks views by interaction type, such as meter and roadblock. **By Gate Type** compares the conversion of each type. **Stories Behind Gate Conversions** shows where readers met the gate that converted them, and **Latest Gate Events** lists the 10 most recent gates; click one for its details.

#### Sign-ups[​](#sign-ups "Direct link to Sign-ups")

![The Sign-ups view: sign-ups up on the previous period, the Reader to Member funnel, and sign-ups per day by gate](/assets/images/sign-ups-de64a3f004e82cd924999845a0465786.png)

The stats show **Sign-ups**, **Magic links requested**, and **Readers who met a gate**. Below them:

* **Reader to Member** is a funnel of unique readers: read a story, met a gate, requested a magic link, and signed up, with each step's share of readers.
* **Sign-ups per Day** stacks each day's sign-ups by the gate the reader saw before signing up.
* **Content That Converts** lists the pages sign-ups happened on.
* **By Member Level** shows the membership level held when signing up.

#### Logins[​](#logins "Direct link to Logins")

The stats show **Logins** and **Members who logged in**. Below them, **Logins** charts the daily count, **Who Logs In** splits logins by member level, **Device** splits them by mobile, desktop, and tablet, and **Where Members Log In** lists the pages they logged in from.

#### Purchases[​](#purchases "Direct link to Purchases")

The stats show **Revenue**, **Purchases**, and **Average order**. **Revenue** charts completed revenue over time, **By Status** counts every checkout started in the range by its outcome, and **Revenue by Product** breaks completed purchases down by product, with purchases, revenue, and average price.

#### Reader timeline[​](#reader-timeline "Direct link to Reader timeline")

The reader timeline follows one registered reader across their visits. Open it from the details of any event by a registered reader in the [event details](#event-details).

The header shows the reader's name and email, when Allegro first saw them, and their page views, number of devices, and primary device. **Open in Audience** opens their [member record](/product/audience.md).

The **Sessions** list on the left shows each visit with its start time, number of events, source, and device, and notes the visits where the reader signed up or logged in. Select a visit to see its events in order:

* Page views show the page title and where the reader came from.
* A sign-up shows how many gates and page views came before it.
* Other events show their interaction and page.

Click **Show these in Events** to open the selected visit in the explorer. The timeline covers the reader's 500 most recent events.

#### Related[​](#related "Direct link to Related")

* [Analytics](/product/analytics.md) — The Pulse, filters, and traffic channels
* [Reports](/product/analytics/reports.md) — Save any view of events as a shared report
* [Story view](/product/content/story.md) — One story in depth


---

### Milestones

A milestone is a dated note: a product launch, a site relaunch, the day a national newspaper featured you. Every analytics chart that covers that date shows it, so a spike or a dip months later comes with its reason attached.

![Audience growth on the dashboard with milestone markers under three bars and the tooltip open on Oct 27](/assets/images/milestone-chart-40b48c086c86ab418e29315606549d1c.png)

#### Where milestones appear[​](#where-milestones-appear "Direct link to Where milestones appear")

A small dot under a chart's bar or point marks each milestone. Hover the bar to see the milestone's title, note, and link in the tooltip, alongside the numbers. When several milestones share a bar, the tooltip lists them all.

Milestones appear on:

* The **Dashboard**'s Audience Growth and Logins charts
* Every **Events** chart, such as Page views, Sign-ups, and All events
* Saved reports and the report builder's preview
* A story's performance chart
* An interaction's report

The **Pulse** doesn't show milestones, since it only covers the last hour.

On a chart grouped by week or month, a milestone marks the bar that contains its date. On an hourly chart, it marks the first hour of its day. If a chart has no bar for that day, because nothing happened, the chart shows no marker for it.

Screen readers get the same information: the chart's data table lists each row's milestones.

#### Adding a milestone[​](#adding-a-milestone "Direct link to Adding a milestone")

Go to **Settings → Milestones** and click **Add milestone**.

![The Add milestone drawer with date, title, note, and link fields](/assets/images/milestone-drawer-c100dfd86254ed7e690dd185ee0b300c.png)

| Field          | What it sets                                                                                  |
| -------------- | --------------------------------------------------------------------------------------------- |
| **Date**       | Required. A single day, past or future, in your organization's timezone.                      |
| **Title**      | Required. Up to 120 characters. Shown on the chart tooltip and in the list.                   |
| **Note**       | Optional. Up to 1,000 characters of context, shown under the title in the tooltip.            |
| **Link**       | Optional. An `http` or `https` address, such as the article that featured you.                |
| **Properties** | Optional. Limits the milestone to some properties. Leave all unchecked to show it everywhere. |

To change or remove a milestone, click it in the list. **Delete milestone** is at the bottom of the drawer.

Only admins can add, edit, or delete milestones. Everyone in your organization sees them on charts.

#### Limiting a milestone to properties[​](#limiting-a-milestone-to-properties "Direct link to Limiting a milestone to properties")

If your organization runs more than one property, a milestone can belong to some of them. A redesign of one site, for example, shouldn't mark the charts of another.

| Charts filtered to                     | Milestones shown                                               |
| -------------------------------------- | -------------------------------------------------------------- |
| The whole organization (no filter)     | Every milestone                                                |
| A property the milestone is limited to | The milestone, plus every milestone with no properties checked |
| Any other property                     | Only milestones with no properties checked                     |

Deleting a property also deletes the milestones limited to that property alone. Milestones that list other properties too keep those.

#### Milestones in the assistant, API, and MCP[​](#milestones-in-the-assistant-api-and-mcp "Direct link to Milestones in the assistant, API, and MCP")

The [analytics assistant](/product/analytics/assistant.md) sees the milestones inside the range it's looking at, so it can point out when a change in the numbers lines up with one.

Milestones can also be managed from your own systems:

| Action             | API endpoint                 | MCP tool                |
| ------------------ | ---------------------------- | ----------------------- |
| List milestones    | `GET /v1/milestones`         | `list-milestones-tool`  |
| Add a milestone    | `POST /v1/milestones`        | `create-milestone-tool` |
| Read one milestone | `GET /v1/milestones/{id}`    |                         |
| Edit a milestone   | `PUT /v1/milestones/{id}`    | `update-milestone-tool` |
| Delete a milestone | `DELETE /v1/milestones/{id}` | `delete-milestone-tool` |

API keys need the `milestones:read` scope to list and read, and `milestones:write` to change them. The MCP analytics tools that return a chart's data include the milestones in its range as well. See [Analytics API and MCP](/product/analytics/api-and-mcp.md) for setting up keys.


---

### Reports

Reports collects every view Analytics offers in one place, plus the reports your team builds. Open it from **Analytics → Reports** in the sidebar.

![The Reports page: a saved report card, and the built-in reports filtered by area](/assets/images/reports-5877271dbf31f694f807ba77875af341.png)

#### Built-in reports[​](#built-in-reports "Direct link to Built-in reports")

**Built-in Reports** lists the views Analytics serves for every site, such as **Real-time pulse**, **When readers show up**, and **Gate-to-login conversion**. Each one links to the page that shows it. Use the area tabs (**Page views**, **Content gates**, **Sign-ups**, and so on) or **Search reports** to find one. The search also filters your saved reports.

Built-in reports can't be edited or deleted.

#### Saved reports[​](#saved-reports "Direct link to Saved reports")

**Saved Reports** holds the reports your team has built. Each card shows the report's name, its description or a one-line summary, who made it, and when it was last updated. Pinned reports come first.

Saved reports are shared: everyone in your organization can open every one.

| Role   | Open reports | Create, edit, and delete reports |
| ------ | ------------ | -------------------------------- |
| Admin  | ✓            | ✓                                |
| Member | ✓            | ✓                                |
| Viewer | ✓            |                                  |

Admins and members can edit or delete any saved report, not only their own.

#### Building a report[​](#building-a-report "Direct link to Building a report")

Click **New report**, or start from what you're already looking at:

* **Turn into report** in the [Events explorer](/product/analytics/events.md#all-events) brings your event types, filters, and breakdown with it.
* **Build a report** on a [story view](/product/content/story.md) starts from that story's page views by referrer.

![The report builder: logins broken down by device per day over the last 30 days, with a live preview chart and table](/assets/images/report-builder-5c88ebec1e5c4bd0bd53ea35636d3850.png)

The form is on the left and a live preview on the right, which updates as you change any field.

| Field             | What it sets                                                                                                                                                                                                    |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**          | Required. Shown on the report card and page.                                                                                                                                                                    |
| **Description**   | Optional. Shown in place of the generated summary.                                                                                                                                                              |
| **Measure**       | What to count: **Count of events**, **Unique sessions**, **Unique readers**, **Unique registered readers**, **Engaged time**, or **Average engaged time**.                                                      |
| **Of events**     | The event types to include, up to 20. Leave it empty for all events. Custom event names work too.                                                                                                               |
| **Where**         | Up to 10 filters, with the same fields and matches as the [Events explorer](/product/analytics/events.md#filtering).                                                                                            |
| **Break down by** | **Nothing**, or any field from the explorer. The top 8 values each get their own series.                                                                                                                        |
| **Per**           | **Hour**, **Day**, **Week**, or **Whole range** for a single total per group.                                                                                                                                   |
| **Over**          | **Last 7 days**, **Last 30 days**, **Last 90 days**, or **Last 12 months**.                                                                                                                                     |
| **Show as**       | **Bar chart and table**, **Area chart and table**, **Line chart and table**, or **Table only**. An area chart stacks the groups so you can see each one's share; a line chart draws each group on its own line. |
| **Pin to Pulse**  | Adds a link to the report on the Pulse for everyone on the team.                                                                                                                                                |

Click **Save report** to save it and open it.

note

Saved reports always cover a rolling window, so a report built over **Last 30 days** shows the latest 30 days every time you open it. Custom date ranges aren't available in reports.

##### Pin to Pulse[​](#pin-to-pulse "Direct link to Pin to Pulse")

Pinned reports appear in a **Pinned Reports** card on the [Pulse](/product/analytics.md#the-pulse), so the views your team checks every day are a click away. A **Pinned to Pulse** badge marks them on their own page.

#### Viewing a report[​](#viewing-a-report "Direct link to Viewing a report")

A report's page shows its name, description, who created it, and a **Results** card with the chart and a table of each group's total for the report's window, in your organization's time zone.

Admins and members also see **Edit report** and **Delete**. Deleting asks you to confirm, because everyone in the organization loses access to the report.

#### Report emails[​](#report-emails "Direct link to Report emails")

Anyone who can view a report can have it delivered by email on a schedule, so the numbers your team watches arrive without anyone opening the dashboard. Both saved reports and most built-in reports can be emailed; the real-time pulse, heat maps, and open-ended explorations can't, because they don't reduce to a periodic summary.

Each scheduled email is a single digest with a section for every report you get at that frequency — not a separate email per report. A section shows the report's headline total and how it changed against the previous period, then a short breakdown or trend. The figures are counted in your organization's time zone, so they match the dashboard.

##### Subscribing[​](#subscribing "Direct link to Subscribing")

Open a saved report and select **Subscribe**, or use the **Subscribe** button on an emailable built-in report in the Reports list. The dialog offers:

| Choice            | What it does                                                                                                                                                           |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **How often**     | **Weekly** (sent Mondays at 6am in your organization's time zone, covering the week before) or **Monthly** (the first Monday of the month, covering the month before). |
| **Send it to me** | Subscribes your own address at the chosen frequency. If you already get the report, the button switches your frequency instead.                                        |
| **Also send to**  | Adds another address — a colleague or a manager, say. Only admins and members see this.                                                                                |

The dialog lists everyone who gets the report, each with their frequency and who added them, and a control to remove an address.

| Role   | Subscribe yourself | Add or remove other addresses |
| ------ | ------------------ | ----------------------------- |
| Admin  | ✓                  | ✓                             |
| Member | ✓                  | ✓                             |
| Viewer | ✓                  |                               |

##### Managing your subscriptions[​](#managing-your-subscriptions "Direct link to Managing your subscriptions")

Open **Settings → Report emails** to see every report you get in the current organization. From there you can change a report's frequency or unsubscribe.

Every email also carries an unsubscribe link. A team member's email links back to the **Report emails** settings page. An outside address gets a one-click unsubscribe that, after a single confirmation, stops **every** report sent to that address at that frequency in this organization — not only the report in the message. To drop one report but keep the rest for that address, remove it from the report's **Subscribe** dialog instead.

note

Removing a person from the organization ends every subscription tied to them — their own, any address they added, and any report sent to their email. If a report's numbers can't be retrieved when an email is prepared, that report is left out of that run rather than sent with incomplete figures.

#### Related[​](#related "Direct link to Related")

* [Analytics](/product/analytics.md) — The Pulse and shared filters
* [Events](/product/analytics/events.md) — Explore events before saving them as a report


---

### Audience

The Audience is your contact database. Every person who interacts with your site through Allegro is recorded here as a **member**. Use the Audience section to browse, search, and manage everyone who has signed up, logged in, or been identified on your site.

![Audience](/assets/images/audience-bbee75dff39ec9eadd00189d8dd5030e.png)

#### How members are created[​](#how-members-are-created "Direct link to How members are created")

Most members are created for you. Allegro creates a member record automatically when someone:

* **Signs up** through a registration form or reg wall on your site.
* **Logs in** with a magic link or social login (Google, Apple, etc.).
* **Is identified** by your backend using an external user ID.

If someone signs up or logs in with an email that already belongs to an existing member, Allegro links the activity to that member instead of creating a duplicate.

You can also [add a member by hand](#adding-a-member) from the dashboard — useful when you already know someone's email and want a profile ready before they first sign in.

##### Adding a member[​](#adding-a-member "Direct link to Adding a member")

If your role can manage the audience, an **Add Member** button appears at the top of the Audience page. (Viewers don't see it.) Click it to open the **Add Audience Member** dialog:

* **Email** (required) — must be a valid address that isn't already registered to an active member. If it is, Allegro shows *"That email address is already registered to another audience member."* and keeps the dialog open.
* **Name** (optional) — leave it blank to add the member by email alone.

Click **Add Member** to create the profile and open it. A member added this way starts out **unverified** — toggle **Email verified** on their profile once you've confirmed the address. The creation is recorded in the member's [activity history](#activity-history).

Adding a previously deleted member

If the email belongs to a member you earlier [deleted](#deleting-a-member), adding it **restores** that member instead of starting a new record. Their existing name is kept unless you provide a new one, and the restore is recorded in the member's activity history.

#### Browsing members[​](#browsing-members "Direct link to Browsing members")

The Audience index lists every member in your organization, sorted by most recently added. Each row shows the member's avatar, display name, email address, and verification status.

Next to the name, a small icon shows how the member signed up — **Google**, **Facebook**, or **Apple** when they used social login, or a globe icon for any other provider. Hover over an icon to see a **Signed up with {Provider}** tooltip. Members who only ever used email or magic links show no icon, and a member who linked more than one provider shows an icon for each.

##### Searching members[​](#searching-members "Direct link to Searching members")

Use the search bar above the list to find a member by **name**, **email address**, or **member ID**. Name and email match on any part of the value, so a partial term works. A member ID must be the member's full ID — paste the exact value (for example, from a URL or an export) to jump straight to that member.

Search combines with the filters below, and the **Export** button exports exactly the members that match your current search and filters.

##### Filtering by verification status[​](#filtering-by-verification-status "Direct link to Filtering by verification status")

Use the filter at the top of the list to narrow results by email verification status: **All**, **Verified**, or **Unverified**.

##### Filtering by Product[​](#filtering-by-product "Direct link to Filtering by Product")

Use the filter at the top right of the table to narrow audience members by those who have active entitlements to a specific product.

##### Exporting members[​](#exporting-members "Direct link to Exporting members")

Use the **Export** button to export the members that match your current search and filters as a CSV. The export is generated in the background; Allegro emails you a download link when it's ready, and the file is also available on the [Exports](/product/exports.md) page for 7 days. Alongside each member's core details, the file summarizes their active products and entitlements, purchases, login providers, and every [user attribute](/product/audience/user-attributes.md) your organization has defined. See [Exports](/product/exports.md#audience-member-columns) for the full column list.

#### Viewing a member profile[​](#viewing-a-member-profile "Direct link to Viewing a member profile")

Click any row to open that member's profile. The header shows:

* **Avatar** — auto-generated from their email via [Gravatar](https://gravatar.com).
* **Display name** — the member's name, or their email if no name has been set.
* **Email** — their email address.
* **Email verified** — whether they have completed email verification.
* **Last seen** — how long ago they last generated an event (e.g. "3 days ago"), or "Never" if no events exist yet.

The profile is organized into tabs:

| Tab                    | Contents                                                                                                                               |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Overview**           | Profile summary, key dates, and the properties the member has joined                                                                   |
| **Profile**            | The organization's [user attributes](/product/audience/user-attributes.md) for this member, grouped by category and editable by admins |
| **Activity**           | Full event history, newest first                                                                                                       |
| **Entitlements**       | Active and past entitlements for this member                                                                                           |
| **Purchases**          | Completed purchases, with refund actions for eligible purchases                                                                        |
| **Sync & Profiles**    | External data provider sync status and manual re-sync controls                                                                         |
| **Data**               | Raw member data and external profile records                                                                                           |
| **Sessions**           | Device sessions for this member, newest first                                                                                          |
| **Webhook deliveries** | Webhooks sent about this member, newest first (admins only)                                                                            |

Each tab has its own URL (e.g. `/audience/{id}/activity`) so you can link directly to a specific view or use the browser back/forward buttons to navigate between tabs.

#### Properties joined[​](#properties-joined "Direct link to Properties joined")

The **Overview** tab lists every [property](/product/administration/properties.md) the member has joined. A member joins a property the first time they sign in on it, so the list shows where across your organization the person has actually been active — not just the properties they could access.

Each entry shows the property name and when the member joined it:

* **Signed up** — that first sign-in is what created the member's account.
* **Joined** — an existing member signed in on the property for the first time.

If the member hasn't joined any property yet, the list shows **None**.

note

A member is still the same person across every property (members, entitlements, and purchases are shared organization-wide). This list only records *which* properties they have signed in on, and when.

#### Activity history[​](#activity-history "Direct link to Activity history")

The **Activity** tab shows the member's full event history, listed newest first. Events load as you scroll.

Each entry shows what the member did (e.g. "signed up", "viewed page"), the relevant subject where applicable (e.g. a page URL), and how long ago it happened.

Click any activity row to open a detail modal showing all raw event attributes recorded for that event.

note

Events are tracked automatically by the Allegro SDK and your site's instrumentation. You don't manage event types from the admin UI — they are recorded as members interact with your site.

Retention

Activity history is kept for one month. Events older than that are removed automatically.

#### Purchases[​](#purchases "Direct link to Purchases")

The **Purchases** tab lists every completed purchase for the member, sorted by most recent. Each row shows the plan name, the amount charged, and the date. Click a row to open the full purchase detail.

Pending or abandoned checkout sessions are not shown here — only purchases that reached a completed state appear in this list.

To browse, filter, and export purchases across your whole organization, use the [Purchases](/product/entitlements/purchases.md) page instead.

##### Refunding a purchase[​](#refunding-a-purchase "Direct link to Refunding a purchase")

Admins can issue a full refund for any completed purchase directly from the purchase detail page:

1. Open the **Purchases** tab on a member's profile and click the purchase you want to refund.
2. Click **Refund** (only visible when the purchase status is **Completed**).
3. A confirmation dialog appears. By default, the member keeps their access — toggle **Revoke member's access** if you also want to remove the associated entitlement.
4. Confirm the refund. The purchase status updates to **Refunded**, the refund ID appears in the **Details** section of the purchase, and the refund is recorded in the purchase's **Activity** timeline.

Once refunded, the Refund button is no longer available for that purchase.

note

Refunds are processed through your connected payment provider. Make sure a payment provider is connected in **Organization Settings → Payment Providers** before attempting a refund.

#### Entitlements[​](#entitlements "Direct link to Entitlements")

The **Entitlements** tab shows every entitlement the member holds — both active and past. Each entry shows the product name, start date, end date (if any), and a status badge: **Active**, **Scheduled**, **Revoked**, or **Expired**. A revoked entitlement shows when it was revoked in place of its end date.

From this tab you can also grant a new entitlement or revoke an existing one. See [Entitlements](/product/entitlements.md) for what each status means and full details.

#### Sessions[​](#sessions "Direct link to Sessions")

The **Sessions** tab lists the device sessions recorded for the member, newest first. A session is created whenever the member is identified on your site, requests or validates a magic link, exchanges a checkout token, or has a session generated for them from the admin.

Each row shows:

* **Location** — the approximate city and country derived from the session's IP address, or **Unknown location** when no IP was captured.
* **Status** — an **Authenticated** badge when the session belongs to a logged-in member, or **Unauthenticated** when it does not.
* **Created** — when the session was first recorded.

If the member has no recorded sessions yet, the tab shows **No sessions found**.

#### Sync status[​](#sync-status "Direct link to Sync status")

The **Sync** tab shows each registered external data provider and the last time it was synced for this member. Use **Re-sync now** to trigger an immediate sync for any provider without waiting for the next scheduled run.

Expand a provider to see the full external profile Allegro stored for this member. To drill into a large profile, hover the JSON and click the search icon to open a **filter bar**, then enter a path to show just the value you want:

* Use dot notation for nested fields (`address_primary.city`) and array indexes (`pledges.0.amount`).
* Use `*` as a wildcard to match every item in an array (`pledges.*.amount`).

When a path matches, only the matched value is shown (with a result count for array matches); when it doesn't, a **No match for …** line appears. The active path stays visible as a chip in the header even when the row is collapsed, and the copy button copies exactly what's displayed. Press `Esc` to clear the filter.

For details on how sync providers work, see the [Audience Member Sync](/developer/platform/integrations/audience-member-sync.md) platform guide.

#### Webhook deliveries[​](#webhook-deliveries "Direct link to Webhook deliveries")

The **Webhook deliveries** tab lists every webhook Allegro sent about this member, newest first, so you can see what was delivered, when, and whether it worked — without opening each webhook's own log. The tab is admin-only (the same permission that manages [webhooks](/developer/webhooks/overview.md)).

Each row shows:

* The delivery **status** and the HTTP **response code** returned by your endpoint.
* The **event type** that triggered the delivery.
* The **webhook** it was sent to — click the name to open that webhook's settings.
* An **attempts** count when a delivery was retried.
* **When** it was sent.

Click a row to open the delivery detail, with the full payload and response. Click **Load more** to page through older deliveries. If no webhook has fired for this member yet, the tab shows **No webhook deliveries**.

note

Deliveries are linked to a member from when this feature shipped onward, so deliveries sent before then aren't listed. Entries age out with the rest of the webhook delivery log.

#### Editing a member[​](#editing-a-member "Direct link to Editing a member")

On a member's profile page you can:

* **Edit the email address.** Click the pencil icon next to the member's email to open the **Edit Email Address** dialog, enter the new address, and save. The address must be a valid email and must not already belong to another member in your organization — if it does, Allegro shows *"That email address is already registered to another audience member."* and keeps the current value. Changing the email leaves the member's verification status untouched.
* **Edit the name.** Click the pencil icon next to the member's name — shown whether a name is set or the profile reads **No name provided** — to open the **Edit Name** dialog, enter a name, and save. Save it blank to clear the name. Names don't have to be unique. The change is recorded in the member's [activity history](#activity-history) with the old and new value.
* **Toggle email verification.** Flip the **Email verified** switch and save.

note

A member can also set their own name from your site through the Allegro SDK. The admin edit here and the member's own updates write to the same name.

#### Deleting a member[​](#deleting-a-member "Direct link to Deleting a member")

To remove a member, open their profile and choose the delete action. You'll be asked to confirm first. A deleted member drops out of your audience list, exports, and the APIs, and no longer counts toward your dashboard figures.

Deleting can be undone

Deleting a member doesn't erase them. If the same email address is later [added](#adding-a-member) by hand — or that person signs up or logs in again — Allegro restores the original profile, along with the data attached to it, rather than creating a new record.

#### Related[​](#related "Direct link to Related")

* [Authentication](/product/audience/authentication.md) — How members authenticate with magic links and OAuth
* [Event Tracking guide](/developer/guides/event-tracking.md) — How events are sent from your site to Allegro


---

### Audience Member Authentication

Allegro handles sign-in for your audience so they never need to create or remember a password. Members authenticate with **magic links** (a one-click email login), **one-time codes** (a six-digit code emailed to them), or **social login** through providers like Google, Apple, and Facebook.

The goal is frictionless access — your audience gets in quickly, and you don't have to worry about password resets or credential management.

#### How It Works[​](#how-it-works "Direct link to How It Works")

When a member signs in, Allegro creates a secure session for their device. That session keeps them authenticated as they interact with your content. No passwords are stored, and sessions are managed entirely by Allegro on your behalf.

#### Magic Links[​](#magic-links "Direct link to Magic Links")

Magic links let members sign in with just their email address.

1. The member enters their email
2. Allegro sends an email containing a one-click login link
3. The member clicks the link and is immediately signed in
4. A secure session is created for their device

If the link expires before the member clicks it, they can request a new one.

tip

Magic links are the simplest way to authenticate your audience. There is nothing to configure — they work out of the box for every tenant.

#### One-Time Codes[​](#one-time-codes "Direct link to One-Time Codes")

One-time codes are the same idea as magic links, but the member types a code instead of clicking a link.

1. The member enters their email
2. Allegro emails them a six-digit code
3. The member types the code back into the sign-in form
4. Once the code is verified, a secure session is created for their device

The key difference is that the code is entered on the **same device** that requested it, so sign-in finishes right away without switching to an email app or waiting for a link to open. This is often a smoother experience on phones and in embedded contexts, and it works well when opening a link would break the flow (for example, inside an in-app browser).

Like magic links, one-time codes require no configuration and are available for every tenant. A few behaviors are worth knowing when you support members:

| Behavior            | Detail                                                                                |
| ------------------- | ------------------------------------------------------------------------------------- |
| Code lifetime       | Each code is valid for 30 minutes.                                                    |
| Requesting a resend | Requesting a new code invalidates the previous one — only the most recent code works. |
| Rate limiting       | A member can request at most three codes per minute for the same email.               |
| Incorrect attempts  | Too many wrong entries locks the code, and the member must request a fresh one.       |

#### Social Login[​](#social-login "Direct link to Social Login")

Social login lets members sign in with an account they already have, such as Google or Apple. The entire flow happens inside a secure popup window, so credentials are never exposed to your site.

1. The member clicks a social login button (e.g. "Sign in with Google")
2. A popup opens where they complete sign-in with the provider
3. Once approved, the popup closes and the member is authenticated

#### Implementation[​](#implementation "Direct link to Implementation")

You can use the Allegro Web SDK to implement authentication yourself or simply drop in our pre-built login form component. For technical integration details, see the [Developer Documentation](/developer/guides/authentication.md).

##### Web Components[​](#web-components "Direct link to Web Components")

The [`<allegro-login-form>`](/developer/components/login-form.md) component provides a ready-made login form that handles magic links, one-time codes, and social login. Drop it into your page and it works — no custom code required.

#### Related[​](#related "Direct link to Related")

* [Magic Links guide](/developer/guides/authentication/magic-links.md) — step-by-step front-end integration
* [One-Time Codes guide](/developer/guides/authentication/one-time-codes.md) — front-end integration for the six-digit code flow
* [Social Login guide](/developer/guides/authentication/social-login.md) — provider setup and customization options


---

### Forms

Forms let you compose your organization's [user attributes](/product/audience/user-attributes.md) into a form that signed-in members fill out on your own site. Each field on a form points at one user attribute — the member's current value is prefilled when the form loads, and submitting the form updates that value on the member's profile in place.

A form is not a general-purpose form builder: you don't create free-form questions, you pick which existing user attributes a member can edit and how each one is presented. This makes forms the building block for a preference center, a profile-completion prompt, or a short survey that writes straight to the member record.

Forms only render for signed-in members

A form appears only to an authenticated member, because it reads and writes that member's profile. When no member is signed in, the embedded form stays empty. Pair it with a sign-in prompt on your site so visitors can authenticate first.

#### Before you start[​](#before-you-start "Direct link to Before you start")

A form can only use attributes that already exist and are marked as editable by the member. Define those first under **Organization Settings → User Attributes**, and turn on **Allow field to be updated by the user** for each one you want to appear on a form. Attributes that members can't edit don't show up in the field picker. See [User Attributes](/product/audience/user-attributes.md).

#### Finding your forms[​](#finding-your-forms "Direct link to Finding your forms")

Open **Forms** from the main navigation. The list shows every form in your organization with its **Title**, its **Slug**, and a count of how many **Fields** it contains. Click a form's title, or the edit icon, to open it.

#### Creating a form[​](#creating-a-form "Direct link to Creating a form")

Click **Add Form** and give the form:

| Field                  | Required | Description                                                                                                                                                                            |
| ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Title**              | Yes      | A name for the form, used only in the admin — for example *Profile Basics*.                                                                                                            |
| **Slug**               | Yes      | The identifier used to embed the form on your site. It auto-fills from the title as you type.                                                                                          |
| **Submit button text** | No       | The label on the form's submit button — for example *Save preferences*. Defaults to *Save*. An embed can override it per page; see [Embedding a form](#embedding-a-form-on-your-site). |

The slug is permanent

The slug identifies the form wherever it's embedded, so it **cannot be changed after the form is created**. On the edit screen the slug field is locked. Pick it carefully — to change it you'd create a new form and update every place the old one is embedded.

Below the title and slug, you build the form's fields.

#### Building the fields[​](#building-the-fields "Direct link to Building the fields")

The **Fields** section is where you compose the form. Click **Add field** to add a field, drag the handle to reorder fields, and use the remove icon to delete one. Once every editable attribute is already on the form, **Add field** is disabled — an attribute can appear at most once per form.

Each field is one user attribute, configured with:

| Setting                | Description                                                                                                                                                                                                                                       |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Attribute**          | The user attribute this field edits. Only member-editable attributes appear, and each one can be used once. The attribute's type (text, number, boolean, or enum) is shown beside the picker; the matching input control is chosen automatically. |
| **Required**           | Whether the member must provide a value before the form can be submitted.                                                                                                                                                                         |
| **Label override**     | A custom label for this field. Leave it blank to use the attribute's own name.                                                                                                                                                                    |
| **Placeholder**        | Placeholder text shown inside an empty input.                                                                                                                                                                                                     |
| **Tooltip**            | Help text shown alongside the field.                                                                                                                                                                                                              |
| **Error message**      | The message shown when the field's value fails validation. Leave it blank to use the attribute's default messages.                                                                                                                                |
| **Display conditions** | Rules that show the field only when other fields have certain values. See [Conditional fields](#conditional-fields).                                                                                                                              |

The input a member sees is derived from the attribute's type — a text box for a text attribute, a checkbox for a boolean, a dropdown for an enum, and so on — so you don't choose a control yourself. Validation follows the attribute too: each value must pass the attribute's type and any [validation rules](/product/audience/user-attributes.md#validation-rules) configured on it.

No user-editable attributes yet?

If your organization hasn't defined any member-editable attributes, the field builder tells you so. Define them under **Organization Settings → User Attributes** first, then come back to add fields.

A form holds up to 50 fields.

##### Conditional fields[​](#conditional-fields "Direct link to Conditional fields")

Use **display conditions** to reveal a field only when it's relevant. Add a condition and it reads *When \[field] \[is] \[value]*, where the operators are:

| Operator           | Shows the field when…                      |
| ------------------ | ------------------------------------------ |
| **Is checked**     | The chosen field is checked.               |
| **Is not checked** | The chosen field is unchecked.             |
| **Has a value**    | The chosen field has any value.            |
| **Equals**         | The chosen field equals a value you enter. |

A field can have several conditions (up to 10), and it appears only when **every** condition is met. Conditions re-evaluate as the member fills out the form, and a hidden field is never submitted. A field can't reference itself, so add the field it depends on first.

#### Live preview[​](#live-preview "Direct link to Live preview")

As you build a form, a **Live preview** beside the editor shows the real `<allegro-form>` the way a member will see it, re-rendering as you add fields and change settings. Switch the preview between **desktop** and **mobile** widths, and — when your organization has properties — choose whether to preview with your organization's branding or a specific property's, with an **Edit branding** link to jump straight to those settings. Type into the preview to try out [conditional fields](#conditional-fields); nothing you enter there is submitted or saved.

#### No draft or publish step[​](#no-draft-or-publish-step "Direct link to No draft or publish step")

A form is live as soon as it exists — there's no draft state, publish button, or enabled toggle. A form starts affecting your site the moment you embed it, and stops when you remove the embed or delete the form.

#### Embedding a form on your site[​](#embedding-a-form-on-your-site "Direct link to Embedding a form on your site")

Open a form and click **Show Snippet** to get the embed code. Add the element anywhere on your site:

```html
<allegro-form slug="your-form-slug"></allegro-form>

```

The form renders for signed-in members only. It uses the submit button text you set on the form; your developers can override that label per embed, along with the confirmation message and the styling — see the developer reference for [`<allegro-form>`](/developer/components/form.md).

#### Styling a form[​](#styling-a-form "Direct link to Styling a form")

Forms are a branding scope, so you can style them without touching your site's CSS. In the branding editor you'll find a **Form** scope with variables for the inputs, labels, tooltips, submit button, error text, and success state. By default these inherit your organization's design tokens (colors, corner radius, fonts), so a form matches the rest of your branding out of the box; override any variable to fine-tune it.

Set branding org-wide under **Organization Settings → Branding**, or per property under **Properties → (property) → Branding**. See [Branding](/product/administration/branding.md) for how scopes and inheritance work.

#### Who can manage forms[​](#who-can-manage-forms "Direct link to Who can manage forms")

| Action                | Who can do it                    |
| --------------------- | -------------------------------- |
| View forms            | Anyone in your organization.     |
| Create and edit forms | Organization admins and members. |
| Delete a form         | Organization admins only.        |

Deleting a form stops it rendering anywhere it's embedded. Members' saved attribute values are **not** affected — a form only edits values, it doesn't own them. Changes to forms are recorded in the [Activity Log](/product/administration/activity-log.md) under the Audience category.

#### Related[​](#related "Direct link to Related")

* [User Attributes](/product/audience/user-attributes.md) — Define the attributes a form edits.
* [`<allegro-form>` component](/developer/components/form.md) — Embed and customize a form on your site.
* [Branding](/product/administration/branding.md) — Style the Form scope.


---

### Segments

A segment is a saved group of known members, defined by rules over their profile: how much they read, how often they visit, their membership level, whether they give, and so on. Use segments to size an audience, export it, or target it from an [interaction](/product/interactions/conditions.md#segments), a [cohort](/product/interactions/cohorts.md), or a [meter](/product/interactions/meters.md).

Allegro keeps each segment's membership up to date as member profiles change, so a segment always describes who matches its rules now, not who matched when you built it.

To see your segments, go to **Segments** in the main navigation.

#### The Segments list[​](#the-segments-list "Direct link to The Segments list")

![The Segments list: each segment with its rules, member count, and last update](/assets/images/segments-list-89c986a0f6ad8949a88c32640d02987f.png)

Above the list, Allegro shows how many known members your organization has — the total every segment's share is measured against. Use the search box to find a segment by name.

| Column           | Description                                                                                                                                         |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Segment**      | The segment's name and how many groups and conditions it has. Click the name to open it.                                                            |
| **Rules**        | A compact summary of the conditions. Conditions in a group are joined by **AND** or **OR**, and a pill between groups shows how the groups combine. |
| **Members**      | How many members are in the segment now, and their share of all known members.                                                                      |
| **Last updated** | When the segment's rules or name were last saved.                                                                                                   |

Each row has a menu with these actions:

| Action         | What it does                                                                                             |
| -------------- | -------------------------------------------------------------------------------------------------------- |
| **Edit**       | Opens the segment editor.                                                                                |
| **Duplicate**  | Saves a copy named "… (copy)" with the same rules and opens it, so you can build a variation.            |
| **Export CSV** | Exports the segment's members. See [Exporting a segment](#exporting-a-segment).                          |
| **Delete**     | Permanently deletes the segment. See [Deleting a segment](#deleting-a-segment) for when this is blocked. |

When a count is unavailable

If Allegro can't reach the analytics engine to count a segment, the row shows **Count unavailable** rather than 0. A 0 always means no members match.

#### Building a segment[​](#building-a-segment "Direct link to Building a segment")

Click **New segment** to open the segment editor. Click the title at the top left to name the segment; until you do, it's called **Untitled segment**.

![The segment editor: two condition groups joined by OR, with the live Segment size panel](/assets/images/segment-editor-778b43c87f5eff3c3d4a8018a94dceb4.png)

A member is in the segment when its conditions match. Conditions work the same way they do in an interaction's [journeys](/product/interactions/journeys.md):

* **Groups.** Each group has one or more conditions. Set the group's **Match** to **All** (every condition must be true) or **Any** (at least one must be true).
* **Combining groups.** Between groups, choose **AND** or **OR**. **AND** binds tighter than **OR**: `A AND B OR C` means "(A and B) or C".
* **Adding conditions.** Click **Add condition** in a group, or **Add group** for a new group. Each condition is an attribute, an operator, and (for most operators) a value.

Click **Save segment** when you're done. A segment with an unfinished condition can't be saved until you complete or remove that condition.

##### Choosing a field[​](#choosing-a-field "Direct link to Choosing a field")

Click **Select attribute** in a condition to open the field picker. Fields are grouped by source; type to search across all of them. The bottom of the picker describes the highlighted field and the kind of value it takes.

![The field picker, showing the Engagement fields and a description of the highlighted field](/assets/images/field-picker-641990fadcf82ee04d5e07db5d021e9f.png)

| Source         | Fields                                                                                                                                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Engagement** | Page views · last 30 days, Engaged minutes · last 30 days, Days visited · last 30 days, Logins · last 30 days, Pages per visit, Days since last visit, Lifetime page views, Lifetime days visited, Lifetime logins |
| **Membership** | Member level, Sign-up gate                                                                                                                                                                                         |
| **Giving**     | Donor, Total donations                                                                                                                                                                                             |
| **Content**    | Top content section                                                                                                                                                                                                |
| **Device**     | Primary device                                                                                                                                                                                                     |

The operators depend on the kind of field:

| Field kind | Operators                                                        | Value                                                               |
| ---------- | ---------------------------------------------------------------- | ------------------------------------------------------------------- |
| Text       | is, is not, is one of, is not one of, contains, does not contain | Text, with suggestions drawn from values your members actually have |
| Number     | =, ≠, >, ≥, <, ≤, between                                        | A number, or two for **between**                                    |
| Yes / no   | is true, is false                                                | None                                                                |

A member with no value for a field matches none of that field's conditions, including **is not** and **is not one of**. For example, **Member level is not MEMBER** leaves out members who have no member level at all.

Engaged time is in minutes

**Engaged minutes · last 30 days** is entered and shown in minutes.

##### Segment size[​](#segment-size "Direct link to Segment size")

The **Segment size** panel on the right updates as you edit, so you can see the effect of each change before you save:

* **Members** — how many members match the conditions as they stand now, and their share of all known members. When you edit a saved segment, the panel also shows how far the count has moved from the saved one ("120 vs saved").
* **How it narrows** — the count for each group on its own, then for the groups combined. Each group card also shows its own count ("443 match").
* **Sample members** — a few members from the **saved** segment, with a short summary of their profile. This list doesn't change until you save.

The same count appears in the pill next to the segment name; click it to open the panel again if you've closed it.

A group with an unfinished condition says **Can't estimate this group yet** and is left out of the count until you finish it. If the count can't be calculated right now, the panel keeps the last numbers it had and says so.

note

Counts in the panel are previews. Your changes don't affect anything — exports, interactions, cohorts, or meters — until you click **Save segment**.

##### Undoing changes[​](#undoing-changes "Direct link to Undoing changes")

Use the undo and redo buttons in the header to step through your edits. While you have unsaved changes, the title shows **Unsaved changes · Reset**; click **Reset** to go back to the segment's last saved rules.

#### Segments in use[​](#segments-in-use "Direct link to Segments in use")

Interactions and cohorts can target a segment with the [Segment condition](/product/interactions/conditions.md#segments), and a meter can let members of chosen segments [bypass it](/product/interactions/meters.md).

When you open a segment that something uses, the editor notes which interactions, cohorts, and meters use it, with links to each. You can still edit its rules; the change applies to everything that uses it as soon as you save.

#### Exporting a segment[​](#exporting-a-segment "Direct link to Exporting a segment")

Click **Export CSV** in the editor header, or choose **Export CSV** from a segment's row menu.

![The export confirmation, showing how many members the saved segment has](/assets/images/export-dialog-3fdce96019dfa3d0db0ddd753b5dd87e.png)

The dialog shows how many members the saved segment has. Click **Start export** to build the file in the background; you can leave the page. Allegro emails you a link when the file is ready, and it appears on the [Exports](/product/exports.md) page as **Segment members: *segment name***.

An export always uses the segment as last saved. If you have unsaved changes, the dialog warns you that they aren't included — save first to export them. A new segment can't be exported until it has been saved.

The CSV has one row per member, with their email, sign-up date, membership and giving details, engagement totals, and first and last seen dates. See [Segment member columns](/product/exports.md#segment-member-columns) for the full list. Engaged time in the CSV is in seconds.

#### Deleting a segment[​](#deleting-a-segment "Direct link to Deleting a segment")

Choose **Delete** from a segment's row menu and confirm. Deleting is permanent.

Allegro won't delete a segment that's still in use. If any interaction (live, draft, or archived), active cohort, or meter references the segment, the dialog says **This segment can't be deleted** and how many of each use it. Remove the segment from them, then delete it.

#### Permissions[​](#permissions "Direct link to Permissions")

| Action                                       | Viewer | Member | Admin |
| -------------------------------------------- | ------ | ------ | ----- |
| View segments, counts, and sample members    | ✅     | ✅     | ✅    |
| Export a segment                             | ✅     | ✅     | ✅    |
| Create, edit, duplicate, and delete segments | ❌     | ✅     | ✅    |

Viewers can open any segment, but the editor is read-only for them.


---

### User Attributes

User attributes are the profile fields you let your members keep on their own record. You define the list of attributes once for your organization — each with a name, a type, and a stable key — and then every member can have a value for each one.

Unlike raw member metadata, user attributes are **controlled**: only the attributes you have defined can be read or written through the Allegro APIs. This is the foundation for a member preference center, where a signed-in member can manage settings like newsletter opt-ins, content preferences, or a favorite topic.

#### How they work[​](#how-they-work "Direct link to How they work")

* You define attributes in **Organization Settings → User Attributes**.
* Each attribute has a **slug** that maps to a single key on the member's profile. This is where the value is stored.
* Each attribute has a **type** (text, number, boolean, color, or a fixed set of choices) that Allegro uses to validate and cast values.
* Members set their own values through the Browser SDK, or your backend sets them through the REST API. See [Setting values](#setting-values).
* A member's current values are included in their signed session token (JWT) so your site can read them without an extra request.

#### Defining an attribute[​](#defining-an-attribute "Direct link to Defining an attribute")

Open **Organization Settings → User Attributes** and click **New attribute**. You provide:

| Field                           | Required | Description                                                                                                                                                                   |
| ------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Attribute Name**              | Yes      | The human-readable label, e.g. *Wants Newsletter*.                                                                                                                            |
| **Slug**                        | Yes      | The key the value is stored under, e.g. `wants-newsletter`. Auto-filled from the name.                                                                                        |
| **Description**                 | No       | An optional note describing what the attribute is for.                                                                                                                        |
| **Category**                    | No       | Groups the attribute in the attribute list and on each member's Profile tab. Pick an existing category or type a new one. See [Categories](#categories).                      |
| **Type**                        | Yes      | How the value is validated and cast. See [Attribute types](#attribute-types).                                                                                                 |
| **Options**                     | Enum     | One choice per line. Shown and required only when the type is **Select (enum)**.                                                                                              |
| **Validation rules**            | No       | Optional constraints each value must pass, each with an optional custom message. Available for **Text** and **Number** types only. See [Validation rules](#validation-rules). |
| **Sync from external profiles** | No       | Ordered paths that fill this attribute automatically from a member's external profile data. See [Syncing from external profiles](#syncing-from-external-profiles).            |
| **Keep this field private**     | No       | Hides the attribute from the Browser SDK and session API completely. See below.                                                                                               |

The slug auto-fills as you type the name, but you can override it before saving.

Every attribute also has two visibility toggles.

**Keep this field private** hides the attribute from the browser entirely. When it's on, the Browser SDK and session API behave as if the attribute doesn't exist: it never appears in the member's session token, and reads and writes against its slug fail the same way an undefined slug does. A private attribute also can't be placed on a [form](/product/audience/forms.md). Admins, your backend using the token API, and webhooks are unaffected. Use this for values you record about a member but don't want exposed in their browser — an internal score or a churn risk flag, for example.

**Allow field to be updated by the user** controls writes only. When it's off, members can't change the value themselves through the Browser SDK or the session API — writes are rejected, though the member can still read the value. Admins and your backend, using the token API, can always update it regardless of this setting. Use this for attributes you want to drive from your own systems (like a membership tier) without a member being able to override them.

Private wins over the editable toggle: once an attribute is private, members can't read it either, so the editable toggle no longer applies and is disabled on the form.

The slug is permanent

The slug is the member profile key the value is stored under, so it **cannot be changed after the attribute is created**. On the edit form the slug field is locked. Pick it carefully — to rename the key you must delete the attribute and create a new one, which leaves the old values behind under the old slug.

#### Attribute types[​](#attribute-types "Direct link to Attribute types")

| Type              | Stored value     | Notes                                                                                                                        |
| ----------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Text**          | A string         | Any free-form text.                                                                                                          |
| **Number**        | A number         | Whole numbers or decimals.                                                                                                   |
| **Boolean**       | `true` / `false` | A simple on/off flag.                                                                                                        |
| **Select (enum)** | One of a list    | Must match one of the **Options** you defined, one per line.                                                                 |
| **Color**         | A hex color      | A `#rrggbb` or `#rgb` value. Shorthand and uppercase are stored as lowercase six-digit hex, so `#ABC` is saved as `#aabbcc`. |
| **File**          | An uploaded file | Admin only. Images (PNG, JPG, GIF, WebP) or the extensions you choose. See [File attributes](#file-attributes).              |

Allegro validates every incoming value against the attribute's type. A value that doesn't match — a non-number for a Number attribute, or a choice outside the list for a Select attribute — is rejected. **Text** and **Number** attributes can carry additional [validation rules](#validation-rules) you configure; **Boolean**, **Select**, and **Color** attributes are constrained by their type alone.

#### Categories[​](#categories "Direct link to Categories")

Give an attribute a **category** to group it with related attributes, such as *Billing* or *Preferences*. The category field suggests the categories you've already used; type a new name to start a new one. Leave it blank and the attribute is **Uncategorized**.

The User Attributes list and each member's **Profile** tab show one heading per category, sorted A to Z, with Uncategorized last. Attributes are sorted by name within each category. Until at least one attribute has a category, neither page shows headings.

Categories only organize the admin screens. They aren't part of the session token, the Browser SDK, or the REST API.

#### File attributes[​](#file-attributes "Direct link to File attributes")

A **File** attribute holds one uploaded file per member, such as a headshot or a signed form. Only admins can set it: upload, replace, or remove the file from the member's **Profile** tab. Images show as a thumbnail; other files show as a download link.

When you define a File attribute, choose **Allowed files**:

* **Images** accepts PNG, JPG, GIF, and WebP files. Allegro checks the file's contents, not just its name. Check **Include SVG** to also accept `.svg` files; scripts and external links are removed from every SVG on upload.
* **Specific extensions** accepts the extensions you list, such as `pdf, docx`. Scripts, web pages, SVG, and executables are never allowed here; to accept SVG, choose **Images** and check **Include SVG**.

Files can be up to 10 MB.

Members can never upload or change a File attribute, so the **Allow field to be updated by the user** toggle, validation rules, and external profile sync don't apply, and a File attribute can't be placed on a form.

**Keep this field private** is on by default. While it's on, only admins can see the files: they never appear in the session token, the Browser SDK, or the REST API. Turn it off to make each member's file readable on your site. Its value is then the file's public URL, available through the session token, the Browser SDK, and the REST API. Choose when you create the attribute: this setting can't be changed afterward. File values are never sent on webhooks. Exports list the uploaded filename.

A File attribute can't be changed to another type, and an existing attribute can't be changed into a File attribute. Create a new attribute instead. Deleting a File attribute permanently removes every member's uploaded file for it.

#### Validation rules[​](#validation-rules "Direct link to Validation rules")

Beyond the type check, you can add **validation rules** to a **Text** or **Number** attribute so every value has to meet your constraints — a maximum length, a numeric range, a required format, and so on. The rules apply everywhere a value is written: the Browser SDK, the session API, your backend through the REST API, and values synced from external profiles.

The **Validation rules** section appears on the attribute form only for Text and Number types. Click **Add rule**, pick a rule, and fill in its value. Each rule also has an optional **Custom error message** — the message a member sees when a value fails that rule. Leave it blank to use Allegro's built-in default.

| Rule                    | Applies to | Value                                                               |
| ----------------------- | ---------- | ------------------------------------------------------------------- |
| **Minimum length**      | Text       | A whole number of characters.                                       |
| **Maximum length**      | Text       | A whole number of characters.                                       |
| **Matches regex**       | Text       | A regular expression, including its delimiters — e.g. `/^[a-z]+$/`. |
| **Contains**            | Text       | Text the value must include.                                        |
| **Does not contain**    | Text       | Text the value must not include.                                    |
| **Is an email address** | Text       | No value — the value must be a valid email.                         |
| **Minimum value**       | Number     | The smallest allowed number.                                        |
| **Maximum value**       | Number     | The largest allowed number.                                         |

You can add up to 20 rules per attribute, and each rule type can be used once.

Custom messages are your words to the member

The message you type on a rule is shown to the member — and returned to your site through the APIs — exactly as written, so keep it clear and specific (for example, *"Enter a US ZIP code"*). When you leave it blank, Allegro falls back to a generic default like *"Must be no more than 40 characters."*

##### Testing your rules[​](#testing-your-rules "Direct link to Testing your rules")

Configuring rules can be fiddly — a regex or a length bound is easy to get subtly wrong. The **Test a value** drawer lets you try a candidate value against the rules before you commit them. It appears on the attribute form for Text and Number attributes, on both the create and edit pages.

Open the drawer and type a value. Allegro checks it against the rules **exactly as they stand in the form right now**, including edits you haven't saved yet, and shows one row per check — the type check first, then each rule in order. Each row reports one of three outcomes:

| Outcome          | Meaning                                                                                                                           |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Passed**       | The value satisfies the check.                                                                                                    |
| **Failed**       | The value violates the rule. The exact message a member would see is shown, including your custom message if you set one.         |
| **Not enforced** | The rule can't run as configured — its value is missing, or its pattern is an invalid regex — so it accepts every value silently. |

The verdict and messages are the real ones a member would receive, because the drawer runs the same server-side validation the APIs use rather than reimplementing it in the browser.

Watch for "not enforced" rules

A rule reported as **not enforced** is doing nothing — a value that looks like it passes it is really slipping through unchecked. This usually means a rule is missing its value or its regex is malformed. Fix the rule so it enforces what you intend before saving.

#### Editing an attribute[​](#editing-an-attribute "Direct link to Editing an attribute")

From the User Attributes list, click an attribute's name to edit its **name**, **description**, **type**, or **options**. The slug stays locked.

Changing the type of an attribute with existing values

Changing an attribute's type does not rewrite values members have already saved. Existing values are reinterpreted under the new type the next time they're read, which can produce unexpected results (for example, text that isn't a number becomes `0`). Change the type of a live attribute with care.

#### Deleting an attribute[​](#deleting-an-attribute "Direct link to Deleting an attribute")

Deleting an attribute removes it from the list so it can no longer be read or written through the APIs or included in new tokens.

Member values are kept

Deleting an attribute definition **does not** erase the values members have already stored. The values remain on each member's profile under the slug. If you later re-create an attribute with the same slug, those existing values become visible again.

File attributes are the exception: deleting one permanently removes every member's uploaded file for it, and re-creating the slug starts empty.

#### Setting values[​](#setting-values "Direct link to Setting values")

You don't set member values from the admin UI — they're set programmatically:

* **Members set their own values** through the Allegro Browser SDK (`allegro.member.setUserAttribute(...)`). This is how a preference center on your site lets a signed-in member update their profile. See the [User Attributes SDK guide](/developer/guides/user-attributes.md).
* **Your backend sets values for any member** through the REST API, under `/v1/audience-members/{id}/user-attributes`. Reading requires the `audience-members:read` scope; writing requires `audience-members:write`. See the [REST API reference](/rest-api/).
* **Admins upload File attribute values** from the member's Profile tab. File values can't be set through the SDK or the REST API.

Writing to a slug that isn't a defined attribute is rejected — this is the control boundary that keeps arbitrary metadata out of the attribute APIs. Every write must also pass the attribute's type and any [validation rules](#validation-rules) you configured; a value that fails is rejected with your custom error message.

#### Syncing from external profiles[​](#syncing-from-external-profiles "Direct link to Syncing from external profiles")

Instead of setting an attribute's values yourself, you can have Allegro fill them automatically from a member's **external profile** data — the records Allegro syncs from your connected data providers. This is useful for surfacing a value that already lives in your CRM (a membership tier, a name, a preference) as a controlled user attribute your site and APIs can read.

##### Adding sync paths[​](#adding-sync-paths "Direct link to Adding sync paths")

On the attribute form, use the **Sync from external profiles** field to add one or more paths. Each path is the profile provider followed by the field's dot path into that provider's data — for example `my_crm.name.full` or `my_crm.person.tier`. As you type, the field suggests real paths drawn from your tenant's most recent external profiles.

Paths are checked **in order**, and the first one that resolves to a single value wins. Drag a path to reprioritize it, and use **Add path** to add more. This lets you list a primary source with fallbacks — if the first provider doesn't have the field for a given member, Allegro tries the next.

##### How the sync runs[​](#how-the-sync-runs "Direct link to How the sync runs")

* **Automatically**, whenever a member's external profile is added, updated, or removed. When a profile that supplied a value is removed, Allegro falls back to the next matching path.
* **On save**, when you add or change an attribute's paths, Allegro backfills every existing member who already has matching profile data.
* **On demand**, using the **Sync now** link next to an attribute's **Synced** badge in the list. This re-runs the backfill across existing members — handy after editing paths. Sync now is rate limited to once per attribute per minute.

Synced values are written through the member's normal attribute value, so JWT claims, the APIs, and the SDK pick them up with no extra work.

Safety rules

Synced values still respect the attribute's type **and any validation rules** you configure. A value that fails validation (for example, a choice outside a **Select** attribute's options, or text longer than a **Maximum length** rule allows) is skipped rather than stored, non-scalar values are skipped, and an existing value is left untouched when no path resolves — so a sync never clears a value it can't replace.

#### Values in the session token[​](#values-in-the-session-token "Direct link to Values in the session token")

Each member's current attribute values are included in the signed session token (JWT) as a `user_attributes` claim, so your site can read a member's preferences directly from their token. Only attributes the member has a value for appear, private attributes never appear, and each value is cast to its declared type. See [JWT Verification](/developer/guides/jwt.md) for the full token structure.

#### Related[​](#related "Direct link to Related")

* [User Attributes SDK guide](/developer/guides/user-attributes.md) — Read and write a member's attributes from the browser.
* [JWT Verification](/developer/guides/jwt.md) — Read attribute values from the session token.
* [Members](/product/audience.md) — Browse and manage your audience.


---

### Command Palette

The command palette is a keyboard-driven search box that lets you jump anywhere in Allegro, run quick actions, switch between sites, and find records across your organization — without reaching for the mouse or paging through lists.

#### Opening the palette[​](#opening-the-palette "Direct link to Opening the palette")

Press **⌘K** on macOS or **Ctrl+K** on Windows and Linux from anywhere in the dashboard. Press the shortcut again (or `Esc`) to close it.

Start typing in the **Search or jump to…** box and the list filters as you type. Use the arrow keys to move through the results and `Enter` to open the highlighted one. If nothing matches, the palette shows **No results for "{your text}"**.

#### What you can do[​](#what-you-can-do "Direct link to What you can do")

Results are grouped so the most direct matches rise to the top. Depending on what you type, you'll see some or all of these groups:

| Group            | What it contains                                                                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Audience**     | Audience members matched by your search (see [Searching records](#searching-records)).                                                                       |
| **Interactions** | Interactions matched by your search.                                                                                                                         |
| **Templates**    | Templates matched by your search.                                                                                                                            |
| **Forms**        | Forms matched by your search.                                                                                                                                |
| **Actions**      | Quick actions you can run from wherever you are.                                                                                                             |
| **Create**       | Start a new record — a form, product, plan, offer, webhook, user attribute, OAuth client, or API key. Only the records you have permission to create appear. |
| **Go to**        | Every page in the sidebar and in Settings, each of your properties, and (as you type) each property's settings pages, so you can navigate straight to it.    |
| **Theme**        | Switch the dashboard's appearance to Light, Dark, or System — applied the moment you pick it.                                                                |
| **Switch**       | The other sites you can access — pick one to switch your current site without leaving the page.                                                              |

Only results you have permission to open are shown, so the palette never links you to a page or record you can't view.

##### Creating records[​](#creating-records "Direct link to Creating records")

The **Create** group opens the same create screen as the matching page — a form, product, plan, offer, webhook, user attribute, OAuth client, or API key. Each entry appears only when your role can create that record, so the group lists just the things you're allowed to add.

##### Jumping to a property[​](#jumping-to-a-property "Direct link to Jumping to a property")

The **Go to** group includes every [property](/product/administration/properties.md) in your organization. Start typing a property's name to also reach its individual settings pages — these stay hidden on an empty query so a tenant with several properties doesn't open the palette to dozens of entries.

##### Switching the theme[​](#switching-the-theme "Direct link to Switching the theme")

The **Theme** group switches the dashboard between **Light**, **Dark**, and **System** (follow your device's setting). The change applies the moment you pick it, exactly like the appearance control in your account settings.

#### Searching records[​](#searching-records "Direct link to Searching records")

The palette searches your organization's **audience members**, **interactions**, **templates**, and **forms** live as you type. How it matches depends on what you enter:

| What you type           | What it finds                                                                                 |
| ----------------------- | --------------------------------------------------------------------------------------------- |
| Two or more letters     | Interactions, templates, and forms whose **title or slug** contains your text.                |
| Text containing `@`     | Audience members whose **email** starts with what you typed (for example `jane@example.com`). |
| A full record ID (UUID) | The exact audience member, interaction, template, or form with that ID.                       |

Each match shows the record's name — and, for audience members, their email as a subtitle — so you can tell similarly named records apart. Selecting a match opens that record.

note

Email search matches from the **start** of the address, so type the beginning of the address (`jane@…`) rather than a word from the middle of it. For a broader member search by name or partial email, use the search bar on the [Audience](/product/audience.md#searching-members) page.


---

### Content

Content lists every page Allegro has cataloged from your site, newest first. Allegro uses the catalog to put titles, sections, and authors on [Analytics](/product/analytics.md) and to choose stories for [recommendations](/product/content/engines.md). Open it from **Content** in the sidebar.

![The Content catalog: search, a section filter, Export, and index status tabs above a list of indexed stories](/assets/images/content-da26fe536ded136a7ca58f2ec116b980.png)

#### How stories get into the catalog[​](#how-stories-get-into-the-catalog "Direct link to How stories get into the catalog")

You don't add stories by hand. A story appears in the catalog within about a minute of its first page view, once the Allegro SDK reports it. Allegro then reads the page and indexes it for recommendations.

#### Finding stories[​](#finding-stories "Direct link to Finding stories")

* **Search by title or URL**, then press Enter.
* Pick a section from **All sections** to see just that section.
* Use the status tabs to see stories at each stage of indexing.

Click a story's title to open its [story view](/product/content/story.md) in Analytics.

| Column           | What it shows                                   |
| ---------------- | ----------------------------------------------- |
| **Story**        | The title and path.                             |
| **Section**      | The section the page belongs to.                |
| **Type**         | The content type, such as Article.              |
| **Index status** | Whether the story is ready for recommendations. |
| **Published**    | When the story was published.                   |

#### Index status[​](#index-status "Direct link to Index status")

| Status                | Meaning                                                                              |
| --------------------- | ------------------------------------------------------------------------------------ |
| **Indexed**           | Allegro has read the story and it can be recommended.                                |
| **Embedding pending** | Allegro has read the story and is still preparing it for recommendations.            |
| **Fetch failed**      | Allegro couldn't read the page. Check that the URL loads publicly and isn't blocked. |

A story that isn't indexed still shows up in Analytics; it just can't be recommended yet.

#### Exporting the catalog[​](#exporting-the-catalog "Direct link to Exporting the catalog")

Click **Export** to download a CSV of every story matching your current search, section, and status. The file includes the title, path, section, type, published date, and index status of each story.

#### Related[​](#related "Direct link to Related")

* [Engines](/product/content/engines.md) — Configure how recommendations are chosen
* [Recommendation Explorer](/product/content/explorer.md) — Try out what a reader would be recommended
* [Story view](/product/content/story.md) — How one story performed


---

### Recommendation Engines

A recommendation engine decides which stories a recommendation placement on your site shows. Each engine blends a few signals with its own weights, so you can run a personal "for you" rail in one spot and a mostly trending rail in another. Open them from **Content → Engines** in the sidebar.

![The Recommendation Engines page: the engine list, an engine\&#39;s signal blend and age limit, and a live serve of six recommended stories](/assets/images/engines-520e4f72f86b2174beb3efecb594e205.png)

Changes apply to the next recommendation request, with nothing to deploy.

#### The default engine[​](#the-default-engine "Direct link to The default engine")

Every organization has a built-in **Default** engine. Placements that don't ask for a specific engine use it. You can open it to see its settings, but you can't change or delete it.

#### Creating an engine[​](#creating-an-engine "Direct link to Creating an engine")

Admins and members can click **New engine**. Viewers can open engines but not change them.

| Field     | What it sets                                                                                                                                               |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**  | The engine's ID, such as `news-rail`. Use lowercase letters, numbers, and dashes, starting with a letter. You can't change it after the engine is created. |
| **Label** | A friendly name shown in Allegro, such as **News rail**.                                                                                                   |

Give your developers the engine's name: a placement asks for an engine by name, and falls back to the default engine if the name doesn't exist.

##### Signal blend[​](#signal-blend "Direct link to Signal blend")

Each signal has a slider. A higher weight gives that signal more say in which stories win; set a weight to 0 to turn the signal off. At least one weight must be above 0.

| Signal         | What it favors                                                                                                    |
| -------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Taste**      | Stories like the ones this reader has read before. For a reader with no history, stories like the one they're on. |
| **Trending**   | The most-engaged stories of the last 24 hours.                                                                    |
| **Categories** | Stories in the categories this reader tends to read.                                                              |
| **Geography**  | Stories set in the places this reader tends to read about.                                                        |

New engines start with **Taste** at 1 and **Trending** at 0.25.

note

**Categories** and **Geography** appear only when the Backfield integration is turned on for your organization.

##### Age limit[​](#age-limit "Direct link to Age limit")

Set **Only articles from the last** to a number of days to keep older stories out, or leave it empty for no limit. **Evergreen articles bypass the age limit**, on by default, lets stories marked as evergreen through regardless of age.

##### Category boosts and filters[​](#category-boosts-and-filters "Direct link to Category boosts and filters")

With the Backfield integration on, you can tune categories directly. Categories are written as `type:value`, such as `subject:Housing`.

* **Boost category** multiplies a category's score. A boost of **1.5** makes matching stories score half again as high.
* **Never serve** keeps a category out of this engine entirely, such as `subject:Obituary`.

Click **Create engine** or **Save changes** to save.

#### Previewing an engine[​](#previewing-an-engine "Direct link to Previewing an engine")

After saving, click **Preview live serve** to see what the engine recommends right now. Leave **as device** empty to see what a reader with no history gets, or enter a device ID to see a specific reader's recommendations. You can find a device ID in an [event's details](/product/analytics/events.md#event-details).

Each card shows the story, the signal that chose it, its section, its score, and how much each signal contributed. Click a card to open the story's [analytics](/product/content/story.md).

If nothing comes back, the device has no reading history for the personal signals and **Trending** is set to 0, or the age limit and filters excluded every story.

#### Deleting an engine[​](#deleting-an-engine "Direct link to Deleting an engine")

Click the trash icon beside an engine and confirm. Placements that ask for a deleted engine fall back to the default engine. Deleting can't be undone.

#### Related[​](#related "Direct link to Related")

* [Recommendation Explorer](/product/content/explorer.md) — Simulate a reader and compare engines
* [Content](/product/content.md) — The catalog of stories engines choose from


---

### Recommendation Explorer

The Recommendation Explorer lets you play the part of a reader. Add the stories they've read, and see what recommendations they'd get. Use it to sanity-check an [engine](/product/content/engines.md) before a placement goes live, or to explain why a reader saw a story. Open it from **Content → Recommendation Explorer** in the sidebar.

Nothing you do here is saved or affects real readers.

![The Recommendation Explorer: three sports and stadium stories in the reading history, and six recommendations chosen by taste](/assets/images/explorer-e9823cb28d88df582d10e8ac07f58dc4.png)

#### Building a reading history[​](#building-a-reading-history "Direct link to Building a reading history")

1. Search for a story by title under **Reading History** and pick it from the list.
2. Keep adding stories in the order the reader read them. The last story is the most recent.
3. Set the engaged seconds for each read. Longer reads count for more.

Use the arrows to reorder reads and **×** to remove one. Once results come back, each read shows its share of the reader's taste, so you can see which stories are driving the recommendations.

With no reads, the explorer shows what a reader who just arrived gets, which is usually trending stories.

How reads are weighted

The explorer weights reads the same way your site does. Reads are treated as one day apart, each read counts for 10 plus its engaged seconds (capped at 600), and a read's influence halves every 14 days.

#### Choosing an engine[​](#choosing-an-engine "Direct link to Choosing an engine")

| Setting                         | What it does                                                                                                                                                                            |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Engine**                      | **Classic ladder** recommends by taste, then falls back to trending. Pick one of your [engines](/product/content/engines.md) to test it instead. Appears once you've created an engine. |
| **Include trending fill**       | With the classic ladder, pads the results with the most-engaged stories of the last 24 hours, as your site does.                                                                        |
| **Only articles from the last** | Leaves out stories older than this many days. Empty means no limit.                                                                                                                     |

#### Reading the results[​](#reading-the-results "Direct link to Reading the results")

**What the Engine Recommends** shows up to six stories, each with the signal that chose it (**taste**, **similar**, **trending**, **category**, or **geo**), its section, and its score. Click a story to open its [analytics](/product/content/story.md).

If a read isn't in the catalog yet, a note lists it; it doesn't count toward the reader's taste until it's [indexed](/product/content.md#index-status).

#### Related[​](#related "Direct link to Related")

* [Recommendation Engines](/product/content/engines.md) — Create and tune engines
* [Content](/product/content.md) — The catalog of stories


---

### Story View

The story view shows how one page performed against the rest of your site. It sits under **Content**, but has no sidebar entry; you open it by clicking a story.

![The story view for an Arts \&amp; Culture story: page views per day since publish, traffic sources, time on page against the site, where readers went next, and the reader-to-member funnel](/assets/images/story-d7d97772ac38ea418028debafac1b799.png)

#### Opening a story[​](#opening-a-story "Direct link to Opening a story")

Click a story title almost anywhere it appears:

* **Spiking** on the [Pulse](/product/analytics.md#the-pulse)
* **Top Content by Engaged Time** on the [Dashboard](/product/dashboard.md) and the [Page views](/product/analytics/events.md#page-views) view
* The [Content](/product/content.md) catalog and recommendation cards
* **View this story's analytics** in an [event's details](/product/analytics/events.md#event-details)
* **Where Readers Went Next** on another story

#### Header and window[​](#header-and-window "Direct link to Header and window")

The header shows the story's thumbnail, title, section, authors, publish date, and path. A **Live** badge appears for stories published in the last 24 hours.

| Button             | What it does                                                                                                          |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| **Open story**     | Opens the story on your site in a new tab.                                                                            |
| **View events**    | Opens the [Events explorer](/product/analytics/events.md#all-events) filtered to this page.                           |
| **Build a report** | Opens the [report builder](/product/analytics/reports.md#building-a-report) with this story's page views by referrer. |

Pick a window under the header: **Since publish** (the default), **24 hours**, or **7 days**. If Allegro doesn't know when the story was published, it shows the last 30 days.

#### What you see[​](#what-you-see "Direct link to What you see")

The stats compare the story's **Page views**, **Readers**, **Avg engaged time**, and **Logins** with your site's average story over the same window.

| Card                        | What it shows                                                                                          |
| --------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Page Views**              | Views per hour or day across the window.                                                               |
| **Traffic Sources**         | Each [channel's](/product/analytics.md#traffic-channels) share of views, plus the top referring sites. |
| **Time on Page**            | How long views lasted, in bands from under 10 seconds to 10 minutes, beside the site average.          |
| **Where Readers Went Next** | The pages readers opened next in the same visit, with the share who kept reading or left the site.     |
| **From Reader to Member**   | Page views, then how many met a gate, requested a magic link, signed up, and logged in on this story.  |
| **Gates on This Story**     | Each gate type's views, and how often it led to a sign-up request or a login.                          |

#### Related[​](#related "Direct link to Related")

* [Content](/product/content.md) — The catalog of stories Allegro knows about
* [Events](/product/analytics/events.md) — Every tracked event, filterable


---

### Dashboard

The Dashboard is the first screen you see after signing in to Allegro. It's a near-real-time view of how readers are engaging with your content, how your audience is growing, and how your content library is performing — so you can spot trends without digging through lists or reports. A **Live** badge next to the title shows the page is updating on its own.

![Dashboard](https://allegroaudience.com/assets/dashboard-hero-light.webp)

The page refreshes on its own while it's open, so you never need to reload. Each section loads independently, and the page appears immediately with placeholder skeletons while the numbers fill in — a slow analytics query never holds up the rest of the page.

| Section                                                        | Refreshes about every |
| -------------------------------------------------------------- | --------------------- |
| Top Content by Engaged Time                                    | 20 seconds            |
| KPIs, Audience Growth, Logins per Hour, Performance by Section | 5 minutes             |

note

Use the **Snippet** button in the top-right corner at any time to view the embed code for adding Allegro to your site.

#### Filtering by property[​](#filtering-by-property "Direct link to Filtering by property")

If your organization has more than one [property](/product/administration/properties.md), a property selector appears in the top-right of the Dashboard. Pick a property to scope the Dashboard to that property, or choose **All properties** to clear the filter. With a single property, there's nothing to filter and the selector is hidden.

Most of the Dashboard follows the selected property:

| Section                                                                                                      | With a property selected                                       |
| ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| Audience Growth and **New Members · 30D**                                                                    | Count only accounts created on that property.                  |
| **Avg Engaged Time**, **Logins · 24H**, Logins per Hour, Top Content by Engaged Time, Performance by Section | Narrow to engagement and logins on that property.              |
| **Active Members**                                                                                           | Stays organization-wide and shows an **All properties** badge. |

**Active Members** can't be filtered because a member's last activity isn't recorded per property. The **All properties** badge on that tile tells you it's still counting your whole organization while the rest of the page is scoped.

note

A property counts an account as new the first time someone signs up on it. Existing members signing in on a property for the first time aren't counted as new there, so scoped Audience Growth always means *new accounts*.

#### KPIs[​](#kpis "Direct link to KPIs")

A strip of four headline tiles sits at the top of the Dashboard, each showing a single number, a colored change indicator comparing it to the previous period, and a small trend sparkline of recent days.

| Tile                  | Meaning                                                           | Window        |
| --------------------- | ----------------------------------------------------------------- | ------------- |
| **Active Members**    | Members active in the period, compared with the previous 30 days. | Last 30 days  |
| **New Members · 30D** | New members who joined, with a trend indicator.                   | Last 30 days  |
| **Avg Engaged Time**  | Average engaged time per page view, with a trend indicator.       | Last 30 days  |
| **Logins · 24H**      | Total member logins, compared with the previous 24 hours.         | Last 24 hours |

Active Members and New Members are drawn from your member records, so they're always available. Average Engaged Time and Logins are powered by Allegro's analytics backend; when that data isn't available, the tile shows a dash (—) instead of a number.

#### Audience Growth[​](#audience-growth "Direct link to Audience Growth")

The Audience Growth card plots how many new members joined over time, so you can see whether sign-ups are trending up or down.

* Each bar is one time bucket, and the busiest bucket in the window is highlighted.
* The bar for the current period is shown as a **projection** (in a muted tone). Because the period is still in progress, this projection estimates where it's on track to land based on the pace so far and your recent average — so a young day reads as "on track to" rather than a sudden drop.
* Hover any bar to see its date and count; the current bucket also shows how many members have joined so far.

Use the **Daily / Weekly / Monthly** toggle in the top-right to change the granularity. Daily covers the last 30 days, Weekly the last 12 weeks, and Monthly the last 12 months.

A row of headline figures sits above the chart and follows the granularity you pick:

| Stat                           | Meaning                                                                         |
| ------------------------------ | ------------------------------------------------------------------------------- |
| **Today (projected)**          | The estimated total new members for the current period, with a trend indicator. |
| **New · 30 days**              | Total new members over the window, with a trend indicator.                      |
| **Avg per day / week / month** | The average per bucket for the chosen granularity.                              |
| **Best day / week / month**    | The single busiest bucket, with the date it occurred.                           |

note

"Today" follows your organization's configured time zone, so the day rolls over at local midnight rather than UTC.

Audience Growth is drawn from your member records directly, so it stays available regardless of the analytics backend.

#### Logins per Hour[​](#logins-per-hour "Direct link to Logins per Hour")

The Logins per Hour card charts member logins over the last 72 hours, grouped into two-hour buckets, so you can see daily rhythms and the impact of a campaign or send. The busiest buckets are drawn in a stronger color.

Two headline figures sit above the chart:

| Stat          | Meaning                                                                                     |
| ------------- | ------------------------------------------------------------------------------------------- |
| **Last 24h**  | Total logins in the last 24 hours, with an indicator comparing it to the previous 24 hours. |
| **Peak hour** | The single busiest bucket in the window, with its login count and the time it occurred.     |

Hover a bar to see its time range, its total logins, and a breakdown by login method (such as Email, Google, Apple, Facebook, or Magic link). Hour labels and the peak-hour time are shown in your organization's time zone.

#### Top Content by Engaged Time[​](#top-content-by-engaged-time "Direct link to Top Content by Engaged Time")

The Top Content card ranks the pages your readers are spending the most *engaged* time on over the last 24 hours. Engaged time counts only the time a page is actually open and active in front of a reader, not time spent in a background tab. This is the most live part of the Dashboard and refreshes about every 20 seconds, so you can watch engagement shift as a new article picks up readers.

Each row shows:

* A thumbnail and the page title, with a meta line of section, author, and publish date when Allegro has that page in its content catalog (otherwise the page's path). Pages the catalog marks as evergreen carry an **Evergreen** badge.
* A **Share of engaged time** bar showing how much of the total the page accounts for.
* **Engaged** (total engaged time), **Views**, and **Avg** (average engaged time per view).

Click a row to open the page's [story view](/product/content/story.md).

Use the section pills at the top of the card to filter to a single section, or **All content** to clear the filter. The subtitle shows how many pages are indexed, and a count shows how many of them the table is currently showing.

If no engagement has been recorded in the last 24 hours yet, the card says `No engagement recorded in this window yet.`

#### Performance by Section[​](#performance-by-section "Direct link to Performance by Section")

The Performance by Section card rolls your indexed pages up by section over the last 30 days, so you can compare how whole areas of your site are performing rather than individual pages.

| Column           | Meaning                                                           |
| ---------------- | ----------------------------------------------------------------- |
| **Section**      | The content section.                                              |
| **Pages**        | Number of indexed pages in the section.                           |
| **Views**        | Total views across the section.                                   |
| **Engaged Time** | Total engaged time across the section.                            |
| **Avg Engaged**  | Average engaged time per page.                                    |
| **30-Day Trend** | A sparkline and change indicator for the section over the window. |

The numeric cells are shaded from light to dark to show low-to-high values at a glance — a **Low … High** key sits above the table. If no section data has been recorded in the window yet, the card says `No section data recorded in this window yet.`

#### When data is unavailable[​](#when-data-is-unavailable "Direct link to When data is unavailable")

Top Content, Performance by Section, Logins per Hour, and the Average Engaged Time and Logins KPI tiles are powered by Allegro's analytics backend. If that backend is temporarily unreachable, those cards show `Analytics data is temporarily unavailable.` (and the affected KPI tiles show a dash), then recover automatically once it's back. Each section degrades on its own, so the rest of the Dashboard keeps working. Audience Growth and the Active Members and New Members KPI tiles are drawn from your member records directly, so they stay available regardless.

#### Related[​](#related "Direct link to Related")

* [Audience](/product/audience.md) — browse and manage your full member list.
* [Analytics](/product/analytics.md) — explore engagement in depth.
* [Content](/product/content.md) — the stories Allegro has cataloged.


---

### Email Templates

Allegro sends transactional emails on your behalf — things like magic sign-in links for your members. Email Templates let you customize the look and feel of those emails so they match your brand.

![Email Templates](/assets/images/email-templates-223d055c713d903bb23652a56a88e7de.png)

#### Built-in Email Types[​](#built-in-email-types "Direct link to Built-in Email Types")

Allegro includes the following transactional email types. Each one comes with a default template that's used until you save your own version.

| Email          | When it's sent                                                                    |
| -------------- | --------------------------------------------------------------------------------- |
| **Magic Link** | When a member requests a passwordless sign-in link. Includes the link and expiry. |

More email types

Additional email types may appear here as Allegro gains new features. Any new type starts with a default template and can be customized in the same way.

#### Template Statuses[​](#template-statuses "Direct link to Template Statuses")

Each template in the list shows one of two statuses:

| Status         | Meaning                                                  |
| -------------- | -------------------------------------------------------- |
| **Default**    | Allegro's built-in template is in use — nothing changed. |
| **Customized** | You've saved your own HTML for this email type.          |

#### Editing a Template[​](#editing-a-template "Direct link to Editing a Template")

1. Go to **Email Templates** in the sidebar.
2. Click the pencil icon next to the email type you want to change, or click the email name directly.
3. The editor opens with an **HTML Editor** on the left and a live **Preview** on the right.

##### Writing Your HTML[​](#writing-your-html "Direct link to Writing Your HTML")

The editor accepts standard HTML. Write the body of your email and Allegro wraps it in a message automatically.

To include dynamic content — like the member's name or a sign-in link — use variable placeholders in the format `{% variable_name %}`. Start typing `{%` and the editor will suggest available variables. You can also click a variable chip in the **Available Variables** panel below the editor to insert it at your cursor.

##### Available Variables[​](#available-variables "Direct link to Available Variables")

Each email type has its own set of variables. The variable panel lists every available placeholder and describes what it contains. The preview panel fills in example values so you can see how the finished email looks.

###### Shared variables[​](#shared-variables "Direct link to Shared variables")

A few variables are available in **every** template, regardless of email type:

| Variable                  | Resolves to                                                                                                                                                |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{% property_name %}`     | The [property](/product/administration/properties.md) the email was sent through, falling back to the organization name when there is no property context. |
| `{% organization_name %}` | Always your organization's name.                                                                                                                           |

The built-in templates use `{% property_name %}`, so out of the box an email reflects the property it was sent through and shows the organization name elsewhere. If you run a single brand with no properties, `{% property_name %}` and `{% organization_name %}` produce the same value.

##### Saving[​](#saving "Direct link to Saving")

Click **Save** when you're happy with the result. The button stays disabled until you make a change. After saving, the template's status updates to **Customized**.

When saving an existing customization, a dialog appears asking for an optional **revision note**. Use this to describe what changed (e.g., "Updated footer copy"). The note is attached to that saved version in the revision history. You can leave it blank if you don't need a record of the change.

#### Revision History[​](#revision-history "Direct link to Revision History")

Every save to an existing customization creates a revision. Revisions let you browse past versions of the template and restore any of them if something goes wrong.

##### Viewing Revisions[​](#viewing-revisions "Direct link to Viewing Revisions")

Click **Show Revisions** in the editor toolbar to open the revision history modal dialog. It lists saved versions of the template, newest first. Each entry shows the revision number, who saved it, when it was saved, and any note that was added. If there are more revisions than fit in the initial list, click **Load More** to see older entries.

Click a revision to open its detail view. You'll see the full subject line and HTML body as they were at that point, along with a rendered preview.

##### Restoring a Revision[​](#restoring-a-revision "Direct link to Restoring a Revision")

From a revision's detail view, click **Restore this revision**. Optionally add a restore note to describe why you're rolling back, then confirm. Allegro replaces the current template with the restored content and records a new revision entry so the restore itself is part of the history.

note

Restoring does not delete more recent revisions — it adds a new revision on top of the existing history, making the restore itself reversible.

#### Sending a Test Email[​](#sending-a-test-email "Direct link to Sending a Test Email")

Click **Send Test Email** to send a rendered copy of the template to your own email address. Allegro fills in example values for all variables so you can check how the email looks in a real inbox.

Save before testing

The test email uses the last saved version of the template. If you have unsaved changes in the editor, save first and then send the test.

#### Resetting to the Default Template[​](#resetting-to-the-default-template "Direct link to Resetting to the Default Template")

Want to start over? You can discard your customization and restore Allegro's built-in template:

1. Open the template editor.
2. Click **Reset to Default** (only visible when a customization exists).
3. Confirm the prompt — your custom HTML is removed and the default template is restored.

Irreversible action

Resetting permanently removes your saved customization **and its entire revision history**. There is no way to recover previous versions after a reset. If you think you may want the content later, copy your HTML somewhere safe before resetting.

AWS SES required

Allegro delivers emails through Amazon Simple Email Service (SES). Your templates won't have any effect until SES credentials are configured. Head to **Organization Settings → Email** to set up your Access Key, Secret, and Region. See [Settings](/product/administration/settings.md) for more details.

For details on who can manage email templates, see [Permissions](/product/administration/permissions.md).

#### Related Links[​](#related-links "Direct link to Related Links")

* [Settings](/product/administration/settings.md) — configure your AWS SES credentials for email delivery.
* [Authentication](/product/audience/authentication.md) — learn about magic links and other sign-in methods that trigger transactional emails.


---

### Entitlements

Entitlements control what your audience can access. You define the things people can get access to (products), and Allegro tracks who has access to what (entitlements). This powers digital subscriptions, gated content, event access, physical product fulfillment, and more.

![Entitlements](/assets/images/resources-e78e06e477bf457d90b412bf2dcd5a8f.png)

#### Key Concepts[​](#key-concepts "Direct link to Key Concepts")

| Concept         | Description                                                                                           |
| --------------- | ----------------------------------------------------------------------------------------------------- |
| **Product**     | A thing a member can gain access to, such as a digital subscription, a print edition, or event entry. |
| **Entitlement** | A record linking a member to a product. The member has access as long as the entitlement is active.   |

Entitlements are usually created automatically when a member subscribes to or purchases an [Offer](/product/entitlements/offers.md). You can also grant them manually.

#### Products[​](#products "Direct link to Products")

A product is something of value that you control access to. Products are flexible — they can represent abstract concepts or concrete goods:

* **Digital subscription** — access to premium content on your site
* **Print edition** — a physical publication mailed to the subscriber
* **Newsletter tier** — a specific tier of email content
* **Event access** — entry to a virtual or in-person event
* **Physical product** — a t-shirt, tote bag, or other merchandise

Each product has a name that you define. Members don't interact with products directly — they interact with offers, which grant access to one or more products behind the scenes.

You create and manage products from **Entitlements → Products** in the admin.

#### Entitlements[​](#entitlements-1 "Direct link to Entitlements")

An entitlement is the record that says "this member has access to this product." Each entitlement belongs to one member and one product.

| Type           | How it works                                                                                  |
| -------------- | --------------------------------------------------------------------------------------------- |
| **Indefinite** | No end date — the member's access does not expire unless the entitlement is manually revoked. |
| **Time-bound** | Has a start date, an end date, or both — access is only active within that date range.        |

A member can hold multiple entitlements to the same product. For example, when they renew a subscription, a new entitlement is created without removing the old one. Access continues as long as at least one entitlement for that product is active.

##### Status[​](#status "Direct link to Status")

Every entitlement has a status derived from its dates and whether it was deliberately revoked. Only an **Active** entitlement grants access.

| Status        | Meaning                                                                                            | Grants access |
| ------------- | -------------------------------------------------------------------------------------------------- | ------------- |
| **Active**    | In effect now — it has started (or has no start date) and has not ended or been revoked.           | Yes           |
| **Scheduled** | Has a start date in the future. Access begins automatically when that date arrives.                | No            |
| **Expired**   | Reached the end date it was granted with.                                                          | No            |
| **Revoked**   | Ended deliberately — by an admin, a refund, or a data sync — rather than by reaching its end date. | No            |

**Revoked** and **Expired** both deny access, but they mean different things: an expired entitlement simply ran its course, while a revoked one was cut short on purpose. Once an entitlement is revoked it stays **Revoked** — it never rolls over to **Expired**, even long after its end date — so you can always tell the two apart on a member's profile and in the API.

#### How Access Works[​](#how-access-works "Direct link to How Access Works")

When your site needs to check whether a member can access a product, the logic is simple: does the member hold at least one active entitlement for it?

You define the products, you decide who gets entitlements, and Allegro tells you whether access is granted.

note

Entitlements define access within Allegro — your site or application is responsible for enforcing that access (for example, showing or hiding gated content based on whether the member holds an active entitlement).

#### Managing Entitlements[​](#managing-entitlements "Direct link to Managing Entitlements")

##### Viewing Entitlements[​](#viewing-entitlements "Direct link to Viewing Entitlements")

You can see a member's current and past entitlements on their profile in the **Audience** section. Each entry shows the product name, start date, end date (if any), and a [status](#status) badge — **Active**, **Scheduled**, **Revoked**, or **Expired**. A revoked entitlement shows when it was revoked in place of its end date.

##### Granting an Entitlement Manually[​](#granting-an-entitlement-manually "Direct link to Granting an Entitlement Manually")

To grant access without going through an offer, open the member's profile and use the **Grant Entitlement** action. Pick the product, and optionally set a start and end date. Leave the end date blank to make it indefinite.

##### Revoking an Entitlement[​](#revoking-an-entitlement "Direct link to Revoking an Entitlement")

To remove access, open the entitlement on the member's profile and choose **Revoke**. This ends access immediately, regardless of any configured end date, and marks the entitlement **Revoked** rather than **Expired** so the deliberate removal is distinguishable from one that simply reached its end date.

warning

Revoking an entitlement is immediate. If the member is currently accessing something protected by that entitlement, their access ends right away.

#### Related[​](#related "Direct link to Related")

* [Offers](/product/entitlements/offers.md) — How members subscribe or purchase to receive entitlements automatically
* [Audience](/product/audience.md) — Browsing and managing member profiles


---

### Offers and Plans

Offers are how members acquire [entitlements](/product/entitlements.md). An offer presents a set of options — called plans — that a member can choose from. When a member selects a plan and completes the action (subscribing, purchasing, signing up), the system automatically creates the appropriate entitlements for them.

#### Key Concepts[​](#key-concepts "Direct link to Key Concepts")

| Concept   | Description                                                                                             |
| --------- | ------------------------------------------------------------------------------------------------------- |
| **Offer** | A collection of plans presented to a member, representing a "choose a plan" or "pick an option" moment. |
| **Plan**  | A single option within an offer. Defines what products are granted, for how long, and at what price.    |

#### Offers[​](#offers "Direct link to Offers")

An offer is a named set of plans that you configure in the admin. You might create one offer for your digital subscription plans, another for event ticket tiers, and another for a membership drive.

Offers are surfaced to members through your site — typically through an [Interaction](/product/interactions.md) that displays the offer's plans and collects the member's selection. The offer itself does not define the look or layout of the page; that is handled by the template you build for it.

You create and manage offers from the **Entitlements → Offers** section of the admin.

##### Showing an offer in an Interaction[​](#showing-an-offer-in-an-interaction "Direct link to Showing an offer in an Interaction")

To show an offer's plans on your site, use a template that [shows plans](/product/interactions/templates.md#showing-plans) in an Interaction:

1. In the Interaction editor, add a template action and choose the template.
2. In the **Offer** picker that appears under it, choose the offer. Each offer is listed with its number of plans.
3. Save the Interaction.

The template shows the offer's plans in the offer's order. If the offer has no plans, the template is not shown, and the editor warns you. Editing, reordering, or removing the offer's plans updates every Interaction that uses the offer.

An offer that an Interaction uses can't be deleted. Choose a different offer in those Interactions first.

#### Plans[​](#plans "Direct link to Plans")

A plan is a single purchasable or subscribable option within an offer. Each plan specifies:

| Property     | Description                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------------- |
| **Name**     | A label for this option, shown to the member (e.g., "Monthly Digital", "Annual + Print").         |
| **Products** | One or more products the member is granted access to when they select this plan.                  |
| **Duration** | How long the entitlement lasts — monthly, annual, or a custom period. Leave blank for indefinite. |
| **Price**    | The cost of this plan (if applicable).                                                            |

A single plan can grant access to multiple products. For example, a "Digital + Print" plan could simultaneously grant "Digital Access" and "Print Edition" entitlements to the member.

To record more about each plan, such as a seat limit or a tier label, define [plan fields](/product/entitlements/plan-fields.md) and fill them in when you edit a plan.

#### Example: Digital Subscription[​](#example-digital-subscription "Direct link to Example: Digital Subscription")

Here is a complete walkthrough of how offers, plans, products, and entitlements work together.

**Setup (configured by an admin):**

1. Create two products: **Digital Access** and **Print Edition**.
2. Create an offer called **Subscribe** with three plans:

| Plan                   | Products granted              | Duration | Price    |
| ---------------------- | ----------------------------- | -------- | -------- |
| Monthly Digital        | Digital Access                | 1 month  | $9.99/mo |
| Annual Digital         | Digital Access                | 1 year   | $99/yr   |
| Annual Digital + Print | Digital Access, Print Edition | 1 year   | $149/yr  |

**Member experience:**

1. A member visits your subscription page and sees the three plans.

2. They select **Annual Digital + Print** and complete the checkout.

3. The system creates two entitlements for them:

   * **Digital Access** — active for 1 year from today
   * **Print Edition** — active for 1 year from today

4. From that point on, any access check for "Digital Access" or "Print Edition" returns active for that member.

#### How Plans Create Entitlements[​](#how-plans-create-entitlements "Direct link to How Plans Create Entitlements")

When a member selects a plan and the action completes successfully, Allegro creates one entitlement per product defined on that plan. The entitlements are set according to the plan's duration:

* If the plan has a duration, the entitlement's start date is set to today and the end date is calculated from the duration.
* If the plan has no duration, the entitlement is created with no end date and does not expire.

If the member already holds an active entitlement for one of the products (for example, they are renewing), a new entitlement is created alongside the existing one. The member's access continues uninterrupted.

note

Entitlements created by a plan are linked back to that plan. You can see the source of each entitlement on the member's profile.

#### Related[​](#related "Direct link to Related")

* [Entitlements](/product/entitlements.md) — Products, active access, and manually managing entitlements
* [Audience](/product/audience.md) — Browsing and managing member profiles
* [One-off Purchases](/developer/guides/payment/purchases.md) — Initiating checkout from the SDK


---

### Payment Provider

A payment provider handles the checkout flow for paid [Offers](/product/entitlements/offers.md). When a payment provider is connected, members can complete purchases through a hosted checkout page and receive their entitlements automatically on success.

#### How It Works[​](#how-it-works "Direct link to How It Works")

When a member selects a paid plan:

1. Allegro creates a hosted checkout session with your connected payment provider.
2. The member is redirected to the provider's checkout page to complete payment.
3. The provider notifies Allegro when payment succeeds.
4. Allegro creates the entitlements defined by the plan and records the purchase.

#### Connecting a Payment Provider[​](#connecting-a-payment-provider "Direct link to Connecting a Payment Provider")

Go to **Organization Settings → Payment Providers** to see all available providers and their current status.

To connect a provider:

1. Click **Connect** next to the provider you want to set up.
2. You are redirected to the provider's site to authorize the connection. Sign in if prompted.
3. Grant the requested permissions and confirm the connection.
4. You are redirected back to Allegro. The provider's panel updates to show **Connected**.

note

Only one payment provider can be active at a time. If you need to switch providers, disconnect the current one first.

#### Verifying the Connection[​](#verifying-the-connection "Direct link to Verifying the Connection")

Once connected, the provider panel shows the account name and whether charges and payouts are currently enabled on that account. If charges are not enabled, check your account status with the provider directly — additional verification steps may be required.

#### Disconnecting a Provider[​](#disconnecting-a-provider "Direct link to Disconnecting a Provider")

To disconnect:

1. Go to **Organization Settings → Payment Providers**.
2. Click **Disconnect** next to the active provider.
3. Confirm the action.

After disconnecting, paid plans in your offers will no longer initiate checkout. Existing entitlements granted through previous purchases are not affected.

warning

Disconnecting immediately disables payment processing. Any member who attempts to purchase a paid plan will see an error until a payment provider is reconnected.

#### Webhooks[​](#webhooks "Direct link to Webhooks")

Reliable checkout fulfillment depends on webhook notifications from your payment provider. Without a webhook configured, purchases are only recorded when the member is redirected back to your site after checkout — they are missed if the member closes the browser before being redirected.

Contact your platform administrator to confirm the webhook is configured for your Allegro instance.

#### Related[​](#related "Direct link to Related")

* [Offers and Plans](/product/entitlements/offers.md) — Configure paid plans that trigger checkout
* [Entitlements](/product/entitlements.md) — What members receive after a successful purchase
* [Purchases](/product/entitlements/purchases.md) — Browse, refund, and export the resulting transactions
* [One-off Purchases](/developer/guides/payment/purchases.md) — Initiating checkout from the SDK


---

### Plan Fields

Plans come with a name, price, and duration. Plan fields let you record anything else your organization needs to know about a plan, such as a seat limit, a tier label, or an internal cost code. You define the fields once, then fill in a value for each plan.

#### Define a field[​](#define-a-field "Direct link to Define a field")

Open **Organization Settings → Plan Fields** and select **New field**.

| Setting         | Description                                                                                                    |
| --------------- | -------------------------------------------------------------------------------------------------------------- |
| **Name**        | The label shown when you edit a plan.                                                                          |
| **Slug**        | A short identifier using lowercase letters, numbers, and underscores. It cannot be changed later.              |
| **Description** | Optional help text shown under the field when you edit a plan.                                                 |
| **Type**        | Text, Number, Boolean (a checkbox), or Select. A Select field lets you list the allowed values.                |
| **Private**     | Keeps the field's values out of anything delivered to visitors. See [Public and private](#public-and-private). |

Only organization admins can create, edit, or delete plan fields.

#### Public and private[​](#public-and-private "Direct link to Public and private")

A **public** field is available wherever plan details are shared with visitors, such as a template that lists the plans in an offer. Use public fields for details visitors should see, like "Includes 5 seats".

A **private** field is for your team only. Its values are never delivered to visitors, so it is the right choice for internal details like a cost code or an accounting reference. A private field still appears when you edit a plan.

#### Fill in values on a plan[​](#fill-in-values-on-a-plan "Direct link to Fill in values on a plan")

Open any plan from **Entitlements → Plans**. The **Custom fields** card lists every field you have defined. Fill in the ones that apply and select **Save Changes**. Leave a field empty if it does not apply to that plan.

If you have not defined any fields yet, the card links to **Plan Fields** so you can set them up.

#### Changing and deleting fields[​](#changing-and-deleting-fields "Direct link to Changing and deleting fields")

You can change a field's name, description, type, and privacy at any time. If you change the type of a field, review the plans that already have a value for it, since an old value may no longer fit.

Deleting a field removes it from the plan form. Values already saved on plans are discarded the next time you save that plan.

#### Related[​](#related "Direct link to Related")

* [Offers and Plans](/product/entitlements/offers.md)


---

### Purchases

The **Purchases** page is the organization-wide record of every transaction made across your plans. Use it to find a specific payment, review its details, issue a refund, and export transactions for accounting or reconciliation.

To open it, go to **Purchases** in the main navigation.

note

This page lists transactions across your whole organization. To see only the purchases for a single person, open their profile and use the **Purchases** tab. See [Audience](/product/audience.md#purchases).

#### Browsing purchases[​](#browsing-purchases "Direct link to Browsing purchases")

The listing shows every purchase across your plans, most recent first, and paginates at 25 per page. Pending or abandoned checkout sessions are not shown — only purchases that reached a real outcome (such as **Completed**, **Refunded**, or **Failed**) appear.

##### Filtering and searching[​](#filtering-and-searching "Direct link to Filtering and searching")

Three controls above the table narrow the list, and they combine:

| Control    | What it does                                                                                        |
| ---------- | --------------------------------------------------------------------------------------------------- |
| **Search** | Matches by audience member name, email, or payment ID.                                              |
| **Status** | Limits the list to a single purchase status. Choose **All statuses** to clear it.                   |
| **Plan**   | Limits the list to a single plan. Choose **All plans** to clear it. Shown only when you have plans. |

Your active filters are reflected in the page URL, so you can bookmark or share a filtered view. When filters are active and nothing matches, the list shows **No purchases match your filters.** instead of the empty **No purchases found.**

#### Viewing a purchase[​](#viewing-a-purchase "Direct link to Viewing a purchase")

Click any row to open the purchase detail page. The header shows the amount and currency, a status badge, and who was charged and when.

The page is organized into sections:

| Section            | Contents                                                                                                                                                                               |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Activity**       | A timeline of everything that has happened to the purchase, newest first — including when it was created and any refunds, with the admin who performed each action.                    |
| **Summary**        | A line-item breakdown of what was purchased and the total charged.                                                                                                                     |
| **Payment method** | The card brand, last four digits, expiration, type, and country (shown only when the provider supplies card details).                                                                  |
| **Details**        | The payment ID, refund ID, provider, status, and the created and last-updated dates. A **View in Stripe** button links to the transaction in your provider's dashboard when available. |
| **Customer**       | The member's name and email, with links to their **audience member** profile and the **product** they purchased.                                                                       |

The payment ID, refund ID, and customer email are click-to-copy — select one to copy it to your clipboard.

#### Refunding a purchase[​](#refunding-a-purchase "Direct link to Refunding a purchase")

You can issue a full refund directly from the purchase detail page:

1. Open the purchase you want to refund.
2. Click **Refund** (only visible when the purchase status is **Completed**).
3. A confirmation dialog appears. By default the member keeps their access — toggle **Revoke member's access** if you also want to remove the associated entitlement.
4. Confirm the refund. The status updates to **Refunded**, the refund ID appears in the **Details** section, and the refund is recorded in the **Activity** timeline along with the admin who issued it and whether access was revoked.

Once refunded, the **Refund** button is no longer available for that purchase.

note

Refunds are processed through your connected payment provider. Make sure a payment provider is connected in **Organization Settings → Payment Providers** before attempting a refund. See [Payment Provider](/product/entitlements/payment-provider.md).

#### Exporting purchases[​](#exporting-purchases "Direct link to Exporting purchases")

Use the **Export** button to export the purchases that match your current filters — not just the page you're viewing. Exports are generated in the background: Allegro confirms the export has started, then emails you a download link when the file is ready. Completed exports also appear on the [Exports](/product/exports.md) page, where they stay available to download for 7 days.

The file is named `purchases-YYYY-MM-DD.csv` and includes these columns:

`Purchase ID`, `Purchased At`, `Status`, `Amount`, `Currency`, `Provider`, `Provider Payment ID`, `Provider Refund ID`, `Member ID`, `Member Name`, `Member Email`, `Product`, `Plan`.

The **Amount** column is a plain decimal (for example `12.99`) with the currency in its own column, so spreadsheets treat it as a number. As with the listing, pending purchases are excluded.

note

Because the export reflects your active filters, you can export a focused slice — a single plan, a date range, or a search — by narrowing the list before you click **Export**. There is no row cap. See [Exports](/product/exports.md) for the full list of your exports and how long files stay available.

#### Related[​](#related "Direct link to Related")

* [Payment Provider](/product/entitlements/payment-provider.md) — Connect a provider to enable checkout and refunds
* [Offers and Plans](/product/entitlements/offers.md) — Configure the paid plans members purchase
* [Audience](/product/audience.md#purchases) — A single member's purchases


---

### Exports

Allegro can export large lists — your purchases, your audience members, and the members of a segment — as CSV files. Exports are generated in the background, so you can start one and keep working: when the file is ready, Allegro emails you a download link and the export appears on the **Exports** page, ready to download.

To see your exports, go to **Exports** in the main navigation.

#### Starting an export[​](#starting-an-export "Direct link to Starting an export")

You start an export from the page whose data you want:

| Export           | Where to start it                                                               |
| ---------------- | ------------------------------------------------------------------------------- |
| Purchases        | The **Export** button on the **Purchases** page.                                |
| Audience members | The **Export** button on the **Audience** page.                                 |
| Segment members  | **Export CSV** on a segment, on the **Segments** page or in the segment editor. |

Purchase and audience-member exports reflect the **filters and search** active on that page when you click **Export** — so to export a subset, narrow the list first, then export. The whole matching set is included, not just the page you are viewing. A segment export includes every member of the segment as last saved.

After you click **Export**, Allegro confirms that the export is being generated and that it will email you a link when it's ready. You don't need to stay on the page.

How many exports you can start

To keep the queue healthy, you can start up to **three exports per minute**. If you go over, Allegro asks you to wait a few seconds before trying again.

#### The Exports page[​](#the-exports-page "Direct link to The Exports page")

The **Exports** page lists every export across your organization, most recent first, and refreshes on its own while any export is still being generated. Each row shows:

| Column           | Description                                                                                  |
| ---------------- | -------------------------------------------------------------------------------------------- |
| **Type**         | What was exported — Purchases, Audience members, or Segment members with the segment's name. |
| **Status**       | Where the export is in its lifecycle (see below).                                            |
| **Requested by** | The admin who started the export.                                                            |
| **Rows**         | The number of records in the file, once it has finished.                                     |
| **Size**         | The size of the generated file.                                                              |
| **Created**      | When the export was started.                                                                 |
| **Download**     | A **Download** button, shown only while the file is available.                               |

##### Statuses[​](#statuses "Direct link to Statuses")

| Status         | Meaning                                                                |
| -------------- | ---------------------------------------------------------------------- |
| **Pending**    | The export is queued and waiting to start.                             |
| **Processing** | Allegro is building the file.                                          |
| **Completed**  | The file is ready to download.                                         |
| **Failed**     | Something went wrong while generating the file. Start a new export.    |
| **Expired**    | The file was completed but has passed its download window (see below). |

#### Downloading and retention[​](#downloading-and-retention "Direct link to Downloading and retention")

When an export completes, Allegro emails the admin who started it a link to the file, and a **Download** button appears on the export's row. Each file stays available for **7 days** after it was created. After that the export is marked **Expired**, the file is removed, and the **Download** button no longer appears — start a new export to get a fresh copy.

Exports are standard CSV files you can open in any spreadsheet.

##### Purchase columns[​](#purchase-columns "Direct link to Purchase columns")

For the exact columns in a purchases export, see [Purchases](/product/entitlements/purchases.md#exporting-purchases).

##### Audience member columns[​](#audience-member-columns "Direct link to Audience member columns")

An audience-member export is named `audience-members-YYYY-MM-DD.csv` and starts with these columns:

| Column                    | Description                                                                                  |
| ------------------------- | -------------------------------------------------------------------------------------------- |
| `Member ID`               | The member's unique ID.                                                                      |
| `Name`                    | The member's display name, or blank if none is set.                                          |
| `Email`                   | The member's email address.                                                                  |
| `Email Verified`          | `Yes` or `No`.                                                                               |
| `Created At`              | When the member was first created (ISO 8601).                                                |
| `Last Active At`          | When the member last generated an event, or blank if never.                                  |
| `Active Products`         | Names of the products the member currently has an active entitlement to, comma-separated.    |
| `Active Product Slugs`    | The same products by slug, comma-separated.                                                  |
| `Active Entitlements`     | The number of active entitlements the member holds.                                          |
| `Entitlement Expires At`  | The soonest expiry among the member's active entitlements, or blank when they never expire.  |
| `Login Providers`         | The login providers the member has connected (for example `apple, google`), comma-separated. |
| `Completed Purchases`     | The number of completed purchases.                                                           |
| `Lifetime Value`          | The total of all completed purchases as a plain decimal (for example `40.00`).               |
| `Lifetime Value Currency` | The currency of the member's purchases (for example `usd`).                                  |
| `Last Purchase At`        | When the member's most recent completed purchase was made, or blank if none.                 |
| `Properties`              | Names of the properties the member has signed in on, comma-separated.                        |
| `Property Slugs`          | The same properties by slug, comma-separated.                                                |

After these fixed columns, the file adds **one column per [user attribute](/product/audience/user-attributes.md)** your organization has defined, ordered by attribute name. Each cell holds that member's value for the attribute (a boolean attribute reads `Yes` or `No`), and is left blank when the member has no value.

##### Segment member columns[​](#segment-member-columns "Direct link to Segment member columns")

A segment export is named `segment-{segment-name}-YYYY-MM-DD.csv` and has one row per member of the segment, with these columns:

| Column                     | Description                                                        |
| -------------------------- | ------------------------------------------------------------------ |
| `audience_member_id`       | The member's unique ID.                                            |
| `email`                    | The member's email address.                                        |
| `signed_up_at`             | When the member signed up.                                         |
| `member_level`             | The member's membership level.                                     |
| `total_donations`          | The total amount the member has donated.                           |
| `is_donor`                 | Whether the member has made a donation.                            |
| `sign_up_gate_type`        | The kind of sign-up gate the member registered through.            |
| `lifetime_page_views`      | Pages viewed since the member joined.                              |
| `lifetime_days_visited`    | Distinct days visited since the member joined.                     |
| `lifetime_logins`          | Logins since the member joined.                                    |
| `pages_per_visit`          | Average pages viewed per visit.                                    |
| `top_content_section`      | The site section the member reads most.                            |
| `primary_device`           | The device type the member uses most.                              |
| `first_seen`               | When the member was first seen.                                    |
| `last_seen`                | When the member was last seen.                                     |
| `days_since_last_visit`    | Days since the member's last visit.                                |
| `page_views_last_30d`      | Pages viewed over the last 30 days.                                |
| `days_visited_last_30d`    | Distinct days visited over the last 30 days.                       |
| `logins_last_30d`          | Logins over the last 30 days.                                      |
| `engaged_seconds_last_30d` | Time spent actively reading over the last 30 days, **in seconds**. |

A cell is blank when the member has no value for that field.

#### Related[​](#related "Direct link to Related")

* [Purchases](/product/entitlements/purchases.md) — Browse, filter, and export transactions
* [Audience](/product/audience.md) — Browse, filter, and export members
* [Segments](/product/audience/segments.md) — Build and export saved groups of members


---

### Fundraise Up

The Fundraise Up integration copies donations and recurring plans from your Fundraise Up account into Allegro and matches them to audience members by email address. Each matched member gets a donor profile: whether they give once or on a schedule, how much and how often, and the state of each recurring plan.

Allegro receives new activity through a Fundraise Up webhook as it happens, and can read your full history with a backfill.

Turn on the **Fundraise Up** package under **Organization Settings → Packages** first. The settings page then appears at **Organization Settings → Fundraise Up**, and each property gets a **Fundraise Up** page in its own settings.

#### Connect an API key[​](#connect-an-api-key "Direct link to Connect an API key")

1. In Fundraise Up, go to **Settings → API keys** and create a key with these permissions:

   | Section                                    | Data type                          | Permission |
   | ------------------------------------------ | ---------------------------------- | ---------- |
   | **Test data** (test mode) or **Live data** | **Donations**, **Recurring plans** | Read       |
   | **Live data**                              | **Campaigns**                      | Read       |

   Fundraise Up only has live campaigns, so a key used in test mode still needs Read for Campaigns under **Live data**. Allegro uses campaigns to find the key's accounts and to list campaigns for the filter.

2. In Allegro, open **Organization Settings → Fundraise Up** and paste the key into **API key**.

3. Turn on **Test mode** if the key is for Fundraise Up's test data rather than live donations.

4. Click **Save changes**.

Allegro checks the key's permissions with Fundraise Up before saving it. If a permission is missing, the error under the field names it and nothing is saved. If Fundraise Up is busy, try again in a minute.

The key is write-only: after saving, the field shows that a value is stored but never shows the key itself. Enter a new key to replace it, or click **remove it** to delete it on the next save.

note

After a new key is saved, Allegro finds the Fundraise Up accounts it covers in the background. If the key's account has no campaigns yet, the page says so and no donations match until it has one. Every backfill checks the accounts again, so run **Sync now** after the account creates its first campaign.

#### Choose campaigns[​](#choose-campaigns "Direct link to Choose campaigns")

By default every campaign counts. To count only some of them, open **Campaigns** and pick the campaigns to include. Donations and plans to other campaigns are still stored, but they do not appear in donor profiles.

The campaign list loads from Fundraise Up after the page opens. If Fundraise Up cannot be reached, the campaigns you already saved are listed by ID so you can still remove them.

#### Create the webhook in Fundraise Up[​](#create-the-webhook-in-fundraise-up "Direct link to Create the webhook in Fundraise Up")

The **Webhook** section shows the URL Fundraise Up should call. Click **Copy** to copy it.

1. In Fundraise Up, go to **Settings → Webhooks** and create a webhook.
2. Paste the URL from Allegro.
3. Subscribe to the **donation** and **recurring plan** events.
4. Copy the signing secret Fundraise Up shows, paste it into **Signing secret** in Allegro, and click **Save changes**.

Allegro rejects any webhook it cannot verify with the signing secret, so webhooks do nothing until the secret is saved.

The URL uses your organization's canonical domain, for example `https://members.acme.com/api/webhooks/fundraiseup`. If you add or change a custom domain, the URL on this page changes with it. Update the webhook in Fundraise Up to match.

Fundraise Up disables failing webhooks

Fundraise Up turns a webhook off after 48 hours of failed deliveries, and Allegro cannot see that. The **Last webhook** time in the Sync section is your signal: if it stops moving while donations are coming in, check the webhook in Fundraise Up.

#### Properties[​](#properties "Direct link to Properties")

Each property chooses where its Fundraise Up data comes from on its own **Fundraise Up** settings page.

| Mode        | What it does                                                                                                                                                                                    |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Inherit** | Uses the organization's connection. This is the default. The page shows the organization's webhook URL and sync status.                                                                         |
| **Custom**  | Uses the property's own API key, campaigns and webhook. The page shows the same Connection, Webhook and Sync sections as the organization page, and the webhook URL uses the property's domain. |
| **Off**     | Takes no Fundraise Up data for the property.                                                                                                                                                    |

A property on its own connection keeps its donor profiles separate from the organization's. A property that inherits reads the organization's profiles.

#### Sync and backfill[​](#sync-and-backfill "Direct link to Sync and backfill")

The **Sync** section shows:

* when the last webhook arrived,
* the status of the latest backfill, when it started or finished, how many donations and recurring plans it read, and its error if it failed,
* the newest 25 log entries, with a link to the member each entry matched.

Click **Sync now** to read every donation and recurring plan from Fundraise Up again. Use it after connecting a key for the first time. Changing campaigns or a property's connection rebuilds donor profiles on its own, without a sync. The page updates while the sync runs.

Switching **Test mode** starts a full backfill of the new mode on its own and clears the donations and plans Allegro stored for the old mode, unless another connection still reads them. Donor profiles are rebuilt when the backfill finishes, so members only have test or only live data, never both.

**Sync now** runs once every 15 minutes per connection and is disabled while a sync is running. The section says when you can use it again.

A backfill reads Fundraise Up a page at a time and respects Fundraise Up's rate limit, so a large account can take a while. If it stops partway, the next run resumes where it left off.

note

Your engineering team can also run a backfill from the command line with `php artisan fundraiseup:backfill`, optionally limited to one connection (`org` or a property slug) and to records created since a date with `--since`.

#### Donor profile fields[​](#donor-profile-fields "Direct link to Donor profile fields")

Only succeeded, unrefunded donations count toward amounts, counts and dates. Amounts are in the account's default currency.

| Field                           | Description                                                                                                                                                                                                                        |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `donor_status`                  | `recurring` when any plan is active, scheduled, retrying or paused; `lapsed` when the member has plans and none are live; `one_time` when the member has donations and no plans; `none` when the member has only failed donations. |
| `donation_type`                 | The live plan's frequency, such as `monthly`, otherwise `one_time`.                                                                                                                                                                |
| `first_donation_at`             | The date of the member's first counted donation.                                                                                                                                                                                   |
| `last_donation_at`              | The date of the member's most recent counted donation.                                                                                                                                                                             |
| `last_donation_amount`          | The amount of the most recent counted donation.                                                                                                                                                                                    |
| `lifetime_amount`               | The total of all counted donations.                                                                                                                                                                                                |
| `donation_count`                | The number of counted donations.                                                                                                                                                                                                   |
| `currency`                      | The currency the amounts are in.                                                                                                                                                                                                   |
| `recurring_amount`              | The amount of the most recently started live plan.                                                                                                                                                                                 |
| `recurring_started_at`          | When that plan started.                                                                                                                                                                                                            |
| `recurring_next_installment_at` | When that plan charges next.                                                                                                                                                                                                       |
| `recurring_ended_at`            | When the member's last plan ended, if none is live.                                                                                                                                                                                |
| `cancellation_reason`           | Why that plan ended, if Fundraise Up recorded a reason.                                                                                                                                                                            |
| `recurring_status`              | The status of the live plan, or of the last plan that ended: `active`, `scheduled`, `retrying`, `paused`, `canceled`, `completed` or `failed`.                                                                                     |
| `last_failed_donation_at`       | When the member's most recent failed donation was attempted.                                                                                                                                                                       |
| `campaign_ids`                  | The Fundraise Up campaigns the member's counted donations and plans belong to.                                                                                                                                                     |
| `plans`                         | Every recurring plan for the member, keyed by plan ID, with its status, frequency, amount, currency, campaign and dates.                                                                                                           |
| `account_ids`, `supporter_ids`  | The Fundraise Up account and supporter IDs the profile was built from.                                                                                                                                                             |
| `livemode`                      | Whether the profile comes from live or test data.                                                                                                                                                                                  |
| `synced_at`                     | When Allegro last rebuilt the profile.                                                                                                                                                                                             |

A member with no donations, failed or counted, and no plans has no Fundraise Up profile.

#### Target interactions[​](#target-interactions "Direct link to Target interactions")

With the package enabled, the interaction builder's attribute picker has a **Fundraise Up** category. Use it to show or hide an interaction based on a member's giving.

| Attribute                     | Matches on                                                                      |
| ----------------------------- | ------------------------------------------------------------------------------- |
| **Donor status**              | Recurring donor, lapsed recurring donor, one-time donor or never donated.       |
| **Lifetime giving**           | The total of the member's counted donations.                                    |
| **Number of donations**       | How many counted donations the member has made.                                 |
| **First donation**            | When the member first donated.                                                  |
| **Last donation**             | When the member last donated.                                                   |
| **Last donation amount**      | The amount of the member's most recent donation.                                |
| **Recurring amount**          | The installment amount of the live recurring plan.                              |
| **Recurring frequency**       | How often the live plan charges, such as `monthly`.                             |
| **Recurring plan status**     | The status of the live plan, or of the last plan that ended.                    |
| **Next recurring payment**    | The date the live plan charges next.                                            |
| **Cancellation reason**       | Why the member's last plan was canceled.                                        |
| **Recurring payment failing** | Whether the plan is retrying a failed payment or ended because payments failed. |
| **Last failed donation**      | When a donation from the member last failed to go through.                      |
| **Donated to campaign**       | The Fundraise Up campaign IDs the member has given to.                          |

These attributes only apply to signed-in members. An anonymous visitor never matches a Fundraise Up condition, including negative ones such as **Donor status is not Recurring donor**.

A signed-in member without a Fundraise Up profile counts as **Never donated**, with lifetime giving and number of donations of `0`.

Each interaction reads the profile for the property it shows on: the organization's when the property inherits, and the property's own when it has one. On a property with Fundraise Up off, Fundraise Up conditions never match.

Profiles update after each webhook and at least once a day, so a new donation can take a moment to change what a member sees.

#### Send donor fields to SFMC[​](#send-donor-fields-to-sfmc "Direct link to Send donor fields to SFMC")

With the [Salesforce Marketing Cloud](/product/integrations/salesforce-marketing-cloud.md#member-data-sync) package enabled, these donor profile fields can fill SFMC columns. Pick them under **Filled from** in the **Member data sync** column mapping.

| Source                            | Value                                                                                       |
| --------------------------------- | ------------------------------------------------------------------------------------------- |
| **Fundraise Up donor status**     | `donor_status`: `recurring`, `lapsed` or `one_time`; empty for `none`.                      |
| **Fundraise Up donation type**    | `donation_type`: the live plan's frequency, such as `monthly`, otherwise `one_time`.        |
| **Fundraise Up membership start** | When the member's first recurring plan started, counting ended plans. Empty without a plan. |
| **Fundraise Up most recent gift** | `last_donation_at`.                                                                         |

Each SFMC scope reads the profile of the connection its property uses: the organization's when the property inherits, the property's own when it has one, and none when Fundraise Up is off for the property. A member without that profile gets empty values, which clears the columns. A change to the profile updates the member's row.

#### Known gaps[​](#known-gaps "Direct link to Known gaps")

* **Plan endings arrive with the next backfill.** Fundraise Up does not send webhooks when a plan fails, completes or pauses, so those changes appear after the next backfill.
* **Email changes in Fundraise Up.** When a supporter changes their email in Fundraise Up, their next donation matches the member with the new email. Earlier donations stay with the old member, and a backfill does not move them.
* **Shared rate limit.** Two keys on the same Fundraise Up account share Fundraise Up's rate limit. Their backfills slow down and retry rather than run side by side.
* **Abandoned donations.** Fundraise Up shows abandoned donations in its dashboard and exports, but not through its API or webhooks, so Allegro cannot use them.
* **Disabled webhooks.** Allegro cannot tell when Fundraise Up turns a webhook off. Watch the **Last webhook** time.


---

### Salesforce Marketing Cloud

The Salesforce Marketing Cloud (SFMC) integration connects your audience in Allegro to your email program in SFMC. It has four parts, and you can turn on any of them on its own:

| Feature                 | What it does                                                                                                      |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Newsletter lists**    | Subscribes members to SFMC lists and Journey Builder campaigns when they sign in, and reads back their lists.     |
| **Member data sync**    | Keeps one row per member in an SFMC data extension, filled from Allegro data, and updates it whenever it changes. |
| **Subscription Center** | Lets members opt in to and out of newsletters on your site. Their choices are read from and saved to SFMC.        |
| **Welcome event**       | Fires a Journey Builder entry event once per member, so a welcome journey starts when they sign up.               |

Turn on the **Salesforce Marketing Cloud** package under **Organization Settings → Packages** first. The settings page then appears at **Organization Settings → Salesforce Marketing Cloud**, and each property gets a **Salesforce Marketing Cloud** page in its own settings.

The organization page has five tabs: **Connection**, **Newsletter lists**, **Member data sync**, **Subscription Center** and **Welcome event**. **Save changes** on any tab saves every tab at once.

#### Connect your SFMC account[​](#connect-your-sfmc-account "Direct link to Connect your SFMC account")

1. In SFMC, open **Setup → Apps → Installed Packages** and create a package with a **Server-to-Server** API integration. Give it access to what the features you plan to use work with:

   | Feature             | Works with                                       |
   | ------------------- | ------------------------------------------------ |
   | Newsletter lists    | Subscribers and lists, data extensions, journeys |
   | Member data sync    | Data extensions                                  |
   | Subscription Center | Data extensions                                  |
   | Welcome event       | Data extensions, journeys                        |

2. Copy the package's **Client Id**, **Client Secret** and **Authentication Base URI**.

3. In Allegro, open the **Connection** tab and paste them into **Client ID**, **Client Secret** and **Base Auth URL**. The base auth URL looks like `https://yoursubdomain.auth.marketingcloudapis.com`.

4. Click **Save changes**.

The client ID and secret are write-only: after saving, each field shows that a value is stored but never shows the value itself. Enter a new value to replace it, or click **remove it** to delete it on the next save.

The connection is shared by every property. Properties can use their own data extensions and events, but not their own SFMC account.

Can't connect to SFMC

If Allegro can't sign in to SFMC, a **Can't connect to SFMC** alert appears at the top of the organization and property pages with the error SFMC returned. Nothing is sent to or read from SFMC until it connects, so check the client ID, secret and base auth URL.

##### Data extensions[​](#data-extensions "Direct link to Data extensions")

Several features read from or write to an SFMC data extension. Every field that takes one accepts its name or external key, and suggests the data extensions in your account as you type.

Allegro finds a member's row by email address, so each of these data extensions needs an `EmailAddress` column as its primary key.

After you save a data extension, the column fields suggest its columns. Allegro remembers a data extension's columns for an hour. If you add a column in SFMC, click **Refresh columns** to read them again.

#### Newsletter lists[​](#newsletter-lists "Direct link to Newsletter lists")

The **Newsletter lists** tab subscribes members to lists and campaigns when they sign in, and keeps a copy of their lists in Allegro.

| Field                           | What it controls                                                                                           |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Default list IDs**            | The SFMC lists a member joins when they sign in. Comma-separated, such as `123, 456`.                      |
| **Default campaign IDs**        | The campaigns sent through the signup event when a member signs in. Comma-separated.                       |
| **Signup event definition key** | The Journey Builder entry event fired once for each campaign. It looks like `APIEvent-…`.                  |
| **Preferences data extension**  | A data extension of email preferences to copy into each member's profile. Leave it empty to turn this off. |

##### When members are subscribed[​](#when-members-are-subscribed "Direct link to When members are subscribed")

Allegro subscribes a member when they request a magic link, sign in with a social provider, or are identified on your site. It creates the SFMC subscriber first if the email address is new to SFMC, then adds them to the lists.

For each campaign, Allegro fires the signup event with these values:

| Value                              | Description                 |
| ---------------------------------- | --------------------------- |
| `EmailAddress`                     | The member's email address. |
| `Record_CreatedDate`               | When the event was sent.    |
| `ProcessedFlag`                    | Always `false`.             |
| `Most_Recent_Acquisition_Campaign` | The campaign ID.            |

Campaigns need a signup event definition key. Without one, no campaign is sent.

Subscribing happens in the background, so it never slows down sign-in. If SFMC rejects a subscription, sign-in still succeeds.

##### Reading lists back[​](#reading-lists-back "Direct link to Reading lists back")

Allegro stores the lists each member belongs to, and the member's row from the preferences data extension, in the `sfmc_email_subscriptions` profile. You can see it on the member's **Data** tab.

Allegro refreshes the profile when a member signs in and their copy is more than 7 days old, and every month for members who signed in within the last 30 days.

#### Member data sync[​](#member-data-sync "Direct link to Member data sync")

The **Member data sync** tab keeps one row per member in an SFMC data extension, so your journeys and segments in SFMC can use Allegro data.

1. Pick the **Data extension** to write to.
2. Under **Column mapping**, click **Add column** for each column to fill. Pick the **SFMC column** and what it is **Filled from**.
3. Click **Save changes**.

Leave **Data extension** empty to stop sending members.

##### Column sources[​](#column-sources "Direct link to Column sources")

| Source                                                     | Value                                                                                                   |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Audience Member ID**                                     | The member's Allegro ID.                                                                                |
| **Email**                                                  | The member's email address.                                                                             |
| **Last active**                                            | When the member was last active.                                                                        |
| **Profile updated**                                        | When the member's profile last changed.                                                                 |
| **Joined**                                                 | When the member joined the property. On the organization page, when they created their account.         |
| Any [user attribute](/product/audience/user-attributes.md) | The attribute's value for the member.                                                                   |
| ***column* (Subscription Center)**                         | Whether the member is subscribed to that newsletter in the [Subscription Center](#subscription-center). |

Other installed packages can add their own sources to this list. With [Fundraise Up](/product/integrations/fundraise-up.md#send-donor-fields-to-sfmc), these include the member's donor status, donation type, membership start and most recent gift.

Allegro formats values the way SFMC expects them: true/false values as `True` and `False`, and dates as `YYYY-MM-DD HH:MM:SS` in UTC. A value the member doesn't have clears the column.

##### When rows are updated[​](#when-rows-are-updated "Direct link to When rows are updated")

Allegro writes a member's row when they:

* sign up, or join a property,
* have a mapped attribute set, changed or removed,
* change a newsletter in the Subscription Center,
* have their Fundraise Up donor profile change, when a Fundraise Up source is mapped.

Allegro waits 30 seconds before writing, so a form that saves several attributes at once produces a single update.

If the mapping names a column the data extension doesn't have, Allegro writes the other columns and skips that one until you add it in SFMC.

#### Subscription Center[​](#subscription-center "Direct link to Subscription Center")

The **Subscription Center** tab connects the newsletter preferences members see on your site to an SFMC data extension that holds one row per subscriber, with a true/false column for each newsletter.

| Field                               | What it controls                                                                                                                                |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Data extension**                  | The preferences data extension. Leave it empty to stop reading and writing preferences.                                                         |
| **Editable newsletters**            | The newsletters members can change. For each, the true/false **Subscribed column** and the **Last change date column** set whenever it changes. |
| **Values for a new row**            | Columns to fill the first time a member's row is created, such as newsletters they start out on. Ignored once the row exists.                   |
| **Global subscription column**      | The true/false column for whether the member gets email at all.                                                                                 |
| **Global subscription date column** | Set when the global subscription is turned on, and when a member's row is first created.                                                        |
| **Opting in subscribes globally**   | When on, a member who opts in to any newsletter is also subscribed globally. Requires both global columns.                                      |

##### How changes are saved[​](#how-changes-are-saved "Direct link to How changes are saved")

When a member changes their preferences, Allegro reads their current row from SFMC, then writes:

* `True` or `False` in each newsletter column they changed, and the current time in its last change date column,
* the global subscription column, when **Opting in subscribes globally** is on and they opted in to something,
* the **Values for a new row**, when SFMC had no row for them yet.

Members can opt out of everything by turning off the global subscription. They can't turn it on directly; that happens when they opt in to a newsletter.

A member who has no row in SFMC and only opts out of something gets no row.

Allegro keeps a copy of each member's row in the `sfmc_subscription_center` profile, refreshed on the same schedule as newsletter lists. A member who has never been read from SFMC is read when they first open their preferences, so they are never shown as unsubscribed by mistake.

##### Preferences API[​](#preferences-api "Direct link to Preferences API")

Your site reads and saves a signed-in member's preferences through these endpoints. They use the member's Allegro session, the same way the SDK does, and accept 30 requests a minute.

| Method  | Path                                               | Description                                                                                         |
| ------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `GET`   | `/api/sfmc/communication-preferences`              | The member's row and editable newsletters for the property the site is on, else the organization's. |
| `PATCH` | `/api/sfmc/communication-preferences`              | Saves changes for that same Subscription Center.                                                    |
| `GET`   | `/api/sfmc/organization/communication-preferences` | The member's organization row, whichever property the site is on.                                   |
| `PATCH` | `/api/sfmc/organization/communication-preferences` | Saves changes to the organization's Subscription Center.                                            |

A `PATCH` takes the newsletter columns to change:

```json
{
    "subscription_data": {
        "Daily_Newsletter": true,
        "Weekend_Edition": false
    }
}

```

Both methods return the member's row, the columns they can change and the global column:

```json
{
    "data": {
        "property": "news",
        "subscription_data": {
            "EmailAddress": "jane@example.com",
            "Daily_Newsletter": "True",
            "Weekend_Edition": "False",
            "Global_Opt_In": "True"
        },
        "editable_columns": ["Daily_Newsletter", "Weekend_Edition"],
        "global_column": "Global_Opt_In"
    }
}

```

| Status | Code                              | When                                                                                          |
| ------ | --------------------------------- | --------------------------------------------------------------------------------------------- |
| `404`  | `SUBSCRIPTION_PROFILE_NOT_FOUND`  | The Subscription Center is off, doesn't apply to the member, or SFMC can't be read right now. |
| `422`  | `INVALID_SUBSCRIPTION_PREFERENCE` | The request names a column that isn't an editable newsletter.                                 |
| `502`  | `SUBSCRIPTION_UPDATE_FAILED`      | SFMC rejected the change. Nothing was saved.                                                  |

#### Welcome event[​](#welcome-event "Direct link to Welcome event")

The **Welcome event** tab fires a Journey Builder entry event once per member, typically the entry to a welcome journey.

| Field                    | What it controls                                                                                          |
| ------------------------ | --------------------------------------------------------------------------------------------------------- |
| **Event definition key** | The journey's entry event. Leave it empty to turn the welcome event off.                                  |
| **Data extension**       | The data extension the event writes to. Required with an event definition key.                            |
| **Fire when**            | When the member signs up or joins a property (the default), or when a chosen user attribute is first set. |

If your registration form collects details after the email address, pick the attribute the form writes last under **Fire when**. The event then waits until the member has filled in the form, so the journey has their details.

The event carries the member's [member data sync](#member-data-sync) values for the columns the welcome data extension has, plus `EmailAddress`, `Record_CreatedDate` (when they joined) and `ProcessedFlag` (`false`). Values the member doesn't have are left out, because SFMC rejects an event with an empty true/false or date value.

Allegro waits 30 seconds after the trigger before firing, and records that the event fired so the member never enters the journey twice. A property with its own welcome event fires it separately for its members.

#### Properties[​](#properties "Direct link to Properties")

Each property chooses where each feature's settings come from on its own **Salesforce Marketing Cloud** settings page. The page has a tab for each feature with a **Settings** choice at the top:

| Setting                       | What it does                                                                                                                                 |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Use organization settings** | Uses the organization's settings, shown read-only with a link to edit them. This is the default.                                             |
| **Use custom settings**       | Uses the property's own data extension, mapping or event instead of the organization's. The fields are the same as on the organization page. |
| **Off**                       | The feature doesn't run for the property's members.                                                                                          |

A member gets each feature from every property they've joined: from the organization for properties that inherit, from the property for ones with custom settings, and not at all for ones that are off. A member of no property gets the organization's. So a member of two properties with custom member data sync has a row in both properties' data extensions.

For member data sync and the welcome event, **Joined** and **Fire when** on a property mean joining that property.

##### Property newsletter lists[​](#property-newsletter-lists "Direct link to Property newsletter lists")

On a property's **Newsletter lists** tab, **Use custom settings** adds:

| Field                           | What it controls                                                                                                                        |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Newsletter list IDs**         | The SFMC lists this property owns. Only these are copied into the property's profile. Leave it empty to copy all of the member's lists. |
| **Default list IDs**            | Lists a member joins when they sign in on this property, instead of the organization's.                                                 |
| **Default campaign IDs**        | Campaigns sent when a member signs in on this property, instead of the organization's.                                                  |
| **Signup event definition key** | The journey event fired for each of this property's campaigns. Required when the property has default campaigns.                        |
| **Preferences data extension**  | A data extension of email preferences to copy into the property's profile.                                                              |

A property with custom newsletter settings and either newsletter list IDs or a preferences data extension gets its own profile for each member, named `sfmc_email_subscriptions:` followed by the property's slug, such as `sfmc_email_subscriptions:news`. The organization's `sfmc_email_subscriptions` profile keeps updating alongside it.

With newsletters **Off**, members who sign in on the property aren't subscribed to any default lists or campaigns.

##### Subscription Centers on properties[​](#subscription-centers-on-properties "Direct link to Subscription Centers on properties")

The Subscription Center the [preferences API](#preferences-api) uses depends on the site the member is on. On a property with its own Subscription Center, members manage that property's newsletters, and must have joined the property. Use the `organization` endpoints to also show the organization's newsletters on that site.

#### Member profiles[​](#member-profiles "Direct link to Member profiles")

The integration stores these profiles on each member. They appear on the member's **Data** tab, and you can fill user attributes from them with [Sync from external profiles](/product/audience/user-attributes.md#syncing-from-external-profiles).

| Profile                           | Contents                                                                                          |
| --------------------------------- | ------------------------------------------------------------------------------------------------- |
| `sfmc_email_subscriptions`        | `list_ids`, the SFMC lists the member belongs to, and `subscription_data`, their preferences row. |
| `sfmc_email_subscriptions:{slug}` | The same for one property with its own newsletter settings.                                       |
| `sfmc_subscription_center`        | The member's Subscription Center rows, under `organization` and under `properties.{slug}`.        |

#### Known gaps[​](#known-gaps "Direct link to Known gaps")

* **Changes made in SFMC arrive later.** Allegro doesn't hear about changes made directly in SFMC, such as an unsubscribe from an email footer. They appear in Allegro at the member's next refresh.
* **Failed writes retry, then stop.** Allegro retries a data extension write or welcome event three times over a few minutes. If SFMC is still failing, the row waits until the member's data next changes, and the welcome event until its trigger happens again.
* **Failed subscriptions aren't retried.** If SFMC rejects a list subscription or campaign at sign-in, Allegro logs it and moves on.
* **New columns need a refresh.** Columns added in SFMC appear in Allegro's suggestions within an hour, or right away after **Refresh columns**.
* **Email address is the key.** Rows are matched by email address. When a member's email changes, their next write creates a new row under the new address, and the old row stays in SFMC.


---

### Interactions

Interactions are how you deploy experiences to your site. Each Interaction bundles one or more [actions](/product/interactions/actions.md) — template injections, JavaScript, cookies, and CSS — and decides when they run on a visitor's page.

An Interaction runs in one of two modes:

* **Automatic targeting** — Allegro evaluates the Interaction on every page view and runs the actions of the first [journey](/product/interactions/journeys.md) the visitor matches. No code changes on your site are needed.
* **Manual embed** — your site triggers the Interaction by its slug from your own code, and every action runs in the order you defined.

![Interactions](/assets/images/interactions-1e65cafdd88ea80f7ebf09cca41787d7.png)

#### How Interactions Relate to Templates[​](#how-interactions-relate-to-templates "Direct link to How Interactions Relate to Templates")

[Templates](/product/interactions/templates.md) are reusable content blocks. An Interaction uses a Template by referencing it in a Template action and filling in its field values. The same Template can appear in many Interactions, each with different field values and placement settings.

```text
Template  ──used by──►  Action  ──belongs to──►  Journey  ──belongs to──►  Interaction
(content block)          (what & where)           (who sees it)             (the deployable unit)

```

You must publish a Template before you can select it in an action.

#### Trigger Modes[​](#trigger-modes "Direct link to Trigger Modes")

| Mode                    | How the Interaction fires                                                                                                                                      | What the editor shows                                                                                                                      |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Automatic targeting** | Allegro evaluates every published automatic Interaction on each page view. The visitor follows the first journey whose conditions match, or **Everyone else**. | The [Journeys](/product/interactions/journeys.md) builder, with the **Meters**, **Evaluate**, **Assistant**, and **Potential reach** tools |
| **Manual embed**        | Your site calls `allegro.interaction.trigger('slug')`. All actions run in order.                                                                               | A single action list and the slug field, with **Show snippet** in the **⋯** menu once the Interaction is published                         |

New Interactions start in **Automatic targeting**. To switch to Manual embed, click **Or trigger it from your own code — make it a manual interaction** in the empty builder; the option is offered only while the Interaction has no journeys. A Manual embed Interaction has a **Use automatic targeting** button above its action list to switch back. Switching keeps the journeys: they stop being used in Manual embed mode and come back when you switch back. In Manual embed mode, journey errors are not shown inline; a banner asks you to switch to Automatic targeting to fix them.

![A Manual embed Interaction, with the Use automatic targeting button above its action list](/assets/images/manual-embed-8cfb2c8bd3ad72b73c1423475d775131.png)

note

In Automatic targeting mode the slug is generated for you and hidden, in the editor and in the Interactions list. In Manual embed mode you can edit the slug while the Interaction is still a draft.

tip

The Interactions list has a trigger filter beside the search box. Choose **All triggers**, **Manual**, or **Automatic** to narrow the list by mode.

#### Lifecycle[​](#lifecycle "Direct link to Lifecycle")

| Status        | Meaning                                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------------- |
| **Draft**     | Work in progress. A draft never fires on your site, in either mode.                                           |
| **Published** | Live. An automatic Interaction is evaluated on every page view; a manual one runs when your site triggers it. |
| **Archived**  | Soft-deleted. Removed from normal listings, can be restored or permanently deleted.                           |

New Interactions start as Draft. Publish when you are ready to go live. You can unpublish a live Interaction at any time to return it to Draft.

note

Archiving an Interaction does not affect the Templates it references. Those Templates remain intact.

#### Creating an Interaction[​](#creating-an-interaction "Direct link to Creating an Interaction")

1. Go to **Interactions → New Interaction**. The Interaction opens as an **Untitled interaction** in Draft, in Automatic targeting mode.
2. Click the title in the header, or choose **Rename** from the **⋯** menu, to name the Interaction.
3. Click **Add your first journey** to build your first [journey](/product/interactions/journeys.md), or **Build it with a prompt** to let the [Assistant](/product/interactions/assistant.md) draft one. Add actions to the **Everyone else** card for visitors who match no journey.
4. For Manual embed instead, click **make it a manual interaction** in the empty builder, then click **Add action** and configure each [action](/product/interactions/actions.md).
5. Click **Save draft** to save without publishing, or **Publish** to go live.

![A new Interaction\&#39;s empty builder, with Add your first journey, Build it with a prompt, and the link to make it a manual Interaction](/assets/images/builder-empty-781ec12854c463c895a0d6178ef8249e.png)

#### Editing Safely[​](#editing-safely "Direct link to Editing Safely")

Several safeguards protect an Interaction while you work on it.

**Edit lock.** Opening an Interaction that someone else is editing shows a banner. Click **Start editing** to claim it, or **Take over editing** if the other editor has gone idle. While you hold the lock, other editors see the Interaction read-only.

**Undo and redo.** Every change in the editor can be undone with `Cmd`/`Ctrl`+`Z` and redone with `Cmd`/`Ctrl`+`Shift`+`Z` (or `Ctrl`+`Y`). Undo and redo buttons appear in the header once there is something to undo. Inside a text field the shortcut edits the text as usual, and while a dialog is open the shortcuts are paused.

**Reset.** When the header shows **Unsaved changes**, click **Reset** beside it to return to the last saved version. Reset is itself undoable.

**Revision notes.** When you save a published Interaction, the **Update Interaction** dialog asks for an optional revision note before the save completes. Click **Write a note with AI** (the sparkle button in the note field) to have the assistant draft a one-line summary of what changed, which you can edit or replace before saving.

#### Publishing and Unpublishing[​](#publishing-and-unpublishing "Direct link to Publishing and Unpublishing")

To publish a draft Interaction, click **Publish** on the edit page. Once it is published, the button reads **Save & publish** and saves your changes straight to the live version.

To unpublish a live Interaction, choose **Unpublish** from the **⋯** menu on the edit page or from its actions menu in the Interactions list. Unpublishing returns the Interaction to Draft status — it stops firing on your site.

Only published Interactions in Automatic targeting mode are evaluated on your site. Publishing an automatic Interaction is all it takes to go live; there is no snippet to install.

#### Activation Code (Manual Embed)[​](#activation-code-manual-embed "Direct link to Activation Code (Manual Embed)")

For an Interaction in Manual embed mode, choose **Show snippet** from the **⋯** menu in the header after publishing to see the JavaScript that triggers it on your site. Copy it and place it wherever you want the Interaction to fire — for example, inside a post template or a tag manager rule.

```js
window.allegro = window.allegro || [];
window.allegro.push(function () {
    window.allegro.interaction.trigger('your-interaction-slug');
});

```

Replace `your-interaction-slug` with the slug shown in the dialog. Automatic Interactions have no snippet and do not need one.

#### Measuring Performance[​](#measuring-performance "Direct link to Measuring Performance")

Once a published Automatic targeting Interaction has been running, choose **View report** from the **⋯** menu to see how often it ran, broken down by journey and by day, with CSV and PDF downloads. Each journey header in the builder also shows an activity pill that links to the same report. See [Report](/product/interactions/report.md).

#### Previewing a Draft on Your Site[​](#previewing-a-draft-on-your-site "Direct link to Previewing a Draft on Your Site")

A draft Interaction in Manual embed mode can be previewed on any live page that has the Allegro SDK loaded, without publishing it.

1. Open the draft Interaction and click the **Preview** icon in the header.
2. In the **Preview on site** dialog, enter the URL of a page on your site.
3. Click **Generate preview link**.
4. Open the link in your browser. A floating **Draft preview** badge appears on the page, and the draft Interaction fires when triggered as normal.

The preview link expires after 30 minutes. The badge can be dismissed, which ends the preview session.

note

The preview URL must begin with `https://`. The draft content is served only to the browser that holds the preview token — regular visitors see the published version (or nothing, if the Interaction is not yet published).

To check an automatic Interaction on your site, use [Debug on site](/product/interactions/testing.md#debug-on-site) instead.

#### Duplicating[​](#duplicating "Direct link to Duplicating")

Choose **Duplicate** from an Interaction's actions menu in the list to create a draft copy. The copy keeps the trigger mode, every journey, and every action.

#### Archiving and Deletion[​](#archiving-and-deletion "Direct link to Archiving and Deletion")

To archive an Interaction, open its actions menu in the Interactions list and choose **Archive**.

Archived Interactions:

* Do not appear in the default list view
* Can be restored to Draft status
* Can be permanently deleted by Admins only

To view archived Interactions, switch to the **Archived** tab on the Interactions list. To restore one, open its actions menu and choose **Restore**.

warning

Permanently deleting an Interaction removes it and all its revision history. This cannot be undone.

#### Revision History[​](#revision-history "Direct link to Revision History")

Every save that changes an Interaction records a revision. Click **History** in the header (beside it, the number of revisions) to open the panel. Each revision is listed with who saved it, when, and a short summary such as **"Everyone else" actions changed**. Each revision has a **Changes** tab that summarizes what changed — including the trigger mode, journeys, conditions, and actions — and a **Configuration** tab that shows the full state at that point.

![Revision history, listing each revision with a Changes tab and Restore this revision](/assets/images/revision-history-25a9533281b86d6ba7e9ed85108c7f15.png)

Restoring a revision that predates automatic targeting returns the Interaction to Manual embed mode with no journeys, so an old snapshot never leaves an Interaction silently running its current journeys.

See [Revisions](/product/interactions/revisions.md) for how revisions and rollback work.

#### Authorization[​](#authorization "Direct link to Authorization")

For details on who can manage interactions, see [Permissions](/product/administration/permissions.md).

#### Related[​](#related "Direct link to Related")

* [Actions](/product/interactions/actions.md) — What an Interaction does, where, and when
* [Journeys](/product/interactions/journeys.md) — Who sees which actions in Automatic targeting
* [Cohorts](/product/interactions/cohorts.md) — Reusable condition sets, under **Interactions → Cohorts** in the sidebar
* [A/B Tests](/product/interactions/ab-tests.md) — Split visitors into variants, under **Interactions → A/B tests** in the sidebar
* [Testing Journeys](/product/interactions/testing.md) — Simulate visitors and debug on your site
* [Report](/product/interactions/report.md) — How an automatic Interaction actually performed
* [Templates](/product/interactions/templates.md) — Reusable content blocks consumed by Template actions
* [Revisions](/product/interactions/revisions.md) — Full version history and rollback


---

### A/B Tests

An A/B test splits an audience into named **variants** by weight. The variant is only a label: it decides nothing on its own. Journeys read it through the **A/B test variant** [condition](/product/interactions/conditions.md), so the same test can drive several interactions, and each interaction decides what a variant sees.

#### Creating a Test[​](#creating-a-test "Direct link to Creating a Test")

Open **Interactions → A/B tests** in the sidebar, then click **New A/B test**. The list has **All**, **Drafts**, **Running**, and **Concluded** tabs. The form walks through four steps, with a **Test plan** summary beside it:

* **What you're testing.** A name your team will recognize in journeys and reports, and an optional hypothesis.
* **Who takes part.** *All visitors* buckets everyone by their device, so anonymous readers take part and a bucket survives signing in on the same device. *Signed-in members* buckets by member, so the variant follows them across devices and anonymous visitors are never in the test. **Share of that audience in the test** sets how many take part; visitors outside it are *not in the test* and match none of its variants.
* **Variants.** Two to ten named variants with whole-number percent weights of at least 1 that add up to 100. **A** is the **control** every other one is compared against. **Split evenly** balances the weights.
* **How a winner is picked.** **Conversion rate**, the share of visitors who complete one of the event types you choose (purchase, sign up, and so on), or **Page views per visitor**. **Run for** sets how many days the test runs once started: **7 days**, **14 days**, **30 days**, or a number you enter. **Roll out the winner automatically** gives every eligible visitor the winning variant once the test ends with a clear winner.

**Save draft** keeps the test without bucketing anyone; **Save and start** starts it right away.

![The New A/B test form beside its Test plan summary](/assets/images/ab-test-form-39176ce65a29d58d70f4a76938edd659.png)

Assignment is deterministic: the same visitor lands in the same variant on every page view, with nothing stored on the server. Changing the audience, share, or variants of a draft re-randomizes assignments.

#### Targeting a Variant[​](#targeting-a-variant "Direct link to Targeting a Variant")

In a journey, add the **A/B test variant** condition, choose the test, then choose the variants with **is any of** or **is none of**. A visitor who is not in the test, whether outside the traffic share, ineligible for the audience, or because the test is still a draft, matches neither operator. "Is none of Control" therefore means "in the test, in another variant", not "anyone but the control group".

A draft test can already be referenced, so you can build journeys before starting it. Journeys match no one until the test starts.

#### Lifecycle[​](#lifecycle "Direct link to Lifecycle")

* **Draft.** Fully editable. Nobody is bucketed.
* **Running.** Click **Start test** on the test's page. The audience, share, variants, duration, and KPI freeze so the results keep meaning something; the name, hypothesis, and **Roll out the winner automatically** stay editable. **End now** finishes early.
* **Concluded.** At the scheduled end, Allegro fetches results from the analytics service and records the winner. Assignments keep resolving the same way until you roll a variant out, so nothing changes under visitors by surprise.

A concluded test never restarts; create a new one instead. A test can't be archived while an interaction's journeys still reference it.

#### Results and the Winner[​](#results-and-the-winner "Direct link to Results and the Winner")

The test's page shows, per variant, how many visitors were exposed, the KPI value, lift over the control, and, for conversions, the confidence that the variant really differs from the control.

A winner is declared only when every variant has reached the minimum exposure (100 visitors by default) and, for the conversions KPI, the leader beats the control at 95% confidence. Otherwise the test completes with **no clear winner** and nothing rolls out automatically; you can still **Roll out** any variant by hand.

How results are measured

Every event the site tag sends carries the visitor's current assignments, so the analytics service can count page views and conversions per variant. Variant ids are opaque labels; no rule or profile data leaves the server.

#### Sharing a Report[​](#sharing-a-report "Direct link to Sharing a Report")

Once a test is running, click **View report** on its page for a summary you can share with stakeholders. It shows the test's setup and dates, the headline result, total participants and conversions, and for each variant its participants, planned and actual split, conversions, conversion rate with a 95% confidence range, lift, and confidence. A page-views test shows page views and page views per participant instead of conversions and conversion rate, with no confidence range.

If participants didn't land in each variant in the proportions the test was set up with, the report warns that the split is off from plan. That usually means assignment or tracking is broken, so treat the results with caution.

* **Download PDF** opens your browser's print dialog. Choose **Save as PDF** as the destination.
* **Download CSV** saves one row per variant, with rates and shares as decimals for spreadsheets.

Anyone in the organization can open a report, including viewers.

#### Simulating and Debugging[​](#simulating-and-debugging "Direct link to Simulating and Debugging")

The journey builder's **Evaluate** panel lets you pick a variant per test for the simulated visitor, with **Not in test** as the default. The on-site debug workbench shows the assignments the server resolved for the current visitor, and `allegro.interaction.experiments()` returns them to page scripts as `{ "<test id>": "<variant id>" | null }`.


---

### Actions

Actions are the individual steps an Interaction performs on a visitor's page. In Automatic targeting mode, every [journey](/product/interactions/journeys.md) has its own action list, and so does the **Everyone else** card. In Manual embed mode the Interaction has a single action list. Wherever they live, actions are built and edited the same way.

#### Action Types[​](#action-types "Direct link to Action Types")

| Type               | What it does                                                                     |
| ------------------ | -------------------------------------------------------------------------------- |
| **Template**       | Renders a published [Template](/product/interactions/templates.md) into the page |
| **Component**      | Shows a ready-made login form, signup form, gate, and more                       |
| **Run JavaScript** | Executes your own script on the page                                             |
| **Apply CSS**      | Injects styles into the page                                                     |
| **Cookie**         | Sets a cookie on the visitor                                                     |
| **Frequency cap**  | Limits how often the actions inside it run                                       |

**Frequency cap** is available in Automatic targeting mode only, because the count happens when a journey matches.

#### The Action List[​](#the-action-list "Direct link to The Action List")

Click **Add action** and choose a type. The new action opens in the action editor right away; canceling the editor at that point removes the action again.

![The Add action menu: Template, Component, Run JavaScript, Apply CSS, Cookie, and Frequency cap](/assets/images/add-action-menu-32082abec34419aa59583f08a2619d3b.png)

Actions run in list order, top to bottom. Drag a row to reorder, or use the arrow buttons. In Automatic targeting mode you can also drag a row into another journey's action list, or into **Everyone else**, to move it there. Click a row to open it in the editor. A row shows a **Needs attention** chip when the action has a validation error.

#### The Action Editor[​](#the-action-editor "Direct link to The Action Editor")

Every action opens in the same editor dialog. The header shows the action's name (click it to rename; names are up to 80 characters and appear in the action list and in revision history) and where the action lives, such as `VIP readers · Action 1 of 2` or `Everyone else · Action 1 of 1`.

Below the header, a type switcher lets you change the action's type: **Render template**, **Show component**, **Run JS on page**, **Apply CSS**, or **Set cookie**. Switching away from a type and back restores what you had entered.

The body has up to three sections:

| Section              | Purpose                                           | Shown for                                                          |
| -------------------- | ------------------------------------------------- | ------------------------------------------------------------------ |
| **What it does**     | The template, component, code, or cookie to apply | All types                                                          |
| **Where it applies** | The part of the page the action targets           | Template and Component (JS and CSS show a fixed "whole page" card) |
| **When it runs**     | The delay before the action executes              | All types                                                          |

Template and Component actions also get a live placement preview beside the sections, with a one-line recap such as "Added immediately before the area." Component actions also show a live render of the component on a sample article, which updates as you change its settings.

Changes are held as a draft until you click **Save action**. **Cancel**, `Esc`, or clicking outside the dialog discards the draft. **Delete action** removes the action from its list.

#### What It Does[​](#what-it-does "Direct link to What It Does")

##### Template[​](#template "Direct link to Template")

Click **Select** (or **Change**) to pick a published Template. If the Template defines fields, a **Fields** summary lists them by tab, and **Edit Fields** (or a tab's row) opens a drawer to fill in the values this action uses. Each field starts with the Template's default, and edits apply as you type; click **Done** to return, then save the action. Fields you don't edit keep following the Template's defaults.

![A Render template action with the selected template, its fields, and where it applies](/assets/images/template-action-dc895e74d3b90bf1a29e9fb5d00cde17.png)

##### Component[​](#component "Direct link to Component")

A Component action shows one of Allegro's ready-made components, with no Template to build first. Choose a component from the picker:

![The component chooser, grouped into Forms, Gates, and Content](/assets/images/component-chooser-e9e309061c7464022177eea416ffd213.png)

| Group   | Component               | What it shows                                                                      |
| ------- | ----------------------- | ---------------------------------------------------------------------------------- |
| Forms   | **Login Form**          | Signs readers in with an emailed link or code, or a social login                   |
| Forms   | **Email Form**          | Collects an email address, with an optional disclaimer                             |
| Forms   | **Form**                | One of your [Forms](/product/audience/forms.md), for signed-in members to fill out |
| Gates   | **Content Gate**        | A dialog over the page that blocks reading until the reader signs up               |
| Gates   | **Content Gate Inline** | A gate in the article that hides the rest of it until the reader signs up          |
| Content | **Recommendations**     | A "Read next" list of articles picked for the reader                               |

Once you choose one, its settings appear below it: text such as button labels and headings, choices such as the login method, and on/off switches. Each setting explains what it controls, and an empty field uses the component's own default. Settings for developers, such as tracking data, are under **Advanced**. Click **Change** to choose a different component; settings the two components share are kept.

![Content Gate settings beside a live preview on a sample article](/assets/images/content-gate-1f895671095af4d141e188375d325436.png)

###### Inside the gate[​](#inside-the-gate "Direct link to Inside the gate")

The two gates show something inside them. Under **Inside the gate**, enter an optional **Heading** and **Message**, then pick the form readers fill in to get past the gate. **Login Form** and **Email Form** are offered first; choose **Another component…** for any other. Click **Customize** to change the inner form's own settings.

tip

A **Content Gate** with a **Login Form** inside makes a registration wall in a few clicks: set its heading to "Keep reading for free", turn off **Dismissible**, and [truncate the article](#truncating-the-article-behind-a-gate) behind it.

##### Run JavaScript[​](#run-javascript "Direct link to Run JavaScript")

Write any valid JavaScript in the code editor. The code runs in the context of the page when the action executes. Use this for analytics events, third-party integrations, or custom behavior that doesn't fit a Template. Click **Format** to tidy the code.

caution

JavaScript actions run in your visitors' browsers. Only use trusted code here.

##### Apply CSS[​](#apply-css "Direct link to Apply CSS")

Write standard CSS in the code editor. The styles apply globally to the page when the action executes. Because templates render inside a shadow root, their own CSS stays inside the template; use a CSS action to hide elements, adjust layout, or apply theme overrides on the page itself.

##### Cookie[​](#cookie "Direct link to Cookie")

| Setting                 | Description                                                                                                                                                                                                                                                                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Set readable cookie** | On by default for new cookie actions. A readable cookie's name gets an `_al_` prefix (`promo_seen` is stored as `_al_promo_seen`), which lets journeys target it with a [Cookie condition](/product/interactions/conditions.md#cookies). Turn it off to set a cookie with exactly the name you enter; Allegro can't read that cookie back. |
| **Name**                | The cookie name (for example `promo_seen`). With **Set readable cookie** on, the `_al_` prefix is shown in front of the field and added for you; the name may use only letters, numbers, dashes, and underscores.                                                                                                                          |
| **Value**               | The value to store (for example `1`)                                                                                                                                                                                                                                                                                                       |
| **Keep for**            | `This visit` (a session cookie that clears when the browser closes), `7 days`, `30 days`, `A year`, or `Custom…` for any number of days from 1 to 365. New cookie actions default to 30 days.                                                                                                                                              |
| **Path**                | The URL path the cookie applies to. Defaults to `/` (the entire site).                                                                                                                                                                                                                                                                     |
| **Domain (optional)**   | Restrict the cookie to a specific domain (for example `.acme.com`). Leave empty to use the current domain.                                                                                                                                                                                                                                 |

##### Frequency cap[​](#frequency-cap "Direct link to Frequency cap")

A frequency cap wraps other actions and delivers them at most a set number of times in a sliding window — for example, a promo banner at most three times every 24 hours, or a launch announcement once per visitor every 30 days.

![A frequency cap showing at most 3 times every 7 days to each visitor, with a Render template action inside](/assets/images/frequency-cap-32ff6b8e04b8936619cd494ccc95eb9a.png)

| Setting          | Description                                                                                                                                                                                                                              |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Show at most** | How many times the actions inside may run within the window (1 to 1000)                                                                                                                                                                  |
| **Every**        | The length of the window, in minutes, hours, or days, up to 365 days in total. The window slides: an impression stops counting once it is older than the window.                                                                         |
| **To**           | `each visitor` counts every visitor separately — signed-in members by account, everyone else by device. `everyone` keeps one shared count across all visitors, for something that should only happen a limited number of times in total. |

Below the settings, **Actions inside the cap** lists the actions the cap limits. Add Template, Component, Run JavaScript, Apply CSS, and Cookie actions there (a cap cannot contain another cap); each opens in its own editor on top of the cap's. Those actions keep their own placement and timing. The cap itself has none: it is counted the moment the Interaction matches on a page view, whether or not the page goes on to render the actions.

Changing the limit, the window, or who it applies to starts the count over. Renaming the cap or editing the actions inside it does not. If the visitor cannot be identified, or the counter is unavailable, the actions run as if there were no cap.

#### Where It Applies[​](#where-it-applies "Direct link to Where It Applies")

This section is for Template and Component actions. JavaScript and CSS actions always run against the whole page, and cookie actions have no placement. A **Content Gate** opens over the page wherever the reader is, so it shows a fixed **Covers the page** card instead.

##### Truncating the Article Behind a Gate[​](#truncating-the-article-behind-a-gate "Direct link to Truncating the Article Behind a Gate")

Below the **Covers the page** card, a Content Gate offers **Truncate the article**, which cuts the story short behind the gate. Click **Pick an area** and choose the article body (type a selector, pick a saved area, or use **Find it for me**). Then set **Show the first** *N* **paragraphs** or **words**, **then** either **Fade out** or **Cut off**. **Remove** keeps the whole article on the page again.

![A Content Gate truncating .article-body to the first 3 paragraphs, then cutting off](/assets/images/gate-truncate-ed6f8441db8d5bf70636cca9c646d0a7.png)

##### Choosing an Area[​](#choosing-an-area "Direct link to Choosing an Area")

The area card shows where the template or component goes. New actions start on **Whole page**, which appends the template to the end of the page body. Click **Change** to pick a different area:

* **Whole page** — append to the end of the body.
* **A saved area** — an area found earlier with **Find it for me**, shown by its friendly name.
* **A CSS selector** — type one yourself, such as `.article-body` or `#sidebar`.

##### How It Sits in That Area[​](#how-it-sits-in-that-area "Direct link to How It Sits in That Area")

Once an area is selected, choose how the template or component is inserted relative to it. **Truncate** is available for Template actions only.

| Option       | Behavior                                 |
| ------------ | ---------------------------------------- |
| **Start**    | Added as the first thing inside the area |
| **End**      | Added as the last thing inside the area  |
| **Above**    | Added immediately before the area        |
| **Below**    | Added immediately after the area         |
| **Replace**  | Replaces the area's content entirely     |
| **Truncate** | Limits how much of the area is shown     |

Choosing **Truncate** reveals one more row: **Show the first** *N* **paragraphs** or **words**, **then** either **Fade out** (the template overlays the remaining content behind a fade) or **Cut off** (the remaining content is removed). New truncate actions start at 3 paragraphs, cut off.

tip

Use **Truncate** with **Fade out** to create a content-paywall effect: show the first few paragraphs, then overlay a subscription prompt.

##### Find It for Me[​](#find-it-for-me "Direct link to Find It for Me")

If you don't know the right CSS selector, let Allegro find it on a real page.

1. Click **Find it for me** in the Where it applies section.
2. Enter an **Example page URL** from your site (it must start with `https://`) and describe **What are you targeting?**, for example "the article body, under the headline".
3. Click **Find matches**. Allegro reads the page and suggests up to six areas. Each suggestion shows a friendly name, the selector it resolved to, and how many elements on that page it matched.
4. Pick one to use it as the action's area, or type a selector manually below the results.

Areas found this way are saved for your organization (the 50 most recent), so future actions can select them by name without another scan.

#### When It Runs[​](#when-it-runs "Direct link to When It Runs")

Every action except a frequency cap has a timing setting. The delay is measured from the moment the Interaction fires on the page.

| Option                             | Behavior                                                                                                       | Available for                                                                |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **Right away**                     | Runs as soon as the Interaction fires                                                                          | All actions                                                                  |
| **After a few seconds**            | Waits the number of seconds you enter (default 3)                                                              | All actions                                                                  |
| **After scrolling a set distance** | Waits until the visitor scrolls the distance you enter, in pixels or percent of the page (default 500 pixels)  | All actions                                                                  |
| **When it scrolls into view**      | Waits until the action's target area enters the viewport                                                       | Template and Component actions with a selected area                          |
| **As the truncation point nears**  | Waits until the visitor scrolls to within the number of pixels you enter of the truncation point (default 200) | Template actions using Truncate, and Content Gates that truncate the article |

If you change the area or placement so that a timing option no longer applies, the action falls back to **Right away**.

#### Related[​](#related "Direct link to Related")

* [Interactions](/product/interactions.md) — Trigger modes, lifecycle, and publishing
* [Journeys](/product/interactions/journeys.md) — Deciding which visitors get which actions
* [Templates](/product/interactions/templates.md) — Building the content that Template actions render


---

### Assistant

The assistant writes and rewrites [journeys](/product/interactions/journeys.md) — their conditions and their actions — from a description in plain language, and can draft a [meter](/product/interactions/meters.md) to go with them. Instead of assembling condition groups by hand, describe who you want to reach and what they should see.

Nothing the assistant produces is saved until you click **Save Draft** or **Publish**. Its changes land in the editor exactly as if you had made them, so undo, revision history, and the edit lock all behave as usual.

Availability

The assistant is on by default and can be turned off for your organization. It is available only in **Automatic targeting** mode and on wider screens.

#### Opening the Assistant[​](#opening-the-assistant "Direct link to Opening the Assistant")

* With no journeys yet, click **Build it with a prompt** in the empty state.
* Otherwise, click **Assistant** in the side panel switcher in the **Journeys** header.

The panel docks to the right of the editor. **New conversation** clears the transcript; **Close the assistant** or `Esc` closes the panel. Switching the Interaction to Manual embed closes the assistant and stops any turn in progress.

#### Writing a Prompt[​](#writing-a-prompt "Direct link to Writing a Prompt")

Type into **Describe the journeys you want…** and click **Send** (or press `Cmd`/`Ctrl`+`Enter`). Starter prompts appear in the empty state, for example:

* "Show the newsletter signup to first-time visitors on article pages."
* "Ask readers who visit often but have not donated yet to support us."
* "Show one message to visitors arriving from a paid campaign, and something else to everyone else."

While it works, the assistant shows its reasoning and a step log with entries such as **Looking up template fields**, **Reading recent page views**, **Drafting 2 journeys**, **Preparing template options**, **Drafting the template**, and — when [Potential Reach](/product/interactions/potential-reach.md) is enabled — **Checking projected reach**, which it uses to flag proposals that would match almost nobody or almost everybody. When you ask it to review an interaction, you also see **Reading live activity**, **Checking A/B test results**, and **Looking at other live interactions**. Click **Stop** to abandon a turn.

The assistant may ask a question before it proposes anything, for example for the URL of a typical article page so it can match your real content structure and find the right spot on the page. Answer in the composer and the turn continues.

#### Reviewing an Interaction[​](#reviewing-an-interaction "Direct link to Reviewing an Interaction")

Besides writing journeys, the assistant can review one that is already running. Ask it something like:

* "How is this interaction doing?"
* "Review this — any gaps or suggestions?"
* "Is this too aggressive?"

It gathers evidence first — each journey's activity from the [report](/product/interactions/report.md), any [A/B test](/product/interactions/ab-tests.md) results, [projected reach](/product/interactions/potential-reach.md), and other live interactions that could compete for the same visitors — then replies in prose with a one-sentence verdict and up to five findings, most important first. Each finding cites the numbers behind it and names the change it would make. A review proposes nothing on its own; it ends by offering to make the changes, so you decide.

To keep its read honest, the assistant holds back where the data is thin: it won't judge a journey with only a handful of matched pages, and it won't score an interaction that changed in the last 7 days, because the numbers still mix the old and new targeting. If you have unsaved edits, it notes that the numbers describe the last saved version.

#### What the Assistant Can Change[​](#what-the-assistant-can-change "Direct link to What the Assistant Can Change")

| Can change                                                      | Cannot change                                            |
| --------------------------------------------------------------- | -------------------------------------------------------- |
| Add, remove, reorder, and rename journeys                       | The title of an Interaction you have named, or its slug  |
| Rewrite condition groups and conditions                         | The trigger mode or publish status                       |
| Add, remove, and edit actions in journeys and **Everyone else** | Anything outside this Interaction                        |
| Action names                                                    | JavaScript actions (it will not write scripts)           |
| Offer template choices for an action, and draft a new template  | Save a drafted template to your library without approval |

While the Interaction is still untitled, a proposal can also name it; the change shows as **Name the interaction "…"**. A drafted meter is never saved for you: see [The Proposed Changes Card](#the-proposed-changes-card).

When an action needs a template, the assistant suggests a few of your published templates as clickable pills, each with a one-line reason, rather than silently picking one. If none fits, it can also **draft a new template** — title, markup, styling, and fields — and show it for your approval. A drafted template is never added to your [Templates](/product/interactions/templates.md) library until you accept it.

Each proposal is a complete picture of the journeys, not a patch, so asking for a small change returns the whole list with that change applied.

#### Autopilot and Review Changes[​](#autopilot-and-review-changes "Direct link to Autopilot and Review Changes")

A toggle beside **Send** controls how a finished turn lands:

| Mode               | Behavior                                                                                                        |
| ------------------ | --------------------------------------------------------------------------------------------------------------- |
| **Autopilot**      | The change applies to the editor as soon as the turn finishes. The turn shows what changed and offers **Undo**. |
| **Review changes** | The change is held in a **Proposed changes** card until you click **Accept changes** or **Discard**.            |

The default depends on how much there is to lose:

| Situation                                     | Default        |
| --------------------------------------------- | -------------- |
| A new or draft Interaction with no journeys   | Autopilot      |
| A draft Interaction that already has journeys | Review changes |
| A published Interaction                       | Review changes |

Your choice sticks for the rest of the session. **Undo** stays available on a turn until the next turn applies, and restores only the journeys and actions — a title you edited in the meantime is untouched.

#### The Proposed Changes Card[​](#the-proposed-changes-card "Direct link to The Proposed Changes Card")

The card summarizes the turn in one line and lists each change: the Interaction's name, if it was untitled; journeys added, removed, reordered, or renamed; conditions changed; actions changed; **Everyone else** actions changed. Any CSS or code the assistant wrote is shown in full so you can read it before accepting.

![A Proposed changes card naming the interaction, adding a journey, and changing another journey\&#39;s actions](/assets/images/assistant-proposal-7e80ea2c72c84b9797557e517d9a2395.png)

A meter the assistant drafts arrives in a **Proposed meter** card instead, with a one-line summary of its settings. Meters belong to your organization rather than to this Interaction, so click **Open in Meters** and save it from the Meters drawer.

When the assistant needs a template for an action, it shows its suggestions as clickable template pills — pick one to use it, or ask it to draft a new one. A template it drafts arrives in its own card with the title, fields, and a preview; open the **full-screen preview** to check it at different device sizes before you accept. Accepting adds the template to your library and wires it into the action; discarding leaves your library untouched.

After you act, the card records the outcome: **Applied to this interaction** (with **Undo**), **Undone — nothing was changed.**, or **Discarded.**

#### Read-Only Situations[​](#read-only-situations "Direct link to Read-Only Situations")

When someone else holds the edit lock, the composer reads **Someone else is editing this interaction** and neither Accept nor Autopilot can apply changes. Claim the lock first; see [Editing Safely](/product/interactions.md#editing-safely).

caution

Responses are generated using AI and may contain mistakes. Review conditions and actions before publishing, and use [Testing Journeys](/product/interactions/testing.md) to confirm the behavior you expect.

#### Related[​](#related "Direct link to Related")

* [Journeys](/product/interactions/journeys.md) — What the assistant is building
* [Cohorts](/product/interactions/cohorts.md) — Where the assistant drafts conditions only, with no actions
* [Actions](/product/interactions/actions.md) — Finding a page area with **Find it for me**
* [Potential Reach](/product/interactions/potential-reach.md) — The counts the assistant checks


---

### Cohorts

A cohort is a named, reusable set of targeting conditions — the same groups and conditions you build inside a [journey](/product/interactions/journeys.md), saved on its own so several interactions can reference it. Edit the cohort once and every journey that references it picks up the change immediately.

Cohorts vs. Segments

Cohorts and [Segments](/product/audience/segments.md) are different things. A segment is a group of known members defined by their profile — engagement, membership, giving — and built on the **Segments** page. A cohort is a reusable set of targeting conditions: you build it the same way you build a journey's, and it can match anonymous visitors too.

#### Creating a Cohort[​](#creating-a-cohort "Direct link to Creating a Cohort")

Open **Interactions → Cohorts** in the sidebar, then click **New Cohort**. The list has **All**, **Active**, and **Archived** tabs. A cohort has a name and a set of condition groups.

#### The Cohort Editor[​](#the-cohort-editor "Direct link to The Cohort Editor")

The cohort editor is the same condition builder used inside a journey, with the same supporting tools:

* **Conditions.** Build one or more condition groups exactly as in a journey — see [Journeys](/product/interactions/journeys.md#conditions) and [Targeting Conditions](/product/interactions/conditions.md) for every attribute, operator, and the **All / Any** and **AND / OR** matching rules. A visitor is in the cohort when these conditions match.
* **Evaluate.** Click **Evaluate** to define a simulated visitor and see whether they land **In this cohort** or **Not in this cohort**. See [Testing Journeys](/product/interactions/testing.md) for how unset attributes are treated.
* **Potential reach.** The side panel shows how many visitors the cohort's conditions would match, the same way it does for a journey. See [Potential Reach](/product/interactions/potential-reach.md).
* **Assistant.** Draft or rewrite the cohort's conditions from a plain-language prompt, the same way the [Assistant](/product/interactions/assistant.md) drafts a journey. In the cohort editor it proposes conditions only — it doesn't add actions, and it never proposes referencing another cohort.
* **Revisions, undo/redo, and the edit lock** all work as they do for an Interaction. See [Revisions](/product/interactions/revisions.md) and [Editing Safely](/product/interactions.md#editing-safely).

![The cohort editor: a name, the condition builder, and the Assistant and Evaluate buttons](/assets/images/cohort-editor-b8d53b4a7f5cec921a90ad6c9f6dc792.png)

A cohort's own conditions can't reference another cohort — the **Cohort** attribute doesn't appear in the cohort editor's attribute picker, so cohorts can't nest.

#### Using a Cohort in a Journey[​](#using-a-cohort-in-a-journey "Direct link to Using a Cohort in a Journey")

Inside a journey's condition builder, **Cohort** is an attribute like any other, listed with **Segments** in the attribute picker:

| Attribute  | Operators                                | Value                             |
| ---------- | ---------------------------------------- | --------------------------------- |
| **Cohort** | **matches any of** / **matches none of** | One or more of your saved cohorts |

**Matches any of** is true when the visitor matches at least one of the listed cohorts' conditions. **Matches none of** is true when the visitor matches none of them. Below the cohort field, **Edit** opens a selected cohort's name and conditions in a drawer, and **Create a cohort** starts a new one there and selects it once you save. Either way you stay in the interaction, and its unsaved changes are kept. Revisions and reach live on the full cohort editor, which the drawer links to.

If a listed cohort has since been archived, it appears as **Deleted cohort** and never matches — for either operator. A cohort condition is otherwise subject to the same [unknown-value rules](/product/interactions/journeys.md#when-a-value-is-unknown) as any other attribute: if a condition inside the cohort depends on data Allegro can't resolve for this visitor (for example, a signed-out visitor and a member-profile condition), that part of the cohort simply doesn't match. Allegro then can't say the visitor is outside the cohort either, so **Matches none of** is false for them too.

#### Saving Changes Live[​](#saving-changes-live "Direct link to Saving Changes Live")

There is no draft or publish state for a cohort. Allegro reads a cohort's conditions each time it evaluates a visitor, so as soon as you save, every published interaction in **Automatic targeting** mode that references the cohort uses the new conditions on the next page view. Draft interactions that reference it pick up whatever the cohort's conditions are when they're published.

When a cohort is referenced by at least one interaction that isn't archived, the save button warns you before you commit: **Save — affects *N* interactions**. Archived interactions aren't counted, since they never run. The same warning appears in the revision note dialog, so you have a chance to describe why you changed it before the change takes effect.

#### Used By and Archiving a Cohort[​](#used-by-and-archiving-a-cohort "Direct link to Used By and Archiving a Cohort")

The **Used by** card on the cohort's edit page lists every interaction that references it, including archived ones, with a link to each interaction's editor (archived interactions are listed with an **Archived** badge but not linked, since they have no editor to open).

Archiving a cohort is blocked while any interaction still references it, including an archived one. The error names each interaction that's still using it and marks the archived ones. Remove the **Cohort** condition from the active interactions' journeys. An archived interaction must first be restored and edited, or permanently deleted. Then archive the cohort.

Restoring an interaction revision that references an archived cohort is refused, and the error names the cohort, so a restore can't bring back a condition that no longer has a cohort behind it.

#### Potential Reach for Cohorts[​](#potential-reach-for-cohorts "Direct link to Potential Reach for Cohorts")

[Potential reach](/product/interactions/potential-reach.md) can estimate a **matches any of** condition exactly: it expands to the visitors who'd match any of the listed cohorts' conditions, the same way it estimates a group of conditions directly in a journey.

**Matches none of** can't be estimated. The panel shows **Reach isn't counted for "matches none of" cohort conditions**, and the condition still evaluates correctly on your site — the panel simply can't count it.

#### Related[​](#related "Direct link to Related")

* [Journeys](/product/interactions/journeys.md) — Building the condition groups a cohort shares with a journey
* [Targeting Conditions](/product/interactions/conditions.md) — Every attribute, operator, and value format, including Segments
* [Potential Reach](/product/interactions/potential-reach.md) — How reach estimates work for a cohort's conditions
* [Testing Journeys](/product/interactions/testing.md) — Simulating a visitor against a cohort
* [Revisions](/product/interactions/revisions.md) — Version history and rollback, shared by cohorts and interactions


---

### Targeting Conditions

This page lists everything a [journey](/product/interactions/journeys.md) condition can test. Each attribute belongs to a source, supports a fixed set of operators, and expects values in a particular format.

#### Operators[​](#operators "Direct link to Operators")

| Operator                                                         | Meaning                                                                                                           | Value                                             |
| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| **is** / **is not**                                              | Exact match (text comparisons ignore case)                                                                        | One value                                         |
| **contains** / **does not contain**                              | Substring match, ignoring case                                                                                    | Text                                              |
| **contains any of** / **does not contain any of**                | Substring match against a list, ignoring case — the text holds at least one of the listed values, or none of them | One or more values                                |
| **starts with**                                                  | Prefix match, ignoring case                                                                                       | Text                                              |
| **is one of** / **is not one of**                                | Matches any value in the list                                                                                     | One or more values                                |
| **is set**                                                       | The attribute has any value                                                                                       | None                                              |
| **=**, **≠**, **>**, **≥**, **<**, **≤**                         | Numeric comparison                                                                                                | A number                                          |
| **between**                                                      | Inclusive range                                                                                                   | A minimum and a maximum                           |
| **is true** / **is false**                                       | Boolean test                                                                                                      | None                                              |
| **within last**                                                  | The event happened within the period                                                                              | A count and a unit: hours, days, weeks, or months |
| **more than … ago**                                              | The event happened before the period began                                                                        | A count and a unit                                |
| **before** / **after**                                           | Compared to a fixed time, date, or date-time                                                                      | One value                                         |
| **is in any of** / **is in all of** / **is in none of**          | Segment membership — the member is in at least one, every one, or none of the listed segments                     | One or more segments                              |
| **includes any of** / **includes all of** / **includes none of** | List match, ignoring case — the page's list holds at least one, every one, or none of the listed values           | One or more values                                |
| **is not empty**                                                 | The page's list has at least one value                                                                            | None                                              |
| **has active entitlement to** / **does not have**                | Whether the member holds an active entitlement to a product                                                       | One product                                       |
| **key exists**                                                   | The named key was sent, with any scalar value                                                                     | None                                              |

When an attribute cannot be determined for a visitor, every operator on it is false — including the negative ones. See [When a Value Is Unknown](/product/interactions/journeys.md#when-a-value-is-unknown).

#### This Request[​](#this-request "Direct link to This Request")

Attributes describing the page being viewed and the device viewing it.

| Attribute                                           | What it checks                                                                                                                       | Operators                                                        | Value                                                                                                              |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Property**                                        | Which of your [properties](/product/administration/properties.md) served the page                                                    | is, is not, is one of, is not one of                             | A property slug; existing slugs autocomplete. Never matches on a host with no property                             |
| **Content type**                                    | The kind of page, as reported by your site tag (for example `article`, `video`)                                                      | Text operators                                                   | Text                                                                                                               |
| **Section**                                         | The section of the site the page belongs to, such as `News` or `Arts`                                                                | Text operators                                                   | Text                                                                                                               |
| **Article tags**                                    | The tags or keywords on the article being viewed                                                                                     | includes any of, includes all of, includes none of, is not empty | One or more tags; tags seen on your content autocomplete                                                           |
| **Article author**                                  | The author or authors of the article being viewed                                                                                    | includes any of, includes all of, includes none of, is not empty | One or more author names; authors seen on your content autocomplete                                                |
| **Article published**                               | When the article being viewed was published                                                                                          | within last, more than … ago, before, after, between             | A period such as 7 days, or a date                                                                                 |
| **URL path**                                        | The page path, without domain or query string                                                                                        | Text operators                                                   | Text such as `/news/`                                                                                              |
| **Referrer**                                        | The URL the visitor came from, if the browser sent one                                                                               | Text operators                                                   | Text                                                                                                               |
| **Referrer type**                                   | What kind of site sent the visitor, classified from the referrer                                                                     | is, is not, is one of, is not one of                             | Direct, Internal, Search, Social, News aggregator, AI assistant, Email, Other website                              |
| **Query parameter**                                 | A single named parameter from the URL's query string                                                                                 | key exists, is, contains, ≥, ≤                                   | Enter the parameter name in the key box, then a value                                                              |
| **Cookie**                                          | A readable cookie set by a [cookie action](/product/interactions/actions.md#cookie)                                                  | key exists, is, contains, ≥, ≤                                   | Enter the cookie name in the key box without the `_al_` prefix, then a value. See [Cookies](#cookies)              |
| **UTM source / medium / campaign / term / content** | The matching `utm_*` parameter on the URL                                                                                            | Text operators                                                   | Text                                                                                                               |
| **Browser**                                         | Detected from the request                                                                                                            | is, is not, is one of, is not one of                             | Chrome, Firefox, Safari, Edge, Samsung Internet, Opera                                                             |
| **User agent**                                      | The raw User-Agent string the browser sent, for in-app browsers that **Browser** can't name (such as the Facebook or Instagram apps) | Text operators, contains any of, does not contain any of         | Text; one or more values for the "any of" operators                                                                |
| **OS**                                              | Detected from the request                                                                                                            | is, is not, is one of, is not one of                             | Windows, macOS, iOS, Android, Linux, ChromeOS                                                                      |
| **Device type**                                     | Detected from the request                                                                                                            | is, is not, is one of, is not one of                             | mobile, desktop, tablet, bot                                                                                       |
| **Country**                                         | Where the visitor appears to be browsing from                                                                                        | is one of, is not one of                                         | Two-letter country codes such as `US` or `GB`; the picker searches by name                                         |
| **Region**                                          | The state or province the visitor appears to be browsing from                                                                        | is one of, is not one of                                         | Bare subdivision codes such as `TX` or `ON`. US states and Canadian provinces are suggested; any code can be typed |
| **City**                                            | The city the visitor appears to be browsing from                                                                                     | Text operators                                                   | Text. Pair with Region, since city names repeat                                                                    |
| **ZIP / postal code**                               | The ZIP or postal code the visitor appears to be browsing from                                                                       | Text operators                                                   | Text                                                                                                               |
| **Continent**                                       | Derived from the visitor's country                                                                                                   | is, is not, is one of, is not one of                             | Africa, Antarctica, Asia, Europe, North America, Oceania, South America                                            |
| **Privacy law**                                     | Which privacy regimes apply, derived from country and region                                                                         | is one of, is not one of                                         | GDPR, UK GDPR, Swiss FADP, Brazil LGPD, Canada PIPEDA, CCPA                                                        |

"Text operators" means is, is not, contains, does not contain, starts with, is one of, and is set.

Location details

Country, Continent, and Privacy law are always available. Region, City, ZIP / postal code, and the CCPA privacy law are shown disabled until your organization connects an IP geolocation provider. See [Geolocation](/product/administration/geolocation.md).

Country codes are validated on save. `UK` is rejected with a suggestion to use `GB`.

A visitor whose location is known but who falls under none of the listed privacy laws matches **Privacy law is not one of** any list. A visitor whose location could not be resolved matches neither operator.

Content type, Section, and the article attributes come from the page metadata your site exposes, usually its JSON-LD structured data. See [Page Metadata](/developer/guides/page-metadata.md) for how those values are read.

Article attributes are read from the page each time it loads, so a new article can be targeted from its first view. A page with no tags or authors matches **includes none of** but not **is not empty**. A page with no publish date matches no **Article published** condition. Use **Article published within last 7 days** to target recent articles, or **more than 1 year ago** for evergreen content.

##### Cookies[​](#cookies "Direct link to Cookies")

A **Cookie** condition reads a cookie that a [cookie action](/product/interactions/actions.md#cookie) set with **Set readable cookie** turned on. Readable cookies are stored with an `_al_` prefix, and the SDK sends every `_al_` cookie with each page view, so a journey can check whether a visitor already saw a promotion, dismissed a banner, or picked an option in an earlier interaction.

The key box shows the `_al_` prefix for you. Enter the same name you gave the cookie action, for example `promo_seen`, then pick an operator. **key exists** matches whenever the cookie is present, whatever its value.

Only `_al_` cookies can be targeted. A cookie set with **Set readable cookie** turned off, or one your site sets itself without the prefix, is never sent to Allegro.

#### Date & Time[​](#date--time "Direct link to Date & Time")

Organization attributes use your organization's timezone (set in [Settings](/product/administration/settings.md)) and are always available. Visitor attributes use the timezone the visitor's browser reports; if the browser did not report one, visitor conditions never match.

| Attribute                                                    | Operators                  | Value                                                                                    |
| ------------------------------------------------------------ | -------------------------- | ---------------------------------------------------------------------------------------- |
| **Current time (organization)** / **Current time (visitor)** | is, before, after, between | 24-hour time such as `18:30`. A **between** range may wrap midnight (`22:00` to `06:00`) |
| **Date (organization)** / **Date (visitor)**                 | is, before, after, between | A calendar date                                                                          |
| **Day of week (organization)** / **Day of week (visitor)**   | is one of, is not one of   | One or more days                                                                         |
| **Visitor timezone**                                         | Text operators             | An IANA name such as `America/Chicago`; names autocomplete                               |

#### Session[​](#session "Direct link to Session")

Session attributes are always known. An anonymous visitor is definitively **false** for both, so **Authenticated is false** is a reliable logged-out rule.

| Attribute         | Operators         | Meaning                                                                   |
| ----------------- | ----------------- | ------------------------------------------------------------------------- |
| **Identified**    | is true, is false | The visitor is linked to a member record, even if not signed in right now |
| **Authenticated** | is true, is false | The visitor is signed in for this session                                 |

#### Member Profile & Behavior[​](#member-profile--behavior "Direct link to Member Profile & Behavior")

These attributes come from the member's analytics profile and resolve only for visitors who are signed in.

The profile is rebuilt on a schedule, about every 10 minutes, not on every page view. A member who donated or signed up a few minutes ago may not match a condition on that activity yet. The same applies to segment membership. The debug workbench shows when the current member's profile was last rebuilt.

| Attribute                                                                                 | Operators                                            | Value                             |
| ----------------------------------------------------------------------------------------- | ---------------------------------------------------- | --------------------------------- |
| **Member level**                                                                          | Text operators                                       | The level recorded on the profile |
| **Is donor**                                                                              | is true, is false                                    | None                              |
| **Total donations**                                                                       | =, ≠, >, ≥, <, ≤, between                            | An amount                         |
| **Sign-up gate type**                                                                     | Text operators                                       | Text                              |
| **Signed up**, **First seen**, **Last seen**                                              | within last, more than … ago, before, after, between | A period, or a date-time          |
| **Pages per visit**                                                                       | Numeric operators                                    | A number                          |
| **Top content section**                                                                   | Text operators                                       | Text                              |
| **Primary device**                                                                        | is, is not, is one of, is not one of                 | Desktop, Mobile, Tablet           |
| **Days since last visit**                                                                 | Numeric operators                                    | A number                          |
| **Lifetime page views**, **Lifetime days visited**, **Lifetime logins**                   | Numeric operators                                    | A number                          |
| **Page views (last 30 days)**, **Days visited (last 30 days)**, **Logins (last 30 days)** | Numeric operators                                    | A number                          |

"Numeric operators" means =, ≠, >, ≥, <, ≤, between, and is set.

#### User Attributes[​](#user-attributes "Direct link to User Attributes")

Every [user attribute](/product/audience/user-attributes.md) you define appears here under its own name. Values come from what is saved on the member, so a change counts from the member's next page view. User attributes resolve only for visitors who are signed in.

| Attribute type | Operators                                                              | Value                          |
| -------------- | ---------------------------------------------------------------------- | ------------------------------ |
| Text           | is, is not, contains, does not contain, starts with, is one of, is set | Text                           |
| Number         | Numeric operators                                                      | A number                       |
| Boolean        | is true, is false                                                      | None                           |
| Select (enum)  | is, is not, is one of, is not one of                                   | One of the attribute's options |

File and color attributes are not offered as conditions. A signed-in member with no value saved for an attribute matches none of its conditions, including **is not**.

#### Segments[​](#segments "Direct link to Segments")

| Attribute   | Operators                                 | Value                                                               |
| ----------- | ----------------------------------------- | ------------------------------------------------------------------- |
| **Segment** | is in any of, is in all of, is in none of | One or more of your saved [segments](/product/audience/segments.md) |

**is in any of** matches a member in at least one listed segment, **is in all of** only a member in every one, and **is in none of** a member in none of them. A signed-in member who belongs to no segments matches **is in none of**. An anonymous visitor matches none of the three.

#### Cohorts[​](#cohorts "Direct link to Cohorts")

| Attribute  | Operators                                | Value                                                                 |
| ---------- | ---------------------------------------- | --------------------------------------------------------------------- |
| **Cohort** | **matches any of** / **matches none of** | One or more of your saved [cohorts](/product/interactions/cohorts.md) |

Unlike a segment, which groups known members by their profile, a cohort is a reusable set of targeting conditions — see [Cohorts](/product/interactions/cohorts.md) for how to build one and how it's evaluated, including how a deleted cohort and an unresolvable value inside it are handled.

#### A/B Tests[​](#ab-tests "Direct link to A/B Tests")

| Attribute            | Operators                      | Value                                                                                        |
| -------------------- | ------------------------------ | -------------------------------------------------------------------------------------------- |
| **A/B test variant** | **is any of** / **is none of** | One of your [A/B tests](/product/interactions/ab-tests.md), then one or more of its variants |

A visitor who is not in the test (outside its traffic share, not in its audience, or while it's still a draft) matches neither operator, so **is none of** means "in the test, in another variant". See [A/B Tests](/product/interactions/ab-tests.md).

#### Entitlements[​](#entitlements "Direct link to Entitlements")

| Attribute       | Operators                                | Value                                            |
| --------------- | ---------------------------------------- | ------------------------------------------------ |
| **Entitlement** | has active entitlement to, does not have | One of your [products](/product/entitlements.md) |

Only active entitlements count. An anonymous visitor matches neither operator.

#### Meters[​](#meters "Direct link to Meters")

Each [meter](/product/interactions/meters.md) adds four attributes: **Meter status**, **Meter remaining**, **Meter used**, and **Meter counted this view**. See [Targeting a Meter](/product/interactions/meters.md#targeting-a-meter) for their operators and values.

#### External Profiles[​](#external-profiles "Direct link to External Profiles")

| Attribute                 | Operators                      | Value                                                                                                |
| ------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------- |
| **External profile data** | key exists, is, contains, ≥, ≤ | Enter the field in the key box as `provider.path.to.field`, then a value. Synced fields autocomplete |

External profile data reads a single field from a profile another system, such as a CRM or email platform, has synced to Allegro for the member. It resolves only for visitors who are signed in.

#### Custom Data[​](#custom-data "Direct link to Custom Data")

| Attribute       | Operators                      | Value                                                                            |
| --------------- | ------------------------------ | -------------------------------------------------------------------------------- |
| **Custom data** | key exists, is, contains, ≥, ≤ | Enter the key in the key box, then a value. Keys your site has sent autocomplete |

Custom data is any key/value your site tag passes to the SDK alongside the page view. Your developer configures it; see the [developer guide](/developer/guides/interactions.md#custom-data).

#### Integrations[​](#integrations "Direct link to Integrations")

Some integrations add their own targeting attributes once the integration is enabled, grouped under their own category in the attribute picker. They resolve only for signed-in members, and they never match for an anonymous visitor.

* **Fundraise Up** adds a **Fundraise Up** category for targeting on a member's giving — donor status, lifetime giving, recurring plan status, campaigns, and more. See [Fundraise Up](/product/integrations/fundraise-up.md#target-interactions) for the full list of attributes and how profiles are matched.

Integration-provided conditions always show **No estimate** in Potential Reach.

#### Which Conditions Can Be Estimated[​](#which-conditions-can-be-estimated "Direct link to Which Conditions Can Be Estimated")

[Potential Reach](/product/interactions/potential-reach.md) counts visitors from analytics data. Eleven attributes are not recorded there and always show **No estimate**: Country, Region, City, ZIP / postal code, Continent, Privacy law, Referrer type, Query parameter, Cookie, Visitor timezone, and External profile data. Meter and integration-provided conditions show **No estimate** too. They all still evaluate correctly on your site.

An A/B test variant condition is estimated from the test's share of traffic and its variant weights, so a draft test can be estimated before it starts.

Article tags, author, and published estimates count views of articles Allegro has already cataloged. A new article joins the catalog shortly after it starts getting traffic, so its views can take a while to show up in an estimate, even though the condition matches it on your site right away.


---

### Journeys

In **Automatic targeting** mode, an Interaction is a list of journeys. A journey pairs a set of **conditions** (who this is for) with a set of [**actions**](/product/interactions/actions.md) (what they get). On every page view, Allegro checks the journeys top to bottom and the visitor follows the first one whose conditions match. Visitors who match no journey fall through to **Everyone else**.

```text
Journey 1: Conditions ──match──► Actions        (Runs first)
   ELSE — try the next journey
Journey 2: Conditions ──match──► Actions
   ELSE (default journey)
Everyone else ─────────────────► Actions

```

#### How Evaluation Works[​](#how-evaluation-works "Direct link to How Evaluation Works")

Targeting runs on Allegro's servers, not in the visitor's browser:

1. When a page loads, the Allegro SDK sends the page's URL, query string, referrer, content type, section, and the visitor's timezone to Allegro. If the visitor is logged in, their session is included.
2. Allegro resolves everything else it needs — device, location, session state, and member profile data — and evaluates every published automatic Interaction.
3. The browser receives only the actions to run. Your targeting rules, segment membership, and member data never leave the server.

Each published automatic Interaction is evaluated independently. If a visitor matches journeys in several Interactions, all of them run, in the order the Interactions were created. There is no priority between Interactions; use conditions to keep them from overlapping when that matters.

By default the SDK evaluates once per page load. Sites built as single-page apps can re-evaluate on navigation; see the [developer guide](/developer/guides/interactions.md).

#### The Journeys Builder[​](#the-journeys-builder "Direct link to The Journeys Builder")

An Interaction in **Automatic targeting** mode shows the **Journeys** section. Its header offers **Meters** (see [Meters](/product/interactions/meters.md)) and a switcher with **Evaluate**, **Assistant**, and, when it is enabled, **Potential reach**. Each opens a side panel; see [Testing Journeys](/product/interactions/testing.md), [Assistant](/product/interactions/assistant.md), and [Potential Reach](/product/interactions/potential-reach.md).

A new Interaction has no journeys yet. Its empty state offers **Add your first journey**, **Build it with a prompt**, and a link to make it a manual Interaction instead.

Journeys appear as cards. The first card is marked **Runs first**; the pills between cards read **ELSE — try the next journey**, and the last pill before the default card reads **ELSE (default journey)**. Hover a pill to reveal **Insert journey**, which adds a journey at that position. The pill above **Everyone else** adds one at the end of the list.

![A journey card with two condition groups on the left and its actions on the right](/assets/images/journey-card-1b58e8aee5b08c3739b26ffb5b16c5ac.png)

On each journey card you can:

* Drag the handle, or use **Move up** and **Move down**, to reorder
* Click the name to rename the journey
* **Expand** or **Collapse** the card
* **Delete journey** (this cannot be undone once saved)

An expanded card has two columns: **Conditions** on the left and **Actions** on the right. Click an action to configure it and drag to reorder. You can also drag an action from one journey into another, or into **Everyone else**; see [Actions](/product/interactions/actions.md).

##### Everyone Else[​](#everyone-else "Direct link to Everyone Else")

The **Everyone else** card at the bottom holds the actions for visitors who match no journey. It cannot be deleted or reordered. It may be left with no actions, in which case unmatched visitors pass through untouched.

#### Conditions[​](#conditions "Direct link to Conditions")

Conditions live in **groups**. A new journey starts with one group; click **Add group** for more and **Add condition** inside a group to add a row.

Each condition row reads left to right: an **attribute** (what to check), an **operator** (how to compare), and a **value**. Attributes that need a key — **Query parameter**, **Cookie**, **Custom data**, and **External profile data** — add a key box before the operator. Some operators, such as **is set** or **is true**, need no value.

The full list of attributes, operators, and value formats is in the [Targeting Conditions](/product/interactions/conditions.md) reference.

##### Matching Within a Group[​](#matching-within-a-group "Direct link to Matching Within a Group")

Each group has a **Match** toggle:

| Match   | The group is true when…                     |
| ------- | ------------------------------------------- |
| **All** | every condition in the group is true        |
| **Any** | at least one condition in the group is true |

##### Combining Groups[​](#combining-groups "Direct link to Combining Groups")

Between consecutive groups an **AND / OR** toggle sets how the lower group joins the one above. **AND** binds tighter than **OR**: the groups are read as runs of AND-joined groups, and the journey matches if any run is entirely true.

![Two condition groups joined by AND: URL path starts with /news/ and Authenticated is false, then Referrer type is one of Social or Search](/assets/images/conditions-groups-536db64f4d3ba8f14e5450a993e01ee3.png)

| Groups                         | Reads as                    |
| ------------------------------ | --------------------------- |
| `G1` AND `G2`                  | G1 and G2                   |
| `G1` OR `G2` AND `G3`          | G1, or (G2 and G3)          |
| `G1` AND `G2` OR `G3` AND `G4` | (G1 and G2), or (G3 and G4) |

##### Picking an Attribute[​](#picking-an-attribute "Direct link to Picking an Attribute")

Click **Select attribute** to open the picker; a newly added row opens it for you. The left rail lists the sources — Recently used, This request, Date & time, Session, Member profile & behavior, External profiles, Segments, Cohorts, A/B tests, Entitlements, Custom data, User attributes, and Meters once your organization has one — with a count for each. **∞** marks a source whose attribute takes a key you type. **Recently used** holds the attributes you picked last.

![The attribute picker, with sources and counts on the left, attributes and their type badges on the right, and a description of the highlighted attribute](/assets/images/attribute-picker-bbd67c8895b597a8bcffc076543d5ef2.png)

Type in **Search or type a key…** to filter across every source; the search also matches common synonyms, so "state" finds **Region** and "logged in" finds **Authenticated**. Each attribute shows a type badge, such as *text*, *choice*, or *key/value*, and a one-line description of where its value comes from when highlighted.

![Searching \&quot;logged in\&quot; finds Authenticated, Lifetime logins, and Logins (last 30 days)](/assets/images/picker-search-4f67b1de264c840bf462b5266204a6fd.png)

##### Value Suggestions[​](#value-suggestions "Direct link to Value Suggestions")

Free-text values autocomplete from what your site has actually sent: recent paths, sections, content types, UTM values, custom data keys, and your content catalog. Suggestions are hints, not limits — you can always type a value the site has not sent yet, for example a section you are about to launch. Short lists open when you focus the field; longer lists (such as timezones) wait until you start typing.

#### When a Value Is Unknown[​](#when-a-value-is-unknown "Direct link to When a Value Is Unknown")

If Allegro cannot determine an attribute for a visitor, every condition on that attribute is false — including negative operators such as **is not**, **is not one of**, **is in none of**, and **does not have**. This keeps rules from accidentally matching everyone.

| Situation                                             | Effect                                                                                                                          |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Visitor is not logged in                              | Member profile, external profile, user attribute, segment, and entitlement conditions are false, even "is in none of segment X" |
| The member's profile could not be loaded              | Member profile and segment conditions are false; entitlement conditions still resolve                                           |
| The SDK did not report a timezone                     | Visitor-local time, date, and day-of-week conditions are false                                                                  |
| Location could not be resolved                        | Country, region, city, postal code, continent, and privacy law conditions are false                                             |
| A query parameter, cookie, or custom key was not sent | **key exists** is false; other operators on that key are false                                                                  |

Two things are always known:

* **Session** attributes. An anonymous visitor is definitively **Authenticated is false**, so that is a reliable "logged out" rule.
* A logged-in member with **no** segments genuinely matches **Segment is in none of**.

Member data requires a login

Member profile, external profile, user attribute, segment, and entitlement conditions resolve only for visitors who are logged in. A visitor who has only been identified (for example by submitting an email form) is treated as anonymous for targeting purposes.

#### Limits[​](#limits "Direct link to Limits")

| Limit                        | Value                             |
| ---------------------------- | --------------------------------- |
| Journeys per Interaction     | 25                                |
| Condition groups per journey | 10                                |
| Conditions per group         | 25                                |
| Minimum per journey          | 1 group with at least 1 condition |
| Actions in **Everyone else** | May be empty                      |

A journey with an empty group cannot be saved. Validation errors appear inline on the condition row they belong to.

#### Repeat Visits[​](#repeat-visits "Direct link to Repeat Visits")

An automatic Interaction shows on every page view it matches. To limit repeats, wrap its actions in a [frequency cap](/product/interactions/actions.md#frequency-cap), or add a **Cookie** action with **Set readable cookie** turned on and a **Cookie → key exists** condition on that cookie's name to a journey above it that does nothing.

#### Related[​](#related "Direct link to Related")

* [Targeting Conditions](/product/interactions/conditions.md) — Every attribute, operator, and value format
* [Cohorts](/product/interactions/cohorts.md) — Save a set of conditions once and reuse it across journeys
* [Potential Reach](/product/interactions/potential-reach.md) — See how many visitors each journey would reach
* [Assistant](/product/interactions/assistant.md) — Draft journeys from a plain-language prompt
* [Testing Journeys](/product/interactions/testing.md) — Simulate a visitor or debug on your site


---

### Meters

A meter counts the pages a visitor views over a period of time and compares that count to a limit. Use one to build a metered paywall ("5 free articles a month"), nudge readers as they approach the limit, or show a registration wall after a visitor's third story.

Once a meter exists, [journeys](/product/interactions/journeys.md) can target it and [templates](/product/interactions/templates.md) can show its numbers, for example "You have 2 free articles left this month."

#### Creating a Meter[​](#creating-a-meter "Direct link to Creating a Meter")

Meters belong to your organization, not to one interaction, so every interaction can target the same meter.

1. Open an interaction that uses automatic targeting.
2. Click **Meters** in the Journeys header. The badge shows how many meters you have.
3. Click **Add meter**, fill in the settings below, and click **Save**.

![The New meter form: name, limit and period, counting, what counts, and who bypasses it](/assets/images/meter-form-d6f8fad9eea31373641e008caecf3784.png)

note

Manual interactions have no **Meters** button. To create or edit meters, open any interaction that uses automatic targeting.

| Setting             | What it controls                                                                                                                                                                                                          |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Meter name**      | What editors see when they target the meter. The name also sets the meter's slug, which never changes, even if you rename the meter later.                                                                                |
| **The limit**       | How many free views a visitor gets, and the period they apply to: **Calendar day**, **Calendar week**, **Calendar month**, **Rolling 7 days**, **Rolling 30 days**, **Rolling N days**, **Per session**, or **Lifetime**. |
| **Counting**        | **Unique pages** counts each page once per period, so rereading an article is free. **Every page view** counts every load, including repeats.                                                                             |
| **What counts**     | **All pages**, or **Pages matching…** a set of conditions. Click **Edit conditions** to choose, for example, only pages whose content type is `article`.                                                                  |
| **Who bypasses it** | Visitors who are never metered: anyone with a paid entitlement, members of selected segments, or both.                                                                                                                    |
| **Enabled**         | Turns the meter off without deleting it.                                                                                                                                                                                  |

Calendar periods start at midnight in your organization's timezone. A rolling period counts the views from the last N days, so the oldest view drops off as each day passes.

**What counts** can only use conditions about the page and the time, such as URL path, section, or content type. It can't use member data, because the meter counts a visitor before Allegro knows who they are.

##### Changes That Reset Counts[​](#changes-that-reset-counts "Direct link to Changes That Reset Counts")

Changing the limit, the period, the counting mode, or **What counts** resets every visitor's count to zero, because the old counts no longer mean the same thing. Renaming a meter, turning it on or off, or changing who bypasses it keeps the counts.

#### How Views Are Counted[​](#how-views-are-counted "Direct link to How Views Are Counted")

Allegro counts a view each time your site loads a page with the Allegro site tag. A signed-in member is counted as the same person on every device. An anonymous visitor is counted per browser.

When a page loads, Allegro checks each enabled meter in this order:

1. If the visitor bypasses the meter, it isn't counted and its status is **Exempt**.
2. If the page matches **What counts**, the view is recorded. With **Unique pages**, a page the visitor already read this period isn't counted again.
3. Journeys are evaluated, so every condition sees the count *including* this page view.

#### Targeting a Meter[​](#targeting-a-meter "Direct link to Targeting a Meter")

Each meter adds four attributes to the **Meters** category of the journey condition picker. They appear as soon as you save the meter.

| Attribute                           | Operators                            | Value                                                                                                      |
| ----------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| **Meter status: *name***            | is, is not, is one of, is not one of | **Under limit**, **Over limit**, or **Exempt (bypassed)**                                                  |
| **Meter remaining: *name***         | Numeric operators                    | Free views left in the current period. Never below zero                                                    |
| **Meter used: *name***              | Numeric operators                    | Views counted in the current period, including this one. With **Unique pages**, this counts distinct pages |
| **Meter counted this view: *name*** | is true, is false                    | Whether this page view added one to the count                                                              |

"Numeric operators" means =, ≠, >, ≥, <, ≤, between, and is set.

A visitor is **Over limit** once they have used *more* views than the limit. A meter with a limit of 5 lets the visitor read five pages. The sixth counted page puts them over the limit.

**Meter counted this view** is false when the page doesn't match **What counts**, when a **Unique pages** meter has already counted the page, and for a visitor who bypasses the meter. Combine it with **Over limit** to keep pages a reader opened before running out free to reread.

##### Examples[​](#examples "Direct link to Examples")

| Goal                                                                   | Conditions                                                                  |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Show the paywall once the free articles run out                        | **Meter status** is **Over limit**                                          |
| Nudge readers who are close to the limit                               | **Meter status** is **Under limit** and **Meter remaining** ≤ 2             |
| Ask for a registration after the third article                         | **Meter used** ≥ 3 and **Authenticated** is false                           |
| Show a "that's one of your free articles" message                      | **Meter counted this view** is true and **Meter status** is **Under limit** |
| Show the wall on new articles only, so articles read earlier stay open | **Meter status** is **Over limit** and **Meter counted this view** is true  |

##### When a Meter Has No Value[​](#when-a-meter-has-no-value "Direct link to When a Meter Has No Value")

A condition on a meter matches nobody when the meter is turned off or deleted, or when Allegro can't count the visitor. That includes a **Per session** meter on a site whose tag doesn't send a session. For a visitor who bypasses a meter, **Meter remaining** and **Meter used** have no value, so target **Meter status** is **Exempt** instead.

[Potential Reach](/product/interactions/potential-reach.md) can't estimate meter conditions and shows **No estimate** for them. They still work on your site.

#### Showing a Meter in a Template[​](#showing-a-meter-in-a-template "Direct link to Showing a Meter in a Template")

A template can show a visitor's meter numbers with a placeholder that names the meter's slug and a field:

```html
<p>
    You've read {% meter.monthly-articles.used %} of {%
    meter.monthly-articles.limit %} free articles this month.
</p>

```

Find the slug under **Meter name** when you open a saved meter. It's the meter's original name in lowercase with hyphens, for example `monthly-articles`, and it stays the same if you rename the meter.

| Placeholder                    | Shows                                                                | Example       |
| ------------------------------ | -------------------------------------------------------------------- | ------------- |
| `{% meter.<slug>.used %}`      | Views counted in the current period, including this one              | `3`           |
| `{% meter.<slug>.limit %}`     | The meter's limit                                                    | `5`           |
| `{% meter.<slug>.remaining %}` | Free views left in the current period, never below zero              | `2`           |
| `{% meter.<slug>.status %}`    | `under_limit`, `over_limit`, or `exempt`                             | `under_limit` |
| `{% meter.<slug>.counted %}`   | `true` when this page view added one to the count, otherwise `false` | `true`        |

The same placeholders work in an interaction's field values, so editors can write "Only {% meter.monthly-articles.remaining %} free articles left" into a headline field without changing the template.

##### Empty Values[​](#empty-values "Direct link to Empty Values")

A placeholder renders as an empty string, never as `null` or `undefined`, when:

* the slug doesn't match any meter, or the meter is turned off or deleted;
* the visitor bypasses the meter (`used` and `remaining` only; `status` shows `exempt`, `limit` shows the limit, and `counted` shows `false`);
* Allegro couldn't count the visitor on this page.

To avoid a sentence with a gap in it, show meter copy only from a journey that targets the meter. For example, show the "2 left" message only when **Meter status** is **Under limit**.

tip

`status` and `counted` render as plain values such as `under_limit` or `true`. They're most useful in template logic, for example `x-show="'{% meter.monthly-articles.status %}' === 'over_limit'"`.


---

### Potential Reach

Potential reach shows, as you edit, how many visitors each [journey](/product/interactions/journeys.md) would have matched over the last 30 days of your analytics data. Use it to catch a journey that is too broad or too narrow before you publish.

Availability

Potential reach requires the analytics service and must be enabled for your organization. When it is off, the **Potential reach** option does not appear and the editor shows no counts.

#### Opening the Panel[​](#opening-the-panel "Direct link to Opening the Panel")

In the **Journeys** header, click **Potential reach** in the side panel switcher. The panel docks to the right of the editor. Click **Potential reach** again to close it. Whether the panel is open is remembered per Interaction.

The [Assistant](/product/interactions/assistant.md) shares the same dock: opening one closes the other.

#### Reading the Panel[​](#reading-the-panel "Direct link to Reading the Panel")

The header shows the total: ***N* visitors · the last 30 days**. Below it, a stacked bar divides those visitors among your journeys in order, with the remainder attributed to **Everyone else**. A status line reads **Live · updates as you edit** while counts are current and **Recalculating…** while a change is being counted; the numbers dim rather than disappear during recalculation.

**Selected journey.** Click a journey card in the builder, or a row in the panel, to select it. The card shows the journey's headline count and a subtitle such as **12.4K match · 3.1K claimed by earlier journeys**, then a breakdown with a count for each group and each condition.

**All journeys.** One row per journey with its share of the bar and its count, followed by the **Everyone else** remainder.

**What to fix.** Advisories derived from the counts:

| Advisory                                                       | Meaning                                                                             |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| *Journey* group *n* matches 95% or more of visitors            | Journeys below it will almost never run. Narrow the group or move the journey down. |
| *Journey* can't be estimated — *Attribute* isn't in event data | The journey uses an attribute the analytics data does not carry (see below).        |

The last journey is exempt from the "too broad" advisory, since nothing runs after it anyway.

#### Counts in the Editor[​](#counts-in-the-editor "Direct link to Counts in the Editor")

With the panel open, the builder annotates itself:

| Where          | Annotation                                                                                                                  |
| -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Journey header | A pill reading ***N* reachable** with the journey's share of all visitors (for example `8.2%` or `41%`), or **No estimate** |
| Journey header | An amber **Too broad** pill when one of its groups matches 95% or more of visitors                                          |
| Group header   | ***N* match**, or a note explaining why the group cannot be estimated                                                       |
| Everyone else  | ***N* reachable** — the visitors no journey claims                                                                          |

#### How the Numbers Work[​](#how-the-numbers-work "Direct link to How the Numbers Work")

**Visitors are devices.** Each count is the number of distinct devices seen in the last 30 days that would have matched. A person who reads on a phone and a laptop counts twice.

**Earlier journeys claim visitors first.** A journey's headline number is its *effective* reach: the visitors it matches minus those already taken by journeys above it. The subtitle shows both the raw match and the claimed portion. If an earlier journey cannot be estimated, the overlap cannot be subtracted and the subtitle reads **overlap with earlier journeys not counted**.

**Counts are historical.** They describe visitors who were on your site in the window. A brand-new condition — a section that launches next week, a campaign that has not started — can match visitors this window never saw, so a low count is not always a mistake.

#### When There Is No Estimate[​](#when-there-is-no-estimate "Direct link to When There Is No Estimate")

| Situation                                                                     | What you see                                                                                                          |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| A condition is still being written                                            | **Can't estimate this group yet. Finish its conditions and the estimate will fill in.**                               |
| A condition uses an attribute not in event data                               | **Can't estimate this group. *Attribute* isn't recorded in event data. It will still evaluate correctly at runtime.** |
| A [cohort](/product/interactions/cohorts.md) condition is **matches none of** | **Reach isn't counted for "matches none of" cohort conditions.**                                                      |
| The journey has too many condition combinations                               | **Too many condition combinations to estimate.**                                                                      |
| The analytics service is unavailable                                          | **Estimates unavailable right now** and a **Not counting right now** status line                                      |

The attributes that can never be estimated are Country, Region, City, ZIP / postal code, Continent, Privacy law, Referrer type, Query parameter, Cookie, Visitor timezone, and External profile data. Meter and integration-provided conditions cannot be estimated either. Journeys using them work normally on your site; the panel simply cannot count them.

An [A/B test variant](/product/interactions/ab-tests.md) condition is estimated from the test's share of traffic and its variant weights, so you can see a draft test's reach before starting it.

#### Related[​](#related "Direct link to Related")

* [Journeys](/product/interactions/journeys.md) — Building and ordering journeys
* [Targeting Conditions](/product/interactions/conditions.md) — Every attribute and operator
* [Cohorts](/product/interactions/cohorts.md) — Reusable condition sets, and how their reach is estimated
* [Testing Journeys](/product/interactions/testing.md) — Check a specific visitor rather than a population


---

### Priority

Several automatic interactions can match the same page view. A "Spring campaign paywall" and a "Newsletter prompt" might both apply to the same reader, and without any rules every match shows. **Priority** is a ranked list that decides which interactions win and what else may still show alongside them.

Open it from **Interactions → Priority** in the dashboard sidebar. There is one list for the whole tenant, and it starts empty. While it is empty, nothing is hidden.

#### Add interactions[​](#add-interactions "Direct link to Add interactions")

1. Click **Add interactions** at the top right of the list. On an empty list the same button also appears in the middle of the page.
2. In the **Add interactions** drawer, search and check the interactions you want. The drawer lists automatic interactions that are not ranked yet.
3. Confirm. New interactions go to the bottom of the list.

Only interactions that trigger automatically can be ranked. Manual interactions never go through targeting, so they are not offered and can't take part.

Draft and archived interactions can stay on the list, and the Status column shows which they are. They never show, so they never hide anything either.

Use the search box to find a ranked interaction by name. You can't reorder the list while a search is active; clear the search first.

#### Rank the list[​](#rank-the-list "Direct link to Rank the list")

The interaction at the top has the highest priority. To change the order:

* Drag a row to a new position.
* Focus a row's drag handle and use the keyboard to move it.
* Open the row menu and choose **Move up** or **Move down**.

The new order saves as soon as you drop the row.

#### Set conflicts[​](#set-conflicts "Direct link to Set conflicts")

Each ranked interaction has a conflict rule that applies when it shows. Open the row menu and choose **Edit conflicts**. Under **When this shows, hide:**, pick one option.

| Option                               | What it does                                                                                       |
| ------------------------------------ | -------------------------------------------------------------------------------------------------- |
| **All other interactions** (default) | Hides every interaction ranked below it and every interaction that is not on the list.             |
| **Only selected interactions**       | Hides only the interactions you check. Everything else is left alone.                              |
| **All except selected interactions** | Hides every interaction ranked below it and every unlisted one, except the interactions you check. |

The two selecting options show a searchable checklist. It offers interactions ranked lower than this one, plus interactions that are not on the list. Interactions ranked higher are never hidden by this one.

To take an interaction off the list, choose **Remove** in the row menu. It then shows or hides based only on the other ranked interactions' rules.

#### How rules apply[​](#how-rules-apply "Direct link to How rules apply")

Allegro goes down the list from the top, looking only at interactions that match the current page view:

1. A matching interaction that is still showing applies its rule to the interactions ranked below it and to unlisted interactions.
2. A matching interaction that has already been hidden applies nothing.
3. Rules only reach downward, so a lower-ranked interaction can never hide a higher-ranked one.

An interaction that is on the list but does not match the page view takes no part, and neither do its rules.

##### Example[​](#example "Direct link to Example")

Interactions A, B, and C are ranked, and F is not on the list. All four match.

| Interaction | Rank     | Conflict rule          |
| ----------- | -------- | ---------------------- |
| A           | 1        | Only selected: C       |
| B           | 2        | All other interactions |
| C           | 3        | All other interactions |
| F           | Unlisted | None                   |

A hides C. B is still showing, so it hides F. C is already hidden, so its rule does nothing. Only A and B show.

##### Cascading example[​](#cascading-example "Direct link to Cascading example")

Interactions A, B, and C are ranked in that order, and F is not on the list.

| Interaction | Conflict rule          |
| ----------- | ---------------------- |
| A           | All except selected: F |
| B           | All other interactions |
| C           | All other interactions |

| If these match | What shows | Why                                                                          |
| -------------- | ---------- | ---------------------------------------------------------------------------- |
| A, B, C, F     | A and F    | A hides B and C and spares F. B and C are hidden, so their rules do nothing. |
| B, C, F        | B          | B hides C and F.                                                             |
| C, F           | C          | C hides F.                                                                   |

#### Things to know[​](#things-to-know "Direct link to Things to know")

* **Unlisted interactions never hide anything.** They can be hidden by a listed interaction, but they have no rule of their own.
* **An interaction has to display to win.** If a ranked interaction has reached its frequency cap and none of its actions display, it doesn't count: it hides nothing, and the next ranked interaction takes its place. If only some of its actions are capped and the rest still display, it counts, and its rule applies. For example, if a "Spring campaign paywall" is capped at three views per reader, a "Newsletter prompt" ranked below it can show from the fourth view on.
* **Hidden interactions don't use up frequency caps.** An interaction that a rule hid wasn't shown, so it doesn't count toward its own cap.
* **Reordering can strand a selection.** If a reorder puts a selected interaction above the one that selected it, the rule keeps the selection but ignores it.

#### Check the result[​](#check-the-result "Direct link to Check the result")

The [workbench](/product/interactions/testing.md) shows **Hidden by** followed by the interaction's name for any interaction that a conflict rule hid on that page view. If an interaction you expect is missing, look there first.


---

### Report

The report shows how an **Automatic targeting** [interaction](/product/interactions.md) has actually performed: how many pages it ran on, how that splits across your [journeys](/product/interactions/journeys.md), and how it trends day by day. Where [Potential Reach](/product/interactions/potential-reach.md) projects who a journey *would* match while you edit, the report counts what really happened.

Availability

The report is available only for a **saved, Automatic targeting** interaction and requires the analytics service. A Manual embed interaction has no journeys to report on, so it has no report. Anyone who can view the interaction can open its report, including viewers.

#### Opening the Report[​](#opening-the-report "Direct link to Opening the Report")

* From the interaction's edit page, choose **View report** in the **⋯** menu. The entry appears once the interaction is saved and in Automatic targeting mode.
* From the **Journeys** builder, click the activity pill on any journey header — it reads, for example, **1.2K runs · 30d** and opens the full report. Its tooltip summarizes recent activity ("Ran on *N* pages for *N* visitors in the last *N* days. Picked on *N* pages.") with a small trend line.

#### Choosing a Window[​](#choosing-a-window "Direct link to Choosing a Window")

A window switcher in the report header covers the **last 7**, **30**, or **90 days**. The window defaults to 30 days and applies to every number and download on the page.

#### Reading the Report[​](#reading-the-report "Direct link to Reading the Report")

Two words run through the whole report:

| Term       | Meaning                                                 |
| ---------- | ------------------------------------------------------- |
| **Picked** | Targeting chose a journey on the page view.             |
| **Ran**    | That journey's actions went on to run on the page view. |

A page can be picked without the actions running — for example, a one-per-visit frequency cap or a meter that hasn't been reached yet keeps the actions from firing even though targeting selected the journey.

##### Totals[​](#totals "Direct link to Totals")

Three figures summarize the window:

| Stat                | What it counts                             |
| ------------------- | ------------------------------------------ |
| **Pages it ran on** | Pages where the interaction's actions ran. |
| **Pages picked**    | Pages where targeting chose any journey.   |
| **Run rate**        | Ran ÷ picked, as a percentage.             |

##### Daily activity[​](#daily-activity "Direct link to Daily activity")

A chart plots **Picked** and **Ran** for each day in the window, so you can see launches, spikes, and quiet stretches at a glance. Days are counted in your organization's timezone.

##### By journey[​](#by-journey "Direct link to By journey")

A table breaks the window down one row per journey — including **Everyone else** — with **Picked**, **Ran**, **Run rate**, and **Visitors** columns. A journey removed since it last ran still appears, labeled **Deleted journey**, so its past activity isn't lost.

**Visitors** counts distinct visitors on pages where the journey ran. A visitor who saw more than one journey over the window is counted under each, so the journey visitor counts can add up to more than the interaction's total.

#### Downloads[​](#downloads "Direct link to Downloads")

* **Download CSV** exports one row per day and journey for the selected window, with a short header naming the interaction, window, and generation time.
* **Download PDF** opens your browser's print dialog on a print-ready copy of the report; choose *Save as PDF* (or print) from there.

note

If the analytics service doesn't answer, the report shows a short "results are unavailable right now" message in place of the numbers and fills in once the service responds. The CSV notes the same when results are unavailable.

#### Related[​](#related "Direct link to Related")

* [Potential Reach](/product/interactions/potential-reach.md) — Projected reach while you edit, versus the actual activity shown here
* [Journeys](/product/interactions/journeys.md) — Building and ordering the journeys the report breaks down
* [A/B Tests](/product/interactions/ab-tests.md) — Compare variants of an interaction with its own report
* [Testing Journeys](/product/interactions/testing.md) — Check a specific visitor rather than the population


---

### Revisions

Every change you make to a template is saved as a revision. That means you can experiment freely, knowing you can always get back to a working version. No change is permanent unless you want it to be.

GitHub-managed templates

Templates synced from a GitHub repository are managed upstream, so Allegro doesn't keep separate in-app revisions for them — their history lives in the repository's commit log. When you open a synced template, the editor is read-only and shows a **Managed by GitHub** label in place of the **Show Revisions** button.

#### What gets tracked[​](#what-gets-tracked "Direct link to What gets tracked")

Every time you save, Allegro creates a new revision automatically. Each revision stores:

* A full snapshot of the content at that moment
* Who made the change
* When it happened
* An optional note describing what changed

Revisions are numbered starting from 1. The first save after creating a template is revision #1.

#### Viewing history[​](#viewing-history "Direct link to Viewing history")

Open a template and click the **History** tab. You'll see every revision listed newest-first — the revision number, who made it, when, and any note that was attached.

#### Adding notes[​](#adding-notes "Direct link to Adding notes")

You can attach a note to any save to explain what you changed and why. Notes are optional, but they're worth adding for anything meaningful — a bug fix, a new section, a major rewrite.

Use notes for team communication

Think of revision notes like commit messages. A short note such as "Updated pricing for Q3 launch" saves your teammates from having to diff two versions to understand what happened.

#### Rolling back[​](#rolling-back "Direct link to Rolling back")

Made a mistake? Restore any previous revision:

1. Open the template's **History** tab.
2. Find the revision you want.
3. Click **Restore**.
4. Optionally add a note explaining why you rolled back.

A rollback creates a **new revision** — it doesn't erase history. That means you can always undo a rollback, too. Restored revisions are labeled **\[RESTORE]** in the history so you can tell them apart.

#### Permissions[​](#permissions "Direct link to Permissions")

Revision access follows the template. If you can view a template, you can view its full revision history.

Revision limits

Templates keep unlimited revisions by default. If a maximum is configured (for example, keep the last 20), the oldest revisions are pruned automatically. Revisions that were used as the source of a rollback are never pruned, so the audit trail for restores is always preserved.

#### Related[​](#related "Direct link to Related")

* [Templates](/product/interactions/templates.md) — the primary content type that uses revisions
* [Interactions](/product/interactions.md) — interactions also track revision history


---

### Templates

Templates are reusable building blocks for the experiences you deploy to your readers. Design a component once — with its own HTML, JavaScript, and CSS — then use it across as many [Interactions](/product/interactions.md) as you need.

#### Overview[​](#overview "Direct link to Overview")

Think of a template as a self-contained widget. It holds everything the browser needs to render a component: markup for structure, styles for presentation, and scripts for behavior. On top of that, you can define **fields** — named placeholders that each Interaction fills in with its own values — so one template can power many different experiences.

Templates also support **external CSS URLs** for loading fonts, icon libraries, or CSS frameworks alongside your code.

![Templates](/assets/images/templates-d1cc06ca305a5c3a04c82a703280d2d1.png)

#### Creating a Template[​](#creating-a-template "Direct link to Creating a Template")

Head to **Templates → New Template**, give it a title, and start writing your HTML, CSS, and JavaScript. A URL-friendly slug is generated from the title on first save. Renaming the template later won't change the slug, so any Interactions that reference it stay linked.

##### Editor assistance[​](#editor-assistance "Direct link to Editor assistance")

As you type HTML, the editor autocompletes Allegro's web components — such as `<allegro-login-form>`, `<allegro-email-form>`, `<allegro-content-gate>`, and `<allegro-content-gate-inline>` — and shows hover documentation describing what each element does. Completion for your template [fields](#fields) (`{% field %}`) works alongside it, so you don't have to remember exact element or field names.

#### Status[​](#status "Direct link to Status")

Every template starts as a **Draft** so you can iterate without affecting live Interactions. When you're ready, publish it.

| Status        | Meaning                                                  |
| ------------- | -------------------------------------------------------- |
| **Draft**     | Work in progress — not available for use in Interactions |
| **Published** | Ready to use                                             |

#### Fields[​](#fields "Direct link to Fields")

Fields make templates flexible. Instead of hard-coding copy or settings, you define named variables that each Interaction supplies at render time.

For example, a "Subscribe Banner" template might expose a `headline` field. One Interaction sets it to "Join our newsletter", another to "Get daily updates" — same template, different message.

Each field has these properties:

| Property        | Description                                                                                                |
| --------------- | ---------------------------------------------------------------------------------------------------------- |
| **Name**        | A human-readable label (e.g. "Email Placeholder")                                                          |
| **Slug**        | The variable name used in your code (e.g. `emailPlaceholder`). Auto-generated from the name if left blank. |
| **Description** | Help text shown to whoever configures the Interaction                                                      |
| **Type**        | Text, Textarea, Rich text, Number, Checkbox, Select, or Group — see [Field Types](#field-types)            |
| **Label**       | The name shown to whoever fills the field in. Defaults to the slug in words.                               |
| **Tab**         | The tab the field appears in when an Interaction fills it in. Fields without one appear under **General**. |

##### Field Types[​](#field-types "Direct link to Field Types")

| Type          | What the Interaction editor fills in                                 |
| ------------- | -------------------------------------------------------------------- |
| **Text**      | A single line of text                                                |
| **Textarea**  | Several lines of plain text                                          |
| **Rich text** | Formatted text: bold, italic, links, and bulleted and numbered lists |
| **Number**    | A number                                                             |
| **Checkbox**  | On or off                                                            |
| **Select**    | One choice from a list of options you define on the field            |
| **Group**     | A list of items, each with its own set of subfields (see below)      |

For a **Select** field, add each option in the field's **Options** list. The value is what your template receives; the optional label is what the Interaction editor sees.

For a **Rich text** field, untick any formatting under **Formatting** that editors shouldn't use. Everything else a field holds appears on the page as plain text, so HTML typed into a Text or Textarea field shows as typed.

##### Repeatable Fields and Groups[​](#repeatable-fields-and-groups "Direct link to Repeatable Fields and Groups")

Turn on **Repeatable** for a field when an Interaction needs a list of values instead of one, such as several links. The Interaction editor can then add, remove, and reorder items.

Use a **Group** when each item needs more than one value. For example, a newsletter sign-up template can have a `newsletters` group with `title`, `image`, and `id` subfields, so each Interaction lists its own newsletters. Groups are always repeatable. A group's subfields can be repeatable or groups themselves, so an FAQ can have a `sections` group whose items each hold a `questions` group of questions and answers. Groups nest up to three levels.

Text, Number, Checkbox, and Select values can be up to 200 characters; Textarea and Rich text values up to 10,000. A list can have up to 50 items.

##### Tabs[​](#tabs "Direct link to Tabs")

Give fields a **Tab** to split a long list of fields into tabs when an Interaction fills them in, such as **Header**, **FAQ**, and **Contact**. Tabs appear in the order of their first field, after a **General** tab for fields without one. The Fields list in the template editor groups fields the same way.

##### Default values[​](#default-values "Direct link to Default values")

A field can ship with a default value, defined by whoever builds the template. When an Interaction uses the template, every field starts filled in with its default. Fields you leave alone keep following the template, so a later change to the default reaches them. Once you edit a field, the Interaction keeps its own value, even if you clear it.

##### Using Fields in Your Code[​](#using-fields-in-your-code "Direct link to Using Fields in Your Code")

Reference a field by wrapping its slug in `{% %}` anywhere in the HTML:

```html
<h1>{% headline %}</h1>
<input placeholder="{% emailPlaceholder %}" />

```

Repeat part of the HTML for each item of a repeatable field with a loop. Inside the loop, `{% item %}` is the current item, and `{% item.title %}` is a group item's `title` subfield:

```html
{% for newsletter in newsletters %}
<h3>{% newsletter.title %}</h3>
{% endfor %}

```

Typing `{%` in the HTML editor suggests every field, and picking a repeatable field inserts its loop for you.

Templates can also show a visitor's meter numbers, such as how many free articles they have left, with `{% meter.<slug>.remaining %}` and similar placeholders. See [Showing a Meter in a Template](/product/interactions/meters.md#showing-a-meter-in-a-template).

#### External CSS URLs[​](#external-css-urls "Direct link to External CSS URLs")

Need Google Fonts, a CSS reset, or a utility framework? Add the stylesheet URLs to the template and they'll be injected as `<link>` tags at render time — no manual `<head>` editing required.

#### Revision History[​](#revision-history "Direct link to Revision History")

Every save creates a new revision automatically. You can browse the full history, compare any two versions side by side, and roll back whenever you need to. See [Revisions](/product/interactions/revisions.md) for details.

#### Archiving[​](#archiving "Direct link to Archiving")

Templates are never permanently deleted right away. Instead, you **archive** them:

* Archived templates disappear from normal listings.
* Members and admins can restore an archived template at any time.
* Only admins can permanently delete one.

To archive, open the template and choose **Archive** from the actions menu. To restore, switch to the **Archived** filter in the Templates list.

#### Permissions[​](#permissions "Direct link to Permissions")

For details on who can manage templates, see [Permissions](/product/administration/permissions.md).

#### Showing Plans[​](#showing-plans "Direct link to Showing Plans")

A template can show the plans of an [offer](/product/entitlements/offers.md), such as a "choose your subscription" card. On the template's **Options** tab, check **Shows plans from an offer**. Templates synced from GitHub declare this in their `template.json` instead.

Once a template shows plans:

* Every Interaction that uses it must choose an **Offer**. The picker appears under the template in the Interaction editor and lists each offer with its number of plans.
* The template shows that offer's plans in the order set on the offer, along with each plan's [plan fields](/product/entitlements/plan-fields.md) that aren't marked private.
* A field on the template can't use the slug `plans`.
* Template previews show two sample plans, not the chosen offer's plans.

If an Interaction has no offer, or its offer has no plans, the template is not shown to readers. The Interaction editor warns you when this happens.

Changes to the offer's plans, such as a new price or a different order, reach readers without editing or republishing the Interaction.

For the placeholders and data a template uses to show plans, see [Plans](/developer/guides/templates.md#plans) in the developer docs.

#### Editing template.json[​](#editing-templatejson "Direct link to Editing template.json")

Every template has a [`template.json`](/developer/guides/template-json.md) that describes its name, fields, and options as JSON. To see it, open the template, go to the **Options** tab, and click **Edit template.json**.

The file always matches the template: it reflects the fields on the **Fields** tab, including changes you haven't saved yet. To change the template through it:

1. Edit the JSON. The editor suggests properties and field types as you type, shows each property's description when you hover over it, and underlines anything that doesn't match the [schema](https://docs.allegroaudience.com/template.schema.json).
2. Click **Apply**. The name, fields, and options update on their tabs. If the JSON has errors, Apply lists them and changes nothing.
3. Click **Save** to keep the changes, as with any other edit.

Properties templates don't store, such as `plans`, are listed before you apply and left out.

For a template synced from GitHub, the button reads **View template.json** and shows the file as it was last synced. Edit it in the repository instead.

Moving a template to GitHub

To move a template you built in Allegro into a GitHub-synced repository, copy its `template.json` into a folder alongside the template's `index.html`, `index.css`, and `index.js`. The `template_json` value returned by the REST API's get template endpoint and the MCP `get-template` tool has the same contents.

#### How Templates Render[​](#how-templates-render "Direct link to How Templates Render")

When an Interaction triggers, Allegro injects the template into the page at the configured position. Each template runs in its own isolated environment, so its styles won't affect the rest of the page and the page's styles won't bleed in.

Templates support **Alpine.js** for reactive behavior and Allegro's **web components** (login form, email capture, content gate) out of the box — no extra setup required.

For technical details on the rendering model, available JavaScript context, and Alpine.js data, see the [Templates guide](/developer/guides/templates.md) in the developer docs.

#### Tips[​](#tips "Direct link to Tips")

* **Keep CSP in mind.** Template HTML, CSS, and JavaScript run in the reader's browser. If your site enforces a strict Content Security Policy, make sure inline scripts and styles are allowed.

#### Related[​](#related "Direct link to Related")

* [Interactions](/product/interactions.md) — Deploy templates to your readers
* [Revisions](/product/interactions/revisions.md) — Full version history and rollback


---

### Testing Journeys

Two tools show you which journey a visitor follows and why. **Evaluate** runs a simulated visitor against the journeys in the editor without touching your site. **Debug on site** opens a real page on your site with an overlay that explains every automatic Interaction's decision for your own browser.

#### Evaluate (Simulator)[​](#evaluate-simulator "Direct link to Evaluate (Simulator)")

Click **Evaluate** in the **Journeys** header to open the **Evaluate journeys** panel.

1. Click **+ Add attribute** and pick an attribute, then enter the value the simulated visitor should have. **Identified** and **Authenticated** are pre-filled as false. **Clear** resets a value to unknown, and **×** removes the attribute.
2. Repeat for every attribute your journeys test. Anything you leave blank is treated as unknown — exactly as on your site when a value cannot be resolved — so conditions on it are false.
3. Click **Evaluate**.

Each journey card gets a badge: **Matched · winner** on the first journey that matched, **Matched** on later journeys that would also have matched, and **No match** on the rest. The winning journey and its true conditions flash in the builder. If nothing matches, the visitor lands on **Everyone else**.

Below the button, the panel names the result, for example **Matched: VIP readers**, and lists every journey with a trace you can expand. The trace shows each group (**All of** or **Any of**) and each condition marked ✓ or ✗, with the value the condition expected and the simulated visitor's actual value.

![Evaluate results: the first journey marked Matched · winner, the second No match, and a trace of each condition](/assets/images/evaluate-result-7cdb2189b8c701ce3951cab8f30c66c5.png)

The simulator evaluates the journeys as they are in the editor, unsaved edits included, and never runs actions or reads real member data. Results clear whenever you change a journey. Derived attributes (Continent and Privacy law) cannot be entered directly; set Country and Region instead. Referrer type can be entered directly, or left out and worked out from Referrer.

#### Debug on Site[​](#debug-on-site "Direct link to Debug on Site")

Debug on site lets you load a page on your live site and see, for every published automatic Interaction, what Allegro resolved about the request and which journey it chose.

1. Save the Interaction if you have not already, then choose **Debug on site** from the **⋯** menu in the header. (The same tool is available for all Interactions under **Developer → Workbench** in the dashboard sidebar.)
2. Enter a URL from your site. It must start with `https://`.
3. Click **Generate debug link**, then **Copy** or open the link.

![The Workbench page, where you enter a page URL and generate a debug link](/assets/images/workbench-link-dfaa09f0f2c9c26df44e0695f89b09e4.png)

The page loads with the **Allegro Workbench** pill in the bottom-left corner. Click it (or press Ctrl+Shift+A) to open the workbench panel, docked to the bottom of the page:

![The workbench panel open on a page, showing an Interaction\&#39;s winning journey and the result of each condition](/assets/images/workbench-d4a49e2bca6d0744744a6e8f8fc8cf44.png)

* **Overview** — which Interactions are shown on this page and which are not.
* **Interactions** — each published automatic Interaction with its journeys marked matched or not and the winner named (or **Everyone else (default)**), down to the expected and actual value of every condition.
* **Actions** — each action that ran, and whether it applied or failed.
* **Request** — what the server resolved for this page view, grouped as Request, Device, Geo, Time, Session, and Member, with the reason for anything it could not determine.
* **Events** — Allegro events as the SDK records them, live.
* **Identity** — the member, device, and session IDs for your browser.

Click **Re-evaluate** to run targeting again without reloading — useful after signing in on the site. The workbench stays on in every tab on that site until you click **Exit** in the panel, or for up to 30 days.

note

The overlay shows the decision for *your* browser: member conditions reflect your own session, and location and device reflect the machine you are using. Actions still render as they would for any visitor. To test a different kind of visitor, use the simulator above.

#### Related[​](#related "Direct link to Related")

* [Journeys](/product/interactions/journeys.md) — How evaluation and unknown values work
* [Cohorts](/product/interactions/cohorts.md) — Evaluate a cohort's own conditions the same way
* [Potential Reach](/product/interactions/potential-reach.md) — How many visitors a journey would reach
* [Previewing a Draft](/product/interactions.md#previewing-a-draft-on-your-site) — Preview a manual-embed draft on your site


---