Compartir a través de

PassKit en Xamarin.iOS

  • Artículo

La aplicación Wallet de iOS permite a los usuarios almacenar pases digitales en sus dispositivos. Estos pases los generan los comerciantes y se envían al cliente por correo electrónico, mediante direcciones URL o a través de la propia aplicación iOS del comerciante. Estos pases pueden representar diversas cosas, desde entradas de cine hasta tarjetas de fidelidad o de embarque. El marco PassKit permite a los desarrolladores interactuar con pases mediante programación.

En este documento se presenta Wallet y se usa la API de PassKit con Xamarin.iOS.

Wallet almacena y organiza todos los pases en un teléfono

Requisitos

Las características de PassKit descritas en este documento requieren iOS 6 y Xcode 4.5, junto con Xamarin.iOS 6.0.

Introducción

El problema clave que resuelve PassKit es la distribución y administración de códigos de barras. Algunos ejemplos reales de cómo se usan actualmente los códigos de barras son:

  • Comprar entradas de cine en línea: a los clientes se les suele enviar por correo electrónico un código de barras que representa sus entradas. Este código de barras se imprime y se lleva al cine para ser escaneado como entrada.
  • Tarjetas de fidelidad: los clientes llevan una serie de tarjetas específicas de cada tienda en su cartera o bolso, para mostrar y escanear cuando compran productos.
  • Cupones: los cupones se distribuyen por correo electrónico, como páginas web imprimibles, a través de buzones y como códigos de barras en periódicos y revistas. Los clientes los llevan a una tienda para escanearlos y recibir artículos, servicios o descuentos a cambio.
  • Tarjetas de embarque: similar a comprar una entrada de cine.

PassKit ofrece una alternativa para cada uno de estos escenarios:

  • Entradas de cine: después de la compra, el cliente agrega un pase de entrada de evento (por correo electrónico o un vínculo al sitio web). A medida que se aproxime el momento de la película, el pase aparecerá automáticamente en la pantalla de bloqueo como recordatorio, y al llegar al cine, el pase se recupera y se muestra fácilmente en Wallet para escanearlo.
  • Tarjetas de fidelidad: en lugar de (o además de) proporcionar una tarjeta física, las tiendas pueden emitir (por correo electrónico o después de iniciar sesión en un sitio web) un pase de tarjeta de la tienda. La tienda puede proporcionar características adicionales, como actualizar el saldo de la cuenta en el pase a través de notificaciones push, y con el uso de servicios de geolocalización, el pase puede aparecer automáticamente en la pantalla de bloqueo cuando el cliente está cerca de una ubicación de tienda.
  • Cupones: los pases de cupones se pueden generar fácilmente con características únicas para ayudar con el seguimiento, y distribuirse a través de correo electrónico o vínculos de sitios web. Los cupones descargados pueden aparecer automáticamente en la pantalla de bloqueo cuando el usuario está cerca de una ubicación específica o en una fecha determinada (por ejemplo, cuando se acerca la fecha de expiración). Dado que los cupones se almacenan en el teléfono del usuario, siempre están a mano y no se pierden. Los cupones pueden animar a los clientes a descargar aplicaciones complementarias porque pueden incorporarse vínculos de App Store al pase, para aumentar la interacción con el cliente.
  • Tarjetas de embarque: después de un proceso de registro en línea, el cliente recibiría su tarjeta de embarque por correo electrónico o mediante un vínculo. Una aplicación complementaria proporcionada por el proveedor de transporte podría incluir el proceso de registro de entrada y también permitir al cliente realizar funciones adicionales, como elegir su asiento o lo que quiere comer. El proveedor de transporte puede usar notificaciones push para actualizar el pase si el transporte se retrasa o se cancela. A medida que el tiempo de embarque se aproxime, el pase aparecerá en la pantalla de bloqueo como recordatorio y para proporcionar acceso rápido al pase.

