WP Engine’s powerful GeoTarget add-on is a great way for users to create customized and targeted content for users in different locations, while still maintaining cacheability and scalability of your site. In this article we will explain how developers can use GeoTarget to implement custom content and functions.
Before getting started, be sure you have fully enabled GeoTarget.
Users often face the struggle of finding a cacheable solution when implementing their geographically-customized content. For example, if a user wanted a Canadian phone number to show only for users in Canada and a US phone number to show for users in the United States, a developer would need to manually regenerate HTML for the page via PHP on every single page load, based on where the user is located. With GeoTarget, WP Engine’s proprietary page caching system (Evercache) will store variations of the page for each geographic location in cache. Our GeoTarget system uses the GeoIP database from MaxMind to determine where the user is from, and serves them cached version commensurate with their location. This allows your site to scale better with waves of traffic while still providing a custom experience!
How to Use GeoTarget Shortcodes
After enabling the GeoTarget system by installing the plugin and contacting Support, you will be able to use the GeoTarget shortcodes in your website’s Pages, Posts, and Widgets. GeoTarget Shortcodes are ideal to use when customizing different content to be displayed to your users around the globe. If you wish to perform PHP functions by using GeoTarget, such as redirects, popups, or custom banner messages, skip down to the GeoTarget PHP Environment variables section.
Use the following GeoTarget location shortcodes to print the location of your users:
*In USA region will return state, in Canada (CA) region will return province, otherwise will return region number, which is not unique between countries.
To print out these variables, use the shortcodes in your Post, Page, or Widget as follows:
Welcome to our website! Hope the weather is great in [geoip-city], [geoip-region], [geoip-country].
If I was visiting this website from Round Rock, Texas, the output would be as follows:
Welcome to our website! Hope the weather is great in Round Rock, TX, US.
Print conditional content based on location
You can use the
geoip-content shortcode to display different content conditionally based on the geographic location of your users. The basic format of the shortcode is as follows:
[geoip-content bucket="value"]Your geographically-specific content here.[/geoip-content]
Your “bucket” can be any of the following values: continent, city, region, areacode, and country.
For example, if you wanted to say, “Guten tag” to users connecting from Germany, you could use the
geoip-content shortcode like so:
[geoip-content country="DE"]Guten tag![/geoip-content]
If you wanted to also say, “Bonjour” to customers connecting from France on the same page, you could use the shortcode in this way:
[geoip-content country="DE"]Guten tag![/geoip-content][geoip-content country="FR"]Bonjour![/geoip-content]
You can also use the “not-bucket” syntax to HIDE content from specific geographies. For example, if you wanted to print, “Hello” to all of the US, but, “Howdy” to Texas specifically, you could use this logic:
[geoip-content country="US" not-region="TX"]Hello![/geoip-content][geoip-content region="TX"]Howdy![/geoip-content]
Your “not-bucket” can be any of the following values: not-continent, not-city, not-region, not-areacode, and not-country.
You can use GeoTarget to inform only EU visitors about GDPR privacy regulation compliance for your site while hiding this information from other users around the world. For example, you may not want to display GDPR messages to visitors from the US or other countries who are not subject to these regulations. On your “About Us” page, you could display a message indicating the website’s compliance by using the following code:
Testing geographically customized content may present a challenge. Some developers may use a Virtual Private Network (VPN) to “spoof” a user’s location. With GeoTarget, you can “spoof” locations by adding arguments to the end of the URL you wish to test. Please note: Spoofing locations in the following way will only work when testing the GeoTarget shortcodes, not when leveraging GeoTarget via PHP code.
To test how your homepage content may display to a user in Texas, use the following argument:
To test how your homepage content may displayed to a user in Austin, Texas, use the following arguments:
GeoTarget allows support for the following arguments:
You can also combine the arguments:
Shortcode Best Practices
- Apply shortcodes to multiple regions and separate by using commas. For example:
[geoip-content country="US, CA, BR, MX"]Americas content here[/geoip-content].
- Exempt regions by narrowing specificity. For example:
[geoip-content country="US" not-region="TX, CA, OR"]Content for everyone but Texas, California, Oregon[/geoip-content]OR
[geoip-content region="TX" not-city="Austin, Dallas"]Content for everyone but Austin and Dallas[/geoip-content].
- Don’t get too granular or specific with your content. For example:
[geoip-content city="Austin"]Hi person from Austin![/geoip-content] [geoip-content city="Los Angeles"]Hi person from Los Angeles![/geoip-content] [geoip-content city="New York"]Hi person from New York![/geoip-content]. Instead, use the geolocation shortcodes as follows:
"Hi person from [geoip-city]!"
- Don’t make an exception to an exception. For example:
[geoip-content continent="EU" not-country="DE" city="Berlin"]Content to show to Europe, but exclude all of Germany except Berlin[/geoip-content].
- Use two shortcodes in lieu of making an exception to an exception. For example:
[geoip-content continent="EU" not-country="DE"]Content to show to Europe, but exclude all of Germany[/geoip-content][geoip-content city="Berlin"]Content to show to Berlin[/geoip-content].
- Don’t exempt a city that exists in two countries to which you are showing content. For example:
[geoip-content country="US, FR" not-city="Paris"]Content to exempt from Paris, France[/geoip-content]. This would exempt Paris, TX and any other city in the US named “Paris.” Instead, use two shortcodes to achieve the desired results. For example:
[geoip-content country="FR" not-city="Paris"]Content to show to all of France except Paris[/geoip-content][geoip-content country="US"]Content to show to US[/geoip-content].
PHP Environment Variables for GeoTarget
If you need to create a PHP function to perform an action based on a GeoTarget variable, you will need to include the PHP environment variables to do so. Shortcodes used in the GeoTarget plugin may not be used in your PHP code. As such, you will need to retrieve the environment in your PHP code as follows:
getenv( 'HTTP_GEOIP_COUNTRY_CODE' )
WP Engine’s GeoTarget system supports the following environment variables:
For an example of how to implement these PHP environment variables in your code, check out this example function to perform a redirect based on
MaxMind Country, Continent, and Region Codes
The accepted country and continent codes used in GeoTarget come from MaxMind can be viewed at the following links:
Note: For “region,” the MaxMind database will use the standardized postal two-letter state or province abbreviation for US or Canada. Other global “region” variables use the ISO-3166 standard which include numeric region codes. These numerical region codes may be reused in multiple countries.
For example, if you plan on using a numeric region, be sure to narrow the result by including the country. For example:
[geoip-content country="CN" region="23"] Content only for Shanghai, China [/geoip-content]
This is because can be many regions with the same number, in different countries. Without specifying the country, the following code will display in any country with a region 23, which includes Tierra Del Fuego, Argentina; Qina, Egypt; and Offaly, Ireland:
[geoip-content region="23"] Content only for Shanghai, China [/geoip-content]
For a full list of region variables accepted by GeoTarget, view the following CSV provided by MaxMind:
When using GeoTarget there are some caveats to keep in mind. Due to the nature of GeoTarget there are some discrepancies users may experience that are outside of the control of WP Engine.
GeoTarget uses locations from the MaxMind GeoIP database. WP Engine does not control or update this database. For example, if unincorporated land became a city between the last time the MaxMind GeoIP database was updated and today, and a visitor from that city accessed your website, their city might not be interpreted correctly. If you need to submit a data correction request, you can use the MaxMind correction request form to do so.
Proxies and VPNs
When customers access your website from an anonymous proxy or VPN, they may see content intended for a different audience as a result. Because a VPN or proxy service sends the request from a separate web server which may be located in another region, it’s possible that someone from one region may be presented with content intended for another. For example, if you use a proxy that allows a user to browse from a British IP address, you may see content with the “GB” country code because that is where the IP address is located, even if you are truly in the US.
Performance Best Practices
GeoTarget is unique in that it allows you to create customized content for users that also plays nice with cache. Each version of the page content is stored in its own cache “bucket” to serve to other users in that same bucket group. However, if you display different content for lots of extremely specific regions, you may “over-segment” your cache. This makes your cache less effective. In order for your site to scale effectively, you may want to make content for fewer, broader regions.
GeoTarget and GDPR
GeoTarget is a system which stores all location data client-side. This means WP Engine servers do not view or store data from your website’s users. As such, the Data Protection Acts do not apply to the location data stored by WP Engine GeoTarget. Read more about Location Data Regulations with GDPR.
WP Engine Scope of Support
The WP Engine Support team is available to assist with your GeoTarget questions via Live Chat, 24/7. Remember, our Support team cannot assist you with creating custom PHP code snippets. However, we are glad to explain how GeoTarget should work, best practices, and show you how to test your GeoTargeted content in your Posts and Pages.