Documentation

Getting started

CauseWise collects pageviews and custom events, then reports them in the dashboard. React components only display data your application has already loaded. They do not call CauseWise and they do not accept an API key.

Account and API key

1. Create a CauseWise account and a site.
2. Copy the public tracking snippet from the site Setup page. That key is not a management key.
3. In Settings → API keys, name a workspace key and select the scopes you need. The secret is shown once.
4. Store it as CAUSEWISE_API_KEY on the server. Do not prefix it with NEXT_PUBLIC_.

API key reference

Paid subscription

Public tracking, the signed-in CauseWise dashboard, and the WordPress snippet work on the free plan./api/v1, /api/mcp, and @razorsoft/causewise need an eligible paid subscription: Pro, Team, or Enterprise with status active, trialing, or unset. The free plan, and a paid plan that is canceled, past_due, or unpaid, receives 402 subscription_required. CauseWise checks this on the server.

Plans

Quick start

Install the tracker, then install the server SDK and React package when you want analytics inside your own application.

npm install @razorsoft/causewise @razorsoft/causewise-react

A complete Next.js page is in examples/nextjs/README.md. Component gallery

Tracking script

Put the official snippet once in the shared head or root layout. data-site is the public site key.

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

Tracking guide

Automatic pageviews

After the script runs it sends a pageview for the current URL, and again when history.pushState, history.replaceState, or popstate changes the URL. Do not call window.causewise.track("pageview"). Hash-only routers are not tracked as navigations.

Custom events

The browser object is window.causewise. Call track from the success path, after the script has loaded. The script does not queue earlier calls.

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

Event properties

The second argument must be a plain object. Goal and funnel conditions compare with equality. Strings must match exactly. A properties object larger than 32KB is dropped. Do not send email addresses, names, passwords, card data, or tokens. Recent-event responses omit property payloads.

Event conventions

Recommended names include sign_up, login, form_submit, begin_checkout, purchase, and subscription_started. Any other name still works. The goal or funnel step must use the same string the site sends. sign_up and signup_completed are different events.

Events guide · Goals · Funnels

REST API

Workspace keys call https://causewise.io/api/v1. The same operations are available as MCP tools.

curl https://causewise.io/api/v1/sites \  -H "Authorization: Bearer $CAUSEWISE_API_KEY"

API authentication

Send Authorization: Bearer cw_api_…. A public tracking key is rejected. CauseWise stores only a hash of the management key.

Permission scopes

• sites:read lists sites and fetches the tracking snippet. sites:write creates and updates sites.
• analytics:read covers summary, overview, tracking status, and recent events.
• goals:read and funnels:read cover those lists and their analytics. The matching :write scopes create, update, and delete.

A write scope does not include the matching read scope. The server SDK uses the read scopes only.

Error handling

• 401 means the key is missing, invalid, revoked, or expired.
• 403 means the key is missing the scope named in the error.
• 402 subscription_required means the workspace is not on an eligible paid plan.
• 404 means the site, goal, or funnel is not in this workspace.
• 429 means the key exceeded the rate limit.

Rate limits

A workspace API key allows 120 requests per minute. Over the limit, CauseWise returns 429. The SDK exposes retryAfterSeconds on CauseWiseError when the response includes it.

REST and MCP reference

TypeScript SDK

@razorsoft/causewise runs on the server. Its browser export throws. The default API origin is https://causewise.io.

import { CauseWise, CauseWiseError } from "@razorsoft/causewise"; const causewise = new CauseWise({  apiKey: process.env.CAUSEWISE_API_KEY!,}); try {  const summary = await causewise.analytics.summary({    siteId: process.env.CAUSEWISE_SITE_ID!,    range: "7d",  });} catch (error) {  if (error instanceof CauseWiseError) {    console.error(error.status, error.code, error.message);  }}

range is today, 7d, or 30d.analytics.overview returns the traffic trend. Each point counts events in that bucket, not pageviews alone.

SDK guide

React components

@razorsoft/causewise-react needs React 18 or newer. Import the stylesheet once.

