Descubra os Assets em segundo plano hospedados pela Apple

Olá! Meu nome é Gabriel. Sou software engineer da equipe App Store. E eu sou a Jenny. Sou engineer da equipe App Processing. Hoje vamos apresentar uma nova forma de distribuir ativos na App Store com os Ativos em segundo plano. Vou explicar como o app e os ativos funcionam juntos nos dispositivos. E eu vou mostrar como usar a hospedagem da Apple para os ativos. Nesta sessão, vamos revisar as tecnologias atuais de entrega de ativos, incluindo os Ativos em segundo plano. Depois, veremos as novidades deste ano, como novas APIs Swift e Objective-C para gerenciar os Ativos em segundo plano e a hospedagem da Apple.

Vamos mostrar como integrar as novidades ao seu app para iOS, iPadOS, macOS, tvOS e visionOS, além de fazer testes locais.

Se quiser que a Apple hospede e entregue seus ativos, vamos mostrar como fazer testes Beta e a distribuição da App Store.

Gabriel fará um resumo geral e falará das novidades dos Ativos em segundo plano.

Obrigado, Jenny. Ao baixar um app da App Store, as pessoas esperam usá-lo imediatamente. Se precisarem aguardar outros downloads para iniciá-lo, elas podem acabar saindo ou apagando o app.

Os Ativos em segundo plano tornaram mais fácil criar uma ótima experiência ao iniciar um app. Você pode configurar como o sistema baixa e atualiza os ativos sem precisar atualizar o app principal. Por exemplo, você pode mostrar um tutorial só para novos jogadores enquanto o jogo baixa em segundo plano e oferecer DLCs pela compra dentro do app ou atualizar modelos de aprendizado de máquina por um processo ágil na App Store. Imagine que você esteja desenvolvendo um jogo com vários níveis, incluindo um tutorial. Você tem quatro opções para distribuir os ativos de cada nível: manter tudo no pacote de apps principal, usar URLSession, empregar Recursos sob demanda ou recorrer a Ativos em segundo plano. Essas tecnologias têm prós e contras. Vou explicar cada uma.

Manter tudo no pacote principal obriga os usuários a esperar o download de todos os ativos, mesmo se só precisar mostrar o tutorial para alguns. Você pode atingir o limite de 4 GB na maioria das plataformas e, para atualizar um ativo, teria de reenviar o app todo. Os Recursos sob demanda permitem que as pessoas comecem o tutorial mais rapidamente, pois possibilitam baixar partes do pacote do app separadamente do TestFlight ou da App Store, mas é preciso reenviar o app inteiro para atualizar alguns arquivos. Os Recursos sob demanda são uma tecnologia antiga que será descontinuada.

Seu sucessor é o recurso Ativos em segundo plano, que permite hospedar os ativos em seu servidor. Você pode atualizar os ativos a qualquer momento, sem atualizar o app todo. O principal dos Ativos em segundo plano é a extensão downloader, que agenda downloads antes mesmo do usuário abrir o app. Isso é ótimo para ter controle total sobre o download e o pós-processamento. No entanto, para muitos, o mais importante é ter os ativos do app atualizados e sempre disponíveis. Com o Ativos em segundo plano gerenciado, o sistema gerencia automaticamente downloads, atualizações, compactação e outras ações. A extensão fornecida pelo sistema pode ser adicionada ao app sem código personalizado. E, com o novo serviço Ativos em segundo plano hospedado pela Apple para TestFlight e App Store, você não precisa usar seu servidor com a hospedagem da Apple. Você recebe 200 GB para hospedar ativos no Apple Developer Program.

Se você ainda usa os Recursos sob demanda, sugerimos começar a migração para os Ativos em segundo plano. Use os Ativos em segundo plano gerenciado e crie vários pacotes de ativos para agrupar arquivos como texturas, sons e shaders da GPU no tutorial. O sistema baixa os pacotes automaticamente nos dispositivos, conforme a política de download. Existem três políticas de download: Essential, Prefetch e On-demand. A política essential faz o sistema baixar o pacote e integrá-lo na instalação do app. O pacote conta no andamento dos downloads visíveis na App Store, TestFlight e tela inicial. Assim que finalizar, o pacote estará pronto para uso ao abrir o app.

