Skip to main content
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:
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:
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

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.