> ## Documentation Index
> Fetch the complete documentation index at: https://docs.puntego.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Experience Collections

> Mount reusable, remotely managed inline cards and banners while preserving production targeting, immutable revisions, and proof-bound engagements.

An Experience Collection is an app-scoped placement channel with a stable key
and an ordered list of Experience fallbacks. Puntego checks the authenticated
app, route, audience, bounded host event, and active production release, then
returns only the first eligible Experience. Candidates that fail eligibility
are never exposed to the browser.

Use Collections for native inline cards and banners that product teams need to
change without another host-product deploy. Collections accept typed Experience
content only; they are not arbitrary HTML or script slots.

> **Package release preview:** Collection delivery through Puntego's hosted
> runtime is implemented. The headless npm import shown below is the tested
> package contract, but `@puntego/embed` still requires public npm publication
> before customers can install that import from an external project.

## Configure a placement

In **Guides → Inline slots**, create a lowercase key such as
`onboarding_card`, choose a `card` or `banner` surface, and add Experiences in
fallback order. Every item needs an active production release before the
Collection can be activated.

The key and app binding stay immutable. Metadata, order, and lifecycle changes
use optimistic version checks, preventing a stale editor from overwriting a
newer update. Pause or archive a Collection to stop delivery.

## Mount the native surface

The shortest path needs no host JavaScript at all. Mark the slot with
`data-puntego-collection` and the installed Puntego snippet fills it:

```html theme={null}
<div data-puntego-collection="onboarding_card"></div>
```

The runtime reconciles these slots automatically: it mounts slots present at
load, slots your framework inserts later, and slots inside shadow roots you
registered with `Puntego.registerShadowRoot()`; it tears the surface down when
the slot is removed or the attribute is blanked, and it re-resolves in place
when you rewrite the key. SPA navigation and DOM mutation are both handled, so
there is nothing to call on route change. Keys must match the same shape as the
key in **Guides → Inline slots** — a lowercase letter, then lowercase letters, digits, `_` or `-`.
A malformed key logs one `[puntego]` console error instead of rendering.

Use the imperative API when you need the mount handle — to refresh or destroy
the surface yourself:

```ts theme={null}
const element = document.querySelector<HTMLElement>('#puntego-next-step');

if (element) {
  const placement = await window.Puntego?.mountExperienceCollection({
    element,
    placementKey: 'onboarding_card',
  });

  await placement?.refresh();
  placement?.destroy();
}
```

The SDK appends an isolated Puntego-owned child and does not replace existing
host children. It re-resolves mounted Collections after SPA navigation and
relevant host events. A valid empty result or definitive `404` clears only that
owned child. Transient network and server failures preserve the last known UI.

## Resolve for controlled headless UI

```ts theme={null}
import { createPuntegoHeadlessClient } from '@puntego/embed/headless';

const puntego = createPuntegoHeadlessClient();
const placement = await puntego.resolveExperienceCollection('onboarding_card');
const match = placement?.matches[0];

if (match) {
  renderTypedExperience(match.definition, placement.collection.surface);
  await puntego.engageExperienceCollection(
    'onboarding_card',
    match.experienceId,
    { kind: 'impression' },
  );
}
```

The snapshot contains typed deployed content and public Collection/revision
identity only. Signed proofs, credentials, environment selection, visitor
identity, ineligible candidate IDs, and arbitrary callbacks stay private. The
runtime uses its private proof to bind each engagement receipt to the exact
deployment and immutable revision that the visitor saw.

## Limits and operations

* 100 Collections per workspace;
* 50 distinct Experiences per Collection;
* production-only visitor resolution;
* one first eligible match per resolution;
* existing typed Experience events remain the analytics source of truth;
* workspace exports include Collection definitions and ordered items.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.