Distribuição do App Center – atualizações no aplicativo do iOS

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.

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.

Observação

Há algumas coisas a considerar ao usar atualizações no aplicativo:

  1. Se você tiver lançado seu aplicativo no App Store, as atualizações no aplicativo serão desabilitadas.
  2. 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 não habilitar a Distribuição do App Center para seu destino de teste de interface do usuário.

Observação

4.0.0 Na versão do App Center, foram introduzidas alterações interruptivas. Siga a seção Migrar para o SDK do App Center 4.0.0 e superior para migrar o App Center de versões anteriores.

Importante

O SDK do App Center não dá suporte a vários aplicativos de janela que foram introduzidos no iOS 13.

Adicionar atualizações no aplicativo ao seu aplicativo

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

1. Adicionar o módulo Distribuir do App Center

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

Integração por meio de Cocoapods

Se você estiver integrando o App Center ao seu aplicativo por meio do Cocoapods, adicione a seguinte dependência ao podfile e execute pod install.

pod 'AppCenter/Distribute'

Integração por meio do Carthage

  1. Adicione a seguinte dependência ao seu Cartfile para incluir a Distribuição do App Center.

    # Use the following line to get the latest version of App Center
    github "microsoft/appcenter-sdk-apple"
    
    # Use the following line to get the specific version of App Center
    github "microsoft/appcenter-sdk-apple" ~> X.X.X
    
  2. Execute carthage update.

  3. Abra a guia Configurações gerais do destino do aplicativo. Arraste e solte o arquivo AppCenterDistribute.framework da pasta Carthage/Build/iOS para a seção Estruturas e Bibliotecas Vinculadas no XCode.

  4. Arraste e solte AppCenterDistributeResources.bundle de AppCenterDistribute.framework para o Project Navigator do XCode.

  5. Uma caixa de diálogo será exibida, verifique se o destino do aplicativo está marcado. Em seguida, clique em Concluir.

Integração por meio do Swift Package Manager

  1. No menu Xcode, clique em Arquivo > Pacotes Rápidos > Adicionar Dependência de Pacote.
  2. Na caixa de diálogo exibida, insira a URL do repositório: https://github.com/microsoft/appcenter-sdk-apple.git.
  3. Em Versão, selecione Até Próximo Major e use a opção padrão.
  4. Escolha o AppCenterDistribute na coluna Produto do Pacote .

Integração copiando os binários em seu projeto

Se você não quiser usar Cocoapods, poderá integrar os módulos copiando os binários em seu projeto. Siga as etapas abaixo:

Observação

O SDK do App Center dá suporte ao uso de XCframework. Se você quiser integrar o XCframeworks ao seu projeto, baixe o AppCenter-SDK-Apple-XCFramework.zip na página de versões e descompacte-o. O conteúdo da pasta resultante não é específico da plataforma, em vez disso, contém XCframeworks para cada módulo. Eles podem ser integrados da mesma maneira que as estruturas usuais, conforme descrito abaixo.

  1. Baixe as estruturas do SDK do App Center fornecidas como um arquivo zip.

  2. Descompacte o arquivo e você verá uma pasta chamada AppCenter-SDK-Apple/iOS que contém estruturas diferentes para cada serviço do App Center. A estrutura chamada AppCenter é necessária no projeto, pois contém código compartilhado entre os diferentes módulos.

  3. [Opcional] Crie um subdiretório para bibliotecas de terceiros.

    • Como prática recomendada, bibliotecas de terceiros geralmente estão dentro de um subdiretório, geralmente chamado de Vendor. Se o projeto não estiver organizado com um subdiretório para bibliotecas, crie um subdiretório Vendor agora.
    • Crie um grupo chamado Vendor dentro de seu projeto Xcode para imitar a estrutura de arquivos no disco.
  4. Abra o Finder e copie a pasta AppCenter-SDK-Apple/iOS descompactada na pasta do projeto no local onde você deseja.

  5. Adicione a estrutura do SDK ao projeto no Xcode:

    • Verifique se o Project Navigator está visível (⌘+1).
    • Agora, arraste e solte AppCenter.framework, AppCenterDistribute.framework e AppCenterDistributeResources.bundle do Finder (aquele dentro da pasta Vendor ) para o Project Navigator do Xcode. O AppCenter.framework é necessário para iniciar o SDK. Verifique se ele foi adicionado ao seu projeto, caso contrário, os outros módulos não funcionarão e se o projeto não será compilado com êxito.
    • Uma caixa de diálogo será exibida, verifique se o destino do aplicativo está marcado. Em seguida, clique em Concluir.

