SDK upgrades and migrations

​

Compatibility signal

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.');
}

​

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.

import { loadPuntego } from '@puntego/embed/loader';

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

​

Loader to React

'use client';

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

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

​

Built-in UI to headless

​

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.