Synchronous and asynchronous loading

How to load and use the Woosmap Recommendation

The script can be loaded in two ways:

  • Synchronously, where scripts are loaded one after another, starting with the <head> tag
  • Asynchronously, where some scripts can be loaded simultaneously

Loading a script asynchronously has the advantage of not slowing the page down, but it can cause a “flicker” on the page, where the original page loads, followed shortly by the variation page. Woosmap uses a synchronous snippet to prevent flickering and has invested in a CDN system to make sure the impact on the page is minimized.

Synchronous loading: the preferred approach

As the purpose of the library is to adapt the content of your page based on the visitor location, we recommend using the synchronous loading to avoid the potential of a flicker on the page.

Add your snippet to the <head> tag of your site

The Woosmap recommendation snippet must be installed in the <head> tag of the HTML to ensure optimal performance. We recommend installing the Woosmap snippet as high up in the head tag as possible, generally after your <html> tag, charset declarations, and possibly other meta tags.

Here’s the Woosmap Snippet for synchronous loading:

<!-- Woosmap Recommendation -->
<script src=""></script>
<!-- End Woosmap Recommendation -->

And here’s what the snippet may look like on a page:

<!DOCTYPE html>
<html lang="en">
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   <!-- Add other meta information here -->
   <!-- Add stylesheets here -->
   <script src=""></script>
   <!-- Add scripts and other content here -->

Why in the top of the head tag?

If the snippet is added anywhere other than the top of the head tag, it will technically still work. But if the page has already loaded a lot of content that the visitor sees before the Woosmap snippet loads, then the original version of the page may load before being transformed into the variation. This is known as “page flickering”. In most cases the code executes too quickly for this to be visible, but to avoid any potential problems we encourage you to add the snippet as early on in the execution path as possible.

Asynchronous loading: benefits and drawbacks

Loading asynchronously will prevent any delay in pageload, because the page will attempt to load all elements simultaneously, including the Woosmap recommendation script.

However, there is a major drawback: when the script is loaded much later than the page and you use the recommendation to adapt the page content, a flicker of the page can occur. This is where the original page loads, followed by the variation. This will make the outcome of your experiment less reliable and could compromise your visitor experience.

Here’s the Woosmap Snippet for asynchronous loading:

<!-- Woosmap Recommendation -->
  var recoScript = document.createElement('script');
  recoScript.async = true;
  recoScript.src = '';
<!-- End Woosmap Recommendation -->

Corresponding to the previous advice, we recommend to add the script loading before the closing </head> tag. If the snippet is added anywhere other than the top of the head tag, it will technically still work.

Enjoy the Recommending API

Once the snippet loaded, you will have to set your project_key that correspond to your data before benefit from the Recommendation location based. You could then play with the Woosmap Recommendation methods.


The recommendation object is directly created when you import the javascript file. Nevertheless you should set your project key before use any available method.

// Get the first recommended (closest) store for your current visitor
    successCallback: function (stores) {
             if (stores && stores.features && stores.features.length > 0) {
                //get attributes for first returned store
    errorCallback: function () {
        //do a fallback
    limit: 1

You can find a complete example on js-fiddle


In asynchronous mode you cannot directly use woosmapRecommendation so you should use the global rRequestQueue instead.

rRequestQueue = [];
rRequestQueue.push(['setProjectKey', ['your_project_key']]);
                   [{successCallback: function (stores) {
                     if (stores && stores.features && stores.features.length > 0){
                        console.log(stores.features[0]) //get attributes
                    limit: 1}]]);

You can find a complete example on js-fiddle

Contributing to Recommendation

In order to build profiles and benefit from the recommendation, every implementation must contribute to collecting location data through users’ digital journey. See Contributing doc for more details.

Recommendation methods

Documentation for all methods is available here.