Overview

Metaplay supports resolving a player's country- or city-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 supports MaxMind's GeoLite2 Country and City databases, 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 the name maxmind_license_key.

Enabling City-Precision Location

By default, the server uses MaxMind's GeoLite2 Country database, which contains only country-precision locations. You can optionally change the server to use the GeoLite2 City database, which contains city-precision locations, as well as approximate latitude and longitude coordinates.

You can choose between GeoLite2Country (default) and GeoLite2City using the MaxMindDatabaseId option:

# Options.base.yaml

Geolocation:
  # ... `Enabled` and `MaxMindLicenseKeyPath` as earlier, omitted here ...
  MaxMindDatabaseId: "GeoLite2City"

When enabling city precision, keep the following in mind:

• You'll be storing more precise personal information from players than just the country.
• The city database takes more space in the server's memory than the country database. At the time of writing, the city database was about 60 MB and the country database about 8 MB. It's also stored in S3 (or the filesystem, for local servers), where it's compressed at roughly a 50% ratio.

Accessing a Player's Location Information

After geolocation has been enabled and correctly configured, subsequent player logins will record the player's location (if available) and store it in PlayerModel. The location 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.

If you've configured the server to use the city-level database, as described in #Enabling City-Precision Information, additional information may be present in members CityMaybe and CoordinatesMaybe of PlayerModel.LastKnownLocation.Value. CityMaybe.Name contains the English name of the city. CoordinatesMaybe's members Latitude and Longitude contain the approximate coordinates of the location. CityMaybe and CoordinatesMaybe are not guaranteed to be available, however, so make sure to check if they're null.

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 or City 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 or City 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!

You may however override your location in the Unity Editor by selecting the MetaplaySDK GameObject and choosing an option in the "Override client location" field of the inspector. The location must be selected before entering Play Mode. This location override is enabled for all players on the development and local environments, but only for Developer Players on production environments. See Working with Developer Players for details how to mark a player as a developer.

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 it's not working, why?

You can 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 this 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.