En su núcleo, PassKit proporciona una manera sencilla y cómoda de almacenar y mostrar códigos de barras en un dispositivo iOS. Con la integración de la pantalla de bloqueo de ubicación y tiempo adicional, las notificaciones push y la aplicación complementaria que lo integran ofrece una base para ventas, entradas y servicios de facturación muy sofisticados.

Ecosistema de PassKit

PassKit no es solo una API dentro de CocoaTouch, sino que forma parte de un ecosistema más grande de aplicaciones, datos y servicios que facilitan el uso compartido seguro y la administración de códigos de barras y otros datos. En este diagrama de nivel general se muestran las distintas entidades que pueden participar en la creación y el uso de pases:

En este diagrama de alto nivel se muestran las entidades implicadas en la creación y el uso de pases

Cada parte del ecosistema tiene un rol claramente definido:

  • Wallet: aplicación de iOS integrada de Apple que almacena y muestra pases. Este es el único lugar en el que se representan los pases para su uso en el mundo real (es decir, se muestra el código de barras, junto con todos los datos localizados del pase).
  • Aplicaciones complementarias: aplicaciones de iOS 6 creadas por proveedores de pases para ampliar la funcionalidad de los pases que emiten, como agregar valor a una tarjeta de tienda, cambiar el asiento en una tarjeta de embarque u otra función empresarial específica. Las aplicaciones complementarias no son necesarias para que un pase sea útil.
  • Servidor: un servidor seguro en el que se pueden generar y firmar pases para su distribución. La aplicación complementaria puede conectarse al servidor para generar nuevos pases o solicitar actualizaciones a los pases existentes. Opcionalmente, puede implementar la API de servicio web a la que Wallet llamará para actualizar los pases.
  • Servidores APNS: el servidor tiene la capacidad de notificar a Wallet las actualizaciones de un pase en un dispositivo determinado mediante APNS. Inserte una notificación push en Wallet que, a continuación, se pondrá en contacto con el servidor para obtener más información sobre el cambio. Las aplicaciones complementarias no necesitan implementar APNS para esta característica (pueden escuchar a PKPassLibraryDidChangeNotification).
  • Aplicaciones de conducto: aplicaciones que no manipulan directamente pases (como las aplicaciones complementarias), pero que pueden mejorar su utilidad al reconocer pases y permitir agregarlos a Wallet. Los clientes de correo, los exploradores de redes sociales y otras aplicaciones de agregación de datos pueden encontrar datos adjuntos o vínculos a pases.

Todo el ecosistema parece complejo, por lo que merece la pena tener en cuenta que algunos componentes son opcionales y se pueden realizar implementaciones de PassKit mucho más sencillas.

¿Qué es un pase?

Un pase es una colección de datos que representan un vale, un cupón o una tarjeta. Puede estar pensado para un solo uso por parte de un individuo (y, por tanto, contener detalles como un número de vuelo y una asignación de asiento) o puede ser un token de uso múltiple que pueda compartir cualquier número de usuarios (como un cupón de descuento). Hay una descripción detallada disponible en el documento Acerca de los archivos de pase de Apple.

Tipos

Actualmente, cinco tipos admitidos, que se pueden distinguir en la aplicación Wallet por el diseño y el borde superior del pase:

  • Entrada de evento: corte semicircular pequeño.
  • Tarjeta de embarque: se pueden especificar muescas laterales, iconos específico del transporte (por ejemplo, autobús, tren, avión).
  • Tarjeta de tienda: parte superior redondeada, como una tarjeta de crédito o débito.
  • Cupón: perforado a lo largo de la parte superior.
  • Genérico: igual que la tarjeta de la tienda, redondeada en la parte superior.

Los cinco tipos de pase se muestran en esta captura de pantalla (en orden: cupón, genérico, tarjeta de tienda, tarjeta de embarque y entrada de evento):

Los cinco tipos de pase se muestran en esta captura de pantalla

Estructura de archivos

