Convite para fazer upgrade do Android

O convite para upgrade é um fluxo de usuário que mostra os principais novos recursos incluídos na principal atualização do SO Android disponível.

O fluxo tem como objetivo convencer os usuários a atualizar o dispositivo para a versão mais recente do SO.

Quando um dispositivo tem uma atualização do SO pendente de aprovação do usuário, os usuários recebem uma notificação push mostrando os novos recursos e convidando-os a fazer o upgrade.

Para ativar o Upgrade Invite no SO Android, faça o registro usando o formulário de solicitação de ativação do Upgrade Invite do Android.

Personalizar a experiência do convite para upgrade

É possível personalizar o convite para upgrade das seguintes maneiras:

• Remova recursos irrelevantes.
• Atualize o idioma nos blocos de texto.
• Modifique as animações, cores e fontes para combinar com sua marca.

Para personalizar o fluxo, consulte as diretrizes no Guia de estilo de convite de upgrade e inclua suas informações de personalização no formulário de solicitação para ativar o convite para upgrade do Android.

Guia de estilo do convite do upgrade

Use este guia de estilo para modificar o visual do convite de upgrade para se adequar à sua marca (telas, cores, fontes). Recomendamos manter os tamanhos e a estrutura próximos ao design original.

O fluxo de convite para upgrade tem os seguintes três componentes:

• Tela de introdução
• Tela de recurso
• Tela de encerramento

Uma animação em cada tela ajuda a explicar cada recurso.

Tela de introdução

A tela de introdução contém uma animação curta que dá as boas-vindas ao usuário e o incentiva a iniciar o fluxo mostrado na tela de introdução.

Layout

A animação do dispositivo sempre consiste em:

• Fundo branco e formas coloridas
• Frame do dispositivo
• Conteúdo da interface

Estilo

Se você optar por adaptar o estilo do Material You, use as cores e formas padrão mostradas no exemplo.

Se você usar a cor da sua marca, verifique se ela funciona bem com o plano de fundo da interface.

Motion

Opção 1:com um relógio na tela inicial

1. Os números aparecem na tela.
2. Os números se movem para o centro enquanto diminuem de tamanho. O frame do smartphone aparece.
3. O tamanho do smartphone diminui. As formas começam a entrar na tela.
4. A animação estará concluída. As formas continuam se movendo suavemente.

Opção 2: não há relógio na tela inicial

1. O smartphone entra na tela.
2. O smartphone se move para o centro enquanto aumenta de tamanho. As formas começam a entrar na tela.
3. O telefone atinge o tamanho máximo e as formas continuam se movendo.

Tela de recurso

Cada tela de recurso destaca um recurso do novo SO.

Layout

A animação do dispositivo sempre consiste em:

• Plano de fundo colorido
• Quadro do dispositivo
• Conteúdo da interface

Estilo

• Escolha uma cor de plano de fundo que funcione bem com o conteúdo da interface e com a aparência geral.
• Nas telas, defina tamanhos de fonte que sejam facilmente legíveis. Se necessário, defina tamanhos de fonte maiores.

Motion

Grave uma animação do fluxo de cada recurso, incluindo interações por toque. Exporte as gravações como arquivos Lottie.

Tela de encerramento

A outra tela conclui o fluxo. Ele indica aos usuários que eles passaram por todas as telas.

Layout

A animação do dispositivo sempre consiste em:

• Meio círculo no plano de fundo (mais formas animadas)
• Frame do dispositivo
• Conteúdo da interface

Estilo

• Selecione uma cor de plano de fundo que funcione bem com o conteúdo da interface e com a aparência geral.
• Use um formato de semicírculo.

Motion

Siga o fluxo padrão de animação de tela de fundo:

1. O smartphone se move um pouco para cima.
2. Um círculo aparece no segundo plano.
3. Formas aparecem atrás do smartphone.
4. As formas saem do plano de fundo como confetes.

Testar o fluxo de convite para upgrade