A política do Prefetch inicia o download do app na instalação, mas pode continuar em segundo plano após concluir a instalação. A política do On-demand baixa o pacote de ativos só quando você usa a API para solicitá-lo. Você pode hospedar os pacotes ou deixar a Apple hospedá-los para você. Agora, passo para a Jenny, que explicará como a Apple entrega pacotes e builds. Claro! Cada pacote hospedado pode ser usado em um app e várias plataformas. Para o dispositivo baixar o binário de app e os pacotes de ativos, você deve fazer o upload deles separadamente no App Store Connect. Depois, enviar para análise e testes no TestFlight e distribuição na App Store.

Depois do upload, o pacote recebe uma versão sem vínculo com um build de app específico. A correspondência entre app e pacote depende do estado da versão do pacote. Vou explicar com exemplos.

Suponha que haja três versões diferentes do mesmo pacote de ativos. Versão 1 ativa na App Store, versão 2 em Beta externo, e versão 3 em Beta interno no TestFlight. Só uma versão do pacote pode estar ativa para cada contexto. Ao mesmo tempo, você tem builds baixados da App Store ou via TestFlight Beta externo ou interno. O servidor entrega a versão ativa do pacote conforme o contexto de cada build.

Ou seja, o app versão 1.0 build 1 baixado da App Store usa o pacote versão 1. O app versão 2.0 build 1 em Beta externo no TestFlight usa o pacote versão 2. E o app versão 2.0 builds 2 e 3 em Beta interno usa o pacote versão 3.

É importante entender o comportamento ao atualizar a versão do pacote de ativos. Se gostar da versão 2 do pacote de ativos, você poderá enviá-la para distribuição na App Store. Ela substitui a versão antiga e passa a ser ativa na App Store.

Assim, todos os apps baixados da App Store passam a usar a nova versão, incluindo versões antigas já instaladas. Antes de atualizar o pacote, garanta que ele funcione nos builds antigos também. Agora, veja um exemplo de atualização do build. Digamos que você queira enviar o app 2.0 build 3 para teste Beta externo. Após aprovação, se baixado via Beta externo, o build usará a versão 2 do pacote. Se quiser usar a versão mais nova, envie também a versão 3 do pacote. Agora que você já conhece os pacotes de ativos, Gabriel mostrará como criá-los e usá-los no seu app. Obrigado, Jenny. Vou mostrar como usar os Ativos em segundo plano gerenciado no seu app. Para começar, vamos criar os pacotes, usar as novas APIs e testar localmente. Vou explicar como criar um pacote de ativos. Use a nova ferramenta de compactação, disponível para macOS, Linux e Windows, que gera arquivos compactados prontos para o TestFlight e a App Store. A ferramenta vem com o Xcode no macOS e estará disponível para download para Linux e Windows no site Apple Developer. Vou mostrar como a ferramenta funciona.

Comece executando o comando template para gerar um manifesto. No macOS, instale o Xcode e execute o xcrun ba-package template no Terminal. No Linux ou Windows, torne a ferramenta acessível e execute o arquivo ba-package template. A ferramenta gera um template de manifesto. O manifesto é um arquivo JSON que descreve o pacote de ativos para a Apple. Você pode escolher um ID personalizado. Esse ID é usado no código do app, informando a política de download e as plataformas compatíveis com o pacote de ativos.

Primeiro, vamos preencher os seletores de arquivo. Eles selecionam arquivos do repositório fonte para incluir no pacote de ativos. Existem dois tipos: um que seleciona arquivos individuais, outro que seleciona diretórios inteiros. Vamos adicionar um seletor de arquivos para o vídeo de introdução do tutorial, usando o caminho relativo da raiz do repositório fonte. O ID deste pacote é Tutorial, pois contém arquivos do nível Tutorial do jogo. Agora, configure a política de download. Como o tutorial é o primeiro contato, disponibilize o pacote de ativos Tutorial localmente de uma pessoa abrir o jogo pela primeira vez. Nesse caso, escolha a política de download essential.

O nível de tutorial só interessa a quem instala o jogo pela primeira vez. Quem já joga e só está atualizando não precisa baixar o tutorial novamente. Portanto, restrinja a política de download essential à primeira instalação. Assim, apenas quem instala o jogo pela primeira vez receberá os ativos do tutorial.

