# Romiltec Analytics Tracking

A professional WordPress plugin for Matomo analytics integration with automatic Post ID tracking as custom dimensions.

## Description

Romiltec Analytics Tracking provides seamless Matomo analytics integration for WordPress sites. The plugin automatically tracks Post IDs as Custom Dimension 1 on single post pages, allowing you to analyze individual content performance in your Matomo dashboard.

Perfect for publishers, bloggers, and content marketers who want detailed insights into their content performance using self-hosted Matomo analytics.

## Features

- 🎯 **Automatic Post ID Tracking**: Post IDs are automatically tracked as Custom Dimension 1 on single post pages
- 📊 **Matomo Integration**: Full Matomo analytics integration with customizable URL and Site ID
- 📜 **Scroll Depth Tracking**: Automatically tracks user scroll depth at 25%, 50%, 75%, and 100% milestones
- ⏱️ **Time on Page Tracking**: Accurate time measurement with heartbeat timer (tracks active viewing time)
- ⚡ **Performance Optimized**: Lightweight and cache-safe implementation
- 🔧 **Easy Configuration**: Simple admin interface with validation
- 🌐 **Translation Ready**: Full internationalization support
- 🛡️ **Security First**: Input sanitization and capability checks
- 🔄 **No External Dependencies**: Works with your self-hosted Matomo installation

## Installation

### Automatic Installation (Recommended)

1. Go to **Plugins > Add New** in your WordPress admin
2. Search for "Romiltec Analytics Tracking"
3. Click **Install Now** and then **Activate**

### Manual Installation

1. Download the plugin zip file
2. Go to **Plugins > Add New > Upload Plugin**
3. Choose the zip file and click **Install Now**
4. Activate the plugin

### FTP Installation

1. Extract the plugin files
2. Upload the `romiltec-analytics-tracking` folder to `/wp-content/plugins/`
3. Activate the plugin through the **Plugins** menu in WordPress

## Configuration

1. Go to **Settings > Romiltec Analytics**
2. Enter your **Matomo Analytics URL** (e.g., `https://analytics.yoursite.com/`)
3. Enter your **Site ID** from your Matomo dashboard
4. Check **Enable Tracking** to activate
5. Click **Save Changes**

### Setting up Custom Dimension in Matomo

To track Post IDs, you need to configure Custom Dimension 1 in your Matomo installation:

1. Log in to your Matomo dashboard
2. Go to **Administration > Custom Dimensions**
3. Click **Add Custom Dimension**
4. Set **Scope** to "Visit" or "Action"
5. Set **Name** to "Post ID" (or your preferred name)
6. Save the custom dimension

The plugin will automatically send Post IDs to Custom Dimension 1 on all single post pages.

### Viewing Tracked Data in Matomo

The plugin automatically tracks multiple data points:

- **Page Views**: Standard page visit tracking
- **Post IDs**: Available in Custom Dimension 1 reports for single posts
- **Scroll Depth Events**: Go to **Behavior > Events** and look for the "Scroll_depth" category with actions: 25%, 50%, 75%, 100%
- **Time on Page**: Accurate time tracking visible in standard time metrics (uses 15-second heartbeat timer)

## Requirements

- WordPress 5.0 or higher
- PHP 7.4 or higher
- Active Matomo analytics installation (self-hosted or cloud)
- HTTPS recommended for security

## Frequently Asked Questions

### Does this work with Matomo Cloud?

Yes! This plugin works with both self-hosted Matomo and Matomo Cloud installations. Just enter your Matomo URL in the settings.

### Where do I find my Site ID?

Log in to your Matomo dashboard, go to **Administration > Websites > Manage**, and you'll see the Site ID next to your website name.

### What events does the plugin track?

The plugin automatically tracks:
- Page views with Post ID custom dimensions
- Scroll depth events (25%, 50%, 75%, 100%)
- Time spent on page using heartbeat timer

All events are sent to Matomo and visible in the Events reports under the "Scroll_depth" category.

### Is this compatible with caching plugins?

Yes! The tracking code is injected client-side and is fully compatible with all major caching plugins.

## Changelog

See [changelog.txt](changelog.txt) for version history.

## Development

This plugin follows WordPress coding standards and best practices:

- Object-oriented architecture
- Proper sanitization and validation
- Translation-ready strings
- WordPress hooks and filters
- Activation/deactivation/uninstall hooks

## Support

For technical support and inquiries, visit [romiltec.it](https://romiltec.it)

## License

This plugin is licensed under the GPL v2 or later.

---

**Developed by [Romiltec](https://romiltec.it)** - Professional digital solutions for your business.