O que é a API do PassKit?

O framework PassKit da Apple é um conjunto abrangente de ferramentas e serviços que permitem aos desenvolvedores iOS criar, distribuir e gerenciar passes digitais para a Apple Wallet. Um passe pode ser um cartão de embarque, bilhete de evento, cartão de fidelidade, cartão de presente, cupom ou qualquer outro tipo de credencial que beneficie de ser armazenado de forma segura no dispositivo do usuário. A API PassKit lida com tudo, desde geração de passes e assinatura até atualizações em tempo real através de notificações de push. Para companhias aéreas, plataformas de ticketing e organizadores de eventos, a API PassKit tornou-se o padrão de fato para eliminar documentos de papel e proporcionar uma experiência móvel sem atrito.

Cada passe é embalado como um arquivo – um arquivo ZIP assinado contendo dados, imagens e strings de localização JSON. Quando um usuário abre este arquivo (através de um link, email ou download in-app), iOS valida a assinatura e apresenta o passe na Carteira. A partir desse momento, o passe vive no dispositivo, pode ser atualizado no ar, e funciona mesmo quando offline para informações críticas como códigos de barras ou códigos QR.

Como funciona a API do PassKit

Passar a Estrutura de Ficheiros

Um arquivo é um arquivo ZIP padrão que deve conter pelo menos um manifesto , um (uma lista de todos os arquivos com seus hashes SHA-1), e um arquivo de assinatura (). O arquivo define todo o conteúdo de passagem: campos de cabeçalho, campos primários, campos secundários, campos auxiliares, códigos de barras e tipo de trânsito para os passes de embarque. As imagens (logo, ícone, fundo, tira, etc.) são colocadas em subdiretórios para cada resolução de exibição (por exemplo, ] para 1x, para 2x, para 3x].

Assinatura e Distribuição

A Apple requer que todos os passes sejam assinados criptograficamente usando um certificado emitido pelo desenvolvedor (obtido através do Portal do Desenvolvedor Apple). A assinatura verifica a autenticidade e integridade do passe. Uma vez assinado, o passe pode ser hospedado em um servidor e distribuído através de uma URL que aciona a instalação da Carteira. Alternativamente, os passes podem ser enviados como anexos de e-mail, incorporados em códigos QR, ou empurrados diretamente de seu aplicativo usando o ou o moderno .

Atualizações em tempo real via Push

Uma das características mais poderosas do PassKit é a capacidade de atualizar os passes após a emissão. Quando um voo muda de portas ou um ticket é atualizado, o servidor pode enviar uma notificação de push silenciosa para o dispositivo do usuário. O dispositivo então obtém um novo arquivo da URL do serviço web registrado. O passe na Carteira é substituído sem problemas e o usuário vê as informações atualizadas imediatamente. Para os passes de embarque, isso significa que as alterações de portas, reatribuições de assentos ou atrasos são refletidas automaticamente sem exigir que o usuário reabra uma aplicação.

O fluxo de atualização push requer um serviço web que cumpre com a especificação da Apple: o serviço deve expor os pontos finais para obter o último passe, números de série e registro remoto do dispositivo. Isso é normalmente implementado em sua infraestrutura usando Node.js, PHP, Python, ou qualquer pilha que possa lidar com solicitações HTTP.

Principais benefícios para o Passe de embarque e gerenciamento de ingressos

Conveniência do usuário e fricção reduzida

Armazenar um cartão de embarque ou bilhete na Carteira Apple elimina a necessidade de se perder para uma versão em papel ou manter uma aplicação de terceiros aberta. Os passes são acessíveis a partir da tela de bloqueio (via geofecção, notificação baseada no tempo ou toque manual) e podem ser rapidamente digitalizados em portões, catracas ou pontos de entrada. Para as companhias aéreas, isso acelera o embarque. Para os locais de eventos, reduz as linhas em janelas de chamadas.

Dados confiáveis e sempre disponíveis

Uma vez que um passe é baixado, a imagem do código de barras e as informações-chave são armazenadas localmente. Mesmo que o dispositivo perca a conectividade celular, o passe permanece digitalizável. Isso é crítico nos aeroportos, estádios e hubs de trânsito onde a cobertura da rede pode ser irregular. O passe também aparece no ecrã de bloqueio quando a data/hora relevante se aproxima, graças à inteligência da Apple.

