Evance's front-end geolocation API allows theme developers to implement regional content targeting in a way that best suits a website's needs. 

International websites can offer targeted content to visitors from different countries using Evance's locale system. In addition to translated content, e-commerce sites can accommodate alternative currencies by exchange or by explicitly defining regional pricing, offer regional product alternatives or accommodate legal restrictions. You just need to get users to the correct locale.

All international websites will have a locale selection option - providing users with the facility to change to their preferred country and language. But, if its not obvious, a potential customer could bounce if the currency doesn't match their wallet's. That's where geolocation can help and there are typically two methods: 

1. Redirect users automatically. This is the easiest to implement, but may not offer the best user experience.
2. Offer a regional selection/continuation prompt. Chances are, you've probably seen something like this on large websites like Apple or Amazon.
   

We recommend option 2 as it provides users with a better overall experience.

Within this article

The remainder of this article is aimed at web developers with an understanding of HTML, CSS and JavaScript.

• We'll use Evance's native ev-locale cookie to store and retrieve a user's locale preference.
• Get the current locale from Evance's <meta name="ev:locale"> meta tag.
• Query the Geolocation Ajax API to get a recommended locale for the user's location and browser language preferences.
• Prompt the user to change locale.

That's a lot to do. Luckily, we've published a Geolocator object, which does most of this. It's open-source and available on Github under MIT licence, so feel free to use and modify the code to best suit your needs.

Get the Geolocator JavaScript from Github

Step 1: Download and install the Geolocator JavaScript

First, head over to the evanceit/theme-geolocator-js Github repo and copy the geolocator.js file into a new JavaScript file in your theme - ~/theme/common/js/geolocator.js.

Now include this file into your ~/theme/common/js/common.json JavaScript packaging file.

{
    "files": [
        ...
        "˜/theme/common/js/geolocator.js"
    ]
}

Step 2: Add the prompt to our Theme's layout

We have complete control over the look and feel of the "Suggested locale" prompt. That means adding some code to our ~/theme/layouts/index.evml file. We can add the prompt anywhere you like within your code.

First, we'll add a container for the prompt. 

<div id="geolocator-prompt"></div>

Next, let's add a JavaScript template to render within the prompt container.

<script id="geolocator-template" type="text/x-template">
    Visit our <%= countryName %> store in <%= currencyCode %>.
    <a href="<%= url %>">Continue</a>
    <a href="#dismiss">Stay</a>
</script>

Step 3: Invoke the geolocator

Open or add a custom JavaScript file which is available site-wide. For the purposes of this article, let's encourage code separation and add a new file to our JSON package file.

{
    "files": [
        ...
        "/portal/web/gateway/theme/v4/common/js/geolocator.js",
        "/portal/web/gateway/theme/v4/common/js/geolocate.js"
    ]
}

Within our new geolocate.js file we'll add the following code:

const geolocator = new Geolocator();
geolocator.prompt();

Step 4: Testing

To test the prompt your site will need more than one Evance Locale where the country does not match your geolocated IP address - easily done using a VPN. For example, if you are located in the UK try adding and visiting a US locale (e.g. /en-us). To test repeatedly you can remove the ev-locale cookie from your browser.

Step 5: Customise

You can now customise the messaging, look and feel of your prompt using your own HTML and CSS.

Final thoughts

We hope you found this article easy to follow. If you have any issues or suggestions to improve the geolocator.js repo please get in touch via Github.