> ## Documentation Index
> Fetch the complete documentation index at: https://docs.puntego.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install Puntego

> The full install reference: boot script attributes, launcher and behavior options, route targeting, and verification.

Puntego ships as one boot script that loads the runtime and mounts the guide inside its own shadow root. This page is the complete install reference — every script attribute, route rule, and verification step.

<Note>
  Want the fastest path to a working guide? Start with the [Quickstart](/quickstart). Come back here when you need the full attribute reference.
</Note>

## Set up your install

<Steps>
  <Step title="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 the boot script to your workspace. You will paste it into the script tag in step 3.
  </Step>

  <Step title="Add and verify your domain">
    Add every production hostname in **Dashboard → Settings → 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](/domains) for the full process.
  </Step>

  <Step title="Paste the boot script">
    Add the script near the end of your `<head>` or immediately before `</body>`, and replace `gp_your_app_id` with the app ID you copied in step 1. Use the Standard snippet unless your site enforces a strict Content Security Policy.

    <Tabs>
      <Tab title="Standard">
        ```html theme={null}
        <script
          async
          src="https://puntego.com/boot.js"
          data-app-id="gp_your_app_id"
          data-gp-api="https://worker.puntego.com"
          crossorigin="anonymous"
        ></script>
        ```
      </Tab>

      <Tab title="Strict CSP">
        Pass your page nonce to both `nonce` and `data-nonce` so the runtime and its injected styles are allowed.

        ```html theme={null}
        <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>
        ```

        See [running under a strict CSP](/csp) for nonce propagation and policy directives.
      </Tab>
    </Tabs>

    <Tip>
      Copy the canonical snippet from **Dashboard → Install** so the app ID and worker URL always match your workspace.
    </Tip>
  </Step>

  <Step title="Set behavior attributes (optional)">
    The defaults boot a floating launcher in the bottom-right corner 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](#script-attributes) below — no code and no redeploy of your app.
  </Step>

  <Step title="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](/troubleshooting).
  </Step>
</Steps>

<Note>
  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.
</Note>

## 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

| Attribute     | Description                                                                                                                |
| ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `data-app-id` | Your Puntego app ID (the `gp_` token). Copy from **Dashboard → Install**.                                                  |
| `data-gp-api` | Your worker URL, `https://worker.puntego.com`. Required — without it the worker is unreachable and the guide never mounts. |

### Strict CSP

| Attribute              | Description                                                                                                                                               |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nonce` / `data-nonce` | Your page CSP nonce, passed to both so the runtime and injected styles are allowed. Only needed under a strict Content Security Policy — see [CSP](/csp). |

### Launcher appearance

| Attribute                  | Values                                                       | Default        | Description                                                                                                                                    |
| -------------------------- | ------------------------------------------------------------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-launcher-mode`       | `cursor` \| `floating` \| `hidden` \| `inline` \| `manual`   | `floating`     | How the guide presents. `cursor` is the talking cursor; `floating`/`inline`/`hidden`/`manual` give you a button or fully programmatic control. |
| `data-launcher-position`   | `bottom-right` \| `bottom-left` \| `top-right` \| `top-left` | `bottom-right` | Corner for the launcher and panel.                                                                                                             |
| `data-launcher-icon`       | `chat` \| `question`                                         | `question`     | Launcher glyph.                                                                                                                                |
| `data-launcher-label`      | text                                                         | —              | Visible launcher button text.                                                                                                                  |
| `data-launcher-aria-label` | text                                                         | —              | Accessible name for the launcher button.                                                                                                       |

### Behavior

| Attribute               | Type                                           | Description                                                                                                       |
| ----------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `data-auto-ask`         | boolean                                        | Ask an opening question automatically after boot.                                                                 |
| `data-auto-open`        | boolean                                        | Open the panel on load.                                                                                           |
| `data-proactive-nudges` | boolean                                        | Allow the greeter and proactive nudges.                                                                           |
| `data-auto-wake`        | `boolean` \| `on-idle-<n>ms` \| `on-idle-<n>s` | Wake the guide after an idle delay, for example `on-idle-8s`. Unrecognized values fall back to the default delay. |
| `data-auto-wake-delay`  | milliseconds                                   | Delay before auto-wake fires.                                                                                     |
| `data-voice-hotkey`     | boolean                                        | Push-to-talk on the **V** key. Enabled by default (opt-out); set to `false` to disable.                           |

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

<CodeGroup>
  ```html Allow only docs and pricing theme={null}
  <script ... data-routes="/docs/**, /pricing"></script>
  ```

  ```html Everywhere except checkout and account theme={null}
  <script ... data-routes="!/checkout/*, !/account/**"></script>
  ```

  ```html Whole app, never the admin subtree theme={null}
  <script ... data-routes="/app/**, !/app/admin/**"></script>
  ```
</CodeGroup>

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](/frameworks).

## Consent and privacy

Consent mode, voice, and other workspace behavior are set in the dashboard, not on the script tag. Configure them in [Configuration](/configuration), and see how Puntego handles consent and PII redaction in [privacy and PII](/privacy-and-pii).

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    The shortest path from app ID to a live guide.
  </Card>

  <Card title="Framework guides" icon="layout-template" href="/frameworks">
    Next.js, the React provider and hooks, SPA route changes, and Google Tag Manager.
  </Card>

  <Card title="Strict CSP" icon="shield-check" href="/csp">
    Run Puntego under a strict Content Security Policy with nonce propagation.
  </Card>

  <Card title="Configuration" icon="sliders-horizontal" href="/configuration">
    Tune appearance, consent, voice, and rollout from workspace settings.
  </Card>
</CardGroup>