Un archivo de pase en realidad es un archivo ZIP con una extensión .pkpass, que contiene algunos archivos JSON específicos (obligatorios), una variedad de archivos de imagen (opcional) y cadenas localizadas (también opcional).

  • pass.json: obligatorio. Contiene toda la información del pase.
  • manifest.json: obligatorio. Contiene hash SHA1 para cada archivo del pase, excepto el archivo de firma y este archivo (manifest.json).
  • signature: obligatorio. Se crea firmando el archivo manifest.json con el certificado generado en el portal de aprovisionamiento de iOS.
  • logo.png: opcional.
  • background.png: opcional.
  • icon.png: opcional.
  • Archivos de cadenas localizables: opcional.

La estructura de directorios de un archivo de pase se muestra a continuación (este es el contenido del archivo ZIP):

La estructura del directorio de un archivo de pase se muestra aquí

pass.json

JSON es el formato porque los pases normalmente se crean en un servidor, lo cual significa que el código de generación es independiente de la plataforma en el servidor. Los tres fragmentos clave de información de cada pase son:

  • teamIdentifier: vincula todos los pases que se generan a una cuenta de App Store. Este valor es visible en el portal de aprovisionamiento de iOS.
  • passTypeIdentifier: realiza el registro en el portal de aprovisionamiento para agrupar los pases (si se genera más de un tipo). Por ejemplo, una cafetería puede crear un tipo de pase de tarjeta de tienda para permitir que sus clientes obtengan créditos de fidelidad, pero también un tipo de pase de cupón independiente para crear y distribuir cupones de descuento. Esa misma cafetería puede incluso contener eventos de música en directo y emitir para ellos pases de entrada de evento.
  • serialNumber: una cadena única dentro de este passTypeidentifier. El valor es opaco para Wallet, pero es importante para realizar un seguimiento de pases específicos al comunicarse con el servidor.

Hay un gran número de otras claves JSON en cada pase y a continuación se muestra un ejemplo de ello:

{
   "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

Solo se admiten formatos 2D: PDF417, Aztec, QR. Apple afirma que los códigos de barras 1D no están adecuados para escanear en una pantalla de teléfono retroiluminada.

El texto alternativo que se muestra debajo del código de barras es opcional: algunos comerciantes quieren poder leer o escribir manualmente.

La codificación ISO-8859-1 es la más común, compruebe qué codificación se usa en los sistemas de escaneado que leerán los pases.

Relevancia (pantalla de bloqueo)

Hay dos tipos de datos que pueden hacer que se muestre un pase en la pantalla de bloqueo:

Ubicación

Se pueden especificar hasta 10 ubicaciones en un pase, por ejemplo, tiendas que un cliente visita con frecuencia o la ubicación de un cine o un aeropuerto. Un cliente puede establecer estas ubicaciones a través de una aplicación complementaria o el proveedor puede determinarlas a partir de los datos de uso (si se recopilan con el permiso del cliente).

Cuando se muestra el pase en la pantalla de bloqueo, se calcula un perímetro de seguridad para que cuando el usuario salga del área, el pase esté oculto de la pantalla de bloqueo. El radio está vinculado al estilo de pase, para evitar un abuso.

Fecha y hora

Solo se puede especificar una fecha/hora en un pase. La fecha y hora es útil para desencadenar recordatorios de pantalla de bloqueo para las tarjetas de embarque y las entradas de evento.

Se puede actualizar por inserción (push) o a través de la API de PassKit, de modo que la fecha y hora se pueda actualizar en el caso de un vale de varios usos (por ejemplo, un abono de temporada a un teatro o un complejo deportivo).

Localización

Traducir un pase a varios idiomas es similar a localizar una aplicación de iOS: cree directorios específicos del idioma con la extensión .lproj y coloque los elementos localizados dentro. Las traducciones de texto deben escribirse en un archivo pass.strings, mientras que las imágenes localizadas deben tener el mismo nombre que la imagen que reemplazan en la raíz del pase.

Seguridad

Los pases se firman con un certificado privado que se genera en el portal de aprovisionamiento de iOS. Los pasos para firmar el pase son:

  1. Calcule un hash SHA1 para cada archivo del directorio de pase (no incluya el archivo manifest.json o signature, ninguno de los cuales debería existir en esta fase).
  2. Escriba manifest.json como una lista de clave/valor JSON de cada nombre de archivo con su hash.
  3. Use el certificado para firmar el archivo manifest.json y escribir el resultado en un archivo denominado signature.
  4. Comprímalo todo y dé al archivo resultante una extensión de archivo .pkpass.

Dado que la clave privada es necesaria para firmar el pase, este proceso solo debe realizarse en un servidor seguro controlado por el usuario. NO distribuya las claves para probar y generar pases en una aplicación.

Instalación y configuración

Esta sección contiene instrucciones para ayudar a configurar los detalles del aprovisionamiento y crear el primer pase.

Aprovisionar PassKit

Para que un pase entre en Apple Store, debe estar vinculado a una cuenta de desarrollador. Esto requiere dos pasos:

  1. El pase debe registrarse mediante un identificador único, denominado id. de tipo de pase.
  2. Se debe generar un certificado válido para firmar el pase con la firma digital del desarrollador.

Para crear un identificador de tipo de pase, haga lo siguiente.

Crear un identificador de tipo de pase

El primer paso es configurar un identificador de tipo de pase para cada tipo de pase diferente que se va a admitir. El identificador de pase (o identificador de tipo de pase) crea un identificador único para el pase. Usaremos este identificador para vincular el pase con su cuenta de desarrollador mediante un certificado.

  1. En la sección Certificados, identificadores y perfiles del portal de aprovisionamiento de iOS, vaya a Identificadores y seleccioneIdentificadores de tipo de pase. A continuación, seleccione el botón + para crear un nuevo tipo de pase: Crear un nuevo tipo de pase

  2. Proporcione una Descripción (nombre) y un Identificador (cadena única) para el pase. Tenga en cuenta que todos los identificadores de tipo de pase deben comenzar con la cadena pass. En este ejemplo se usa pass.com.xamarin.coupon.banana: Proporcionar una descripción e identificador

  3. Para confirmar el id. de pase, presione el botón Registrar.

Generar un certificado

Para crear un nuevo certificado para este identificador de tipo de pase, haga lo siguiente:

  1. Seleccione el id. de pase recién creado de la lista y haga clic en Editar: Seleccione el nuevo id. de pase de la lista

    A continuación, seleccione Crear certificado...:

    Seleccione Crear certificado

  2. Siga los pasos para crear una solicitud de firma de certificado (CSR).

  3. Presione el botón Continuar en el portal para desarrolladores y cargue la CSR para generar el certificado.

  4. Descargue el certificado y haga doble clic en él para instalarlo en la cadena de claves.

Ahora que hemos creado un certificado para este identificador de tipo de pase, en la sección siguiente se describe cómo compilar un pase manualmente.

Para obtener más información sobre el aprovisionamiento para Wallet, consulte la guía Trabajar con funcionalidades.

Crear un pase manualmente

Ahora que hemos creado el tipo de pase, podemos crear manualmente un pase para probarlo en el simulador o en un dispositivo. Los pasos para crear un pase son:

  • Cree un directorio para contener los archivos de pase.
  • Cree un archivo pass.json que contenga todos los datos necesarios.
  • Incluya imágenes en la carpeta (si es necesario).
  • Calcule los hash SHA1 para cada archivo de la carpeta y escriba en manifest.json.
  • Firme manifest.json con el archivo .p12 del certificado descargado.
  • Comprima el contenido del directorio y cambie el nombre por la extensión .pkpass.

Hay algunos archivos de código fuente en el código de ejemplo de este artículo que se pueden usar para generar un pase. Use los archivos en el directorio CouponBanana.raw del directorio CreateAPassManually. Los siguientes archivos están presentes:

Estos archivos están presentes

Abra pass.json y edite el archivo JSON. Debe actualizar al menos passTypeIdentifier y teamIdentifer para que coincidan con su cuenta de desarrollador de Apple.

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

A continuación, debe calcular los hashes de cada archivo y crear el archivo manifest.json. Tendrá un aspecto similar al siguiente cuando haya terminado:

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

A continuación, se debe generar una firma para este archivo mediante el certificado (archivo .p12) que se generó para este identificador de tipo de pase.

Iniciar sesión en un equipo Mac

Descargue los materiales de soporte técnico de inicialización de Wallet desde el sitio de descargas de Apple. Use la herramienta para convertir la carpeta signpass en un pase (esto también calculará los hash SHA1 y comprimirá la salida en un archivo .pkpass).

Prueba

Si desea examinar la salida de estas herramientas (estableciendo el nombre de archivo en .zip y, a continuación, abriéndolo), verá los siguientes archivos (tenga en cuenta la adición de los archivos manifest.json y signature):

Examen de la salida de estas herramientas

Una vez que haya firmado, comprimido y cambiado el nombre del archivo (por ejemplo, a BananaCoupon.pkpass) puede arrastrarlo al simulador para probarlo o enviarlo por correo electrónico para recuperarlo en un dispositivo real. Debería ver una pantalla para agregar el pase, como esta:

Agregar la pantalla de pase

Normalmente, ese proceso se automatizaría en un servidor, pero la creación manual de pases podría ser una opción para pequeñas empresas que solo crean cupones que no requieren la compatibilidad de un servidor back-end.

Cartera

Wallet es la pieza central del ecosistema de PassKit. En esta captura de pantalla se muestra la aplicación Wallet vacía y el aspecto de la lista de pases y los pases individuales:

En esta captura de pantalla se muestra la aplicación Wallet vacía y el aspecto de la lista de pases y los pases individuales

Las características de Wallet incluyen:

  • Es el único lugar donde se representan los pases con su código de barras para escanear.
  • El usuario puede cambiar la configuración de las actualizaciones. Si están habilitadas, las notificaciones push pueden desencadenar actualizaciones en los datos del pase.
  • El usuario puede habilitar o deshabilitar la integración de la pantalla de bloqueo. Si está habilitada, permite que el pase aparezca automáticamente en la pantalla de bloqueo, en función de los datos de tiempo y ubicación pertinentes insertados en el pase.
  • El lado inverso del pase admite la extracción para actualizar, si se proporciona una dirección URL de servidor web en el JSON de pase.
  • Las aplicaciones complementarias se pueden abrir (o descargar) si el identificador de la aplicación se proporciona en el JSON de pase.
  • Los pases se pueden eliminar (con una bonita animación de trituración).

Agregar pases a Wallet

Los pases se pueden agregar a Wallet de las maneras siguientes:

  • Aplicaciones de conducto: no manipulan pases directamente, simplemente cargan archivos de pase y presentan al usuario la opción de agregarlos a Wallet.

  • Aplicaciones complementarias: escritas por los proveedores para distribuir pases y ofrecen funcionalidad adicional para examinarlos o editarlos. Las aplicaciones de Xamarin.iOS tienen acceso completo a la API de PassKit para crear y manipular pases. A continuación, se pueden agregar pases a Wallet mediante PKAddPassesViewController. Este proceso se describe con más detalle en la sección Aplicaciones complementarias de este documento.

Aplicaciones de conducto

Las aplicaciones de conducto son aplicaciones intermedias que pueden recibir pases en nombre de un usuario, y deben programarse para reconocer su tipo de contenido y proporcionar funcionalidad para agregar a Wallet. Entre los ejemplos de aplicaciones de conducto se incluyen:

  • Correo: reconoce los datos adjuntos como un pase.
  • Safari: reconoce el tipo de contenido de pase cuando se hace clic en un vínculo de dirección URL de pase.
  • Otras aplicaciones personalizadas: cualquier aplicación que reciba datos adjuntos o vínculos abiertos (clientes de redes sociales, lectores de correo, etc.).

En esta captura de pantalla se muestra cómo Correo en iOS 6 reconoce un archivo adjunto de pase y (cuando se toca) ofrece realizar la acción de Agregar a Wallet.

En esta captura de pantalla se muestra cómo Correo en iOS 6 reconoce los datos adjuntos de pase

En esta captura de pantalla se muestra cómo Correo ofrece agregar datos adjuntos de pase a Wallet

Si va a crear una aplicación que podría ser un conducto para pases, se pueden reconocer mediante:

  • Extensión de archivo: .pkpass
  • Tipo MIME: application/vnd.apple.pkpass
  • UTI: com.apple.pkpass

El funcionamiento básico de una aplicación de conducto es recuperar el archivo de pase y llamar a PKAddPassesViewController de PassKit para dar al usuario la opción de agregar el pase a Wallet. La implementación de este controlador de vista se trata en la sección siguiente de Aplicaciones complementarias.

Las aplicaciones de conducto no necesitan aprovisionarse para un identificador de tipo de pase específico de la misma manera que lo hacen las aplicaciones complementarias.

Aplicaciones complementarias

Una aplicación complementaria proporciona funcionalidad adicional para trabajar con pases, incluida la creación de un pase, la actualización de información asociada a un pase y también la administración de pases asociados a la aplicación.

Las aplicaciones complementarias no deben intentar duplicar las características de Wallet. No están diseñadas para mostrar pases para escanear.

En el resto de esta sección se describe cómo crear una aplicación complementaria básica que interactúe con PassKit.

Aprovisionamiento

Dado que Wallet es una tecnología de tienda, la aplicación debe aprovisionarse por separado y no puede usar el perfil de aprovisionamiento de equipo o el identificador de aplicación comodín. Consulte la guía Trabajar con funcionalidades para crear un identificador de aplicación único y un perfil de aprovisionamiento para la aplicación Wallet.

Derechos

El archivo Entitlements.plist debe incluirse en todos los proyectos recientes de Xamarin.iOS. Para agregar un nuevo archivo Entitlements.plist, siga los pasos descritos en la guía Trabajar con derechos.

Para establecer derechos, haga lo siguiente:

Haga doble clic en el archivo Entitlements.plist del Panel de solución para abrir el editor de Entitlements.plist:

Editor Entitlements.plst

En la sección Wallet, seleccione la opción Habilitar Wallet

Habilitar derechos de cartera

La opción predeterminada es que la aplicación permita todos los tipos de pase. Sin embargo, es posible restringir la aplicación y permitir solo un subconjunto de tipos de pases de equipo. Para habilitar esta opción, seleccione Permitir subconjunto de tipos de pase de equipo y escriba el identificador de tipo de pase del subconjunto que desea permitir.

Depuración

Si tiene problemas para implementar la aplicación, compruebe que usa el Perfil de aprovisionamiento correcto y que Entitlements.plist está seleccionado como archivo de Derechos personalizados en las opciones de Firma de conjunto de iPhone.

Si experimenta este error al llevar a cabo la implementación:

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

significa que la matriz de derechos pass-type-identifiers es incorrecta (o no coincide con el Perfil de aprovisionamiento). Compruebe que los identificadores de tipo de pase y el identificador de equipo sean correctos.

Clases

Las siguientes clases de PassKit están disponibles para que las aplicaciones accedan a los pases:

  • PKPass: una instancia de un pase.
  • PKPassLibrary: proporciona a la API acceso a los pases en el dispositivo.
  • PKAddPassesViewController: se usa para mostrar un pase para que el usuario lo guarde en Wallet.
  • PKAddPassesViewControllerDelegate: desarrolladores de Xamarin.iOS

Ejemplo

Consulte el proyecto PassLibrary en el ejemplo de este artículo. Muestra las siguientes funciones comunes que serían necesarias en una aplicación complementaria de Wallet:

Compruebe que Wallet está disponible

Wallet no está disponible en el iPad, por lo que las aplicaciones deben comprobar su disponibilidad antes de intentar acceder a las características de PassKit.

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

Creación de una instancia de biblioteca de pases

La biblioteca de PassKit no es un singleton, las aplicaciones deben crearse, almacenarse y generarse instancias de ellas para acceder a la API de PassKit.

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

Obtener una lista de pases

Las aplicaciones pueden solicitar una lista de pases de la biblioteca. PassKit filtra automáticamente esta lista para que solo pueda ver los pases que se han creado con el identificador de equipo y que aparecen en los derechos.

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

Tenga en cuenta que el simulador no filtra la lista de pases devueltos, por lo que este método siempre debe probarse en dispositivos reales. Esta lista se puede mostrar en uiTableView. La aplicación de ejemplo tiene este aspecto después de agregarse dos cupones:

La aplicación de ejemplo tiene este aspecto después de agregarse dos cupones

Mostrar pases

Hay disponible un conjunto limitado de información para la representación de pases dentro de las aplicaciones complementarias.

Elija entre este conjunto de propiedades estándar para mostrar listas de pases, como hace el código de ejemplo.

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

Esta cadena se muestra como una alerta en el ejemplo:

Alerta seleccionada del cupón en el ejemplo

También puede usar el método LocalizedValueForFieldKey() para recuperar datos de los campos de los pases que ha diseñado (ya que sabrá qué campos deben estar presentes). El código de ejemplo no lo muestra.

Cargar un pase desde un archivo

Dado que un pase solo se puede agregar a Wallet con el permiso del usuario, se debe presentar un controlador de vista para dejar que decidan. Este código se usa en el botón Agregar del ejemplo para cargar un pase precompilado que se inserte en la aplicación (debe reemplazarlo por uno que haya firmado):

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);

