📊 NanoTrack: 1x1 Nano-Size Spy-Pixel Analytics

🌟 Introduction

NanoTrack redefines web analytics with its minimalistic yet powerful approach to user activity tracking. Designed for performance-conscious developers and marketers, it ensures efficient data collection without the need for heavy JavaScript libraries, aligning with modern standards of ethical web practices.

🎯 Use Cases

Email Campaign Tracking: Measure open rates and engagement.
Website Visitor Analytics: Gain insights without impacting load times.
Marketing Campaign Monitoring: Unique IDs for tailored tracking.

✅ Core Features

NanoTrack offers a fresh take on web analytics, focusing on simplicity and minimalism. Here's a snapshot of its evolving features:

Feature	Description
Ultra-Lightweight Tracking Method	NanoTrack employs a 1-pixel GIF for analytics, ensuring an almost invisible impact on your site’s performance and user experience.
User-Friendly Design	The tool is crafted for straightforward setup and ease of use, making web analytics approachable for users of all skill levels.
Storage Flexibility	NanoTrack offers MongoDB for scalability or flat files for simplicity. MongoDB is included in the default docker-compose setup but can be disabled for external connections. Choose the storage option that suits your needs.
No JavaScript Dependency	Operating without heavy JavaScript, NanoTrack offers a nimble alternative that contributes to quicker page loads and smoother site interactions.
Emerging Real-Time Dashboard	The real-time dashboard, in its beta form, provides instant insights in a simple and uncluttered format, tailored for quick analysis.
Introductory Click Tracking Feature	The new click tracking with redirection functionality is a step towards more dynamic analytics, enabling basic user journey tracking.
Multi-Campaign Capability	NanoTrack simplifies handling multiple campaigns with ease, requiring only unique campaign IDs, making it versatile for various tracking needs.
Streamlined URL Generator	The inclusion of a URL generator tool aids in effortlessly creating precise tracking tags, eliminating the typical complexities of setup.
Custom Parameter Tracking Ability	This feature allows the customization of tracking parameters, offering a level of detail and specificity for targeted analytics.
Dedicated Dashboards for Campaigns	Separate dashboards for individual campaigns provide more nuanced insights, enhancing campaign-specific analysis.
Ethical Approach to Data	From the outset, NanoTrack has been committed to ethical data practices, placing a high priority on user privacy and responsible data handling.
Tracking Transparency Page	In line with NanoTrack's commitment to ethical tracking, the unique Tracking Transparency Page is triggered when users directly access a tracking pixel URL.

As NanoTrack continues to evolve in its beta phase, it represents a commitment to simplicity and ethical practices in web analytics. This project, rich with potential, invites users to not only leverage its current capabilities but also to contribute to its ongoing development, shaping a tool that embodies both efficiency and ethical responsibility.

📸 Screenshots

🌄 Background

NanoTrack was born out of a simple yet profound idea: to shed light on the extensive data exchanged with every interaction on the internet. My initial inspiration was to create a project that would inform users and the internet at large about the staggering amount of data they unknowingly release with every call to a server. It was an attempt to raise awareness about data privacy expectations online, regardless of how diligently we try to block trackers.

What started as an inspirational idea quickly evolved into something much more significant. In just a matter of three days, version 1.0 of NanoTrack went from a conceptual spark to a full-fledged self-hosting analytic tool. The realization of how valuable this tool could be for various use cases was a driving force behind its rapid development.

🚧 Early-Release Beta Status

Current Phase

NanoTrack is currently in an early-release beta phase. This is an exciting stage in the project's lifecycle where users have the unique opportunity to shape its development. During this phase, I am actively refining features, squashing bugs, and enhancing the overall functionality of the tool.

Expect Continuous Improvements

Ongoing Enhancements: Users can expect a continuous rollout of improvements and new features. My development roadmap is packed with exciting updates that I am eager to share.
Active Development: The beta phase is characterized by active development. This means regular updates and changes as I iterate based on user feedback and my own innovation.

Your Feedback Matters

Community Input: I highly value user feedback during this phase. Your experiences, suggestions, and criticisms are crucial in steering NanoTrack towards a tool that truly meets the needs of its users.
Join the Development Journey: By using NanoTrack now, you're not just adopting a tool; you're joining a journey of development and innovation. I encourage users to report any issues they encounter and share their thoughts on potential features.

A Note of Caution

