Geolocating visitors with Evance front-end API
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:
- Redirect users automatically. This is the easiest to implement, but may not offer the best user experience.
- 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.
Get the knowledge and inspiration
Get the knowledge and inspiration you need to build a profitable business — straight to your inbox.
Unsubscribe any time! / Privacy Policy