Documentation
Download Metric documentation.
Set it up, add your files and read the numbers.
1
Installation
- Download the Download Metric zip.
- In WordPress go to Plugins > Add New > Upload Plugin, choose the zip and click Install Now.
- Click Activate.
- Open Download Metric in the admin menu to add files and see your stats.
Requires WordPress 5.5 or later and PHP 7.4 or later.
2
Adding files
On the Dashboard tab, use the Files panel:
- Label: the name visitors see, for example “My Plugin Pro”
- File: press Upload New File to upload a file or pick one from the Media Library, or Browse Server Files to pick a file already in your uploads folder. The address box is filled in for you and cannot be typed into
- Version: recorded against every download of this file
- Button text: optional, used by the shortcode when no text is given
- Status: a new file starts as a Draft, and until it is published its link behaves as if the file doesn’t exist. When it is ready, set Status to Published in the File Downloads table and press the tick beside it
Each file then appears in the File Downloads table with its tracked link and shortcode. Click the copy icon inside a field to copy it. Use the pencil and bin icons at the end of a row to edit or delete a file. The table also shows each file’s downloads and, under the red X, the requests for it that were blocked.
3
Shortcode
[sdt_download id="1" text="Download Now"]
| Attribute | What it does | Example |
|---|---|---|
id | The file’s number, shown in the File Downloads table. Required. | id="3" |
text | The link text. If left out, the file’s own button text is used, otherwise “Download”. | text="Get the PDF" |
Shortcode links open the download pop-up on the page. The tracked link on its own (from the File Downloads table) can be used as the address of any button or link on your site. Opened directly, for example from an email, it shows a “Your download is ready” pop-up with a Download button, unless you switch off button-only downloads on the Settings tab.
4
Dashboard & settings
The four counters at the top of every tab show the downloads for Today, This Week, This Month and All Time. Under each is the number of requests that were blocked in the same period. The Help button on the tab row explains both.
The Dashboard tab has your Files (the Add New File form), File Downloads, Most Downloaded, Downloads by Country, Top Files and Recent Downloads. Drag the widgets to rearrange them.
The Settings tab has three cards:
- Download protection: button-only downloads, the limit on how often one visitor can download the same file, whether the Files list shows the Shortcode column, and the text to hide in file addresses so that long addresses are easier to read.
- Exempt IP addresses: a table of addresses whose downloads still work but are never recorded, each with a note saying why it is exempt. Use it for your own servers, for example your other sites fetching plugin updates from this one, so they do not fill the log.
- Download button colours: the pop-up’s button background, hover background, text and hover text. Hover the preview to see the result before saving.
Button-only downloads are on by default. A file is sent only when a visitor presses a download button or link on your site. A request made straight to the link, by a crawler or from an email, gets a “Your download is ready” pop-up with a Download button instead, and is counted as blocked. WordPress sites fetching plugin updates are always served. By default one visitor can download the same file 3 times every 10 minutes.
5
Logs & exports
The Logs tab lists every download. Filter by file, or type in the two search boxes: each one matches any column, and with both filled in a row must match both. Click the copy icon beside an IP address to copy it, or the bin beside it to delete that one entry. Tick rows to delete them, or remove everything in a chosen time range; a confirmation window asks first. Export to CSV downloads the log using the current filter and search.
On File Analytics, choose a file (and optionally a country) and use Export CSV to save the data behind the chart.
Deleting a file also deletes its download records. A confirmation window tells you how many records will be removed before anything is deleted.
Frequently asked questions
Is the download link admin-only?
No. Managing files and viewing stats needs the manage_options capability, but the tracked links are public so visitors can use them.
Does country lookup cost anything?
No. It uses the free ip-api.com service with no API key. Each IP address is cached for 30 days.
Does cancelling the Save dialog count as a download?
No. Files are streamed through WordPress and only logged once the whole file has been sent.
Will I lose my logs when I update?
No. Tables are updated automatically; only new columns are added and existing rows are kept.
Do my old numeric links still work?
Yes, for files that existed when tokens were introduced, until you retire them. See Secure Links.
Why does my download link show a pop-up instead of the file?
Button-only downloads are on. A file is sent when a visitor presses a download button or link on your site. A link opened directly, for example from an email or by a crawler, shows a “Your download is ready” pop-up with a Download button. Switch this off on the Settings tab if you want links to go straight to the file.
What is a blocked request?
A request for a download link that was turned away: it did not start with a download button on your site, or the visitor was over the download limit. No file is sent and nothing is added to the logs. The Help button on every tab has the details.