Expect Some Instability: As with any beta software, users should be prepared for some instability and imperfections. I recommend not relying on NanoTrack as the sole analytics tool for mission-critical applications during this beta phase.

I'm excited to have you aboard during this pivotal phase of NanoTrack's development and look forward to growing together!

⚠️ Important Note for Safari Users

Safari, by default, disables cross-site tracking. This privacy feature significantly impacts how referring URLs are captured and recorded by NanoTrack. Specifically, when cross-site tracking is disabled, NanoTrack will only be able to capture the host domain of the referrer, not the full referring URL.

Implications for Tracking:

Limited Referrer Data: Users visiting from Safari with the default settings will result in NanoTrack capturing limited referrer information, potentially impacting detailed analytics and insights.
Campaign Strategy Adjustment: If capturing the full referrer URL is critical for your analytics, you may need to consider creating separate campaigns for each page you wish to track. This approach ensures that you can still obtain detailed referrer data without relying on the full URL being passed by the browser.

📖 Table of Contents

📊 NanoTrack: 1x1 Nano-Size Spy-Pixel Analytics

🚀 Getting Started

Self-Hosting

If you prefer self-hosting, follow these steps:

Deploy NanoTrack using Docker Compose. Create a docker-compose.yml file with the following content:

version: '3'

services:
  nanotrack:
    image: nanotrack/nanotrack:latest
    ports:
      - "3000:80" # Use whatever port you would like
    environment:
      - NODE_ENV=production
      - MONGO_URI=mongodb://nanotrack:nanotrack@mongodb:27017/nanotrack  # Use the hostname "mongodb" if using the mongodb in this compose
      - PORT=80
      - DB_TYPE=mongodb
      # - DB_TYPE=flatfile #only recommended for testing
      - USERNAME=nanotrack
      - PASSWORD=admin
    restart: unless-stopped

  mongodb:
    image: mongo
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: rootpassword
      MONGO_INITDB_DATABASE: nanotrack
    volumes:
      - mongodb_data:/data/db
      - ./utils/init-mongo.js:/docker-entrypoint-initdb.d/init-mongo.js:ro

volumes:
  mongodb_data:  # Define a volume to persist MongoDB data

Run docker-compose up to start the service.
Embed the tracking pixel: http://[your_server_ip]/track/action.gif?campaignID=your-campaign-id

🌟 Usage Examples

NanoTrack allows for the tracking of various user interactions by embedding customizable tracking URLs. You can track standard metrics like page views or email opens, and also include unlimited additional parameters in the URL query to capture specific user actions or preferences.

Web Tracking

Track user interactions on specific web pages by embedding a tracking URL. For example, to track a pageview on dillonbaird.io (the specific page is parsed from the referrer automatically), use the following URL:

http://[your_server_ip]/track/pageview.gif?campaignID=dillonbaird.io

Email Tracking

Track email opens by embedding a tracking URL in the email. For instance, to track an email open for an offer letter sent to email@example.com, use:

http://[your_server_ip]/track/email-open:email@example.com.gif?campaignID=email-offerletter

Event Tracking

Monitor specific user actions or events on your application. For instance, to track user registrations, you can embed a URL like this:

http://[your_server_ip]/track/user-registration.gif?campaignID=my-awesome-app

This example would track whenever a user accesses the registration page, helping you understand user interest in signing up for your service.

Click Tracking

Track user clicks that lead them to external links. Embed a URL like the following to log click events and then redirect the user to the intended destination:

<a href="http://[your_server_ip]/track/click?campaignID=dillonbaird.io&redirectURL=https://dillonbaird.io">DillonBaird.io</a>

This feature is particularly useful for tracking outbound link clicks, providing insights into how users interact with external links on your site.

Advanced Parameter Tracking

NanoTrack also supports tracking of additional custom parameters. You can append any number of custom parameters to your tracking URL to gather more detailed insights. For instance, to track how far users scroll on a blog post and whether they use dark mode, you might use:

http://[your_server_ip]/track/pageview.gif?campaignID=dillonbaird.io&scroll-depth=70%&dark-mode=true

This method allows for a highly detailed understanding of user behavior and preferences, making your analytics more robust and actionable.

🕹 Data Collected

User Agent: Browser and device information.
IP Address (optional): Geolocation data.
Page Path and Timestamps: User journey.
Referrer Data: Traffic sources.
Custom Campaign IDs: For specific tracking.

