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

# SDK upgrades and migrations

> Upgrade the Puntego script, loader, React package, and public SDK without mixing incompatible runtime generations.

Puntego has one browser runtime whether you install it with a script tag,
`@puntego/embed`, or `@puntego/react`. Keep the package and CDN boot script on
the same supported generation. Do not load two scripts or two Providers to
bridge an upgrade.

## Compatibility signal

The public runtime exposes `window.Puntego.protocolVersion`. The current loader
expects protocol `1` and checks it once per page. A missing or different value
produces a console warning with this guide; it does not send telemetry, block
the visitor, or reveal application data.

```ts theme={null}
import {
  PUNTEGO_SDK_PROTOCOL_VERSION,
  whenPuntegoReady,
} from '@puntego/embed/loader';

const sdk = await whenPuntegoReady();
if (sdk && sdk.protocolVersion !== PUNTEGO_SDK_PROTOCOL_VERSION) {
  throw new Error('The Puntego package and CDN runtime are out of sync.');
}
```

Use that hard failure only in local tests or staging. Production keeps the
warning non-blocking so an older cached asset cannot take down the host product.

## Script tag to programmatic loader

1. Remove the hand-authored `<script>` from the host template.
2. Install `@puntego/embed` after the package is publicly available.
3. Call `loadPuntego` once from the application's client lifecycle.
4. Preserve the same app ID, worker URL, CSP nonce, theme, and optional
   server-minted customer identity token.
5. Run `puntego doctor --strict` and an external clean-project build.

```ts theme={null}
import { loadPuntego } from '@puntego/embed/loader';

loadPuntego({
  appId: 'gp_your_app_id',
  apiUrl: 'https://worker.puntego.com',
  theme: 'auto',
});
```

The loader deduplicates the canonical Puntego boot script. If a different app
ID is already mounted, it warns and retains the first page-level runtime.

## Loader to React

Replace the direct loader lifecycle with one `PuntegoProvider` near the client
application root. Do not keep the old `loadPuntego` call.

```tsx theme={null}
'use client';

import { PuntegoProvider } from '@puntego/react';

export function PuntegoBoundary({ children }: { children: React.ReactNode }) {
  return <PuntegoProvider appId="gp_your_app_id">{children}</PuntegoProvider>;
}
```

Move manual target registration to `usePuntegoTarget` or
`usePuntegoTargetRef`. Keep identity minting on the server; never migrate a
programmatic API key into a React prop or browser environment variable.

## Built-in UI to headless

Headless mode is immutable for the lifetime of the page. Set `headless: true`
on the first loader or Provider call, render sanitized snapshots from
`@puntego/embed/headless`, and remove code that opens the built-in panel.
Consent, action confirmation, postconditions, match proofs, and audit receipts
remain enforced by the runtime and Worker.

## Upgrade checklist

* Use one exact version for `@puntego/embed` and `@puntego/react`.
* Rebuild from a clean external project and inspect the packed tarballs.
* Run `puntego doctor --strict`.
* Run the official Playwright helpers against local or staging.
* Verify boot, authenticated identity, targets, one Experience engagement, and
  one governed action receipt.
* Confirm CSP and Trusted Types before production rollout.
* Roll back package and boot-script changes together if protocol diagnostics
  appear.

There are no deprecated public SDK members in protocol `1`. Future
deprecations will retain the old behavior for their documented window and emit
a bounded once-per-page warning with the replacement and removal version.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.