WP FileTrace

Simple tracked downloads and file analytics for WordPress.

WP FileTrace gives you an easy way to see how many times files are downloaded from your WordPress site.

It works with files already in the WordPress Media Library, files hosted somewhere else, and tracked links that you want to use in emails, newsletters, documents, QR codes, or other websites.

If you just need to answer something like:

"How many people downloaded this PDF?"

WP FileTrace is built for that.

It does not try to replace the WordPress Media Library or turn your site into a complicated download-management system.

---

What Can WP FileTrace Do?

WP FileTrace can:

• Track downloads of PDFs, ZIP files, documents, images, and other files.
• Track files from the WordPress Media Library.
• Track files hosted at another URL.
• Create a simple download button using a WordPress shortcode.
• Create a separate tracked URL for use in emails or anywhere outside your site.
• Keep separate counts for website button clicks and external links.
• Show the latest download date.
• Export your tracked-file totals to CSV.
• Optionally send download events to Google Analytics / gtag.
• Customize the small handoff page shown before a download begins.
• Help migrate basic downloads from Simple Download Monitor.
• Update itself through the normal WordPress plugin updater using GitHub Releases.

WP FileTrace also includes safeguards intended to reduce false download counts and unnecessary WordPress load caused by automated link scanners, email-security systems, previews, and similar non-human requests.

---

Quick Start

1. Install WP FileTrace

Install and activate WP FileTrace like a normal WordPress plugin.

If installing manually:

1. Download the plugin from the GitHub Releases page.
2. In WordPress, go to Plugins → Add New Plugin → Upload Plugin.
3. Upload the ZIP.
4. Activate WP FileTrace.

After activation, look for WP FileTrace in the WordPress admin menu.

---

2. Choose a File to Track

Open:

WP Admin → WP FileTrace → Tracked Files

You can either:

• choose a file from your WordPress Media Library, or
• paste the URL of a file hosted somewhere else.

Give the tracker a useful title if needed, then click:

Generate Tracking Link

WP FileTrace will create a tracker for that file.

---

Put a Tracked Download Button on a WordPress Page

The easiest way to use WP FileTrace on your website is with its shortcode.

After creating a tracker, use the Copy Shortcode button in the Tracked Files table.

A Media Library file looks like:

[wft media="123"]

An externally hosted file can look like:

[wft url="https://example.com/files/report.pdf"]

You can also change the button text:

[wft media="123" text="Download Report"]

Paste the shortcode into a WordPress page, post, custom post type, shortcode block, or other area that supports WordPress shortcodes.

WP FileTrace will display a download button and count downloads made through it.

---

Track a Download Link in an Email

You do not need to use the shortcode if the link is going somewhere outside WordPress.

This is useful for:

• email newsletters
• marketing emails
• PDFs
• QR codes
• social posts
• client portals
• other websites
• plain text messages

In WP FileTrace → Tracked Files, find your file and click Copy Link.

Use that URL instead of linking directly to the PDF or file.

For example, instead of sending someone directly to:

https://example.com/wp-content/uploads/report.pdf

you send them the WP FileTrace tracking link.

WP FileTrace handles the tracking and then starts the real file download.

---

Website Downloads vs. Email Downloads

WP FileTrace keeps these traffic sources separate.

Each tracker can show:

• Total Downloads
• Shortcode Downloads
• External Downloads

A download made using a [wft] button is counted as a Shortcode download.

A shareable tracking link used in an email, document, QR code, or elsewhere is counted as an External download.

The totals still stay together under the same tracked file.

---

What Happens When Someone Clicks a Download?

A visitor briefly passes through a lightweight WP FileTrace download page.

The page:

1. handles the tracking process,
2. starts the requested file,
3. provides a manual download link if the automatic download does not begin, and
4. gives the visitor a way back to your site.

When the visitor came from a WordPress page, WP FileTrace can return them to that page.

For external links such as email links, it can instead return them to your site's home page.

The built-in page is intentionally simple and can be customized under the Download Page tab.

---

Email Link Scanners and Automated Requests

Modern email systems often inspect links before the person receiving the email ever clicks them.

Security products, spam filters, link previews, bots, and automated scanners can sometimes hit the same URL many times — especially when a tracked link is sent to a large mailing list.

WP FileTrace is designed to make this less troublesome.

It ignores requests such as HEAD checks and known preview/prefetch traffic where possible. Newer versions also use a lightweight browser handoff for tracked links so the initial request does not need to perform the full WordPress tracking/download process.

The actual tracking step is moved into the browser flow.

This helps:

• reduce unnecessary PHP/database work from automated link checks,
• protect the site during bursts of email scanner traffic, and
• reduce false download counts caused by non-human requests.

No tracking system can identify every possible bot or security scanner, but WP FileTrace tries to keep ordinary automated link checking separate from a real browser download.

---

View Your Download Counts

Go to:

WP FileTrace → Tracked Files

The table lets you view and manage your tracked files.

You can:

• sort tracked files,
• view download totals,
• see shortcode vs. external downloads,
• see when the tracker was created,
• see the latest download time,
• copy tracking links,
• copy shortcodes,
• edit trackers,
• delete trackers,
• bulk-delete selected trackers, and
• export the data to CSV.

The admin interface uses AJAX for most normal actions, so sorting, pagination, editing, saving, and other common tasks can happen without repeatedly reloading the entire WordPress admin page.

---

Export Download Data

Use the CSV Export option in the Tracked Files area to download a spreadsheet-friendly copy of your tracker totals.

This is useful if you need to send download numbers to a client, build a report, or keep an offline record.

---

Google Analytics / gtag Support

Google Analytics integration is completely optional.