Atualizações dinâmicas sem ação do usuário

Com as atualizações baseadas em notificações de push, qualquer alteração no conteúdo do passe pode ser refletida imediatamente. Para um atraso de voo, o tempo estimado de partida nas atualizações de pass; para um festival, uma mudança de palco aparece no ticket. Os usuários não precisam atualizar ou baixar nada manualmente. Isso reduz as solicitações de suporte e melhora a experiência geral.

Segurança e Luta Antifraude reforçadas

Os passes da Apple Wallet são assinados com um certificado de desenvolvedor, para que seja detectada a adulteração. Além disso, os passes podem incluir um número de série único que você pode validar no servidor. Para eventos de alto valor, você pode combinar o PassKit com verificações do lado do servidor – por exemplo, invalidando um passe remotamente se for reembolsado, então empurrando uma versão atualizada com um status “voided”. Os códigos de barras também podem ser regenerados periodicamente para evitar a reutilização de imagens, embora isso seja mais comum com sistemas de código de barras dinâmicos.

Passar a Criação e o Desenho

Definir os Campos de Passagem

O conteúdo do passe é dividido em grupos lógicos: campos de cabeçalho (por exemplo, “Passo de embarque”), campos primários (por exemplo, “Portão A12”), campos secundários (por exemplo, “Setor 23A”), campos auxiliares (por exemplo, “Número Frequente de Voo”) e campos de trás (por exemplo, termos e condições). Cada campo tem uma chave, rótulo, valor e atributos opcionais como estilo de data, estilo de número ou estilo de moeda. Para os passes de embarque, você também define o para PKTransitTypeAir, PKTransitTypeTrain, etc., que afeta a disposição visual e a visão de tickets de tela de bloqueio.

Códigos de barras e códigos QR

Cada passagem deve incluir pelo menos um objeto de código de barras. Você pode usar , , ou (os dois últimos são comuns para embarque de avião). O valor de código de barras – tipicamente o número do ticket ou um código de confirmação – é codificado na imagem em tempo de geração de passe. Para uma segurança aprimorada, você pode gerar um código de barras único no servidor e incluí-lo no passe, então faça uma atualização para invalidar o antigo após a digitalização. No entanto, a maioria das companhias aéreas e plataformas de eventos usam um ID de passageiro estático combinado com validação do lado do servidor.

Orientações para o Design Visual

A Apple oferece diretrizes de design fortes para garantir que os passes sejam consistentes entre os dispositivos. O logotipo deve ser simples e centralizado, o fundo deve complementar o código de barras e as imagens de strip (opcional) podem adicionar o toque de marca. Você precisa fornecer imagens em várias resoluções (1x, 2x, 3x) para todas as densidades de tela. Com o aumento de iPhones maiores, o layout de passe se adapta automaticamente, mas testes cuidadosos em diferentes tamanhos de tela é essencial.

Para um exemplo prático de uma passagem devidamente estruturada JSON, consulte a documentação oficial da Apple Criando uma passagem].

Localização

Os passes podem ser localizados através da inclusão de subdiretórios específicos de linguagem (por exemplo, , ) no pacote . O pode referenciar estas cadeias localizadas para etiquetas de campo e valores. Isto é particularmente importante para companhias aéreas internacionais e organizadores de eventos globais que queiram apresentar informações sobre os bilhetes na língua preferida do utilizador.

Distribuindo Passes para Usuários

Adição Directa In-App

Se o seu aplicativo for o ponto de contato primário, você pode adicionar programaticamente um passe para Wallet usando (iOS 6+) ou o mais moderno (iOS 12+). O arquivo de passe deve ser baixado do seu servidor (como NSData) e então apresentado ao usuário. Um fluxo padrão: o usuário compra um ticket ou check-in, seu aplicativo obtém o assinado , e mostra um botão “Adicionar a Wallet”. Se tocar nele, abrirá a Wallet com uma prévia, e o usuário confirmará.

E-mail e distribuição web

