Partilhar via

PassKit no Xamarin.iOS

  • Artigo

O aplicativo iOS Wallet permite que os usuários armazenem passes digitais em seus dispositivos. Esses passes são gerados pelos comerciantes e enviados ao cliente por e-mail, URLs ou por meio do aplicativo iOS do próprio comerciante. Esses passes podem representar várias coisas, de ingressos de cinema a cartões de fidelidade e cartões de embarque. A estrutura PassKit permite que os desenvolvedores interajam com passes programaticamente.

Este documento apresenta a Carteira e o uso da API PassKit com o Xamarin.iOS.

A Carteira armazena e organiza todos os passes em um telefone

Requisitos

Os recursos do PassKit discutidos neste documento exigem o iOS 6 e o Xcode 4.5, juntamente com o Xamarin.iOS 6.0.

Introdução

O principal problema que o PassKit resolve é a distribuição e o gerenciamento de códigos de barras. Alguns exemplos reais de como os códigos de barras são usados atualmente incluem:

  • Comprar ingressos de cinema on-line – Os clientes geralmente recebem por e-mail um código de barras que representa seus ingressos. Este código de barras é impresso e levado ao cinema para ser digitalizado para entrada.
  • Cartões de fidelidade – Os clientes carregam vários cartões específicos da loja em sua carteira ou bolsa, para exibição e digitalização quando compram mercadorias.
  • Cupons – Os cupons são distribuídos via e-mail, como páginas web imprimíveis, através de caixas de correio e como códigos de barras em jornais e revistas. Os clientes os levam a uma loja para digitalização, para receber mercadorias, serviços ou descontos em troca.
  • Cartões de embarque – Semelhante à compra de um ingresso de cinema.

O PassKit oferece uma alternativa para cada um destes cenários:

  • Ingressos de cinema – Após a compra, o cliente adiciona um passe de ingresso para o evento (via e-mail ou link do site). À medida que o tempo para o filme se aproxima, o passe aparecerá automaticamente na tela de bloqueio como um lembrete e, na chegada ao cinema, o passe é facilmente recuperado e exibido na Carteira para digitalização.
  • Cartões de fidelidade – Em vez de (ou além de) fornecer um cartão físico, as lojas podem emitir (por e-mail ou após um login no site) um Passe do Cartão da Loja. A loja pode fornecer recursos adicionais, como atualizar o saldo da conta no passe por meio de notificações push e, usando serviços de geolocalização, o passe pode aparecer automaticamente na tela de bloqueio quando o cliente estiver perto de um local de loja.
  • Cupons – Os passes de cupom podem ser facilmente gerados com características únicas para ajudar no rastreamento e distribuídos por e-mail ou links de sites. Os cupons baixados podem aparecer automaticamente na tela de bloqueio quando o usuário está perto de um local específico e/ou em uma determinada data (como quando a data de validade está se aproximando). Como os cupons são armazenados no telefone do usuário, eles são sempre úteis e não são extraviados. Os cupons podem incentivar os clientes a baixar os aplicativos complementares porque os links da App Store podem ser incorporados ao passe, aumentando o envolvimento com o cliente.
  • Cartões de embarque – Após um processo de check-in online, o cliente receberia seu cartão de embarque por e-mail ou um link. Um aplicativo Companion fornecido pelo provedor de transporte pode incluir o processo de check-in e também permitir que o cliente execute funções adicionais, como escolher seu assento ou refeição. O provedor de transporte pode usar notificações por push para atualizar o passe se o transporte for atrasado ou cancelado. À medida que o horário de embarque se aproxima, o passe aparecerá na tela de bloqueio como um lembrete e para fornecer acesso rápido ao passe.

Em sua essência, o PassKit fornece uma maneira simples e conveniente de armazenar e exibir códigos de barras em seu dispositivo iOS. Com a integração adicional de tela de bloqueio de tempo e local, notificações push e integração do aplicativo Companion, ele oferece uma base para serviços de vendas, emissão de bilhetes e faturamento muito sofisticados.

Ecossistema PassKit

