On Demand Resources foi descontinuado: o preço do Background Assets

Apple aposentou um sistema de entrega de conteúdo com uma década de vida em 13 palavras: “On Demand Resources and the NSBundleResourceRequest API are deprecated. Use Background Assets instead.”¹

Essa frase é a entrada inteira. Ela leva o radar 170066290, aparece sob Deprecations e se repete palavra por palavra em três notas de versão distintas.¹²³ A Apple não publicou versão de remoção, nem guia de migração vinculado à descontinuação, nem qualquer nota equivalente nas notas de versão do macOS ou do watchOS.

O trabalho está escondido nas últimas quatro palavras. Background Assets não é uma coisa só. Ele se divide em três configurações com modelos de hospedagem diferentes, alvos mínimos de implantação diferentes e custos de migração separados por algo próximo de uma ordem de grandeza. A escolha acontece antes de você escrever uma linha de código, e errar aí é o erro caro.

Resumo

• A Apple descontinuou o On Demand Resources e o NSBundleResourceRequest nas notas de versão do iOS e iPadOS 27, do tvOS 27 e do visionOS 27.¹²³ O ODR continua funcionando. A Apple não indicou data de remoção, e as APIs descontinuadas continuam sendo distribuídas e continuam resolvendo tags.
• Os dados de disponibilidade da própria API marcam a descontinuação em seis plataformas, duas a mais do que qualquer nota de versão menciona: Mac Catalyst e watchOS.⁴ O Background Assets não publica disponibilidade alguma para watchOS, ou seja, o watchOS recebe uma descontinuação sem substituto documentado.⁵⁶
• “Use Background Assets instead” se divide em três caminhos: gerenciado com hospedagem da Apple, gerenciado com hospedagem própria e não gerenciado. Os dois caminhos gerenciados exigem iOS 26.0 como alvo mínimo de implantação.⁷⁸ Abaixo de 26.0, só resta o caminho não gerenciado, que exige que você hospede os arquivos, invente o formato do manifesto e faça o parsing por conta própria.⁹
• O gerenciamento de disco se inverte. O ODR deixava o sistema descartar recursos marcados que não estivessem em uso e tratava setPreservationPriority(_:forTags:) como uma dica de ordenação.⁴¹⁰ O Background Assets mantém no dispositivo todo pacote baixado até que seu código chame remove(assetPackWithID:).¹¹
• A Apple hospeda até 200 GB de asset packs comprimidos e até 200 pacotes por registro de app — limites compartilhados entre todas as plataformas em que seu app é oferecido —, enviados ao App Store Connect e revisados separadamente das builds.¹²¹³

O que a Apple descontinuou, com precisão

Três detalhes da nota pesam, e a nota não menciona nenhum deles.

O alcance é maior do que o das notas de versão. Três documentos trazem a entrada: iOS e iPadOS 27, tvOS 27 e visionOS 27, cada um sob um título On Demand Resources com subtítulo Deprecations, todos citando o mesmo radar.¹²³ As notas do macOS 27 e do watchOS 27 não dizem nada a respeito.

A anotação de disponibilidade da API conta uma história mais ampla. NSBundleResourceRequest aparece como introduzida no iOS 9.0 e descontinuada em 27.0, com a mesma descontinuação em 27.0 no iPadOS 9.0, no Mac Catalyst 13.1, no tvOS 9.0, no visionOS 1.0 e no watchOS 2.0.⁴ Seis plataformas nos metadados, quatro citadas nas notas. Os dois métodos de prioridade de preservação de Bundle carregam a mesma anotação de seis plataformas.¹⁰ Uma auditoria guiada apenas pelas notas de versão perde por completo as entradas de Mac Catalyst e watchOS.

A entrada do Mac Catalyst é apenas nominal. A Apple documenta que NSBundleResourceRequest “ignora chamadas de apps Mac criados com o Mac Catalyst”, ou seja, a descontinuação aposenta uma API que nunca fez nada por lá.⁴ A entrada do watchOS não é apenas nominal. O Background Assets lista disponibilidade para iOS 16.0, iPadOS 16.0, Mac Catalyst 16.0, macOS 13.0, tvOS 18.4 e visionOS 2.4, sem nenhuma linha de watchOS.⁵ A Apple afirma sem rodeios que os asset packs hospedados pela Apple estão “disponíveis para apps distribuídos pela App Store em todas as plataformas, exceto watchOS”.⁶ Um app watchOS que use ODR ganha um aviso de descontinuação e nenhum substituto para o qual migrar.

