Skip to main content
Use window.Puntego when your app already knows the right target or workflow and wants the guide to show it without waiting for a model turn. This is the imperative side of the guide: you call a method, the guide points, highlights, scrolls, or walks a tour right away. Importing @puntego/embed augments the global Window, so window.Puntego is fully typed in TypeScript. The methods below are part of that typed surface unless a section says otherwise.
The @puntego/embed import is a release preview: the package publishes to npm at launch. The window.Puntego runtime surface is available today after the hosted script install boots; package imports become usable once the package is published.
Call these methods after the runtime is ready. Wait for the ready event (or whenPuntegoReady from @puntego/embed/loader) before driving the guide, since window.Puntego is only present once the boot script has mounted.

Point, highlight, and scroll

These three single-shot methods cover most “show the visitor this element” cases. highlight and scrollTo run synchronously and return void; point returns a Promise<boolean> that resolves true when the pointer landed on the target.
Pass a CSS selector, an element, or a target object. The optional second argument is the caption the guide shows next to the cursor.

Show multiple markers

Use markers to label several elements at once — for example, to annotate a pricing grid or a multi-step form.

Run a guided tour

Use tour to chain steps into a single narrated sequence. Each step names a target and a step type (point, scroll, spotlight, or caption). In a tour you start, a spotlight step dims the rest of the page around its target; the page stays usable under the dim.
The tour runs in the guide’s card: “1 of 2” with Back and Next in its footer, and the step’s target outlined on the page. When a step belongs on a specific page, give it a route (a same-origin path; * matches any run of characters, so /projects/*/settings covers every project). A page change then completes the step only when it lands on the next step’s route; any other page shows “You left the flow” with Go back and End tour, and returning to the step’s page picks the tour back up. Tours adapt to the page as it is. A step that goes as planned costs nothing extra; only when the page is not what a step expected does the guide re-plan that one step:
  • The visitor wanders off. The card names your page’s own link back to the step and outlines it. Following that link picks the tour back up, the same as Go back.
  • A step’s control moved or was renamed. The guide outlines it where it is now, and the step completes when the visitor uses it.
  • A step is already done. A step whose field already holds the value it asks for is skipped, and the next card says so.
  • The visitor comes back later. After a reload or a return, the card says how far they had got (“You had finished 2 of 4”).
A re-plan only ever points. It never clicks, types, or navigates for the visitor, and it never outlines a control your Guide Action Contract switches off or a protected field. The tour’s title is its goal, so give it one that names what the visitor is trying to get done.

Use the control namespace

The same controls are mirrored under window.Puntego.control for product-owned helpers that want a stable namespace. The visual methods (caption, highlight, scrollTo, markers, tour) return void; point returns a Promise<boolean> and speak returns Promise<void> — those two are the ones to await.

Register stable targets

Register stable IDs instead of relying on brittle selectors. Registered targets survive markup changes and give the guide a reliable handle on an element. Runtime registrations are grounding, not authorization. They describe your page to the guide so it can resolve “the Growth plan card” without guessing from the DOM. They do not add anything to your workspace’s declared-action allowlist: a page cannot grant itself a capability, because the browser is not a trusted source. Authorize an action by declaring it in your workspace’s Guide Action Contract, which the server holds. allowedActions on a registration is a narrowing hint for a target you have already declared, never a grant.
Call unregisterTarget('pricing-card-growth') when the element leaves the page so the guide stops resolving it.

Capture a target from the guide editor

For a tooltip nudge, open Live Target Capture in the guide editor (Dashboard → Guides). Choose a pathname such as /settings/billing; the recorder opens it on the workspace’s primary HTTPS origin only when that origin belongs to a DNS-verified domain. Full URLs, query strings, credentials, and backslashes are rejected; a fragment is accepted only when it names a page view (/#pricing, /app#/settings), never state or tokens. The one-shot recorder capability travels in window.name and is consumed when the window opens. Click one non-sensitive control, review the target ID, route, data-gp-id, and selector fallback, then choose Save Target & Apply. This performs a compare-and-set update of only that manifest target. The Experience draft receives only targetId and the route include; it never stores the selector. A page holds at most 100 targets. When it already has 100, the recorder records nothing new and never drops one to make room: your site shows “This page already has 100 targets” and the guide editor marks the capture Page at its limit. Recording a control again under a target ID the page already has still updates it. When the clicked element has both a product-authored data-gp-id and one unique DOM id, the contract preserves both: data-gp-id remains primary and the reviewed [id="…"] selector is its fallback. Runtime guidance tries that fallback only when the primary locator is missing or no longer reachable. It does not invent a selector at execution time. Prefer a product-authored data-gp-id for release-stable anchoring:
Puntego may create gp-N identifiers internally while observing the current page. The recorder recognizes those as temporary and never sends them to the editor. Without a product-authored data-gp-id, capture falls back only to a unique DOM id; if neither exists, the editor asks you to add a durable locator and keeps capture active. The recorder blocks hidden, password, OTP, identity, date-of-birth, payment, banking, insurance, and medical fields identified through native, label, name, placeholder, autocomplete, contenteditable, or ARIA evidence. It also blocks anything inside a data-puntego-ignore region, including the legacy data-sensitive="true", data-gp-private="true", and data-gp-ignore="true" spellings (see Privacy and PII). Ordinary email and telephone fields remain redacted from screenshots and model transit, but a visitor can review and confirm preparing those contact values; Puntego never submits the form automatically. A selector fallback remains reviewable, but the editor marks it as less stable so you can add a durable data-gp-id before release. The guide editor reports target configuration separately from live evidence: stable, fallback-only, sensitive-blocked, ambiguous/unstable, or missing/unavailable. “Stable” describes the locator contract, not current visibility. Releases adds blocking findings for protected or invalid tooltip anchors, warnings for fallback-only anchors, and separate runtime-evidence findings when available.

Generate or revise a local Experience draft

The Draft Assistant beside the real preview uses the server-side structured AI provider to propose typed draft operations. It receives the bounded prompt, the current typed draft, and the active audience catalog; it never invents an audience ID or writes outside the typed draft contract. The UI shows a reviewable field diff and every operation it could not apply. Both Generate Starter and Revise This Draft mutate only the local typed draft. Undo restores the prior local snapshot. The assistant never saves, deploys, activates, or publishes. Provider failure, refusal, timeout, or malformed output leaves the draft unchanged and offers a retry. Builder/preview state stays deep-linkable, while prompt text remains tab-local and never enters the URL.

Report workflow outcomes

When your app owns the state transition — a plan upgrade, a form submission, a booking — report the outcome so owners can see what happened. reportWorkflowResult is asynchronous, so await it.
Puntego records each SDK action proposal and result as an outcome trace for owner review in the dashboard. A reported result is a record of what the guide did — it does not edit your action manifest or feed an automated learning loop.

Inspect the current page

The typed getPageContext(), inspect(), and locateTarget() methods let an app inspect bounded snapshots of what the guide can currently see before driving it.
These are point-in-time, redacted snapshots rather than live DOM handles. Use window.Puntego.recordTarget() when an authorized editor should select and record a manifest target through the in-product recorder.

Let the guide read and change the visitor’s account

registerTool offers the guide functions of your page. A read tool (list invoices, read usage) runs when the guide needs the visitor’s own data to answer. A write tool (kind: 'write') makes one change the visitor asks for — an API key, a member’s access, a role, the plan or billing, the payment method — with the visitor’s own session and your API’s own permissions. It runs only after the visitor presses Do it on the guide’s card, which counts after a second and always offers I’ll do it instead; Growth and above, never for another AI agent. A secret it creates is shown by your own UI, inside an element marked data-puntego-ignore, and never reaches the guide. See Host tools and Write tools.

Let other AI agents use the guide

When an owner turns on Settings → Guide behavior → Other AI agents, an AI agent in the visitor’s browser can use the guide as a tool through WebMCP or window.Puntego.assist: ask a question, have the guide show the way, or ask for an action the visitor approves on the guide’s card. The agent never approves anything itself. See Other AI agents.
Every result carries a typed type (with status as the detail). Your own server can start the guide in a visitor’s live session too, with the Assist API (POST /api/v1/assist, an API key with assist:invoke).

Next steps

SDK reference

The full typed surface for window.Puntego — every method, event, and option in one place.

Verified Actions

Let the guide read or change a business object after policy checks, with confirmation and audit logging.