App Center Distribute – atualizações no aplicativo Android

2025-05-05

Importante

O Visual Studio App Center foi desativado em 31 de março de 2025, com exceção dos recursos de Análise e Diagnóstico, que continuarão com suporte até 30 de junho de 2026. Saiba mais.

A Distribuição do App Center permitirá que os usuários instalem uma nova versão do aplicativo quando você distribuí-la por meio do App Center. Com uma nova versão do aplicativo disponível, o SDK apresentará uma caixa de diálogo de atualização aos usuários para baixar ou adiar a nova versão. Depois que eles optarem por atualizar, o SDK começará a atualizar seu aplicativo.

Aviso

O Google Play considera o código de atualização no aplicativo como um comportamento mal-intencionado, mesmo que ele não seja usado em runtime. Use uma variante do SDK de Distribuição conforme indicado nesta seção ou remova completamente o SDK de Distribuição que contém o código de atualização no aplicativo antes de enviar seu aplicativo para o Google Play. A falha ao fazer isso pode levar à não conformidade e à remoção do aplicativo do Google Play.

Observação

Se você estiver executando testes automatizados de interface do usuário, as atualizações habilitadas no aplicativo bloquearão seus testes automatizados de interface do usuário, pois tentarão se autenticar no back-end do App Center. Recomendamos não habilitar a Distribuição do App Center para seus testes de interface do usuário.

Adicionar atualizações no aplicativo ao seu aplicativo

Siga a seção Introdução se você ainda não configurou e iniciou o SDK em seu aplicativo.

1. Adicionar o módulo Distribuição do App Center

O SDK do App Center foi projetado com uma abordagem modular– um desenvolvedor só precisa integrar os módulos dos serviços nos quais está interessado.

Abra o arquivo build.gradle no nível do aplicativo do projeto (app/build.gradle) e adicione as seguintes linhas após apply plugin.
```
dependencies {
   def appCenterSdkVersion = '5.0.6'
   implementation "com.microsoft.appcenter:appcenter-distribute:${appCenterSdkVersion}"
}
```
Observação

Se a versão do plug-in do Android Gradle for inferior à 3.0.0, você precisará substituir implementation por compile.
Salve o arquivo build.gradle e acione uma sincronização do Gradle no Android Studio.
DownloadManager é usado para baixar atualizações. O SDK do App Center impõe o TLS 1.2 para melhorar a segurança.

2. Iniciar Distribuição do App Center

Para usar o App Center, opte pelos módulos que você deseja usar. Por padrão, nenhum módulo é iniciado e você deve chamar explicitamente cada um deles ao iniciar o SDK.

Adicione a classe Distribuir ao método AppCenter.start() para iniciar o Serviço de Distribuição do App Center.

AppCenter.start(getApplication(), "{Your App Secret}", Distribute.class);

AppCenter.start(application, "{Your App Secret}", Distribute::class.java)

Verifique se você substituiu {Your App Secret} o exemplo de código acima pelo segredo do aplicativo. O Android Studio sugere automaticamente a instrução de importação necessária depois de adicionar uma referência à Distribute classe ao start() método, mas se você vir um erro de que os nomes de classe não são reconhecidos, adicione as seguintes linhas às instruções de importação em sua classe de atividade:

import com.microsoft.appcenter.AppCenter;
import com.microsoft.appcenter.distribute.Distribute;

import com.microsoft.appcenter.AppCenter
import com.microsoft.appcenter.distribute.Distribute

Observação

O Android 10 ou superior tem restrições à atividade de inicialização em segundo plano. Consulte o artigo sobre restrições ao iniciar atividades em segundo plano.

Observação

Aplicativos em execução no Android 10 (edição Go) não podem receber a permissão SYSTEM_ALERT_WINDOW . Consulte o artigo sobre SYSTEM_ALERT_WINDOW em dispositivos Go.

Observação

A partir do Android 11, ACTION_MANAGE_OVERLAY_PERMISSION intents sempre levam o usuário à tela principal de Configurações, onde o usuário pode conceder ou revogar as SYSTEM_ALERT_WINDOW permissões para aplicativos. Consulte o artigo sobre atualizações de permissões no Android 11.

Preparar seu build do Google Play

Abra o arquivo build.gradle no nível do aplicativo do projeto (app/build.gradle).

Configure variantes de build adicionando sabores de produto:

android {
    flavorDimensions "distribute"
    productFlavors {
        appCenter {
            dimension "distribute"
        }
        googlePlay {
            dimension "distribute"
        }
    }
}

Modifique o bloco de dependências para consumir dependências diferentes com base no sabor do produto:

dependencies {
    def appCenterSdkVersion = "5.0.6"
    appCenterImplementation "com.microsoft.appcenter:appcenter-distribute:${appCenterSdkVersion}"
    googlePlayImplementation "com.microsoft.appcenter:appcenter-distribute-play:${appCenterSdkVersion}"
}

Salve o arquivo build.gradle e acione uma sincronização do Gradle no Android Studio.
Você pode alterar a variante de build no menu suspenso Build > Select Build Variant ou Build Variants na barra de janelas de ferramentas .

Você pode ler mais sobre como configurar variantes de build na documentação do Android.

Usar grupo de distribuição privado

Por padrão, o Distribute usa um grupo de distribuição público. Se você quiser usar um grupo de distribuição privado, precisará defini-lo explicitamente por meio da setUpdateTrack API.

Distribute.setUpdateTrack(UpdateTrack.PRIVATE);

Distribute.setUpdateTrack(UpdateTrack.PRIVATE)

Observação

O valor padrão é UpdateTrack.PUBLIC. Esse método só pode ser chamado antes da chamada do AppCenter.start método. As alterações na faixa de atualização não são mantidas quando o processo do aplicativo é reiniciado e, portanto, se o método nem sempre for chamado antes da AppCenter.start chamada, ele será público, por padrão.

Quando o aplicativo está em primeiro plano (depois de Distribute.setUpdateTrack(UpdateTrack.PRIVATE); e AppCenter.start), uma janela do navegador é aberta para autenticar o usuário. Todas as verificações de atualizações subsequentes obterão a versão mais recente no canal privado.

Se um usuário estiver na faixa privada, isso significa que, após a autenticação bem-sucedida, ele obterá a versão mais recente de todos os grupos de distribuição privados dos quais ele é membro. Se um usuário estiver na faixa pública, isso significa que ele obterá a versão mais recente de qualquer grupo de distribuição pública.

Desabilitar a Verificação Automática de Atualização

Por padrão, o SDK verifica automaticamente se há novas versões:

Quando o aplicativo é iniciado.
Quando o aplicativo entra em primeiro plano depois de ir para o segundo plano.
Ao habilitar o módulo Distribuir, caso ele tenha sido desabilitado anteriormente.

Se você quiser verificar se há novas versões manualmente, poderá desabilitar a verificação automática de atualização. Para fazer isso, chame o seguinte método antes do início do SDK:

Distribute.disableAutomaticCheckForUpdate();

Distribute.disableAutomaticCheckForUpdate()

Observação

Esse método deve ser chamado antes da chamada do AppCenter.start método.

Em seguida, você pode usar a checkForUpdate API, que é descrita na seção a seguir.

Verificar manualmente se há atualização

Distribute.checkForUpdate();

Distribute.checkForUpdate()

Isso envia uma solicitação ao App Center e exibe uma caixa de diálogo de atualização caso haja uma nova versão disponível.

Observação

Uma verificação manual de chamada de atualização funciona mesmo quando as atualizações automáticas estão habilitadas. Uma verificação manual de atualização será ignorada se outra verificação já estiver sendo feita. A verificação manual da atualização não será processada se o usuário tiver adiado as atualizações (a menos que a versão mais recente seja uma atualização obrigatória).

Personalizar ou localizar a caixa de diálogo de atualização no aplicativo

1. Personalizar ou localizar texto

Você pode fornecer facilmente suas próprias cadeias de caracteres de recurso se quiser alterar ou localizar o texto exibido na caixa de diálogo de atualização. Examine os arquivos de cadeia de caracteres neste arquivo de recurso. Use o mesmo nome/chave de cadeia de caracteres e especifique o valor localizado a ser refletido na caixa de diálogo em seus próprios arquivos de recurso de aplicativo.

2. Personalizar a caixa de diálogo de atualização

Você pode personalizar a aparência da caixa de diálogo de atualização padrão implementando a DistributeListener interface. Você precisa registrar o ouvinte antes de chamar AppCenter.start , conforme mostrado no exemplo a seguir:

Distribute.setListener(new MyDistributeListener());
AppCenter.start(...);

Distribute.setListener(MyDistributeListener())
AppCenter.start(...)