Com o manifesto pronto, execute novamente a ferramenta para gerar o arquivo comprimido. Defina o diretório atual como a raiz do repositório, passe o caminho do manifesto e onde salvar o archive. Com o pacote pronto, veja como aplicá-lo ao jogo.

Com poucas linhas, você pode usar as novas APIs nos Ativos em segundo plano para acessar os arquivos no pacote. Adicione uma extensão downloader no Xcode. Essa extensão agenda downloads dos pacotes de ativos quando o app principal não está executando, como na instalação.

Adicione um novo target, selecione o template Ativos em segundo plano. Aqui, escolha usar o serviço de hospedagem da Apple ou seu próprio. O template gera o código Swift, mas você poderá trocar para Objective-C se preferir. O sistema tem uma extensão downloader pronta, com suporte a download automático, atualização em segundo plano e mais, para integrar no app sem personalizar o código. O snippet do Xcode no template já vem configurado para implementação padrão. Não há outros códigos de extensão para escrever.

Você poderá remover o método shouldDownload(_:) se não quiser personalizar os downloads. Basta adicionar a extensão gerada ao app com pouquíssimas linhas do código Xcode gerado. Se quiser controle, implemente shouldDownload(_:) com sua lógica. O sistema chama a implementação de shouldDownload(_:) para cada novo pacote de ativos que planeja baixar em segundo plano, com base na política de download, e você pode retornar um valor booleano para decidir se o download deve continuar. Isso é útil se alguns pacotes têm requisitos específicos de compatibilidade. Agora que a extensão foi implementada, veja como acessar os arquivos no app principal.

O primeiro passo é chamar ensureLocalAvailability(of:) no AssetPackManager compartilhado. Esse método verifica se o download do pacote já foi feito. Se não estiver, inicie o download e aguarde a conclusão. Na maioria dos casos, o pacote já terá sido baixado pela extensão, então será rápido. Se for necessário baixar, mostre o progresso ao usuário.

No Swift, aguarde por status updates da sequência assíncrona statusUpdates(forAssetPackWithID:). No Objective-C, crie um delegate que implemente o BAManagedAssetPackDownloadDelegate e associe a propriedade do asset pack manager. Se for preciso cancelar, chame cancel() em qualquer estrutura de progresso retornada pelo status update. Assim que ensureLocalAvailability(of:) retornar sem erro, o pacote já poderá ser usado no dispositivo. Para ler um arquivo, use o método contents(at:searchingInAssetPackWithID:options:) no asset pack manager compartilhado. O primeiro parâmetro é um caminho relativo do repositório de origem, ou seja, o diretório do qual você executou a ferramenta de compactação para criar o pacote, até o arquivo que você quer ler. O sistema une todos os pacotes em um namespace compartilhado, como se fosse uma cópia integral do repositório da sua máquina de desenvolvimento nos dispositivos das pessoas. Assim, você não precisa se preocupar em saber qual pacote contém cada arquivo que quer ler no tempo de execução. Por padrão, o contents(at:searchingInAssetPackWithID:options:) retorna um dado mapeado na memória, ideal para arquivos grandes. Se você precisar acessar o arquivo de forma mais direta, por exemplo, para ler o arquivo manualmente para a memória, use o método descriptor(for:searchingInAssetPackWithID:). Só lembre que, nesse caso, você precisa fechar o descritor quando terminar de usar. Você pode limitar a busca a um pacote específico informando o assetPackID. O sistema monitora quais pacotes foram baixados e mantém todos atualizados em segundo plano. Porém, não remove automaticamente os pacotes enquanto o app estiver instalado. Então é recomendável usar remove(assetPackWithID:) para liberar espaço quando não precisar mais de um pacote. Por exemplo, você pode remover o pacote Tutorial após o usuário concluir o tutorial. Você sempre pode chamar o ensureLocalAvailability(of:) para rebaixar o pacote, caso o usuário reinicie o jogo e abra o tutorial novamente. Lembre-se de que o espaço ocupado pelos pacotes aparece para o usuário nos Ajustes do app. O próximo passo é adicionar seu app principal e sua extensão downloader ao mesmo app group. O sistema utiliza o app group para facilitar a coordenação entre o app principal e a extensão. Depois, adicione a chave BAAppGroupID ao Info.plist do app principal, com o ID do app group como valor de texto. Adicione também a chave BAHasManagedAssetPacks com o valor true ou yes, como valor booleano. Se for usar hospedagem da Apple, adicione a chave BAUsesAppleHosting com valor true ou yes, também como valor booleano. Se não for usar a hospedagem da Apple, consulte a documentação específica na sessão de Recursos deste vídeo para conhecer as outras chaves necessárias no Info.plist, incluindo BAManifestURL. Agora que o app e a extensão estão configurados, é hora de testar.