Para usuários que não tenham seu aplicativo instalado (ou prefira não usá-lo para gerenciamento de passe), você pode enviar um link para o arquivo ou colocar um link de download direto em um site. Quando o usuário toca no link em um dispositivo iOS, Safari automaticamente abre Carteira e pede para adicionar o passe. Você também pode usar Links universais para melhorar a experiência. Este método é amplamente utilizado pelas companhias aéreas que enviam links de passe em e-mails de confirmação de reserva.

Varredura de código de barras ou QR

Outro padrão comum é incorporar um URL apontando para o arquivo em um código QR. Quando digitalizado com a aplicação Câmera, o iOS exibe um banner Carteira no topo da tela. Tocando nele adiciona o passe. Isto é ideal para walk-up de tickets em escritórios de caixa de eventos ou quiosques de autoatendimento em aeroportos. Para mais detalhes sobre esta abordagem, consulte o guia Adicionar um Passe à Carteira].

Atualizando Passagens em Tempo Real

Arquitetura de atualização baseada em push-based

Para ativar atualizações automáticas, você deve implementar um serviço web simples que a Apple Wallet pode chamar. O serviço deve expor três pontos finais:

  1. Obtém a última versão de um passe (chamado pela Carteira quando recebe uma notificação de push).
  2. Obtém números de série para um dispositivo (utilizado durante o registo inicial e para detectar alterações).
  3. Registro e não inscrição (armazena tokens de dispositivos para notificações de push).

Quando um passe precisa de actualização, o seu servidor envia uma notificação de push (usando as APNs) para os dispositivos registados. O dispositivo então consulta o serviço Web para um novo ficheiro [[FLT: 26]]. Se a versão de pass tiver mudado, a Carteira baixa e substitui o antigo passe silenciosamente. O conteúdo actualizado (por exemplo, nova porta, nova hora de partida, estado vazio) é instantaneamente visível para o utilizador.

Quando usar as atualizações

Os casos comuns de utilização incluem:

  • Alterações, atrasos ou cancelamentos da porta de voo
  • Remarcação de eventos ou alterações de locais
  • Atualizações ou rebaixamentos de assentos
  • Validação de ticket (por exemplo, digitalização nas marcas de entrada do passe conforme usado)
  • Atualizações de segurança (por exemplo, substituição de um código de barras após uma tentativa de varredura)

Note que cada passagem só pode ser atualizada usando o mesmo certificado usado para assiná- lo originalmente. Você não pode alterar o tipo de passagem ou o identificador da organização após a emissão.

Melhores práticas de execução

Segurança e Confiança

  • Mantenha seu certificado de assinatura e chave privada em um ambiente de servidor seguro, nunca em código de cliente.
  • Validar todas as solicitações de registo de impulsos para evitar a injecção de token.
  • Utilize HTTPS para todas as interações entre o servidor e a Carteira Apple.
  • Considere usar códigos de barras únicos ou IDs de curta duração para eventos de alta segurança.
  • Implementar taxa limitando em seus terminais de serviço web.

Experiência do Utilizador

  • Mostrar a opção “Adicionar à Carteira” no momento mais relevante – após a confirmação da compra, após o check-in, ou no início de um dia de evento.
  • Use um estilo claro e de alto contraste para códigos de barras e garanta que eles atendam aos requisitos mínimos de tamanho (pelo menos 2 polegadas de largura em equivalentes de impressão).
  • Mantenha o passe simples: evite a confusão com campos desnecessários. A visão de tela de bloqueio deve mostrar as três informações mais críticas.
  • O teste passa em dispositivos reais com diferentes versões iOS. Simulador pode renderizar passes, mas você não pode testar atualizações push ou digitalização real lá.

Integração com infra- estrutura

O seu serviço de geração de passes deve ser idempotente e escalável. Use um banco de dados para mapear o número de série de passes de cada usuário para o seu evento ou reserva de voo. Armazene os tokens do dispositivo para atualizações de push. Muitas equipes aproveitam bibliotecas como Swift-Protobuf[] ou servidores existentes (por exemplo, ]Passbook PHP library[]) para lidar com a geração de .pkpass. Independentemente da linguagem, valide sempre que o arquivo ZIP gerado, quando assinado, abre corretamente em um dispositivo de teste.

Testes e QA

