@puntego/react for React and Next.js, @puntego/embed for any other framework) or as one hosted boot script. Both load the same runtime from the Puntego CDN and mount the guide inside its own shadow root. This page is the complete install reference: every script attribute, route rule, and verification step. Want the fastest path to a working guide? Start with the Quickstart, or hand the job to your coding agent with Install with Claude Code.
The
@puntego/* packages publish to npm at launch. Until then, use the
Script tag tab in step 3. It loads the same guide, and moving to the
package later changes nothing in your dashboard.Set up your install
1
Create your app and copy the app ID
Sign in to the Puntego dashboard and create or select your workspace. Open Dashboard → Install and copy your app ID — the
gp_ token that links your install to your workspace. You will use it in step 3.2
Add and verify your domain
Add every production hostname in Dashboard → Install → Domains, publish the DNS TXT record the dashboard generates, and run verification before launch. Boot calls from an unverified origin are rejected, so the guide will not appear until verification passes. See domains and allowlisting for the full process.
3
Add Puntego to your app
Mount Puntego once, in your root layout or app shell, and replace Wrap your app once in The Next.js guide has the full root layout, including the strict-CSP nonce.Not the person who edits the site? Use Send to developer on the Install page. It opens your own email app with the code and a link to the setup guide; Puntego sends nothing on your behalf.
gp_your_app_id with the app ID you copied in step 1. Use one boot strategy per page: the package or the script tag, never both.- React and Next.js
- Other frameworks
- Script tag
- Script tag, strict CSP
<PuntegoProvider>. It loads the guide in a client effect, so it is safe to render from a server layout. apiUrl is optional and defaults to the public Puntego worker.4
Set behavior attributes (optional)
The defaults boot a floating launcher in the bottom-right corner — carrying the Puntego pointer mark, so visitors can see it is a guide that points at things before they open it — with no extra setup. To change the launcher, automate proactive behavior, or scope the guide to specific routes, add the data attributes documented in script attributes below — no code and no redeploy of your app. With the npm packages, pass the loader options listed in the SDK reference instead.
5
Verify the guide appears
Load a page on a verified domain. The guide mounts inside its own shadow root, isolated from your styles. Desktop visitors see the launcher you configured; if nothing appears, check troubleshooting.
The cursor launcher (
data-launcher-mode="cursor") falls back to a bubble experience on touch-primary or narrow (under 768px) screens. The default floating launcher keeps its button at every screen size.Framework tabs and the npm packages
The Install page shows the same setup for React, Next.js, Vue and Other (Svelte, Angular, Google Tag Manager), generated from your workspace so the app ID and worker URL always match. The npm packages@puntego/react and @puntego/embed are MIT-licensed. The widget runtime itself is not in those packages: it is served from the Puntego CDN and stays proprietary, so the package and the script tag always run the same guide.
Diagnose an install that does not boot
While the guide has not booted, Dashboard → Install shows Why the guide is not showing yet: three checks in order, so the first one that is not green is the thing to fix.- Domain verified. Puntego refuses to boot on a domain you have not verified.
- Snippet reaches Puntego. A page with the snippet has contacted Puntego.
- Boot accepted. The guide booted on your site.
Only the origin (
https://host), the reason and when it happened are kept: no path, visitor or page content. The Install page lists the 20 most recent origins from the last 30 days, and a busy page is not recorded again on every view: a repeat from the same origin is written at most about once every 30 seconds. Once a domain change would make an origin acceptable, the entry moves to Fixed since; reload that page to confirm. Each origin is listed once, with the reason that applies to your domain list today.
After the guide has booted, the checklist goes away, but any other origin Puntego still refuses (a second site, a staging host) stays listed under Pages Puntego still refuses.
Script attributes
Everything below is set on the install<script> tag — no code, no redeploy. Boolean attributes accept true/false (also 1/0, yes/no, on/off); a bare attribute with no value means true.
Required
Strict CSP
Launcher appearance
Behavior
data-auto-ask, data-auto-open, data-proactive-nudges, data-voice-hotkey, and data-summon-hotkey also exist as workspace defaults under Dashboard → Guides → Actions → Proactive Behavior, so you can turn one on or retire it across every page without editing the snippet. The attribute above always wins on the page that sets it. data-struggle-help and data-struggle-metrics are workspace defaults under Dashboard → Settings → Guide behavior, together with the pages where they stay off, and data-first-run-moment is the live-site switch under Dashboard → Install → First-visit moment, together with the pages it may show on.Route targeting
Scope the guide to (or away from) specific routes without code.data-routes is a comma-separated list of path globs matched against the page pathname (query and hash are ignored, matching is case-insensitive):
*matches within a single path segment;**(or a trailing/**) spans segments.- A leading
!makes a rule a deny, and a deny always wins. - If any allow rule is present, the path must match one of them to mount.
- A deny-only list mounts everywhere except the denied paths.
Local development
Every workspace has two snippets on Dashboard → Install. The test snippet carries agp_test_… app ID and boots on any page — http://localhost:3000, a staging host, a teammate’s machine — with no domain to verify. Paste it, load the page, and ask a question.
A test-mode widget:
- shows a visible Test mode label on the launcher, in the open ask bar and on every answer;
- never writes conversations, analytics, usage, memory or anything to your integrations;
- shows the way instead of clicking or typing on any domain you have not verified, localhost included. On a verified domain it clicks, types and fills forms for real as in production (after the visitor confirms, or at once for the standard fields of a form fill whose values the visitor gave); each of those actions leaves a test receipt kept apart from your live data (deleted within a day) and never counts against your plan. Connectors, human handoff and returning-visitor memory stay off;
- keeps no earlier messages, so each answer reads only the question you just asked. From the second question on, the answer says so: “Test mode doesn’t keep earlier messages…”. Put the details you want it to use in the question itself;
- keeps a tour going when you move to another page in the middle of it, as in production. What it needs to pick the tour up again is kept apart from your live data and deleted within a day;
- answers up to 20 questions an hour, 60 a day and 300 a month per workspace, with further per-page, per-visitor and per-network limits. Hourly limits reset on the hour, daily ones at midnight UTC and the monthly one on the 1st (UTC);
- stops working everywhere as soon as you choose Replace test key, for example if the key ended up somewhere public. The new key starts right away; answers already used this hour, day or month still count.
Why the production snippet returns 403 on http://localhost:3000
Boot authorizes on the browser’s Origin header, and in production two rules apply with no exceptions:
- HTTPS only. A verified domain never widens the allowlist to an insecure origin, so an
http://origin is rejected even if the hostname would otherwise match. - No loopback special case.
localhostand other loopback hosts are accepted only by non-production stages, never by the production worker.
http://localhost:3000 sends Origin: http://localhost:3000, matches nothing, and /boot answers 403 with boot/origin_not_allowed. That is deliberate — it is what stops a forged origin from minting a visitor session against your workspace. Adding localhost in Dashboard → Install → Domains does not help either: verification needs a site or DNS you control. Use the test snippet above for localhost, or the recipe below for production parity.
Boot a local dev server against production
The subdomain match runs on the origin string, not on where the hostname resolves. So an HTTPS subdomain of your verified apex is authorized even when it points at127.0.0.1.
1
Confirm the apex is verified
Verify
example.com in Dashboard → Install → Domains. A verified apex authorizes the apex, its www host, and any HTTPS subdomain — so local.example.com needs no entry of its own. If the apex is not verified, nothing under it is authorized.2
Point a subdomain at your machine
Add a hosts entry on the machine you develop on:On Windows the file is
/etc/hosts
C:\Windows\System32\drivers\etc\hosts. If you would rather not edit hosts on every machine, publish a real DNS A record for local.example.com pointing at 127.0.0.1 instead — the origin check does not care which one you use.3
Serve the dev app over local HTTPS
Issue a locally trusted certificate for the hostname and start your dev server with it — for example with mkcert:Then pass the generated certificate and key to your framework’s dev server. Use a certificate your browser actually trusts; clicking through a certificate warning leaves the page in a degraded security state, and the visitor cookie the worker sets (
SameSite=None; Secure) may be dropped.4
Leave the snippet unchanged
Keep the production
src and data-gp-api from step 3. Nothing about the install differs in local development.5
Load the page
Open
https://local.example.com:3000 — any port works, the origin check ignores it. The browser sends Origin: https://local.example.com, the worker matches it against the verified apex, and the guide boots against production.Because you are booting against production, everything the guide touches is production: the live workspace configuration and knowledge, plan limits, analytics, and usage. Sessions from your dev machine are recorded like any other visitor session. Keep that in mind before running experiments this way.
Constraints and trade-offs
- Every developer needs the hosts entry and a locally trusted certificate on their own machine.
- It only works for teams that already own and have verified a domain — there is no path here for a brand-new workspace with nothing verified yet.
- Booting against production is not a sandbox. There is no separate dev workspace, dev data, or dev quota.
What the guide can do on your site
Once installed, the guide can act on your pages when a visitor asks it to: open sections and tabs, fill fields and press buttons, with the risk it detects on each control, a 3-second countdown before anything that can’t be undone, and never a password or a card number. Nothing needs declaring first. Rule out a control, mark it Always confirm, add a No-AI zone, or keep the guide to Only what I declared in Dashboard → Guides → Actions → Guide autonomy; an element withdata-puntego-ignore is never read or acted on at all. See What the guide does on your pages.
Consent and privacy
Consent mode, voice, and other workspace behavior are set in the dashboard, not on the script tag. Configure them in Configuration, and see how Puntego handles consent and PII redaction in privacy and PII.Next steps
Quickstart
The shortest path from app ID to a live guide.
Framework guides
Next.js, the React provider and hooks, SPA route changes, and Google Tag Manager.
Strict CSP
Run Puntego under a strict Content Security Policy with nonce propagation.
Configuration
Tune appearance, consent, voice, and rollout from workspace settings.