1. No dispositivo Android, acesse: Configurações > Google > Depuração do Upgrade Party.
2. Prepare o acionador do Upgrade Invite para o SO do dispositivo relevante (dependendo da versão atual do SO e do fluxo específico do Upgrade Invite a ser testado). Ter um dos seguintes:
   1. Clique em Gravar upgrade falso (versão atual). Por exemplo, se você executar o SO Android 13, isso vai acionar o fluxo de teste do Android 13.
   2. Clique em Gravar upgrade pendente (versão atual + 1). Por exemplo, se você executar o SO Android 12, isso vai acionar o fluxo de teste do Android 13.
   3. Clique em Denunciar upgrade do SO.
3. Clique na notificação recebida ou em Abrir convite de upgrade.

Opções de acionamento para o convite de upgrade

Há três maneiras diferentes de acionar o fluxo de convite para upgrade: 1. automática 2. transmissão 3. SDK do Google Play Services acionado

Automático: notificação acionada pelo Google (somente para dispositivos com gOTA em execução)

Para dispositivos OEM que executam o gOTA, a integração é automática e não são necessárias etapas de integração do Upgrade Invite. Quando uma atualização importante do SO pendente é detectada, uma notificação push é enviada ao dispositivo pelos serviços do Google Play, levando ao fluxo de convite para upgrade.

Transmissão do Android: notificação acionada pelo Google (recomendado)

Uma transmissão de app é a maneira mais simples e recomendada de integrar o fluxo de convite de upgrade.

Um broadcast receiver permite que você acione o fluxo de convite para upgrade no app usando uma mensagem de transmissão. A transmissão envia uma notificação por push ao dispositivo do Google Play Services, levando ao fluxo de convite para upgrade.

Pré-requisitos de transmissão

Para preparar o app, siga as etapas nas seções a seguir.

Verifique se os arquivos de configuração do app usam os seguintes valores:

• Uma minSdkVersion de 14 ou mais
• Uma compileSdkVersion de 28 ou mais recente
• Uma usesPermission de android.permission.RECOVERY

Enviar a transmissão

Confira abaixo as instruções para que o app (ou código) do OEM envie uma transmissão do Android para acionar a notificação push:

1. Envie a transmissão com a ação.

   com.google.android.gms.growth.upgradeparty.upgradeinvite.ACTION_SYSTEM_UPDATE
   

2. Adicione o pacote com.google.android.gms à transmissão.

   com.google.android.gms
   

Outros requisitos

O fluxo de convite para upgrade também permite que os usuários realizem o upgrade do SO diretamente no fluxo.

Para que isso funcione, exponha uma intent personalizada que o Google possa chamar do fluxo de convite de upgrade que aciona o download da atualização.

Exemplo de uso de transmissão

Confira o exemplo a seguir de uma transmissão de app:

Context context = getApplicationContext();
Intent upgradeInviteIntent = new Intent()
  .setAction( "com.google.android.gms.growth.upgradeparty.upgradeinvite.ACTION_SYSTEM_UPDATE")
  .setPackage("com.google.android.gms");
  .putExtra("com.google.android.gms.growth.upgradeparty.upgradeinvite.EXTRA_PENDING_ANDROID_OS_VERSION_NUMBER", 14);

context.sendBroadcast(updateIntent);

O valor da chave EXTRA_PENDING_ANDROID_OS_VERSION_NUMBER é um número inteiro que indica a versão pendente do SO. Neste exemplo, a versão do Android a ser instalada é a 14. Ele é usado para determinar qual fluxo de convite de upgrade será acionado.

SDK do Play Services: apenas acionamento de fluxo

O SDK de terceiros permite que você acione o fluxo de convites para upgrade no seu app ou nas suas próprias notificações OTA. Use uma API externa de terceiros para ativar o fluxo de convite para upgrade. Esse método é menos recomendado.

Pré-requisitos

Para preparar o app, siga as etapas nas seções a seguir.

O arquivo de build do app precisa usar estes valores:

• Uma minSdkVersion de 14 ou mais
• Uma compileSdkVersion de 28 ou mais recente