O PassKit não é apenas uma API dentro do CocoaTouch, mas faz parte de um ecossistema maior de aplicativos, dados e serviços que facilitam o compartilhamento e o gerenciamento seguros de códigos de barras e outros dados. Este diagrama de alto nível mostra as diferentes entidades que podem estar envolvidas na criação e no uso de passes:

Este diagrama de alto nível mostra as entidades envolvidas na criação e no uso de passes

Cada pedaço do ecossistema tem um papel claramente definido:

  • Wallet – o aplicativo iOS integrado da Apple que armazena e exibe passes. Este é o único lugar que os passes são renderizados para uso no mundo real (ou seja, o código de barras é exibido, juntamente com todos os dados localizados no passe).
  • Aplicativos complementares – aplicativos iOS 6 criados por provedores de passes para estender a funcionalidade dos passes que eles emitem, como agregar valor a um cartão de loja, alterar o assento em um cartão de embarque ou outra função específica do negócio. Os aplicativos complementares não são necessários para que um passe seja útil.
  • Seu servidor – Um servidor seguro onde os passes podem ser gerados e assinados para distribuição. Seu aplicativo Companion pode se conectar ao seu servidor para gerar novos passes ou solicitar atualizações para passes existentes. Opcionalmente, você pode implementar a API de serviço Web que a Carteira chamaria para atualizar passes.
  • Servidores APNS – Seu servidor tem a capacidade de notificar a Carteira sobre atualizações para uma passagem em um determinado dispositivo usando o APNS. Envie uma notificação para a Carteira, que entrará em contato com seu servidor para obter detalhes da alteração. Os aplicativos complementares não precisam implementar o APNS para esse recurso (eles podem ouvir o PKPassLibraryDidChangeNotification ).
  • Conduit Apps – Aplicativos que não manipulam diretamente passes (como aplicativos companheiros), mas que podem melhorar sua utilidade reconhecendo passes e permitindo que eles sejam adicionados à Carteira. Clientes de email, navegadores de redes sociais e outros aplicativos de agregação de dados podem encontrar anexos ou links para passes.

Todo o ecossistema parece complexo, então vale a pena notar que alguns componentes são opcionais e implementações de PassKit muito mais simples são possíveis.

O que é um Pass?

Um passe é uma coleção de dados que representam um bilhete, cupom ou cartão. Ele pode ser destinado a um único uso por um indivíduo (e, portanto, conter detalhes como um número de voo e alocação de assentos) ou pode ser um token de uso múltiplo que pode ser compartilhado por qualquer número de usuários (como um cupom de desconto). Uma descrição detalhada está disponível no documento Sobre arquivos de passe da Apple.

Tipos

Atualmente, cinco tipos suportados, que podem ser distinguidos no aplicativo Carteira pelo layout e borda superior do passe:

  • Ingresso para Evento – pequeno recorte semicircular.
  • Cartão de embarque – entalhes na lateral, ícone específico de transporte pode ser especificado (por exemplo, ônibus, trem, avião).
  • Cartão da loja – topo arredondado, como um cartão de crédito ou débito.
  • Cupom – perfurado ao longo da parte superior.
  • Genérico – o mesmo que Store Card, topo arredondado.

Os cinco tipos de passe são mostrados nesta captura de tela (em ordem: cupom, genérico, cartão da loja, cartão de embarque e ingresso do evento):

Os cinco tipos de passe são mostrados nesta captura de tela

Estrutura de Arquivos

Um arquivo pass é na verdade um arquivo ZIP com uma extensão .pkpass , contendo alguns arquivos JSON específicos (obrigatório), uma variedade de arquivos de imagem (opcional), bem como cadeias de caracteres localizadas (também opcional).

  • pass.json – obrigatório. Contém todas as informações para o passe.
  • manifest.json – obrigatório. Contém hashes SHA1 para cada arquivo na passagem, exceto o arquivo de assinatura e este arquivo (manifest.json).
  • assinatura – obrigatória. Criado assinando o manifest.json arquivo com o certificado gerado no Portal de Provisionamento do iOS.
  • logo.png – opcional.
  • background.png – opcional.
  • icon.png – opcional.
  • Arquivos de cadeias de caracteres localizáveis – opcional.

