Geographically Customized Content with GeoTarget

GeoTarget is a user segmentation system that allows users the ability to show different content or perform different actions based on the geolocation of their visitors. The GeoTarget system is unique in that it also plays nicely with WP Engine’s server cache. Page content is cached as separate objects for separate regions allowing your site to show customized content, while still maintaining cacheability and scalability.

---

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 will store variations of the page for each geographic location in separate cache segments. Our GeoTarget system uses the GeoIP database from MaxMind to determine where the user is from, and serves them cached version from their location. This allows your site to scale better with waves of traffic while still providing a custom experience.

With other integrations, you get GeoTarget from a Javascript library, but that loads only after the page has already been generated by WordPress, and therefore you cannot make code-based modifications based on the geography. There’s also often a “flash” or other effect because the page is rendered before the Javascript gets a chance to do something differently.

Also, other page-caching systems are not flexible enough to be able to be tuned for specific GeoTarget use-cases, which means you generally have to disable page-caching, severely hampering your speed and scale.

Rather than creating your own implementation of rules based on a GeoIP database, WP Engine minimizes the needed technical effort from your team by managing the complex configuration of these rules, as well as the back-end settings to cache page variations separately. Enablement of GeoTarget in three simple steps unlocks the ability to segment pages by geography, so you can focus on building the content.

---

Enable GeoTarget

In this section we will outline the recommended steps to fully activate the functionality. After GeoTarget is enabled, users can create geographically-specific content and PHP functions using the proper GeoTarget variables.

Purchase GeoTarget Add-on

Customers on dedicated and enterprise hosting plans will have GeoTarget included at no additional cost.

If your plan is Startup, Growth or Scale then there are two ways you can purchase GeoTarget for your account.

First, if you have an existing account, simply reach out to your Account Manager . Otherwise, GeoTarget can be added to your plan from User Portal, under Billing > Modify Plan (Click here for a direct link).

Add WP Engine GeoTarget Plugin

1. Login to your website’s wp-admin dashboard area
2. Click Plugins and select Add New
3. Search for WP Engine GeoTarget
4. Install and Active the GeoTarget plugin

Like any WordPress plugin, WP Engine will update the GeoTarget plugin from time to time. When an update is released, you will be able to update it in your WordPress Dashboard.

Enable a GeoTarget Profile

Finally, you will need to contact our Support team to enable the GeoTarget profile for the environment(s) on which you wish to use the feature. This profile defines the “buckets” that GeoTarget can use on each site.

Contact WP Engine Support and provide the following information:

1. Environment name(s) for GeoTarget
2. Bucket(s) to enable
3. Support PIN for verification
   • Your user must have access to all environments for which you are enabling GeoTarget.

GeoTarget is able to sort visitors into specific geographic caching “buckets”. Ideally you will choose the broadest bucket(s) that achieves your goals. In most cases 1 bucket is enough, however we do not recommend using more than 2 buckets.

The more specific and granular the bucket, the more segmented your cache will be. The more cache segments, the less effective cache is. This will impact performance as your traffic scales. Wider geographic buckets are best for both cacheability and scalability.

Available caching buckets:

• Continent
• Country
• State/Region
• City

---

GeoTarget Shortcodes

After enabling the GeoTarget system, 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.

Print location

Use the following GeoTarget location shortcodes to print the location of a user:

[geoip-continent]
[geoip-country]
[geoip-region]
[geoip-city]
[geoip-postalcode]
[geoip-location]

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 “Austin, Texas, US” the output would be as follows:

Welcome to our website! Hope the weather is great in Austin, TX, US.

Print Conditional Content

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
• postalcode
• region
• 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 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.

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]

Hide Content from Specific Geographies

Use the “not-bucket” syntax to HIDE content from specific geographies.

Your “not-bucket” can be any of the following values:

• not-continent
• not-city
• not-region
• not-postalcode
• not-country

For example, if you wanted to print, “Hello” to all of the US, but only to Texas visitors print “Howdy”, use this logic:

[geoip-content country="US" not-region="TX"]Hello![/geoip-content][geoip-content region="TX"]Howdy![/geoip-content]

---

Test Shortcodes

Testing geographically customized content may present a challenge. For example, you could use a Virtual Private Network (VPN) to “spoof” a user’s location. With GeoTarget, you can actually “spoof” locations much more easily just by adding arguments to the end of the URL you want to test.

To test how your homepage content may display to a user in Texas, use the following argument:

yourdomain.com/?geoip&region=TX

To test how your homepage content may displayed to a user in the United States, use the following arguments:

yourdomain.com/?geoip&country=US

GeoTarget allows support for the following arguments:

• ?geoip&continent=
• ?geoip&country=
• ?geoip&region=
• ?geoip&city=
• ?geoip&postalcode=

You can also combine the arguments by adding an ampersand & in between values.

yourdomain.com/?geoip&country=CA&city=Toronto&region=ON

---

Shortcode Best Practices

• Apply shortcodes to multiple regions and separate using commas
  • [geoip-content country="US, CA, BR, MX"]Americas content here[/geoip-content]
