=== Marsad Download Tracker ===
Contributors: marsadgrouplabs
Tags: download, tracking, analytics, leads, email
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 2.4.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Secure file delivery, lead capture, privacy controls, and detailed download analytics for WordPress.

== Description ==

Marsad Download Tracker creates a tracked link for each downloadable file. It can deliver public or email-gated files, record download activity, and show privacy-aware reports in the WordPress dashboard.

Main features:

* Manage multiple downloadable files and choose files from the Media Library.
* Deliver files through protected, expiring links with version history.
* Optionally require an email address and job role before delivery.
* Record all, unique, and repeat downloads using a configurable time window.
* Inspect unique-download details, including product, location, device, source, and date.
* Filter dashboard reports by product, country, and date.
* Review countries, cities, devices, browsers, referrers, UTM values, and conversions.
* Manage collected leads, marketing-consent status, tags, notes, and deletion requests.
* Configure SMTP and send a test message to a chosen email address.
* Edit and preview the HTML download-email subject and body.
* Export download events and leads to CSV, and export a PDF summary.
* Download a full JSON backup before permanently erasing plugin data.
* Use WordPress personal-data export and erasure tools.
* Optionally connect confirmed marketing opt-ins to Brevo, Mailchimp, or a webhook.
* Optionally look up approximate country and city data. This is disabled by default.

For setup, privacy, integrations, backups, and troubleshooting, see `DOCUMENTATION.txt` in the plugin folder.

== Installation ==

1. In WordPress, open Plugins > Add New Plugin > Upload Plugin.
2. Upload the plugin ZIP and activate Marsad Download Tracker.
3. Open Marsad Downloads > Files.
4. Add a downloadable file and copy its generated tracking link.
5. Add the tracking link to a button, post, page, email, or campaign.
6. Review activity under Marsad Downloads > Dashboard.
7. Review Marsad Downloads > Settings and Delivery & Email before going live.

== Frequently Asked Questions ==

= Does the plugin send data to an external service by default? =

No. Approximate-location lookup is disabled by default, and Brevo, Mailchimp, webhook, and custom SMTP connections are inactive until an administrator configures them.

= How are unique downloads counted? =

The plugin checks the same product, IP address, and, when available, email address inside the configured repeat window. The event remains in the log, but repeat activity is not counted as unique.

= Can I delete all plugin data? =

Yes. Open Marsad Downloads > Delivery & Email > Data. The plugin requires the current administrator to download a fresh JSON backup before the permanent-erasure controls are unlocked.

= Does uninstalling remove data? =

Only when the Uninstall cleanup option is enabled. Otherwise, uninstalling keeps plugin tables and settings so they can be recovered after reinstalling.

= Can I edit the download email? =

Yes. The subject and safe HTML body are editable under Delivery & Email. The screen lists the supported placeholders and shows a preview of the saved template.

== External Services ==

This plugin does not load executable code, JavaScript, CSS, fonts, or tracking pixels from third-party servers. The following optional server-to-server connections are used only when an administrator enables or configures them.

= IPWhois / ipwho.is =

Purpose: approximate country and city lookup for download analytics.

Data sent: the downloader's IP address.

When sent: after a download request, only when Approximate location has been enabled by an administrator. This option is disabled by default.

Service: https://ipwho.is/
Documentation: https://ipwhois.io/documentation
Privacy: https://ipwhois.io/privacy
Terms: https://ipwhois.io/terms

= Brevo =

Purpose: add a confirmed marketing contact to administrator-selected Brevo lists.

Data sent: the confirmed email address, job role, optional custom role, and configured list IDs.

When sent: only after an administrator saves a Brevo API key and the visitor has explicitly opted in to marketing. If double opt-in is enabled, synchronization occurs only after confirmation.

Service: https://www.brevo.com/
Privacy: https://www.brevo.com/legal/privacypolicy/
Terms: https://www.brevo.com/legal/termsofuse/

= Mailchimp =

Purpose: add or update a confirmed marketing contact in an administrator-selected Mailchimp audience.

Data sent: the confirmed email address, job role, audience ID, and the administrator-configured server prefix.