A estrutura de diretório de um arquivo de passagem é mostrada abaixo (este é o conteúdo do arquivo ZIP):

A estrutura de diretório de um arquivo de passagem é mostrada aqui

pass.json

JSON é o formato porque os passes são normalmente criados em um servidor – isso significa que o código de geração é independente de plataforma no servidor. As três principais informações em cada passagem são:

  • teamIdentifier – Vincula todos os passes que você gera à sua conta da App Store. Esse valor é visível no Portal de Provisionamento do iOS.
  • passTypeIdentifier – Registre-se no Portal de Provisionamento para agrupar passes juntos (se você produzir mais de um tipo). Por exemplo, uma cafeteria pode criar um tipo de passe de cartão de loja para permitir que seus clientes ganhem créditos de fidelidade, mas também um tipo de passe de cupom separado para criar e distribuir cupons de desconto. Essa mesma cafeteria pode até realizar eventos de música ao vivo e emitir passes de ingressos para eventos.
  • serialNumber – Uma cadeia de caracteres exclusiva dentro deste passTypeidentifier . O valor é opaco para a Carteira, mas é importante para rastrear passes específicos ao se comunicar com seu servidor.

Há um grande número de outras chaves JSON em cada Pass, um exemplo do qual é mostrado abaixo:

{
   "passTypeIdentifier":"com.xamarin.passkitdoc.banana",  //Type Identifier (iOS Provisioning Portal)
   "formatVersion":1,                                     //Always 1 (for now)
   "organizationName":"Xamarin",                          //The name which appears on push notifications
   "serialNumber":"12345436XYZ",                          //A number for you to identify this pass
   "teamIdentifier":"XXXAAA1234",                         //Your Team ID
   "description":"Xamarin Demo",                          //
   "foregroundColor":"rgb(54,80,255)",                    //color of the data text (note the syntax)
   "backgroundColor":"rgb(209,255,247)",                  //color of the background
   "labelColor":"rgb(255,15,15)",                         //color of label text and icons
   "logoText":"Banana ",                                  //Text that appears next to logo on top
   "barcode":{                                            //Specification of the barcode (optional)
      "format":"PKBarcodeFormatQR",                       //Format can be QR, Text, Aztec, PDF417
      "message":"FREE-BANANA",                            //What to encode in barcode
      "messageEncoding":"iso-8859-1"                      //Encoding of the message
   },
   "relevantDate":"2012-09-15T15:15Z",                    //When to show pass on screen. ISO8601 formatted.
  /* The following fields are specific to which type of pass. The name of this object specifies the type, e.g., boardingPass below implies this is a boarding pass. Other options include storeCard, generic, coupon, and eventTicket */
   "boardingPass":{
/*headerFields, primaryFields, secondaryFields, and auxiliaryFields are arrays of field object. Each field has a key, label, and value*/
      "headerFields":[          //Header fields appear next to logoText
         {
            "key":"h1-label",   //Must be unique. Used by iOS apps to get the data.
            "label":"H1-label", //Label of the field
            "value":"H1"        //The actual data in the field
         },
         {
            "key":"h2-label",
            "label":"H2-label",
            "value":"H2"
         }
      ],
      "primaryFields":[       //Appearance differs based on pass type
         {
            "key":"p1-label",
            "label":"P1-label",
            "value":"P1"
         }
      ],
      "secondaryFields":[     //Typically appear below primaryFields
         {
            "key":"s1-label",
            "label":"S1-label",
            "value":"S1"
         }
      ],
      "auxiliaryFields":[    //Appear below secondary fields
         {
            "key":"a1-label",
            "label":"A1-label",
            "value":"A1"
         }
      ],
      "transitType":"PKTransitTypeAir"  //Only present in boradingPass type. Value can
                                        //Air, Bus, Boat, or Train. Impacts the picture
                                        //that shows in the middle of the pass.
   }
}