A força é a menor entre as três mudanças do ciclo 27 que já cobri. Descontinuado quer dizer descontinuado. A Apple não publicou versão de remoção, nem barreira na submissão, nem falha em tempo de execução. Compare com a exigência do ciclo de vida de cenas do mesmo ciclo, em que apps criados com o novo SDK “não conseguem iniciar”, ou com a exigência da tela de inicialização, em que a App Store rejeita a build direto. O ODR não faz nem uma coisa nem outra. As tags existentes continuam resolvendo, as chamadas existentes continuam devolvendo recursos e os binários já publicados continuam funcionando. O que chega é um aviso do compilador e um relógio que ninguém consegue ler.

O momento parece decisão, não faxina. A Apple descontinuou a API em quatro nomes de plataforma de uma vez, uma versão depois de a camada gerenciada do substituto ter sido lançada. Trate a descontinuação como a abertura de uma janela de migração cuja duração a Apple não publicou, e não como uma emergência.

A bifurcação que você enfrenta antes de escrever código

A visão geral do framework publicada pela Apple descreve dois modelos de hospedagem e um padrão gerenciado que “cuida de downloads, atualizações, compressão e mais por você”. Na hospedagem da Apple, “você envia seus assets para o App Store Connect e os mantém lá, de forma parecida com as builds do app”.⁵ O template de extensão Background Download do Xcode nomeia dois tipos diretamente: gerenciado com hospedagem da Apple e não gerenciado com hospedagem própria.⁹¹¹ Uma terceira combinação existe nas chaves da property list: BAHasManagedAssetPacks definida como YES sem BAUsesAppleHosting seleciona asset packs gerenciados que você mesmo hospeda, e a documentação encaminha você para o protocolo ManagedDownloaderExtension em vez do StoreDownloaderExtension do StoreKit.⁷⁸¹⁴

Para a maioria dos times, o alvo de implantação decide. Todo ponto de entrada gerenciado exige pelo menos iOS 26.0, de AssetPackManager e ManagedDownloaderExtension até as três chaves da property list.⁷⁸¹⁴¹⁵ Um app que dá suporte ao iOS 18 simplesmente não pode adotar a camada gerenciada, e suas opções se estreitam ao caminho não gerenciado, que alcança o iOS 16.1, ou a continuar no ODR descontinuado até o alvo de implantação subir.⁹

O caminho não gerenciado é outro trabalho. Na sequência da Apple, o sistema baixa um manifesto de BAManifestURL antes de seu app iniciar, entrega o arquivo à sua extensão e recebe de volta um conjunto de solicitações de download.⁹ A Apple declara a divisão sem meio-termo: “É responsabilidade sua criar arquivos de manifesto para seus assets não gerenciados e hospedados por você (no formato que você preferir), que seu código faz o parsing para levar as URLs e os tamanhos de arquivo até o sistema.”⁹ Você entra com hospedagem, CDN, esquema de manifesto, parser e lista de domínios permitidos. Quem lê “use Background Assets instead” como uma troca de API está lendo a camada gerenciada e citando a conta da não gerenciada.

O que o ODR entregava e você agora reconstrói na mão

Três comportamentos do ODR não têm equivalente direto.

Tags viram asset packs. O ODR identificava conteúdo com tags de texto atribuídas no Xcode, e NSBundleResourceRequest(tags:) reivindicava uma ou mais delas.⁴ O Background Assets substitui tags por asset packs: diretórios de arquivos descritos por um manifesto JSON, comprimidos em um arquivo .aar por uma ferramenta de linha de comando. A unidade de granularidade cresce, e a atribuição sai do asset catalog do Xcode e vai para um arquivo que você mantém.

