App Center Distribute – MAUI e Xamarin Atualizações no aplicativo

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.

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.

Visual Studio para Mac

• Abra o Visual Studio para Mac.
• Clique em Abrir arquivo> e escolha sua solução.
• No navegador de soluções, clique com o botão direito do mouse na seção Pacotes e escolha Adicionar pacotes NuGet....
• Procure o App Center e instale o 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.
• Procure o App Center e instale o Microsoft.AppCenter.Distribute.

Console do Gestor de Pacotes

• Abra o console no Visual Studio. Para fazer isso, escolha Ferramentas>Gerenciador de Pacotes NuGet>Console do Gerenciador de Pacotes.
• Se estiver a trabalhar no Visual Studio para Mac, certifique-se de que instalou as Extensões de Gestão de Pacotes NuGet. Para isso, escolha Extensões do Visual Studio>, procure NuGet e instale, se necessário.
• Digite o seguinte comando no console:

Install-Package Microsoft.AppCenter.Distribute

2. Inicie o App Center Distribute

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

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

Distribute.DontCheckForUpdatesInDebug();

Não há necessidade desta etapa no Android, onde a configuração de depuração é detetada automaticamente durante o tempo de execução.

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

Distribute.SetEnabledForDebuggableBuild(true);

2.3 [Apenas para iOS] Modificar o Info.plist do projeto

O SDK do App Center verifica as URLs que redirecionam para a aplicação para evitar a instalação de aplicações não autorizadas (sideloading). Assim, para que as atualizações distribuídas através do portal sejam tratadas corretamente, precisas especificar CFBundleURLSchemes na secção CFBundleURLTypes do ficheiro Info.plist:

1. Adicione uma nova chave para URL types ou CFBundleURLTypes no seu ficheiro Info.plist (caso o Xcode exiba o 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 da sua aplicação.

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

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

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. A não remoção do código de atualização no aplicativo pode levar à não conformidade e à remoção do aplicativo do Google Play. Para facilitar, fornecemos a versão do App Center Distribute SDK com APIs stubbed, portanto, a única alteração para você é uma troca de dependência.

1. Adicione uma nova configuração de compilação nomeada GooglePlay para seu Xamarin.Android e projetos compartilhados. Certifique-se de que a configuração de compilação de projetos está corretamente mapeada para a configuração de solução apropriada. Consulte Instruções do Visual Studio ou Visual Studio para Mac para obter mais detalhes.

2. Abra o Xamarin.Android e projetos compartilhados' .csproj em 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 packages.config antigo para gerenciar referências do NuGet, poderá migrar para um formato PackageReference , siga as instruções de migração.

3. Salve suas alterações e restaure 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, Distribuir usa um grupo de distribuição público. Se quiseres usar um grupo de distribuição privado, terás de defini-lo explicitamente através da propriedade UpdateTrack.

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 receberão a versão mais recente na faixa privada. A faixa de atualização não é mantida no SDK em todas as inicializações de aplicativos.

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 segundo plano e depois torna ao primeiro plano novamente.
• 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();

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 facilmente fornecer suas próprias cadeias de texto de recursos caso deseje localizar o texto exibido na janela de diálogo de atualização. Observe 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 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 o "callback" ReleaseAvailable. Você precisa registrar o retorno de chamada antes de ligar 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 da implementação de callback que substitui a caixa de diálogo SDK por uma 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;

    // 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:

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

Se não chamares NotifyUpdateAction, o retorno de chamada irá repetir-se 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 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.

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

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 callback NoReleaseAvailable é invocado. Isso permite que você execute código personalizado em tais cenários. Você precisa registrar o retorno de chamada antes de ligar 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 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.SetEnabledAsync(false);

Para habilitar o App Center Distribute novamente, use a mesma API, mas passe true como parâmetro.

Distribute.SetEnabledAsync(true);

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

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

Verifique se o App Center Distribute está ativado

Você também pode verificar se o App Center Distribute está habilitado ou não:

bool enabled = await Distribute.IsEnabledAsync();

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

Registe o callback como mostrado no exemplo seguinte:

// 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?

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

1. Esse recurso só funciona com compilações RELEASE (por padrão) que são distribuídas usando o serviço App Center Distribuir . Não funcionará se a funcionalidade de Acesso Guiado do iOS estiver ativada.

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

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

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

   • No iOS 9 e 10, uma instância de SFSafariViewController será aberta dentro do 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 pedirá permissão ao usuário para acessar as informações de login. 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 login 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 for:

   • iOS:

     • um valor superior a CFBundleShortVersionString ou
     • um valor igual de CFBundleShortVersionString mas um valor superior de CFBundleVersion.
     • As versões são as mesmas, mas o identificador exclusivo de compilação é diferente.

   • Android:

     • um valor superior a versionCode ou
     • um valor igual de versionCode mas um valor diferente de versionName.

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.

1. Crie seu aplicativo no Portal do App Center, se ainda não o fez.
2. Crie um novo grupo de distribuição e nomeie-o, para que você possa reconhecer que ele foi destinado a 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 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.
4. Crie uma nova compilação 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 sua compilação do aplicativo.
6. 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.
7. Revise a Distribuição e distribua a compilação para seu grupo de teste no aplicativo.
8. 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.
9. Aumente a versão do seu aplicativo (CFBundleShortVersionString CFBundleVersion ou para iOS, versionCode para Android)
10. 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.

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

O App Center usa swizzling para encaminhar automaticamente os métodos do seu delegado de aplicativo para os serviços do App Center para melhorar 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, convém desabilitar o encaminhamento do delegado de aplicativo do App Center para todos os serviços do App Center 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 OpenUrl callback no seu AppDelegate.cs arquivo.

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