# Marsad Download Tracker Documentation

Version 2.4.0

Marsad Download Tracker provides tracked and optionally gated file delivery, lead management, privacy controls, and download analytics inside WordPress.

## Requirements

- WordPress 6.2 or later.
- PHP 7.4 or later.
- Pretty permalinks are recommended but not required.
- WordPress must be able to run scheduled events for retention cleanup and delayed integration synchronization.
- Email delivery requires either a working WordPress mail transport or valid custom SMTP settings.

## Installation

1. Open **Plugins > Add New Plugin > Upload Plugin**.
2. Select the Marsad Download Tracker ZIP file.
3. Choose **Install Now**, then **Activate**.
4. Open **Marsad Downloads > Files** and create the first tracked product.
5. Copy the generated tracking URL and use it in a page, post, button, email, or campaign.

The plugin creates its own database tables during activation and registers its download routes. Deactivation keeps data. Uninstall removes data only when **Uninstall cleanup** is enabled. Upgrades from versions earlier than 2.4 automatically migrate the legacy short-prefixed tables and settings to the current `marsdotr_` names.

## Add a downloadable product

1. Open **Marsad Downloads > Files**.
2. Enter a product name and choose a file URL from the Media Library or enter a valid URL.
3. Decide whether the visitor must provide an email address.
4. Configure secure delivery, version label, gate text, optional image, accent color, and abuse controls.
5. Save the product and copy its tracking URL.

When email gating is enabled, the form collects an email address and job role. Marketing consent is a separate optional checkbox and is not required to receive the file.

## Dashboard and reports

Open **Marsad Downloads > Dashboard** to review totals and filter results by product and date. The dashboard includes trends, product comparisons, country activity, devices, browsers, sources, UTM values, and conversion information.

The **Unique downloads** card opens a detailed report showing the downloader email or IP, product, country and city, device, browser, operating system, referrer, and download time. A unique event is determined from the product, IP address, available email address, and the configured repeat window.

Use **Countries** for country rankings and city drill-downs. Use **Leads** to search email records, add tags or notes, export leads, or erase one person's stored data.

## Email delivery and template

Open **Marsad Downloads > Delivery & Email**.

### Default WordPress mail

When custom SMTP is disabled, the plugin calls the standard WordPress `wp_mail()` function. Delivery then depends on the site's existing mail configuration.

### Custom SMTP

1. Enable **Custom SMTP**.
2. Enter the server host, port, encryption, username, password, From address, and From name supplied by the mail provider.
3. Save the settings.
4. Enter a recipient in **Send a test email** and send the saved template.

Secrets are stored encrypted when WordPress authentication salts are available. The plugin never displays a saved secret in plain text.

### Download email template

The subject and safe HTML body can be edited. Save changes before using the preview or test-email form.

Available placeholders:

- `{file_name}`: product or file name.
- `{site_name}`: WordPress site title.
- `{download_button}`: secure download button.
- `{confirm_block}`: optional marketing-confirmation link.
- `{thank_you_block}`: optional thank-you link.
- `{year}`: current year.

The saved body is filtered through WordPress safe-HTML rules. Scripts, unsafe attributes, and unsupported markup are removed.

## Integrations

Brevo, Mailchimp, and the webhook are optional and inactive until an administrator enters credentials or a URL. Only confirmed marketing opt-ins are synchronized.

### Brevo

Enter a Brevo API key and one or more numeric list IDs separated by commas. The plugin sends the confirmed email address, job role, optional custom role, and list IDs to the Brevo Contacts API.

### Mailchimp

Enter the API key, audience ID, and server prefix such as `us21`. The plugin adds or updates the confirmed email and job role in that audience.

### Webhook

Enter an HTTPS endpoint controlled or approved by the site owner. The plugin sends a JSON `lead.confirmed` event containing the confirmed email, job role, product ID, and event time. Requests use WordPress safe HTTP handling to reject unsafe destinations.

Provider privacy and terms links are listed in `readme.txt`. The site owner remains responsible for choosing lawful providers and disclosing each configured processor in the site's Privacy Policy.

## Privacy and geolocation

The plugin can store email, job role, marketing-consent status, IP address, product, date and time, device, browser, operating system, user agent, referrer, UTM values, and approximate location.

Approximate-location lookup is **disabled by default**. If an administrator enables it under **Marsad Downloads > Settings**, the downloader IP address is sent to the ipwho.is API to obtain approximate country and city data. Review the provider privacy policy and terms before enabling this feature.

The plugin adds suggested wording to WordPress privacy-policy tools and registers personal-data exporters and erasers. The site owner should adapt the suggested wording to the site's actual configuration and legal requirements.

## Retention, backup, and erasure

Set the download-log retention period under **Marsad Downloads > Settings**. A value of zero keeps logs indefinitely; otherwise, old download logs are deleted by a daily scheduled event.

To erase all plugin records:

1. Open **Delivery & Email > Data**.
2. Download the fresh JSON backup generated for the current administrator.
3. Return to the settings screen if needed. The erase controls remain unlocked for a limited time.
4. Type the exact confirmation phrase.
5. Optionally choose to reset plugin settings, SMTP, templates, and integrations.
6. Confirm permanent erasure.

The backup contains plugin tables and settings, including encrypted secret values. Store it securely. Full erasure clears database records; it does not delete protected or uploaded file binaries.

Protected copies are stored in the active WordPress uploads directory under `marsad-download-tracker/private`. The plugin adds common Apache and IIS deny rules and serves files through validated, expiring token routes. Version 2.4 migrates referenced protected copies from the former storage directory and updates their database paths only after a successful copy.

## Exports

- Dashboard downloads can be exported as UTF-8 CSV.
- Lead results can be exported as CSV.
- A PDF summary can be generated for reporting.
- WordPress privacy tools can export or erase data for an individual email address.
- The Data screen creates a complete JSON backup before full erasure.

Spreadsheet-formula prefixes are neutralized in CSV output to reduce spreadsheet injection risk.

## Source code

All runtime PHP, JavaScript, and CSS is included in the plugin in human-readable form. No minified or compiled asset is shipped and no build step is required. See `SOURCE.txt` for the source-file list and Natural Earth/world-atlas map-data attribution.

## Troubleshooting

### A tracked URL returns 404

Open **Settings > Permalinks** and save once to refresh rewrite rules. Confirm the product is active and its slug has not been changed in an old link.

### The download email does not arrive

Send a test email from **Delivery & Email**. Check the recipient address, SMTP host, port, encryption, credentials, From address, spam folder, and mail-server logs. A successful WordPress response means the message was accepted for delivery, not that the receiving server placed it in the inbox.

### Country or city is empty

Confirm approximate-location lookup is enabled, the server can make HTTPS requests to `ipwho.is`, and the visitor address is a public IP. Private, reserved, invalid, blocked, or failed lookups intentionally return no location. IP location is approximate.

### An integration does not receive a lead

Confirm the visitor explicitly opted in and, if double opt-in is enabled, completed confirmation. Verify credentials, list or audience values, WordPress scheduled events, and provider logs.

### Counts differ from raw events

All events remain visible, but repeated activity inside the configured repeat window is not counted as unique. Change the window under **Settings** if the business definition differs.

## Support and safe reporting

After publication, use the plugin support forum on WordPress.org. Include reproducible steps, WordPress version, PHP version, and plugin version. Never publish passwords, API keys, private file URLs, backup files, personal data, or full server logs containing secrets.

## License

Marsad Download Tracker is licensed under GPL-2.0-or-later. See `LICENSE.txt`.
