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

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 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– você só precisa integrar os módulos dos serviços nos quais você 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 Cartfile para incluir o App Center Distribute.

   # 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 a opção referente ao seu aplicativo está selecionada. Em seguida, clique em Concluir.

Integração por meio do Swift Package Manager

1. No menu do Xcode, clique em File > Swift Packages > Add Package Dependency.
2. Na caixa de diálogo exibida, insira a URL do repositório: https://github.com/microsoft/appcenter-sdk-apple.git.
3. Na Versão, selecione Até a Próxima Versão Principal e escolha 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:

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 externas geralmente estão dentro de um subdiretório, geralmente chamado Fornecedor. 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 (os que estão dentro da pasta Vendor ) no Project Navigator do Xcode. 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 seu projeto não será compilado com êxito.
   • Uma caixa de diálogo será exibida, verifique se a opção referente ao seu aplicativo está selecionada. 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 no 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 método start:withServices: para iniciar o serviço 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} o exemplo de código acima pelo segredo do aplicativo. Confira também a seção Introdução se você ainda não configurou 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 0adicione 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 seu aplicativo.

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

MSACDistribute.updateTrack = MSACUpdateTrackPrivate;

Distribute.updateTrack = .private

Após essa chamada, uma janela do navegador será aberta para autenticar o usuário. Todas as verificações de atualizações subsequentes obterão a versão mais recente no canal privado.

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:

[MSACDistribute disableAutomaticCheckForUpdate];

Distribute.disableAutomaticCheckForUpdate()

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 ao App Center e exibe uma caixa de diálogo de atualização caso haja uma nova versão disponível.

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 string e especifique o valor localizado a ser refletido na caixa de diálogo nos seus próprios arquivos de strings do 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 atualizações disponíveis mais recentes do que a versão usada atualmente, um retorno de chamada delegado distributeNoReleaseAvailable: do MSACDistributeDelegate é invocado. Isso permite que você execute 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 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.

[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 é 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 = [MSACDistribute isEnabled];

var enabled = Distribute.enabled

Não inicialize a Distribuição do App Center durante o desenvolvimento.

Se estiver no modo privado, a Distribuição do App Center abrirá sua interface/navegador ao iniciar o 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 a limpeza antes que o aplicativo feche 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?

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 conectado ou 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-o no App Center, os usuários desse grupo de distribuição serão notificados para 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 o aplicativo – a Distribuição do App Center 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 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 9 e 10, mas o iOS 11 solicitará ao usuário sua permissão para acessar 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:

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

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 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 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. Atualize o nome da versão (CFBundleShortVersionString) do seu aplicativo.
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 redirecionamento das chamadas dos métodos do delegado do aplicativo para os serviços do App Center

O SDK do App Center usa swizzling para melhorar sua integração, encaminhando para ele mesmo algumas chamadas de métodos do delegado do aplicativo. O swizzling de método é uma maneira de alterar a implementação de métodos em tempo de execução. Se por algum 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 delegados de aplicativos para todos os serviços do App Center.
3. Adicione o retorno de chamada openURL no arquivo do projeto AppDelegate.

- (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)
}