2. Iniciar Distribuição do App Center

O App Center usa apenas os módulos específicos que você invoca em seu aplicativo. Você deve chamar explicitamente cada um deles ao iniciar o SDK.

2.1 Adicionar a importação para Distribuição do App Center

Abra o arquivo AppDelegate.m do projeto no arquivo Objective-C ou AppDelegate.swift em Swift e adicione as seguintes instruções de importação:

@import AppCenter;
@import AppCenterDistribute;
import AppCenter
import AppCenterDistribute

2.2 Adicionar o start:withServices: método

Adicione Distribute ao seu start:withServices: método para iniciar o Serviço de Distribuição do App Center.

Insira a linha a seguir para iniciar o SDK na classe AppDelegate.m do projeto para a classe Objective-C ou AppDelegate.swift para Swift no didFinishLaunchingWithOptions método .

[MSACAppCenter start:@"{Your App Secret}" withServices:@[[MSACDistribute class]]];
AppCenter.start(withAppSecret: "{Your App Secret}", services: [Distribute.self])

Verifique se você substituiu {Your App Secret} no exemplo de código acima pelo Segredo do Aplicativo. Além disso, marcar a seção Introdução se você não tiver configurado o SDK em seu aplicativo.

2.3 Modificar o Info.plist do projeto

  1. No arquivo Info.plist do projeto, adicione uma nova chave para URL types clicando no botão '+' ao lado de "Lista de Propriedades de Informações" na parte superior. Se o Xcode exibir seu Info.plist como código-fonte, consulte a dica abaixo.
  2. Altere o tipo de chave para Matriz.
  3. Adicione uma nova entrada à matriz (Item 0) e altere o tipo para Dicionário.
  4. Em Item 0, adicione uma URL Schemes chave e altere o tipo para Matriz.
  5. Em sua URL Schemes chave, adicione uma nova entrada (Item 0).
  6. Em URL Schemes>Item 0, altere o valor para appcenter-{APP_SECRET} e substitua {APP_SECRET} pelo Segredo do Aplicativo do aplicativo.

Dica

Se você quiser verificar se modificou o Info.plist corretamente, abra-o como código-fonte. Ele deve conter a seguinte entrada com o Segredo do Aplicativo em vez de {APP_SECRET}:

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

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 por meio da updateTrack propriedade .

MSACDistribute.updateTrack = MSACUpdateTrackPrivate;
Distribute.updateTrack = .private

Observação

O valor padrão é UpdateTrack.public. Essa propriedade só pode ser atualizada antes da chamada do AppCenter.start método. As alterações na faixa de atualização não são persistentes quando o processo do aplicativo é reiniciado, portanto, se a propriedade nem sempre for atualizada antes da AppCenter.start chamada, ela será pública, por padrão.

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.

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, chame o seguinte método antes do início do SDK:

[MSACDistribute 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 descrita na seção a seguir.

Verificar manualmente se há atualização

[MSACDistribute 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

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 facilmente suas próprias cadeias de caracteres de recurso se quiser localizar o texto exibido na caixa de diálogo de atualização. Examine este arquivo de cadeias de caracteres. 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 cadeias de caracteres 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 DistributeDelegate protocolo. Você precisa registrar o delegado antes de iniciar o SDK, conforme mostrado no exemplo a seguir:

[MSACDistribute setDelegate:self];
Distribute.delegate = self;

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

- (BOOL)distribute:(MSACDistribute *)distribute releaseAvailableWithDetails:(MSACReleaseDetails *)details {

  // Your code to present your UI to the user, e.g. an UIAlertController.
  UIAlertController *alertController = [UIAlertController
      alertControllerWithTitle:@"Update available."
                       message:@"Do you want to update?"
                preferredStyle:UIAlertControllerStyleAlert];

  [alertController
      addAction:[UIAlertAction actionWithTitle:@"Update"
                                         style:UIAlertActionStyleCancel
                                       handler:^(UIAlertAction *action) {
                                         [MSACDistribute notifyUpdateAction:MSACUpdateActionUpdate];
                                       }]];

  [alertController
      addAction:[UIAlertAction actionWithTitle:@"Postpone"
                                         style:UIAlertActionStyleDefault
                                       handler:^(UIAlertAction *action) {
                                         [MSACDistribute notifyUpdateAction:MSACUpdateActionPostpone];
                                       }]];

  // Show the alert controller.
  [self.window.rootViewController presentViewController:alertController animated:YES completion:nil];
  return YES;
}
func distribute(_ distribute: Distribute, releaseAvailableWith details: ReleaseDetails) -> Bool {

  // Your code to present your UI to the user, e.g. an UIAlertController.
  let alertController = UIAlertController(title: "Update available.",
                                        message: "Do you want to update?",
                                 preferredStyle:.alert)

  alertController.addAction(UIAlertAction(title: "Update", style: .cancel) {_ in
    Distribute.notify(.update)
  })

  alertController.addAction(UIAlertAction(title: "Postpone", style: .default) {_ in
    Distribute.notify(.postpone)
  })

  // Show the alert controller.
  self.window?.rootViewController?.present(alertController, animated: true)
  return true;
}

Caso você retorne YES/true no método acima, seu aplicativo deverá obter a escolha do usuário e enviar uma mensagem ao SDK com o resultado usando a API a seguir.

// Depending on the user's choice, call notifyUpdateAction: with the right value.
[MSACDistribute notifyUpdateAction:MSACUpdateActionUpdate];
[MSACDistribute notifyUpdateAction:MSACUpdateActionPostpone];
// Depending on the user's choice, call notify() with the right value.
Distribute.notify(.update);
Distribute.notify(.postpone);

Se você não chamar o método acima, o releaseAvailableWithDetails:método -será repetido sempre que o aplicativo estiver entrando em primeiro plano.

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 nenhuma atualização disponível mais recente do que a usada atualmente, um distributeNoReleaseAvailable: do retorno de chamada delegado MSACDistributeDelegate é invocado. Isso permite que você execute um código personalizado nesses cenários.

Aqui estão exemplos que mostram como exibir a interface do usuário do alerta quando nenhuma atualização é encontrada:

- (void)distributeNoReleaseAvailable:(MSACDistribute *)distribute {
  UIAlertController *alert = [UIAlertController alertControllerWithTitle:nil
                                                                 message:NSLocalizedString(@"No updates available", nil)
                                                          preferredStyle:UIAlertControllerStyleAlert];
  [alert addAction:[UIAlertAction actionWithTitle:NSLocalizedString(@"OK", nil) style:UIAlertActionStyleDefault handler:nil]];
  [self.window.rootViewController presentViewController:alert animated:YES completion:nil];
}
  func distributeNoReleaseAvailable(_ distribute: Distribute) {
    let alert = UIAlertController(title: nil, message: "No updates available", preferredStyle: .alert)
    alert.addAction(UIAlertAction(title: "OK", style: .default, handler: nil))
    self.window?.rootViewController?.present(alert, animated: true)
  }

Habilitar ou desabilitar a Distribuição do App Center no runtime

Você pode habilitar e desabilitar a Distribuição do App Center em runtime. 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.

[MSACDistribute setEnabled:NO];
Distribute.enabled = false

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

[MSACDistribute setEnabled:YES];
Distribute.enabled = true

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

Observação

Esse método só deve ser usado depois Distribute de ter sido iniciado.

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

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

BOOL enabled = [MSACDistribute isEnabled];
var enabled = Distribute.enabled

Observação

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

Não inicializar a Distribuição do App Center durante o desenvolvimento

Se estiver no modo privado, o App Center Distribute abrirá sua interface do usuário/navegador no início do aplicativo. Embora esse seja um comportamento esperado para os usuários finais, isso pode causar interrupções durante o estágio de desenvolvimento do aplicativo. Não recomendamos a inicialização Distribute para sua DEBUG configuração.

#if DEBUG
    [MSACAppCenter start:@"{Your App Secret}" withServices:@[[MSACAnalytics class], [MSACCrashes class]]];
#else
    [MSACAppCenter start:@"{Your App Secret}" withServices:@[[MSACAnalytics class], [MSACCrashes class], [MSACDistribute class]]];
#endif
#if DEBUG
    AppCenter.start(withAppSecret: "{Your App Secret}", services: [Analytics.self, Crashes.self])
#else
    AppCenter.start(withAppSecret: "{Your App Secret}", services: [Analytics.self, Crashes.self, Distribute.self])
#endif

Executar limpo até que o aplicativo seja fechado para atualização

Implemente o DistributeDelegate protocolo e registre o delegado, conforme mostrado no exemplo a seguir:

[MSACDistribute setDelegate:self];
Distribute.delegate = self;

O distributeWillExitApp: método delegado será chamado logo antes de o aplicativo ser encerrado para a instalação da atualização:

- (void)distributeWillExitApp:(MSACDistribute *)distribute {
  // Perform the required clean up here.
}
func distributeWillExitApp(_ distribute: Distribute) {
  // Perform the required clean up here.
}

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 for instalado de um IDE ou manualmente.

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

  1. Esse recurso só funcionará com builds distribuídos usando o serviço Distribuição do App Center . Ele não funcionará quando o depurador estiver anexado ou se o recurso acesso guiado do iOS estiver ativado..

  2. Depois de integrar o SDK, criar uma versão de lançamento do aplicativo e carregá-lo no App Center, os usuários desse grupo de distribuição serão notificados para a nova versão por meio de um 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 o aplicativo – o App Center Distribute não dá suporte a atualizações no aplicativo para aplicativos que foram instalados de outras fontes (por exemplo, baixar o aplicativo de um anexo de email). 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 importantes.

  4. Se o aplicativo definir a faixa como privada, um navegador será aberto para autenticar o usuário e habilitar as 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 privada 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.

    • No iOS 9 e 10, uma instância do 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 9 e 10, mas o iOS 11 solicitará ao usuário sua permissão para acessar informações de logon. Essa é 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:

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

Dica

Se você carregar o mesmo ipa uma segunda vez, a caixa de diálogo NÃO aparecerá, pois os binários são idênticos. 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 .

Como fazer testar atualizações no aplicativo?

Você precisa 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 nomeie-o para que você possa reconhecer que ele destina-se 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 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 testadores reais.
  4. Crie um novo build do 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 propriedade updateTrack.
  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 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 no Portal do App Center de 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. Aumente o nome da versão (CFBundleShortVersionString) do aplicativo.
  10. Crie a versão de lançamento do aplicativo e carregue um novo build do 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.

Desabilitar o encaminhamento das chamadas de métodos do delegado de aplicativo para os serviços do App Center

O SDK do App Center usa swizzling para melhorar sua integração encaminhando-se algumas das chamadas de métodos do delegado do aplicativo. O swizzling de método é uma maneira de alterar a implementação de métodos em runtime. Se, por qualquer motivo, você não quiser usar o swizzling (por exemplo, devido a uma política específica), poderá desabilitar esse encaminhamento 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 representantes de aplicativos para todos os serviços do App Center.
  3. Adicione o openURL retorno de chamada no arquivo do AppDelegate projeto.
- (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
  sourceApplication:(NSString *)sourceApplication
         annotation:(id)annotation {

  // Pass the url to MSACDistribute.
  return [MSACDistribute openURL:url];
}
func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool {

  // Pass the URL to App Center Distribute.
  return Distribute.open(url)
}