haxcode/magento-georouting

Intelligent geo-based store routing for Magento 2 with SEO protection and product availability checking

Maintainers

Package info

github.com/haxcode-ts/Haxcode_GeoRouting-Magento

Type:magento2-module

pkg:composer/haxcode/magento-georouting

Statistics

Installs: 0

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

dev-main 2026-03-03 12:35 UTC

Requires

  • php: ^7.4|^8.0|^8.1|^8.2
  • magento/framework: ^102.0|^103.0
  • magento/module-checkout: ^100.4
  • magento/module-store: ^101.0

proprietary b8445d7d77833d8d8feb4de84d5c6e7d76b30eaa

  • Haxcode <mail.woop@haxcode.com>

This package is not auto-updated.

Last update: 2026-05-13 12:04:09 UTC

README

Intelligent geo-based store routing module for Magento 2 with comprehensive SEO protection, product availability checking, and user preference management.

Features

Core Functionality

  • Automatic Geo-Detection: Automatically detects visitor's country and redirects to appropriate store
    • Visitors from Canada → CAD store (/ca/)
    • Visitors from US, China, and other countries → USD store (default)
  • Manual Store Switching: Header dropdown with confirmation popup before switching
  • User Preference Memory: Cookie-based storage remembers user's manual store selection (30 days default)
  • Product Availability Check: Shows popup if product not available in target store

SEO & Performance Safeguards

  • Bot Detection: Search engine crawlers are excluded from auto-redirects to avoid indexing issues
  • Hreflang Tags: Automatic implementation of hreflang meta tags for proper SEO
  • Deep Link Safety: Product/category URLs retain full path during redirects (e.g., /product → /ca/product)
  • CDN/Cache Compatible: Works seamlessly with Cloudflare, Varnish, and other caching layers

E-commerce Protection

  • Checkout Protection: Store switching blocked during cart/checkout to prevent order issues
  • Cart Awareness: Warning popup when switching stores about potential cart changes
  • Fail-safe Fallback: System defaults to USD store if geo-detection fails (no redirect loops)

Installation

Method 1: Composer (Recommended)

composer require haxcode/module-georouting
php bin/magento module:enable Haxcode_GeoRouting
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
php bin/magento cache:flush

Method 2: Manual Installation

  1. Download or clone this repository
  2. Copy the GeoRouting folder to app/code/Haxcode/
  3. Run the following commands:
php bin/magento module:enable Haxcode_GeoRouting
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
php bin/magento cache:flush

Configuration

Admin Configuration

Navigate to: Stores → Configuration → Haxcode → Geo Routing

General Settings

  • Enable Geo Routing: Enable/disable the module
  • Canada Store Code: Store code for Canada (default: ca)
  • Default Store Code: Store code for US/Default (default: default)
  • Cookie Lifetime: Days to remember user preference (default: 30)
  • Exclude Search Engine Bots: Prevent auto-redirect for SEO crawlers (recommended: Yes)
  • Protect Checkout Process: Prevent store switching during cart/checkout (recommended: Yes)
  • Check Product Availability: Show popup if product not available in target store (recommended: Yes)
  • Enable Hreflang Tags: Add hreflang meta tags for SEO (recommended: Yes)

GeoIP Settings

  • GeoIP Service: Select detection method
    • Cloudflare: Uses Cloudflare's CF-IPCountry header (recommended if using Cloudflare)
    • Server Variable: Uses generic server variables (mod_geoip, custom headers)
  • Cloudflare Country Header: Header name (default: HTTP_CF_IPCOUNTRY)
  • Fallback Country Code: Country to use if detection fails (default: US)

Store Setup

Ensure you have configured your stores in Magento:

  1. Stores → All Stores
  2. Create store views:
    • Default Store (USD) - Store Code: default
    • Canada Store (CAD) - Store Code: ca

URL Configuration

Configure store URLs to include store code:

  1. Stores → Configuration → General → Web
  2. Set Add Store Code to URLs: Yes
  3. Configure base URLs:
    • Default Store: https://yushefashion.com/
    • Canada Store: https://yushefashion.com/ca/

Cloudflare Setup (Recommended)

If using Cloudflare:

  1. Enable IP Geolocation in Cloudflare Dashboard
  2. The module will automatically use the CF-IPCountry header
  3. No additional configuration needed

Usage

Automatic Redirection

Once enabled, the module automatically:

  1. Detects visitor's country on page load
  2. Redirects to appropriate store (Canada → /ca/, Others → default)
  3. Preserves URL path and query parameters
  4. Skips redirect if user has manual preference or is a bot

Manual Store Switching

Add store switcher to your header template:

<!-- Example: app/design/frontend/[Vendor]/[Theme]/Magento_Theme/templates/html/header.phtml -->
<div class="store-switcher">
    <select onchange="if (this.value) window.georouting.showManualSwitchPopup(this.value)">
        <option value="">Select Store</option>
        <option value="default">United States (USD)</option>
        <option value="ca">Canada (CAD)</option>
    </select>
