Hanzo Analytics

Analytics is a simple, fast, privacy-focused alternative to Google Analytics.

---

🚀 Getting Started

A detailed getting started guide can be found at hanzo.ai/docs.

---

🛡️ Anti-Ad-Blocker Technology

Analytics employs a sophisticated, multi-layered approach to prevent ad blockers from disrupting data collection. This ensures that you get the most accurate and complete picture of your website's traffic.

How It Works

1. Encrypted Tracker Script: The tracker script is not served as plain JavaScript. Instead, it's encrypted and delivered as a binary file (tracker.bin). This makes it impossible for ad blockers to analyze the script's contents and block it based on known patterns.

2. WASM-Based Decryption: A small, efficient WebAssembly module (decrypt.wasm) is used to decrypt the tracker script in the browser's memory. This decryption logic is compiled into a compact and efficient binary format, making it difficult to reverse-engineer.

3. Dynamic Loading: A lightweight loader script is responsible for fetching the encrypted tracker and the WASM decryptor. It then uses the WASM module to decrypt and execute the tracker. This means that the full tracker code is never exposed in a way that's easy to inspect or block.

4. Obfuscated API: The tracker's API is obfuscated to avoid detection. Instead of using a common and easily blockable function name like track(), it uses a generic and non-descript API. This makes it much harder for ad blockers to identify and block the tracker based on its global footprint.

5. Encrypted Payloads: All data sent from the tracker to the server is encrypted. This prevents ad blockers from inspecting the request payloads and blocking them based on their contents.

This multi-layered approach makes it significantly harder for ad blockers and other privacy tools to detect and block the tracker, while still providing a simple and consistent way for you to trigger events.

---

🛠 Installing from Source

Requirements

• A server with Node.js version 18.18 or newer
• A database. Analytics supports MariaDB (minimum v10.5), MySQL (minimum v8.0) and PostgreSQL (minimum v12.14) databases.

Get the Source Code and Install Packages

git clone https://github.com/hanzoai/analytics.git
cd analytics
npm install

Configure Analytics

Create an .env file with the following:

DATABASE_URL=connection-url

The connection URL format:

postgresql://username:mypassword@localhost:5432/mydb
mysql://username:mypassword@localhost:3306/mydb

Build the Application

npm run build

The build step will create tables in your database if you are installing for the first time. It will also create a login user with username admin and password analytics.

Start the Application

npm run start

By default, this will launch the application on http://localhost:3000. You will need to either proxy requests from your web server or change the port to serve the application directly.

---

🐳 Installing with Docker

To build the Analytics container and start up a Postgres database, run:

docker compose up -d

Alternatively, to pull just the Analytics Docker image with PostgreSQL support:

docker pull docker.hanzo.ai/hanzoai/analytics:postgresql-latest

Or with MySQL support:

docker pull docker.hanzo.ai/hanzoai/analytics:mysql-latest

---

🔄 Getting Updates

To get the latest features, simply do a pull, install any new dependencies, and rebuild:

git pull
npm install
npm run build

To update the Docker image, simply pull the new images and rebuild:

docker compose pull
docker compose up --force-recreate -d

---

🛟 Support