Targeted Content

This is a WordPress plugin that allows you to display content for users based on different criteria.

A list of all criteria:

• Arriving from LinkedIn
• Arriving from Facebook
• Arriving from Threads
• Arriving from Instagram
• Arriving from TikTok
• Arriving from YouTube
• Arriving from specific domain
• Referrer URL contains a specific keyword
• Arriving with specific UTM parameter
• Incoming URL has a custom URL parameter
• Specific date
• Day of week
• Time of day (server local time)
• User is from specific country
• User is from specific city
• Users with specific IP addresses
• Specific cookie is set
• Specific session cookie is set
• Operating system
• Browser
• Browser language (first Accept-Language)
• Internet connection (ISP)
• Device type
• Show only once, and when to show again

You can specify which content blocks can be added inside this Targeted Content block on the Settings → Targeted Content → General page. There you can also allow addtional blocks, inluding your custom blocks. Just click on the "Discover blocks" button and select which ones to allow.

If it feels like you always use only some specific criteria, and all the other criterias are just in the way, then you can hide those criteria you never use via the plugin setting page.

You can see how many times each Targeted Content block has been displayed via Settings → Targeted Content → Statistics.

Requirements

The block is registered using the PHP-only block registration method introduced in WordPress 7.0 released in May 2026. That or newer version of WordPress is required for this plugin to work.

Installation

Clone this repository or download as a ZIP file, install it via your WordPress admin plugin page, and enable the plugin.

If you need to add the Targeted Content block to any allowed blocks setting, its name is kenda/targeted-content.

Country / city criteria

By default the plugin uses Free IP API https://freeipapi.com/ to find out the users location. No registration or API key is needed. The free tier allows 60 requests per minute; results are cached on your server for 7 days per IP, so a typical site stays well under the limit. To raise the limit, buy a plan and paste its API key to the plugin settings.

This means that the users IP is sent to a third party service. EU sites using it should mention this in their privacy policy.

A privacy friendly alternative is to use a local MaxMind GeoLite2 City database. This option keeps visitor IPs on your own server. See download and install instructions below.

If you do not intend to use the country or city criteria, then you do not need to do anything about this. User IP is not used or sent anywhere if not the criteria is used.

Location based criteria is hard to test in localhost since your IP will be 127.0.0.1. Same goes for ISP criteria.

1. Download GeoLite2 City

This is the privacy friendly alternative to find out users location.

GeoLite2 is free but requires a MaxMind account:

1. Sign up for a free account at https://www.maxmind.com/en/geolite2/signup.
2. After confirmation, log in and go to Download files in the MaxMind account portal.
3. Download GeoLite City in the Binary / .mmdb format (not the CSV). You'll get a .tar.gz archive containing a file named GeoLite2-City.mmdb.

The file size is only 65 megabytes (april 2026).

Only the City database is needed — not the Country one. GeoLite2 City is a superset: it already contains the ISO country code used by the "country" criterion. The plugin's reader calls ->city($ip), which requires the City record format, so the smaller GeoLite2 Country DB wouldn't work here even if you only plan to match on country.

MaxMind refreshes the database twice a week; if you rely on city-level accuracy, plan to re-download (or automate with MaxMind's free geoipupdate tool) every few weeks.

2. Place the .mmdb file on the server

Extract the archive and upload GeoLite2-City.mmdb to your WordPress installation. The plugin's default path is:

wp-content/uploads/geoip/GeoLite2-City.mmdb

Create the uploads/geoip/ directory if it doesn't exist. Any other location that is readable by the PHP process works too — you just need to point the plugin at it (see step 3). Only the web-server user needs read access; no writes are ever made to the file.

3. Confirm / change the path in WordPress

In the WordPress admin, go to Settings → Targeted Content → General and check the GeoLite2 DB path field:

• If the file is at the default location, you can leave the field as-is.
• Otherwise, enter the absolute server path to your GeoLite2-City.mmdb file.

Saving the setting re-checks the path and the page shows whether the file was found. The country/city criteria start matching as soon as the path resolves to a readable GeoLite2 City database.

Optional: MaxMind PHP libraries

If your site already installs the geoip2/geoip2 Composer package (which pulls in maxmind-db/reader), the plugin uses the high-level \GeoIp2\Database\Reader automatically. If only the lower-level maxmind-db/reader is available, the plugin falls back to \MaxMind\Db\Reader. When neither library is present, GeoIP criteria silently skip — the rest of the plugin is unaffected.

Specific IP addresses criterion

Schools, libraries, and corporate offices often share a single public IP address (or a small range), so an "Is from this organisation" gate can be expressed as a list of IPs. The Users with specific IP addresses criterion takes one entry per line. Each entry is either an exact IP address or a CIDR range; both IPv4 and IPv6 are supported. Examples:

192.0.2.5
198.51.100.0/24
2001:db8::/48

Entries that don't parse as a valid address or CIDR are silently ignored, so a single typo doesn't disable the whole criterion. The visitor IP is the same one used by the country/city criteria — read from Cf-Connecting-IP, then X-Forwarded-For, then REMOTE_ADDR — so sites behind Cloudflare or a load balancer compare against the real client, not the edge.

A note on reliability: corporate VPNs, cloud egress proxies (Zscaler, Netskope, Cloudflare WARP), and ISP changes can all move an organisation's apparent IP. Treat IP-based targeting as a useful signal, not a hard identity check.