A hospedagem da Apple vira uma linha de lançamento separada. O conteúdo de ODR ia junto com a build. Os asset packs hospedados pela Apple sobem de forma independente pelo Transporter, pelo altool, pelo iTMSTransporter ou pela API do App Store Connect, e você os submete à App Review separadamente do app.¹¹¹³ O desacoplamento é justamente a vantagem: você publica conteúdo novo sem publicar uma build. O custo é um segundo pipeline de submissão, uma segunda fila de revisão e um segundo conjunto de status para acompanhar.

A limpeza automática passa a ser tarefa sua, e essa inversão é a mudança mais afiada. O ODR tratava o conteúdo baixado como um cache que pertencia ao sistema. A Apple documentava que o sistema “não tentará descartar do armazenamento do dispositivo os recursos marcados com uma tag enquanto pelo menos um objeto NSBundleResourceRequest estiver gerenciando a tag”, o que é uma promessa sobre quando a limpeza acontece, não sobre se acontece.⁴ setPreservationPriority(_:forTags:) existia exatamente para dar “uma dica ao sistema sobre a ordem relativa de descarte de conjuntos de recursos marcados no bundle”.¹⁰ Você encerrava sua reivindicação, o sistema recuperava o espaço no ritmo dele, e lidar com pouco armazenamento era problema da Apple.

O Background Assets inverte a propriedade. O sistema mantém os pacotes atualizados automaticamente, e checkForUpdates() remove pacotes que ficaram obsoletos no servidor.¹⁵ Nenhum dos dois mecanismos remove um pacote com o qual você simplesmente terminou. A instrução da Apple é explícita: “o sistema não removerá automaticamente seus asset packs enquanto seu app estiver instalado. Portanto, quando terminar de usar um asset pack, chame o método remove(assetPackWithID:)”.¹¹

O padrão com escopo e contagem de referências se reduz a uma exclusão explícita que você precisa decidir chamar:

// ODR: claim a tag, use the file, release the claim.
// The system reclaims the space afterward on its own schedule.
let request = NSBundleResourceRequest(tags: ["Tutorial"])
try await request.beginAccessingResources()
let url = Bundle.main.url(forResource: "Introduction", withExtension: "m4v")
request.endAccessingResources()

import System  // url(for:) and contents(at:) take a FilePath

// Background Assets: ensure the pack, read the file, delete the pack.
// Nothing reclaims the space if you skip the last line.
let manager = AssetPackManager.shared
guard let pack = try await manager.manifest.assetPack(withID: "Tutorial") else { return }
try await manager.ensureLocalAvailability(of: pack, requireLatestVersion: false)
let url = try manager.url(for: "Videos/Introduction.m4v")
try await manager.remove(assetPackWithID: "Tutorial")

Todo app que carrega a premissa de descarte do ODR precisa de uma política de armazenamento escrita para ele. A falha é silenciosa: nada quebra, nada avisa, e o armazenamento do dispositivo sobe até algum usuário reparar no seu app na lista de armazenamento.

A superfície de migração, item por item

Para o caminho gerenciado com hospedagem da Apple, os próprios passos da Apple resultam nesta lista.

Agrupe os arquivos em asset packs e escolha uma política de download por pacote. Existem três políticas. essential baixa durante a instalação e alimenta o progresso que as pessoas acompanham na App Store, no TestFlight e na tela de início. prefetch começa durante a instalação e continua em segundo plano depois que a instalação termina. onDemand só baixa quando seu código pede.¹¹ Para essential e prefetch, um array aninhado installationEventTypes aceita firstInstallation, subsequentUpdate ou ambos, de modo que um pacote de tutorial pode baixar na primeira instalação e ficar de fora de toda atualização posterior.¹¹

Escreva um manifesto por pacote. O Xcode gera um template comentado:

xcrun ba-package template -o Manifest.json

{
  "assetPackID": "Tutorial",
  "downloadPolicy": {
    "essential": {
      "installationEventTypes": ["firstInstallation"]
    }
  },
  "fileSelectors": [
    { "file": "Videos/Introduction.m4v" },
    { "directory": "Textures/Tutorial" }
  ],
  "platforms": ["<identifiers from the generated template comments>"]
}

