TABLE OF CONTENTS

  1. Introduction
  2. Caching Plugins
    1. Comet Cache (both free and paid version)
    2. WP Super Cache
    3. WP Rocket
    4. W3 Total Cache
    5. WP Fastest Cache
    6. LiteSpeed Cache
    7. Breeze Caching
  3. Caching Servers
    1. Nginx
    2. Varnish
  4. Caching services and CDNs
    1. CloudFlare
    2. BunnyCDN
    3. Sucuri CloudProxy
    4. Incapsula
    5. WP Engine
    6. SiteGround
    7. Kinsta
    8. GoDaddy
    9. HostGator Endurance Cache
    10. Pressidium
  5. Temporary workaround - The Cache Handler plugin
  6. Technical details
  7. Notes


1. Introduction

Implementing dynamic caching depends on which caching system you use. Some caching systems can handle dynamic caching, and can serve different content depending on the selected currency (and other parameters), while others are too rigid and must be disabled on catalogue pages.In this article you can find our recommended approach for the most common caching systems. 


Important
  • The solutions offered are provided as a reference, and may have to be adapted to your specific site. We cannot offer free support in relation to them. If you need assistance implementing them, you can avail of our paid support services. 
  • Unless otherwise specified, where a caching plugin is described as compatible with the Aelia plugins, such compatibility is based on a claim from the caching plugin's authors. We, at Aelia, can't verify such claims, and simply publish them when the caching plugin's authors contact us. If you need assistance with a caching plugin that is supposed to be compatible with the Aelia plugins, you should contact the authors of the caching plugin directly.
  • If you use our Currency Switcher for WooCommerce, make sure that the plugin's geolocation feature is enabled in WooCommerce > Currency Switcher Options > Geolocation(see below).

    This is required for the solutions below to work correctly.
    Please note that this geolocation option is independent from the one provided by WooCommerce 2.4 and later. We normally recommend to keep WooCommerce geolocation feature disabled, to improve performance, as dynamic caching doesn't need it.

2. Caching Plugins


Comet Cache (both free and paid version)

Comet Cache supports dynamic caching out of the box, both in the free and paid versions. To use such feature, please follow the instructions below:
  1. On your site, create folder /wp-content/ac-plugins.
  2. Download the Aelia Advanced Caching Plugin for Comet Cache/ZenCache (file aelia-zencache-ac-plugin.zip).
  3. Extract the caching module in the folder you created at step #1. Note: the file must be saved directly in that folder, not in a subfolder.
Comet Cache will load the Advanced Caching Module automatically, serving the correct content depending on the active currency, customer's country, and so on. No configuration is required.

WP Super Cache


Important disclaimer

The solution described below might not work with recent versions of WP Super Cache. If the solution doesn't seem to work, we would recommend to switch to a plugin which includes support for the Aelia plugins, such as Comet Cache, WP Rocket or Litespeed.


To add dynamic caching to Super Cache, please follow the instructions below:

  1. Create a folder for the Super Cache plugins in /wp-content. For example, /wp-content/wpsc-plugins.
  2. Download the Aelia Advanced Caching Plugin for WP Super Cache (file aelia-wpsupercache-ac-plugin.zip).
  3. Extract the caching module in the folder you created at step #1.
  4. In wp-config.php, add the following line:
    $wp_cache_plugins_dir = '<full path to the folder you just created>';

    Example
    $wp_cache_plugins_dir = '/var/www/yoursite/wp-content/wpsc-plugins';

    This will make Super Cache look for its plugins in the folder you just created, instead of the default folder /wp-super-cache/plugins/. This change is needed because, when you update Super Cache, the whole WPSC plugin folder is deleted and recreated. By keeping the module outside of the plugin folder, it will be preserved when you update Super Cache.
  5. Configure Super Cache to set the caching mode to PHP or Legacy and enable dynamic caching (see below).

    Fig. 1 - Configure Super Cache in PHP or Legacy mode

    Fig. 2 - Enable Dynamic Caching

  6. Depending on your specific setup, you might also need to enable the "Late init" option in Super Cache settings (see below).
    Fig 3. - Enable Late Init


    Alternatively, you can add the following line to your wp-config.php file:

    $wp_super_cache_late_init = 1;

    If your page source contains a note saying "Super Cache dynamic page detected but late init not set. See the readme.txt for further details.", changing this setting should fix it (see Super Cache FAQ for technical details). Please note that this is not a requirement introduced by our plugin, it's how Super Cache handles dynamic caching.


