SDK Setup

How to install and use the Quotient SDK in your application

This guide walks you through setting up the Quotient SDK from start to finish, including API key creation, SDK installation, and implementation best practices.

Prerequisites

Before starting, ensure you have:

• A Quotient account with a business created
• Access to your application's codebase
• Node.js 14+ and npm/yarn/pnpm installed

Step 1: Create Your API Key

1.1 Access Developer Settings

1. Log into your Quotient dashboard
2. Navigate to Settings → Developers
3. Click "Create API Key"

1.2 Configure Your Key

For Development:

Name: Development Web App
Description: Local development environment
Allowed Origins: 
- localhost:3000
- localhost:3001
- 127.0.0.1:3000

For Production:

Name: Production Web App
Description: Main production application
Allowed Origins:
- yourapp.com
- www.yourapp.com
- app.yourapp.com

Step 2: Install the SDK

Choose the appropriate package for your framework:

Vanilla JavaScript / TypeScript

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

React

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

Step 3: Environment Setup

3.1 Create Environment Variables

It is safe, but not recommended to hard-code API keys. Use environment variables:

.env.local (Next.js)

NEXT_PUBLIC_QUOTIENT_API_KEY=pk_test_your_api_key_here

.env (Vite/Create React App)

VITE_QUOTIENT_API_KEY=pk_test_your_api_key_here
# or for Create React App
REACT_APP_QUOTIENT_API_KEY=pk_test_your_api_key_here

Step 4: Initialize the SDK

We allow you to source the sdk in a few different ways.

Vanilla JavaScript

Basic Setup:

// get-quotient-client.js
import { QuotientClient } from '@quotientjs/client';

let client: QuotientClient | null = null;

export async function getQuotientClient() {
  if (!client) {
    client = await QuotientClient.init({
      apiKey: process.env.NEXT_PUBLIC_QUOTIENT_API_KEY,
    });
  }
  return client;
}

React Setup

App.jsx / App.tsx:

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

function App() {
  // Handle missing API key
  const apiKey = import.meta.env.VITE_QUOTIENT_API_KEY;
  
  if (!apiKey) {
    return (
      <div className="error">
        Missing Quotient API key. Please set VITE_QUOTIENT_API_KEY.
      </div>
    );
  }

  return (
    <QuotientProvider
      clientOptions={{
        apiKey,
      }}
      autoTrackPageViews={true}
    >
      <YourApp />
    </QuotientProvider>
  );
}

Step 5: Basic Implementation

Once your SDK is initialized, you can start tracking events and managing customer data. Here are the essential features to implement:

Page View Tracking

For React apps with autoTrackPageViews={true}, page views are tracked automatically. For manual tracking or vanilla JavaScript:

// Track initial page view
await client.analytics.event({ eventType: 'pageView' });

User Identification

Identify users when they sign up, log in, or submit forms:

const { personId } = await client.people.upsert({
  emailAddress: 'user@example.com',
  firstName: 'Jane',
  lastName: 'Doe'
});

Event Tracking

Track important user interactions:

// Track search
await client.analytics.event({
  eventType: 'search',
  searchQuery: 'winter boots'
});

For detailed implementation examples and the full API reference, see the SDK Usage Guide.

Step 6: Testing Your Implementation

6.1 Verify Connection

// test-quotient.js
async function testQuotientConnection() {
  try {
    const client = await getQuotientClient();
    const info = await client.auth.whoami({});
    
    console.log('✅ Connection successful');
    console.log('Business ID:', info.businessId);
    console.log('Key Type:', info.keyType);
    console.log('Device ID:', info.deviceId);
    
    return true;
  } catch (error) {
    console.error('❌ Connection failed:', error);
    return false;
  }
}

6.2 Debug Event Tracking

// Enable debug mode
const client = await QuotientClient.init({
  apiKey: process.env.NEXT_PUBLIC_QUOTIENT_API_KEY,
  debug: true // Logs all API calls
});

// Test event tracking
async function testTracking() {
  const client = await getQuotientClient();
  
  console.log('Testing page view...');
  await client.analytics.event({ eventType: 'pageView' });
  
  console.log('Testing search...');
  await client.analytics.event({ 
    eventType: 'search',
    searchQuery: 'test query'
  });
  
  console.log('✅ Events tracked successfully');
}

6.3 Verify in Dashboard

1. Go to your Quotient dashboard
2. Navigate to Analytics → Events
3. You should see:
   • Page view events
   • Search events
   • Device/session information

Next Steps