Autograph Pixel

Autograph Pixel is a tracking library that provides capabilities similar to the Facebook Pixel. It logs user actions, sends back the user's IP address, and other relevant information that we can use to track fandom across websites.

Architecture

The Autograph Pixel system consists of two main parts: a client-side JavaScript library that tracks user actions and sends them to a server, and a server-side application that receives these events and stores them in a MongoDB database.

Client-side

The client-side library is implemented in JavaScript and is designed to be included in web pages using a <script> tag. It tracks various user actions, such as page views, button clicks, and user engagement over time. It also collects additional information about the user, such as their IP address, device information, browser language, and timezone.

The library uses cookies to store a unique identifier for each user. This allows us to track multiple events from the same user over time, even if they leave and return to the website.

The library supports two modes of operation:

1. Semi-Anonymous pixel tracking: In this mode, the library generates a random ID for each user and does not collect any additional identifying information. This is the default mode of operation.

2. Cooperative user pixel tracking: In this mode, the website can include a unique user ID in a URL parameter when loading the library. This allows the website to provide a consistent ID for each user, which can be useful if the user is logged in and the website wants to track actions per user across multiple sessions or devices.

Server-side

The server-side application is implemented in Node.js and uses Express as the web framework. It exposes a single endpoint (/events) that receives events from the client-side library and stores them in a MongoDB database.

Each event is stored as a document in the MongoDB database, with fields for the event type, description, timestamp, user ID, and additional user information.

The server-side application is designed to be stateless and horizontally scalable. It does not maintain any state between requests, and you can run multiple instances of the application behind a load balancer to handle higher loads.

Installation

1. Clone this repository:

git clone https://github.com/Autograph-Core/pixel.git

2. Navigate to the project directory:

cd pixel

3. Install the dependencies:

npm install

Usage

Client-side

Include the pixel.js file in your HTML files using a <script> tag:

<script src="path/to/pixel.js"></script>

We'll be publishing the library to NPM soon, so presumably this src will use unpkg or something similar.

Then, initialize the AutographPixel:

<script>
  window.AutographPixel = new AutographPixel();
</script>

Server-side

To start the server, run:

npm start

The server will start on port 3000. You can use ngrok to expose the server to the internet:

ngrok http 3000

We plan to put this on vercel and frequently use https://autograph-identity.ngrok.io/ as the server URL. Let Josh know if you'd like to test.

Testing

To run the tests, use:

npm test

We currently don't have any tests.

Building

To build a minified version of the client-side code, run:

npm run build

This will create a pixel.min.js file in the project directory.