That should be all. Your page will now be cached dynamically, taking into account information such as customer's currency, country and so on.

Should you encounter any difficulty configuring dynamic caching with WP Super Cache, we recommend that you open a support request on the plugin Support page (its developers know it in more details and will be able to help you troubleshooting any issue you might have with it).


WP Rocket

WP Rocket supports dynamic caching from version 2.7, available since the 11th March 2016. There is no configuration required to enable dynamic caching in such version. Simply install it, and dynamic caching will be enabled out of the box. Starting with version 2.8.15, WP Rocket also supports our Prices by Country or Tax Display by Country plugins. If you use an older version of WP Rocket, you will have to disable caching on catalogue pages to ensure that the correct content is displayed to visitors, or use an alternative solution.


Important notes 

  1. Installing WP Rocket on a site hosted by WP Engine won't introduce dynamic caching. This is because, in such configuration, the caching is still handled by the WP Engine systems, which don't support dynamic caching, while WP Rocket takes care of elements such as images, scripts and styles. If your site is hosted by WP Engine, we recommend to refer to the related section, below. The proposed solutions are still applicable, even after installing WP Rocket.
  2. When used with the Aelia plugins, WP Rocket will behave as follows:
    - Visitors who reach the site for the first time will see an uncached version of the page. This is to allow the geolocation feature to identify visitor's location and set the correct country and currency cookies.
    - Returning visitors will see cached content, as usual.

    This means that first visits will always be uncached. Testing tools always appear as first time visitors, as they discard the cookies set during the identification, therefore they will report a slower page speed than the one experienced by visitors from the second page load onward.

Update about WP Rocket - January 2021
Based on our tests, it should be possible to "trick" WP Rocket into serving cached content to first time visitors. To do this, one has to perform the geolocation before the caching logic is applied. This can be done with some custom code, which has to be tailored to the specific site where it's going to run, to set the cookies used by the Aelia plugins and WP Rocket to determine the content to serve (see Technical Details section, at the bottom of this article).

Please be aware that, although this approach can work, it's not officially supported by WP Rocket. Due to that, the WP Rocket Team can't help with its implementation. If needed, we are happy to offer our consultation services (paid services) to assist with the scoping, implementation and testing of a custom solution for your site. Please feel free to contact us for more information and for an estimate: https://aelia.co/contact.


W3 Total Cache

W3 Total Cache does not support dynamic caching (which is different from the fragment caching feature that the plugin includes), due to restrictions in its architecture. The dynamic caching feature has been requested some time ago, therefore it's possible that will be introduced in the future. In the meantime, if you use such plugin, you can either switch to another solution (recommended), or install the free WooCommerce Cache Handler plugin.


WP Fastest Cache

WP Fastest Cache does not support dynamic caching, due to restrictions in its architecture. You can either switch to another solution, which supports dynamic caching (recommended), or install the free WooCommerce Cache Handler plugin as a workaround.


Note

By default, WP Fastest Cache doesn't cache a page if the URL contains a query string (i.e. URL arguments, such as https://example.org?arg=value). If you use the Cache Handler plugin in "redirect" mode, that will add a query string to each page, and this might cause WPFC to not serve cached content. To prevent this issue, you can try enabling the WPFC_CACHE_QUERYSTRING option in your site's settings. For more information, please refer to the following article: https://www.wpfastestcache.com/tutorial/cache-url-with-querystring/. 


Should you have any question about configuring WP Fastest Cache to take into account URL arguments, please contact their support team directly: https://wordpress.org/support/plugin/wp-fastest-cache


LiteSpeed Cache

The LiteSpeed Cache plugin introduced support our plugins since version 2.6. Please contact its authors to learn how to configure it.


Should you encounter any compatibility issue when using LiteSpeed with the Aelia Currency Switcher or other Aelia plugins, please contact the LiteSpeed support team. You can do so by posting a support request on the LiteSpeed plugin page: https://wordpress.org/support/plugin/litespeed-cache..


