Overview

The Cookie3 Analytics plugin is a versatile tool designed to simplify the process of adding tracking to websites for clients of Cookie3. Whether you're working with a traditional codebase or a modern Single Page Application (SPA) built with frameworks like Next.js, React, or Nuxt, this library offers the flexibility and ease of integration you need.

Features

Cross-Framework Compatibility: Works seamlessly with various web development frameworks and libraries, including Next.js, React, Nuxt, and more.
Universal Tracking: Provides a unified API for tracking user interactions, events, and other metrics across different types of web applications.
Customizable Tracking: Easily configure tracking parameters and events to suit your specific analytics requirements.
Asynchronous Loading: Ensures minimal impact on your website's performance by loading tracking scripts asynchronously.
Real-Time Data: Access real-time analytics data through the Cookie3 dashboard for informed decision-making.

Installation

You can install the Cookie3 Analytics plugin via npm or yarn:

npm install @cookie3/analytics

yarn add @cookie3/analytics

Getting Started

Notice: The Cookie3 Analytics plugin requires a valid Cookie3 siteId to work. If you don't have a Cookie3 account, you can sign up for a free account here.

Registering a website in Cookie3

Note: skip this step if you already have a website registered in Cookie3.

Before you can start tracking your website's analytics, you'll need to register your website in Cookie3. To do this, follow these steps:

Log in to your Cookie3 account.
Go to the /data-sources page.
Click on the Integrate Website button.
On the next page, click on the "Add a new website" button in the top right corner.
Enter your website's URL and name, then click on the "Add site" button.
Copy the site ID from the script snippet and save it for later.

You can now start tracking your website's analytics using the Cookie3 Analytics plugin.

Getting the site id of an existing website

If you already have a website registered in Cookie3, you can get its site ID by following these steps:

On the /data-sources page, click on the Integrate Website button. You should see your website listed on the page. Click on the "View script" button next to your website's name. You should see a script snippet with your website's site ID. Copy the site ID and save it for later.

Usage

1. Import the Library

Import the library into your project to begin using it:

import { cookie3Analytics } from "@cookie3/analytics";

2. Initialize the Library

Initialize the library with your siteId from Cookie3 key:

const analytics = cookie3Analytics(options);

The options parameter is an object that accepts the following properties:

Property	Type	Description
`siteId`	`number`	Your Cookie3 site ID.
`disabled`	`boolean`	Whether to disable tracking. Defaults to `false`.
`autoDetectWalletAddresses`	`boolean`	Whether to automatically detect wallet addresses in the page and track them. Defaults to `true`.
`autoDetectWalletExtensions`	`boolean`	Whether to automatically detect wallet extensions in the page and track them. Defaults to `true`.
`heartBeat`	`active: boolean; seconds?: number;`	Whether to enable heart beat tracking and the interval in seconds. This option enables more accurate visit time tracking. The default interval is set to 10 seconds. Defaults to `undefined`.
`linkTracking`	`boolean`	Whether to enable link tracking. Defaults to `true`.
`disableCookies`	`boolean`	Whether to disable cookies. Defaults to `false`.
`staging`	`boolean`	Whether to use the staging environment. Defaults to `false`. For internal use only.

3. Track Page Views

Important information

When using the Cookie3 Analytics plugin all tracked pageviews are registered programmatically, so you need to call the trackPageView method on every page load.

Start tracking page views by calling the library's trackPageView method:

Tracking pageviews

analytics.trackPageView();

By default, the trackPageView method will automatically track the current page's URL and title. You can also pass in custom parameters to override the default values:

analytics.trackPageView({
  documentTitle: "Custom title",
  href: "https://example.com",
});

Note: The trackPageView method should be called on every page load.

4. Track Events

Start tracking events and user interactions by calling the library's tracking methods:

analytics.trackEvent({
  category: "Call to action",
  action: "Click",
  value: 200,
});

Note: The value parameter is optional and is used to track the financial value of the event. For example, if you're tracking a purchase event, you can pass in the total amount of the purchase as the value parameter.

How it works

The library sends a request to the Cookie3 API to track pageviews, events and user interactions. The API then processes the request and stores the data in the Cookie3 database. You can then access the data through the Cookie3 dashboard.

Whitelisting the Cookie3 API domain

The Cookie3 Analytics plugin sends requests to the Cookie3 API domain. If you're using a Content Security Policy (CSP) on your website, you'll need to whitelist the Cookie3 API domain to allow the plugin to work properly. The Cookie3 API domain is webanalytics.cookie3.co.

Usage with Next.js / React

Create a context provider to make the instance available in your React app:

import { type Cookie3Analytics } from "@cookie3/analytics";
import { createContext, useContext } from "react";

export interface ProviderProps {
  children?: React.ReactNode;
  value: Cookie3Analytics;
}

const Cookie3Context = createContext<Cookie3Analytics | undefined>(undefined);

export const Cookie3Provider = ({ children, value }: ProviderProps) => {
  return (
    <Cookie3Context.Provider value={value}>{children}</Cookie3Context.Provider>
  );
};

export const useCookie3 = () => {
  const context = useContext(Cookie3Context);

  return context;
};

Initialize the instance in your _app.tsx file:

import type { AppProps } from "next/app";

import { UserOptions, cookie3Analytics } from "@cookie3/analytics";
import { Cookie3Provider } from "@/hooks/useCookie3Analytics";

const config: UserOptions = {
  siteId: YOUR_SITE_ID,
};

const analytics = cookie3Analytics(config);

export default function App({ Component, pageProps }: AppProps) {
  return (
    <Cookie3Provider value={analytics}>
      <Component {...pageProps} />
    </Cookie3Provider>
  );
}

Track events in your components:

const cookie3 = useCookie3();

useEffect(() => {
  cookie3?.trackPageView();
}, []);

@cookie3/analytics