Códigos de barras

Apenas os formatos 2D são suportados: PDF417, Aztec, QR. A Apple afirma que os códigos de barras 1D não são adequados para digitalização em uma tela de telefone retroiluminada.

O texto alternativo exibido abaixo do código de barras é opcional – alguns comerciantes querem ser capazes de ler/digitar manualmente.

A codificação ISO-8859-1 é a mais comum, verifique qual codificação é usada pelos sistemas de digitalização que lerão seus passes.

Relevância (Tela de bloqueio)

Há dois tipos de dados que podem fazer com que uma passagem seja exibida na tela de bloqueio:

Localidade

Até 10 locais podem ser especificados em um Pass, por exemplo, lojas que um cliente visita com frequência, ou a localização de um cinema ou aeroporto. Um cliente pode definir esses locais por meio de um aplicativo complementar ou o provedor pode determiná-los a partir dos dados de uso (se coletados com a permissão do cliente).

Quando o passe é exibido na tela de bloqueio, uma cerca é calculada para que, quando o usuário sair da área, o passe fique oculto da tela de bloqueio. O raio é amarrado ao estilo de passagem para evitar abusos.

Data e Hora

Apenas uma data/hora pode ser especificada em um Pass. A data e a hora são úteis para acionar lembretes de tela de bloqueio para cartões de embarque e ingressos para eventos.

Pode ser atualizado via push ou via API PassKit, para que a data/hora possa ser atualizada no caso de um ingresso de uso múltiplo (como um ingresso de temporada para um teatro ou complexo esportivo).

Localização

Traduzir um passe para vários idiomas é semelhante à localização de um aplicativo iOS – crie diretórios específicos de idioma com a .lproj extensão e coloque os elementos localizados dentro. As traduções de texto devem ser inseridas em um pass.strings arquivo, enquanto as imagens localizadas devem ter o mesmo nome da imagem que substituem na raiz Pass.

Segurança

Os passes são assinados com um certificado privado que você gera no Portal de Provisionamento do iOS. Os passos para assinar o passe são:

  1. Calcule um hash SHA1 para cada arquivo no diretório de passagem (não inclua o manifest.json arquivo ou signature , nenhum dos quais deve existir neste estágio de qualquer maneira).
  2. Escreva manifest.json como uma lista de chave/valor JSON de cada nome de arquivo com seu hash.
  3. Use o certificado para assinar o manifest.json arquivo e gravar o resultado em um arquivo chamado signature .
  4. ZIP o tudo para cima e dar ao arquivo resultante uma extensão de .pkpass arquivo.

Como sua chave privada é necessária para assinar o passe, esse processo só deve ser feito em um servidor seguro que você controla. NÃO distribua suas chaves para tentar gerar passes em um aplicativo.

Configuração e instalação

Esta seção contém instruções para ajudar a configurar seus detalhes de provisionamento e criar sua primeira passagem.

PassKit de provisionamento

Para que um passe entre na App Store, ele deve estar vinculado a uma conta de desenvolvedor. Isso requer duas etapas:

  1. O passe deve ser registrado usando um identificador exclusivo, chamado de ID do Tipo de Pass.
  2. Um certificado válido deve ser gerado para assinar o passe com a assinatura digital do desenvolvedor.

Para criar uma ID de Tipo de Pass, faça o seguinte.

Criar uma ID de Tipo de Passe

A primeira etapa é configurar um ID de Tipo de Passe para cada tipo diferente de passe a ser suportado. O ID de Passe (ou identificador de Tipo de Pass) cria um identificador exclusivo para o Pass. Usaremos essa ID para vincular o passe à sua conta de desenvolvedor usando um Certificado.

  1. Na seção Certificados, Identificadores e Perfis do Portal de Provisionamento do iOS, navegue até Identificadores e selecione IDs de Tipo de Passe . Em seguida, selecione o + botão para criar um novo tipo de passe: Criar um novo tipo de passe

  2. Forneça uma Descrição (nome) e um Identificador (cadeia de caracteres exclusiva) para o Pass. Observe que todas as IDs de Tipo de Passe devem começar com a cadeia de caracteres pass. Neste exemplo, usamos pass.com.xamarin.coupon.banana : Fornecer uma descrição e um identificador

  3. Confirme o ID do passe pressionando o botão Registrar .

