App Center Distribute – Atualizações no aplicativo do iOS

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ê não tiver configurado 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 – você só precisa integrar os módulos dos serviços em que está interessado.

Integração via Cocoapods

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

pod 'AppCenter/Distribute'

Integração via Cartago

1. Adicione a seguinte dependência ao seu 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 do AppCenterDistribute.framework para o Project Navigator do XCode.

5. Será exibida uma caixa de diálogo, verifique se o alvo da aplicação está marcado. Em seguida, clique em Concluir.

Integração via Swift Package Manager

1. No menu Xcode, clique em File > Swift Packages > Add Package Dependency.
2. Na caixa de diálogo exibida, digite o URL do repositório: https://github.com/microsoft/appcenter-sdk-apple.git.
3. Em Versão, selecione 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 para o seu projeto

Se você não quiser usar Cocoapods, você pode integrar os módulos copiando os binários em seu projeto. Siga os passos 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, as bibliotecas de terceiros geralmente estão dentro de um subdiretório, muitas vezes chamado Vendor. Se o seu projeto não estiver organizado com um subdiretório para bibliotecas, crie um subdiretório Vendor agora.
   • Crie um grupo chamado Vendor dentro do seu projeto Xcode para imitar a estrutura de arquivos no disco.

4. Abra o Finder e copie a pasta AppCenter-SDK-Apple/iOS descompactada para a pasta do seu projeto no local desejado.

5. Adicione a estrutura SDK ao projeto no Xcode:

   • Certifique-se de que o Project Navigator está visível (⌘+1).
   • Agora, arraste e solte AppCenter.framework, AppCenterDistribute.framework e AppCenterDistributeResources.bundle do Finder (aqueles dentro da pasta Vendor ) para o Project Navigator do Xcode. O AppCenter.framework é necessário para iniciar o SDK. Certifique-se de que 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.
   • Será exibida uma caixa de diálogo, verifique se o alvo da aplicação está marcado. Em seguida, clique em Concluir.

2. Inicie o App Center Distribute

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 o App Center Distribute

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 App Center Distribute.

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

[MSACAppCenter start:@"{Your App Secret}" withServices:@[[MSACDistribute class]]];

AppCenter.start(withAppSecret: "{Your App Secret}", services: [Distribute.self])

Certifique-se de que substituiu {Your App Secret} no exemplo de código acima pelo seu Segredo da Aplicação. 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 "Information Property List" no topo. Se o Xcode exibir o 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. Sob a sua URL Schemes chave, adicione uma nova entrada (Item 0).
6. Sob URL Schemes>Item 0, altere o valor para appcenter-{APP_SECRET} e substitua {APP_SECRET} pelo Segredo da aplicação 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, 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.

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ção subsequentes receberão a versão mais recente no canal privado.

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:

[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 para o 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 facilmente fornecer suas próprias cadeias de texto de recursos caso deseje localizar o texto exibido na janela de diálogo de atualização. Olhe para este ficheiro de strings. 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 cadeia de caracteres 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 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 delegada que substitui a caixa de diálogo 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 deve obter a escolha do usuário e enviar uma mensagem ao SDK com o resultado usando a seguinte API.

// 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:-method se repetirá sempre que seu aplicativo estiver entrando em primeiro plano.

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

Nos casos em que o SDK verifica atualizações e não encontra nenhuma atualização disponível mais recente do que a que está a ser usada atualmente, é invocado um retorno de chamada do delegado distributeNoReleaseAvailable: de MSACDistributeDelegate. Isso permite que você execute código personalizado em tais cenários.

Aqui estão exemplos que mostram como exibir a interface do usuário de 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 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.

[MSACDistribute setEnabled:NO];

Distribute.enabled = false

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

[MSACDistribute setEnabled:YES];

Distribute.enabled = true

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

var enabled = Distribute.enabled

Não inicialize o App Center Distribute 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 seus usuários finais, ele pode causar interrupções durante o estágio de desenvolvimento do seu 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

Execute 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 método de delegado distributeWillExitApp: será chamado logo antes que a aplicação seja encerrada 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 compilações distribuídas usando o serviço Distribuir do App Center . Ele não funcionará quando o depurador estiver conectado ou se o recurso Acesso Guiado do iOS estiver ativado.

2. Depois de integrar o SDK, criar uma versão de lançamento do seu aplicativo e carregá-lo no 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 de e-mail para instalar o aplicativo - o App Center Distribute não suporta atualizações no aplicativo para aplicativos que foram instalados de outras fontes (por exemplo, baixar o aplicativo de um anexo de e-mail). 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 9 e 10, mas o iOS 11 pedirá ao usuário sua permissão 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:

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

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 se destina 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 propriedade updateTrack.
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 o nome da versão (CFBundleShortVersionString) do seu aplicativo.
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 de chamadas de 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 si mesmo algumas das chamadas de métodos do delegado do aplicativo. O swizzling de métodos é uma maneira de alterar a implementação de métodos em tempo de execução. Se, por qualquer motivo, você não quiser usar swizzling (por exemplo, por causa de uma política específica), então você pode desativar 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 callback de openURL no arquivo AppDelegate do 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)
}