Distribuição do App Center – atualizações do MAUI e do Xamarin no aplicativo

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.

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.

Visual Studio para Mac

• Abra o Visual Studio para Mac.
• Clique em Abrir Arquivo> e escolha sua solução.
• No navegador da solução, clique com o botão direito do mouse na seção Pacotes e escolha Adicionar pacotes NuGet....
• Pesquise por App Center e instale App Center Distribute.
• Clique em Adicionar Pacotes.

Visual Studio para Windows

• Abra o Visual Studio para Windows.
• Clique em Abrir Arquivo> e escolha sua solução.
• No navegador da solução, clique com o botão direito do mouse em Referências e escolha Gerenciar Pacotes NuGet.
• Pesquise pelo App Center e instale o Microsoft.AppCenter.Distribute.

Console do Gerenciador de Pacotes

• Abra o console no Visual Studio. Para fazer isso, escolha Ferramentas>Gerenciador de Pacotes NuGet>Console do Gerenciador de Pacotes.
• Se você estiver trabalhando no Visual Studio para Mac, verifique se instalou as Extensões de Gerenciamento de Pacotes NuGet. Para isso, escolhaExtensões do >, pesquise nuGet e instale, se necessário.
• Digite o seguinte comando no console:

Install-Package Microsoft.AppCenter.Distribute

2. Iniciar Distribuição do App Center

Configure o SDK do App Center chamando AppCenter.Start(...) conforme descrito no guia de introdução.

Para seu aplicativo iOS, abra o AppDelegate.cs e adicione a seguinte linha antes da chamada para LoadApplication:

Distribute.DontCheckForUpdatesInDebug();

Esta etapa não é necessária no Android, onde a configuração de depuração é detectada automaticamente no momento da execução.

Para habilitar atualizações no aplicativo para builds de depuração no Android, chame o método a seguir no arquivo MainActivity.cs do projeto, no método OnCreate e antes LoadApplication.

Distribute.SetEnabledForDebuggableBuild(true);

2.3 [Somente para iOS] Modifique o Info.plist do projeto

O SDK do App Center verifica as URLs redirecionando para o aplicativo para evitar o carregamento paralelo, portanto, para que as atualizações distribuídas pelo portal sejam tratadas corretamente, você precisará especificar CFBundleURLSchemes na seção CFBundleURLTypes do arquivo Info.plist.

1. Adicione uma nova chave para URL types ou CFBundleURLTypes em seu arquivo Info.plist (caso o Xcode exiba seu Info.plist como código-fonte).
2. Altere a chave do primeiro item filho para URL Schemes ou CFBundleURLSchemes.
3. Insira appcenter-${APP_SECRET} como o esquema de URL e substitua ${APP_SECRET} pelo Segredo do Aplicativo do seu aplicativo.

<key>CFBundleURLTypes</key>
  <array>
      <dict>
          <key>CFBundleURLSchemes</key>
          <array>
              <string>appcenter-${APP_SECRET}</string>
          </array>
      </dict>
  </array>

Remover atualizações dentro do 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. 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 facilitar, fornecemos uma versão do SDK de Distribuição do App Center com APIs simuladas, portanto, a única alteração para você é uma troca de dependência.

1. Adicione uma nova configuração de build nomeada GooglePlay para seu Xamarin.Android e projetos compartilhados. Verifique se a configuração de compilação dos projetos está corretamente associada à configuração de solução apropriada. Consulte as instruções do Visual Studio ou do Visual Studio para Mac para obter mais detalhes.

2. Abra o Xamarin.Android e os projetos compartilhados em .csproj qualquer editor de texto e mova a referência de distribuição para o grupo de itens condicionais:

   <ItemGroup Condition=" '$(Configuration)' != 'GooglePlay' ">
       <PackageReference Include="Microsoft.AppCenter.Distribute" Version="3.3.0" />
   </ItemGroup>
   <ItemGroup Condition=" '$(Configuration)' == 'GooglePlay' ">
       <PackageReference Include="Microsoft.AppCenter.DistributePlay" Version="3.3.0" />
   </ItemGroup>
   

   Observação

   Se você estiver usando o formato depackages.config antigo para gerenciar referências do NuGet, poderá migrar para um formato PackageReference , siga a instrução de migração.

3. Salve suas alterações e restaure os pacotes NuGet.

4. Você pode alterar a configuração na barra de comandos na parte superior do IDE.

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 UpdateTrack propriedade.

Distribute.UpdateTrack = UpdateTrack.Private;

