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.
About 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.
Print location
Use the following GeoTarget location shortcodes to print the location of your users:
[geoip-continent]
[geoip-country]
[geoip-region]*
[geoip-city]
[geoip-postalcode]**
[geoip-latitude]
[geoip-longitude]
[geoip-location]
*In USA region will return state, in Canada (CA) region will return province, otherwise will return region number, which is not unique between countries.
**USA only.
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, country, postalcode.
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, not-country, not-postalcode.
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:
[geoip-content country="AT, BE, BG, HR, CY, CZ, DK, EE, FR, DE, FI, GR, HU, IE, IT, LV, LT, LU, MT, NL, PL, PT, RO, SK, SI, ES, SE, GB"] Heads up! We use cookies to ensure you get the best experience on our website. This website is also fully GDPR compliant. Head to http://mydomain.com/privacy/ to request a DPA if your organization requires one.[/geoip-content]
Testing Shortcodes
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:
yourdomain.com/?geoip®ion=TX
To test how your homepage content may displayed to a user in Austin, Texas, use the following arguments:
yourdomain.com/?geoip&country=US
GeoTarget allows support for the following arguments:
?geoip&country=
?geoip®ion=
?geoip&city=
?geoip&continent=
?geoip&areacode=
?geoip&postalcode=
You can also combine the arguments:
yourdomain.com/?geoip&country=CA&city=Toronto®ion=ON
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:
Country: HTTP_GEOIP_COUNTRY_CODE
Areacode: HTTP_GEOIP_AREA_CODE
Region: HTTP_GEOIP_REGION
City: HTTP_GEOIP_CITY
Postalcode: HTTP_GEOIP_POSTAL_CODE
Latitude: HTTP_GEOIP_LATITUDE
Longitude: HTTP_GEOIP_LONGITUDE
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 HTTP_GEOIP_COUNTRY_CODE.
You can also use the PHP environment variables to pass GeoTarget data to JavaScript. For an example of how to pass this data to JavaScript, check out this example where the developer uses the user’s country to determine whether to display a GDPR popup box.
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:
View list of MaxMind country codes
View list of MaxMind continent codes
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:
Caveats
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.
MaxMind Database
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.
Use GeoTarget to measure distance with latitude/longitude
While the GeoTarget plugin also allows you to calculate distance between latitude and longitude markers, this measurement system may not always be accurate. Latitude, Longitude, and ZIP code measurements tend to be the most inaccurate in the GeoIP database from MaxMind. Measuring distance in this way is not recommended. For more information, see MaxMind’s guide to database accuracy.
Measuring distance with markers could be useful for determining approximate distances, but results may be cached at the state or country level, depending on your configuration. For example, I could use the following example to measure the distance from a fixed latitude/longitude marker, perhaps an office location, to the end user. In this method the GeoTarget plugin does basic distance calculations between the fixed point and the end user.
$latitude = 30.268246;
$longitude = -97.745992;
$geo = WPEngine\GeoIp::instance();
if ( false !== $geo->distance_to( $latitude, $longitude ) ) {
$miles_to_wp_engine = $geo->distance_to(
$latitude, $longitude );
}
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.