⚙️ Configuration Options

NanoTrack offers a range of configurable options to suit your specific tracking requirements and preferences. You can set these options in an .env file or as environment variables.

📝 Environment Configuration

Here are some of the key configuration options available:

Storage System Type
- DB_TYPE: Choose the type of storage system (mongodb or flatfile) for data persistence.
```
DB_TYPE=mongodb
```
Dashboard Authentication
- USERNAME: Set a username for dashboard access.
- PASSWORD: Set a password for dashboard access.
```
USERNAME=admin
PASSWORD=securepassword
```
Disabling Specific Tracking Information
- DISABLE_IP_TRACKING: Disable collecting IP addresses.
- DISABLE_USER_AGENT_TRACKING: Disable collecting user agent data.
```
DISABLE_IP_TRACKING=true
DISABLE_USER_AGENT_TRACKING=false
```
Other Configurations
- Additional options can be added here as your project evolves.

🛠️ Setting Up the `.env` File

Create a .env file in your project root and set your desired configuration options:

DB_TYPE=mongodb
USERNAME=admin
PASSWORD=securepassword
DISABLE_IP_TRACKING=true
DISABLE_USER_AGENT_TRACKING=false

These settings give you the flexibility to customize NanoTrack's functionality and privacy settings according to your preferences and requirements.

📄 Responsible and Ethical Use

By using NanoTrack, you commit to:

Adherence to Laws: Complying with all relevant data privacy laws in your region.
Respect User Privacy: Honoring user privacy and data removal requests.
Ethical Usage: Using NanoTrack responsibly and not for malicious activities.

🔒 Enhancing Security with HTTPS

In today's digital landscape, securing your tracking data is paramount. We highly recommend using HTTPS to encrypt the data transmitted between your users and NanoTrack. This not only protects user privacy but also strengthens the integrity of the data collected.

Why Use HTTPS?

Data Security: Prevents unauthorized interception of tracking data.
User Trust: Increases trust in your service, as users are becoming more security-conscious.
SEO Benefits: Search engines, like Google, favor HTTPS-enabled websites, potentially improving your site's ranking.

One of the simplest ways to implement HTTPS is by using Cloudflare. Cloudflare provides a free and easy-to-setup SSL/TLS certificate, ensuring that your tracking data is securely transmitted over the internet.

⚠️ Limitations of Pixel Tracking

While NanoTrack provides a streamlined and efficient approach to web analytics, it's important for users to understand the inherent limitations of pixel tracking technology. This understanding will help in determining the best use cases for NanoTrack and how it complements other analytics tools.

Caching Challenges

Impact on Repeat Tracking: Caching mechanisms in browsers and networks can impact the ability to track repeat visits accurately. When a tracking pixel is cached, subsequent requests may not reach the server, leading to undercounting of user interactions.
NanoTrack's Mitigation Efforts: Although NanoTrack implements strategies to minimize caching effects (such as cache-busting techniques), it's crucial to acknowledge that these methods can't completely eliminate the impact of caching on analytics.

Comparison with Standard Analytics

Not a Full Replacement: Given the limitations posed by caching and the nature of pixel tracking, NanoTrack is not a 1-to-1 replacement for standard, JavaScript-heavy analytics solutions.
Solid Alternative with Right Implementation: However, with the right implementation and understanding of its limitations, NanoTrack can serve as a solid alternative or complement to traditional analytics tools, especially in scenarios where lightweight and unobtrusive tracking is desired.

Ideal Use Cases

Email Open Tracking: Perfect for environments where embedding JavaScript is not feasible, such as tracking email opens.
Basic Pageview Tracking: Well-suited for simple pageview tracking, where detailed user interactions are not the primary focus.
Complement to Standard Analytics: Can be used alongside more comprehensive analytics solutions to provide additional insights without adding significant load to your web pages.

Understanding these limitations is key to leveraging NanoTrack effectively. It’s designed to offer a balance between performance and tracking capabilities, catering to specific scenarios where a lightweight and ethical approach to analytics is preferred.

📏 NanoTrack vs. Google Analytics: A Comparison in Efficiency and Size

NanoTrack offers a lightweight alternative to Google Analytics, focusing on minimal impact on website performance. Here's a detailed comparison highlighting the efficiency and size differences:

Tracking Pixel vs. JavaScript File Size

