Infinity Metrics BETA

Documentation

Contents

Automated Installation

This method provides a streamlined installation process with automatic updates, ideal for Ubuntu Server users.

1. Get your license

Purchase your Infinity Metrics license from our pricing section to get started.

2. InfinityMetrics Installer and Updater

The installer automatically configures SSL certificates and uses Caddy as a proxy. For more details, see the Infinity Metrics Installer on GitHub.

Install with a single command

Run the installer and follow its instructions. 

curl -fsSL https://getinfinitymetrics.com/install -o install.sh && sudo bash install.sh

Self-Managed Installation

This method is for users who prefer manual setup or are using a non-Ubuntu Linux distribution, deploying Infinity Metrics via a Docker image.

1. Get your license

Purchase your Infinity Metrics license from our pricing section to get started.

2. Docker Installation

  • Infinity Metrics consists of a single Docker image that automatically manages its internal database, making it compatible with any Linux distribution.
  • It is actively tested on Ubuntu Server (20.04 LTS or newer), but theoretically, it can be used on any Linux distribution.
  • Note: We recommend putting Infinity Metrics behind a proxy for enhanced security and performance. With this method, all updates are in your hands.

Required Environment Variables

The following environment variables are required to run the Infinity Metrics Docker image:

  • INFINITY_METRICS_LOG_LEVEL: Logging level (e.g., debug)
  • INFINITY_METRICS_APP_PORT: Port for the app (e.g., 8080)
  • INFINITY_METRICS_LICENSE_KEY: Your license key obtained in step 1
  • INFINITY_METRICS_DOMAIN: Your domain (e.g., your-domain.com)
  • INFINITY_METRICS_PRIVATE_KEY: Private key for internal functioning of the app. (32 random characters)

Docker Run Command

Use the following command to run the Infinity Metrics Docker image. Replace the placeholder values with your own: 

docker run -d \
  --name infinity-metrics \
  -v /path/to/storage:/app/storage \
  -v /path/to/logs:/app/logs \
  -e INFINITY_METRICS_LOG_LEVEL=debug \
  -e INFINITY_METRICS_APP_PORT=8080 \
  -e INFINITY_METRICS_LICENSE_KEY=your-license-key \
  -e INFINITY_METRICS_DOMAIN=your-domain.com \
  -e INFINITY_METRICS_PRIVATE_KEY=your-private-key \
  --restart unless-stopped \
  infinitymetrics/app:latest

Integrating the Tracking Script

Copy the lightweight tracking script below to your website(s) to start collecting data. This step applies to both installation methods. 

<script defer src="https://your-domain.com/api/v1/sdk.js"></script>

Accessing the Dashboard

Once installed, access the analytics dashboard at https://your-domain.com/. This step applies to both installation methods.

Administrative Operations

Manage your Infinity Metrics installation with the following administrative commands.

Password Reset

To reset or change the admin password, run the following command with sudo privileges: 

sudo infinity-metrics change-admin-password

Forced Updates

To manually force an update of Infinity Metrics, run the following command with sudo privileges: 

sudo infinity-metrics update

Server Requirements

Infinity Metrics is designed to run efficiently with minimal server resources. You can get started with very modest specifications.

Minimum Requirements

  • CPU: 1 vCPU/Core
  • RAM: 512MB (sufficient to get started)
  • Storage: 10GB SSD

Network Requirements

  • Inbound: Ports 80 (HTTP) and 443 (HTTPS) must be open for Let's Encrypt certificate setup, verification, and normal operations
  • Outbound: General internet access required for Let's Encrypt certificate renewal and OpenAI API communication
  • SSL Certificate: Automatically provisioned during installation with Let's Encrypt (for automated installer) or configured manually

SDK Usage

Our lightweight JavaScript SDK makes it easy to capture analytics data from your websites.

Including the SDK

Add the following script tag to the section of your website. Replace your-domain.com with the domain where you installed Infinity Metrics. 

