@quotientjs/react

React provider for the Quotient SDK client.

Installation

npm install @quotientjs/react
# or
yarn add @quotientjs/react
# or
pnpm add @quotientjs/react

Usage

Provider Setup

Wrap your application with the QuotientProvider:

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

function App() {
  return (
    <QuotientProvider
      clientOptions={{
        apiKey: "your_api_key",
        baseUrl: "https://api.quotient.com",
      }}
      // Automatically track page views on initial load and route changes
      autoTrackPageViews={true}
    >
      <YourApp />
    </QuotientProvider>
  );
}

Using the Client

Access the Quotient client with the useQuotient hook:

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

function YourComponent() {
  // Get the client context - includes all needed functionality
  const { client, isInitializing, error, reset, trackPageView } = useQuotient();

  // Example: manually track page view
  const handleTrackPageView = () => {
    trackPageView();
  };

  // Example: track a person
  const handleSubmit = async (email) => {
    if (client) {
      await client.people.upsert({
        emailAddress: email,
        emailMarketingState: "SUBSCRIBED",
      });
    }
  };

  return (
    <div>
      {isInitializing ? (
        <p>Initializing client...</p>
      ) : error ? (
        <p>Error: {error.message}</p>
      ) : (
        <p>Client ready!</p>
      )}

      <button onClick={handleTrackPageView}>Track Page View</button>
      <button onClick={reset}>Reset Client</button>
    </div>
  );
}

Automatic Page View Tracking

When autoTrackPageViews is enabled, the provider will:

1. Track a page view when the component mounts
2. Track page views when the pathname changes (works with history API)
3. Works with most modern React routers like React Router

This is ideal for Single Page Applications where you want analytics for each virtual page.

Additional Hooks

For components that only need to know the client status:

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

function ClientStatus() {
  // Get just the client status without the client itself
  const { isInitializing, error } = useQuotientStatus();

  return (
    <div>
      {isInitializing
        ? "Initializing..."
        : error
          ? `Error: ${error.message}`
          : "Ready"}
    </div>
  );
}

Manual Initialization

If you need to initialize the client manually:

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

function App() {
  return (
    <QuotientProvider
      clientOptions={{
        apiKey: "your_api_key",
        baseUrl: "https://api.quotient.com",
      }}
      autoInitialize={false}
    >
      <InitializeButton />
    </QuotientProvider>
  );
}

function InitializeButton() {
  const { initialize, isInitializing, client } = useQuotient();

  return (
    <div>
      {client ? (
        <p>Client initialized!</p>
      ) : (
        <button onClick={initialize} disabled={isInitializing}>
          {isInitializing ? "Initializing..." : "Initialize Client"}
        </button>
      )}
    </div>
  );
}

License

MIT