NanoTrack's 1-Pixel GIF: The 1-pixel GIF used by NanoTrack is approximately 35 bytes in size. This ultra-small footprint ensures minimal impact on page load times.
Google Analytics JavaScript File: Google Analytics typically requires loading a JavaScript file. The size of this file can be around 45 KB for Universal Analytics (analytics.js) and about 17 KB for Google Analytics 4 (gtag.js). This is significantly larger compared to NanoTrack's pixel.

Network Request Size

NanoTrack's Data Transfer: A typical tracking request from NanoTrack (including the pixel and URL parameters) may total around a few hundred bytes, depending on the number of additional parameters used.
Google Analytics API Call: A Google Analytics tracking request can be larger, often exceeding several kilobytes, as it transmits more data back to Google's servers.

Load Time and Performance Impact

NanoTrack: Due to its minuscule size, NanoTrack's tracking pixel can be loaded almost instantaneously, even on slow connections, resulting in negligible impact on website performance.
Google Analytics: The load time for Google Analytics' script varies, but it can add noticeable delays, especially on mobile devices or in regions with slower internet speeds. The impact is more pronounced when considering that these scripts also execute significant code on the client's device.

Practical Implications

Use-Case for NanoTrack: NanoTrack is ideal for simple, efficient tracking requirements, such as page views or email opens, where the goal is to minimize the impact on page load and user experience.
Comprehensive Analysis with Google Analytics: For in-depth user behavior analytics and advanced features like event tracking, funnel analysis, and user segmentation, Google Analytics is more suitable, though with a higher resource cost.

In essence, while Google Analytics provides comprehensive analytics capabilities, NanoTrack stands out for its minimalistic approach, prioritizing performance and speed, especially critical for sites where user experience and page load times are paramount.

🤝 Contributing to NanoTrack

I welcome contributions that enhance NanoTrack's efficiency and ethics. See Contribution Guidelines.

👥 Contributors

_{Dillon M. Baird}
_🌎

📄 License

NanoTrack is under the MIT License.

🛣 Roadmap

Additional Users / Roles
Campaign Blacklist
IP Blacklist
Dashboard Revamp
Campaign Dashboard Expansion
Reports
Data Export
Notifications
Digest Email
User Segmentation
Event Funnel Analysis
Custom Dashboards
Machine Learning Insights
A/B Testing
Integration with 3rd Party Tools
More on our Roadmap.

📜 Changelog

Stay updated with our Changelog.

🛠 Troubleshooting

Common issues and their solutions in our Troubleshooting Guide.

Attributions and Licensing

NanoTrack uses a number of open source projects to work properly. Here's a list of them along with their licenses:

Dependencies

cookie-parser - Simplified HTTP request cookie parsing. License: MIT
dotenv - Loads environment variables from a .env file. License: BSD-2-Clause
express - Fast, unopinionated, minimalist web framework for Node.js. License: MIT
express-minify-html - Express middleware to minify HTML responses. License: MIT
express-useragent - Express middleware for detecting user agents. License: MIT
fs - Filesystem utilities for Node.js (Note: This is a core module in Node.js and doesn't have its own license separate from Node.js).
geoip-lite - A light weight native JavaScript implementation of GeoIP API from MaxMind. License: MIT
mongoose - Elegant MongoDB object modeling for Node.js. License: MIT
nocache - Middleware to disable client-side caching. License: MIT
node-fetch - A light-weight module that brings window.fetch to Node.js. License: MIT
ws - A Node.js WebSocket library. License: MIT

Development Dependencies

@babel/core, @babel/cli, @babel/preset-env, etc. - Babel is a compiler for writing next generation JavaScript. License: MIT
@types/... - TypeScript definitions for various packages. These are community provided and typically MIT licensed.
babel-loader, copy-webpack-plugin, html-loader, terser-webpack-plugin, etc. - These packages are part of the Webpack ecosystem for bundling and optimizing assets and scripts. Licenses vary, mostly MIT.
jest - Delightful JavaScript Testing. License: MIT
nodemon - Simple monitor script for use during development of a Node.js app. License: MIT
ts-node - TypeScript execution and REPL for Node.js. License: MIT
webpack, webpack-cli, webpack-node-externals, webpack-obfuscator - Webpack is a static module bundler for modern JavaScript applications. License: MIT

This project is licensed under the MIT License - see the LICENSE file for details.

DillonBaird/NanoTrack