Criamos um mock server dos Ativos em segundo plano para macOS, Linux e Windows, o que permite testar o download dos pacotes de ativos antes do envio para o TestFlight ou a App Store. Assim como a ferramenta de compactação, o mock server já vem com o Xcode no macOS e, em breve, estará disponível para download no site Apple Developer para Linux e Windows. Os Ativos em segundo plano usam HTTPS nos downloads, então antes você precisa criar um certificado SSL. Para isso, crie uma autoridade certificadora raiz. Depois, instale essa autoridade certificadora nos dispositivos de teste. Em seguida, use essa autoridade para emitir um certificado SSL e, por fim, inicie o mock server apontando para esse certificado SSL. Para obter mais detalhes, consulte a documentação na sessão Recursos deste vídeo. Com o certificado SSL pronto, você pode executar o ba-serve para iniciar o mock server, informar os caminhos dos arquivos de pacotes de ativos que quer servir e definir o host. O host pode ser um endereço IP, um nome de host ou um domínio. No macOS, a ferramenta vai pedir para você escolher uma identidade, ou seja, um par de certificado e chave privada das suas Chaves. No Linux ou Windows, você precisará passar o certificado e a chave privada pela linha de comando. Use o comando help para descobrir mais opções, como definir uma porta personalizada, e, em breve no macOS, a opção de ignorar a escolha da identidade. No iOS, iPadOS e visionOS, e em breve no tvOS, acesse Development Overrides nos Ajustes de Desenvolvedor para informar o URL base do mock server, incluindo host e porta. Em dispositivos de teste com macOS, use xcrun ba-serve url-override para inserir essas informações.

Quando você criar e executar seu app pelo Xcode, ele baixará dos ativos do seu mock server. Agora, passo para a Jenny falar sobre testes Beta e distribuição dos pacotes. Jenny? Obrigada, Gabriel. Agora que você tem o novo binário do app e os pacotes de ativos prontos, vou mostrar como prepará-los para testes Beta no TestFlight e distribuição na App Store. Se usar a hospedagem da Apple, o upload do binário do app e dos pacotes de ativos para o App Store Connect será feito separadamente, e você poderá usar o TestFlight e distribuir na App Store. Vamos ver em detalhes como funciona o upload dos pacotes de ativos. Há várias formas de fazer upload de pacotes de ativos. Se quiser uma interface de arrastar e soltar, use o app Transporter para macOS. Para controle total e transparência, use as APIs REST do App Store Connect para criar sua própria automação. Na linha de comando, o iTMSTransporter multiplataforma oferece comandos úteis e faz solicitações às APIs App Store Connect para você. Consulte a documentação de todas essas ferramentas. Aqui, vou mostrar o processo usando o Transporter e a API App Store Connect. No app Transporter, basta arrastar seu arquivo Tutorial.aar para a janela do Transporter. Adicione ao app desejado e clique em Deliver. Assim, será criada uma nova versão do pacote de ativos do Tutorial. Você poderá ver o status do upload do pacote diretamente no app Transporter. Se quiser mais detalhes sobre o processo de upload, use a API App Store Connect. Siga estas três etapas: Crie o registro do pacote, a versão dele e faça upload do arquivo compactado para essa versão. Primeiro, para registrar o pacote de ativos, faça um POST no recurso backgroundAssets. No corpo da requisição, coloque o nome do pacote como assetPackIdentifier e adicione a Conta Apple do app na sessão Relações. A resposta trará um UUID para seu pacote, para ser usado nas próximas chamadas de API. Em seguida, crie uma nova versão para o pacote fazendo um POST no recurso backgroundAssetVersions.

Na sessão Relações, use o ID do pacote recebido na resposta anterior da API. Essa operação aumenta o número da versão automaticamente, conforme versões já existentes. Aqui, será criada a versão 1. Você também receberá um ID na resposta para identificar a versão 1 do pacote Tutorial.

