Distribuição do App Center – Atualizações no aplicativo do Unity

Importante

O Visual Studio App Center está programado para ser desativado em 31 de março de 2025. Embora você possa continuar a usar o Visual Studio App Center até que ele seja totalmente desativado, há várias alternativas recomendadas para as quais você pode considerar a migração.

Saiba mais sobre linhas do tempo e alternativas de suporte.

• Android
• iOS
• Unity
• MAUI/Xamarin

A Distribuição do App Center permite que seus usuários/testadores instalem novas versões de um aplicativo depois de distribuí-lo por meio do App Center. Depois de habilitado, o SDK apresenta uma caixa de diálogo de atualização aos usuários para baixar ou adiar a instalação da atualização mais recente. Depois que eles optarem por atualizar, o SDK começará a atualizar seu aplicativo.

Importante

O SDK de Distribuição para Unity não dá suporte à UWP. As instruções nesta página abrangem apenas Android e iOS.

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. Remova esse código conforme indicado nesta seção antes de enviar seu aplicativo para o Google Play. A falha ao não remover o código de atualização no aplicativo 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 de interface do usuário automatizados, pois tentarão se autenticar no back-end do App Center. Recomendamos desabilitar atualizações no aplicativo para seus testes de interface do usuário.

Adicionar atualizações no aplicativo ao seu aplicativo

Adicionar 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 nos quais está interessado.

Siga os documentos de introdução do Unity se você ainda não configurou e iniciou o SDK em seu aplicativo. Certifique-se de importar o pacote Distribuição do App Center. Seu nome deve estar no formato AppCenterDistribute-v{version}.unitypackage.

Observação

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

Observação

Os 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 as intenções sempre levam o usuário para a tela Configurações de nível superior, em que 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.

Remover atualizações no aplicativo para builds do Google Play

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. Remova esse código antes de enviar seu aplicativo para o Google Play. A falha ao não remover o código de atualização no aplicativo pode levar à não conformidade e à remoção do aplicativo do Google Play. Para remover o código nativo de atualizações no aplicativo, desmarque a caixa de seleção Usar Distribuir na seção Distribuir no objeto de jogo com AppCenterBehavior anexado.

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á alterar UpdateTrack para Privado. Para fazer isso, escolha Privado na lista suspensa Atualizar Faixa em Distribuir seção no objeto de jogo com AppCenterBehavior anexado.

Ao usar a faixa privada, uma janela do navegador será aberta para autenticar o usuário. Todas as verificações de atualização subsequentes obterão a versão mais recente na faixa privada.

Se um usuário estiver no caminho privado, isso significa que, após a autenticação bem-sucedida, ele obterá a versão mais recente de qualquer grupo de distribuição privado do qual seja membro. Se um usuário estiver no caminho público, isso significa que ele obterá a versão mais recente de qualquer grupo de distribuição pública.

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

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

• Quando o aplicativo é iniciado.
• Quando o aplicativo entra em segundo plano, em primeiro plano novamente.
• Ao habilitar o módulo Distribuir se estiver desabilitado anteriormente.

Se você quiser marcar para novas versões manualmente, poderá desabilitar o marcar automático para atualização.

Para fazer isso, desmarque a caixa de seleção Verificação Automática para Atualização em Distribuir seção no objeto de jogo com AppCenterBehavior anexado.

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

Verificar manualmente se há atualização

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

Um marcar manual para a chamada de atualização funciona mesmo quando as atualizações automáticas estão habilitadas. Uma marcar manual para atualização será ignorada se outra marcar já estiver sendo feita. O marcar manual para atualização não será processado 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 suas próprias cadeias de caracteres de recurso se quiser localizar o texto exibido na caixa de diálogo de atualização. Examine os arquivos de cadeia de caracteres para iOS neste arquivo de recurso do iOS e para Android neste arquivo de recurso do Android. 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 o ReleaseAvailable retorno de chamada.

Aviso

Você precisa registrar o retorno de chamada no Awake método de um MonoBehaviour na primeira cena que o aplicativo carrega para evitar a falta de invocações de retorno de chamada de versão.

// In this example, OnReleaseAvailable is a method name in same class
Distribute.ReleaseAvailable = OnReleaseAvailable;

Aqui está uma implementação de retorno de chamada que substitui a caixa de diálogo do SDK pela lógica personalizada:

bool OnReleaseAvailable(ReleaseDetails releaseDetails)
{
    // Look at releaseDetails public properties to get version information, release notes text or release notes URL
    string versionName = releaseDetails.ShortVersion;
    string versionCodeOrBuildNumber = releaseDetails.Version;
    string releaseNotes = releaseDetails.ReleaseNotes;
    Uri releaseNotesUrl = releaseDetails.ReleaseNotesUrl;

    // (Do something with the values if you want)

    // On mandatory update, user can't postpone
    if (releaseDetails.MandatoryUpdate)
    {
        // Force user to update (you should probably show some custom UI here)
        Distribute.NotifyUpdateAction(UpdateAction.Update);
    }
    else
    {
        // Allow user to update or postpone (you should probably show some custom UI here)
        // "GetUserUpdateAction()" isn't part of the SDK; it just represents a way of getting user response.
        // This blocks the thread while awaiting the user's response! This example shouldn't be used literally
        UpdateAction updateAction = GetUserUpdateAction();
        Distribute.NotifyUpdateAction(updateAction);
    }
    // Return true if you're using your own UI to get user response, false otherwise
    return true;
}

Notas de implementação para Android:

Conforme mostrado no exemplo, você deve chamar Distribute.NotifyUpdateAction(UpdateAction.UPDATE); ou Distribute.NotifyUpdateAction(UpdateAction.POSTPONE); se o retorno de chamada retornar true.

Se você não chamar NotifyUpdateAction, o retorno de chamada será repetido em cada alteração de atividade.

O retorno de chamada 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 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).
• Cenários semelhantes ao acima.

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.

3. Executar código se nenhuma atualização for encontrada

Nos casos em que o SDK verifica se há atualizações e não encontra atualizações disponíveis mais recentes do que a usada atualmente, um NoReleaseAvailable retorno de chamada é invocado. Isso permite que você execute um código personalizado nesses cenários. Você precisa registrar o retorno de chamada antes de chamar AppCenter.Start , conforme mostrado no exemplo a seguir:

// In this example OnNoReleaseAvailable is a method name in same class
Distribute.NoReleaseAvailable = OnNoReleaseAvailable;
AppCenter.Start(...);

void OnNoReleaseAvailable()
{
    AppCenterLog.Info(LogTag, "No release available callback invoked.");
}

## Enable or disable App Center Distribute at runtime

You can enable and disable App Center Distribute at runtime. If you disable it, the SDK won't provide any in-app update functionality but you can still use the Distribute service in the App Center portal.

To disable the Distribute service, use the following code:

```csharp
Distribute.SetEnabledAsync(false);

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

Distribute.SetEnabledAsync(true);

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

Você não precisa aguardar essa chamada para tornar outras chamadas à API (como IsEnabledAsync) consistentes.

O estado é persistente no armazenamento do dispositivo entre as inicializações de aplicativos.

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

Você também pode marcar se a Distribuição do App Center estiver habilitada:

Distribute.IsEnabledAsync();

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

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

Por padrão, as atualizações no aplicativo são habilitadas apenas para builds de versão.

Para habilitar atualizações no aplicativo para builds de depuração no Android e no iOS, marcar caixa de seleção Habilitar Distribuir em Depurar, na seção Distribuir no objeto de jogo com AppCenterBehavior anexado.

No Unity, um build depurável é um build com uma opção de build de desenvolvimento marcada.

Executar limpo antes que o aplicativo seja fechado para atualização

Observação

Esse retorno de chamada só funciona no iOS.

Registre o retorno de chamada conforme mostrado no exemplo a seguir:

// In this example, OnWillExitApp is a method name in same class
Distribute.WillExitApp = OnWillExitApp;

void OnWillExitApp()
{
    // Perform clean up here
}

Com isso, OnWillExitApp() será invocado quando Distribute estiver prestes a fechar.

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:

1. Esse recurso só funciona com builds RELEASE (por padrão) que são distribuídos usando o serviço Distribuição do App Center . Ele não funcionará se o recurso de Acesso Guiado do iOS estiver ativado.
2. Depois de integrar o SDK, crie uma versão de lançamento do aplicativo e carregue-a no App Center. Os usuários do grupo de distribuição são notificados sobre a nova versão por email.
3. 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 damos suporte ao sideload. Quando um aplicativo é baixado do link, o SDK salva informações importantes de cookies para marcar para atualizações posteriormente, caso contrário, o SDK não tem essas informações de chave.
4. 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 será aberto novamente, desde que as informações de autenticação permaneçam válidas mesmo ao alternar de volta para a faixa pública e voltar para privadas novamente 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.
5. 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:
   • iOS:
     • um valor mais alto de CFBundleShortVersionString ou
     • um valor igual de CFBundleShortVersionString , mas um valor mais alto de CFBundleVersion.
     • as versões são as mesmas, mas o identificador exclusivo de build é diferente.
   • Android:
     • um valor mais alto de versionCode ou
     • um valor igual de versionCode , mas um valor diferente de versionName.

Dica

Se você carregar o mesmo .apk/.ipa uma segunda vez, a caixa de diálogo não aparecerá, pois os binários são idênticos. No iOS, se você carregar um novo build com as mesmas propriedades de versão, ele mostrará a caixa de diálogo de atualização. O motivo disso é que ele é um binário diferente. No Android, os binários serão considerados os mesmos se ambas as propriedades de versão forem as mesmas.

Como fazer testar atualizações no aplicativo?

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

1. Crie seu aplicativo no Portal do App Center, caso ainda não tenha feito isso.
2. Crie um novo grupo de distribuição e dê um nome a ele.
3. 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 esta etapa, um que ainda não foi usado com este aplicativo. Isso garante que sua experiência esteja próxima da experiência de seus testadores reais.
4. Crie um novo build do seu aplicativo que inclua o App Center Distribute e contenha a lógica de configuração, conforme descrito abaixo. 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 UpdateTrack propriedade .
5. Clique no botão Distribuir nova versão no portal e carregue a compilação do aplicativo.
6. Depois que o upload for concluído, clique em Avançar e selecione o Grupo de distribuição que você criou anteriormente como o Destino dessa distribuição de aplicativo.
7. Examine a Distribuição e distribua o build para o grupo de testes no aplicativo.
8. Pessoas nesse grupo receberão um convite para serem testadores do aplicativo. Depois de aceitar o convite, eles poderão baixar o aplicativo do Portal do App Center de seu dispositivo móvel. Depois que as atualizações no aplicativo estiverem instaladas, você estará pronto para testar as atualizações no aplicativo.
9. Aumente a versão do seu aplicativo (CFBundleShortVersionString ou CFBundleVersion para iOS, versionCode para Android).
10. Crie a versão de lançamento do seu aplicativo e carregue um novo build como você fez na etapa anterior. Distribua 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.

Dica

Veja as 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 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.