When sent: only after an administrator saves Mailchimp credentials and the visitor has explicitly opted in to marketing. If double opt-in is enabled, synchronization occurs only after confirmation.

Service: https://mailchimp.com/
Privacy: https://mailchimp.com/legal/privacy/
Terms: https://mailchimp.com/legal/terms/
API policy: https://mailchimp.com/legal/api_use/

= Administrator-configured webhook =

Purpose: notify an endpoint chosen by the site administrator when a marketing lead is confirmed.

Data sent: event name, confirmed email address, job role, product ID, and event time.

When sent: only when an administrator saves a webhook URL and a visitor has explicitly confirmed marketing consent. The endpoint and its privacy terms are controlled by the site administrator.

= Administrator-configured SMTP server =

Purpose: send download, confirmation, test, and notification emails through the mail server selected by the site administrator.

Data sent: recipient address, email subject and body, and normal SMTP envelope information.

When sent: only when custom SMTP is enabled. The server and its privacy terms are controlled by the site administrator. When custom SMTP is disabled, WordPress uses its normal mail transport.

== Privacy ==

Depending on configuration, this plugin may store email address, job role, marketing-consent status, IP address, requested product, date and time, device, browser, operating system, user agent, referrer, UTM values, and approximate country or city.

Administrators should:

* Update the site's Privacy Policy using the suggested text added by this plugin under WordPress privacy settings.
* Enable approximate-location lookup only after reviewing the disclosure and IPWhois terms.
* Configure a suitable retention period.
* Send marketing only to people who explicitly opted in.
* Review the privacy terms for every configured SMTP, email-marketing, or webhook provider.
* Use WordPress personal-data export and erasure tools when responding to data requests.

== Source Code ==

All PHP, JavaScript, and CSS used by the plugin is included in the distributed package in human-readable form. The plugin ships no minified or compiled assets and requires no build step. See `SOURCE.txt` for the complete source-file list and attribution for the Natural Earth/world-atlas map data embedded in `assets/v2-admin.js`.

== Support ==

After the plugin is listed, use its support forum on WordPress.org for questions and reproducible bug reports. Include the WordPress version, PHP version, plugin version, and steps to reproduce. Do not post passwords, API keys, personal data, or private download links.

== Changelog ==

= 2.4.0 =
* Replaced the legacy short prefix with the unique `marsdotr_` prefix across declarations, stored data, hooks, screens, and assets.
* Added an automatic migration that preserves existing plugin tables, settings, and scheduled tasks.
* Moved protected-file storage to a dedicated directory beneath the active WordPress uploads directory and added safe legacy-file migration.
* Replaced direct PHP style output with properly enqueued public CSS and WordPress inline-style handling for the configurable accent.
* Expanded nonce, capability, request-sanitization, and protected-path checks across administrative and public actions.
* Included readable map data and complete source and licensing documentation for all JavaScript and CSS assets.

= 2.3.0 =
* Added complete end-user documentation and WordPress.org-ready metadata.
* Added the required WordPress and PHP version headers to the main plugin file.
* Documented all optional external services, the data sent, and when each request occurs.
* Changed approximate-location lookup to disabled by default for new installs and settings resets.
* Replaced generic plugin-site metadata with directory-safe plugin headers.
* Replaced developer branding on the public download gate with the site name.
* Hardened administrator-configured webhook requests against unsafe destinations.
* Updated licensing and privacy documentation for directory review.

= 2.2.0 =
* Redesigned Delivery & Email settings with clearer cards and responsive controls.
* Added editable email templates, preview, and test-recipient selection.
* Added a required JSON backup step before full plugin-data erasure.
* Added clickable unique-download detail reports.
* Renamed Analytics to Dashboard and updated the menu icon.
* Fixed world-map seam artifacts, excessive height, and dashboard scaling.

= 2.1.2 =
* Routed Countries report queries through prepared-query helpers.

= 2.1.1 =
* Hardened analytics queries and streamed export responses.
* Corrected world-map projection and marker alignment.

= 2.1.0 =
* Moved protected-file operations to the WordPress filesystem API.
* Added country and city drill-down reports.

= 2.0.0 =
* Added secure email gates, lead management, SMTP, integrations, privacy tools, and expanded analytics.

= 1.0.0 =
* Initial release.