Breeze Caching

On the 26th of October, 2023, the developers of Breeze Caching informed us that their caching solution is now compatible with our Aelia Currency Switcher. Below you can find some notes about the compatibility feature, directly from the Breeze Caching developers:


The fix applied in Breeze cache plugin contain to use cookie of Currency Switcher plugin and save in different HTML cache files for each currency respectively. Now Breeze is fully compatible with Aelia Currency Switcher Plugin. 

If Varnish is active, you will need to exclude the cookie of Aelia currency switcher plugin "aelia_cs_selected_currency" from Varnish settings. The following article explains how you can do that: How to exclude cookies from the Varnish cache


After doing that, Breeze Caching will take care of serving the correct currency-specific content to the users.



3. Caching Servers


Important disclaimer

The instructions and settings provided may need to be adjusted to your specific environment. Reviewing, installing and testing the custom settings described for caching servers, like Nginx and Varnish, will be up to your hosting provider. We cannot take responsibility, nor offer assistance in relation to server issues that may occur after applying the suggested changes. We strongly recommend to test the settings thoroughly, as their use will be at your own risk.


If your hosting provider can't assist you with the implementation or troubleshooting of the server settings, we would recommend to contact an expert for that purpose. Unfortunately, we can't offer this kind of services, but you can find an expert on Codeable. Referral shortcut: https://aelia.co/hire_expert.


Nginx

Nginx can handle dynamic caching with the appropriate configuration. Below you can find an example of how you can configure Nginx for that purpose.


IMPORTANT

  • This is an example configuration file, and the settings apply to the entire server. You should probably adapt these settings to apply to a specific location, instead, so that they only affect your specific ecommerce site. 
  • If you enter an incorrect configuration in Nginx, your web server could crash. If you are not familiar with Nginx configuration, we recommend to contact your developer, or hosting provider, who should be able to adjust the settings for you. We cannot provide assistance with the configuration of Nginx. 
    # Add Aelia cookies to the cache key. This will create multiple copies of each
    # cached page (one for each combination of currency, country and province/state)
    proxy_cache_key "$scheme$request_method$host$request_uri $cookie_aelia_cs_selected_currency$cookie_aelia_customer_country$cookie_aelia_customer_state$cookie_aelia_tax_exempt";
    
    # IMPORTANT
    # This is an example configuration file, and the settings apply to the entire server.
    # You should probably adapt these settings to apply to a specific location, instead,
    # so that they only affect your specific ecommerce site.
    #
    # If you are not familiar with Nginx configuration, we recommend to contact your
    # developer, or hosting provider, who should be able to adjust the settings for you.
    server {
      listen 80;
      server_name www.example.org;
    
      set $no_cache 0;
      # If none of the Aelia cookies are set, disable caching. This will ensure that
      # the page is loaded dynamically, and that cookies are set at the next load
      if ($cookie_aelia_cs_selected_currency$cookie_aelia_customer_country$cookie_aelia_customer_state$cookie_aelia_tax_exempt ~* "") {
        set $no_cache 1;
      }
        
      # Don't pull from cache based on $no_cache
      fastcgi_cache_bypass $no_cache;
      # Don't save to cache based on $no_cache
      fastcgi_no_cache $no_cache; 
    }


 

Varnish

If your server uses Varnish, that service may remove the currency selection cookie. This may cause your server to store and serve the same content to all your visitors. In such case, you should contact your System Administrator to amend the configuration, so that the country and currency cookies are taken into account when serving cached content.


You can refer to the following article to learn how to configure Varnish for dynamic caching: Cache WooCommerce Currency from GeoIP with Varnish 4 vmod.


If you are using Varnish and CloudFlare together, please refer to the following article to learn how to leverage the geolocation capabilities offered by CloudFlare within Varnish: Cache WooCommerce Currency from CloudFlare GeoIP with Varnish 4.


If you can't amend Varnish settings to implement dynamic caching, then you should either disable Varnish, or use the free WooCommerce Cache Handler plugin to work around such limitation. Caching of resources, such as JavaScript, CSS and images, can be left enabled.


4. Caching services and CDNs


CloudFlare