Gerar um certificado

Para criar um novo Certificado para esta ID de Tipo de Aprovação, faça o seguinte:

  1. Selecione a ID de Passe recém-criada na lista e clique em Editar : Selecione o novo ID de Passe na lista

    Em seguida, selecione Criar Certificado... :

    Selecione Criar certificado

  2. Siga as etapas para criar uma Solicitação de Assinatura de Certificado (CSR).

  3. Pressione o botão Continuar no portal do desenvolvedor e carregue o CSR para gerar seu certificado.

  4. Baixe o certificado e clique duas vezes nele para instalá-lo em suas chaves.

Agora que criamos um certificado para essa ID de Tipo de Pass, a próxima seção descreve como criar uma senha manualmente.

Para obter mais informações sobre o provisionamento para carteira, consulte o guia Trabalhando com recursos .

Criar um passe manualmente

Agora que criamos o Pass Type, podemos criar manualmente um passe para testar no simulador ou em um dispositivo. As etapas para criar um passe são:

  • Crie um diretório para conter os arquivos de passagem.
  • Crie um arquivo pass.json que contenha todos os dados necessários.
  • Inclua imagens na pasta (se necessário).
  • Calcule hashes SHA1 para cada arquivo na pasta e grave em manifest.json.
  • Entre manifest.json com o arquivo .p12 do certificado baixado.
  • ZIP o conteúdo do diretório e renomeie com a extensão .pkpass.

Existem alguns arquivos de origem no código de exemplo para este artigo que podem ser usados para gerar um passe. Use os CouponBanana.raw arquivos no diretório do diretório CreateAPassManual. Os seguintes arquivos estão presentes:

Esses arquivos estão presentes

Abra pass.json e edite o JSON. Você deve pelo menos atualizar o passTypeIdentifier e teamIdentifer para corresponder à sua conta de desenvolvedor Apple.

"passTypeIdentifier" : "pass.com.xamarin.coupon.banana",
"teamIdentifier" : "?????????",

Em seguida, você deve calcular os hashes para cada arquivo e criar o manifest.json arquivo. Será algo parecido com isso quando você terminar:

{
  "icon@2x.png" : "30806547dcc6ee084a90210e2dc042d5d7d92a41",
  "icon.png" : "87e9ffb203beb2cce5de76113f8e9503aeab6ecc",
  "pass.json" : "c83cd1441c17ecc6c5911bae530d54500f57d9eb",
  "logo.png" : "b3cd8a488b0674ef4e7d941d5edbb4b5b0e6823f",
  "logo@2x.png" : "3ccd214765507f9eab7244acc54cc4ac733baf87"
}

Em seguida, uma assinatura deve ser gerada para esse arquivo usando o certificado (arquivo .p12) que foi gerado para essa ID de tipo de passe.

Iniciar sessão num Mac

Baixe os materiais de suporte do Wallet Seed no site Apple Downloads. Use a signpass ferramenta para transformar sua pasta em um passe (isso também calculará os hashes SHA1 e ZIP a saída em um arquivo .pkpass).

Testando

Se você fosse examinar a saída dessas ferramentas (definindo o nome do arquivo como .zip e, em seguida, abrindo-o), você veria os seguintes arquivos (observe a adição dos manifest.json arquivos e signature ):

Examinando a saída dessas ferramentas

Depois de assinar, ZIPped e renomear o arquivo (por exemplo, para BananaCoupon.pkpass) você pode arrastá-lo para o simulador para testar, ou enviá-lo por e-mail para si mesmo para recuperar em um dispositivo real. Você deve ver uma tela para adicionar o passe, assim:

Adicionar a tela de aprovação

Normalmente, esse processo seria automatizado em um servidor, no entanto, a criação manual de passes pode ser uma opção para pequenas empresas que estão criando apenas cupons que não exigem o suporte de um servidor back-end.