Os caminhos de arquivo são resolvidos em relação ao diretório onde você roda o comando de empacotamento, o que volta a importar mais adiante, quando você lê os arquivos de volta por caminho.¹¹ Arquive cada pacote:

xcrun ba-package Manifest.json -o Tutorial.aar

Adicione um target de extensão Background Download em Application Extension, escolhendo o tipo gerenciado com hospedagem da Apple. Adicione a capability App Groups tanto ao app quanto à extensão, e coloque os dois no mesmo grupo. Depois, adicione três chaves de property list ao target do app: BAAppGroupID, BAHasManagedAssetPacks definida como YES e BAUsesAppleHosting definida como YES. A Apple orienta a omitir todas as demais chaves de Background Assets em projetos hospedados pela Apple.¹¹ Há uma restrição em que é fácil tropeçar: adotar AssetPackManager sem adotar também o protocolo de extensão correspondente é, nas palavras da Apple, “um erro de programação”.¹⁵

A leitura dos arquivos acontece por meio de um namespace unificado. A Apple “mescla automaticamente todos os seus asset packs em um namespace compartilhado, reconstruindo de fato sua pasta raiz de assets como se ela tivesse sido colada no dispositivo da pessoa”, então o código endereça arquivos por caminho sem precisar saber qual pacote os contém.¹¹ As leituras retornam Data mapeado em memória por padrão, com uma variante por descritor de arquivo para carregamento procedural que você mesmo precisa fechar.¹¹

Os testes locais têm um custo de configuração que vale orçar à parte. O Background Assets usa HTTPS em todo download, então o servidor de teste precisa de um certificado. O caminho documentado pela Apple passa pelo Keychain Access para criar uma CA raiz autoassinada, pelo Apple Configurator para montar um perfil com essa CA, pela instalação e confirmação de confiança do perfil em cada dispositivo de teste, pela emissão de um certificado SSL folha cujo nome corresponda exatamente ao IP ou hostname do servidor, pela inicialização do servidor e pela definição de uma URL de override no menu Developer dos Ajustes de cada dispositivo.¹⁷

xcrun ba-serve --host localhost Tutorial.aar HighQualityTextures.aar

Orce essa sequência como tarefa própria. O On Demand Resources nunca exigiu um servidor seu em momento algum: a Apple o descreve como um gerenciador de “conteúdo hospedado na App Store”, e recursos ausentes no dispositivo “são solicitados à App Store”.⁴ Migrar significa colocar hospedagem de pé, ou um mock confiável dela, antes de conseguir exercitar um único download. Lendo os dois fluxos de trabalho lado a lado, minha expectativa é que a cadeia de certificados, e não a adoção da API, consuma o primeiro dia de uma migração.

Os números para planejar

A Apple publica dois tetos rígidos para pacotes hospedados por ela: 200 GB no total e 200 asset packs por registro de app. Ambos são “compartilhados entre todas as plataformas oferecidas para seu app”.¹² A Apple calcula o total a partir do tamanho máximo entre as versões elegíveis para distribuição no TestFlight ou na App Store, excluindo as versões Awaiting Upload, Processing, Failed e totalmente Superseded, e envia um e-mail quando você chega a 80% do limite. Arquivar um pacote recupera espaço removendo todas as versões dele, inclusive as que estão no ar na App Store.¹²

O caminho não gerenciado troca esses tetos por quatro chaves de property list de nível superior que você define, uma delas um dicionário com outras três, e a separação entre comprimido e não comprimido é uma armadilha de verdade. BADownloadAllowance e BAEssentialDownloadAllowance limitam tamanhos de download e recebem valores comprimidos. BAMaxInstallSize e BAEssentialMaxInstallSize limitam tamanhos instalados e recebem valores não comprimidos.⁹ A Apple acopla às chaves de tamanho de instalação um alerta que na prática é um alerta de produto: “A App Store usa esta chave para mostrar o tamanho do seu app na página do produto, então forneça um valor preciso … Não exagere o espaço em disco de que você precisa.”¹⁸ BADownloadDomainAllowList fecha o conjunto, aceitando domínios em formato DNS com um asterisco inicial opcional para curingas.⁹

