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.
Show multiple markers
Usemarkers to label several elements at once — for example, to annotate a pricing grid or a multi-step form.
Run a guided tour
Usetour 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.
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”).
Use the control namespace
The same controls are mirrored underwindow.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.
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:
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.
Inspect the current page
The typedgetPageContext(), 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 orwindow.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.
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.