Skip to main content
Puntego ships as a single script tag that boots the worker, loads the runtime, and mounts the guide inside its own shadow root.

​
1. Add the script tag

Paste this near the end of your <head> or immediately before </body>: 
<script
  async
  src="https://puntego.com/boot.js"
  data-app-id="gp_your_app_id"
  data-gp-api="https://worker.puntego.com"
  crossorigin="anonymous"
  nonce="YOUR_CSP_NONCE"
  data-nonce="YOUR_CSP_NONCE"
></script>
Copy the canonical snippet from Dashboard -> Install so the app id stays aligned with your tenant. Using a framework? The framework guides cover Next.js (App Router) with a CSP nonce, the @puntego/react provider and hooks, single-page-app route changes, and a no-code Google Tag Manager template.

​
2. Configuration attributes

Everything below is set on the install <script> tag — no code, no redeploy of the widget. Boolean attributes accept true/false (also 1/0, yes/no, on/off); a bare attribute with no value means true.

​
Required

AttributeDescription
data-app-idYour Puntego app id (gp_…). Copy from Dashboard → Install.
data-gp-apiYour worker URL, e.g. https://worker.puntego.com.

​
CSP

AttributeDescription
nonce / data-nonceYour page CSP nonce, passed to both so the runtime + style injection are allowed. See §5.

​
Launcher appearance

AttributeValuesDescription
data-launcher-modecursor | floating | hidden | inline | manualHow the guide presents. cursor is the talking cursor; floating/inline/hidden/manual give you a button or fully programmatic control.
data-launcher-positionbottom-right | bottom-left | top-right | top-leftCorner for the launcher/panel.
data-launcher-labeltextVisible launcher button text.
data-launcher-aria-labeltextAccessible name for the launcher button.
data-launcher-iconchat | questionLauncher glyph.

​
Behavior

AttributeTypeDescription
data-auto-askbooleanAsk an opening question automatically after boot.
data-auto-openbooleanOpen the panel on load.
data-proactive-nudgesbooleanAllow the greeter and proactive nudges.
data-auto-wakeboolean | scroll | idleWake the guide on a chosen signal.
data-auto-wake-delaymillisecondsDelay before auto-wake fires.
data-voice-hotkeybooleanEnable push-to-talk via the V key.

​
Per-route targeting (data-routes)

Scope the widget 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. 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.
<!-- Only on docs and pricing -->
<script ... data-routes="/docs/**, /pricing"></script>

<!-- Everywhere except checkout and account -->
<script ... data-routes="!/checkout/*, !/account/**"></script>

<!-- The whole app, but never the admin subtree -->
<script ... data-routes="/app/**, !/app/admin/**"></script>
On a non-matching route the runtime chunk is never even downloaded, so there is no performance cost on pages where the guide should not appear. For single-page apps, the runtime re-checks the DOM on client-side route changes (see the framework guides); data-routes is evaluated at initial load.

​
3. Create the app and tenant

  1. Sign in to the Puntego dashboard.
  2. Create or select your organization.
  3. Open Dashboard -> Install to copy the full script tag.

​
4. Domain allowlist

  • Add every production hostname in Dashboard → Settings → Domains.
  • Copy the DNS TXT record from the dashboard.
  • Publish the TXT record and run verification before launch.

​
5. CSP nonce support

If your site uses strict CSP, pass the same nonce to the boot script with both nonce and data-nonce. If you do not use CSP nonces, omit those two attributes but keep crossorigin.
  • boot.js propagates the nonce to the runtime loader.
  • runtime.js propagates the nonce to the voice chunk and injected styles.
  • Configure your consent mode in Dashboard → Settings → Privacy.
  • Voice remains optional and can be disabled per tenant.
  • Puntego redacts PII before model calls and honors opt-out or disclosure-only modes.
  • The OpenAI Responses API powers the live chat path, and Cloudflare AI Gateway logs carry hashed metadata only when the gateway is enabled.
  • Sentry events, Langfuse traces, and Promptfoo/eval traces stay redacted; sensitive verified actions still require server-side Turnstile Siteverify.

​
7. What to expect after boot

  • Desktop visitors get the cursor guide.
  • Touch-primary or narrow screens get the bubble fallback.
  • If GP_KILLSWITCH=true is active in the worker, boot returns 503 and the embed silently no-ops.

​
Troubleshooting

  • If the guide never appears, verify the domain allowlist first.
  • If the browser console shows CSP errors, confirm the nonce values match the page nonce.
  • If the worker boot call returns 401, verify the app id and tenant mapping.
  • If the page is iframe-heavy or canvas-heavy, expect degraded guidance until those surfaces are redesigned for DOM-native controls.