How to add the Swapotamus referral widget to WordPress

1. Check your WordPress permissions and pilot access

You need an approved Swapotamus pilot account, a registered website you own or manage, and access to publish code on that website. Complete DNS ownership verification if your dashboard requires it. The site must also pass the live homepage installation check before it becomes active.

For self-hosted WordPress, script permissions depend on your role, site configuration, and hosting policy. WordPress may remove script tags when the user lacks the relevant permission. Its current Custom HTML editor can also separate HTML and JavaScript controls. Follow the official Custom HTML block documentation for your editor version.

On WordPress.com, external JavaScript requires a plugin-enabled plan with hosting features activated. Check WordPress.com’s current code support before installing. If scripts are unavailable, ask the site administrator about a supported integration rather than repeatedly pasting code that is removed on save.

2. Copy the snippet for the correct website

Sign in to Swapotamus, open the widget page for the website you registered, and find Install on your website. Copy the full snippet shown there. It includes a container and an external script with your account-specific website ID.

<div id="swapotamus-widget"></div>
<script async src="https://swapotamus.com/widget.js"
  data-site-id="YOUR_SITE_ID"></script>

Keep the container before the script, and install one copy per page. Do not substitute a WordPress post ID, a domain name, or another publisher’s ID. The example above will not activate a website while its placeholder remains.

3. Publish the snippet on your homepage

Start on the public homepage, because Swapotamus’s activation check looks there for your exact script and website ID. Installing it only on an individual blog post is insufficient for that check.

1. In WordPress, open the homepage editor. If your homepage uses a theme template, edit the template or a footer template part that appears on the homepage.
2. Add a Custom HTML block where recommendations will be useful, such as after the main content. Paste the full snippet using the code controls your editor permits.
3. Save and publish. Open the public homepage in a separate signed-out browser window, rather than relying on the editor preview.
4. If your installation uses caching, purge the affected page cache so visitors and the verification check receive the new HTML.

If your editor strips scripts, use your host’s or theme’s supported custom-code integration. Keep the container where recommendations should appear and load the external script after it. Choose an integration that outputs the original script in the homepage HTML; a delayed script loader that rewrites it may prevent activation.

A shared footer can place the widget on several pages. Check that the homepage contains it and that the container ID is not duplicated. The widget fits its container up to 720px wide and adjusts its height to the recommendations.

4. Verify the live homepage in Swapotamus

Return to the widget dashboard and select Verify installation. The installation check retrieves the registered domain’s HTTPS homepage and looks for the account-specific script. It must receive the published HTML directly; a redirect, login wall, or bot challenge can prevent confirmation.

A successful check confirms the script and activates the website’s domain claim. Reopen the live homepage to check the visitor experience, then review relevant partner suggestions. Saving widget appearance settings updates the configuration without replacing the snippet.

Installation success and visible recommendations are separate checks. A correctly installed widget intentionally stays empty when there are no eligible partners. Review approvals, partner activity, language and category preferences, and pause status before assuming that the code failed.

What to check when the widget does not appear

The script disappears after saving

Reopen the block and inspect the published page source. Confirm that your role and hosting plan permit scripts. Use a permitted custom-code integration if needed.

Verify installation cannot find the script

Check the live homepage, the exact script URL, and data-site-id. Purge stale HTML caches. Ask your host about redirects or bot protection if the homepage does not return published HTML directly.

The site is active, but there are no links

Check the live partner preview in Swapotamus. Approve relevant partners and review exclusions. A partner must be eligible and active; no available matches means the widget stays empty.

The script is present, but requests are blocked

Check browser network and console messages. Your content security policy must permit https://swapotamus.com in script-src and connect-src. The widget needs permission for its scoped styles; use the nonce support described in your dashboard or an appropriate style policy. Optional partner logos need permission for their image hosts. Test without a blocking extension to isolate the cause.

The widget appears twice

Check whether both the page content and a shared template install it. Keep one container and one script per page.

If you still need help, use Swapotamus support with the public homepage URL, the installation message, and the relevant browser error. Do not send account passwords or sign-in tokens.

Measure referrals and keep control of the placement

Swapotamus records recommendation clicks and estimates visible impressions from sampled observations. Use your own destination analytics to measure resulting sessions and conversions; a click is not proof of a completed visit. The widget does not use visitor cookies or browser storage.

Recheck the homepage after changing themes, caching tools, or script optimizers. You can change appearance, disable logos, review partners, or pause the website in Swapotamus. To remove the widget, remove both the container and script from WordPress, publish the change, and clear the relevant cache.

For help deciding which websites to recommend, read the referral partnership guide. For current access and costs, see pilot pricing.