Metrics and analytics
How post engagement numbers are collected, stored as a time series, and used by campaigns.
The base module stores platform metrics as single, overwritten values on the post. This module adds a metric snapshot table that appends a dated row every time the sync runs, turning a point-in-time number into a trend line.
What is measured#
The same four groups are used everywhere: on posts, in campaigns, and in snapshots.
| Group | Fields included |
|---|---|
| Views | Telegram views, Facebook video views, Instagram impressions, X impressions |
| Likes | Facebook likes, Instagram likes, X likes |
| Comments | Telegram comments, Facebook comments, Instagram comments, X replies |
| Shares | X reposts, X quote-posts, Instagram saves |
Engagement = likes + comments + shares.
Engagement Rate (%) = engagement ÷ views × 100. Zero views gives a rate of 0.
On a post#
The Post Metrics tab on a post form shows the running totals and the history table. The history is append-only: each row is one snapshot at a point in time, with two delta columns — New Views and New Engagement — that record the change since the previous row. A negative delta is real data (platforms occasionally revise counts downward) and is kept as-is.
On a campaign#
The campaign form rolls the published posts' metrics up into campaign-level totals. Total Views, Total Engagement and Engagement Rate are computed from live post data, so they update when the sync runs without any extra action. Engagement vs Target (%) compares Total Engagement against Target Engagement.
How metrics are collected#
Manual sync#
Social Media → Configuration → Accounts → an account → Sync Metrics (or the platform-specific refresh button) pulls fresh numbers from the platform API for all posts on that account.
Automated sync#
Two scheduled actions ship with the module. Both are inactive by default because they call the live platform APIs, which require real credentials and a connected account.
| Action | Interval | What it does |
|---|---|---|
| Social: Auto-Sync Metrics and Comments | Hourly | Pulls engagement figures for all published posts. |
| Social: Update Telegram Post Views | Hourly | Refreshes Telegram-specific view counts. A post-by-post replacement for the base module's broken action. |
Enable them once real accounts are connected: Settings → Technical → Scheduled Actions, open the action, tick Active, save.
Metric snapshots#
A third action, Social: Snapshot Post Metrics, runs daily and appends one row to the history table for every post published in the last 90 days that has non-zero metrics. Posts older than 90 days are skipped — their engagement is effectively flat, and the extra rows provide no signal worth the table growth.
X / Twitter token auto-refresh#
X access tokens expire in approximately two hours. The Social: Refresh X Access Tokens hourly action (active by default) calls _refresh_access_token on every connected X account before the token expires. This prevents the publish failure you would otherwise get mid-campaign when a token runs out between two scheduled posts.
If the refresh fails for one account (a revoked app, a changed password), the failure is logged as a warning and the loop continues with the next account. No other account's token is affected.
Viewing the time series#
On a post form, open the Post Metrics tab and switch to Graph view. Use the Capture Date grouping for a day-by-day line. The New Views and New Engagement delta columns let you plot incremental reach rather than cumulative, which is more useful for comparing posts of different ages.
Troubleshooting#
| Symptom | Likely cause |
|---|---|
| Metrics are all zero | The sync actions are inactive, or credentials are not connected. Enable the actions and check connection health. |
| History has only one row | The daily snapshot action is inactive. Enable Social: Snapshot Post Metrics. |
| X metrics stop updating | The X account token may have expired or been revoked. Check Connection Health and reconnect the account if needed. |
| Engagement rate is 0% despite engagement | Views are zero. Check whether the platform reports impressions in the metric fields or under a different name on the account's page. |