Compreendendo AVFoundation para Varredura de Código de Barras e QR

A estrutura AVFoundation da Apple oferece uma interface completa e de baixo nível para trabalhar com mídia audiovisual em dispositivos iOS. Para a digitalização de código de barras e QR, a estrutura expõe a classe , que pode detectar uma ampla gama de códigos legíveis por máquina em tempo real a partir da alimentação da câmera. Isto inclui códigos QR, EAN-8/13, Código 128, PDF417, Aztec e muitos outros formatos. A estrutura lida com o levantamento pesado da análise de imagem e decodificação de código, permitindo que os desenvolvedores se concentrem na lógica de aplicação em vez de implementar algoritmos de digitalização personalizados.

A varredura AVFoundation é acelerada por hardware em dispositivos modernos, oferecendo detecção rápida e confiável, mesmo em condições de iluminação desafiadoras. Funciona com câmeras dianteiras e traseiras, e a área de detecção pode ser restrita a uma região específica de interesse para melhorar o desempenho e a experiência do usuário.

Configurar a Sessão de Captura da Câmera

O núcleo de qualquer scanner baseado em AVFoundation é o . Este objeto orquestra o fluxo de dados da entrada da câmera para a saída de metadados. A configuração da sessão requer várias etapas da caldeira, que são melhor implementadas em uma classe de controlador de visão ou gerenciador de dados.

Solicitando Permissão da Câmera

Antes de acessar a câmera, você deve pedir permissão do usuário. A partir do iOS 10, você precisa incluir a chave no seu arquivo Info.plist com uma string explicando por que seu aplicativo precisa da câmera. A permissão é solicitada usando . Lide com ambos os casos – concedido e negado – e atualize sua interface de acordo.

AVCaptureDevice.requestAccess(for: .video) { granted in
 if granted {
 // Configure and start the capture session
 } else {
 // Show an alert guiding the user to Settings
 }
}

Criando a Sessão AVCapture

Uma vez concedida a permissão, instanciar um . Configure sua sessão predefinida para controlar a qualidade do vídeo; para a digitalização de código de barras, é um bom padrão, mas você também pode usar para processamento mais rápido.

let session = AVCaptureSession()
session.sessionPreset = .high

Adicionando a Entrada da Câmera

Obter o dispositivo de vídeo padrão (a câmera traseira) e criar um . Se a entrada não puder ser adicionada à sessão (por exemplo, o dispositivo está ocupado), pegar o erro e apresentar feedback ao usuário.

guard let camera = AVCaptureDevice.default(for: .video) else { return }
do {
 let input = try AVCaptureDeviceInput(device: camera)
 guard session.canAddInput(input) else { return }
 session.addInput(input)
} catch {
 print("Camera input error: \(error.localizedDescription)")
}

Adicionando o Saída de Metadados

Crie uma instância , defina seu delegado (em uma fila serial dedicada) e adicioná-la à sessão. O delegado receberá objetos de metadados detectados.

let metadataOutput = AVCaptureMetadataOutput()
metadataOutput.setMetadataObjectsDelegate(self, queue: DispatchQueue.main)
guard session.canAddOutput(metadataOutput) else { return }
session.addOutput(metadataOutput)

// Specify which code types to detect – must be done after the output is added
metadataOutput.metadataObjectTypes = [.qr, .ean13, .code128, .pdf417]

Importante: deve ser definido após o resultado ser adicionado à sessão. Se o configurar mais cedo, irá causar um estoiro.

Iniciando a Sessão

Execute a sessão em um tópico de fundo para manter a interface sensível. Chame em uma fila de despacho de fundo ou em uma fila serial dedicada.

DispatchQueue.global(qos: .userInitiated).async {
 session.startRunning()
}

Aplicação do método de delegação

O método delegado é chamado sempre que o scanner detecta um ou mais códigos. Este método recebe uma matriz de instâncias , que você precisa lançar para para acessar a string decodificada.

func metadataOutput(_ output: AVCaptureMetadataOutput,
 didOutput metadataObjects: [AVMetadataObject],
 from connection: AVCaptureConnection) {
 // Process only the first detected code (most common pattern)
 guard let metadataObject = metadataObjects.first,
 let readableObject = metadataObject as? AVMetadataMachineReadableCodeObject,
 let stringValue = readableObject.stringValue else { return }

 // Use the scanned value (e.g., display, validate, or send to server)
 handleScannedCode(stringValue, type: readableObject.type)
}

É comum parar a sessão após uma varredura bem sucedida para evitar detecçãos repetidas. Ligue para após o manuseio do código e reinicie-o quando o usuário redefinir o scanner.

Manuseamento de códigos detectados

