Docs

Install Userbook with an AI coding agent

Paste this prompt into Claude, Codex, or your preferred coding agent. It tells the agent how to add Userbook, identify users, and track the standard SaaS lifecycle events.

Agent install prompt

Open https://userbook.io/docs/install and install Userbook in this app.

Use the Node SDK where server-side code is available:
- Install @userbook/node.
- Read the API key from USERBOOK_API_KEY.
- Create one shared Userbook client.
- Do not expose USERBOOK_API_KEY in browser/client bundles.
- Set USERBOOK_DEV_MODE=true only for local validation when outbound writes should be suppressed.

Identify users with userbook.identify() whenever a user signs up, signs in, changes profile/account details, changes plan, or completes onboarding.

Attach these fields when they are available:
- id: stable user id
- email
- name
- role
- organisation: { id, name } using the account/org/workspace id and name
- plan: { name, interval, cost, currency, trial_days, subscribed_at }
- signup_source

Track these standard lifecycle events with userbook.event():
- signed_up
- signed_in
- signed_out
- started_trial
- completed_onboarding
- activated
- upgraded
- downgraded
- changed_plan
- cancelled
- reactivated
- opened_email
- error
- custom
- closed_account

For every event, include identity_id with the same stable user id used in identify().
Do not duplicate organisation or plan details in event metadata when those details are already attached through identify().
Add useful event-specific description and metadata when available, such as source, route, feature, step, error_name, and error_message.
For revenue-impacting events, include cost and currency on the event itself so Userbook can connect product activity to customer value.
For application-specific behavior, send type: 'custom' with a descriptive custom event name.

After installing, add or update tests around the integration points, then run the relevant test/build command for this app.

Implementation reference

Use this section when you or the coding agent need the exact SDK shape.

Install the SDK

npm install @userbook/node

Use an API key

const userbook = require('@userbook/node')(
  process.env.USERBOOK_API_KEY
);

Identify a user

userbook.identify({
  id: user.id,
  email: user.email,
  name: user.name,
  organisation: {
    id: account.id,
    name: account.name,
  },
  plan: {
    name: account.plan,
  },
});

Track an event

userbook.event({
  type: 'standard',
  name: 'completed_onboarding',
  identity_id: user.id,
});

Identify users

Use identify to attach durable user, organisation, and plan context to every identity.

Full identify shape

userbook.identify({
  id: user.id,
  email: user.email,
  name: user.name,
  role: user.role,
  organisation: {
    id: organisation.id,
    name: organisation.name,
  },
  plan: {
    name: plan.name,
    interval: plan.interval,
    cost: plan.price,
    currency: plan.currency,
    trial_days: plan.trialDays,
    subscribed_at: subscription.startedAt,
  },
  signup_source: user.signupSource,
});

When to identify

Call identify() after signup and signin.
Call it when profile, organisation, role, or plan data changes.
Call it before or alongside lifecycle events so events are connected to the right identity.
Keep organisation and plan data on the identity instead of repeating it on every event.

Track standard events

Userbook standard events must use the supported event names below. The SDK sends standard events by default; direct API calls should include type: 'standard'.

signed_up

signed_in

signed_out

started_trial

completed_onboarding

activated

upgraded

downgraded

changed_plan

cancelled

reactivated

opened_email

error

custom

closed_account

Event example

userbook.event({
  name: 'completed_onboarding',
  identity_id: user.id,
  description: 'Completed onboarding',
  metadata: {
    source: 'onboarding',
    step_count: 4,
  },
});

Track custom events

Use custom events for product behavior that is important to your app but is not one of the standard lifecycle events.

Custom event example

userbook.event({
  type: 'custom',
  name: 'report_exported',
  identity_id: user.id,
  description: 'Exported a report',
  metadata: {
    format: 'csv',
    row_count: 500,
  },
});

Use event metadata for context

Metadata should describe the event itself: route, feature, source, format, counts, ids for the object acted on, or error details. Do not use event metadata to repeat user plan or organisation fields already sent through identify().

Track event value

Use cost and currency when a specific event has direct monetary value.

Cost example

userbook.event({
  type: 'custom',
  name: 'ai_tokens_used',
  identity_id: user.id,
  description: 'Generated AI summary',
  cost: 0.18,
  currency: 'USD',
  metadata: {
    model: 'gpt-4.1',
    input_tokens: 2100,
    output_tokens: 420,
  },
});

Why cost matters

Event cost helps Userbook show which product actions create variable cost or measurable value. Use it for usage-based activity such as AI token spend, API calls, compute jobs, storage, or credit consumption. Keep subscription price and trial details on the identity plan.