Custom Auto

.md

Developer reference for Custom Auto Redirects — cookies, query parameters, bot detection, and custom JavaScript rules.

Cookies

Cookie	Purpose	Duration
xgeo-session	Cached geolocation data	7 days
xgeo-auto-once	“Redirect once” tracking (when using cookies mode)	7 days
xgeo-off	Dev mode — disables all redirects	7 days

Session Storage

Key	Purpose
xgeo-auto-once	“Redirect once” tracking (when using session mode)

Query Parameters (All Embeds)

These query parameters work across all embeds and are useful during development and testing:

Parameter	Purpose
?xgar=1	Loop prevention — appended to redirect URLs by default. When present, auto-redirect is skipped.
?xgeo-sim=1	Activates the Geo Simulator overlay — simulate visits from any country
?xgeo-sim=0	Deactivates the Geo Simulator overlay
?xgeo-off	Disables all redirects for 7 days (sets a cookie)
?xgeo-reset	Re-enables redirects (removes the xgeo-off cookie)
?xgeo-test	Test mode — skips auto-redirect execution for debugging

Bot Detection

The auto-redirect script checks navigator.userAgent against a regex pattern to prevent bots from being redirected. The default pattern:

bot|adsbot|googlebot|crawler|spider|robot|crawling|slurp

This pattern is customizable in the dashboard settings. The regex is case-insensitive. Add additional bot identifiers separated by |.

Custom JavaScript Rule (Pro)

Pro plan only. Override the default redirect logic with a custom function.

How to Add Custom Code

1. Go to Geolocation Flow Dashboard → Custom Auto Redirects
2. Scroll down to the Advanced section
3. Paste your custom JavaScript into the Custom redirect rule field
4. Click Save

Parameters

Parameter	Description
redirectUrl	The URL the visitor would be redirected to
currentUrl	The current page URL
geolocation	{ country: "CA", country_name: "Canada", continent: "NA" }
forceRedirect(url)	Call to force a redirect to a specific URL

Execution Order

Your custom code runs per redirect item, after the app matches the visitor’s location to a redirect rule. The flow is:

1. The app loops through redirect items in order
2. For each item that matches the visitor’s geo, your run() function is called
3. Your code can override or cancel the redirect via return values

Important: forceRedirect(url) calls window.location.replace(), but the browser doesn’t stop JavaScript execution instantly. The redirect item loop continues running — so if you call forceRedirect() without returning false, the next matching redirect item can overwrite your forced redirect before the browser navigates.

Return Values

• return {} — proceed with the default redirect
• return { skip: true } — cancel the redirect for this item
• return false — skip this redirect item (use after calling forceRedirect)
• forceRedirect(url) + return false — redirect to a different URL and prevent the normal redirect from overwriting it

Sample: Use default redirect logic (pass-through)

function run(redirectUrl, currentUrl, geolocation, forceRedirect) {
  return {}; // let the default logic handle everything
}

Sample: Cancel redirect for specific countries

function run(redirectUrl, currentUrl, geolocation, forceRedirect) {
  var noRedirect = ["US", "CA"];
  if (noRedirect.indexOf(geolocation.country) !== -1) {
    return { skip: true };
  }
  return {};
}

Sample: Redirect to a different URL based on country

function run(redirectUrl, currentUrl, geolocation, forceRedirect) {
  if (geolocation.country === "GB") {
    forceRedirect("https://uk.mystore.com" + window.location.pathname);
    return false; // prevents the normal redirect from overwriting
  }
  if (geolocation.country === "DE") {
    forceRedirect("https://de.mystore.com" + window.location.pathname);
    return false;
  }
  return {}; // default logic for everyone else
}

Sample: Only redirect on the homepage

function run(redirectUrl, currentUrl, geolocation, forceRedirect) {
  if (window.location.pathname !== "/") {
    return { skip: true };
  }
  return {};
}

Sample: Cancel redirect if a specific cookie exists

function run(redirectUrl, currentUrl, geolocation, forceRedirect) {
  if (document.cookie.includes("my-custom-cookie=1")) {
    return { skip: true };
  }
  return {};
}

Related Docs

• Custom Auto Redirects — setup and configuration guide
• UTM & Tracking — safety parameters and tracking
• Custom Widget — widget-side developer reference