A Apple fornece uma ferramenta de teste de passe de carteira dentro do Xcode que pode validar a estrutura do seu . Use-o antes de distribuir passes. Além disso, teste o ciclo de vida completo: adicionar passe → atualização via push → remover passe. Teste com condições de rede ruins para garantir que o display de código de barras offline funcione. Simule notificações de push usando ferramentas APNs para verificar se seus terminais de serviço web respondem corretamente.

Exemplos do mundo real e casos de uso

Companhias aéreas e aeroportos

Todas as principais companhias aéreas – Delta, United, Emirates e muitos outros – usam o PassKit para cartões de embarque. Os passageiros podem fazer check-in através da aplicação da companhia aérea, adicionar o cartão de embarque à Carteira e usá-lo durante a sua viagem. As mudanças de porta e as reatribuições de assento são empurradas automaticamente. Algumas companhias aéreas até usam o passe para exibir o acesso ao lounge ou o status de embarque prioritário. O passe também pode ser usado para validação de bag-tag em quedas de bagagem de autoatendimento. De acordo com relatórios da indústria, as companhias aéreas que adotam os passes da Carteira vêem menor check-in contra tráfego e maiores pontuações de satisfação do cliente.

Ingressos de Eventos

Os fãs compram um bilhete, recebem um passe com um código QR rotativo (para evitar fraudes) e usam-no para entrar. O passe também pode incluir compras adicionais como estacionamento ou atualizações VIP. Durante o evento, os organizadores podem empurrar atualizações sobre mudanças de horário, mapas de locais ou alertas meteorológicos. Isso reduz a necessidade de sinalização de papel e anúncios no local.

Trânsito público e Estacionamento

Agências de trânsito da cidade (como MTA em Nova Iorque ou TfL em Londres) experimentaram com PassKit para passes mensais ou bilhetes de passeio único. Alguns aplicativos de estacionamento usam passes de carteira como licenças de estacionamento digitais que podem ser validados por agentes de execução. Passagens de trânsito beneficiam da mesma capacidade de empurrar em tempo real, por exemplo, se uma linha de trem for interrompida, o passe pode sugerir rotas alternativas.

Limitações e Considerações

Enquanto PassKit é poderoso, ele tem restrições desenvolvedores devem planejar para:

  • iOS apenas:] Os passes não podem ser adicionados aos dispositivos Android. Se o seu público for multiplataforma, você deve oferecer uma alternativa (por exemplo, um PDF ou um ticket móvel baseado na web).
  • Nenhuma interação Bluetooth ou NFC (por padrão): Os passes não suportam NFC a menos que você incorpore uma sessão NFC de aplicativo nativo. Para true tap-and-go, você precisaria usar Core NFC separadamente.
  • Push update latency:] Enquanto as notificações de push são rápidas, o dispositivo deve estar online para receber o gatilho. Se um usuário estiver offline durante uma atualização, o passe permanecerá obsoleto até que ele se conecte.
  • Memoria e armazenamento: Cada passe é pequeno (tipicamente 30–80 KB), mas se você emitir milhões de passes, seu serviço web push deve lidar com alta concorrência.
  • Renovação do certificado: Os certificados de assinatura do passe expiram todos os anos ou dois. Você deve garantir que o seu servidor atualiza o certificado antes do prazo de validade, caso contrário todos os passes assinados com o certificado antigo deixarão de ser atualizáveis (eles ainda funcionarão, mas novos impulsos falharão).

Conclusão

A API iOS PassKit oferece uma forma robusta, segura e fácil de usar para gerenciar os passes de embarque e os tickets na Carteira Apple. Ao alavancar a criação de passes, assinatura, distribuição e atualizações de push em tempo real, os desenvolvedores podem oferecer uma experiência de viagem ou evento perfeita que mantém os usuários informados sem exigir engajamento constante de aplicativos. A Implementation PassKit requer atenção cuidadosa às diretrizes de design e segurança da Apple, bem como uma infraestrutura confiável ao lado do servidor, mas o pagamento na satisfação do cliente e eficiência operacional é substancial.

Para mais leitura, consulte a documentação do PassKit da Apple e o Guia de Programação do PassKit. Estes recursos cobrem as chaves JSON, as especificações de imagem e o protocolo de atualização push com detalhes exaustivos.