Aqui está um exemplo da implementação do ouvinte que substitui a caixa de diálogo do SDK por uma personalizada:

import android.app.Activity;
import android.app.AlertDialog;
import android.content.DialogInterface;
import android.net.Uri;

import com.microsoft.appcenter.distribute.Distribute;
import com.microsoft.appcenter.distribute.DistributeListener;
import com.microsoft.appcenter.distribute.ReleaseDetails;
import com.microsoft.appcenter.distribute.UpdateAction;

public class MyDistributeListener implements DistributeListener {

    @Override
    public boolean onReleaseAvailable(Activity activity, ReleaseDetails releaseDetails) {

        // Look at releaseDetails public methods to get version information, release notes text or release notes URL
        String versionName = releaseDetails.getShortVersion();
        int versionCode = releaseDetails.getVersion();
        String releaseNotes = releaseDetails.getReleaseNotes();
        Uri releaseNotesUrl = releaseDetails.getReleaseNotesUrl();

        // Build our own dialog title and message
        AlertDialog.Builder dialogBuilder = new AlertDialog.Builder(activity);
        dialogBuilder.setTitle("Version " + versionName + " available!"); // you should use a string resource instead, this is just a simple example
        dialogBuilder.setMessage(releaseNotes);

        // Mimic default SDK buttons
        dialogBuilder.setPositiveButton(com.microsoft.appcenter.distribute.R.string.appcenter_distribute_update_dialog_download, new DialogInterface.OnClickListener() {

            @Override
            public void onClick(DialogInterface dialog, int which) {

                // This method is used to tell the SDK what button was clicked
                Distribute.notifyUpdateAction(UpdateAction.UPDATE);
            }
        });

        // We can postpone the release only if the update isn't mandatory
        if (!releaseDetails.isMandatoryUpdate()) {
            dialogBuilder.setNegativeButton(com.microsoft.appcenter.distribute.R.string.appcenter_distribute_update_dialog_postpone, new DialogInterface.OnClickListener() {

                @Override
                public void onClick(DialogInterface dialog, int which) {

                    // This method is used to tell the SDK what button was clicked
                    Distribute.notifyUpdateAction(UpdateAction.POSTPONE);
                }
            });
        }
        dialogBuilder.setCancelable(false); // if it's cancelable you should map cancel to postpone, but only for optional updates
        dialogBuilder.create().show();

        // Return true if you're using your own dialog, false otherwise
        return true;
    }
    
    @Override
    public void onNoReleaseAvailable(Activity activity) {
        Toast.makeText(activity, activity.getString(R.string.no_updates_available), Toast.LENGTH_LONG).show();
    }
}

import android.app.Activity
import android.app.AlertDialog
import com.microsoft.appcenter.distribute.Distribute
import com.microsoft.appcenter.distribute.DistributeListener
import com.microsoft.appcenter.distribute.ReleaseDetails
import com.microsoft.appcenter.distribute.UpdateAction

class MyDistributeListener : DistributeListener {

    override fun onReleaseAvailable(activity: Activity, releaseDetails: ReleaseDetails): Boolean {

        // Look at releaseDetails public methods to get version information, release notes text or release notes URL
        val versionName = releaseDetails.shortVersion
        val versionCode = releaseDetails.version
        val releaseNotes = releaseDetails.releaseNotes
        val releaseNotesUrl = releaseDetails.releaseNotesUrl

        // Build our own dialog title and message
        val dialogBuilder = AlertDialog.Builder(activity)
        dialogBuilder.setTitle("Version $versionName available!") // you should use a string resource instead, this is just a simple example
        dialogBuilder.setMessage(releaseNotes)

        // Mimic default SDK buttons
        dialogBuilder.setPositiveButton(
            com.microsoft.appcenter.distribute.R.string.appcenter_distribute_update_dialog_download
        ) { dialog, which ->
            // This method is used to tell the SDK what button was clicked
            Distribute.notifyUpdateAction(UpdateAction.UPDATE)
        }

        // We can postpone the release only if the update isn't mandatory
        if (!releaseDetails.isMandatoryUpdate) {
            dialogBuilder.setNegativeButton(
                com.microsoft.appcenter.distribute.R.string.appcenter_distribute_update_dialog_postpone
            ) { dialog, which ->
                // This method is used to tell the SDK what button was clicked
                Distribute.notifyUpdateAction(UpdateAction.POSTPONE)
            }
        }
        dialogBuilder.setCancelable(false) // if it's cancelable you should map cancel to postpone, but only for optional updates
        dialogBuilder.create().show()

        // Return true if you're using your own dialog, false otherwise
        return true
    }

