Installation Guide
Add GeoSwap to your website in under 60 seconds
Prerequisites
A free GeoSwap account. Create one here if you have not already.
Your Account ID, found in Settings → Install.
Access to edit your website's HTML, theme, or CMS settings.
The GeoSwap Script
GeoSwap works by adding a single JavaScript file to your website. This script is lightweight (under 5KB gzipped), served from a global CDN, and cached aggressively. It does not block page rendering thanks to the defer attribute.
Add to <head>html
<script src="https://cdn.geoswap.co/geoswap.js" data-account="YOUR_ACCOUNT_ID" defer></script>Replace YOUR_ACCOUNT_ID with your actual Account ID from the dashboard.
Platform Guides
HTML / Static Sites
Add the script tag to the <head> section of every page. If you use a shared layout or template, add it once there.
index.htmlhtml
<!-- Add to your <head> section -->
<script
src="https://cdn.geoswap.co/geoswap.js"
data-account="YOUR_ACCOUNT_ID"
defer
></script>
WordPress
PopularThere are three ways to add GeoSwap to WordPress, ordered from simplest to most reliable:
Option A: Using a plugin (easiest)
Install any "Insert Headers and Footers" plugin (e.g., WPCode or Insert Headers and Footers by WPBeginner). Paste the GeoSwap script into the header section.
Option B: Theme header
Go to Appearance → Theme File Editor and open header.php. Add the script tag just before the closing </head> tag.
header.phphtml
<!-- Add before </head> in header.php -->
<script
src="https://cdn.geoswap.co/geoswap.js"
data-account="YOUR_ACCOUNT_ID"
defer
></script>
</head>Option C: functions.php (most reliable)
Add the following to your theme's functions.php file or a custom plugin:
functions.phpphp
function geoswap_enqueue_script() {
wp_enqueue_script(
'geoswap-geo',
'https://cdn.geoswap.co/geoswap.js',
array(),
null,
false // Load in <head>
);
wp_script_add_data('geoswap-geo', 'defer', true);
}
add_action('wp_enqueue_scripts', 'geoswap_enqueue_script');
// Add the data-account attribute
function geoswap_script_attributes($tag, $handle, $src) {
if ('geoswap-geo' !== $handle) return $tag;
return str_replace(
' src=',
' data-account="YOUR_ACCOUNT_ID" src=',
$tag
);
}
add_filter('script_loader_tag', 'geoswap_script_attributes', 10, 3);
Shopify
Popular- Go to Online Store → Themes in your Shopify admin.
- Click Actions → Edit code on your active theme.
- Open
theme.liquid(under Layout). - Paste the GeoSwap script just before the closing
</head>tag. - Click Save.
theme.liquidhtml
<!-- Add before </head> in theme.liquid -->
<script
src="https://cdn.geoswap.co/geoswap.js"
data-account="YOUR_ACCOUNT_ID"
defer
></script>
Next.js
App Router (Next.js 13+)
Add the script to your root layout using the Next.js Script component:
app/layout.tsxtsx
// app/layout.tsx
import Script from "next/script";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en">
<body>
{children}
<Script
src="https://cdn.geoswap.co/geoswap.js"
data-account="YOUR_ACCOUNT_ID"
strategy="afterInteractive"
/>
</body>
</html>
);
}Pages Router
Add the script to _app.tsx or _document.tsx:
pages/_app.tsxtsx
// pages/_app.tsx
import Script from "next/script";
import type { AppProps } from "next/app";
export default function App({ Component, pageProps }: AppProps) {
return (
<>
<Component {...pageProps} />
<Script
src="https://cdn.geoswap.co/geoswap.js"
data-account="YOUR_ACCOUNT_ID"
strategy="afterInteractive"
/>
</>
);
}
Webflow
- Open your Webflow project and go to Project Settings.
- Navigate to the Custom Code tab.
- Paste the GeoSwap script into the Head Code section.
- Click Save and publish your site.
Webflow Head Codehtml
<script src="https://cdn.geoswap.co/geoswap.js" data-account="YOUR_ACCOUNT_ID" defer></script>
Squarespace
- Go to Settings → Advanced → Code Injection.
- Paste the GeoSwap script into the Header field.
- Click Save.
Squarespace Header Injectionhtml
<script src="https://cdn.geoswap.co/geoswap.js" data-account="YOUR_ACCOUNT_ID" defer></script>
Squarespace Business plan required
Code Injection is only available on Squarespace Business and Commerce plans. If you are on a Personal plan, you will need to upgrade to add custom scripts.
Google Tag Manager
If you use Google Tag Manager, you can add GeoSwap as a custom HTML tag:
- Create a new Tag of type "Custom HTML".
- Paste the script code below.
- Set the trigger to "All Pages" with firing priority set high (so it loads early).
- Publish your container.
GTM Custom HTML Taghtml
<script src="https://cdn.geoswap.co/geoswap.js" data-account="YOUR_ACCOUNT_ID" defer></script>GTM adds latency
Loading GeoSwap through GTM adds a small delay because GTM itself must load first. For the fastest geo redirects, add the script directly to your HTML head. GTM is fine for Geo Content personalization where a brief delay is acceptable.
Verifying Installation
After adding the script, verify it is working:
Open your website in a browser and open the browser's Developer Tools (F12 or Cmd+Option+I).
Go to the Network tab and filter by "geoswap.js". You should see the script loading successfully (HTTP 200).
Go to the Console tab. You should see [GeoSwap] Initialized in the console output.
In the GeoSwap dashboard, go to Settings → Install. The installation status should show as verified within a few minutes of your first page view.
Troubleshooting
Script not loading (404 error)
Verify the script URL is exactly ${CDN_URL}/geoswap.js. Check for typos. Ensure your HTML is valid (the script tag is properly closed).
Console shows "Invalid account ID"
Verify the data-account attribute matches your Account ID from Settings > Install. Account IDs are case-sensitive.
Redirects not working
Ensure you have created at least one active redirect rule in the dashboard. Check that the source URL in your rule matches the page where the script is installed.
Content personalization flickering
Add CSS to hide personalized elements until GeoSwap loads: [data-geoswap] { opacity: 0; transition: opacity 0.2s; } Then GeoSwap will reveal them after swapping content.
Script blocked by ad blocker
Some aggressive ad blockers may block third-party scripts. If this is a concern, you can use a custom domain for the script URL. See Settings > Domains in the dashboard.
Anti-Flicker Snippet (Optional)
If you use Geo Content personalization and notice a brief flash of default content before the personalized content appears, add this CSS snippet to your stylesheet:
Anti-flicker CSScss
/* Hide GeoSwap-targeted elements until content is swapped */
[data-geoswap] {
opacity: 0;
transition: opacity 0.15s ease-in;
}
/* GeoSwap adds this class after swapping content */
[data-geoswap].geoswap-ready {
opacity: 1;
}
/* Fallback: show default content if GeoSwap fails to load within 3s */
@media (scripting: none) {
[data-geoswap] {
opacity: 1;
}
}This is optional and only relevant for Geo Content. Geo Redirects and Geo Links do not have a flicker issue because they navigate to a different page entirely.
Next up
Set up your first geo redirect rule.