Production Best Practices

Google recommends that you follow these best practices when administering and running your app.

Securing API keys

You need an API key to use our online services, and its use allows Google to meter your usage. We recommend restricting your API keys to prevent unauthorized use.

Types of API key restrictions

There are two types of API key restrictions, and you can use them both at the same time.

Restriction typeRestricts key usage to
API restriction A particular API.
Application restriction Particular IP addresses, web sites, or app.

API key restriction recommendations

We recommend that you commission separate API keys for the following scenarios.

ScenarioRecommendation
Your back-end game servers calls the Playable Locations API to retrieve playable locations. Configure a key with two restrictions:
  • API restriction: Allow calls to only the Playable Locations API.
  • Application restriction: Allow calls originating from only your back-end game server's IP addresses.
The Android version of your app calls the Maps Unity SDK to retrieve geo data. Configure a key with an application restriction to allow calls from only the Android version of your app.
The iOS version of your app calls the Maps Unity SDK API to retrieve geo data. Configure a key with an application restriction to allow calls from only the iOS version of your app.

For more information, see Using API Keys.

To setup API key restrictions

  1. Visit the credentials panel.
  2. Select the API key that you want to set a restriction on. The API key property page appears.
  3. Under Key restrictions, select the Application restrictions tab, and then select one of the four applications restriction types.
    Restriction type Description
    HTTP referrers Accept requests from the list of websites that you supply.
    IP addresses Accept requests from the list of web server IP addresses that you supply.
    Android apps Add your package name and SHA-1 signing-certificate fingerprint to restrict usage to your Android app.
    iOS apps Accept requests from the iOS app with the bundle identifier that you supply.
  4. Under Key restrictions, select the API restrictions tab, and then select the API that you want to restrict your API key to.
  5. Click Save.

Support API key updates

Make sure that you have infrastructure in place to update API keys across your serving stack. That way, your game can recover if your API key is compromised, and you need to renew it on short notice.

We recommend regenerating your API keys periodically—to invalidate keys that may have been compromised. This also tests your ability to handle emergencies.

To regenerate your API keys

  1. Visit the credentials panel.

  2. Click Regenerate key for each API key.

  3. Update your app to use the newly-generated keys. Your old keys will continue to work for 24 hours after you generate replacement keys.

Game server safety recommendations

When the Playable Locations API server experiences an outage for any reason, problems occur when it comes back online—when multiple game servers attempt to reconnect to it at the same time. Such a QPS spike can send the server into DoS mode, which exacerbates the situation by blocking incoming traffic.

To mitigate this situation, Google asks that you implement Binary Exponential Back-off on your game server. It's a systematic approach to spacing-out your connection retries. Specifically, you would implement an algorithm that waits N seconds after a failed reconnection attempt before trying again. If the next attempt fails, then your algorithm doubles the waiting period and then tries again. If the next attempt fails, then your algorithm again doubles the waiting period, and then tries again. You continue doubling the waiting period after each attempt--until your final attempt succeeds.

Handling HTTP return status codes

You should implement binary exponential back-off for some HTTP return codes, but not all of them.

400s
These are client errors that generally don't recover, so retrying failed requests that produce this error codes won't work. You should catch these kinds of errors during testing.
429
This is a resource exhausted error, and it occur when you begin running out of API quota. To see your project's API QPS limits, visit Google APIs Quotas.
500s
These are the server-side errors—the kind of errors that exponential back-off is most useful for.