Quando a versão do pacote for criada, use o recurso backgroundAssetUploadFiles para reservar o upload do arquivo Tutorial.aar. Essa etapa é semelhante a outras operações de upload, como capturas de tela. Aqui, você deve informar o tipo do arquivo, nome, tamanho e checksum MD5. Inclua também a relação com o ID da versão do pacote de ativos. A resposta dessa chamada fornece um ID para o upload e detalhes sobre as instruções para upload.

Depois do upload, faça um PATCH para o backgroundAssetUploadFiles com o ID do upload, e seu pacote de ativos começará a ser processado.

Para acompanhar o progresso, confira as informações completas sobre seus pacotes disponíveis no App Store Connect ou pelas APIs. No App Store Connect, veja o status de processamento do pacote na aba TestFlight. Quando o upload for processado com sucesso, o status será Ready for Internal Testing. Isso significa que sua nova versão já pode ser usada nos builds do app liberados para testes internos no TestFlight. Você receberá um e-mail avisando que a nova versão do pacote de ativos está pronta. Também é possível configurar um webhook para receber essa notificação.

Confira a sessão "Automatizar seu processo de desenvolvimento com a API App Store Connect", da WWDC25, para saber mais sobre os webhooks deste ano. Se durante o processamento ocorrer algum problema com o seu arquivo, o estado mudará para Failed e você receberá uma notificação. Basta corrigir o erro e fazer upload do pacote novamente como uma nova versão. Com as APIs do App Store Connect, é possível fazer requisições GET para relacionar os pacotes de ativos do app, suas versões e respectivos estados. Acompanhe o progresso do upload usando o recurso backgroundAssetVersions. Quando o pacote for processado, um recurso Internal Beta Releases será criado. Ele vai mostrar a versão do pacote como READY_FOR_TESTING. Depois do upload do binário e dos pacotes, você já poderá iniciar os testes Beta no TestFlight. No App Store Connect, veja que a versão 1 do Tutorial já pode ser usada em teste interno. Se quiser testar o app e a versão do pacote com mais pessoas, envie para teste externo. Para enviar um pacote de ativos, clique na versão específica e selecione Submit for External Testing. Assim que aprovado, o estado mudará para Ready for External Testing, e você receberá uma notificação. Pelas APIs, também é possível enviar o pacote para revisão externa pelo recurso betaBackgroundAssetReviewSubmissions. Acompanhe a análise com recurso external Beta releases. Ele vai mostrar quando a versão do pacote estiver pronta para o teste externo. Depois dos testes, para liberar esse pacote na App Store, envie-o para análise do App Review para distribuição da App Store. No App Store Connect, vá até a aba de distribuição para ver os pacotes. Agora você pode enviar uma versão do pacote sozinha, junto com outros pacotes, uma versão do app ou outros itens de revisão. Ao enviar um pacote de ativos e uma versão do app juntos, a equipe de revisão usará o pacote selecionado para testar o app. Para adicionar um pacote para análise, clique em Select Asset Pack, selecione a versão e adicione para revisão. Quando o envio for aprovado, você verá que a versão do asset pack está Ready for Distribution.

Usando as APIs, também é possível enviar para análise usando o recurso reviewSubmissions. Durante a análise, veja o progresso no recurso App Store releases. Quando o estado chegar a Ready for Distribution, significará que os usuários do seu app poderão baixar os novos ativos pela App Store. Pronto, cobrimos muitos tópicos hoje. Falamos sobre pacotes de ativos, como criar e usá-los no app e como fazer upload para hospedagem da Apple. Esperamos que esta sessão ajude você a começar a usar os novos Ativos em segundo plano gerenciados. Agora é sua vez. Use a ferramenta de compactação e crie seu pacote de ativos. Depois, se seu app ainda usa Recursos sob demanda, analise como migrar para Ativos em segundo plano. Consulte a documentação e adote as novas APIs Background Assets no seu app. Agora, queremos seu feedback. Conte para nós o que funciona bem e o que não funciona no Assistente de Feedback. Confira também todas as novidades deste ano no App Store Connect na sessão "Novidades do App Store Connect". Além disso, conheça mais recursos Ativos em segundo plano, incluindo dicas para testes locais, na sessão "Novidades do Background Assets" da WWDC23. - Agradeço sua participação. - E não esqueça de enviar seu feedback.