App Center Distribute – Atualizações no aplicativo para Android

2025-05-05

Importante

O Visual Studio App Center foi desativado em 31 de março de 2025, exceto para os recursos de Análise e Diagnóstico, que continuarão a ter suporte até 30 de junho de 2026. Mais informações.

O App Center Distribute permitirá que seus usuários instalem uma nova versão do aplicativo quando você distribuí-lo via 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. Assim que eles optarem por atualizar, o SDK começará a atualizar seu aplicativo.

Advertência

O Google Play considera o código de atualização no aplicativo como um comportamento mal-intencionado, mesmo que não seja usado em tempo de execução. 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. Se não o fizer, pode levar à não conformidade e à remoção da aplicação do Google Play.

Observação

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

Adicionar atualizações na aplicação ao seu aplicativo

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

1. Adicione o módulo Distribuir 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 em que está interessado.

Abra o arquivo build.gradle de nível de 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 seu plugin Android Gradle é inferior a 3.0.0, você precisa substituir a implementação por compilar.
Salve seu arquivo build.gradle e certifique-se de acionar uma sincronização 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. Inicie o App Center Distribute

Para utilizar o App Center, opte por aceder ao(s) módulo(s) que pretende utilizar. Por padrão, nenhum módulo é iniciado e você deve chamar explicitamente cada um deles ao iniciar o SDK.

Adicione a classe Distribute ao método AppCenter.start() para iniciar o serviço App Center Distribute.

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

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

Certifique-se de que substituiu {Your App Secret} no exemplo de código acima pelo seu Segredo da Aplicação. O Android Studio sugere automaticamente a instrução de importação necessária depois que você adiciona uma referência à Distribute classe ao start() método, mas se você vir um erro informando 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 na atividade de inicialização em segundo plano. Por favor, veja o artigo sobre restrições para iniciar atividades em segundo plano.

Observação

As aplicações executadas 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 as intenções sempre levam o usuário para a tela Configurações de nível superior, 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 o build para o Google Play

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

Configure variantes de compilação adicionando sabores de produto:

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

Modificar o bloco de dependências para consumir diferentes dependências 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 seu arquivo build.gradle e certifique-se de acionar uma sincronização Gradle no Android Studio.
Você pode alterar a variante de compilação no menu suspenso Build > Select Build Variant ou no Build Variants na barra de ferramentas.

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

Usar grupo de distribuição privado

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

Distribute.setUpdateTrack(UpdateTrack.PRIVATE);

Distribute.setUpdateTrack(UpdateTrack.PRIVATE)

Observação

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

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

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

Desativar a verificação automática de atualizações

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

Quando a aplicação é iniciada.
Quando o aplicativo entra em primeiro plano depois de ir para o plano de fundo.
Ao ativar o módulo Distribuir, caso esteja desativado anteriormente.

Se você quiser verificar novas versões manualmente, você pode desativar 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

Este método deve ser chamado antes da chamada de 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 para o App Center e exibe uma caixa de diálogo de atualização caso haja uma nova versão disponível.

Observação

Uma chamada de verificação manual de atualização funciona mesmo quando as atualizações automáticas estão ativadas. Uma verificação manual de atualização é ignorada se outra verificação já estiver sendo feita. A verificação manual de atualizações não será processada se o usuário tiver adiado 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 facilmente fornecer suas próprias cadeias de caracteres de recursos se quiser alterar ou localizar o texto exibido na caixa de diálogo de atualização. Veja as cadeias de caracteres em este 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 recursos do aplicativo.

2. Personalize 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 ligar AppCenter.start , como 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 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()
    }
}

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

Se não chamares notifyUpdateAction, o retorno de chamada irá repetir-se a cada mudança de atividade.

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

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

