Getting started

Install the SDK, identify your users, and connect your coding agent to your Saasco project.

Getting Saasco into your app takes four steps: install the SDK, identify people when they sign in, track the lifecycle events you care about, and connect your coding agent over MCP.

Agent prompt

Paste this into Claude Code, Cursor, Codex or any coding agent that can edit your repo and run commands. If you're signed in, your Project ID is already filled in. Otherwise the agent asks you for the ID from Settings → Project. The same steps are on Setup for coding agents. The prompt sends your agent that page as plain text.

First ask me for my Saasco project ID (Settings → Project in Saasco) and use it wherever YOUR-PROJECT-ID appears on that page and in the commands below.

Before you change anything, run `curl -sX POST "https://www.saasco.com/api/setup/started?projectId=YOUR-PROJECT-ID"` so my Saasco setup screen knows you've started.

Set up Saasco in this project. Read https://www.saasco.com/docs/sdk/agents.md and follow that page. My Saasco project ID is "YOUR-PROJECT-ID".

Check progress with `curl -s "https://www.saasco.com/api/setup/progress?projectId=YOUR-PROJECT-ID"`.

Before you start

A Saasco account and a project. See Before you start.
Your Project ID, from Settings → Project in the dashboard.

Test and live

Every project comes with a test project. Its ID is your Project ID with test_ in front, for example test_YOUR-PROJECT-ID. Send everything from local development, staging and preview deployments to the test project, and only production to the live one. Setup and testing then never show up in your live analytics, contacts or billing.

Switch between them from the project menu in the dashboard: pick a project, then Live or Test mode. Test mode is free up to a small monthly allowance. Campaigns can't be sent from it, and its emails only go to the project's members.

Install the SDK with your live Project ID. The SDK sends to the test project by itself on:

localhost, 127.0.0.1 and *.localhost
Preview deployments on Vercel (-git- branch and deployment URLs), Netlify (-- deploys), Cloudflare Pages (<branch>.<project>.pages.dev) and Render (-pr-<n>)
Subdomains starting staging., stage., preview., dev., test., qa. or uat.

Everywhere else counts as live. For a staging host that doesn't match, turn on test for that environment:

new Saasco({
  projectId: "YOUR-PROJECT-ID",
  test: true,
});

On the script tag, add data-test="true". Pass test: false to send one of the hosts above to live.

Install the SDK

Install the package

npm install saasco-sdk

Use whichever package manager your lockfile says you use.

Create the client

lib/saasco.ts

import { Saasco } from "saasco-sdk";

export const saasco = new Saasco({
  projectId: "YOUR-PROJECT-ID",
});

Call `init()` once, in the browser

init() starts automatic page views and loads the support and social-proof widgets when they're switched on in the dashboard. Constructing new Saasco(...) on its own does neither.

The SDK reads cookies and window.location, so it must never run during server rendering. Where the call goes depends on your framework:

Components render on the server by default (the Next.js App Router and similar): make a small client-only component that calls init() on mount, and render it once from the root layout.
Client-rendered apps (the Next.js Pages Router, Vite): call init() at the client entry point, such as pages/_app.tsx or main.tsx.
No build step: skip npm and add the script tag below before </body>. It calls init() for you.

components/SaascoAnalytics.tsx

"use client";

import { useEffect } from "react";

import { saasco } from "../lib/saasco";

export function SaascoAnalytics() {
  useEffect(() => {
    saasco.init();
  }, []);

  return null;
}

<script
  src="https://www.saasco.com/sdk/saasco-sdk.js"
  data-projectId="YOUR-PROJECT-ID"
  async
></script>

The SDK quick start covers the same install in more depth, and Configuration lists every option.

Identify your users

Call identify() when someone signs in, and logout() when they sign out. This is what turns a signup into a CRM contact.

saasco.identify(user.id, { email: user.email, name: user.name });

saasco.logout();

Call it on sign-in or when their details change, not on every page load. Identify covers people who don't have an account yet, such as newsletter signups.

Track lifecycle events

Page views are automatic after init(), so don't call page() as well. For the key moments in a customer's lifecycle, use the reserved names so funnels and revenue line up without a mapping step:

saasco.track("Signed Up");

saasco.track("Subscription Started", {
  plan: "pro",
  revenue: 49,
  currency: "USD",
});

The full list is Signed Up, Signed In, Signed Out, Trial Started, Trial Ended, Payment Completed, Subscription Started, Subscription Cancelled, Subscription Upgraded and Subscription Downgraded.

Send browser events through the SDK rather than with fetch or the REST API. The SDK is what attaches the session, referrer and UTM parameters. Billing events usually happen on your server instead. Tracking shows how to send those.

Connect your coding agent

The Saasco MCP server lets your agent query events, contacts and support conversations. Follow MCP and use the steps for your client. Add ?projectId= with this project's id to keep the entry on this project; leave it off to reach every project on the account.

To write an entry for every agent on the machine instead, use add-mcp:

npx -y add-mcp https://www.saasco.com/api/mcp?projectId=YOUR_PROJECT_ID

Adding the server doesn't sign you in, and your agent can't do that step for you. Reload your agent, then authorize it: in Claude Code, run /mcp, select saasco and choose Authenticate. In Cursor, click Needs login in Settings → MCP. Your browser opens on Saasco, where you sign in and allow access.

Check it works

