The Google Play Instant plugin for Unity configures your Unity project to create an instant app version of your game. This guide describes how to install and use this plugin.
Download and import the plugin
The plugin is part of the Google Play Plugins for Unity. To import the plugin, follow these steps:
- Download the latest release from Google Play Plugins for Unity releases.
- Import the
.unitypackage
file by selecting the Unity IDE menu option Assets > Import package > Custom Package and importing all items.
Unity Editor features
Import the plugin to add a Google > Play Instant submenu in Unity. This submenu provides the following options.
Build Settings
Opens a window that enables switching between Installed and Instant development modes. Switching to Instant performs the following changes:
- Creates a Scripting Define Symbol called
PLAY_INSTANT
that can be used for scripting with#if PLAY_INSTANT
and#endif
. - Manages updates to the AndroidManifest.xml for certain required changes such as android:targetSandboxVersion.
Player Settings
The Player Settings dialog, shown in Figure 1, displays suggestions to help you optimize support for Google Play Instant, develop against more compatible graphics APIs, and reduce your APK's size.
![Specific suggestions include using OpenGL ES 2.0 only and
disabling Multithreaded Rendering.](https://developer.android.google.cn/static/topic/google-play-instant/images/unity-plugin-player-settings.png?authuser=8)
These Player Settings are divided into Required and Recommended settings. If a setting has a corresponding Update button, click it to change the setting to the preferred value.
To further reduce the APK size, open the Unity Package Manager and remove any unused packages.
Quick Deploy
Quick Deploy can reduce the size of a Unity-based instant app by packaging some assets in an AssetBundle. When using Quick Deploy, the Unity game engine and a loading screen are packaged into an instant app APK, and after the instant app starts it retrieves the AssetBundle from a server.
Support installation workflows
The goal of many instant apps is to give users a chance to experience the app before installing the full version. The Google Play Instant plugin for Unity provides APIs for displaying a Play Store install dialog and for transferring state from instant to installed app.
Show an install prompt
An instant app with an Install button can display a Play Store install dialog by calling the following from an install button click handler:
Google.Play.Instant.InstallLauncher.ShowInstallPrompt();
The ShowInstallPrompt()
method has an overload that allows for one or more of
the following:
- Determining if the user cancels out of the installation process. Override
onActivityResult()
in the instant app's main activity and check forRESULT_CANCELED
on the specifiedrequestCode
. - Passing an install referrer string via the
referrer
parameter. - Passing state about the current game session via
PutPostInstallIntentStringExtra()
.
These are demonstrated in the following example:
using Google.Play.Instant;
...
const int requestCode = 123;
var sessionInfo = /* Object serialized as a string representing player's current location, etc. */;
using (var activity = UnityPlayerHelper.GetCurrentActivity())
using (var postInstallIntent = InstallLauncher.CreatePostInstallIntent(activity))
{
InstallLauncher.PutPostInstallIntentStringExtra(postInstallIntent, "sessionInfo", sessionInfo);
InstallLauncher.ShowInstallPrompt(activity, requestCode, postInstallIntent, "test-referrer");
}
If the user completes app installation, the Play Store will re-launch the app
using the provided postInstallIntent
. The installed app can retrieve a value
set in the postInstallIntent
using the following:
var sessionInfo = InstallLauncher.GetPostInstallIntentStringExtra("sessionInfo");
Notes:
- The extras included in the
postInstallIntent
may not reach the installed app if the user installs the app but cancels the post-install launch. Passing intent extras is better suited for retaining active session state than it is for retaining persistent state; for the latter refer to the Cookie API. - Anyone can construct an intent with extra fields to launch the installed app, so if the payload grants something of value, design the payload so that it can only be used once, cryptographically sign it, and verify the signature on a server.
Use the Cookie API
The Cookie API provides methods for passing a cookie (e.g. player ID or level
completion data) from an instant app to its corresponding installed app. Unlike
postInstallIntent
extras, the cookie state is available even if the user
doesn't immediately launch the installed app. For example, an instant app could
call the following code from an install button click handler:
using Google.Play.Instant;
...
var playerInfo = /* Object serialized as a string representing game levels completed, etc. */;
var cookieBytes = System.Text.Encoding.UTF8.GetBytes(playerInfo);
try
{
var maxCookieSize = CookieApi.GetInstantAppCookieMaxSize();
if (cookieBytes.Length > maxCookieSize)
{
UnityEngine.Debug.LogErrorFormat("Cookie length {0} exceeds limit {1}.", cookieBytes.Length, maxCookieSize);
}
else if (CookieApi.SetInstantAppCookie(cookieBytes))
{
UnityEngine.Debug.Log("Successfully set cookie. Now display the app install dialog...");
InstallLauncher.ShowInstallPrompt();
}
else
{
UnityEngine.Debug.LogError("Failed to set cookie.");
}
}
catch (CookieApi.InstantAppCookieException ex)
{
UnityEngine.Debug.LogErrorFormat("Failed to set cookie: {0}", ex);
}
If the user completes app installation, the installed app can retrieve the cookie data using the following code:
var cookieBytes = CookieApi.GetInstantAppCookie();
var playerInfoString = System.Text.Encoding.UTF8.GetString(cookieBytes);
if (!string.IsNullOrEmpty(playerInfoString))
{
// Initialize game state based on the cookie, e.g. skip tutorial level completed in instant app.
}