Guide Tools SDK

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.

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. They run synchronously and return void, so there is nothing to await.

window.Puntego.point('#pricing-growth', 'Growth plan');
window.Puntego.highlight('#pricing-growth', 'Growth plan');
window.Puntego.scrollTo('#checkout-summary', 'Checkout summary');

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.

window.Puntego.markers([
  { target: '#plan-free', label: 'Free' },
  { target: '#plan-growth', label: 'Growth' },
]);

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).

window.Puntego.tour({
  title: 'Set up billing',
  steps: [
    {
      narration: 'Start by choosing the right plan.',
      target: '#pricing-growth',
      type: 'point',
    },
    {
      narration: 'Then review the checkout summary.',
      target: '#checkout-summary',
      type: 'scroll',
    },
  ],
});

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 (point, caption, highlight, scrollTo, markers, tour) return void. Only speak is asynchronous, so it is the one to await.

window.Puntego.control.point('#pricing-growth', 'Growth plan');
window.Puntego.control.caption('Compare the plans before upgrading.');

await window.Puntego.control.speak('Compare the plans before upgrading.');

Register stable targets

Register stable IDs instead of relying on brittle selectors. Registered targets survive markup changes and let you constrain exactly which actions the guide may run against an element.

window.Puntego.registerTarget('#pricing-growth', {
  id: 'pricing-card-growth',
  allowedActions: ['point', 'spotlight', 'scroll'],
  description: 'Growth plan pricing card',
  route: '/pricing',
});

Call unregisterTarget('pricing-card-growth') when the element leaves the page so the guide stops resolving it.

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.

await window.Puntego.reportWorkflowResult({
  workflowId: 'billing-upgrade',
  actionId: 'select-growth-plan',
  status: 'completed',
  durationMs: 4200,
});

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.

Advanced runtime helpers

The runtime also exposes getPageContext() and locateTarget() for apps that need to inspect what the guide can currently see before driving it. These are runtime-only helpers: they are not part of the typed window.Puntego surface, so a TypeScript consumer needs a cast to call them.

const control = window.Puntego.control as any;

const page = control.getPageContext();
console.log(page.captureContext.targets[0]?.center_viewport);

const target = control.locateTarget('#pricing-growth');
if (target) {
  console.log(target.gp_id, target.computed_name, target.bbox_viewport);
}

Because these helpers are not typed, their return shapes may evolve. Treat them as advanced inspection tools rather than a stable contract, and prefer the typed methods above for production flows.

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.

Get started

Integrate

Deploy & security

Resources

Guide Tools SDK

Point, highlight, and scroll

Show multiple markers

Run a guided tour

Use the control namespace

Register stable targets

Report workflow outcomes

Advanced runtime helpers

Next steps

SDK reference

Verified Actions

​Point, highlight, and scroll

​Show multiple markers

​Run a guided tour

​Use the control namespace

​Register stable targets

​Report workflow outcomes

​Advanced runtime helpers

​Next steps

SDK reference

Verified Actions

Point, highlight, and scroll

Show multiple markers

Run a guided tour

Use the control namespace

Register stable targets

Report workflow outcomes

Advanced runtime helpers

Next steps