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.
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:
- Se você tiver lançado seu aplicativo no App Store, as atualizações no aplicativo serão desabilitadas.
- 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.
Siga a seção Introdução se você ainda não configurou o SDK em seu aplicativo.
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.
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'
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
Execute
carthage update
.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.
Arraste e solte AppCenterDistributeResources.bundle de AppCenterDistribute.framework para o Project Navigator do XCode.
Uma caixa de diálogo será exibida, verifique se o destino do aplicativo está marcado. Em seguida, clique em Concluir.
- No menu Xcode, clique em Arquivo > Pacotes Rápidos > Adicionar Dependência de Pacote.
- Na caixa de diálogo exibida, insira a URL do repositório:
https://github.com/microsoft/appcenter-sdk-apple.git
. - Em Versão, selecione Até Próximo Major e use a opção padrão.
- Escolha o AppCenterDistribute na coluna Produto do Pacote .
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.
Baixe as estruturas do SDK do App Center fornecidas como um arquivo zip.
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.[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.
Abra o Finder e copie a pasta AppCenter-SDK-Apple/iOS descompactada na pasta do projeto no local onde você deseja.
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.
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.
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
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.
- 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. - Altere o tipo de chave para Matriz.
- Adicione uma nova entrada à matriz (
Item 0
) e altere o tipo para Dicionário. - Em
Item 0
, adicione umaURL Schemes
chave e altere o tipo para Matriz. - Em sua
URL Schemes
chave, adicione uma nova entrada (Item 0
). - Em
URL Schemes
>Item 0
, altere o valor paraappcenter-{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>
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.
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.
[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).
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.
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.
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)
}
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.
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.
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
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.
}
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:
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..
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.
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.
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.
- No iOS 9 e 10, uma instância do
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 deCFBundleVersion
. - as versões são as mesmas, mas o identificador exclusivo de build é diferente.
- um valor mais alto de
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 .
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.
- Crie seu aplicativo no Portal do App Center, caso ainda não tenha feito isso.
- 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.
- 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.
- 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.
- Clique no botão Distribuir nova versão no portal e carregue o build do aplicativo.
- 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.
- Examine a Distribuição e distribua o build para o grupo de testes no aplicativo.
- 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.
- Aumente o nome da versão (
CFBundleShortVersionString
) do aplicativo. - 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:
- Abra o arquivo Info.plist do projeto.
- Adicione
AppCenterAppDelegateForwarderEnabled
a chave e defina o valor como0
. Isso desabilita o encaminhamento de representantes de aplicativos para todos os serviços do App Center. - Adicione o
openURL
retorno de chamada no arquivo doAppDelegate
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)
}