JavaScript SDK

Complete guide to using Quotient's JavaScript SDK

Quotient makes it easy to integrate our platform into your website or node.js application.

SDK Overview

The Quotient JavaScript SDK provides:

🔐 Secure Authentication - API key-based auth with origin restrictions
📊 Analytics Tracking - Page views, searches, and custom events
👤 Profile Management - Create and update customer profiles
🎯 Real-time Context - Automatic device, session, and user tracking
⚛️ Framework Support - Vanilla JS and React packages
📱 Cross-platform - Works in browsers and mobile webviews

Installation

# For vanilla JavaScript/TypeScript
npm install @quotientjs/client

# For React applications
npm install @quotientjs/react

Basic Usage

Vanilla JavaScript

import { QuotientClient } from "@quotientjs/client";

// Initialize the SDK
const quotient = await QuotientClient.init({
  // Your public API key
  apiKey: "pk_test_your_api_key",
});

// Track a page view
await quotient.analytics.event({
  eventType: "pageView",
});

// Identify a user -- use this within a form submission handler
//  to implement contact capture and list building for your email campaigns.
await quotient.people.upsert({
  emailAddress: "user@example.com",
  firstName: "Jane",
  lastName: "Doe",
});

React

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

// Wrap your app
function App() {
  return (
    <QuotientProvider
      // Your public API key
      clientOptions={{ apiKey: "pk_test_your_api_key" }}
      // Set to true to automatically track page views
      autoTrackPageViews={true}
    >
      <YourApp />
    </QuotientProvider>
  );
}

// Use in components
function MyComponent() {
  const { client } = useQuotient();

  const upsertPerson = () => {
    client?.people.upsert({
      emailAddress: "user@example.com",
      firstName: "Jane",
      lastName: "Doe",
    });
  };

  return <button onClick={upsertPerson}>Click Me</button>;
}

Architecture

The SDK consists of several key components:

Client Context

The SDK automatically manages persistent identifiers:

Device ID - Unique identifier per device (localStorage)
Session ID - Unique per browser session (sessionStorage)
Browser Fingerprint - Device characteristics for fraud detection
Person ID - Set after identifying a user

API Communication

All requests include:

Authentication via Authorization: Bearer pk_* header
Client context headers (X-Quotient-Device-Id, etc.)

Common Use Cases

1. (COMING SOON) E-commerce Integration

// Track product views
await quotient.analytics.event({
  eventType: "productView",
  productId: "SKU123",
  productName: "Winter Jacket",
  price: 99.99,
});

2. SaaS User Tracking

// Identify users on signup or from non-authenticated forms
await quotient.people.upsert({
  emailAddress: user.email,
  properties: {
    plan: "pro",
    company: "Acme Corp",
    role: "admin",
  },
});

Performance Considerations

Initialization

Initialize once and cache the client
Use singleton pattern for vanilla JS
Provider handles caching in React