Uma vez que você tenha o valor da string, determine qual ação tomar com base no tipo de código e conteúdo. Os cenários comuns incluem:

  • URLs – Abra no Safari ou em um navegador in-app usando .
  • Crédits Wi-Fi – Analisar o formato padrão (]) e conectar programáticamente (necessita de direitos adicionais).
  • Códigos de produto – Procure informações sobre o produto através de uma API como o Base de dados UPC[ ou o seu próprio sistema de inventário.
  • Informações de contacto – Formatos parse vCard ou MeCard e criar um novo contacto no livro de endereços.
  • Texto em forma – Apresentar em alerta ou cópia para pasteboard.

Para cada tipo de código, valide a string antes de processar. Os códigos malformados ou maliciosos devem ser ignorados ou reportados graciosamente.

Melhores práticas para a digitalização de desempenho

Para garantir uma digitalização suave e eficiente, siga estas diretrizes:

  • Limite os tipos de objetos de metadados – Só habilite os formatos de código que sua aplicação realmente precisa. Cada formato extra adiciona o processamento em cima.
  • Defina uma região de interesse – Use para definir uma pequena parte do feed de vídeo onde os códigos são esperados.Isso melhora drasticamente a velocidade de detecção e reduz falsos positivos.
  • Use a gravidade correta do vídeo – mantém a visualização da câmera proporcional e é ideal para sobrepor guias de área de varredura.
  • Aproveite uma fila serial para retornos de chamadas de delegados – Execute processamento pesado (por exemplo, buscas de rede) fora do tópico principal para manter a interface sensível.
  • Considere o suporte à tocha – Permita que o usuário comuta a tocha da câmera para cenários de pouca luz. Verifique antes de alternar.
  • Repor a digitalização após a manipulação – Após uma verificação bem sucedida, reiniciar a sessão com um pequeno atraso (por exemplo, 1-2 segundos) para evitar a re-detecção imediata do mesmo código.

Fornecendo feedback do usuário

Uma boa experiência de digitalização inclui pistas visuais e auditivas. Implemente estes mecanismos de feedback para orientar o usuário:

  • Sobreposição visual – Desenhar um retângulo de realce em torno do código detectado usando a propriedade de . Isto requer converter coordenadas de metadados para visualizar coordenadas via .
  • Animação – Tocar uma animação sutil (por exemplo, uma borda encolhendo) quando um código é reconhecido.
  • Som – Tocar um som do sistema usando com um tom curto e positivo como (o som “Mail Enviado”).
  • Reaplicação estática – Use ou para uma vibração sutil.
  • Guia de área de varredura – Exibir um retângulo translúcido com guias de canto para ajudar os usuários a centralizar o código.

Erro no tratamento e nas bordas

O manuseio robusto de erros garante que seu scanner se degrade graciosamente quando as coisas dão errado.

  • Câmera não disponível – Verificar e no dispositivo. No iPod touch ou simulador sem uma câmera, apresentar uma mensagem significativa.
  • Permissão negada – Mostre um alerta com um botão que abre Configurações via .
  • Falha na configuração da sessão – Erros de registo quando ou retorna . Isto pode acontecer se outra aplicação estiver a usar a câmara em segundo plano (raro).
  • Baixa imagem de luz ou desfocada – Reduza a região de detecção de interesse e garanta que o foco automático da câmera esteja ativado.
  • Tipos de código inválidos ou não suportados – A propriedade pode não suportar todos os formatos em todos os dispositivos. Use para compatibilidade de consultas antes de configurar.

Testando através de dispositivos

O desempenho de digitalização de código de barras AVFoundation varia significativamente entre gerações de iPhone e iPad. Teste sua implementação em:

  • Dispositivos mais antigos (iPhone 6s, iPad Air 2) – Estes têm processadores mais lentos e podem ter dificuldades com predefinições de alta resolução. Use para um equilíbrio ideal no hardware antigo.
  • Dispositivos com diferentes ópticas de câmera – iPhones com telefoto ou câmeras ultra-largas podem se concentrar de forma diferente. Use sempre a câmera de grande angular padrão para digitalização de código de barras.
  • Ambientes de baixa luz – Teste em condições obstérias para garantir que a sobreposição da varredura permaneça visível e que a tocha funcione.
  • Vários tamanhos de código e orientações – Tente códigos de 1 cm × 1 cm adesivos para cartazes grandes, e testar paisagem vs. digitalização de retrato.

Considerações Avançadas

Para aplicativos de produção, considere adicionar recursos como digitalização contínua (permitindo múltiplos códigos em uma sessão), controles de zoom ou integração com ARKit para sobreposições de realidade aumentada. Se você precisa processar códigos de imagens paradas (por exemplo, biblioteca de fotos), use ou do framework Vision, embora o AVFoundation seja geralmente mais rápido para vídeo em tempo real.

Para um mergulho mais profundo na configuração da AVFoundation, consulte a documentação da Apple Setting Up a Capture Session e o guia AVCaptureMetadataOutput documentation. Você também pode encontrar um projeto completo de amostra no artigo Scanning Barcodes with AVCaptureMetadataOutput[].

Seguindo estas orientações e testando completamente a sua implementação, você pode fornecer um código de barras polido e de alto desempenho e um scanner de código QR que aprimora a usabilidade e confiabilidade do seu aplicativo iOS.