You do not need Google Analytics to use WP FileTrace.

If you already have Google Analytics installed through your theme, Google Tag Manager, another plugin, or another method, you generally do not need to add the global site tag again.

Open:

WP FileTrace → Analytics

You can optionally provide a custom gtag event such as:

gtag('event', 'file_download', {
    'download_source': 'WP FileTrace'
});

WP FileTrace can dynamically add information about the download to the event, including:

• tracker ID
• actual filename
• download source
• originating WordPress page ID
• originating WordPress page title

Example parameter names:

download_id
download_name
download_source
via_page_id
via_page_title

This makes it possible to create more detailed reports inside Google Analytics without hard-coding individual file information into every event.

---

Customize the Download Page

Open:

WP FileTrace → Download Page

The default download page is intentionally minimal.

You can customize it with:

• a logo or icon from the WordPress Media Library,
• an option to show or hide the WordPress site name,
• custom HTML, and
• custom CSS.

If you leave the custom HTML and CSS empty, WP FileTrace simply uses its built-in layout.

You can safely use Preview Saved Page to test your design.

Preview mode does not:

• increase the download counter,
• start the real file download, or
• fire the configured download analytics event.

---

Download Page Variables

Custom HTML can use these variables:

{{download_name}}
{{file_name}}
{{download_url}}
{{download_source}}
{{via_page_id}}
{{via_page_title}}
{{via_page_url}}
{{return_url}}
{{site_name}}
{{site_url}}
{{logo_url}}

For example:

<h1>Your download is starting...</h1>

<p>
    Downloading <strong>{{download_name}}</strong>
</p>

<p>
    <a href="{{download_url}}">Click here if your download does not start.</a>
</p>

{{download_url}} uses WP FileTrace's retry route, so clicking the fallback link does not count the same download a second time.

---

Moving From Simple Download Monitor

WP FileTrace includes an optional Simple Download Monitor Migration tool.

This feature is currently considered Beta and is disabled by default.

Enable it under:

WP FileTrace → Settings

Once enabled, a Migration tab will appear.

The migration tool can find standard Simple Download Monitor shortcodes such as:

[sdm_download id="123"]

and preview their equivalent WP FileTrace trackers and [wft] shortcodes.

Run a Dry Run First

Use:

Scan Site / Dry Run

before changing anything.

The dry run does not modify your pages.

WP FileTrace will identify items that appear safe to migrate and flag more complicated situations for manual review.

It intentionally avoids blindly replacing things such as:

• password-protected downloads,
• unpublished downloads,
• unsupported shortcode behavior,
• certain Terms & Conditions or reCAPTCHA configurations,
• page-builder/post-meta content that cannot be safely rewritten automatically.

Use Apply Safe Replacements only after reviewing the results.

WP FileTrace keeps rollback copies of changed post_content so the content changes can be restored while you verify the migration.

Historical Simple Download Monitor download totals are not currently imported.

---

Updating WP FileTrace

WP FileTrace can check this GitHub repository for new normal releases.

Updates can then appear through the regular WordPress plugin update system.

You can also open:

WP FileTrace → Settings

to see:

• your installed version,
• the latest available GitHub version,
• GitHub connection status,
• the last release check, and
• a Check for Updates button.

The manual check bypasses WP FileTrace's normal release cache and asks GitHub for the latest release again.

---

Requirements

WP FileTrace currently requires:

• WordPress 6.4 or newer
• PHP 8.0 or newer

---

Developer Notes

Everything below is more useful if you are integrating with WP FileTrace, maintaining the plugin, or just want to know how it works internally.

---

Tracking Sources

WP FileTrace currently identifies tracked downloads using two main source values:

shortcode
external

shortcode represents downloads initiated through the [wft] shortcode.

external represents the shareable tracking URL, including links used in emails or other external locations.

---

Server-Side Download Hook

After a download is successfully tracked, WP FileTrace fires:

do_action(
    'wft_download_tracked',
    $download_id,
    $file_url,
    $source,
    $tracker
);

This can be used by another plugin or custom theme code to respond to successfully recorded downloads.

---

Analytics Event Filter

The browser analytics context can be modified using:

apply_filters(
    'wft_analytics_event_context',
    $context,
    $tracker,
    $source
);

The context can include information such as:

• tracker ID,
• file name,
• destination URL,
• download source,
• originating content ID/title, and
• configured analytics parameter mappings.

---

Data Storage

WP FileTrace uses dedicated WordPress database tables:

{prefix}wft_downloads
{prefix}wft_download_events

The first stores tracker information and summary data.

The second stores individual anonymous download events for reporting and future analytics use.

Plugin configuration such as Analytics and Download Page settings is stored using normal WordPress options.

WP FileTrace does not intentionally store visitor IP addresses or other personally identifying visitor information as part of its normal download tracking.

---

Deleting the Plugin

Deleting WP FileTrace through the normal WordPress Plugins screen runs the included uninstall process.

This permanently removes WP FileTrace data, including:

• tracker records,
• download-event records,
• Analytics settings,
• Download Page settings,
• migration state and rollback metadata,
• plugin database/version options, and
• supported legacy WP FileTrace/ADT data.

If you want to keep your download records, export or back up your data before deleting the plugin.

---

GitHub Release Workflow

For maintainers:

1. Update the plugin version.
2. Update changelog.md.
3. Commit and push the release to GitHub.
4. Create a matching GitHub tag such as:

v0.1.14

5. Create a normal GitHub Release from that tag.

Do not publish the updater-target release as a draft or prerelease.

WP FileTrace can use GitHub's automatically generated source ZIP, so a separately uploaded plugin ZIP is not normally required for current releases.

---