</div>

<!-- Or use data attributes -->
<a href="#" data-georouting-store="ca">Switch to Canada Store</a>
<a href="#" data-georouting-store="default">Switch to US Store</a>

Product Availability Popup

When enabled, the module automatically:

  1. Checks if current product exists in target store
  2. Shows popup if product not available: "This product is not available in Canada store. Do you want to continue in the US store?"
  3. Options: Stay (saves preference) or Go to US Store (switches store)

JavaScript API

The module exposes a JavaScript API:

require(['Haxcode_GeoRouting/js/georouting'], function(georouting) {
    // Show manual switch popup
    georouting.showManualSwitchPopup('ca');

    // Show product availability popup
    georouting.showProductAvailabilityPopup('ca', 'default');

    // Save user preference
    georouting.saveUserPreference('ca');
});

How It Works

Request Flow

  1. Page Request → Observer checks if geo-routing should run
  2. Detection → Gets country from Cloudflare/server headers
  3. Preference Check → Checks if user has manual preference (cookie)
  4. Bot Check → Excludes search engine crawlers
  5. Checkout Check → Skips if in cart/checkout
  6. Product Check → Validates product availability (if on product page)
  7. Redirect → Redirects to appropriate store with preserved URL

Cookie Management

  • Cookie Name: georouting_preference
  • Lifetime: Configurable (default 30 days)
  • Scope: Site-wide
  • Set when: User manually switches stores

SEO Implementation

Hreflang Tags

Automatically added to <head>:

<link rel="alternate" hreflang="en-US" href="https://yushefashion.com/product-name" />
<link rel="alternate" hreflang="en-CA" href="https://yushefashion.com/ca/product-name" />
<link rel="alternate" hreflang="x-default" href="https://yushefashion.com/product-name" />

Bot Detection

The module detects common bots:

  • Googlebot, Bingbot, Slurp (Yahoo)
  • DuckDuckBot, Baiduspider, YandexBot
  • AhrefsBot, SemrushBot, MJ12bot
  • And more...

Scenarios

Scenario 1: Canadian Visitor on Product Page

  • Visitor: From Canada
  • Product: Available in both US and CA stores
  • Result: Auto-redirects to /ca/product-name

Scenario 2: Canadian Visitor, Product Only in US Store

  • Visitor: From Canada
  • Product: Only available in US store
  • Result: Shows popup: "This product is not available in Canada store. Do you want to continue in the US store?"
  • Options:
    • Stay in US Store → Saves preference, stays on US store
    • Go to Canada Store → Redirects to CA store homepage

Scenario 3: Manual Store Switch During Checkout

  • Action: User tries to switch store
  • Result: Blocked with message: "Store switching is not allowed during checkout. Please complete your order or clear your cart first."

Scenario 4: User with Manual Preference

  • Previous Action: User manually switched to US store
  • Current: User from Canada visits site
  • Result: No auto-redirect, stays on US store (preference remembered for 30 days)

Scenario 5: Search Engine Bot

  • Visitor: Googlebot
  • Result: No redirect, allows bot to crawl all stores independently

Troubleshooting

Auto-redirect not working

  1. Check module is enabled: Configuration → Geo Routing → Enable
  2. Verify store codes match configuration
  3. Check if user has manual preference (clear cookies to test)
  4. Review logs: var/log/system.log (search for "GeoRouting")

Cloudflare country detection failing

  1. Verify IP Geolocation is enabled in Cloudflare
  2. Check header name in configuration matches HTTP_CF_IPCOUNTRY
  3. Test with fallback country to verify module is working

Popups not showing

  1. Clear static content: php bin/magento cache:clean
  2. Deploy static content: php bin/magento setup:static-content:deploy
  3. Check browser console for JavaScript errors
  4. Verify jQuery and Magento UI are loaded

Hreflang tags not appearing

  1. Enable in configuration: Enable Hreflang Tags = Yes
  2. Clear page cache: php bin/magento cache:clean full_page
  3. View page source to verify tags in <head>

Logging

The module logs important events to var/log/system.log:

  • Country detection results
  • Bot detection
  • Store switching actions
  • Redirect operations
  • Errors and exceptions

Search for GeoRouting: prefix in logs.

Compatibility

  • Magento 2.3.x, 2.4.x
  • PHP 7.4, 8.0, 8.1, 8.2
  • Works with:
    • Cloudflare
    • Varnish
    • Full Page Cache
    • All major themes

Support

For issues, questions, or feature requests:

License

Proprietary - Copyright (c) 2024 Haxcode

Changelog

Version 1.0.0

  • Initial release
  • Automatic geo-based routing
  • Manual store switching with confirmation
  • Product availability checking
  • SEO-safe bot exclusion
  • Hreflang implementation
  • Checkout protection
  • User preference memory
  • Cloudflare integration