@contentsquare/wizard

AI-assisted Contentsquare installation and configuration. A standalone CLI that drops a skill into your project for your AI coding agent (GitHub Copilot, Cursor, Claude Code) to install Contentsquare — the web tracking tag or a mobile SDK (Android, iOS, Flutter, React Native) — plus a verify command that opens your web app in a real browser and confirms the tag, CSP, and pageview coverage in one session.

Quickstart

Inside your web project, run:

npx @contentsquare/wizard start

That single command:

1. Asks which stack you're integrating — Web, Android, iOS, Flutter, or React Native (or pass --stack <stack>).
2. For Web, resolves your tag ID — pass --tag-id <hashed> (hex, e.g. 81c677ba742d7), or answer the prompt.
3. Creates .cs-wizard/ with state.json and the selected skill under skills/.
4. Adds .cs-wizard/ to your .gitignore.
5. Copies a prompt to your clipboard to paste into your agent.

Then open your project in your editor and paste the prompt start copied to your clipboard — it points your agent at the skill for the stack you chose (e.g. Read and follow .cs-wizard/skills/web-tag-skill/SKILL.md).

For Web, the agent detects your framework, installs @contentsquare/tag-sdk, wires up the init code, and verifies the result by running npx @contentsquare/wizard verify. For a mobile SDK, the agent follows that stack's SKILL.md to install the SDK, add screen tracking, and verify on-device.

install is an alias of start — both run the same flow, so use whichever you prefer.

Prerequisites

• Node.js >= 20 (npm and npx ship with Node).
• An AI coding agent (GitHub Copilot in VS Code, Cursor, or Claude Code).
• For verify: a desktop with a graphical display. It uses your installed Chrome/Edge, or downloads Chromium on demand with --install-browser.

Why npx is enough

You never need to install this package globally — npx @contentsquare/wizard … resolves the package on demand (cached after the first run). No PATH setup, no global install, no version drift between projects.

Tip: if you'd rather type wizard-cs verify than npx @contentsquare/wizard verify, install once globally with npm i -g @contentsquare/wizard. The bin is wizard-cs (scoped to avoid clashing with other tools named wizard).

Commands

| Command | Description | | ---------------------------------- | ------------------------------------------------------------------------------- | | npx @contentsquare/wizard start | Drop a Contentsquare skill (web or mobile) into your project (alias: install) | | npx @contentsquare/wizard verify | Open your app in a real browser and verify the tag, CSP, and pageview coverage | | npx @contentsquare/wizard status | Show the configured tag ID and the latest verification result |

Options

start / install:

• --dir <path> — Target directory (defaults to cwd)
• --stack <stack> — Skill to install: web, android, ios, flutter, react-native (prompts if omitted)
• --tag-id <hashed> — Hashed Contentsquare tag ID (hex, e.g. 81c677ba742d7) — Web only

verify:

• --dir <path> — Project directory (defaults to cwd)
• --url <url> — App URL to open (skips the prompt)
• --tag-id <hashed> — Tag ID to check against (defaults to wizard state)
• --install-browser — Auto-download the Chromium engine if no browser is found
• --preflight — Check browser availability and environment, then exit (diagnostics)
• --json — Emit the report as JSON to stdout (for agents)

How verification works

verify launches a real browser window with a Contentsquare banner overlaid on your app. You browse — let the first page load, click through a few in-app routes, log in if needed — then click Done (or close the window). It then prints a report covering:

• whether the tag script loaded (t.contentsquare.net/uxa/<tagId>.js),
• whether the first pageview fired,
• pageview coverage across the routes you navigated, and
• any CSP violations referencing Contentsquare domains.

The same report is written to .cs-wizard/last-report.json, and status summarizes the latest run.

Skills

start installs the skill for your chosen stack into .cs-wizard/skills/:

• web-tag-skill (bundled) — Detect the web framework, install @contentsquare/tag-sdk, add the browser-only init code (Next.js, React, Vue, Nuxt, Angular, SvelteKit, static HTML / server-rendered), run verify, and fix CSP only when verify reports a violation.
• contentsquare-android-sdk, contentsquare-ios-sdk, contentsquare-flutter-sdk, contentsquare-reactnative-sdk (downloaded) — Integrate or upgrade the mobile Contentsquare SDK: install, screen tracking, Session Replay, masking, privacy opt-in/out, and migration. Mobile skills verify on-device (logcat / Xcode console) — the browser-based verify command is Web only.

The web skill ships inside this package (it is versioned together with verify). The mobile skills are maintained in the public ContentSquare/agents repository and downloaded on demand, so choosing a mobile stack requires network access to GitHub. If the download fails, start reports the error — retry once you have access, or copy the skill manually from the skills repo.

Configuration that requires the Contentsquare app UI (e.g. Tracking URL Changes mode for SPA route changes) is not performed by this wizard. When verify returns pass-with-recommendation, it surfaces that as a recommendation for the developer to complete in the app.

Anonymous usage data

The wizard reports anonymous usage data to Contentsquare so we can understand which commands are run and where they fail. Each event is a fixed, non-identifying record:

• a random install id (a UUID, not tied to you or your machine),
• the command (start, install, verify, status) and a coarse status message from a fixed list,
• the CLI version and OS family (e.g. darwin).

It never contains your code, URLs, file paths, or any personal data. The full, human-readable record of everything reported is kept locally at .cs-wizard/telemetry.jsonl.

To opt out, set either environment variable before running the wizard:

export DO_NOT_TRACK=1          # cross-tool standard
export CS_WIZARD_TELEMETRY=0   # wizard-specific

With either set, nothing is recorded or sent.