Seu aplicativo é enviado para o plano de fundo (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. Assim, 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 disponível mais recente do que a usada atualmente, um onNoReleaseAvailable retorno de chamada da interface é DistributeListener invocado. Isso permite que você execute código personalizado em tais cenários. O exemplo acima mostra como exibir a mensagem do sistema quando nenhuma atualização é encontrada.

Habilitar ou desabilitar o App Center Distribute em tempo de execução

Você pode habilitar e desabilitar o App Center Distribute em tempo de execução. Se você desativá-lo, 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 o App Center Distribute novamente, use a mesma API, mas passe true como parâmetro.

Distribute.setEnabled(true);

Distribute.setEnabled(true)

O estado é persistido no armazenamento do dispositivo em todas as inicializações de aplicativos.

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

Observação

Este método só deve ser utilizado depois de Distribute ter sido iniciado.

Verifique se o App Center Distribute está ativado

Você também pode verificar se o App Center Distribute está habilitado 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

Este método só deve ser usado depois de Distribute ter sido iniciado, ele sempre retornará false antes de começar.

Habilitar atualizações no aplicativo para compilações de depuração

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

Para habilitar atualizações na aplicação em compilações de debug, chame o seguinte método antes de AppCenter.start:

Distribute.setEnabledForDebuggableBuild(true);

Distribute.setEnabledForDebuggableBuild(true)

Observação

Esse método afeta apenas compilações de depuração e não tem impacto nas compilações de versão. Debug build significa que o sinalizador android:debuggable é definido como true (que geralmente é definido automaticamente por variantes de compilação de depuração predefinidas gradle). Caso contrário, esta é uma versão de lançamento.

Como funcionam as atualizações no aplicativo?

Observação

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

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

Esse recurso só funciona com compilações RELEASE (por padrão) que são distribuídas usando o serviço App Center Distribuir .
Depois de integrar o SDK, criar a versão de lançamento do seu aplicativo e fazer o upload para o App Center, os usuários desse grupo de distribuição serão notificados sobre a nova versão por e-mail.
Quando cada usuário abre o link em seu e-mail, o aplicativo será instalado em seu dispositivo. É importante que eles usem o link por e-mail para instalar - não damos suporte a carregamento lateral. Quando um aplicativo é baixado do link, o SDK salva informações importantes dos cookies para verificar se há atualizações posteriormente, caso contrário, o SDK não terá 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 voltará a abrir enquanto as informações de autenticação permanecerem válidas, mesmo ao alternar para a faixa pública e voltando novamente para a privada 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), o próximo passo ocorre imediatamente.
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 for:
- um valor superior a versionCode ou
- um valor igual de versionCode mas um valor diferente de versionName.

Sugestão

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

Como faço para testar as atualizações no aplicativo?

Você precisa carregar compilações de versão (que usam o módulo Distribuir do SDK do App Center) para o Portal do App Center para testar atualizações no aplicativo, aumentando os números de versão sempre.

Crie seu aplicativo no Portal do App Center, se ainda não o fez.
Crie um novo grupo de distribuição e nomeie-o, para que você possa reconhecer que ele se destina 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 e-mail novo ou descartável 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 testadores reais.
Crie uma nova compilação do seu aplicativo que inclua o App Center Distribute e contenha a lógica de configuraçã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 sua compilação do aplicativo.
Quando o carregamento terminar, clique em Avançar e selecione o grupo de distribuição que você criou como o Destino da distribuição desse aplicativo.
Revise a Distribuição e distribua a compilação para seu grupo de teste no aplicativo.
As pessoas desse grupo receberão um convite para serem testadores do aplicativo. Assim que aceitarem o convite, podem descarregar a aplicação do Portal do App Center nos seus dispositivos móveis. Depois que eles tiverem as atualizações no aplicativo instaladas, você estará pronto para testar as atualizações no aplicativo.
Aumente o versionCode do seu aplicativo.
Crie a versão de lançamento do seu aplicativo e carregue uma nova compilação do seu aplicativo como 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 fornecer uma nova versão na próxima vez que o aplicativo for iniciado.

Sugestão

Dê uma olhada nas informações sobre como utilizar o App Center Distribute para obter informações mais detalhadas sobre Grupos de Distribuição , etc. Embora seja possível usar o App Center Distribute para distribuir uma nova versão do seu aplicativo sem adicionar nenhum código, adicionar o App Center Distribute ao código do seu 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.

Partilhar via

App Center Distribute – Atualizações no aplicativo para Android

Adicionar atualizações na aplicação ao seu aplicativo

1. Adicione o módulo Distribuir do App Center

2. Inicie o App Center Distribute

Preparar o build para o Google Play

Usar grupo de distribuição privado

Desativar a verificação automática de atualizações

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. Personalize a caixa de diálogo de atualização

Habilitar ou desabilitar o App Center Distribute em tempo de execução

Verifique se o App Center Distribute está ativado

Habilitar atualizações no aplicativo para compilações de depuração

Como funcionam as atualizações no aplicativo?

Como faço para testar as atualizações no aplicativo?

Comentários

Recursos adicionais