    override fun onNoReleaseAvailable(activity: Activity) {
        Toast.makeText(activity, activity.getString(R.string.no_updates_available), Toast.LENGTH_LONG).show()
    }
}

Conforme mostrado no exemplo, você deve chamar Distribute.notifyUpdateAction(UpdateAction.UPDATE); ou Distribute.notifyUpdateAction(UpdateAction.POSTPONE); se o ouvinte retornar true.

Se você não chamar notifyUpdateAction, o callback será repetido a cada mudança de atividade.

O ouvinte poderá ser chamado novamente com a mesma versão se a atividade for alterada antes que a ação do usuário seja notificada para o SDK.

Esse comportamento é necessário para abranger os seguintes cenários:

Seu aplicativo é enviado para o segundo plano (como pressionar HOME) e, em seguida, retomado em uma atividade diferente.
Sua atividade é coberta por outra sem sair do aplicativo (como clicar em algumas notificações).
Outros cenários semelhantes.

Nesse caso, a atividade que hospeda a caixa de diálogo pode ser substituída sem interação do usuário. Portanto, o SDK chama o ouvinte novamente para que você possa restaurar a caixa de diálogo personalizada.

Nos casos em que o SDK verifica se há atualizações e não encontra nenhuma atualização mais recente disponível do que a usada atualmente, é invocado um retorno de chamada da interface onNoReleaseAvailable de DistributeListener. Isso permite que você execute código personalizado nesses cenários. O exemplo acima mostra como exibir uma mensagem de notificação quando nenhuma atualização é encontrada.

Habilitar ou desabilitar a Distribuição do App Center em tempo de execução

Você pode habilitar e desabilitar a Distribuição do App Center em tempo de execução. Se você desabilitar, o SDK não fornecerá nenhuma funcionalidade de atualização no aplicativo, mas você ainda poderá usar o serviço Distribuir no portal do App Center.

Distribute.setEnabled(false);

Distribute.setEnabled(false)

Para habilitar a Distribuição do App Center novamente, use a mesma API, mas transmita true como um parâmetro.

Distribute.setEnabled(true);

Distribute.setEnabled(true)

O estado é mantido no armazenamento do dispositivo entre as inicializações do aplicativo.

Essa API é assíncrona, você pode ler mais sobre isso em nosso guia de APIs assíncronas do App Center .

Observação

Esse método só deve ser usado depois que Distribute tiver sido iniciado.

Verificar se a Distribuição do App Center está habilitada

Você também pode verificar se a Distribuição do App Center está habilitada ou não:

Distribute.isEnabled();

Distribute.isEnabled()

Essa API é assíncrona, você pode ler mais sobre isso em nosso guia de APIs assíncronas do App Center .

Observação

Esse método só deve ser usado depois Distribute de iniciado, ele sempre retornará false antes do início.

Habilitar atualizações para o aplicativo em versões de depuração

Por padrão, o App Center habilita atualizações no aplicativo somente para builds de versão.

Para habilitar as atualizações no aplicativo em builds de depuração, chame o seguinte método antes de AppCenter.start:

Distribute.setEnabledForDebuggableBuild(true);

Distribute.setEnabledForDebuggableBuild(true)

Observação

Esse método afeta apenas as compilações de depuração e não tem impacto nas compilações de lançamento. A compilação de depuração significa que o sinalizador android:debuggable está definido como true (o que geralmente é definido automaticamente pelas variantes de build de depuração predefinidas do Gradle). Caso contrário, esse é um build de versão.

Como funcionam as atualizações no aplicativo?

Observação

Para que as atualizações no aplicativo funcionem, um build de aplicativo deve ser baixado do link. Ele não funcionará se instalado de um IDE ou manualmente.

O recurso de atualizações no aplicativo funciona da seguinte maneira:

