=== Payamava CTA Analytics ===
Contributors: payamava
Tags: analytics, cta, click tracking, reports
Requires at least: 6.4
Tested up to: 6.8
Requires PHP: 7.4
Stable tag: 1.5.2
License: GPLv2 or later

Lightweight CTA click tracking with configurable CSS selectors, durable browser queue,
daily aggregated counters, page and destination reports, CSV export, and secure reset.

== Installation ==

1. Upload the plugin folder to /wp-content/plugins/.
2. Activate Payamava CTA Analytics.
3. Open the "آمار CTA" menu in WordPress admin.
4. Review the default tracking rules and add any custom CSS selectors.
5. Clear full-page cache after changing tracking rules on a cached website.

== Privacy ==

The plugin does not store IP addresses, cookies, user IDs, or user agents. Reports are
aggregated by date, CTA, click page, optional destination, referring page and visit entry.
Referrer URLs contain origin and path only, without credentials, query or fragment.
The current tab's entry referrer is stored in sessionStorage, expiring after 30 minutes
without a tracked page load or click. A new external referral starts a new visit.
If sessionStorage is unavailable, attribution is limited to the current page.
Browsers may omit referrers or expose only the external origin: these visits are
reported as direct/unknown when no referrer is supplied. Historical data and old
queued events are marked unknown, never retroactively attributed.

== Campaign attribution ==

Add utm_source, utm_medium, utm_campaign, utm_content and/or utm_term to landing
URLs. Example: /?utm_source=instagram&utm_medium=paid_social&utm_campaign=autumn&utm_content=story_a
These five parameters (up to 190 characters each) are stored with click aggregates.
The latest tagged landing wins within the current tab. Untagged internal navigation
preserves the campaign for 30 minutes without a tracked page load/click. An external
untagged referral or expired visit clears the previous campaign. No cross-tab or
cross-device attribution is attempted. Blocked sessionStorage limits it to the page.
The campaign table ranks up to 100 tagged combinations by clicks and follows the
date/CTA filters. CSV includes all five fields and all rows, including untagged rows.
Historical clicks cannot be retrospectively attributed. Clear page/asset caches.
Telephone link clicks do not confirm dialer approval, connection, or answered calls.

== Manual initial counts ==

Each CTA has an editable manual initial count and attribution date under Manage CTAs.
Saving replaces the baseline, never increments it. Zero removes the baseline.
Only non-negative integers up to 1,000,000,000 and dates no later than today are accepted.
Report widgets, including summary cards and CTA totals, show tracked clicks only.
Manual baselines remain visible in Manage CTAs and are exported as labeled CSV rows
only when their attribution date falls inside the selected range.
CSV identifies each row with record_type=tracked or manual and a manual update timestamp.
Deleting a CTA or resetting all statistics also clears its manual baseline.

== Central updates ==

Version 1.5.0 introduces the Payamava updater. Install this version manually once
on existing sites and keep the plugin active to receive future native update notices.
Metadata is retrieved over HTTPS from updates.payamava.net (cached for 5 minutes).
The update request does not send analytics records or visitor information.
Use Dashboard > Updates > Check again to refresh the release metadata.
Automatic updates follow the site's WordPress settings and are not forced.
The server hosts public update.json and versioned releases/ds-cta-analytics-VERSION.zip.

== Changelog ==

= 1.5.2 =
* Refresh metadata before the core update check.
* Populate native update notices independently of WordPress.org availability and core cache timing.
* Preserve unrelated plugin updates and avoid frontend update requests.

= 1.5.0 =
* Central updates from updates.payamava.net using the native WordPress updater.
* Plugin information dialog, versioned release validation and cached metadata.


= 1.4.0 =
* Dedicated Campaigns tab with Persian date/CTA filters and usage guide.
* Campaign CSV excludes untagged and manual counts; main report CSV is unchanged.

= 1.3.1 =
* Exclude manual baselines from all report widgets; retain management and labeled CSV export.

= 1.3.0 =
* Per-CTA manual baseline with attribution date, explicit labels and update timestamp.
* Separate tracked/manual breakdowns and tagged CSV rows; real tracking is unchanged.


= 1.2.0 =
* Persistent tab-level UTM attribution, campaign ranking and CSV dimensions.
* Existing counters and event deduplication are preserved.
* Exported text is protected against spreadsheet formula interpretation.


= 1.1.1 =
* Internal/external referring pages and tab visit entry attribution.
* Source reports respect date and CTA filters; CSV includes both source dimensions.
* Existing counters are preserved during automatic database upgrade.
* Clear full-page and asset caches after upgrading to load the new tracker.
