Analytics Plugin

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.

Walkthrough

1. Access the Analytics Plugin:

   1. Visit app.cookie3.co/data-sources and then click on the Website tab.

   2. In the table displaying your websites, locate the row corresponding to your website.

      1. If you haven't added your website yet, click on the Add Website button in the top-right corner to add your website.

      2. The form will ask you to enter your website's URL and a name for your website. Once you have entered the information, click on the Add Website button to add your website.

   3. After adding your website, you will be redirected to a dedicated page for your website. Choose the Analytics Plugin option from the tabs below the website name.

   4. Click on the Available on NPM button to access the Analytics Plugin on NPM.

   5. Follow the instructions on NPM to install the Analytics Plugin on your website.

   6. Once you have installed the Analytics Plugin, you can follow the instructions in the Analytics Plugin documentation to learn how to use the Analytics Plugin.

Installation

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

npm install @cookie3/analytics

or

yarn add @cookie3/analytics

Integrating 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:

1. Log in to your Cookie3 account.

2. Go to the /data-sources page.

3. Click on the Integrate Website button.

4. On the next page, click on the "Add a new website" button in the top right corner.

5. Enter your website's URL and name, then click on the "Add site" button.

6. 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

1. 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;
};

2. 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>
  );
}

3. Track events in your components:

const cookie3 = useCookie3();

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