Esse recurso só funciona com builds RELEASE (por padrão) que são distribuídos usando o serviço Distribuição do App Center .
Depois de integrar o SDK, criar a versão de lançamento do aplicativo e carregá-lo no App Center, os usuários desse grupo de distribuição serão notificados sobre a nova versão por email.
Quando cada usuário abrir o link em seu email, o aplicativo será instalado em seu dispositivo. É importante que eles usem o link de email para instalar. Não há suporte para carregamento lateral. Quando um aplicativo é baixado do link, o SDK salva informações importantes de cookies para verificar se há atualizações mais tarde, caso contrário, o SDK não tem essas informações importantes.
Se o aplicativo definir a faixa como privada, um navegador será aberto para autenticar o usuário e habilitar atualizações no aplicativo. O navegador não abrirá novamente enquanto as informações de autenticação forem válidas, mesmo ao alternar para o modo público e voltar para o modo privado mais tarde. Se a autenticação do navegador for bem-sucedida, o usuário será redirecionado de volta para o aplicativo automaticamente. Se a faixa for pública (que é o padrão), a próxima etapa ocorrerá diretamente.
Uma nova versão do aplicativo mostra a caixa de diálogo de atualização no aplicativo solicitando que os usuários atualizem seu aplicativo se ele for:
- um valor mais alto de versionCode ou
- um valor igual de versionCode , mas um valor diferente de versionName.

Dica

Se você carregar a mesma APK uma segunda vez, a caixa de diálogo NÃO aparecerá, pois as versões são idênticas.

Como fazer para testar as atualizações no aplicativo?

Você precisa carregar builds de liberação (que usam o módulo Distribuir do SDK do App Center) no Portal do App Center para testar atualizações internas do aplicativo, aumentando o número de versão em cada atualização.

Crie seu aplicativo no Portal do App Center se ainda não tiver feito isso.
Crie um novo grupo de distribuição e nomeie-o, para que você possa reconhecer que ele destina-se a testar o recurso de atualização no aplicativo.
Adicione a si mesmo (ou a todas as pessoas que você deseja incluir no teste do recurso de atualização no aplicativo). Use um endereço de email novo ou descartado para isso, que não foi usado para esse aplicativo no App Center. Isso garante que sua experiência esteja próxima da experiência de seus verdadeiros testadores.
Crie um novo build de seu aplicativo que inclua a Distribuição do App Center e contenha a lógica de instalação, conforme descrito acima. Se o grupo for privado, não se esqueça de definir a faixa de atualização privada no aplicativo antes de começar a usar a API setUpdateTrack.
Clique no botão Distribuir nova versão no portal e carregue o build do aplicativo.
Depois que o upload for concluído, clique em Avançar e selecione o grupo de distribuição que você criou como o destino da distribuição do aplicativo.
Examine a Distribuição e distribua o build para seu grupo de testes no aplicativo.
As pessoas nesse grupo receberão um convite para serem testadores do aplicativo. Depois de aceitarem o convite, eles poderão baixar o aplicativo no Portal do App Center em seu dispositivo móvel. Depois que elas tiverem as atualizações no aplicativo instaladas, você estará pronto para testar as atualizações no aplicativo.
Atualize o versionCode do seu aplicativo.
Crie a versão de lançamento do seu aplicativo e carregue um novo build do seu aplicativo como você fez na etapa anterior e distribua isso para o Grupo de Distribuição criado anteriormente. Os membros do Grupo de Distribuição serão solicitados a obter uma nova versão na próxima vez que o aplicativo for iniciado.

Dica

Confira as informações sobre como utilizar a Distribuição do App Center para obter informações mais detalhadas sobre grupos de distribuição etc. Embora seja possível usar a Distribuição do App Center para distribuir uma nova versão do seu aplicativo sem adicionar nenhum código, adicionar a Distribuição do App Center ao código do aplicativo resultará em uma experiência mais perfeita para seus testadores e usuários à medida que eles obtêm a experiência de atualização no aplicativo.

Compartilhar via

App Center Distribute – atualizações no aplicativo Android

Adicionar atualizações no aplicativo ao seu aplicativo

1. Adicionar o módulo Distribuição do App Center

2. Iniciar Distribuição do App Center

Preparar seu build do Google Play

Usar grupo de distribuição privado

Desabilitar a Verificação Automática de Atualização

Verificar manualmente se há atualização

Personalizar ou localizar a caixa de diálogo de atualização no aplicativo

1. Personalizar ou localizar texto

2. Personalizar a caixa de diálogo de atualização

Habilitar ou desabilitar a Distribuição do App Center em tempo de execução

Verificar se a Distribuição do App Center está habilitada

Habilitar atualizações para o aplicativo em versões de depuração

Como funcionam as atualizações no aplicativo?

Como fazer para testar as atualizações no aplicativo?

Comentários

Recursos adicionais