Convite para fazer upgrade do Android

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

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 um upgrade do SO pendente de aprovação do usuário, ele recebe uma notificação push mostrando os novos recursos e convidando a fazer o upgrade.

Os fabricantes de dispositivos podem ativar o Upgrade Party nos dispositivos com SO Android enviando o formulário de solicitação para ativar o Android Upgrade Invite.

Personalizar a experiência do convite para fazer upgrade

É possível personalizar a experiência do 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, revise as diretrizes no Guia de estilo de convite para upgrade e inclua suas informações de personalização na resposta do formulário.

Guia de estilo de convite para upgrade

Use este guia de estilo para modificar a aparência do convite de upgrade e adequá-lo à 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 três componentes a seguir:

• Tela de introdução
• Tela de recursos
• 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 pequena animação 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:

• Plano de fundo branco e formas coloridas
• Estrutura 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.

Movimento

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

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

Opção 2:sem 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 smartphone atinge o tamanho máximo, e as formas continuam se movendo.

Tela de recursos

Cada tela de recurso destaca um recurso no novo SO.

Layout

A animação do dispositivo sempre consiste em:

• Plano de fundo colorido
• Frame 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.
• Dentro das telas, defina tamanhos de fonte que sejam facilmente legíveis. Se necessário, defina tamanhos de fonte maiores.

Movimento

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

Tela de encerramento

A tela de encerramento conclui o fluxo. Isso 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.

Movimento

Siga o fluxo padrão de animação da tela final:

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

Testar o fluxo de convite para upgrade

1. No dispositivo Android, acesse Configurações > Google > Upgrade Party debug.
2. Prepare o gatilho para o Upgrade Invite no SO do dispositivo relevante (dependendo da sua versão atual do SO e do fluxo específico do Upgrade Invite a ser testado. Ter um dos seguintes:
   1. Clique em Escrever upgrade falso (versão atual). Por exemplo, se você estiver executando o sistema operacional 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ê estiver executando o SO Android 12, isso vai acionar o fluxo de teste do Android 13.
   3. Clique em Relatar upgrade do SO.
3. Clique na notificação recebida ou em Abrir convite para 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ático 2. transmissão 3. SDK do Google Play Services acionado

Automática: notificação acionada pelo Google (somente para dispositivos que executam gOTA)

Para dispositivos OEM que executam gOTA, a integração é automática e não exige etapas de integração de convite de upgrade. Quando um upgrade importante do SO pendente é detectado, uma notificação push é enviada ao dispositivo pelos serviços do Google Play e inicia o 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 para upgrade.

Um broadcast receiver permite acionar o fluxo de convite de upgrade do seu app usando uma mensagem de transmissão. A transmissão envia uma notificação push ao dispositivo pelo Google Play Services, o que leva 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:

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

Enviar a transmissão

Confira abaixo as instruções para o app (ou código) do OEM enviar 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 façam o upgrade do SO diretamente do fluxo.

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

Exemplo de uso de transmissões

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

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. Isso é usado para determinar qual fluxo de convite para upgrade será acionado.

SDK dos Serviços do Google Play: apenas acionamento de fluxo

Com o SDK de terceiros, é possível acionar o fluxo de convite 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 de 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:

• minSdkVersion de 14 ou mais recente
• compileSdkVersion 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 Growth do Google 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 de atividade precisa ser o objeto Activity inicial.

Funções da API

O UpgradePartyClient resultante expõe a seguinte funcionalidade.

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

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 de API podem falhar com uma exceção do tipo com.google.android.gms.common.api.ApiException. Nesses casos, o chamador precisa tentar de novo mais tarde. Os códigos de status comuns esperados incluem:

• INTERNAL_ERROR: para qualquer erro no fluxo da lógica subjacente.
• TIMEOUT: se a solicitação não puder ser processada a tempo.
• 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);
             }
           });
   }