Shadow Track

Make Matomo/Piwik analytics undetectable by ad blockers through parameter encryption and endpoint obfuscation.

How it works

Shadow Track protects your Matomo analytics from being blocked by:

1. Endpoint Obfuscation: Renames tracking endpoints to innocent-looking names
2. Parameter Encryption: Encrypts all tracking parameters into a single obfuscated parameter
3. Pattern Breaking: Removes recognizable Matomo/Piwik parameter patterns that ad blockers detect

Instead of sending:

POST /matomo.php?idsite=1&rec=1&action_name=Home&url=https://example.com

Shadow Track sends:

POST /waschbaerenparadies?d=a7x9k2FibGUiLCJjb2RlX25hbWUiOiJIb21lIn0=k9x7a

Installation

npm install -g /root/shadow-track

Or run directly:

cd /root/shadow-track
npm install
./cli.js --help

Usage

Quick Setup (Recommended)

Run the complete setup with one command:

shadow-track full-setup \
  --domain analytics.example.com \
  --path /var/www/matomo \
  --js-endpoint tracker.js \
  --tracking-endpoint analytics \
  --secret your-secret-key-2024

Manual Setup

1. Generate Nginx Configuration

shadow-track nginx \
  --domain analytics.example.com \
  --path /var/www/matomo \
  --js-endpoint tracker.js \
  --tracking-endpoint analytics \
  --output /etc/nginx/sites-available/matomo-shadow.conf

2. Patch matomo.js

shadow-track patch-js \
  --input /var/www/matomo/matomo.js \
  --tracking-endpoint analytics \
  --secret your-secret-key-2024

3. Patch matomo.php

shadow-track patch-php \
  --input /var/www/matomo/matomo.php \
  --secret your-secret-key-2024

4. Enable and reload services

# Enable nginx config
ln -s /etc/nginx/sites-available/matomo-shadow.conf /etc/nginx/sites-enabled/

# Test and reload nginx
nginx -t
systemctl reload nginx

# Restart PHP-FPM to clear opcache
systemctl restart php8.2-fpm

Configuration Options

Endpoint Names

• --js-endpoint: Name for the JavaScript file (default: loewenzahntiger.js)
• --tracking-endpoint: Name for the tracking endpoint (default: waschbaerenparadies)

Choose innocent-looking names that don't contain words like:

• track, analytics, matomo, piwik, stats, metrics, telemetry

Secret Key

• --secret: Encryption key (default: shadow-track-secret-2024)

⚠️ Important: Use the same secret key for both JS and PHP patching!

Update Tracking Code

After setup, update your website's tracking code:

<!-- Before -->
<script src="https://analytics.example.com/matomo.js"></script>

<!-- After -->
<script src="https://analytics.example.com/tracker.js"></script>

Testing

1. Check if the obfuscated JS loads:

curl https://analytics.example.com/tracker.js

2. Test tracking endpoint:

curl -X POST "https://analytics.example.com/analytics?d=test"

3. Monitor nginx logs:

tail -f /var/log/nginx/analytics.example.com.matomo.access.log

Troubleshooting

404 Errors

• Check nginx configuration is loaded: nginx -T | grep shadow
• Verify file paths in nginx config
• Check PHP-FPM socket path

Tracking not working

• Clear browser cache
• Check browser console for errors
• Verify same secret key used for JS and PHP
• Restart PHP-FPM: systemctl restart php8.2-fpm

Still blocked by ad blockers

• Try different endpoint names
• Avoid patterns like sequential numbers or common words
• Consider using subdomains instead of paths

Security Notes

• Keep your secret key private
• Use HTTPS only
• Regularly rotate endpoint names if they get detected
• Monitor access logs for suspicious activity

License

MIT