⁕

Custom Auto

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

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 {};
}

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