Configurar o app

Para configurar o app:

1. Extract the library from the provided .zip file, and place it in your

repositório. 2. Adicione as dependências do SDK do Google Growth ao arquivo Gradle do módulo no nível do app, normalmente app/build.gradle:

   dependencies {
    implementation files('<PATH_TO_BINARY>/play-services-growth-16.1.0-eap04.aar')
   }

1. Para fornecer as dependências do cliente, inclua as seguintes bibliotecas:

   com.google.android.gms:play-services-base:18.0.1
   com.google.android.gms:play-services-basement:18.0.0
   com.google.android.gms:play-services-tasks:18.0.1
   

Inicialização da API

1. Para inicializar um cliente, use a classe UpgradeParty:

   import com.google.android.gms.growth.UpgradeParty;
   UpgradeParty.getClient(activity);
   

2. O parâmetro da atividade deve ser o objeto inicial da atividade.

Funções da API

O UpgradePartyClient resultante expõe a funcionalidade a seguir.

isEligibleForUpgradeInvite

import com.google.android.gms.growth.UpgradeInviteEligibilityParams;

Task<Boolean> isEligibleForUpgradeInvite(UpgradeInviteEligibilityParams params);

/** Contains parameters for the eligibility query. */
class UpgradeInviteEligibilityParams {


/** Integer indicating the pending OS version (in this example, the Android version to be installed is 14). This is used to determine which Upgrade Invite flow will be triggered. */
  int pendingAndroidOsVersionNumber;
}

Retorna uma tarefa que verifica de forma assíncrona se o usuário está qualificado para um convite de upgrade. O valor booleano resultante indica se o usuário está qualificado ou não.

invokeUpgradeInvite (link em inglês)

Task<Void> invokeUpgradeInvite();

Invoca a atividade de convite para upgrade. O objeto _Task _resultante indica se ocorreu um erro ao iniciar a atividade.

Códigos de erro

Os dois métodos da API podem falhar com uma exceção do tipo com.google.android.gms.common.api.ApiException. Nesses casos, o autor da chamada precisa tentar novamente mais tarde. Os códigos de status comuns esperados incluem:

• INTERNAL_ERROR: para qualquer erro no fluxo da lógica subjacente.
• TEMPO LIMITE EXPIRADO: se a solicitação não puder ser processada em tempo hábil.
• API_NOT_CONNECTED: quando a API não está disponível (ou seja, o módulo UpgradeParty ainda não está pronto).
• NETWORK_ERROR: não foi possível processar a solicitação devido a erros de rede.
• DEVELOPER_ERROR: o pacote de chamada não tem permissão para acessar a API UpgradeParty.

Exemplo de uso do SDK

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import com.google.android.gms.growth.UpgradeParty;
import com.google.android.gms.growth.UpgradePartyClient;

public class SampleActivity extends Activity {

 @Override
 protected void onCreate(Bundle savedInstanceState) {
   super.onCreate(savedInstanceState);
   final UpgradePartyClient client = UpgradeParty.getClient(this);

   // Hide the invocation button initially
   View startUpgradeInviteButton = findViewById(R.id.__some_button__);
   startUpgradeInviteButton.setVisibility(View.GONE);

   // Register an onClick handler to invoke the Upgrade Party Activity
   startUpgradeInviteButton
       .setOnClickListener(
           view -> {
             client
                 .invokeUpgradeInvite()
                 .addOnCompleteListener(
                     task -> {
                       if (!task.isSuccessful()) {
                         // Do something with error, see task.getException()
                       }
                     });
           });
   }

   // Check if eligible for an Upgrade Party
   client
       .isEligibleForUpgradeInvite()
       .addOnCompleteListener(
           task -> {
             if (!task.isSuccessful()) {
               // Do something with error, see task.getException()
             } else {
                  // Show/Hide invocation button, based on the result
                  int visibility = 
                        task.getResult() ? View.VISIBLE : View.GONE;
                  startUpgradeInviteButton.setVisibility(visibility);
             }
           });
   }