5The download-time re-injection quirk

Joomla's extra_query reliably gets appended when Joomla checks an update site's feed. It is not reliably re-applied when Joomla later downloads the actual package file — a long-standing core quirk, confirmed directly by Akeeba's own lead developer in the ticket referenced at the end of this guide: "Joomla applies the Download ID when it is looking for updates, not when it tries to download updates."

The fix Akeeba uses for their own Pro products, and the one we copied: a small installer-group plugin that hooks the modern onInstallerBeforePackageDownload event and appends the key directly to the download URL at the moment Joomla is about to fetch it.

use Joomla\CMS\Event\Installer\BeforePackageDownloadEvent;
use Joomla\Event\SubscriberInterface;

final class PlgInstallerYourpackage extends CMSPlugin implements SubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return ['onInstallerBeforePackageDownload' => 'onInstallerBeforePackageDownload'];
    }

    public function onInstallerBeforePackageDownload(BeforePackageDownloadEvent $event): void
    {
        $url = $event->getUrl();
        // Look up the matching update site's extra_query and append it here
        // if it isn't already present in $url.
        $event->updateUrl($url);
    }
}