• Exempt regions by narrowing specificity:
  • [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:
  • [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:
  • [geoip-content continent="EU" not-country="DE" city="Berlin"]Content to show to Europe, but exclude all of Germany except Berlin[/geoip-content]
  • Instead, use two shortcodes in lieu of making an exception to an exception:
    • [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:
  • [geoip-content country="US, FR" not-city="Paris"]Content to exempt from Paris, France[/geoip-content]
  • The previous example would exempt Paris, TX and any other city in the US named “Paris.” Instead, use two shortcodes to achieve the desired results:
    • [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:

• Continent: HTTP_GEOIP_CITY_CONTINENT_CODE
• Country: HTTP_GEOIP_COUNTRY_CODE
• Region/State: HTTP_GEOIP_REGION
• City: HTTP_GEOIP_CITY
• Zip/Postal Code: HTTP_GEOIP_POSTALCODE

To simply print the values for an IP in the browser, the following can be loaded into a PHP file on your website:

<?php
/** Loads the WordPress Environment and Template */
require( dirname( FILE ) . '/wp-load.php' );
$test_geoip_country_Code = do_shortcode( '[geoip-country]' );
$test_geoip_region = do_shortcode( '[geoip-region]' );
$test_geoip_city = do_shortcode( '[geoip-city]' );
$test_geoip_postalcode = do_shortcode( '[geoip-postalcode]' );
$test_geoip_location = do_shortcode( '[geoip-location]' );
echo "Country: " . $test_geoip_country . "<br/>";
echo "Region: " . $test_geoip_region . "<br/>";
echo "City: " . $test_geoip_city . "<br/>";
echo "Postal Code:" . $test_geoip_postalcode . "<br/>";
echo "Location: " . $test_geoip_location . "<br/>";

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. This PHP file should be dropped within the wp-content/mu-plugins directory.

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.

GeoIP shortcodes can be called directly from PHP using the do_shortcode() function in WordPress:

echo do_shortcode ( [geoip-city]);
echo do_shortcode ( ‘[geoip-content country="US"]’ . ‘Content just for US visitors’ . ‘[/geoip-content]’ );

---

MaxMind Country, Continent, and Region Codes

GeoTarget is designed to be used with WP Engine’s proprietary caching platform. As such, when you enable GeoTarget on your site, you have the ability to choose which GeoTarget variable (Country, Region/State, City) you want to have its own separate cache on your site.

For example, if you enable the Country caching bucket, visitors from Brazil, Mexico and Argentina will each have a cached version of the site built at the country level.

While you may enable up to two caching buckets, it is important to note that some buckets work better with cache than others. If you segment your geographically-specific content too much, it can cause many versions of the page to be cached which is less effective for site speed and performance. For this reason, we recommend wider geographic buckets like Country, and Region/State rather than City.

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

Postal Codes

This variable is only available in the US due to limitations with the location data GeoTarget uses. Currently, the estimation of accuracy for Postal Codes is less than 25% of GeoIP requests. Therefore we don’t recommend using this unless absolutely necessary.

About Regions

For “region,” the MaxMind database will use the standardized two-letter postal state or province abbreviation for the US and Canada. Other global “region” variables use the ISO-3166 standard, which include numerical region codes. These numerical region codes are often reused across multiple countries.

There can be many regions with the same region number in different countries. Without specifying the country, the following code will display in any country with a region 23 (Tierra Del Fuego, Argentina; Qina, Egypt; and Offaly, Ireland, etc…) (This is an example of what not to do):

[geoip-content region="23"] Content only for Shanghai, China [/geoip-content]

This means you should include both the country code and the region number to ensure you get the intended region within that country (This is the correct approach):

[geoip-content country="CN" region="23"] Content only for Shanghai, China [/geoip-content]

See the full list of region codes on MaxMind.

---

Additional Information

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.

Some locations in this database may not be accurate, or reflect up-to-date geopolitical boundaries. For example, an unincorporated place in a region might become its own city. If this happened after the current MaxMind GeoIP database was created, it may not return current data. This place may still display as unincorporated by the data printed by the WP Engine GeoTarget API. If you are experiencing an issue with incorrect locations, please submit a correction request to MaxMind directly.

Currently, WP Engine’s GeoTarget database works best with IPv4. Support for IPv6 is expected in future releases.

Mobile Users

LTE/4G/3G/Edge connections return null GeoTarget data as the information passed by cell towers currently don’t support Geolocation. If you are looking to use location services, which do not support mobile connections, you may want to instead refer to Android‘s or iOS’s native functionality documentation.

It’s best practice to develop a website to be responsive. GeoTarget does work with responsive code.

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 SEO

GeoTarget is primarily meant to improve and personalize user experiences. It should not be used to create geo-targeted landing pages intended to rank for specific geographic terms in search engines. GeoTargeted content is rendered server side. This means a bot’s IP address location determines which content the bot will be served. For example, often times in the US, Googlebot triggers GeoTarget to serve content as if the would be user is based in the Bay Area of California (Google’s HQ)–so it’s important to not use GeoTarget content for geo-specific keyword targeting on landing pages you use to drive traffic from search engines.

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.

GeoTarget and Legacy 1-Click Staging

GeoTarget technically works in Legacy 1-Click Staging, however remember that legacy staging is never cached. Legacy Staging is strictly for testing to make sure your code is correct. You can test the GeoTarget shortcode functionality in the 1-Click Staging area using the parameters in the test URLs mentioned in our testing shortcodes section.

If you wish to test the caching aspect of GeoTarget this will not be an accurate representation.

WP Engine Scope of Support

The WP Engine Support team is available to assist with your GeoTarget questions via Live Chat, 24/7 with the following areas:

• Enabling GeoTarget
• How GeoTarget works
• How to test GeoTarget shortcodes

WP Engine Support is not able to help you create custom PHP code snippets for use with GeoTarget.

You can learn more about GeoTarget using the following resources:

• GeoTarget plugin page at the WordPress plugin repository
• Country Codes from MaxMind
• Continent Codes from MaxMind
• Region Codes from UNECE – See Developer’s Guide for context on usage.

---

NEXT STEP: Personalize content with user segmentation and page cache