AI IDE integration
A checklist for an AI coding assistant integrating Nastar into your existing website, plus copyable prompts. Nothing here asks the assistant to do anything the management API doesn't actually support.
sites:read, sites:write, sites:publish). Revoke it when the task is done. The checklist
1. Inspect before changing anything
Have the assistant read the target site's framework, rendering mode, existing tag manager, analytics/advertising scripts, CSP, and any current cookie/consent handling — and report it back — before writing code. It must not silently replace existing tracking or legal copy.
Inspect this repository's frontend framework, rendering mode (SSR/CSR/SSG), tag manager, analytics/advertising scripts, CSP, and any existing cookie/consent implementation. List what you find. Do not modify or remove anything yet, and do not replace any existing legal text. If the only analytics found is Google Analytics (GA4) — no other custom analytics script — it can be fully Nastar-managed instead of integrated by hand: enable it in the dashboard's Integrations tab with a Measurement ID and Basic/Advanced Consent Mode, and skip adding a separate gtag.js snippet entirely. The SDK loads, configures, and fires page views for GA4 itself. For SPA frameworks, call client.trackPageView(pagePath) on each client-side route change — see SDK reference.
2. Get a public site key
Either reuse an existing site's public site key (Overview tab, or GET /v1/agent/sites/:siteId with a sites:read token), or have the assistant create one via POST /v1/organizations/:orgId/sites — with your explicit go-ahead, since creating a site is a real, persisted action. The public site key is an identifier the SDK reads config with; it is not an authorization credential and is safe in client-side HTML.
3. Install and initialize the SDK
Use the snippet from the site's Overview tab for a non-bundled site, or the ESM build at https://cdn.nastar.dev/sdk/v1/nastar.esm.js for a bundled app — see SDK reference for both. Initialize it before any optional script can run. For server-rendered pages, keep optional server-side tracking disabled unless you can independently verify consent server-side — the SDK itself only runs client-side.
npm install @nastar/consent-sdk does not work — the package isn't on the npm registry yet, so an assistant that reaches for it will hit a 404 and may invent a workaround. Tell it to install from the CDN, as the prompt below does. The /sdk/v1/ path is a rolling one: it always serves the current SDK, so a fix reaches every site that embeds it without anyone redeploying. If the site you're integrating requires exact, reviewed dependency versions, an immutable per-version path exists too — https://cdn.nastar.dev/sdk/0.4.0/nastar.min.js — but it never receives fixes on its own; upgrading means editing the URL and watching the changelog. Pick one deliberately rather than by accident.
Install the Nastar consent SDK from its CDN — the <script> build at https://cdn.nastar.dev/sdk/v1/nastar.min.js for a non-bundled site, or the ESM build at https://cdn.nastar.dev/sdk/v1/nastar.esm.js for a bundled one. Do not run npm install @nastar/consent-sdk: that package is not on the registry yet and the install will fail. Initialize the SDK with the public site key I've given you: <PUBLIC_SITE_KEY>. Never ask me for an OTP, a login session, or a full-privilege API token — a public site key is the only credential this step needs.4. Gate every optional integration
Map each script found in step 1 to a real consent category from the published config, and move it behind client.loadWhenConsented(categoryKey, loader). Add a persistent Privacy settings control that calls client.openPreferences(). Handle client.onConsentChange() for withdrawal — note the SDK cannot retroactively undo a script's own side effects (e.g. cookies it already set); see SDK reference for exactly what it can and can't clean up.
Move every optional analytics/marketing script you found in the inspection step behind client.loadWhenConsented('<category>', ...), mapping each one to the correct consent category. Do not let any of them execute before that call fires. Add a persistently visible "Privacy settings" control that calls client.openPreferences(). Do not touch scripts that are legally required or already gated by an existing, working consent mechanism without asking me first.5. Keep credentials out of the client
The public site key may appear in HTML, JS bundles, and CSP examples. A setup token (nst_...) must never appear in any of those places — it belongs in CI secrets or the assistant's own environment only, never committed or bundled.
6. Test it for real
Run browser-based checks, not just unit tests: fresh visitor, reject all, accept all, selective accept, withdraw, refresh, config-version update, and API/CDN outage. Inspect actual network requests, cookies, and localStorage before any choice and after each one.
Write Playwright tests against this integration covering: fresh visitor (banner shown, nothing optional loaded), reject all, accept all, selective accept, withdraw, reload persistence, config-version change, and API/CDN outage (fail closed, no banner, nothing optional loads). Then report which files you changed, which third-party services you found, which are now gated, and which still need my manual review.7. Report honestly
The assistant should end with a concrete report: files changed, third-party services found, which are gated and which are not, and what still needs manual/legal review. It must never claim universal cookie blocking, certification, or legal compliance — Nastar doesn't make that claim about itself either.
Worked examples
Two framework guides exist today:
- Plain HTML — a tested, working integration pattern for a static site with no build step.
- Nuxt — the SDK in a Nuxt app, including the SPA page-view hook. This site runs that exact integration.
Astro, Next.js, and WordPress guides do not exist — they are not written and not tested. The SDK has no framework-specific API, so the plain HTML pattern is the honest starting point for any of them, but nothing here has verified it in those frameworks. Don't present an untested adaptation as a supported integration.
Machine-readable index
/llms.txt lists these docs, the OpenAPI document, and the SDK reference for tools that consume it directly. It's a navigational aid, not a guarantee of support — always verify against the real /v1/openapi.json rather than trusting a cached summary.
/llms.txt · nastar-integration.md (downloadable agent instructions)