Mais um número precisa entrar no plano, e ele vem dos metadados de disponibilidade, não da prosa. AssetPackManager estreou no iOS 26.0, e quatro de seus membros já carregam descontinuações: ensureLocalAvailability(of:) e status(ofAssetPackWithID:) em 26.4, depois assetPack(withID:) e allAssetPacks em 27.0.¹⁹ Busca, status e a chamada de download mudaram de lugar uma vez cada, ao longo de duas versões pontuais. A rota que a Apple agora indica, pela propriedade manifest do gerenciador, vem com anotação de beta no SDK 27.0, assim como o ensureLocalAvailability(of:requireLatestVersions:) em lote.¹⁹ O próprio passo a passo da Apple para pacotes hospedados por ela ainda demonstra duas das chamadas descontinuadas.¹¹ O piso prático, portanto, fica acima dos 26.0 nominais da camada. Escrever o caminho de download mostrado antes sem colher um aviso de descontinuação significa mirar em 27.0 e aceitar símbolos com anotação de beta para isso. O substituto que estão mandando você adotar é mais novo e se mexe mais rápido do que a API que ele substitui.

Quem a descontinuação realmente pega

A população afetada é estreita, e eu não a encontrei no meu próprio código. Busquei, em sete projetos publicados, por NSBundleResourceRequest, beginAccessingResources, setPreservationPriority, qualquer build setting ON_DEMAND_RESOURCES, knownAssetTags e configuração de tags no asset catalog. Zero ocorrências, nos sete, em todos os padrões. Uma varredura de repositório inteiro sobre todos os arquivos Swift, Objective-C, property list e pbxproj do meu diretório de projetos não retornou nada para nenhum símbolo de ODR, e nada para Background Assets também.²⁰

O resultado nulo tem uma causa que vale nomear, porque ela se generaliza. O ODR existe para apps cujo conteúdo é muito maior que o código. Meu maior asset catalog é o do Return, com 66,6 MB, e todos os outros apps ficam abaixo de 8 MB, com Water e Yawara abaixo de 100 KB.²⁰ Nesses tamanhos, dividir conteúdo em pacotes acrescenta modos de falha de rede, uma política de armazenamento e um segundo pipeline de revisão enquanto economiza um download do qual ninguém reclama. Os apps que realmente precisam de Background Assets são jogos com conteúdo de fases, apps que entregam modelos grandes de machine learning e qualquer coisa com vídeo por idioma, que é exatamente o público visado pelo suporte a asset packs localizados que a Apple lançou no iOS 27.²¹

Os alvos de implantação afinam o quadro, e são o número a conferir primeiro em qualquer base de código. Cinco dos meus seis apps iOS já estão em iOS 26.0 ou posterior, então a camada gerenciada estaria disponível para eles hoje. O Ace Citizenship ainda declara 17.0 e 17.5 em alguns targets, o que descartaria a camada gerenciada e deixaria só o caminho não gerenciado ou o ODR descontinuado.²⁰ Faça essa checagem antes de desenhar qualquer coisa: é o alvo mínimo de implantação, e não o volume de assets, que define qual migração está de fato sendo oferecida a você.

Perguntas frequentes

O On Demand Resources para de funcionar no iOS 27?

Não. A Apple marcou o ODR e NSBundleResourceRequest como descontinuados e não publicou versão de remoção, nem barreira na submissão, nem falha em tempo de execução.¹ APIs descontinuadas continuam funcionando, e as tags existentes continuam resolvendo. O que você ganha é um aviso do compilador. O contraste com as outras mudanças de ruptura do mesmo ciclo é instrutivo: a exigência do ciclo de vida de cenas faz os apps “não conseguirem iniciar”, e a exigência da tela de inicialização faz a App Store rejeitar a build. A descontinuação do ODR dispara um relógio, não fecha uma porta.

Quais plataformas a descontinuação abrange?

