Skip to main content
Puntego installs from npm (@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 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.
Wrap your app once in <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.
The Next.js guide has the full root layout, including the strict-CSP nonce.
Copy the canonical setup from Dashboard → Install so the app ID and worker URL always match your workspace. Once a domain is verified, that page also has tabs for React, Next.js, Vue and other frameworks, each with its own copy button and guide link.
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.
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.
  1. Domain verified. Puntego refuses to boot on a domain you have not verified.
  2. Snippet reaches Puntego. A page with the snippet has contacted Puntego.
  3. Boot accepted. The guide booted on your site.
When Puntego refuses a page it logs the origin and the reason, and the Install page shows them in plain words: 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.
On a non-matching route the runtime chunk is never downloaded, so there is no cost on pages where the guide should not appear. Rules are evaluated at initial load; single-page apps re-check on client-side route changes — see the framework guides.

Local development

Every workspace has two snippets on Dashboard → Install. The test snippet carries a gp_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.
The production snippet is what you ship. It only boots on domains you verified, and the rest of this section explains how to run it against a local dev server when you need production data and limits exactly as visitors see them.

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. localhost and other loopback hosts are accepted only by non-production stages, never by the production worker.
A page served from 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 at 127.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:
/etc/hosts
On Windows the file is 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.
Use this recipe only when you need production itself on your machine; for everything else the test snippet is simpler. Origin authorization works exactly as described above — the recipe satisfies the existing rules rather than relaxing them.

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 with data-puntego-ignore is never read or acted on at all. See What the guide does on your pages. 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.

Scale trial

Your 14-day Scale trial starts when you create your account, with no card. It includes 1,000 AI replies, 250 agent actions, 30 voice minutes and 250 knowledge pages for the whole trial. Each workspace and verified website can use one trial. Verification does not restart or extend it. When it ends, the workspace moves to Free unless you choose a paid plan; nothing is charged automatically. The trial does not enable the production snippet before domain verification. Use the existing test snippet to evaluate your guide before going live; it has its own test-mode limits and does not consume the trial’s production usage allowance. Existing workspaces that never started a trial keep it: it starts on the owner’s next successful sign-in, workspace activation, or domain verification, whichever happens first. The existing Billing action can also start an unused trial. Trials already started keep their original dates.