PassKit in Xamarin.iOS

L'app Portafoglio iOS consente agli utenti di archiviare i passaggi digitali sui propri dispositivi. Questi passaggi vengono generati dai commercianti e inviati al cliente tramite posta elettronica, URL o tramite l'app iOS del commerciante. Questi pass possono rappresentare varie cose, dai biglietti del cinema alle carte fedeltà alle carte d'imbarco. Il framework PassKit consente agli sviluppatori di interagire con i passaggi a livello di codice.

Questo documento presenta Wallet e usa l'API PassKit con Xamarin.iOS.

Requisiti

Le funzionalità passkit descritte in questo documento richiedono iOS 6 e Xcode 4.5, insieme a Xamarin.iOS 6.0.

Introduzione

Il problema chiave risolto da PassKit è la distribuzione e la gestione dei codici a barre. Alcuni esempi reali di utilizzo dei codici a barre includono:

• Acquisto di biglietti per film online : i clienti vengono in genere inviati tramite posta elettronica a un codice a barre che rappresenta i biglietti. Questo codice a barre viene stampato e portato al cinema per essere analizzato per l'immissione.
• Carte fedeltà: i clienti portano una serie di carte specifiche del negozio nel portafoglio o nella borsa, per la visualizzazione e la scansione quando acquistano merci.
• Coupon : i coupon vengono distribuiti tramite posta elettronica, come pagine Web stampabili, tramite caselle di lettere e come codici a barre su giornali e riviste. I clienti li portano in un negozio per la scansione, per ricevere merci, servizi o sconti in cambio.
• Carte d'imbarco: simile all'acquisto di un biglietto cinematografico.

PassKit offre un'alternativa per ognuno di questi scenari:

• Biglietti per i film : dopo l'acquisto, il cliente aggiunge un biglietto evento (tramite posta elettronica o un collegamento al sito Web). Come il tempo per il film si avvicina, il pass apparirà automaticamente sulla schermata di blocco come promemoria, e all'arrivo al cinema il pass è facilmente recuperato e visualizzato in Portafoglio per la scansione.
• Carte fedeltà: anziché (o oltre a) fornire una carta fisica, i negozi possono emettere (tramite posta elettronica o dopo l'accesso a un sito Web) un pass per le carte del negozio. L'archivio può fornire funzionalità aggiuntive, ad esempio l'aggiornamento del saldo dell'account sul pass tramite notifiche push e l'uso dei servizi di georilevazione, il passaggio potrebbe apparire automaticamente nella schermata di blocco quando il cliente si trova vicino a una posizione del negozio.
• Coupon : i coupon possono essere facilmente generati con caratteristiche uniche per facilitare il rilevamento e distribuiti tramite e-mail o collegamenti al sito Web. I coupon scaricati possono essere visualizzati automaticamente nella schermata di blocco quando l'utente si trova vicino a una posizione specifica e/o in una determinata data (ad esempio quando si avvicina la data di scadenza). Poiché i coupon vengono archiviati sul telefono dell'utente, sono sempre utili e non vengono spostati in modo sbagliato. I coupon potrebbero incoraggiare i clienti a scaricare le app complementari perché i collegamenti di App Store possono essere incorporati nel pass, aumentando il coinvolgimento con il cliente.
• Carte d'imbarco: dopo un processo di check-in online, il cliente riceverà il pass di imbarco tramite posta elettronica o un collegamento. Un'app complementare fornita dal provider di trasporto può includere il processo di archiviazione e consentire al cliente di eseguire funzioni aggiuntive come la scelta del posto o del pasto. Il provider di trasporto può usare le notifiche push per aggiornare il passaggio se il trasporto è ritardato o annullato. Quando il tempo di imbarco si avvicina al pass verrà visualizzato nella schermata di blocco come promemoria e per fornire accesso rapido al pass.

Al suo centro, PassKit offre un modo semplice e pratico per archiviare e visualizzare codici a barre nel dispositivo iOS. Con l'integrazione aggiuntiva della schermata di blocco della posizione, le notifiche push e l'applicazione complementare lo integrano offre una base per vendite, ticket e servizi di fatturazione molto sofisticati.

Ecosistema PassKit

PassKit non è solo un'API all'interno di CocoaTouch, ma fa parte di un ampio ecosistema di app, dati e servizi che facilitano la condivisione sicura e la gestione dei codici a barre e di altri dati. Questo diagramma generale illustra le diverse entità che possono essere coinvolte nella creazione e nell'uso dei passaggi:

Ogni parte dell'ecosistema ha un ruolo chiaramente definito:

• Wallet : app iOS predefinita di Apple che archivia e visualizza i passaggi. Questo è l'unico luogo in cui viene eseguito il rendering dei passaggi per l'uso nel mondo reale (ad esempio, viene visualizzato il codice a barre, insieme a tutti i dati localizzati nel passaggio).
• App complementari: le app iOS 6 create dai provider pass per estendere le funzionalità dei passaggi che rilasciano, ad esempio aggiungendo valore a una scheda negozio, modificando il posto su una carta d'imbarco o altre funzioni specifiche dell'azienda. Le app complementari non sono necessarie per un passaggio per essere utili.
• Il server : un server sicuro in cui i passaggi possono essere generati e firmati per la distribuzione. L'app complementare può connettersi al server per generare nuovi passaggi o richiedere aggiornamenti ai passaggi esistenti. Facoltativamente, è possibile implementare l'API del servizio Web che Wallet chiamerebbe per i passaggi di aggiornamento.
• Server APNS: il server ha la possibilità di notificare a Portafoglio gli aggiornamenti a un determinato dispositivo tramite APNS. Effettuare il push di una notifica al portafoglio che contatterà il server per informazioni dettagliate sulla modifica. Le app complementari non devono implementare APNS per questa funzionalità (possono restare in ascolto di PKPassLibraryDidChangeNotification ).
• App conduit: applicazioni che non modificano direttamente i passaggi (come le app complementari), ma che possono migliorare la loro utilità riconoscendo i passaggi e consentendo loro di essere aggiunti a Wallet. I client di posta, i browser di social network e altre app di aggregazione dati possono tutti incontrare allegati o collegamenti da passare.

L'intero ecosistema sembra complesso, quindi vale la pena notare che alcuni componenti sono facoltativi e implementazioni PassKit molto più semplici sono possibili.

Che cos'è un pass?

Un pass è una raccolta di dati che rappresentano un ticket, un coupon o una carta. Può essere destinato a un singolo utilizzo da parte di un individuo (e pertanto contenere dettagli come un numero di volo e l'allocazione di posti) oppure può essere un token di utilizzo multiplo che può essere condiviso da un numero qualsiasi di utenti (ad esempio un coupon di sconto). Una descrizione dettagliata è disponibile nel documento About Pass Files di Apple.

Tipi

Attualmente cinque tipi supportati, che possono essere distinti nell'app Portafoglio in base al layout e al bordo superiore del passaggio:

• Ticket evento : piccolo cutout semicirculare.
• Pass d'imbarco: è possibile specificare l'icona specifica del trasporto ( ad esempio bus, treno, aereo).
• Carta store: arrotondata in alto, ad esempio una carta di credito o di debito.
• Cedola – forata lungo la parte superiore.
• Generico : uguale a Store Card, arrotondato in alto.

I cinque tipi di pass sono visualizzati in questo screenshot (in ordine: coupon, generico, carta di negozio, pass d'imbarco ed evento):

Struttura del file

Un file pass è in realtà un archivio ZIP con estensione pkpass , contenente alcuni file JSON specifici (obbligatori), un'ampia gamma di file di immagine (facoltativi) e stringhe localizzate (facoltativo).

• pass.json: obbligatorio. Contiene tutte le informazioni per il passaggio.
• manifest.json: obbligatorio. Contiene hash SHA1 per ogni file nel passaggio, ad eccezione del file di firma e del file (manifest.json).
• signature : obbligatorio. Creato firmando il manifest.json file con il certificato generato nel portale di provisioning iOS.
• logo.png: facoltativo.
• background.png : facoltativo.
• icon.png: facoltativo.
• File di stringhe localizzabili: facoltativo.

La struttura di directory di un file pass è illustrata di seguito (si tratta del contenuto dell'archivio ZIP):

pass.json

JSON è il formato perché i passaggi vengono in genere creati in un server, ovvero il codice di generazione è indipendente dalla piattaforma nel server. Le tre informazioni chiave in ogni passaggio sono:

• teamIdentifier : consente di collegare tutti i passaggi generati all'account dell'App Store. Questo valore è visibile nel portale di provisioning iOS.
• passTypeIdentifier : eseguire la registrazione nel portale di provisioning per raggruppare i passaggi (se si producono più tipi). Ad esempio, un bar potrebbe creare un tipo di pass di carta negozio per consentire ai clienti di guadagnare crediti fedeltà, ma anche un tipo di pass coupon separato per creare e distribuire coupon. La stessa caffetteria potrebbe anche contenere eventi musicali dal vivo e rilasciare i biglietti evento per quelli.
• serialNumber : stringa univoca all'interno di questo passTypeidentifier oggetto . Il valore è opaco per Portafoglio, ma è importante per tenere traccia di passaggi specifici durante la comunicazione con il server.

In ogni passaggio è presente un numero elevato di altre chiavi JSON, un esempio di cui è illustrato di seguito:

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

Codici a barre

Sono supportati solo i formati 2D: PDF417, Azteco, QR. Apple sostiene che i codici a barre 1D non sono adatti alla scansione su uno schermo del telefono nascosto.

Testo alternativo visualizzato sotto il codice a barre è facoltativo: alcuni commercianti vogliono essere in grado di leggere/digitare manualmente.

La codifica ISO-8859-1 è la più comune, verificare quale codifica viene usata dai sistemi di analisi che leggeranno i passaggi.

Pertinenza (schermata di blocco)

Esistono due tipi di dati che possono causare la visualizzazione di un passaggio nella schermata di blocco:

Location

È possibile specificare fino a 10 posizioni in un pass, ad esempio i negozi che un cliente visita frequentemente o la posizione di un cinema o di un aeroporto. Un cliente può impostare queste posizioni tramite un'app complementare o il provider potrebbe determinarli dai dati di utilizzo (se raccolti con l'autorizzazione del cliente).

Quando il passaggio viene visualizzato nella schermata di blocco, viene calcolato un recinto in modo che quando l'utente esce dall'area il passaggio è nascosto dalla schermata di blocco. Il raggio è associato al passaggio dello stile per prevenire l'abuso.

Data e ora

È possibile specificare una sola data/ora in un pass. La data e l'ora sono utili per attivare i promemoria della schermata di blocco per le carte d'imbarco e i biglietti di evento.

Può essere aggiornato tramite push o tramite l'API PassKit, in modo che la data/ora possa essere aggiornata nel caso di un biglietto multiuso (ad esempio un biglietto di stagione per un teatro o un complesso sportivo).

Localizzazione

La traduzione di un passaggio in più lingue è simile alla localizzazione di un'applicazione iOS: creare directory specifiche della lingua con l'estensione .lproj e posizionare gli elementi localizzati all'interno. Le traduzioni di testo devono essere immesse in un pass.strings file, mentre le immagini localizzate devono avere lo stesso nome dell'immagine che sostituiscono nella radice Pass.

Sicurezza

I passaggi vengono firmati con un certificato privato generato nel portale di provisioning iOS. I passaggi per firmare il pass sono:

1. Calcolare un hash SHA1 per ogni file nella directory pass (non includere il manifest.json file o signature , nessuno dei quali deve esistere comunque in questa fase).
2. Scrivere manifest.json come elenco chiave/valore JSON di ogni nome file con il relativo hash.
3. Usare il certificato per firmare il manifest.json file e scrivere il risultato in un file denominato signature .
4. Comprimere tutto il contenuto e assegnare al file risultante un'estensione .pkpass di file.

Poiché la chiave privata è necessaria per firmare il passaggio, questo processo deve essere eseguito solo in un server sicuro controllato. NON distribuire le chiavi per provare a generare passaggi in un'applicazione.

Installazione e configurazione

Questa sezione contiene istruzioni per configurare i dettagli del provisioning e creare il primo passaggio.

Provisioning PassKit

Affinché un passaggio entri nell'App Store, deve essere collegato a un account per sviluppatore. Questa operazione richiede due passaggi:

1. Il pass deve essere registrato usando un identificatore univoco, denominato ID tipo pass.
2. Per firmare il passaggio con la firma digitale dello sviluppatore, è necessario generare un certificato valido.

Per creare un ID tipo di passaggio, eseguire le operazioni seguenti.

Creare un ID tipo di passaggio

Il primo passaggio consiste nel configurare un ID tipo pass per ogni tipo di passaggio diverso da supportare. L'ID pass (o pass type identifier) crea un identificatore univoco per il pass. Questo ID verrà usato per collegare il pass con l'account sviluppatore usando un certificato.

1. Nella sezione Certificati, identificatori e profili del portale di provisioning iOS passare a Identificatori e selezionare Passa ID tipo . Selezionare quindi il + pulsante per creare un nuovo tipo di passaggio:

2. Specificare una descrizione (nome) e un identificatore (stringa univoca) per il pass. Si noti che tutti gli ID di tipo pass devono iniziare con la stringa pass. In questo esempio viene usato pass.com.xamarin.coupon.banana :

3. Confermare l'ID pass premendo il pulsante Registra .

Generare un certificato

Per creare un nuovo certificato per questo ID tipo di passaggio, eseguire le operazioni seguenti:

1. Selezionare l'ID pass appena creato dall'elenco e fare clic su Modifica :

   Selezionare quindi Crea certificato... :

   

2. Seguire la procedura per creare una richiesta di firma del certificato (CSR).

3. Premere il pulsante Continua nel portale per sviluppatori e caricare la richiesta di firma del certificato per generare il certificato.

4. Scaricare il certificato e fare doppio clic su di esso per installarlo nel keychain.

Ora che è stato creato un certificato per questo ID tipo di passaggio, la sezione successiva descrive come compilare manualmente un passaggio.

Per altre informazioni sul provisioning per Portafoglio, vedere la guida Uso delle funzionalità .

Creare manualmente un passaggio

Ora che è stato creato il tipo di passaggio, è possibile creare manualmente un passaggio per il test nel simulatore o in un dispositivo. I passaggi per creare un passaggio sono i seguenti:

• Creare una directory per contenere i file pass.
• Creare un file pass.json contenente tutti i dati necessari.
• Includere immagini nella cartella (se necessario).
• Calcolare gli hash SHA1 per ogni file nella cartella e scrivere in manifest.json.
• Firmare manifest.json con il file con estensione p12 del certificato scaricato.
• Comprimere il contenuto della directory e rinominarlo con l'estensione pkpass.

Nel codice di esempio per questo articolo sono presenti alcuni file di origine che possono essere usati per generare un passaggio. Usare i file nella CouponBanana.raw directory della directory CreateAPassManually. Sono presenti i file seguenti:

Aprire pass.json e modificare il codice JSON. È necessario aggiornare almeno e teamIdentifer in modo che corrisponda all'account passTypeIdentifier Apple Developer.

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

È quindi necessario calcolare gli hash per ogni file e creare il manifest.json file. Al termine, l'aspetto sarà simile al seguente:

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

Successivamente, è necessario generare una firma per questo file usando il certificato (file con estensione p12) generato per questo ID di tipo pass.

Firma in un Mac

Scaricare i materiali di supporto per il seeding del portafoglio dal sito dei download apple. Usare lo signpass strumento per trasformare la cartella in un passaggio (verranno calcolati anche gli hash SHA1 e comprimere l'output in un file pkpass).

Test

Se si desidera esaminare l'output di questi strumenti (impostando il nome file su .zip e quindi aprendolo), verranno visualizzati i file seguenti (si noti l'aggiunta dei manifest.json file e signature ):

Dopo aver firmato, compresso e rinominato il file (ad esempio BananaCoupon.pkpassin ) è possibile trascinarlo nel simulatore per testarlo o inviare un messaggio di posta elettronica a se stessi per recuperarlo in un dispositivo reale. Verrà visualizzata una schermata per aggiungere il passaggio, come illustrato di seguito:

In genere tale processo verrebbe automatizzato in un server, tuttavia la creazione manuale del passaggio potrebbe essere un'opzione per le piccole imprese che creano solo coupon che non richiedono il supporto di un server back-end.

Portafoglio

Wallet è il pezzo centrale dell'ecosistema PassKit. Questo screenshot mostra il portafoglio vuoto e l'aspetto dell'elenco dei passaggi e dei singoli passaggi:

Le funzionalità di Portafoglio includono:

• È l'unico luogo in cui viene eseguito il rendering dei passaggi con il codice a barre per la scansione.
• L'utente può modificare le impostazioni per gli aggiornamenti. Se abilitata, le notifiche push possono attivare gli aggiornamenti ai dati nel passaggio.
• L'utente può abilitare o disabilitare l'integrazione della schermata di blocco. Se abilitata, in questo modo il passaggio viene visualizzato automaticamente nella schermata di blocco, in base ai dati relativi all'ora e alla posizione incorporati nel passaggio.
• Il lato inverso del passaggio supporta l'aggiornamento pull-to-refresh, se viene fornito un URL web-server nel passaggio JSON.
• Le app complementari possono essere aperte (o scaricate) se l'ID dell'app viene fornito nel pass JSON.
• I passaggi possono essere eliminati (con un'animazione carina di shredding).

Aggiunta di pass al portafoglio

I pass possono essere aggiunti al Portafoglio nei modi seguenti:

• App conduit: queste non manipolano direttamente i passaggi, caricano semplicemente i file di passaggio e presentano all'utente la possibilità di aggiungerli al portafoglio.

• App complementari: vengono scritte dai provider per distribuire i passaggi e offrire funzionalità aggiuntive per esplorarle o modificarle. Le applicazioni Xamarin.iOS hanno accesso completo all'API PassKit per creare e modificare i passaggi. I pass possono quindi essere aggiunti al portafoglio utilizzando .PKAddPassesViewController Questo processo è descritto in modo più dettagliato nella sezione Applicazioni complementari di questo documento.

Applicazioni conduit

Le applicazioni conduit sono app intermedie che potrebbero ricevere passaggi per conto di un utente e devono essere programmate per riconoscere il tipo di contenuto e fornire funzionalità da aggiungere al portafoglio. Esempi di app conduit includono:

• Mail: riconosce gli allegati come pass.
• Safari : riconosce il pass Content-Type quando si fa clic su un collegamento pass URL.
• Altre app personalizzate: qualsiasi app che riceve allegati o collegamenti aperti (client di social media, lettori di posta elettronica e così via).

Questo screenshot mostra come Mail in iOS 6 riconosce un allegato di passaggio e (quando toccato) offerte per Aggiungerlo al portafoglio.

Se stai creando un'app che potrebbe essere un canale per i passaggi, possono essere riconosciuti da:

• Estensione del file - pkpass
• Tipo MIME - application/vnd.apple.pkpass
• UTI – com.apple.pkpass

L'operazione di base di un'applicazione conduit consiste nel recuperare il file pass e chiamare PassKit PKAddPassesViewController per dare all'utente la possibilità di aggiungere il pass al proprio Portafoglio. L'implementazione di questo controller di visualizzazione è illustrata nella sezione successiva sulle applicazioni complementari.

Non è necessario effettuare il provisioning delle applicazioni conduit per un ID di tipo pass specifico nello stesso modo in cui le applicazioni complementari fanno.

Applicazioni complementari

Un'applicazione complementare offre funzionalità aggiuntive per l'uso dei passaggi, inclusa la creazione di un passaggio, l'aggiornamento delle informazioni associate a un pass e la gestione di passaggi associati all'applicazione.

Le applicazioni complementari non devono tentare di duplicare le funzionalità di Wallet. Non sono destinati a visualizzare i passaggi per l'analisi.

Questa parte restante di questa sezione descrive come creare un'app complementare di base che interagisce con PassKit.

Provisioning in corso

Poiché Wallet è una tecnologia di store, è necessario effettuare il provisioning dell'applicazione separatamente e non può usare il profilo di provisioning del team o l'ID app con caratteri jolly. Fare riferimento alla guida Uso delle funzionalità per creare un ID app univoco e un profilo di provisioning per l'applicazione Wallet.

Diritti

Il file Entitlements.plist deve essere incluso in tutti i progetti Xamarin.iOS recenti. Per aggiungere un nuovo file Entitlements.plist, seguire la procedura descritta nella guida Uso dei diritti .

Per impostare i diritti, eseguire le operazioni seguenti:

Debug

Se si verificano problemi durante la distribuzione dell'applicazione, verificare di usare il profilo di provisioning corretto e che Entitlements.plist sia selezionato come file entitlement personalizzati nelle opzioni di firma del bundle iPhone.

Se si verifica questo errore durante la distribuzione:

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

quindi la pass-type-identifiers matrice entitlements non è corretta (o non corrisponde al profilo di provisioning). Verificare che gli ID tipo di passaggio e l'ID del team siano corretti.

Classi

Le classi PassKit seguenti sono disponibili per consentire alle app di accedere ai passaggi:

• PKPass : istanza di un pass.
• PKPassLibrary : fornisce l'API per accedere ai passaggi nel dispositivo.
• PKAddPassesViewController : usato per visualizzare un pass per consentire all'utente di salvare nel portafoglio.
• PKAddPassesViewControllerDelegate : sviluppatori Xamarin.iOS

Esempio

Fare riferimento al progetto PassLibrary nell'esempio per questo articolo. Illustra le seguenti funzioni comuni che sarebbero necessarie in un'applicazione complementare portafoglio:

Verificare che Portafoglio sia disponibile

Portafoglio non è disponibile nell'iPad, quindi le applicazioni devono controllare prima di tentare di accedere alle funzionalità passkit.

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

Creazione di un'istanza di libreria pass

La libreria PassKit non è un singleton, le applicazioni devono creare e archiviare e istanza per accedere all'API PassKit.

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

Ottenere un elenco di passaggi

Le applicazioni possono richiedere un elenco di passaggi dalla libreria. Questo elenco viene filtrato automaticamente in base a PassKit, in modo che sia possibile visualizzare solo i passaggi creati con l'ID team e che sono elencati nei diritti.

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

Si noti che il simulatore non filtra l'elenco dei passaggi restituiti, quindi questo metodo deve essere sempre testato nei dispositivi reali. Questo elenco può essere visualizzato in un oggetto UITableView. L'app di esempio è simile alla seguente dopo l'aggiunta di due coupon:

Visualizzazione dei passaggi

È disponibile un set limitato di informazioni per il rendering dei passaggi all'interno delle app complementari.

Scegliere da questo set di proprietà standard per visualizzare elenchi di passaggi, come avviee nel codice di esempio.

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

Questa stringa viene visualizzata come avviso nell'esempio:

È anche possibile usare il LocalizedValueForFieldKey() metodo per recuperare i dati dai campi nei passaggi progettati (poiché si saprà quali campi devono essere presenti). Il codice di esempio non visualizza questo valore.

Caricamento di un passaggio da un file

Poiché un pass può essere aggiunto solo a Wallet con l'autorizzazione dell'utente, è necessario presentare un controller di visualizzazione per consentire loro di decidere. Questo codice viene usato nel pulsante Aggiungi nell'esempio per caricare un passaggio predefinito incorporato nell'app (è necessario sostituirlo con quello firmato):

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

Il pass viene presentato con le opzioni Aggiungi e Annulla :

Sostituire un passaggio esistente

La sostituzione di un passaggio esistente non richiede l'autorizzazione dell'utente, ma avrà esito negativo se il passaggio non esiste già.

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

Modifica di un passaggio

PKPass non è modificabile, quindi non è possibile aggiornare gli oggetti passati nel codice. Per modificare i dati in un passaggio, un'applicazione deve avere accesso a un server Web in grado di mantenere un record di passaggi e generare un nuovo file pass con valori aggiornati che l'applicazione può scaricare.

La creazione di file pass deve essere eseguita in un server perché i passaggi devono essere firmati con un certificato che deve essere mantenuto privato e sicuro.

Dopo aver generato un file pass aggiornato, usare il Replace metodo per sovrascrivere i dati precedenti nel dispositivo.

Visualizzare un pass per l'analisi

Come indicato in precedenza, solo Portafoglio può visualizzare un pass per l'analisi. È possibile visualizzare un pass usando il OpenUrl metodo , come illustrato di seguito:

UIApplication.SharedApplication.OpenUrl (p.PassUrl);

Ricezione di notifiche di modifiche

Le applicazioni possono restare in ascolto delle modifiche apportate alla libreria pass usando .PKPassLibraryDidChangeNotification Le modifiche potrebbero essere causate da notifiche che attivano aggiornamenti in background, quindi è consigliabile ascoltarli nell'app.

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 passare un'istanza di libreria durante la registrazione per la notifica perché PKPassLibrary non è un singleton.

Elaborazione server

Una descrizione dettagliata della creazione di un'applicazione server per supportare PassKit non rientra nell'ambito di questo articolo introduttivo.

Vedere codice C# open source dotnet-passbook sul lato server.

Notifiche push

Una discussione dettagliata sull'uso delle notifiche push per i passaggi di aggiornamento non rientra nell'ambito di questo articolo introduttivo.

È necessario implementare l'API simile a REST definita da Apple per rispondere alle richieste Web da Wallet quando sono necessari aggiornamenti.

Per altre informazioni, vedere la Guida all'aggiornamento di un pass di Apple.

Riepilogo

Questo articolo ha introdotto PassKit, descritto alcuni dei motivi per cui è utile e descritto le diverse parti che devono essere implementate per una soluzione PassKit completa. Descrive i passaggi necessari per configurare l'account Apple Developer per creare passaggi, il processo per eseguire un passaggio manualmente e come accedere alle API PassKit da un'applicazione Xamarin.iOS.

Collegamenti correlati

• Portafoglio per sviluppatori
• Guida per gli sviluppatori di Portafoglio
• Framework - Apple Pay and Wallet (video WWDC)
• Informazioni di riferimento sul framework PassKit
• Informazioni di riferimento sul servizio Web Passbook
• Informazioni sul passaggio di file
• dotnet-passbook, una libreria open source per la generazione di pacchetti portafogli iOS
• Introduzione a iOS 6