CloudFlare supports dynamic caching, but only on Enterprise plans. With any other plan, there are two options to ensure that the correct content is served:

  1. Recommended: create a page rule for the whole website (see: https://support.cloudflare.com/hc/en-us/articles/218411427-Understanding-and-configuring-Cloudflare-Page-Rules-Page-Rules-Tutorial-) and set the caching level to Standard.

    In this mode, CloudFlare doesn't cache the HTML content, which is served by the site. The site can then use a service, or plugin, properly configured to store and serve the correct content, based on visitor's country and/or currency. 
  2. If the caching mode is set to "Cache Everything", then it becomes necessary to install the free WooCommerce Cache Handler plugin, which acts as a workaround to show the correct content. 


Setting the CloudFlare caching level

The CloudFlare caching level should be set to Standard:

Please refer to the CloudFlare documentation for more information on how to configure the caching level: https://developers.cloudflare.com/cache/how-to/set-caching-levels/.


BunnyCDN

The BunnyCDN service allows to serve different content based on the value of specific cookies. You can find the documentation of this feature here: https://bunny.net/blog/introducing-vary-cache-by-cookie-value/


To use the Vary Cache by Cookies feature with our solutions, the configuration should be the following:

  1. Enable the feature in the BunnyCDN control panel by selecting "Cookie Value".
  2. Enter the names of the cookies used by the Aelia solutions in the "Cookie Names" field.
     You can find the list of cookie names to be entered in the Technical Details section, below.


This should be sufficient to ensure that BunnyCDN serves the correct content, based on the cookies used by our plugins. If you need assistance configuring the CDN service, please refer to the BunnyCDN documentation and to their support service.


Sucuri CloudProxy

Sucuri CloudProxy doesn't yet supports dynamic caching. As with CloudFlare, you will have to disable it on catalogue pages, or install the free WooCommerce Cache Handler plugin. Caching of resources, such as JavaScript, CSS and images, can be left enabled.


Incapsula

The caching service provided by Incapsula doesn't yet supports dynamic caching. As with CloudFlare, you will have to disable it on catalogue pages, or install the free WooCommerce Cache Handler plugin. Caching of resources, such as JavaScript, CSS and images, can be left enabled. 


WP Engine

WP Engine does not yet support dynamic caching. We provided them with detailed information on how they could implement it, and they acknowledged that it could be a useful feature. However, they could not confirm if they would be able to implement it, nor when. Until they add such feature, you can disable caching on catalogue pages, or install the free WooCommerce Cache Handler plugin .


You can find more details about WP Engine's caching, and how to test and troubleshoot it, in the following article: WP Engine - How to address the issues caused by caching.


SiteGround

SiteGround offers several levels of caching. Their static caching will work fine, as it caches static resources, such as CSS and JavaScript. Their dynamic caching, despite its name,  is not really dynamic, it's static caching of dynamic content. It's possible, however, to use the SiteGround static caching feature together with one of the plugins listed above, to get optimal performance.


If you wish to enable the SiteGround's dynamic caching, you will have to install the free WooCommerce Cache Handler plugin to ensure that the correct content is served to your visitors.


Kinsta

Kinsta can implement the custom rules for Nginx and/or Varnish, directly on their servers. You can simply contact them, and ask them to implement the custom configuration to support the Aelia Currency Switcher, Aelia Prices by Country, or Aelia Tax Display by Country, and they will be able to do that for you.


GoDaddy

GoDaddy's caching does not yet support dynamic caching. Until they add such feature, you can disable caching on catalogue pages, or install the free WooCommerce Cache Handler plugin.


HostGator Endurance Cache

The Endurance Cache solution does not yet support dynamic caching. Until they add such feature, you can disable caching on catalogue pages, or install the free WooCommerce Cache Handler plugin.


Pressidium

Pressidium can implement the custom rules for Nginx and/or Varnish, directly on their servers, if you have a business plan or higher. If you have another plan, which doesn't allow such customisation, and you wish to enable the caching on Pressidium servers, you can install the free WooCommerce Cache Handler plugin to ensure that the correct content is served to your visitors


5. Temporary workaround - The Cache Handler plugin


 Important! The Cache Handler is meant as a temporary workaround to the limitations of caching systems. We recommend to use it for the time needed to configure your caching correctly. We also recommend to test the site thoroughly, after enabling the Cache Handler, to ensure that all pages load correctly.


The Cache Handler plugin can work around the limitations of rigid caching systems. Its purpose is to ensure that the correct content is served to the visitors, depending on their country, province, currency and tax status. Configuring the plugin is simple.


1. Download the Cache Handler plugin from our site.

2. Upload and activate the plugin. 

3. Go to WooCommerce > Settings > Cache Handler to configure the plugin. 

xLaPrZ397NXMuw5F1TYjIE2wlnDrcnur5g.png

You will be presented with three options:
  • Disabled
    The Cache Handler will be disabled and won't do anything.
  • Enable Redirect
    The Cache Handler will use the same redirect mechanism adopted by WooCommerce to redirect users to the correct content. Visitor's will be redirected to pages that have a unique page identifier appended to the URL (e.g. http://example.org?ph=23985623985). The identifier will be unique for the combination of country, province, currency and tax status, and it will ensure that visitors will see the correct content.
  • Enable Ajax Loader
    The Cache Handler will use Ajax to load prices dynamically on each page. This method will trigger an Ajax request that will update "on the fly" all the prices found on a page. Its main drawback is that it cannot handle prices introduced by other plugins (e.g. pricing tables, product addons, etc). If you use that type of plugins, you should use the Enable Redirect method instead.

4. Choose the option that works best for your site, and save the settings.

5. Clear all the caching systems you are using (plugins, Nginx, Varnish, CloudFlare, etc). This is important, as it will allow the Cache Handler to add its scripts to your pages, and ensure that the correct content is served.


Important note

When the Enable Redirect option is enabled, the Cache Handler adds an argument to each page URL, which then looks like the following: https://www.example.org/?ph=1234567890476357. That argument is used to create a unique URL, based on the combination of currency, country and province/state, and "trick" caching systems into storing and fetching a separate copy of the content for each unique URL. For this system to work, it's imperative that the caching system running on the site are configured to take into account the full URL, including the extra argument, and store and serve each copy separately. In other words, URLs like:


And so on, must be considered different by the caching systems and cached separately. If the caching system is configured to ignore URL arguments, then it will treat all URLs as if they were just "https://www.example.org/". That will prevent the caching workaround from working correctly, and could cause issues like infinite page reloads.



6. Technical details


If you would like to implement your own custom dynamic caching logic, you will have to keep track of the values of the following cookies:

  • aelia_cs_selected_currency - The active currency. This cookie is always set by the Aelia Currency Switcher.
  • aelia_customer_country - Visitor's country. This cookie is always set by the Prices by Country and by the Tax Display by Country plugins. It can also be set by the Aelia Currency Switcher, if the "force currency by country" option is enabled.
  • aelia_customer_state - Visitor's State/Province/County. This cookie may be set by the Tax Display by Country plugin, if the option "handle customer's State/Province/County" is enabled.
  • aelia_tax_exempt - Flag indicating if the customer is exempt from tax. This cookie is set by the Tax Display by Country plugin if the customer ticks the checkbox labelled "I'm exempt from VAT, show me prices exclusive of tax" on the country selector widget.
You should use the above information to generate a separate cache key for each combination of values, so that the same URL can show different content. That is, while the cache key is usually just the page URL, thus serving one content for one URL, the new cache key will have to be "URL + aelia_cs_selected_currency + aelia_customer_country + aelia_customer_state + aelia_tax_exempt".

In past versions, the plugins used a cookie named aelia_billing_country. That cookie is no longer used by newer versions of Aelia plugins and can be ignored.

For the cookies to be set properly, the flow should be the following:
  1. First visit. The visitor doesn't have any of the above cookies set. Skip the cache entirely. This will allow the page to load dynamically, identify the visitor and set the cookies.
  2. Second and subsequent visits. One or more of the cookies are set. Append them to the URL requested by the visitor to generate the cache key. This will effectively create a copy of the content for each combination of the URL and the value of each cookie, and ensure that each visitor sees the content that applies to him.



7. Notes

In all cases in which caching has to be disabled, it's possible to keep caching of static content enabled. For example, caching can be used to minify JavaScript and CSS, thus reducing the amount of HTTP requests sent to the server, speeding up the page.


You can purchase our internationalisation solutions from our online shop.