App Group: o que é, criação de um contêiner compartilhado e configuração de acesso

O que é App Group?

App Group é um mecanismo do sistema operacional iOS que fornece uma área de armazenamento compartilhada para múltiplos processos do mesmo desenvolvedor. Sem ele, cada extensão opera em sua própria sandbox e não pode ler dados escritos por outro componente. O App Group resolve esse isolamento criando um diretório no sistema de arquivos acessível a todos os processos com os entitlements corretos.

O identificador de grupo começa com o prefixo group. e é especificado no arquivo de entitlements do projeto. No Xcode, este identificador é adicionado via Capabilities — o sistema o inclui automaticamente na assinatura do aplicativo. Após a configuração, todos os membros do grupo obtêm acesso ao diretório compartilhado em Library/Application Support/ dentro do contêiner.

De acordo com a Apple WWDC 2020 Session 10026, o App Group cobre três cenários principais: sincronização de configurações via NSUserDefaults, compartilhamento de arquivos via FileManager e Core Data compartilhado com um único armazenamento. Cada cenário requer apenas especificar o identificador de grupo na API correspondente.

Como funciona o contêiner compartilhado do App Group

O iOS cria o contêiner compartilhado na primeira execução de qualquer processo com o entitlement com.apple.security.application-groups. Fisicamente, o contêiner está localizado em um diretório do sistema — seu caminho difere da sandbox do aplicativo principal e das extensões, mas todos os processos autorizados têm permissões de leitura e escrita.

Direitos de acesso e segurança

A Apple garante a segurança do App Group através da combinação de team ID e assinatura de código. Um processo não assinado com o mesmo certificado de desenvolvedor não pode acessar o contêiner do grupo. Isso evita vazamentos de dados entre aplicativos de diferentes desenvolvedores.

Identificador de grupo

O formato do identificador é: group.<team-id>.<name>. Por exemplo, group.ABC123DEFG.widget-data. Vários grupos podem ser criados em um dispositivo, cada um com seu próprio conjunto de membros. Um único aplicativo pode pertencer a vários App Groups simultaneamente — isso é útil para separar dados de diferentes extensões.

// Get the App Group container URL
guard let containerURL = FileManager.default
    .containerURL(forSecurityApplicationGroupIdentifier: "group.com.example.widget")
else { return }

// Create a file in the shared container
let fileURL = containerURL.appendingPathComponent("shared.data")
try "Hello from main app".write(to: fileURL, atomically: true, encoding: .utf8)

O FileManager fornece o método containerURL(forSecurityApplicationGroupIdentifier:) que retorna a URL do diretório compartilhado. É importante chamar este método separadamente em cada processo — o caminho é fisicamente o mesmo, mas cada processo o vê através de sua própria perspectiva de segurança.

Configuração do App Group no Xcode

Habilitar o App Group no Xcode começa com as Capabilities — a chave App Groups adiciona o entitlement ao projeto. O Apple Developer Portal também requer que o identificador do aplicativo inclua esta capacidade. Sem ela, a assinatura de código não funcionará em um dispositivo real.

Configuração passo a passo

Abra seu projeto no Xcode, selecione o target do aplicativo e vá para a guia Signing & Capabilities. Clique em + e escolha App Groups. Crie ou selecione um grupo existente. Repita os mesmos passos para cada extensão que precisa de acesso ao contêiner compartilhado. Todos os participantes devem usar o mesmo identificador de grupo.

Verificação de entitlements

Após habilitar as Capabilities, o Xcode cria automaticamente um arquivo .entitlements com a chave com.apple.security.application-groups e uma matriz de identificadores. Certifique-se de que todas as extensões necessárias tenham este arquivo com o team ID correto no identificador de grupo.

<!-- Example entitlements file -->
<key>com.apple.security.application-groups</key>
<array>
    <string>group.com.example.shared</string>
</array>

Se seu projeto tiver várias extensões (Today Widget, Share Extension, Notification Service), cada uma deve ter seu próprio arquivo de entitlements com o mesmo grupo. A ausência de entitlements em qualquer target é uma razão comum pela qual uma extensão não consegue ver os dados compartilhados.

Uso do UserDefaults com App Group

A maneira mais simples de sincronizar dados entre um aplicativo e suas extensões é o UserDefaults com um suite name. Em vez do UserDefaults.standard padrão, você cria uma instância com o identificador do App Group, e todos os processos leem as mesmas configurações.

De acordo com as Apple Human Interface Guidelines, este mecanismo é adequado para sincronizar estado: tema selecionado, favoritos, flags de integração. No entanto, não é projetado para grandes volumes de dados ou operações de escrita concorrentes — para isso, use arquivos ou Core Data.

// Write to UserDefaults App Group (main app)
let defaults = UserDefaults(suiteName: "group.com.example.shared")
defaults?.set(true, forKey: "isDarkMode")
defaults?.synchronize()

// Read from UserDefaults App Group (widget extension)
let sharedDefaults = UserDefaults(suiteName: "group.com.example.shared")
let isDark = sharedDefaults?.bool(forKey: "isDarkMode") ?? false

Observação: a instância do UserDefaults com suiteName é criada separadamente em cada processo, mas lê do mesmo arquivo plist no contêiner compartilhado. O método synchronize() garante a escrita imediata no disco — no iOS 13+ pode ser omitido, pois o sistema sincroniza os dados periodicamente.

Acesso compartilhado a arquivos e Core Data

Para cenários mais complexos, o App Group fornece acesso a um sistema de arquivos compartilhado. Qualquer arquivo criado no diretório do contêiner é acessível a todos os processos do grupo. Isso permite um banco de dados Core Data compartilhado, cache de imagens ou arquivos temporários.

Configuração do Core Data com App Group

Para usar um armazenamento Core Data compartilhado, crie um NSPersistentContainer com a URL do arquivo .sqlite localizado no diretório do App Group. Certifique-se de que apenas um processo escreva no banco de dados por vez — a escrita concorrente pode corromper os dados. Uma arquitetura típica: o aplicativo principal escreve, as extensões leem.

// Setup Core Data with App Group container
lazy var persistentContainer: NSPersistentContainer = {
    let container = NSPersistentContainer(name: "SharedModel")
    guard let appGroupURL = FileManager.default
        .containerURL(forSecurityApplicationGroupIdentifier: "group.com.example.shared")
    else { return container }

    let storeURL = appGroupURL.appendingPathComponent("SharedModel.sqlite")
    container.persistentStoreDescriptions = [NSPersistentStoreDescription(url: storeURL)]
    container.loadPersistentStores { _, error in
        if let error = error { fatalError(error.localizedDescription) }
    }
    return container
}()

Uma abordagem alternativa é um cache de imagens baseado em arquivos. O NSCache vive apenas na memória, mas através do App Group você pode salvar imagens em cache no disco no diretório compartilhado. A extensão do widget pode acessar os mesmos arquivos e exibir dados atualizados sem downloads adicionais de rede.

Ao trabalhar com arquivos compartilhados, lembre-se de que o sistema pode encerrar a extensão a qualquer momento. Use NSFileCoordinator para coordenar o acesso e evitar corrupção de dados quando vários processos escrevem simultaneamente.