Overview

Metaplay supports resolving a player's country-level location based on their IP address during login. This information is shown on the player's page in the LiveOps Dashboard and is available in PlayerModel for game code to access.

The IP geolocation uses MaxMind's GeoLite2 Country database, which the game backend automatically downloads and updates from MaxMind's servers.

Geolocation is disabled by default, but it can be enabled in a few simple steps.

Important

Before you enable geolocation, please consider the relevant privacy aspects.

Privacy

Physical location is personally identifiable information. With geolocation enabled, the game backend will be collecting players' location information and storing it in the database. Thus, you should make sure that you comply with any relevant laws. For example, make any necessary additions to your privacy policy regarding the collection of this data. Please see also GDPR Compliance.

Configuration

To enable geolocation, you'll need to set two variables:

• Set Geolocation:MaxMindLicenseKeyPath to the path to a file that contains a MaxMind license key that the backend will then use to download the geolocation databases.
  • You can create a free MaxMind GeoLite2 account to generate a license key, as described in MaxMind's instructions.
• Set Geolocation:Enabled to true.

For example, say the file Backend/Server/Secrets/mygame-maxmind-license-key contains your MaxMind license key:

abcde01234567890

📝 Note

The file should contain only the license key as plain ASCII, without a newline at the end.

Accordingly, your Backend/Server/Config/Options.base.yaml would contain the following:

# Options.base.yaml

Geolocation:
  Enabled:               true
  MaxMindLicenseKeyPath: "./Secrets/mygame-maxmind-license-key"

Then disable it for the locally running server to avoid wasting download quota unnecessarily:

# Options.local.yaml

Geolocation:
  Enabled: false

🔒 Store secrets securely

To avoid storing secrets within the code repository, you can put them in AWS Secrets Manager instead. For example, setting MaxMindLicenseKeyPath to aws-sm://us-east-1#maxmind_license_key would denote credentials in Secrets Manager on us-east-1 with name maxmind_license_key.

Accessing a Player's Country Information

After geolocation has been enabled and correctly configured, subsequent player logins will record the player's country (if available) and store it in PlayerModel. The country code will then be accessible in the LiveOps Dashboard as well as in-game code.

In the LiveOps Dashboard

On a player's page in the LiveOps Dashboard, the player's last known country is shown among the Stats in the overview card at the top.

You can also see a list of recent login locations under the player's Latest Logins:

If geolocation is disabled or the player's location is unknown, "Unknown" is shown instead.

In Game Code

PlayerModel has a member called LastKnownLocation. The member can be null if geolocation is disabled or if the player's IP could not be found from the geolocation database. Otherwise, PlayerModel.LastKnownLocation.Value.Country.IsoCode contains the latest known country, represented as a 2-letter ISO country code string, such as "FI" for Finland, or "US" for the United States of America.

Under the Hood

While using geolocation in Metaplay should be simple enough, it can be useful to know how it works under the hood.

IP-based lookups

When a player connects and logs in, the backend uses the source IP address of the connection to look up a physical location in MaxMind's GeoLite2 Country IP database.

There are two reasons this is not completely reliable. Firstly, the IP address itself can be controlled by clients by using proxies; thus, the IP does not necessarily reflect the actual location. Secondly, even given a true source IP, IP-based geolocation is not 100% accurate.

Geolocation Databases

The backend uses MaxMind's GeoLite2 Country database to translate IP addresses to countries. The backend does not include a static copy of the database; instead, it automatically downloads it from MaxMind. After downloading an initial copy of the database, it occasionally polls for and downloads updates to the database. It stores these downloaded copies in a cluster-private S3 bucket to avoid needing to download them from MaxMind unnecessarily.

By automatically downloading updates, the backend ensures it always has the most accurate IP location information. MaxMind releases weekly updates of the database.

Because the backend doesn't contain a static copy of the database, it may take a moment for geolocation to become available when enabled for the first time in an environment. Normally this shouldn't take longer than a few seconds.

Downloading the database from MaxMind requires a valid MaxMind license key. If an incorrect license key is configured, the backend won't be able to download the database. Please follow MaxMind's instructions for creating a free GeoLite2 account and generating a license key.

To ensure that stale geolocation data is not used, and to comply with MaxMind's license terms, the backend automatically disables geolocation lookups if its latest copy of the database is older than 30 days. The database should never fall that far behind if the automatic updates are functioning correctly.

Frequently Asked Questions

Why can't I see my location when I'm running a local server?

When you're testing your game locally, all of your connections will come from localhost - which does not have a country!

How do I configure my geolocation settings?

This specific setting is covered above, but you can read Working with Runtime Options if you would like more information about the configuration system in general.

I have configured my geolocation settings but its not working, why?

You check that your configuration settings are as you expect by using the Runtime Options page of the LiveOps Dashboard. If you believe that the configuration is correct but geolocation is not working, please check that the MaxMind license key looks correct. In particular, the license key file should not contain any spaces or newlines (not even at the end of the file).

How can I find messages from the geolocation system in my server logs?

You can search your server logs for Geolocation (case-insensitive) to find messages from the geolocation system.

Why do all of my players seem to come from the same location?

Certain backend configurations may cause the source client IP addresses to be masked by load balancer IPs. For each client connection, the backend logs an info-level message containing a partially redacted version of the source IP address, such as Client handshake completed with (12.34.X.X-55ab2e3f). If these messages show that the backend is only seeing a handful of different IPs, or all have the same country as the load balancer, then it probably means this is happening. You might also notice this in the LiveOps Dashboard if all of your players seem to originate from the same country, even though you know that that is not the case. Please contact us if this seems to be the case.

Similar to the above, some versions of Metaplay infrastructure use an ad-hoc IPv6 proxy. In such configurations, IP geolocation will only give sensible results for IPv4 connections. Nowadays this IPv6 proxy is no longer the recommended solution since AWS contains improved IPv6 support. Please contact us if this is an issue for you.