Carteira

A carteira é a peça central do ecossistema PassKit. Esta captura de tela mostra a Carteira vazia e a aparência da lista de passes e dos passes individuais:

Esta captura de tela mostra a Carteira vazia e a aparência da lista de passes e dos passes individuais

As características do Wallet incluem:

  • É o único lugar que passa com seu código de barras para digitalização.
  • O usuário pode alterar as configurações de atualizações. Se habilitada, as notificações por push podem disparar atualizações para os dados no Pass.
  • O usuário pode habilitar ou desabilitar a integração de tela de bloqueio. Se habilitado, isso permite que o passe apareça automaticamente em sua tela de bloqueio, com base nos dados relevantes de hora e localização incorporados no passe.
  • O lado inverso do passe suporta pull-to-refresh, se uma URL de servidor web for fornecida no JSON de passagem.
  • Os aplicativos complementares podem ser abertos (ou baixados) se a ID do aplicativo for fornecida no passe JSON.
  • Os passes podem ser excluídos (com uma animação de destruição fofa).

Adicionando passes na carteira

Os passes podem ser adicionados à Carteira das seguintes maneiras:

  • Conduit Apps – Estes não manipulam passes diretamente, eles simplesmente carregam arquivos de passe e apresentam ao usuário a opção de adicioná-los à Carteira.

  • Aplicativos complementares – são escritos por provedores para distribuir passes e oferecer funcionalidade adicional para navegar ou editá-los. Os aplicativos Xamarin.iOS têm acesso completo à API PassKit para criar e manipular passes. Os passes podem ser adicionados à Carteira usando o PKAddPassesViewController. Esse processo é descrito com mais detalhes na seção Aplicativos complementares deste documento.

Aplicações de Conduítes

Os aplicativos de conduíte são aplicativos intermediários que podem receber passes em nome de um usuário e devem ser programados para reconhecer seu tipo de conteúdo e fornecer funcionalidade para adicionar à Carteira. Exemplos de aplicativos de conduíte incluem:

  • Mail – Reconhece o anexo como um Pass.
  • Safari – Reconhece o tipo de conteúdo do passe quando um link de URL de passagem é clicado.
  • Outros aplicativos personalizados – Qualquer aplicativo que receba anexos ou links abertos (clientes de mídia social, leitores de e-mail, etc).

Esta captura de tela mostra como o Mail no iOS 6 reconhece um anexo de passe e (quando tocado) se oferece para adicioná-lo à Carteira.

Esta captura de tela mostra como o Mail no iOS 6 reconhece um anexo de passagem

Esta captura de tela mostra como o Mail oferece para adicionar um anexo de passe à Carteira

Se você estiver criando um aplicativo que possa ser um canal para passes, eles podem ser reconhecidos por:

  • Extensão do arquivo - .pkpass
  • Tipo MIME - application/vnd.apple.pkpass
  • UTI – com.apple.pkpass

A operação básica de um aplicativo de conduíte é recuperar o arquivo de passe e chamar PassKit's PKAddPassesViewController para dar ao usuário a opção de adicionar o passe à sua carteira. A implementação desse controlador de exibição é abordada na próxima seção sobre Aplicativos complementares.

Os Aplicativos de Conduíte não precisam ser provisionados para uma ID de Tipo de passagem específica da mesma forma que os Aplicativos Complementares.

Aplicativos complementares

Um aplicativo complementar fornece funcionalidade adicional para trabalhar com passes, incluindo a criação de um Pass, a atualização de informações associadas a um Pass e, de outra forma, o gerenciamento de passes associados ao aplicativo.

Os aplicativos complementares não devem tentar duplicar os recursos do Wallet. Eles não se destinam a exibir passes para digitalização.

Este restante desta seção descreve como criar um aplicativo complementar básico que interage com o PassKit.

Provisionamento

Como a Carteira é uma tecnologia de loja, o aplicativo precisa ser provisionado separadamente e não pode usar o Perfil de Provisionamento de Equipe ou a ID do Aplicativo Curinga. Consulte o guia Trabalhando com recursos para criar uma ID de aplicativo e um perfil de provisionamento exclusivos para o aplicativo Carteira.

