page-events-analysis

Files (1)

• SKILL.md

SKILL.md (first lines)

# Page Events Analysis

Analyze page views and events for specific URL patterns, then cross-reference them to calculate usage rates. This answers questions like "how many people used feature X on pages Y".

## Gather Parameters

Ask the user for (or infer from context):

1. **Site ID** - the Matomo site to query
2. **URL pattern** - regex to filter pages (e.g. `guidelines-epc|guidelines-pct`)
3. **Event filter** - the event name or action to cross-reference (e.g. `Toggle Show Modifications`)
4. **Date range** - start and end dates (default: last 30 days from today)
5. **Device filter** (optional) - `desktop`, `mobile`, `smartphone`, `tablet`, or `phablet` if the user asks about a specific device slice (e.g. "how many mobile users toggled X")

## Execution Steps

### 1. Fetch page views

Call `matomo_search_pages` with:
- `siteId`: the site ID
- `urlPattern`: the URL pattern
- `period`: `range` when the user gave start/end dates, otherwise `month` for long windows and `day` for short ones
- `date`: comma-separated start,end range when `period=range` (e.g. `2026-02-01,2026-02-28`)
- `device`: pass through if the user asked for a device slice

Sum up `nb_visits` (unique visitors) and `nb_hits` (page views) across all matching pages. Keep monthly totals if the range spans multiple months.

### 2. Fetch event counts

Call `matomo_search_events` with:
- `siteId`: the site ID
- `filterPattern`: the event filter
- `dimension`: `name` (to see specific event values like on/off toggles)
- `period`, `date`, `device`: same as above

Sum up `nb_events` across all matching events. Keep monthly totals.

### 3. Calculate usage rate

```
usage_rate = (total_events / total_page_views) * 100
```

If both on/off event variants exist (e.g. "Toggle Show Modifications On" and "Toggle Show Modifications Off"), report them separately and combined.

### 4. Present findings

Provide a summary with:

**Key figures:**
- Total page views (hits) and unique visitors
- Total events (broken down by variant if applicable)
- Overall usage rate %

**Monthly breakdown table:**

| Month | Page Views | Unique Visitors | Events | Usage Rate |
|-------|-----------|-----------------|--------|------------|
| ...   | ...       | ...             | ...    | ...        |
| **Total** | **...** | **...** | **...** | **...%** |

**Observations:**
- Note any trends (increasing/decreasing adoption)
- Flag months with unusual spikes or drops
- If usage rate is very low or very high, call it out

## Fallback when segments return zero

If a `device`-filtered call comes back with all-zero metrics while the same
query without `device` returns normal numbers, the Matomo server is refusing
to aggregate the segment for this API token (it lacks `process_new_segment`
or the segment isn't pre-archived). Do not claim "no mobile traffic" — that's
almost never the real answer.

Try these in order:

1. **Switch to `matomo_count_visits_by_segment`.** It uses the Live API
   under the hood (no archiving required) and accepts the same `device`
   shortcut plus an optional `urlPattern` for the page filter. For per-URL
   mobile slicing:
   `{siteId, period, date, device: "mobile", urlPattern: "bulletin/download"}`
   Returns `{visits, byDevice, byCountryTop10, actionHitsOnPattern}`.
   For per-language breakdown, call `matomo_get_last_visits` with the same
   segment and iterate `actionDetails[].url` client-side (strip ISO lang
   prefix with regex `/^/([a-z]{2})/...`).
2. **Check `matomo_list_segments`** to find saved segments on the instance.
   Any segment with `auto_archive=1` is pre-archived and will always return
   real numbers when you reference its `definition` string in `segment`.
3. **Open the Matomo UI in a logged-in browser session** as a last resort.
4. **Longer-term fix**: ask the Matomo admin to grant
   `process_new_segment` on the token or pre-archive common segments.

From lucaspretti/matomo-mcp-client, MIT.

More from lucaspretti/matomo-mcp-client