The Proxima Analytics JavaScript Client

The Proxima Analytics JavaScript Client is a convenient solution for incorporating Proxima Analytics into your front-end projects. It streamlines the process of integrating Proxima Analytics by providing a simple, easy-to-use interface for loading the script and sending events. With this library, you can focus on your application's functionality, without having to worry about the details of managing the Proxima Analytics script and event tracking. Additionally, it is written in TypeScript, providing type safety and making it easy to integrate with your existing TypeScript projects. Last but not least, it's lightweight and easy to install via the npm registry.

Installation

You can easily integrate the Proxima Analytics JavaScript Client into your project by installing it using popular package managers such as npm, yarn, or pnpm.

npm install @prxm/client

Another option for integrating the Proxima Analytics JavaScript Client into your project is by using the SkyPack CDN to directly load the client into your project.

import * as client from 'https://cdn.skypack.dev/@prxm/client';

Usage

Once you have completed the setup, you will need to initialize the Proxima Analytics JavaScript Client by providing it with the unique website identifier found in your Proxima Analytics dashboard.

import * as client from '@prxm/client';

client.init({
    site: 'YOUR_WEBSITE_IDENTIFIER',
});

The library will inject the Proxima Analytics script into the page and initialize the Proxima Analytics tracking script and start tracking pageviews. All the options that are available for the Proxima Analytics script can be passed to the init function as an object.

import * as client from '@prxm/client';
const options = {
    site: 'YOUR_WEBSITE_IDENTIFIER', // required
    manual: true, // disable automatic pageview tracking
    dnt: true, // respect do not track 
    spa: 'hash', // enable single page application mode with hash based routing
    url: 'http://example.com', // specify the url of the API
    hostname: 'foo.bar', // specify the hostname of the pageview
};

client.init(options);

If you're using a proxy, you also have the option to specify a custom source for the Proxima Analytics script.

import * as client from '@prxm/client';
client.init({
    src: '/proxima.js',
    site: 'YOUR_WEBSITE_IDENTIFIER',
});

Tracking Pageviews

The client is designed to automatically track pageviews when the `init` function is called, but if you want more granular control you can also use the `track` function to manually track pageviews.

import * as client from '@prxm/client';
client.track();

The URL and the referrer of the pageview can be specified by passing them as arguments to the `track` function.

import * as client from '@prxm/client';
client.track({
    url: 'http://example.com',
    referrer: 'http://foo.com',
});

Tracking Events

The client not only provides an easy way for tracking pageviews, it also offers a simple interface for tracking custom events. By using the `event` function, you can track specific user actions, such as button clicks, form submissions, or other interactions on your website.

import * as client from '@prxm/client';
client.event('event', { param1: 1234, param2: 'foo' });

The `event` function takes two arguments, the first one is the name of the event, and the second one is an object containing the event metadata.