Qualificações

O arquivo Entitlements.plist deve ser incluído em todos os projetos Xamarin.iOS recentes. Para adicionar um novo arquivo Entitlements.plist, siga as etapas no guia Trabalhando com Direitos .

Para definir direitos, faça o seguinte:

Clique duas vezes no arquivo Entitlements.plist no Solution Pad para abrir o editor Entitlements.plist:

Editor Entitlements.plst

Na seção Carteira, selecione a opção Ativar Carteira

Habilitar o direito à carteira

A opção padrão é que seu aplicativo permita todos os tipos de passe. No entanto, é possível restringir seu aplicativo e permitir apenas um subconjunto de tipos de passe de equipe. Para habilitar isso, selecione o subconjunto Permitir de tipos de passe de equipe e insira o identificador de tipo de passe do subconjunto que você deseja permitir.

Depuração

Se você tiver problemas para implantar seu aplicativo, verifique se está usando o Perfil de provisionamento correto e se o Entitlements.plist está selecionado como o arquivo de direitos personalizados nas opções de assinatura de pacote do iPhone.

Se você enfrentar esse erro ao implantar:

Installation failed: Your code signing/provisioning profiles are not correctly configured (error: 0xe8008016)

em seguida, a pass-type-identifiers matriz de direitos está incorreta (ou não corresponde ao Perfil de Provisionamento). Verifique se as IDs do Tipo de Aprovação e sua ID de Equipe estão corretas.

Classes

As seguintes classes de PassKit estão disponíveis para aplicativos acessarem passes:

  • PKPass – Uma instância de um Pass.
  • PKPassLibrary – Fornece a API para acessar os passes no dispositivo.
  • PKAddPassesViewController – Usado para exibir um passe para o usuário salvar em sua carteira.
  • PKAddPassesViewControllerDelegate – desenvolvedores Xamarin.iOS

Exemplo

Consulte o projeto PassLibrary no exemplo deste artigo. Ele demonstra as seguintes funções comuns que seriam necessárias em um aplicativo Wallet Companion:

Verifique se a Carteira está disponível

A carteira não está disponível no iPad, portanto, os aplicativos devem verificar antes de tentar acessar os recursos do PassKit.

if (PKPassLibrary.IsAvailable) {
    // create an instance and do stuff...
}

Criando uma instância de biblioteca de aprovação

A biblioteca PassKit não é um singleton, os aplicativos devem criar e armazenar e instância para acessar a API PassKit.

if (PKPassLibrary.IsAvailable) {
    library = new PKPassLibrary ();
    // do stuff...
}

Obter uma lista de passes

Os aplicativos podem solicitar uma lista de passes da biblioteca. Essa lista é filtrada automaticamente pelo PassKit, para que você só possa ver os passes que foram criados com sua ID de Equipe e que estão listados em seus Direitos.

var passes = library.GetPasses ();  // returns PKPass[]

Note que o simulador não filtra a lista de passes retornados, então esse método deve sempre ser testado em dispositivos reais. Essa lista pode ser exibida em um UITableView. O aplicativo de exemplo tem esta aparência depois que dois cupons foram adicionados:

O aplicativo de exemplo tem esta aparência depois que dois cupons foram adicionados

Exibindo passes

Um conjunto limitado de informações está disponível para renderização de passes em aplicativos complementares.

Escolha entre esse conjunto de propriedades padrão para exibir listas de passagens, como faz o código de exemplo.

string passInfo =
                "Desc:" + pass.LocalizedDescription
                + "\nOrg:" + pass.OrganizationName
                + "\nID:" + pass.PassTypeIdentifier
                + "\nDate:" + pass.RelevantDate
                + "\nWSUrl:" + pass.WebServiceUrl
                + "\n#" + pass.SerialNumber
                + "\nPassUrl:" + pass.PassUrl;

Essa cadeia de caracteres é mostrada como um alerta no exemplo:

