O Android 14 Beta já está disponível. Teste hoje mesmo e nos conte o que você achou.

Atualizar o app para oferecer suporte ao gesto "Voltar" preditivo

**Figura 1**: modelo mostrando como funciona o gesto "Voltar" preditivo em um smartphone

O Android 13 introduz um gesto "Voltar" preditivo para os dispositivos Android, como smartphones, telas grandes e dobráveis. Após a implementação, esse recurso vai permitir que o usuário visualize o destino ou o resultado de um gesto "Voltar" antes de concluí-lo. Assim, ele poderá decidir se quer continuar na visualização atual ou concluir a ação.

O gesto "Voltar" pode, por exemplo, exibir uma visualização animada da tela inicial atrás do app, como apresentado na Figura 1. A partir da versão final do Android 13, você poderá ativar uma opção para desenvolvedores a fim de testar a animação de retorno à tela de início. Vamos descrever esse processo nesta página.

Para oferecer suporte ao gesto "Voltar" preditivo, é necessário atualizar o app usando o OnBackPressedCallback do AppCompat versão 1.6.0-alpha03 (no AndroidX ou mais recente) ou usando a nova API da plataforma OnBackInvokedCallback.

Essa atualização oferece um caminho de migração para as APIs de navegação de retorno que não são mais compatíveis, KeyEvent.KEYCODE_BACK, e para as classes com métodos onBackPressed, como Activity e Dialog.

Codelab

Além de consultar a documentação disponível nesta página, você pode acessar nosso codelab, que apresenta a implementação de um caso de uso comum de um WebView que processa o gesto "Voltar" preditivo usando AndroidX Activity APIs.

Atualizar um app que usa a navegação de retorno padrão

Se o app não implementa nenhum comportamento personalizado para a ação "Voltar", ou seja, é o sistema que processa essa ação, a atualização para oferecer suporte ao novo recurso é um processo simples. Basta ativar esse recurso da maneira descrita nesta página.

Atualizar um app que usa uma navegação de retorno personalizada

Existem diferentes caminhos de migração para apps que implementam um comportamento personalizado para a ação "Voltar", dependendo se o app usa o AndroidX e da maneira como ele processa a navegação de retorno.

O app usa o AndroidX	Como o app processa a navegação de retorno	Caminho de migração recomendado (link nesta página)
Sim	APIs do AndroidX	Migrar uma implementação da ação "Voltar" existente do AndroidX
Sim	APIs de plataforma sem suporte	Migrar para as APIs do AndroidX um aplicativo AndroidX com APIs de navegação de retorno sem suporte
Não	App usa APIs de plataforma sem suporte, mas é possível migrá-lo	Migrar para as APIs de plataforma um aplicativo que usa APIs de navegação de retorno sem suporte
Não	App usa APIs de plataforma sem suporte, mas não é possível migrá-lo	Adiar a ativação do recurso até que ele seja obrigatório

Migrar a implementação da navegação de retorno do AndroidX

Esse é o caso de uso mais comum e recomendado. Ele se aplica a apps novos ou existentes que processam uma navegação de retorno por gesto personalizada com OnBackPressedDispatcher, conforme descrito em Oferecer navegação de retorno personalizada.

Caso seu app se encaixe nessa categoria, basta ativar o gesto "Voltar" preditivo, conforme descrito nesta página, para oferecer suporte a esse novo recurso.

Migrar para as APIs do AndroidX um aplicativo AndroidX com APIs de navegação de retorno sem suporte

Se o app usa as bibliotecas do AndroidX, mas implementa ou faz referência a APIs de navegação de retorno sem suporte, você precisará migrar para as APIs do AndroidX para conseguir oferecer suporte ao novo comportamento.

Para migrar de APIs sem suporte e passar a usar as APIs do AndroidX:

Migre a lógica de processamento da ação "Voltar" do sistema para o OnBackPressedDispatcher do AndroidX, implementando OnBackPressedCallback. Encontre instruções detalhadas em Oferecer navegação de retorno personalizada.
Para deixar de interceptar a ação "Voltar" do sistema, desative as instâncias de OnBackPressedCallback, se houver, e não ative callbacks em nenhum momento.
Depois de migrar o app, ative o gesto "Voltar" preditivo, conforme descrito nesta página.

