Usar o Google Play Instant com o Unity

O plug-in do Google Play Instant para Unity configura seu projeto do Unity para criar uma versão instantânea do seu jogo. Este guia descreve como instalar e usar esse plug-in.

Fazer o download e importar o plug-in

O plug-in faz parte dos plug-ins do Google Play para Unity. Para importar o plug-in, siga estas etapas:

1. Faça o download da versão mais recente do Google Play Plug-ins for Unity (link em inglês).
2. Importe o arquivo .unitypackage selecionando a opção de menu Assets > Import package > Custom Package do ambiente de desenvolvimento integrado do Unity e importando todos os itens.

Recursos do Unity Editor

Importe o plug-in para adicionar um submenu Google > Play Instant no Unity. Esse submenu oferece as opções a seguir.

Build Settings

Abre uma janela que permite alternar entre os modos de desenvolvimento Installed e Instant. Alternar para Instant causa as seguintes mudanças:

• Cria um símbolo de definição de script chamado PLAY_INSTANT, que pode ser usado para scripts com #if PLAY_INSTANT e #endif.
• Gerencia atualizações do AndroidManifest.xml para algumas mudanças necessárias, como android:targetSandboxVersion.

Player Settings

A caixa de diálogo Player Settings, mostrada na Figura 1, apresenta sugestões para ajudar a otimizar a compatibilidade com o Google Play Instant, desenvolver usando APIs gráficas mais compatíveis e reduzir o tamanho do APK.

As configurações são divididas entre Required (Obrigatórias) e Recommended (Recomendadas). Caso uma configuração tenha um botão Update, clique nele para mudar a configuração para o valor preferencial.

Para reduzir ainda mais o tamanho do APK, abra o Unity Package Manager e remova todos os pacotes não usados.

Implantação rápida

A implantação rápida pode reduzir o tamanho de um app instantâneo baseado em Unity empacotando alguns recursos em um AssetBundle. Ao usar a implantação rápida, o mecanismo de jogo Unity e a tela de carregamento são empacotados em um APK de app instantâneo e, depois que esse app é iniciado, recupera o AssetBundle de um servidor.

Oferecer compatibilidade com fluxos de trabalho de instalação

O objetivo de muitos apps instantâneos é oferecer aos usuários a oportunidade de experimentar o app antes de instalar a versão completa. O plug-in do Google Play Instant para Unity oferece APIs para exibir uma caixa de diálogo de instalação da Play Store e transferir o estado do app de instantâneo para instalado.

Mostrar uma solicitação de instalação

Um app instantâneo com um botão Instalar pode exibir uma caixa de diálogo de instalação da Play Store chamando os métodos a seguir por um gerenciador de cliques do botão de instalação:

Google.Play.Instant.InstallLauncher.ShowInstallPrompt();

O método ShowInstallPrompt() tem uma sobrecarga que permite uma ou mais das seguintes opções:

• Determinar se o usuário cancela o processo de instalação. Substituir onActivityResult() na atividade principal do app instantâneo e procurar RESULT_CANCELED no requestCode especificado.
• Transmitir uma string de referência de instalação por meio do parâmetro referrer.
• Transmitir o estado da sessão atual do jogo com PutPostInstallIntentStringExtra().

Essas opções são demonstradas nos exemplos a seguir:

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");
}

Se o usuário concluir a instalação do app, ele será reiniciado pela Play Store usando a postInstallIntent fornecida. O app instalado pode recuperar um valor definido na postInstallIntent usando o seguinte:

var sessionInfo = InstallLauncher.GetPostInstallIntentStringExtra("sessionInfo");

Observações:

• Os extras incluídos na postInstallIntent podem não chegar ao app instalado se o usuário instalar o app, mas cancelar a inicialização pós-instalação. Transferir extras de intent é mais adequado para manter o estado de sessão ativo do que para reter o estado permanente. Para estados permanentes, consulte a API Cookie.
• Qualquer pessoa pode construir uma intent com campos extras para iniciar o app instalado. Assim, se o payload atribui algo de valor, configure-o para que ele só possa ser usado uma vez, assine-o criptograficamente e verifique a assinatura em um servidor.

Usar a API Cookie

A API Cookie oferece métodos para transmitir um cookie (por exemplo, ID do jogador ou dados de conclusão de nível) de um app instantâneo para o app instalado correspondente. Ao contrário dos extras de postInstallIntent, o estado do cookie fica disponível mesmo se o usuário não inicia o app instalado imediatamente. Por exemplo, um app instantâneo pode chamar o seguinte código de um gerenciador de cliques do botão de instalação:

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);
}

Se o usuário concluir a instalação do app, o app instalado poderá recuperar os dados do cookie usando o seguinte código:

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