The
@puntego/* packages publish to npm at launch. The @puntego/embed,
@puntego/react, and @puntego/cli packages (version 0.1.0, MIT-licensed;
the widget runtime stays on the Puntego CDN and remains proprietary) are
not yet published, so until launch use the script tag or the
Google Tag Manager path below, which load the same guide.
Dashboard → Install shows the same setup for your workspace, with copy
buttons and a Send to developer email.Next.js (App Router)
Install the React wrapper and its peers:<PuntegoProvider> is an
explicit client-module boundary and loads the guide in a client effect, it is
safe to render from a server layout. appId is required. apiUrl is optional
and defaults to the public Puntego worker; pass it explicitly when using a
custom worker origin or when you want the integration origin visible in code.
- Standard
- With CSP nonce
Authenticated customer identity
Signed-in products can bind the first Puntego boot to their own customer and account records. Mint a fresh, one-time token from a server route with an API key scoped toidentity:write, then hand only identity_token to the browser.
The server route authenticates the current user before minting. The server
subpath keeps the protocol, validation, no-store response, and fail-closed error
handling in one place. The environment variable below is a placeholder for your
server-held Puntego key, never a value that belongs in client code:
createPuntegoIdentityRoute is built on standard Request, Response, and
fetch, so the same handler works in Remix and other Fetch API server runtimes.
It sends exactly one authenticated POST to the Worker’s /api/identity/token
endpoint, never retries a mint, forwards only identity_token and expires_at,
and returns generic errors without exposing the API key, customer record, or
upstream body.
Boot from a small client component. It makes one mint request and does not retry
the token if the result is ambiguous, because a lost response may still have
consumed its one-time nonce:
customerIdentityToken is
page-lifetime immutable: the SDK uses it only on the initial /boot, clears its
in-memory handoff, never replays it during JWT refresh, and fails closed on an
invalid, expired, or ambiguous identity boot. Switching customers requires a
full document reload and a newly minted token.
Authenticated account identity
A customer token identifies the signed-in person. Account entitlement lookup also needs the workspace that person is currently authorized to access. An account claim identifies that workspace; it does not prove the connector is configured, that a lookup succeeded, or that SSO is included or enabled. For account-aware help, replace the customer-only handler above with the SDK’s server helper in the same host route. The two auth helpers below belong to your application: authenticate the session and read current membership from your authoritative server-side store. The session’s active workspace is only a candidate until that membership check succeeds. Neither helper may trust a customer/account ID from the request body, query string, page content or chat. Keep your host route’s normal session and request protections.customerId is the authenticated customer’s stable external identifier.
accountExternalId comes from your server’s mapping for the authorized host
workspace and must match the account understood by your entitlement service.
It is not the ID of a CRM record currently open on the page. Do not put plan or
SSO guesses into identity traits as a substitute for the permitted account read.
Missing, inactive or unverifiable membership produces a customer-only token:
account reads remain unavailable, while permitted general site help can
continue. Explain that account access could not be verified; do not ask an
already authenticated person to sign in again merely because membership is
missing. A session-authentication failure is different: the helper mints no
token, and the client must not silently fall back to anonymous identity.
Use the same in-memory token handoff and account-switch lifecycle described
above. Retire the previous account runtime when account access changes; never
retain its token or conversation while rechecking membership. The helper
returns identity_token and expires_at with private, no-store, and never
retries an ambiguous mint. Passing this identity check still requires a
separate authorized account read
to establish the current plan/SSO result. Entitlement does not grant permission
to configure SSO.
Declare targets
Declared targets are the highest-priority grounding tier — the guide resolves them before falling back to DOM heuristics, which raises action success. Declare the elements that matter on each page; the hook registers on mount and unregisters on unmount.usePuntegoTarget(ref, options) instead when you already own an object ref.
Use usePuntegoEvent(name, handler) for typed, lifecycle-managed analytics and
observability listeners.
Account facts
Tell the guide about the signed-in account (plan, seats, usage, features, renewal date, role) through the provider’scontext prop, or with
usePuntegoContext where your app loads the account. Facts from the page
ground answers and never authorize anything; when accountId changes, the
guide starts a new conversation.
signPuntegoAccountFacts from @puntego/react/server (secret from Settings →
Account facts, kept in PUNTEGO_ACCOUNT_FACTS_SECRET) and pass the token as
signedAccountFacts. See Account facts.
React
The same@puntego/react package works in any React 18+ app (Vite, CRA,
Remix). Wrap your app once in <PuntegoProvider> (with required appId and an
optional custom apiUrl),
then use usePuntegoTarget and usePuntegoAction to declare targets and
actions per component. Use usePuntego() for imperative calls such as point
or sendMessage. Use usePuntegoStatus() to render loading, ready, or
recoverable error connection state without polling window.Puntego. See the
SDK reference for the full surface.
This Vite-style component combines the provider, concise callback-ref target,
and a typed outcome listener without a second boot path:
headless and build the answer card and ask bar from @puntego/react/ui; let the
guide read your app’s data with usePuntegoTool, and pipe its versioned events
into your analytics with usePuntegoEvents. See
React components.
The prepared source includes complete, production-building starters at
examples/nextjs-app-router and examples/react-vite (set
VITE_PUNTEGO_HEADLESS=true there for a card built from your own components
with a read tool). Both keep one provider
above the router, declare a real target, expose accessible connection status,
and render a safe setup message when the public app-id environment variable is
missing. They do not invent authenticated users or place server credentials in
browser-prefixed environment variables.
Vue
Use the framework-neutral loader from a root composable. Mount once, abort the readiness wait on unmount, and register controls from component lifecycle:examples/vue-loader composable also registers and unregisters
targets when the referenced DOM node changes. Its TypeScript render functions
are checked directly with TypeScript 7.
Svelte
Call the loader fromonMount; never combine it with a script tag in the same
page. A Svelte action is a natural owner for target cleanup:
examples/svelte-loader includes the complete typed store and target action and
passes the official Svelte compiler and svelte-check-native with TypeScript 7
without warnings. Its regression checks cover template types, incomplete
blocks, and accessibility diagnostics.
Angular
Put the loader behind one root-provided service, guard it withisPlatformBrowser, and run the boot outside change detection. Components can
await that service after render, register their ElementRef, and unregister in
ngOnDestroy. examples/angular-loader uses TypeScript 7 and Angular’s JIT
compiler. Its Chromium integration check exercises the compiled template,
element registration, SDK button, and cleanup on destroy. The service rejects
configuration changes after the page singleton has booted.
Single-page apps and client-side routing
The runtime uses the Navigation API when available and otherwise observeshistory.pushState, history.replaceState, popstate, and hashchange, so
client-side route changes are detected automatically — there is nothing to wire
up for React Router, Vue Router, or SvelteKit navigation. The guide re-reads the
page after a committed pathname or hash change, and an in-progress tour resumes
across navigations.
For accuracy: query-only history updates do not trigger a page re-read. A
replaceState call that changes the pathname does; one that changes only search
parameters does not. If a query-only transition mounts or unmounts declared
targets, call the registration hooks — use the framework hooks, or call
window.Puntego.registerTarget / unregisterTarget from your own lifecycle —
so the registry always matches what is on screen.
Google Tag Manager (no code)
If you cannot edit your site’s HTML but you have a GTM container, manually import the Puntego template.1
Import the template
In GTM, open Templates → Tag Templates → New, then import the template.
Download the Puntego Embed template,
then select that downloaded file in the template importer.
2
Add and configure the tag
Add a Puntego Embed tag and fill in your App ID and Worker API
origin (copy both from Dashboard → Install).
3
Trigger, preview, publish
Trigger on All Pages (Initialization), then Preview and Publish.
boot.js once and publishes a window.__PUNTEGO_CONFIG__
object that the boot script reads when no data-app-id attribute is present.
The GTM and hand-pasted paths share the same runtime.
Programmatic loader
For custom integrations, the loader injects the boot script imperatively and is SSR-safe (a no-op on the server):Validate an integration locally
The read-only doctor scans application source and root package metadata without network access or file writes. It reports filenames but never prints matched source, API keys, or identity tokens:--strict makes warnings fail CI. @puntego/cli
publishes to npm at launch with the other packages; until then, perform the
same checks manually.
Test with Playwright
Import the official helpers from the optional@puntego/embed/playwright subpath. Playwright is a type-only optional peer for
this subpath; none of the testing code enters the production widget bundle.
resetLocalPuntego clears only Puntego-owned browser
storage, makes no network request, always reloads, and is hard-blocked outside
localhost/loopback with no override. Use a fresh Playwright BrowserContext for
QA or production-origin isolation; there is no simulated remote data reset.
The receipt waiter captures the next Experience engagement response on its
Page, so serialize engagement triggers or use separate Pages/BrowserContexts
for intentionally concurrent cases.
Next steps
Install
The raw script tag and every launch attribute.
Configuration
Tune launcher mode, routes, voice, and wake behavior.
SDK reference
Imperative methods, hooks, and runtime events.
Guide Tools SDK
Build product-owned helpers and declared targets.
CSP
The full Content Security Policy for strict sites.
Domains
Allow the origins where the guide may mount.