Track page views and custom events with the Quotient analytics API

Overview

Use the analytics API to connect activity on your site, such as viewing a page or custom event that you define, to the marketing that brought each visitor there.

The client SDK (@quotientjs/client or @quotientjs/react) runs in the browser. It adds the visitor's session, attribution, and identity to each event. The server SDK (@quotientjs/server) tracks backend events about a person you already know.

Endpoint	API Key	SDK	Method
Track a browser event	public	Client SDK	client.analytics.event(event)
Track a server event	private	Server SDK	quotient.analytics.event(event)

Track a Client Event with @quotientjs/client

client.analytics.event(event)

POST /api/v0/analytics/web

Auth: public key · scope: ANALYTICS_WRITE

Every client event includes the current session ID, device ID, browser fingerprint, page URL, and attribution. Attribution comes from the utm_* and qt_* parameters on the visitor's incoming URL and lasts for the current session. If a tagged link or client.audience.people.upsert() identifies the visitor, the SDK includes their personId too. You only provide the event.

eventType	Extra fields	Description
"pageView"	none	A page view. The SDK tracks these automatically by default
"custom"	customEventId: string	The ID of an event defined by your business, such as "completedOnboarding"

// Page view (usually automatic; see Auto-Tracking below)
await client.analytics.event({
  eventType: "pageView",
});

// Custom event
await client.analytics.event({
  eventType: "custom",
  customEventId: "completedOnboarding",
});

Returns: void

Register each custom event in Quotient before sending it. Pass its immutable event ID as customEventId; the API rejects IDs that have not been registered for your business.

Track a Server Event

quotient.analytics.event(event)

POST /api/v0/analytics/server

Auth: private key · scope: ANALYTICS_WRITE

Use a server event when an activity that matters to your marketing analytics does not take place in a browser. These activities often happen in webhooks, OAuth callbacks, scheduled jobs, or other backend code. For example, you might track when a free trial expires, a customer upgrades their plan, or a user completes onboarding.

The server API currently accepts custom events only. Each event must be about a known person, so include their personId, the person's identifier in Quotient. It must belong to an existing person in your business. Because the event does not come from a browser, the SDK cannot add a browser session or its attribution automatically. You can optionally attribute the event to a campaign by including campaignId.

Field	Type	Required	Description
eventType	"custom"	Yes	Server events are always custom events today
personId	string	Yes	The Quotient identifier of the person this event is about
customEventId	string	Yes	A custom event ID already registered for your business
campaignId	string	No	Attributes the event to a specific campaign

await quotient.analytics.event({
  eventType: "custom",
  personId: "person_abc123",
  customEventId: "upgradedPlan",
});

Returns: void

Auto-Tracking with React

QuotientProvider tracks a page view when your app loads and after each navigation. Auto-tracking is on by default, so no additional setup is needed.

<QuotientProvider clientOptions={{ apiKey: "pk_your_public_api_key" }}>
  <YourApp />
</QuotientProvider>

If another tool on the page already sends Quotient page views, pass autoTrackPageViews={false} to avoid counting each navigation twice.

See the React SDK article for full provider setup. For manual tracking, use client.analytics.event() via the useQuotient() hook.

Common Patterns

Custom Event Tracking

import { useQuotient } from "@quotientjs/react";

function CompleteOnboardingButton() {
  const { client } = useQuotient();

  const handleClick = async () => {
    completeOnboarding();
    await client?.analytics.event({
      eventType: "custom",
      customEventId: "completedOnboarding",
    });
  };

  return <button onClick={handleClick}>Complete onboarding</button>;
}

Page View Tracking in a SPA

If you're not using the React SDK's autoTrackPageViews, you can track route changes manually:

import { useEffect } from "react";
import { useLocation } from "react-router-dom";
import { useQuotient } from "@quotientjs/react";

function PageTracker() {
  const location = useLocation();
  const { client } = useQuotient();

  useEffect(() => {
    void client?.analytics.event({ eventType: "pageView" });
  }, [location, client]);

  return null;
}

Next Steps