This guide assumes that you already know the sort of gaming experience you'd like to provide. If you'd like to see ideas and best practices for making high-quality games, read through UX best practices for games on Google Play Instant.
In addition, before publishing a game that can run on Google Play Instant, you should review the Technical requirements checklist.
Specify an entry point
An activity that includes the following intent filter becomes the entry point for the Google Play Instant experience:
<activity android:name=".GameActivity"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> </activity>
This activity is launched when a user taps the Try Now button in the Play Store or the Instant play button in Google Play Games app. You can also launch this activity directly using the deep link API.
Define the correct version codes
The version code of your game's instant experience needs to be less than the version code of the installable game. Versioning your app in this way allows players to move from the Google Play Instant experience to downloading and installing the game onto their device. The Android framework considers this transition to be an app update.
To make sure that you follow the recommended versioning scheme, follow one of these strategies:
- Restart the version codes for the Google Play Instant experience at 1.
- Increase the version code of the installable APK by a large number, such as 1000, to ensure that there is enough space for your instant experience's version number to increase.
It's OK to develop your instant game and your installable game in two separate Android Studio projects. If you do so, however, you must do the following to publish your game on Google Play:
- Use the same package name in both Android Studio projects.
- In the Google Play Console, upload both variants to the same application.
For more details on setting your game's version, see Version your app.
Support the execution environment
Like other apps, games on Google Play Instant run within a limited sandbox on the device. To support this execution environment, complete the steps shown in the following sections.
Opt out of cleartext traffic
Games on Google Play Instant don't support HTTP traffic. If your game targets Android 9 (API level 28) or higher, Android disables cleartext support in your game by default.
If your game targets Android 8.1 (API level 27) or lower, however, you must
create a Network Security Config file.
In this file, set
false, as shown in the
following code snippet:
<?xml version="1.0" encoding="utf-8"?> <network-security-config> <domain-config cleartextTrafficPermitted="false"> <domain includeSubdomains="true">secure.example.com</domain> </domain-config> </network-security-config>
Update the target sandbox version
Update your instant game's
AndroidManifest.xml file so that it targets the
sandbox environment that Google Play Instant supports. You can complete
this update by adding the
android:targetSandboxVersion attribute to your
<manifest> element, as shown in the following code snippet:
<manifest xmlns:android="http://schemas.android.com/apk/res/android" ... android:targetSandboxVersion="2" ...>
For more information, see documentation on the
Don't rely on the presence of a cache or app data
Your instant experience remains downloaded on a user's device until the instant experience cache is cleared, which occurs in one of the following situations:
- The instant experience cache is garbage-collected because the device is running low on available memory.
- The user restarts their device.
If either process occurs, the user must re-download your instant experience in order to interact with it.
If the system is running very low on storage space, it's possible that your instant experience's user data is removed from internal storage. Therefore, it's recommended to periodically sync user data with your game's server so that the user's progress is preserved.
Reduce your APK size
Unlike other types of apps, games on Google Play Instant have a download size limit of 15 MB. To create a game of this size, you might need to refactor your game's logic. This section describes some tools and techniques to help optimize the size of your game.
The following list of tools can help you determine what is contributing to the size of your game:
- APK Analyzer: Provides a holistic view of the contents of a compiled APK. Using this view, you can determine the number of bytes that each element is contributing to the overall size. Use this tool to quickly check the size of resources, assets, logic, and native libraries that your game is using.
- Bloaty McBloatface: Shows the size profile of binary files.
- Android GPU Inspector: See the file size effect of reducing texture size without having to recompile your game.
The following is a list of techniques that you can use to reduce the size of your game:
- Extract some of your game's logic and place it in one or more feature modules, which don't count toward the size limit.
- Reduce the resolution of your game's textures.
- Consider using the WebP format, especially if you're using uncompressed textures on the GPU. The WebP format creates images that are the same quality as JPEG images but are 15% to 30% smaller. Although it takes longer to decompress WebP images, this decompression time is still significantly shorter than the download time of your game's textures. Google has also integrated the format into an open source game engine.
- Compress or re-use sounds and music.
- Use different compilation flags to help make your binary file smaller:
-fvisibility=hidden– The most important one. In
cmake, you can specify it as follows:
$ set_target_properties(your-target PROPERTIES CXX_VISIBILITY_PRESET hidden)
-Oz– Also important for reducing size. If you compile using
-flto– Sometimes decreases file size.
- Linker flags – Use
--gc-sectionsin conjunction with compiler flags, such as
- Use Proguard to shrink your code and resources.
- Use Gradle 4.4 or higher to generate smaller DEX files.
- Implement cloud delivery of assets.
Divide a large game into multiple APKs
It can be difficult to optimize the Google Play Instant experience to make your game fit in a single 15 MB APK, even after applying the recommendations to reduce APK size. To address this challenge, you can divide your game into multiple APKs. Players start by downloading the primary, base APK; as they play, the remaining split APKs are made available to the game in the background.
For example, the base APK can contain the core game engine and the assets required to display a loading screen. As the base APK launches, it displays the loading screen and immediately requests an additional split APK that contains the game and level data. After that split APK becomes available, it can load its assets into the game engine and give the player the content they need to begin the game.
Adopt UX best practices
After you configure your game so that it supports instant experiences, add the logic that's shown in the following sections to provide a good user experience.
Check whether game is running instant experience
If some of your game's logic depends on whether the user is engaged in your
instant experience, call the
method. This method returns
true if the currently-running process is an
By doing this check, you can determine whether your app needs to run within a limited execution environment or can take advantage of platform features.
Display an installation prompt
If you have built a trial Google Play Instant experience, at some point the game should prompt
the player to install the full version onto their device. To do so, use the
method in the Google APIs for Android.
To learn more about how and when you should prompt the player for installation, see UX best practices for games on Google Play Instant.
Transfer data to an installed experience
If a player enjoys your trial experience, they might decide to install the full version of your game. To provide a good user experience, it's important that the player's progress is transferred from your instant experience to the full version of your game.
If the player is using a device that runs Android 8.0 (API level 26) or higher,
and if your game specifies a
2, then the player's progress is transferred
automatically to the full version of your game. Otherwise, you must transfer the
data related to player progress manually. To do so, use one of the following
- For players who use devices that run Android 8.0 (API level 26) and higher, use the Cookie API - sample app
- If players can interact with your experience on devices that run Android 7.1 (API level 25) and lower, add support for the Storage API - sample app
Learn more about Google Play Instant from these additional resources:
- Codelab: Build Your First Instant App
- Add support for Google Play Instant in an existing app.
- Codelab: Build a Multi-Feature Instant App
- Modularize a multi-feature app.