O alerta Cupom selecionado no exemplo

Você também pode usar o LocalizedValueForFieldKey() método para recuperar dados de campos nos passes que você criou (já que você saberá quais campos devem estar presentes). O código de exemplo não mostra isso.

Carregando um passe de um arquivo

Como um passe só pode ser adicionado à Carteira com a permissão do usuário, um controlador de exibição deve ser apresentado para permitir que ele decida. Esse código é usado no botão Adicionar no exemplo, para carregar um passe pré-criado que está incorporado no aplicativo (você deve substituí-lo por um que você assinou):

NSData nsdata;
using ( FileStream oStream = File.Open (newFilePath, FileMode.Open ) ) {
        nsdata = NSData.FromStream ( oStream );
}
var err = new NSError(new NSString("42"), -42);
var newPass = new PKPass(nsdata,out err);
var pkapvc = new PKAddPassesViewController(newPass);
NavigationController.PresentModalViewController (pkapvc, true);

O passe é apresentado com as opções Adicionar e Cancelar :

O passe apresentado com as opções Adicionar e Cancelar

Substituir um passe existente

A substituição de um passe existente não requer a permissão do usuário, no entanto, ele falhará se o passe ainda não existir.

if (library.Contains (newPass)) {
     library.Replace (newPass);
}

Editando um passe

PKPass não é mutável, portanto, você não pode atualizar objetos de passagem em seu código. Para alterar os dados em um passe, um aplicativo deve ter acesso a um servidor Web que possa manter um registro de passes e gerar um novo arquivo de passe com valores atualizados que o aplicativo pode baixar.

A criação do arquivo pass deve ser feita em um servidor porque os passes devem ser assinados com um certificado que deve ser mantido privado e seguro.

Depois que um arquivo de passagem atualizado tiver sido gerado, use o Replace método para substituir os dados antigos no dispositivo.

Exibir um Passe para digitalização

Como observado anteriormente, apenas a Carteira pode exibir um passe para digitalização. Um Pass pode ser exibido usando o OpenUrl método como mostrado:

UIApplication.SharedApplication.OpenUrl (p.PassUrl);

Recebendo notificações de alterações

Os aplicativos podem escutar as alterações que estão sendo feitas na Biblioteca de Passes usando o PKPassLibraryDidChangeNotification. As alterações podem ser causadas por notificações que disparam atualizações em segundo plano, portanto, é uma boa prática ouvi-las em seu aplicativo.

noteCenter = NSNotificationCenter.DefaultCenter.AddObserver (PKPassLibrary.DidChangeNotification, (not) => {
    BeginInvokeOnMainThread (() => {
        new UIAlertView("Pass Library Changed", "Notification Received", null, "OK", null).Show();
        // refresh the list
        var passlist = library.GetPasses ();
        table.Source = new TableSource (passlist, library);
        table.ReloadData ();
    });
}, library);  // IMPORTANT: must pass the library in

É importante passar uma instância de biblioteca ao se registrar para a notificação porque PKPassLibrary não é um singleton.

Processamento do servidor

Uma discussão detalhada sobre a criação de um aplicativo de servidor para oferecer suporte ao PassKit está além do escopo deste artigo introdutório.

Consulte código do lado do servidor C# de código aberto dotnet-passbook .

Notificações por Push

Uma discussão detalhada sobre o uso de notificações por push para atualizar passes está além do escopo deste artigo introdutório.

Você seria obrigado a implementar a API do tipo REST definida pela Apple para responder a solicitações da Web da Carteira quando atualizações forem necessárias.

Consulte o guia Atualizando um passe da Apple para obter mais informações.

Resumo

Este artigo apresentou o PassKit, descreveu algumas das razões pelas quais ele é útil e descreveu as diferentes partes que devem ser implementadas para uma solução completa do PassKit. Ele descreveu as etapas necessárias para configurar sua conta de desenvolvedor da Apple para criar passes, o processo para fazer um passe manualmente e também como acessar as APIs do PassKit a partir de um aplicativo Xamarin.iOS.