Convert an existing game to an instant app

The technical requirements for running apps on Google Play Instant, as explained in Create your first instant app, also apply to games. This guide emphasizes some requirements specific to games.

A Google Play Instant experience starts with a URL, either when a player clicks a link directly or when an intent is raised to the Android system. In order to launch from the URL, the instant app needs to support deep linking and provide URL access.

You also need to specify a default URL, which usually corresponds to your game's main activity. This URL launches the Google Play Instant experience when a player clicks the Try Now button on the Play Store details page:

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

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

   <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 Instant Apps SDK.

To learn more about how and when you should prompt the player for installation, see UX best practices for games on Google Play Instant.