Load your app with ?saasco-debug=true on the URL. The console logs Saasco started, then every event the SDK sends. Within a few seconds the Page View shows up in Analytics → Debugger (in Test mode while you're on the test project), and identified users show up on its Identifies tab.

From a terminal, or for an agent that can't read the browser console, ask Saasco which setup steps have arrived and what the last events in the test project were:

curl -s "https://www.saasco.com/api/setup/progress?projectId=YOUR-PROJECT-ID"

Setup for coding agents explains each field.

With MCP connected, you can also ask your agent: "Show me the latest events in Saasco."

Next steps

Turn on the support widget. It loads through the SDK you just installed, so there is no second snippet. Switch it on and add your site's origin as a trusted domain in the Support app.
Show social proof notifications built from the events you already track.
When you're ready, send production traffic to the live project and check it in the dashboard with Live selected.
Connect a domain under Settings → Domains to send email campaigns and create branded short links.
Use the REST API for backfills, imports and server-to-server events.

Getting Saasco into your app takes four steps: install the SDK, identify people when they sign in, track the lifecycle events you care about, and connect your coding agent over MCP.

Agent prompt

First ask me for my Saasco project ID (Settings → Project in Saasco) and use it wherever YOUR-PROJECT-ID appears on that page and in the commands below.

Before you change anything, run `curl -sX POST "https://www.saasco.com/api/setup/started?projectId=YOUR-PROJECT-ID"` so my Saasco setup screen knows you've started.

Set up Saasco in this project. Read https://www.saasco.com/docs/sdk/agents.md and follow that page. My Saasco project ID is "YOUR-PROJECT-ID".

Check progress with `curl -s "https://www.saasco.com/api/setup/progress?projectId=YOUR-PROJECT-ID"`.

Before you start

A Saasco account and a project. See Before you start.
Your Project ID, from Settings → Project in the dashboard.

Test and live

Install the SDK with your live Project ID. The SDK sends to the test project by itself on:

localhost, 127.0.0.1 and *.localhost
Preview deployments on Vercel (-git- branch and deployment URLs), Netlify (-- deploys), Cloudflare Pages (<branch>.<project>.pages.dev) and Render (-pr-<n>)
Subdomains starting staging., stage., preview., dev., test., qa. or uat.

Everywhere else counts as live. For a staging host that doesn't match, turn on test for that environment:

new Saasco({
  projectId: "YOUR-PROJECT-ID",
  test: true,
});

On the script tag, add data-test="true". Pass test: false to send one of the hosts above to live.

Install the SDK

Install the package

npm install saasco-sdk

Use whichever package manager your lockfile says you use.

Create the client

lib/saasco.ts

import { Saasco } from "saasco-sdk";

export const saasco = new Saasco({
  projectId: "YOUR-PROJECT-ID",
});

Call `init()` once, in the browser

init() starts automatic page views and loads the support and social-proof widgets when they're switched on in the dashboard. Constructing new Saasco(...) on its own does neither.

The SDK reads cookies and window.location, so it must never run during server rendering. Where the call goes depends on your framework:

Components render on the server by default (the Next.js App Router and similar): make a small client-only component that calls init() on mount, and render it once from the root layout.
Client-rendered apps (the Next.js Pages Router, Vite): call init() at the client entry point, such as pages/_app.tsx or main.tsx.
No build step: skip npm and add the script tag below before </body>. It calls init() for you.

components/SaascoAnalytics.tsx

"use client";

import { useEffect } from "react";

import { saasco } from "../lib/saasco";

export function SaascoAnalytics() {
  useEffect(() => {
    saasco.init();
  }, []);

  return null;
}

<script
  src="https://www.saasco.com/sdk/saasco-sdk.js"
  data-projectId="YOUR-PROJECT-ID"
  async
></script>

The SDK quick start covers the same install in more depth, and Configuration lists every option.

Identify your users

Call identify() when someone signs in, and logout() when they sign out. This is what turns a signup into a CRM contact.

saasco.identify(user.id, { email: user.email, name: user.name });

saasco.logout();

Call it on sign-in or when their details change, not on every page load. Identify covers people who don't have an account yet, such as newsletter signups.

Track lifecycle events

Page views are automatic after init(), so don't call page() as well. For the key moments in a customer's lifecycle, use the reserved names so funnels and revenue line up without a mapping step:

saasco.track("Signed Up");

saasco.track("Subscription Started", {
  plan: "pro",
  revenue: 49,
  currency: "USD",
});

Connect your coding agent

To write an entry for every agent on the machine instead, use add-mcp:

npx -y add-mcp https://www.saasco.com/api/mcp?projectId=YOUR_PROJECT_ID

Check it works

From a terminal, or for an agent that can't read the browser console, ask Saasco which setup steps have arrived and what the last events in the test project were:

curl -s "https://www.saasco.com/api/setup/progress?projectId=YOUR-PROJECT-ID"

Setup for coding agents explains each field.

With MCP connected, you can also ask your agent: "Show me the latest events in Saasco."

Next steps

Turn on the support widget. It loads through the SDK you just installed, so there is no second snippet. Switch it on and add your site's origin as a trusted domain in the Support app.
Show social proof notifications built from the events you already track.
When you're ready, send production traffic to the live project and check it in the dashboard with Live selected.
Connect a domain under Settings → Domains to send email campaigns and create branded short links.
Use the REST API for backfills, imports and server-to-server events.

Getting started

Agent prompt

Before you start

Test and live

Install the SDK

Install the package

Create the client

Call `init()` once, in the browser

Identify your users

Track lifecycle events

Connect your coding agent

Check it works

Next steps

On this page

Getting started

Agent prompt

Before you start

Test and live

Install the SDK

Install the package

Create the client

Call `init()` once, in the browser

Identify your users

Track lifecycle events

Connect your coding agent

Check it works

Next steps

On this page