Google Play Instant

With Google Play Instant, people can use a game without installing it first. Use it to increase engagement or gain more installs by surfacing your instant game across the Play Store and Google Play Games app. (official Google Play Instant docs)

GooglePlayInstant

Publishing process

To be able to publish your game as Google Play Instant app you need to set up your project properly:

  • Create a custom AndroidManifest.xml file (copy the default from builtins/manifests/android/AndroidManifest.xml) and add the following attributes to the <manifest> element:
xmlns:dist="http://schemas.android.com/apk/distribution"
android:targetSandboxVersion="2"

The following declaration need to be added right after manifest element:

<dist:module dist:instant="true" />

This is what it would look like with the default AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
        package="{{android.package}}"
        android:versionCode="{{android.version_code}}"
        android:versionName="{{project.version}}"
        android:installLocation="auto"
        xmlns:dist="http://schemas.android.com/apk/distribution"
        android:targetSandboxVersion="2">
      <dist:module dist:instant="true" />
  • Add a dependency to the Google Play Instant extension in your game.project file. Add:
https://github.com/defold/extension-googleplayinstant/archive/master.zip

or point to the ZIP file of a specific release to the Dependencies property.

Project settings

  • Download libraries: Project->Fetch Libraries
  • Bundle aab Project->Bundle->Android Application
  • Upload your aab in Google Play Console as Android Instant App

Version codes

Pay attention to the recommendations about the version codes: Instant Game version code needs to be less than the version code of the installable game.

Project settings

android:targetSandboxVersion=”2”

If you set android:targetSandboxVersion="2" in the main installable game you will be able to access the same files as the instant game (a save file for example). Note that certain restrictions apply to a level 2 sandbox. More information in the official documentation.

Once an app is installed, you can only update its target sandbox value to a higher value. To downgrade the target sandbox value, you must uninstall the app and replace it with a version whose manifest contains a lower value for this attribute.

Even if you set a different android:targetSandboxVersion in the installable game and instant game you are still able to use instantapp.set_cookie() and instantapp.get_cookie() for communication between the game versions.

Technical Requirements

According to the Google Play Instant Technical Requirements apk size must be less than or equal to 15 MB. Recommendations for application size optimisation are available in the optimization manual.

Google Play Instant is only available to Android devices running Android OS 6.0 or higher.

API Usage

The Google Play Instant extension is accessible through the instantapp.* namespace where it wraps Java PackageManagerCompat methods in a Lua API.

If you are working on a cross-platform application the best practice is to check the existence of the instantapp module since this module exists only in an Android bundle:

if instantapp then
  -- call instantapp methods
end

For example:

if instantapp and instantapp.is_instant_app() then
  -- if this is instant app save data for the main app and show install prompt
  local cookie_size = instantapp.get_cookie_max_size()
  if cookie_size > 0 then
    instantapp.set_cookie(bytes_of_save_data)
  end
  instantapp.show_install_prompt()
else
  -- regular app logic
end

instantapp.is_instant_app() Google Developer docs

Returns true if this application is an instant app.

if instantapp.is_instant_app() then
  -- do something specific for instant app
end

instantapp.show_install_prompt() Google Developer docs

Shows a dialog that allows the user to install the current instant app.

if instantapp.is_instant_app() then
  instantapp.show_install_prompt() -- if this is instant app then show install prompt
else
  -- regular app logic
end

Popup example:

2019-04-07 20 54 02

Gets the maximum size in bytes of the cookie data an instant app can store on the device.

local cookie_size = instantapp.get_cookie_max_size() --number, for example 16384

Gets the instant application cookie for this app. Non instant apps and apps that were instant but were upgraded to normal apps can still access this API.

local cookie_byte_array = instantapp.get_cookie()

Sets the instant application cookie for the calling app. Non instant apps and apps that were instant but were upgraded to normal apps can still access this API.

instantapp.set_cookie(bytes)

Testing

Testing Instant game

|
+-android-sdk
  |
  +-cmdline-tools
    |
    +-latest
      |
      +-bin (from unpacked archive)
      +-lib (from unpacked archive)
  • Install the Android build tools:
./android-sdk/cmdline-tools/latest/bin/sdkmanager --verbose "build-tools;29.0.3"
  • Install extra-google-instantapps tools:
./android-sdk/cmdline-tools/latest/bin/sdkmanager --verbose "extras;google;instantapps"
  • Launch apk as Instant game on your device:
android-sdk/extras/google/instantapps/ia run path_to_your_game.apk

More information about debugging on mobile devices available in the Debugging manual.

Source code

The source code is available on GitHub

API reference

API Reference


Did you spot an error or do you have a suggestion? Please let us know on GitHub!

GITHUB