Convert an existing game to an instant app

The steps for setting up apps to run on Google Play Instant, as explained in Create your first instant app, also apply to games. This guide emphasizes some setup steps specific to games.

You can develop games for Google Play Instant using Unity (with or without the Google Play Instant Unity plugin), Cocos2D, Android Studio, or your own custom engine.

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 Games technical requirements checklist.

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 Play Games app. You can also launch this activity directly using the deep link API.

If you'd like players to access your game using a URL that you own, you can also add app links. If you add these app links, however, you also need to add a default URL that matches one of the app link URLs exactly.

The following code snippet shows an example combination of app links and default URL:

<activity
   android:name=".GameActivity" ... >

   <!-- App links (HTTP and HTTPS) -->
   <intent-filter android:autoVerify="true">
       <action android:name="android.intent.action.VIEW" />

       <category android:name="android.intent.category.BROWSABLE" />
       <category android:name="android.intent.category.DEFAULT" />

       <data android:scheme="http" />
       <data android:scheme="https" />
       <data android:host="example.com" />
       <data android:pathPrefix="/instant" />
   </intent-filter>

   <!-- Default URL -->
   <meta-data
       android:name="default-url"
       android:value="https://example.com/instant" />
</activity>

Version codes

The version code of your game's instant app needs to be less than the version code of the installable game. The expectation is that players 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 this versioning scheme, you can use 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 app's version number to increase.

For more details on setting your app's version, see Version your app.

Target sandbox version

Like other apps, games on Google Play Instant run within a limited sandbox on the device. The instant app's AndroidManifest.xml file needs to be updated to target this sandbox. You can complete this update by adding the android:targetSandboxVersion attribute to the <manifest> element, as shown in the following code snippet:

<manifest
   xmlns:android="http://schemas.android.com/apk/res/android"
  ...
   android:targetSandboxVersion="2" ...>

If you're using Gradle 3.0 or higher to build the Android version of your game, you can apply the com.android.feature and com.android.instantapps plugins to your feature modules. These plugins automatically add the necessary attribute to the module's manifest file.

For more information, see documentation on the targetSandboxVersion attribute.

APK size reduction

Unlike other types of apps, games on Google Play Instant have a download size limit of 10 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.

Tools

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.
  • GAPID: See the file size effect of reducing texture size without having to recompile your game.

Techniques

The following is a list of techniques that you can use to reduce the size of your game:

  • 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.

  • Use only a subset of sounds that are available in the installable game.

  • 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 gcc, use -Os instead.
    • -flto – Sometimes decreases file size.
    • Linker flags – Use --gc-sections in conjunction with compiler flags, such as -ffunction-sections and -fdata-sections.
  • Use Proguard to shrink your code and resources.

  • Use Gradle 4.4 or higher to generate smaller DEX files.

Play Core Split Install API

It can be difficult to optimize the Google Play Instant experience to make your game fit in a single 10 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.

Installation prompt

At some point during the Google Play Instant experience, the game should prompt the player to install the full version onto their device. To do so, use the showInstallPrompt() 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.

Additional resources

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.