Custom Website

Install website tracking on a site you build and host yourself

When someone reaches your website from a Quotient email, social post, or campaign, the Quotient pixel shows you what they do next. It records the pages they visit while preserving the content that brought them to your site as the source.

This guide covers websites that you build yourself, from static HTML hosted on GitHub Pages to applications built with React, Next.js, Remix, or React Router. If you use a hosted website builder, follow the instructions for that platform instead.

Create a Public API Key

Create a key in Settings → Developers. Choose a Public key and give it the Analytics: write permission.

Add every domain where you will run the pixel to the key's allowed origins. For example, you might add:

https://example.com for your production site
https://your-name.github.io for a GitHub Pages site
http://localhost:3000 for local development

Each origin must match exactly, including https://. If your site loads on both https://example.com and https://www.example.com, add both.

Allowed origins prevent another website from using your key. The key you copy should begin with pk_. Never put a private key beginning with sk_ in code that runs in a browser.

Choose an Installation Method

The right installation method depends on how your site is built.

Static HTML

Use this method for a site made from HTML files, including a static site hosted on GitHub Pages. Add the following code before the closing </body> tag on every page you want to track:

<script src="https://unpkg.com/@quotientjs/client@0.6.2/dist/quotient.browser.js"></script>
<script>
  const client = Quotient.QuotientClient.init({
    apiKey: "pk_replace_with_your_public_key",
  });
</script>

Replace pk_replace_with_your_public_key with the public key you copied from Quotient. If your site uses a shared layout or template, add the code there so you do not have to maintain a separate copy on every page.

JavaScript or TypeScript

Use the browser client if your site has a JavaScript build step but does not use React. Install it with your package manager:

npm install @quotientjs/client

Then initialize it once from the browser entry point for your site:

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

const client = QuotientClient.init({
  apiKey: "pk_replace_with_your_public_key",
});

This code must run in the browser, where it can read the current page and store the visitor's session. Do not initialize the browser client from server-only code.

React, Remix, or React Router

For a React application, install the React package:

npm install @quotientjs/react

Wrap the root of your application with QuotientProvider:

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

export function App() {
  return (
    <QuotientProvider
      clientOptions={{ apiKey: "pk_replace_with_your_public_key" }}
    >
      <YourApp />
    </QuotientProvider>
  );
}

The provider should stay mounted while the visitor moves between pages. In a React Router application, place it above your router or around the root route's Outlet. In Remix and framework-mode React Router, add it to app/root.tsx around the Outlet.

Next.js App Router

The Quotient provider uses browser features, so it needs a small Client Component in a Next.js App Router project. Create a file such as app/quotient-provider.tsx:

"use client";

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

export function WebsiteTracking({ children }: { children: ReactNode }) {
  return (
    <QuotientProvider
      clientOptions={{ apiKey: "pk_replace_with_your_public_key" }}
    >
      {children}
    </QuotientProvider>
  );
}

Then add it to your root layout so it remains mounted across page changes:

import { WebsiteTracking } from "./quotient-provider";

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body>
        <WebsiteTracking>{children}</WebsiteTracking>
      </body>
    </html>
  );
}

If your Next.js site uses the Pages Router, wrap the page component with QuotientProvider in pages/_app.tsx, just as you would at the root of any other React application.

How Page Views Are Tracked

Each installation method records the current page as soon as the pixel starts. It also watches browser navigation, including the history changes used by React Router and other single-page applications.

Initialize Quotient only once. Do not send a separate page-view event unless you have disabled automatic tracking, or each visit may be counted twice.

Check the Installation

Deploy or run the site from a domain listed in the key's allowed origins. Then visit the site and move between a few pages.

To confirm that the pixel is sending data:

Open your browser's developer tools and select Network.
Reload the page.
Search the requests for analytics/web.
Select the request and confirm that its status is 200.

If the request returns 403, the domain is probably missing from the key's allowed origins, or the key does not have the Analytics: write permission. If there is no request, make sure the code runs in the browser and that the key begins with pk_.

If your site uses a Content Security Policy, allow connections to https://www.getquotient.ai. Static HTML sites that load the CDN bundle must also allow scripts from https://unpkg.com.

The pixel stores device and session identifiers in the visitor's browser. Your privacy notice and consent setup should cover this tracking. If you require consent before loading analytics, initialize Quotient only after the visitor accepts analytics tracking.

To record your own conversion events after setup, see Custom Events. For the complete API reference, see the JavaScript analytics API.