<script defer src="https://your-domain.com/api/v1/sdk.js"></script>

For optimal data collection, place the script as early as possible in the of your HTML document.

SDK Configuration

The Infinity Metrics SDK comes with sensible defaults, but you can customize its behavior by modifying the configuration options. 

// Modify configuration before the SDK loads
window.InfinityMetrics = window.InfinityMetrics || {};
window.InfinityMetrics.config = {
	respectDoNotTrack: true,            // Honor browser's Do Not Track setting
	autoInstrumentButtons: true,        // Auto-track button clicks
	autoSendPageViews: true,            // Automatically send page views
	debug: false                        // Enable debug logging
};

Configuration Options

Option Default Description
respectDoNotTrack true Honor the browser's Do Not Track setting
autoInstrumentButtons true Automatically track button clicks
autoSendPageViews true Automatically send page views
debug false Enable debug logging to console

Automated Tracking

By default, Infinity Metrics automatically tracks the following without any additional code:

Page Views

Every page load is automatically tracked.

Single-Page Application (SPA) Navigation

The SDK automatically detects navigation changes in SPAs by monitoring history state and popstate events, treating them as new page views. It supports React, Vue, and Angular.

Button Clicks

When auto-instrumentation is enabled (default), clicks on <button> elements, <input type="button">, <input type="submit">, and any element with role="button" are automatically tracked.

Button events are named using the pattern: click:button:sanitized_text:button_id. Here's how it's constructed:

  • sanitized_text: Derived from the button's visible text. The system prioritizes textContent, then value, then title. This text is then sanitized: converted to lowercase, spaces replaced with underscores, non-alphanumeric characters (except underscores) removed, and truncated to 50 characters. If no text is found or sanitization results in an empty string, it defaults to "unnamed_button".
  • button_id: The id attribute of the button. If the button has no ID, this defaults to "noid".

For example, <button id="myBtn">Submit</button> would generate an event named click:button:submit:mybtn.

Note: If an <a> tag is styled like a button but includes the data-infinity-event-name attribute, it will be handled by Link Event Tracking (see below) to avoid duplication, and this general button tracking will defer.

Link Event Tracking

Track clicks on specific links declaratively by adding data- attributes to your <a> tags. This is useful for CTAs or important navigational elements. This method takes priority over general button click tracking for <a> tags to prevent double counting.

  • Activation: Add data-infinity-event-name to the link.
  • Event Naming: Value of data-infinity-event-name is sanitized (lowercase, underscores, alphanumeric, 50 chars).
  • Automatic Metadata: href (link URL) and text (link text).
  • Custom Metadata: Use attributes like data-infinity-metadata-yourkey="value".

Example:


<a href="/features"
   data-infinity-event-name="Clicked Features Link From Docs"
   data-infinity-metadata-location="Docs Page Section"
   data-infinity-metadata-custom_id="feat_123">
   Explore Our Features
</a>

Offline Support

The SDK automatically detects when the user is offline and stores events locally for a reasonable period of time. When the connection is restored, it will send the stored events to the server.

Manual Tracking

For custom events, user actions, or additional data collection, you can use our JavaScript API.

Custom Events

Track specific user interactions or milestones not covered by automated tracking using the sendCustomEvent function.

Syntax: InfinityMetrics.sendCustomEvent(eventName, metadata)

  • eventName (string): A unique name for your event (e.g., "trial_started", "file_downloaded").
  • metadata (object): An object containing any additional dynamic information relevant to the event. You can include any key-value pairs, for example, { plan: "premium", fileName: "report.pdf" }. This data will be available in your analytics.

Example:

InfinityMetrics.sendCustomEvent("video_played", { videoTitle: "Product Demo", durationWatched: "60s" });

Manual Page Views

SPA frameworks could fail to automatically trigger page views changes, you can do it manually like this: 

window.InfinityMetrics.sendPageView()