As notas de versão citam quatro plataformas em três documentos: iOS e iPadOS 27, tvOS 27 e visionOS 27, todos com o radar 170066290.¹²³ Os metadados de disponibilidade da API vão além, marcando NSBundleResourceRequest e os métodos de prioridade de preservação de Bundle como descontinuados em 27.0 em seis plataformas, somando Mac Catalyst e watchOS.⁴¹⁰ O Mac Catalyst é uma questão teórica, porque a Apple documenta que a classe ignora chamadas de apps Catalyst.⁴ O watchOS não é: o Background Assets não publica disponibilidade para watchOS, e os pacotes hospedados pela Apple estão disponíveis “em todas as plataformas, exceto watchOS”, então um app watchOS tem uma API descontinuada e nenhum sucessor documentado.⁵⁶

Posso migrar se meu app dá suporte ao iOS 18?

Para a camada gerenciada, não. AssetPackManager, ManagedDownloaderExtension, BAHasManagedAssetPacks e BAUsesAppleHosting exigem todos iOS 26.0.⁷⁸¹⁴¹⁵ Abaixo desse piso restam duas opções. O caminho não gerenciado funciona a partir do iOS 16.1, e pede que você hospede os assets, defina seu próprio formato de manifesto, faça o parsing numa extensão e declare limites de download e uma lista de domínios permitidos na property list.⁹ Fora isso, continue usando o ODR descontinuado até seu alvo de implantação chegar a 26.0, o que a ausência de data de remoção por parte da Apple permite hoje.

O que quebra em silêncio se eu portar o código de ODR direto?

O armazenamento. O ODR deixava o sistema descartar conteúdo marcado sem uso, e setPreservationPriority(_:forTags:) apenas sugeria a ordem.⁴¹⁰ O Background Assets nunca remove um pacote com o qual você terminou enquanto seu app continuar instalado, ou seja, o espaço é seu até você chamar remove(assetPackWithID:).¹¹ Código que espelha o antigo par beginAccessingResources e endAccessingResources sem acrescentar uma exclusão explícita vaza disco indefinidamente, sem crash e sem aviso que o denuncie nos testes. Escreva a política de descarte antes de escrever o código de download.

Pontos principais

Para desenvolvedores iOS: - Confira o alvo mínimo de implantação antes de qualquer outra coisa. Abaixo do iOS 26.0, a camada gerenciada não existe para você, e “use Background Assets instead” significa construir hospedagem, formato de manifesto e parser no caminho não gerenciado.⁷⁹ - Escreva uma política de descarte como parte da migração. remove(assetPackWithID:) não tem contrapartida automática, e o hábito herdado do ODR de encerrar a reivindicação e confiar no sistema deixa o armazenamento crescendo em silêncio.¹¹

Para times que entregam conteúdo pesado: - Orce a configuração de testes locais separadamente do código. O caminho documentado pela Apple passa por uma CA raiz autoassinada, um perfil do Apple Configurator instalado e marcado como confiável em cada dispositivo, um certificado SSL folha que corresponda ao hostname do servidor e um override de URL por dispositivo.¹⁷ - Planeje com base em 200 GB e 200 pacotes por registro de app, compartilhados entre todas as plataformas em que seu app é distribuído, e fique atento ao e-mail que a Apple envia aos 80%.¹² Arquivar para recuperar espaço remove versões que estão no ar na App Store.¹²

Para gerentes de release: - Pacotes hospedados pela Apple significam um segundo pipeline de submissão: enviados pelo Transporter ou pela API do App Store Connect, versionados de forma independente das builds e submetidos à App Review por conta própria.¹¹¹³ Dimensione o ciclo de revisão de acordo. - Nada obriga a migração neste ciclo. Coloque o ODR atrás da exigência do ciclo de vida de cenas e da exigência da tela de inicialização, que são de fato impostas, e reveja quando a Apple publicar uma versão de remoção.

O ciclo 27 continua ordenando suas mudanças de ruptura pelo tamanho dos dentes: o ciclo de vida de cenas impede o app de iniciar, a tela de inicialização impede a build de ser publicada, e o ODR apenas dispara um relógio. Saber distinguir uma da outra é o que faz você aproveitar bem o ciclo. Para o mesmo padrão numa superfície menor, veja a remoção do ImageCreator do Image Playground. O hub completo da série é a Série Ecossistema Apple.

Referências