Migrar para as APIs de plataforma um aplicativo que usa APIs de navegação de retorno sem suporte

Caso não seja possível usar as bibliotecas do AndroidX no app e ele implemente ou faça referência à navegação de retorno personalizada usando APIs sem suporte, você precisa migrar para a API de plataforma OnBackInvokedCallback.

Conclua as etapas a seguir para migrar das APIs sem suporte e passar a usar a API da plataforma:

Use a nova API OnBackInvokedCallback em dispositivos com o Android 13 ou versões mais recentes. No Android 12 ou versões anteriores, você precisará usar APIs sem suporte.
Registre sua lógica de retorno personalizada em OnBackInvokedCallback, inserindo a lógica no método onBackInvoked. Isso impede que a atividade em curso seja finalizada, assim, o callback poderá reagir à ação "Voltar" quando o usuário concluir a navegação de retorno.

Para garantir que o app ofereça suporte para futuras melhorias na navegação de retorno do sistema, ele PRECISA cancelar o registro do OnBackInvokedCallback. Caso contrário, o app pode apresentar comportamentos indesejáveis para a ação "Voltar". Por exemplo, ele pode ficar preso entre as duas visualizações, fazendo com que o usuário tenha que forçar o fechamento do app.

Veja um exemplo de como migrar a lógica de onBackPressed:

Kotlin

@Override
fun onCreate() {
    if (BuildCompat.isAtLeastT()) {
        onBackInvokedDispatcher.registerOnBackInvokedCallback(
            OnBackInvokedDispatcher.PRIORITY_DEFAULT
        ) {
            /**
             * onBackPressed logic goes here. For instance:
             * Prevents closing the app to go home screen when in the
             * middle of entering data to a form
             * or from accidentally leaving a fragment with a WebView in it
             *
             * Unregistering the callback to stop intercepting the back gesture:
             * When the user transitions to the topmost screen (activity, fragment)
             * in the BackStack, unregister the callback by using
             * OnBackInvokeDispatcher.unregisterOnBackInvokedCallback
             * (https://developer.android.com/reference/kotlin/android/view/OnBackInvokedDispatcher#unregisteronbackinvokedcallback)
             */
        }
    }
}

Java

@Override
void onCreate() {
  if (BuildCompat.isAtLeastT()) {
    getOnBackInvokedDispatcher().registerOnBackInvokedCallback(
        OnBackInvokedDispatcher.PRIORITY_DEFAULT,
        () -> {
          /**
           * onBackPressed logic goes here - For instance:
           * Prevents closing the app to go home screen when in the
           * middle of entering data to a form
           * or from accidentally leaving a fragment with a WebView in it
           *
           * Unregistering the callback to stop intercepting the back gesture:
           * When the user transitions to the topmost screen (activity, fragment)
           * in the BackStack, unregister the callback by using
           * OnBackInvokeDispatcher.unregisterOnBackInvokedCallback
           * (https://developer.android.com/reference/kotlin/android/view/OnBackInvokedDispatcher#unregisteronbackinvokedcallback)
           */
        }
    );
  }
}

Depois de migrar o app, ative o gesto "Voltar" preditivo, conforme descrito na próxima seção.

Ativar o gesto "Voltar" preditivo

Depois de entender como atualizar o app de acordo com seu caso específico, é fácil oferecer suporte ao gesto "Voltar" preditivo.

Para ativar esse recurso, em AndroidManifest.xml, na tag <application>, defina a sinalização android:enableOnBackInvokedCallback como true.

<application
    ...
    android:enableOnBackInvokedCallback="true"
    ... >
...
</application>

Se você não informar nenhum valor, o padrão será false, o que vai desativar o gesto "Voltar" preditivo.

Testar a animação do gesto "Voltar" preditivo

A partir da versão final do Android 13, você poderá ativar uma opção para desenvolvedores para testar a animação de retorno à tela de início, conforme mostrado na Figura 1.

Para testar a animação, siga estas etapas:

No dispositivo, acesse Configurações > Sistema > Opções do desenvolvedor.
Selecione Animações de gestos "Voltar" preditivos.
Inicie o app atualizado e use o gesto "Voltar" para ver esse recurso em ação.