PBJ.TECH — WordPress Plugins

PBJ Geo Viewer — User Guide

Version 1.5.0 · pbj.tech/wordpress-plugins

PBJ Geo Viewer — Install & Usage Guide

Version 1.5.0

What this plugin does

PBJ Geo Viewer makes your WordPress site view-only for visitors outside the countries you allow. Selected countries get the full interactive experience. Everyone else can still browse every page on the site, but cannot:

Search engines and admins are always exempt, so SEO and your own access are unaffected.

Requirements

Installation

  1. Download pbj-geo-viewer.zip (or pbj-geo-viewer-1.5.0.zip).
  2. In WordPress admin: Plugins → Add New → Upload Plugin → choose the zip → Install Now → Activate.
  3. After activation, go to Geo Viewer — its own top-level item in the admin sidebar.

To upgrade later: just upload the newer zip the same way. WordPress will prompt to replace the existing copy. Your settings are preserved across upgrades — the plugin handles schema migrations automatically.

First-time setup

Since 1.5.0 the Settings tab is a guided five-step walkthrough — each step in its own numbered card with a plain-English "what this does" explanation. It's one form: work through the steps, then click Save settings once at the bottom (everything saves together).

Step 1 — Choose your mode and countries

In the Countries grid, tick every country the rule should apply to. Type into the Filter countries… box to narrow the list; Select all shown and Clear all act on the filtered view, and a live count shows how many are selected. The full ISO 3166-1 country set is available.

Step 1 also holds two related settings:

Step 2 — Choose what view-only visitors can't do

Four independent toggles:

Step 3 — What blocked visitors see

Two independent notice toggles:

Both default to ON. The banner text and inline message are fully editable.

Step 4 — Exemptions

In the Admin IP allowlist, enter one IP or CIDR per line, e.g.:

203.0.113.5
198.51.100.0/24
2001:db8::1

Any visitor from a listed IP is treated as fully allowed regardless of country. Add your home and office IP here before going live — otherwise, the next time you visit from a blocked country (or VPN through one), you'll lose the ability to interact with your own site. (Logged-in editors and admins are also always exempt, so as long as you're logged in you're fine.)

The same card holds the Login username allowlist — usernames or emails that may sign in from blocked regions (a login-only exemption; admins and editors can always sign in) — and Geo cache (minutes), which controls how long an IP-to-country lookup is remembered.

Step 5 — Test your setup

The Diagnostics table in the last step shows:

If the country is wrong or showing as (unknown), check whether your site is actually proxied through Cloudflare and whether your hosting provider is forwarding the real client IP via X-Real-IP, X-Forwarded-For, or CF-Connecting-IP.

Daily usage

Once configured, the plugin runs automatically. There's nothing to push or sync — every page request is evaluated in real time.

Testing as a blocked visitor

To preview how blocked visitors see your site:

  1. Add a temporary "test" country to your allowlist (or remove your own from it).
  2. Log out of WordPress.
  3. Browse from an IP that isn't in your admin allowlist (use a phone on cellular, or a VPN).

The banner and inline notices should appear, cart and forms should be disabled, and /cart should redirect.

Adjusting countries

Add or remove countries any time. Changes take effect immediately for new requests. Cached country lookups for individual visitor IPs persist for 24 hours by default — that's fine in practice because countries-per-IP almost never change.

If you need to flush the geo cache immediately (e.g., a customer complains they're misclassified), deactivate and reactivate the plugin. The deactivation handler clears all pbj_geo_* transients.

Crawler behavior

The plugin maintains a list of known crawler user-agents (Googlebot, Bingbot, DuckDuckBot, Slurp, GPTBot, ClaudeBot, PerplexityBot, Applebot, FacebookExternalHit, TwitterBot, LinkedInBot, ScreamingFrog SEO Spider, and many others). Anything matching one of those strings is always treated as fully allowed.

This means:

If you want to add a private crawler or scraper to the always-allowed list (e.g., your own monitoring bot), use the admin IP allowlist instead — that's the more reliable mechanism for identifying your own infrastructure.

Upgrading

Manual upgrade

Upload the newer zip via Plugins → Add New → Upload Plugin. WordPress will prompt to overwrite. Settings are preserved.

Auto-updates (optional, when you've set up an update server)

The plugin's Update URI header points at https://pbj.tech/plugins/pbj-geo-viewer. To enable auto-updates from your own server, host a JSON manifest at that URL:

{
  "version":      "1.0.2",
  "package":      "https://pbj.tech/dl/pbj-geo-viewer-1.0.2.zip",
  "tested":       "6.5",
  "requires":     "5.8",
  "requires_php": "7.4",
  "url":          "https://pbj.tech/plugins/pbj-geo-viewer"
}

WordPress checks for updates roughly twice a day. When the remote version is newer than the installed version, Plugins → Installed Plugins shows the usual update prompt.

If the update server is unreachable, the updater silently falls back to "no update available" — your site is never harmed by a broken update endpoint.

Troubleshooting

Where things live