# CauseWise for AI coding assistants

CauseWise does not edit the repository and does not run an AI model. The assistant inspects the website, installs the official snippet, and calls `window.causewise.track` where an outcome happens. Management of sites, goals, and funnels goes through the MCP server or the REST API in [causewise-mcp.md](./causewise-mcp.md).

Read [causewise-tracking.md](./causewise-tracking.md) before adding events. Recommended names are in [causewise-events.md](./causewise-events.md). `get_tracking_instructions` returns the same rules, and the official snippet when you pass `siteId`.

## Prompt

```text
Integrate CauseWise into this website using the connected CauseWise MCP server.

Inspect the framework and existing analytics setup.
Register the website if necessary.
Install the official tracking snippet.
Identify meaningful conversion events.
Instrument those events using the existing CauseWise tracking API.
Create appropriate goals and funnels.
Run relevant project checks.
Verify event collection through CauseWise MCP.

Do not duplicate existing tracking.
Do not claim events are arriving without confirmation.
```

## Order of work

1. Inspect the repository: framework, layout, router, and any existing `causewise.js` or `data-site` tag.
2. Identify the production domain from the project config, not from a guess.
3. `list_sites`. Reuse a site whose domain matches. `create_site` only when the domain is new.
4. `get_tracking_snippet` or `get_tracking_instructions` with `siteId`. Install that HTML once.
5. Leave automatic pageviews alone. Add `window.causewise.track` only for outcomes a pageview cannot represent.
6. Use event names the product already sends, or the names in [causewise-events.md](./causewise-events.md). The goal’s `eventName` must match the string passed to `track`.
7. `create_goal` and `create_funnel` through MCP. A page step uses `trackingMethod: "pageview"` and a path. A custom step uses the event name.
8. Run the website’s existing tests and build.
9. Ask for a real page load, then `get_tracking_status` and `list_recent_events`.

A green test run means the code compiled. It does not mean CauseWise stored an event. Say that events arrived only after a CauseWise tool reports them.

## Frameworks

**Next.js.** One snippet in the root layout (`app/layout.tsx` or `pages/_document` / `_app`). App Router navigations use `history.pushState`, which `causewise.js` already records. Do not add a pageview in `useEffect`, `usePathname`, or `next/navigation` listeners.

**React SPA.** One snippet in `index.html`. Browser-history routers are tracked. Hash routers are not; document that limit instead of inventing a second pageview channel unless the product needs those views. Call `track` from the success handler, not from a mount effect.

**HTML.** One snippet in the shared head. Call `track` from the handler that confirms the conversion.

**Other frameworks.** One snippet in the shared shell. If the app uses the History API, pageviews are already handled. Add custom events only for conversions.

## Examples

These use the existing goal and funnel tools. They do not add a backend feature.

### SaaS

| Outcome | Event | Goal |
| --- | --- | --- |
| Registration completed | `sign_up` with `method` | custom event `sign_up` |
| Trial started | `subscription_started` is the paid start; a trial can be `sign_up` with `method` or a name the app already uses | match that exact name |
| Subscription started | `subscription_started` with `plan`, `value`, `currency` | custom event, optional `plan` condition |
| Purchase completed | `purchase` with `value` and `currency` | custom event `purchase` |

Funnel: pageview `/` → `sign_up` → `subscription_started`. Window `7 days` unless the product needs another allowed window.

### E-commerce

| Outcome | Event |
| --- | --- |
| Product viewed | automatic pageview with a path such as `/products/*`, or `track` only if the view is not a URL change |
| Checkout started | `begin_checkout` |
| Purchase completed | `purchase` |

Funnel: pageview of the product path → `begin_checkout` → `purchase`. Do not also mark the receipt URL as the purchase if the confirmation handler already sent `purchase`. A page visit goal on `/checkout/complete` is a different metric from the `purchase` event.

### Lead generation

| Outcome | Event |
| --- | --- |
| Contact form submitted | `form_submit` with `form: "contact"` |
| Demo requested | `form_submit` with `form: "demo"`, or a dedicated name if you need it separate |
| Lead conversion | a goal on the event that means the lead was accepted |

A goal on `form_submit` with property `form = contact` does not count `form = demo`. Both conditions are equality. An inactive goal does not appear in conversion totals.

## Verify with MCP

| Tool | Use |
| --- | --- |
| `get_tracking_status` | `no_events`, `events_previously`, or `events_recently`. A site record is not installation. |
| `list_recent_events` | Names and paths that actually arrived. Properties are omitted. |
| `list_goals` | Names, event names, paths, conditions, `isActive`. |
| `get_goal_analytics` | Matches, unique visitors, the unique-visitor rate, and `eventCoverage`. |
| `list_funnels` | Steps and the conversion window. |
| `get_funnel_analytics` | Entry visitors, step counts, drop-off, `largestDropOff`. |
| `get_site_analytics_summary` | Pageviews and sessions. Goal and funnel sections need `goals:read` and `funnels:read`. |

### What the result means

- **No events.** The snippet is missing, blocked, or the page has not been loaded. `get_tracking_status` stays `no_events`. Do not invent a collect call.
- **Pageviews only.** Tracking is installed. The custom `track()` call is missing, not deployed, or not on the success path.
- **Name mismatch.** Recent events show `signup_completed` and the goal says `sign_up`. Change one side so they match. CauseWise will not alias them.
- **Property mismatch.** The event name arrived, and `eventCoverage.received` is true, but the goal’s conditions do not match. Check `get_goal_analytics`.
- **Wrong site key.** `data-site` is another site’s public key, or a management key. Replace it with the snippet from `get_tracking_snippet`.
- **Duplicate snippet.** Two tags with the tracker send two pageviews for one view. Remove the extra tag.
- **Inactive goal.** `isActive` is false. Analytics report the inactive status and do not treat it as a live conversion rate.
- **Funnel not completing.** `largestDropOff` names the step. `eventCoverage` on a step tells you whether that event was collected at all. Later steps count only after earlier steps for the same visitor, inside the conversion window.
- **Not deployed yet.** Local code and a passing build do not create production events. Wait until a real visit on the deployed site shows up in `list_recent_events`.