Após essa chamada, 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. A faixa de atualização não é mantida no SDK entre as inicializações do aplicativo.

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 segundo plano e, em seguida, entra novamente em primeiro 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();

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

Verificar manualmente se há atualização

Distribute.CheckForUpdate();

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 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 e aqueles para Android 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 o ReleaseAvailable callback. Você precisa registrar o retorno de chamada antes de chamar AppCenter.Start , conforme mostrado no exemplo a seguir:

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

Aqui está um exemplo de callback que substitui o diálogo do SDK por um personalizado.

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;

    // custom dialog
    var title = "Version " + versionName + " available!";
    Task answer;

    // On mandatory update, user can't postpone
    if (releaseDetails.MandatoryUpdate)
    {
        answer = Current.MainPage.DisplayAlert(title, releaseNotes, "Download and Install");
    }
    else
    {
        answer = Current.MainPage.DisplayAlert(title, releaseNotes, "Download and Install", "Maybe tomorrow...");
    }
    answer.ContinueWith((task) =>
    {
        // If mandatory or if answer was positive
        if (releaseDetails.MandatoryUpdate || (task as Task<bool>).Result)
        {
            // Notify SDK that user selected update
            Distribute.NotifyUpdateAction(UpdateAction.Update);
        }
        else
        {
            // Notify SDK that user selected postpone (for 1 day)
            // This method call is ignored by the SDK if the update is mandatory
            Distribute.NotifyUpdateAction(UpdateAction.Postpone);
        }
    });

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

Notas de implementação para Xamarin.Android:

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

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

O callback pode ser chamado novamente com o mesmo lançamento se a atividade mudar antes que a ação do usuário seja notificada ao 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.

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

Em 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 no momento, um NoReleaseAvailable retorno de chamada é invocado. Isso permite que você execute 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.");
}

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.SetEnabledAsync(false);

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

Distribute.SetEnabledAsync(true);

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

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

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:

bool enabled = await Distribute.IsEnabledAsync();

Execute a limpeza antes que o aplicativo feche para atualização (somente iOS)

Registre o callback, 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 o Distribute estiver prestes a fechar.

Como funcionam as atualizações no aplicativo?

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 . Não funcionará se o recurso de Acesso Guiado do iOS estiver ativado.

2. 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.

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

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

   • No iOS 9 e 10, uma instância de SFSafariViewController será aberta no aplicativo para autenticar o usuário. Ele se fechará automaticamente depois que a autenticação for bem-sucedida.
   • No iOS 11, a experiência do usuário é semelhante ao iOS 10, mas o iOS 11 solicitará ao usuário sua permissão para acessar as informações de logon. Esta é uma caixa de diálogo no nível do sistema e não pode ser personalizada. Se o usuário cancelar a caixa de diálogo, ele poderá continuar a usar a versão que está testando, mas não receberá atualizações no aplicativo. Eles serão solicitados a acessar as informações de logon novamente quando iniciarem o aplicativo na próxima vez.

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 ele 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.

   • Andróide:

     • um valor mais alto de versionCode ou
     • um valor igual de versionCode , mas um valor diferente de versionName.

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.

1. Crie seu aplicativo no Portal do App Center se ainda não tiver feito isso.
2. Crie um novo grupo de distribuição e nomeie-o, para que você possa reconhecê-lo para testar o recurso de atualização no aplicativo.
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 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.
4. 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 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 o build do aplicativo.
6. 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.
7. Examine a Distribuição e distribua o build para seu grupo de testes no aplicativo.
8. 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.
9. Aumentar 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 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.

Desabilitar o encaminhamento automático dos métodos do delegado de aplicativo para os serviços do App Center

O App Center usa o swizzling para encaminhar automaticamente os métodos do delegado do aplicativo aos serviços do App Center, melhorando a integração do SDK. Há uma possibilidade de conflitos com outras bibliotecas de terceiros ou com o próprio delegado do aplicativo. Nesse caso, talvez você queira desabilitar o delegado de encaminhamento de aplicativo do App Center para todos os serviços seguindo as etapas abaixo:

1. Abra o arquivo Info.plist do projeto.
2. Adicione AppCenterAppDelegateForwarderEnabled a chave e defina o valor como 0. Isso desabilita o encaminhamento de delegados de aplicativos para todos os serviços do App Center.
3. Adicione o retorno de chamada OpenUrl no arquivo AppDelegate.cs.

public override bool OpenUrl(UIApplication application, NSUrl url, string sourceApplication, NSObject annotation)
{
    Distribute.OpenUrl(url);
    return true;
}