The Enterprise Edition of CountryHawk provides the ability for you to easily group countries by region. By default, CountryHawk ships with regions defined based on geographical location, such as North America, Western Europe, and Scandinavia. However, you have complete flexibility in defining regions however you wish.
Categorizing countries into regions with CountryHawk is useful for a number of purposes. For example, you can use CountryHawk to easily produce statistical reports showing the number of visits by region. Other purposes include automatically routing web site requests based on region, and the ability to target advertising and other content based on a region - rather than a specific country.
You can customize or redefine regions by editing your regions.properties file in a text editor. This file contains entries in the following format:
region.XXXXX.name=YYYYY
region.XXXXX.countries=AA AA AA
To define a new region follow these steps:
First you need to define the region code and give it a name. Create two lines as shown above. In the region.XXXXX.name line, replace XXXXX with the region code you wish to assign to this region. Region codes serve as abbreviated IDs for regions. Typically you would base your program logic around the results of region codes and store region codes in your database if desired. This is the value that will be returned from the RegionCode property. Note that region codes are always converted to lowercase.
You also have the ability to define a region name for each region code. This is done with the "=YYYYY" after the region.XXXX.name declaration. Replace the value specified for YYYYY with the region name to associate with this region code. Region names typically serve as display names. This is the value that is returned by the RegionName and RegionNameFromCountryCode methods.
Now that we have defined the region code and name, we need to define which countries are associated with this region. We do this with the region.XXXXX.countries=AA AA AA line. Replace XXXXX with the region code you defined for the new region. Then replace AA AA AA with the two-letter country codes associated with this region. These codes must match the codes that are defined in your countrynames.properties file.
Example:
To further demonstrate how to define your own regions, let's walk through an example. Assume that you have three sales people, each that handles their own region. We want to be able to track statistics on what percentage of our visitors come from each person's sales region.
To do this, we must first replace the default region definitions with our own. Start by making a back up copy of your regions.properties file, and then delete its contents. Now we need to define our three region codes – let's get started.
Let's assume our sales people are named "Evan R. Smith", "Taylor S. Litov", and "Diane M. Espador". The follow is how we would define these regions and associate countries with each.
region.ers.name=Evan R. Smith
region.ers.countries=US CA UK
region.tsl.name=Taylor R. Smith
region.tsl.countries=AU FJ KI MH FM
region.dme.name=Diane M. Espador
region.dme.countries=AR BO BR CL CO EC GF GY PY
Note: If you are using CountryHawk from web scripts you must restart your web services after making changes to this file for the changes to take affect.
Now whenever a CountryHawk object is created for US, CA, or UK, the object's RegionCode property will return "ers" and the RegionName method will return "Evan R. Smith". Likewise the internal statistics for hits by region will automatically increment the "ers" region count by one.
Note: Use of region codes and names requires the Enterprise Edition of CountryHawk.
See Also:
About the CountryHawk Users Guide
Understanding and customizing the data files