El pase se presenta con las opciones Agregar y Cancelar:

El pase presentado con las opciones Agregar y Cancelar

Reemplazar un pase existente

Reemplazar un pase existente no requiere el permiso del usuario, pero se producirá un error si el pase aún no existe.

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

Editar un pase

PKPass no es mutable, por lo que no se pueden actualizar los objetos de pase en el código. Para modificar los datos de un pase, una aplicación debe tener acceso a un servidor web que pueda conservar un registro de pases y generar un nuevo archivo de pase con valores actualizados que la aplicación pueda descargar.

La creación de archivos de pase debe realizarse en un servidor porque los pases deben estar firmados con un certificado que se debe mantener privado y seguro.

Una vez generado un archivo de pase actualizado, use el método Replace para sobrescribir los datos antiguos en el dispositivo.

Mostrar un pase para escanearlo

Como se indicó anteriormente, solo Wallet puede mostrar un pase para escanearlo. Se puede mostrar un pase mediante el método OpenUrl tal y como se muestra:

UIApplication.SharedApplication.OpenUrl (p.PassUrl);

Recibir notificaciones de cambios

Las aplicaciones pueden escuchar los cambios realizados en la biblioteca de pases mediante PKPassLibraryDidChangeNotification. Los cambios pueden deberse a que las notificaciones desencadenan actualizaciones en segundo plano, por lo que es recomendable escucharlas en la aplicación.

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

Es importante pasar una instancia de biblioteca al registrarse para la notificación porque PKPassLibrary no es un singleton.

Procesamiento del servidor

Una explicación detallada de la creación de una aplicación de servidor para admitir PassKit queda fuera del ámbito de este artículo introductorio.

Consulte el código de lado servidor de C# de código abierto de dotnet-passbook.

Notificaciones de inserción

Una explicación detallada del uso de notificaciones push para actualizar pases queda fuera del ámbito de este artículo introductorio.

Se le pedirá que implemente la API similar a REST definida por Apple para responder a las solicitudes web de Wallet cuando se requieran actualizaciones.

Para obtener más información, consulte la guía de Apple para Actualizar un pase.

Resumen

En este artículo se ha presentado PassKit, se han descrito algunas de las razones por las que resulta útil y las distintas partes que se deben implementar para una solución de PassKit completa. Se describen los pasos necesarios para configurar la cuenta de desarrollador de Apple para crear pases, el proceso para realizar un pase manualmente y también cómo acceder a las API de PassKit desde una aplicación de Xamarin.iOS.