import "@razorsoft/causewise-react/styles.css";import { CauseWiseStats } from "@razorsoft/causewise-react";

• CauseWiseStats shows pageviews, sessions, and visitors. A null visitor count renders as Unavailable.
• CauseWiseTrafficChart plots overview trend counts. The default series label is Events.
• CauseWiseTopPages lists paths and view counts.
• CauseWiseGoals lists goal conversions from the summary payload.
• CauseWiseFunnel draws one funnel. conversionWindow is seconds.
• CauseWiseRecentEvents lists recent events. Property payloads are omitted.

Component guide · Component gallery

Complete dashboard

CauseWiseDashboard composes the sections. Check the signed-in user before the server calls the SDK. Pass sections to hide a block, for example sections={{ goals: false }}.

<CauseWiseDashboard  title="Acme analytics"  theme="dark"  period={summary.period}  stats={summary}  trend={{    range: overview.range,    trend: overview.trend,    seriesLabel: "Events",  }}  topPages={summary.topPages}  goals={summary.goals}  funnels={summary.funnels}  recentEvents={summary.recentEvents}/>

Themes

theme is light, dark, or system. system follows prefers-color-scheme. Override the variables on .cw-root: --cw-bg, --cw-surface, --cw-text, --cw-muted, --cw-border, --cw-accent, and --cw-font.

Loading and errors

Shared props include state (ready, loading, error) and error ({ code?, message }). Empty arrays render an empty state. Null visitor and conversion rates stay unavailable.

<CauseWiseDashboard state="loading" /><CauseWiseDashboard  state="error"  error={{ code: "subscription_required", message: "Subscription required." }}/>

MCP

Assistants connect to https://causewise.io/api/mcp with the same workspace key. The assistant edits the website. CauseWise does not. Do not put the management key in the website.

MCP tools

The server exposes 21 tools: list_sites, create_site, get_site, update_site, get_tracking_snippet, get_tracking_instructions, get_tracking_status, list_recent_events, list_goals, create_goal, get_goal, update_goal, delete_goal, get_goal_analytics, list_funnels, create_funnel, get_funnel, update_funnel, delete_funnel, get_funnel_analytics, and get_site_analytics_summary.

Cursor

{  "mcpServers": {    "causewise": {      "url": "https://causewise.io/api/mcp",      "headers": {        "Authorization": "Bearer cw_api_YOUR_KEY"      }    }  }}

Claude Code

Claude Code requires type. ${CAUSEWISE_API_KEY} is the raw cw_api_… key.

{  "mcpServers": {    "causewise": {      "type": "http",      "url": "https://causewise.io/api/mcp",      "headers": {        "Authorization": "Bearer ${CAUSEWISE_API_KEY}"      }    }  }}

Codex

Set CAUSEWISE_AUTHORIZATION to Bearer cw_api_…. Codex copies that value into the header.

[mcp_servers.causewise]url = "https://causewise.io/api/mcp" [mcp_servers.causewise.env_http_headers]Authorization = "CAUSEWISE_AUTHORIZATION"

AI instrumentation

Ask the assistant to register the site if needed, install the official snippet once, and add window.causewise.track only for outcomes a pageview cannot represent. It should confirm collection with get_tracking_status and list_recent_events. A passing test suite does not prove an event was stored.

Assistant setup · MCP reference

WordPress

The plugin installs the public tracking snippet. Upload the 0.4.0 ZIP, activate it, and paste the tracking code from the CauseWise dashboard into Settings → CauseWise Analytics. Page views still use only the public site key. The CauseWise screen inside WordPress reads the management API from the server. A management key saved there is not added to the tracker. The CauseWise category has Analytics Overview, Traffic Chart, Top Pages, Referrers, Goals, and Recent Events. The matching shortcodes are [causewise_stats], [causewise_traffic], [causewise_top_pages], [causewise_referrers], [causewise_goals], and [causewise_events]. Visitors see a sign-in message. The numbers load only for a signed-in user who can activate plugins, and event properties are not included. An empty goal list says that no goals have been configured yet. To track a Button block, select it, enable CauseWise tracking, name the event, and publish.

WordPress integration