# CauseWise tracking API

This is the browser tracker in `causewise.js`. Management keys, goals, and funnels are a different API. See [causewise-mcp.md](./causewise-mcp.md).

The public object is `window.causewise`. It has one method, `track`, and a `version` string. There is no `identify`, `page`, or queue.

## Install the script

Use the snippet from CauseWise (`get_tracking_snippet` or the site Setup page). It looks like:

```html
<script async src="https://causewise.io/causewise.js" data-site="PUBLIC_TRACKING_KEY" data-collect-base="https://causewise.io"></script>
```

- `data-site` is the site’s public tracking key. It is not a `cw_api_` management key.
- `data-collect-base` is the CauseWise origin. Collection is `POST {origin}/api/collect`.
- Put the tag once in the shared head or root layout.
- If a script with the same `data-site` is already on the page, do not add another one. Each copy runs on its own and sends its own events.
- `data-debug="true"` logs the site key, the collect URL, and the response. Leave it off in production.
- `/track.js` only loads `/causewise.js` and copies `data-site`. Prefer `/causewise.js`.

The script reads `data-site` from the embed tag, including when `document.currentScript` is null after `async` load.

## Automatic pageviews

After the script runs it sends a `pageview` for the current URL. It also wraps `history.pushState` and `history.replaceState`, and listens for `popstate`. A navigation that changes the URL is sent about 75ms later. The previous URL is the referrer for that pageview.

The same full URL is not sent again by that script instance. A reload starts a new instance and sends the page again.

Do not call `window.causewise.track("pageview")`. That would be a second event on top of the automatic one.

Hash routers that only change `location.hash` and never call `history.pushState` are not tracked as navigations.

## Custom events

```js
window.causewise.track("sign_up", {
  method: "email"
});
```

```js
window.causewise.track("purchase", {
  value: 49.99,
  currency: "USD"
});
```

`track` sends the current URL, path (including the query string), title, document referrer, a timestamp, and the same visitor and session ids as pageviews. The event name is the `type` stored by CauseWise, truncated to 64 characters. An empty name is stored as `custom`.

Call `track` from the code path that knows the outcome succeeded: the registration response, the payment confirmation, the form success handler. Call it after `causewise.js` has executed. The public script does not queue calls made before it loads. A click handler that runs after page load is safe. A script that runs above the snippet is not.

`track` does not drop duplicate custom events. A handler that runs twice sends two events. In React development, Strict Mode runs mount effects twice, so do not put a conversion event in a mount effect unless you guard it.

## Properties

The second argument must be a plain object. An array or other value is ignored.

JSON-serializable values are stored. Goal and funnel conditions compare with equality:

- strings must match exactly
- finite numbers match their decimal string (`49.99` matches `"49.99"`)
- booleans match `"true"` or `"false"`
- objects and arrays are stored and do not satisfy an equality condition

A properties object larger than 32KB is dropped by collection. Omit the argument when there is nothing to send.

Names and values you send are visible to people who can read the site in CauseWise. Do not send email addresses, names, passwords, card data, session tokens, or raw form bodies.

## Visitor and session

The script stores a random `cw_vid` in `localStorage` and a `cw_sid` that rolls after 30 minutes of inactivity. These are not user accounts. If storage is blocked, events are still sent without those ids, and unique-visitor rates may be omitted.

The request uses `fetch` with `credentials: "omit"` and `Content-Type: text/plain`. Collection does not use the management API key.

## What the tracker stores

Each event can include the URL, path, title, referrer, visitor id, session id, timestamp, event name, the properties you passed, and the browser user agent. Do not add personal data to properties to “identify” the visitor. CauseWise does not provide a user-id API.