Zestaw passkit w środowisku Xamarin.iOS

Artykuł
03/05/2024

Aplikacja Portfel systemu iOS umożliwia użytkownikom przechowywanie cyfrowych przejść na swoich urządzeniach. Te przepustki są generowane przez handlowców i wysyłane do klienta za pośrednictwem poczty e-mail, adresów URL lub własnej aplikacji dla sprzedawcy dla systemu iOS. Te przepustki mogą reprezentować różne rzeczy, od biletów filmowych do kart lojalnościowych do kart pokładowych. Platforma PassKit umożliwia deweloperom interakcję z przekazywaniem programowo.

W tym dokumencie przedstawiono aplikację Wallet i używanie interfejsu API PassKit z platformą Xamarin.iOS.

Wymagania

Funkcje zestawu PassKit omówione w tym dokumencie wymagają systemów iOS 6 i Xcode 4.5 wraz z platformą Xamarin.iOS 6.0.

Wprowadzenie

Kluczowym problemem, który rozwiązuje PassKit, jest dystrybucja kodów kreskowych i zarządzanie nimi. Oto kilka rzeczywistych przykładów użycia kodów kreskowych:

Kupowanie biletów filmowych online — klienci zazwyczaj wysyłają pocztą e-mail kod kreskowy reprezentujący swoje bilety. Ten kod kreskowy jest drukowany i przewieziony do kina do skanowania pod kątem wpisu.
Karty lojalnościowe — klienci noszą wiele różnych kart specyficznych dla sklepu w portfelu lub torebki do wyświetlania i skanowania podczas zakupu towarów.
Kupony — kupony są dystrybuowane za pośrednictwem poczty e-mail, jako drukowalnych stron internetowych, za pośrednictwem skrzynek pocztowych i jako kodów kreskowych w gazetach i magazynach. Klienci przynoszą je do sklepu do skanowania, aby otrzymywać towary, usługi lub rabaty w zamian.
Wejścia na pokład – podobnie jak zakup biletu filmowego.

Zestaw PassKit oferuje alternatywę dla każdego z tych scenariuszy:

Bilety filmowe — po zakupie klient dodaje bilet zdarzeń (za pośrednictwem poczty e-mail lub linku do witryny internetowej). W miarę zbliżania się czasu na film, przepustka będzie automatycznie wyświetlana na ekranie blokady jako przypomnienie, a po przybyciu do kina przepustka jest łatwo pobierana i wyświetlana w Portfelu do skanowania.
Karty lojalnościowe — zamiast (lub oprócz) dostarczania karty fizycznej, sklepy mogą wystawiać (za pośrednictwem poczty e-mail lub po zalogowaniu się do witryny internetowej) kartę sklepu. Sklep może udostępniać dodatkowe funkcje, takie jak aktualizowanie salda konta w ramach przekazywania za pośrednictwem powiadomień wypychanych, a korzystanie z usług geolokalizacji może automatycznie pojawić się na ekranie blokady, gdy klient znajduje się w pobliżu lokalizacji sklepu.
Kupony — kupony można łatwo wygenerować z unikatowymi cechami, aby pomóc w śledzeniu i dystrybuowaniu za pośrednictwem poczty e-mail lub linków do witryn internetowych. Pobrane kupony mogą być automatycznie wyświetlane na ekranie blokady, gdy użytkownik znajduje się w pobliżu określonej lokalizacji i/lub w danej dacie (np. gdy zbliża się data wygaśnięcia). Ponieważ kupony są przechowywane na telefonie użytkownika, są zawsze przydatne i nie są zagubione. Kupony mogą zachęcić klientów do pobierania aplikacji towarzyszących, ponieważ linki ze sklepu App Store można włączyć do aplikacji Pass, zwiększając zaangażowanie klienta.
Przekazywanie na pokład — po zakończeniu procesu ewidencjonowania online klient otrzyma dostęp do wejścia na pokład za pośrednictwem poczty e-mail lub linku. Aplikacja pomocnika dostarczana przez dostawcę transportu może obejmować proces ewidencjonowania, a także umożliwić klientowi wykonywanie dodatkowych funkcji, takich jak wybór miejsca lub posiłku. Dostawca transportu może użyć powiadomień wypychanych, aby zaktualizować przepustkę, jeśli transport jest opóźniony lub anulowany. W miarę zbliżania się czasu wejścia do przejścia na ekranie blokady jako przypomnienia i zapewnienia szybkiego dostępu do passa.

Zestaw PassKit zapewnia prosty i wygodny sposób przechowywania i wyświetlania kodów kreskowych na urządzeniu z systemem iOS. Dzięki dodatkowej integracji ekranu blokady i lokalizacji powiadomienia wypychane i aplikacja pomocnika integrują ją z bardzo zaawansowanymi usługami sprzedaży, biletów i rozliczeń.

Ekosystem zestawu PassKit

PassKit nie jest tylko interfejsem API w usłudze CocoaTouch, a raczej jest częścią większego ekosystemu aplikacji, danych i usług, które ułatwiają bezpieczne udostępnianie kodów kreskowych i innych danych oraz zarządzanie nimi. Ten ogólny diagram przedstawia różne jednostki, które mogą być zaangażowane w tworzenie i używanie przebiegów:

Każdy element ekosystemu ma jasno zdefiniowaną rolę:

Portfel — wbudowana aplikacja systemu iOS firmy Apple, która przechowuje i wyświetla przechodzi. Jest to jedyne miejsce, w których przekazywane są renderowane do użytku w świecie rzeczywistym (tj. kod kreskowy jest wyświetlany wraz ze wszystkimi zlokalizowanymi danymi w przekazaniu).
Aplikacje towarzyszące — aplikacje dla systemu iOS 6 utworzone przez dostawców przekazywania w celu rozszerzenia funkcjonalności przekazywanych, takich jak dodanie wartości do karty sklepu, zmiana miejsca na wejściu na pokład lub innej funkcji specyficznej dla firmy. Aplikacje towarzyszące nie są wymagane, aby przekazywanie było przydatne.
Serwer — bezpieczny serwer , na którym można wygenerować i podpisać przekazywanie na potrzeby dystrybucji. Aplikacja pomocnika może nawiązać połączenie z serwerem, aby wygenerować nowe przebiegi lub zażądać aktualizacji istniejących przebiegów. Opcjonalnie możesz zaimplementować interfejs API usługi internetowej, który portfel wywoła, aby zaktualizować przebiegi.
Serwery USŁUGI APNS — Serwer ma możliwość powiadamiania portfela o aktualizacjach w celu przekazania danych na danym urządzeniu przy użyciu usługi APNS. Wypchnij powiadomienie do portfela, które następnie skontaktuje się z serwerem, aby uzyskać szczegółowe informacje o zmianie. Aplikacje towarzyszące nie muszą implementować usługi APNS dla tej funkcji (mogą nasłuchiwać ).PKPassLibraryDidChangeNotification
Aplikacje conduit — aplikacje, które nie bezpośrednio manipulują przejściami (na przykład aplikacje towarzyszące), ale które mogą poprawić swoje narzędzie, rozpoznając przebiegi i umożliwiając dodanie ich do portfela. Klienci poczty, przeglądarki sieci społecznościowych i inne aplikacje agregacji danych mogą napotkać załączniki lub linki do przebiegów.

Cały ekosystem wygląda złożony, dlatego warto zauważyć, że niektóre składniki są opcjonalne i znacznie prostsze implementacje zestawu PassKit są możliwe.

Co to jest pass?

Przekazywanie to kolekcja danych reprezentujących bilet, kupon lub kartę. Może być przeznaczony do pojedynczego użycia przez osobę (i w związku z tym zawierać szczegóły, takie jak numer lotu i alokacja miejsca) lub może to być wiele tokenów użycia, które mogą być współużytkowane przez dowolną liczbę użytkowników (na przykład kupon rabatowy). Szczegółowy opis jest dostępny w dokumencie Informacje o przekazaniu plików firmy Apple.

Typy

Obecnie pięć obsługiwanych typów, które można odróżnić w aplikacji Portfel za pomocą układu i górnej krawędzi przebiegu:

Bilet zdarzenia — małe półokrągowe wycięcie.
Kartę pokładową — można określić nacięcia boczne, ikonę specyficzną dla transportu (np. autobus, pociąg, samolot).
Karta sklepu — zaokrąglona góra, na przykład karta kredytowa lub debetowa.
Kupon – perforowany wzdłuż góry.
Ogólny — taki sam jak karta sklepu, zaokrąglona górna.

Na tym zrzucie ekranu przedstawiono pięć typów pass (w kolejności: kupon, ogólny, karta sklepu, kartę pokładową i bilet zdarzenia):

Struktura plików

Plik przekazujący jest w rzeczywistości archiwum ZIP z rozszerzeniem .paleniass , zawierającym określone pliki JSON (wymagane), różne pliki obrazów (opcjonalnie), a także zlokalizowane ciągi (również opcjonalne).

pass.json — wymagane. Zawiera wszystkie informacje dotyczące przekazywania.
manifest.json — wymagane. Zawiera skróty SHA1 dla każdego pliku w przekazaniu z wyjątkiem pliku podpisu i tego pliku (manifest.json).
podpis — wymagany. Utworzony przez podpisanie manifest.json pliku przy użyciu certyfikatu wygenerowanego w portalu aprowizacji systemu iOS.
logo.png — opcjonalne.
background.png — opcjonalne.
icon.png — opcjonalnie.
Pliki ciągów lokalizowalnych — opcjonalne.

Poniżej przedstawiono strukturę katalogów pliku przekazywania (jest to zawartość archiwum ZIP):

pass.json

Format JSON jest formatem, ponieważ przekazywanie jest zwykle tworzone na serwerze — oznacza to, że kod generowania jest niezależny od platformy na serwerze. Trzy kluczowe informacje w każdym przebiegu to:

teamIdentifier — wszystkie linki są generowane na koncie sklepu App Store. Ta wartość jest widoczna w portalu aprowizacji systemu iOS.
passTypeIdentifier — zarejestruj się w portalu aprowizacji, aby grupować razem (jeśli utworzysz więcej niż jeden typ). Na przykład kawiarnia może utworzyć typ karty sklepu, aby umożliwić swoim klientom uzyskanie kredytów lojalnościowych, ale także oddzielny typ kuponu, aby utworzyć i dystrybuować kupony rabatowe. Ten sam kawiarnia może nawet zorganizować wydarzenia muzyczne na żywo i wydać bilet wydarzenia dla tych.
serialNumber — unikatowy ciąg w tym passTypeidentifier obiekcie . Wartość jest nieprzezroczysta dla portfela, ale jest ważna w przypadku śledzenia określonych przebiegów podczas komunikacji z serwerem.

W każdym przebiegu istnieje duża liczba innych kluczy JSON, na przykład pokazano poniżej:

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

Kodów kreskowych

Obsługiwane są tylko formaty 2D: PDF417, Aztec, QR. Apple twierdzi, że kody kreskowe 1D nie są wyposażone w skanowanie na ekranie z podświetlanym telefonem.

Tekst alternatywny wyświetlany poniżej kodu kreskowego jest opcjonalny — niektórzy handlowcy chcą mieć możliwość ręcznego odczytywania/wpisywania.

Kodowanie ISO-8859-1 jest najbardziej typowe. Sprawdź, które kodowanie jest używane przez systemy skanowania, które będą odczytywać przebiegi.

Trafność (ekran blokady)

Istnieją dwa typy danych, które mogą spowodować wyświetlenie przekazywania na ekranie blokady:

Lokalizacja

W passie można określić maksymalnie 10 lokalizacji, np. sklepy, które klient często odwiedza lub lokalizację kina lub lotniska. Klient może ustawić te lokalizacje za pośrednictwem aplikacji towarzyszącej lub dostawca może określić je na podstawie danych użycia (jeśli są zbierane z uprawnieniami klienta).

Gdy przejście jest wyświetlane na ekranie blokady, jest obliczane ogrodzenie tak, aby gdy użytkownik opuszcza obszar, przejście jest ukryte przed ekranem blokady. Promień jest powiązany ze stylem przekazywania, aby zapobiec nadużyciom.

Data i godzina

W passie można określić tylko jedną datę/godzinę. Data i godzina jest przydatna do wyzwalania przypomnień na ekranie blokady na potrzeby kart pokładowych i biletów zdarzeń.

Można aktualizować za pomocą wypychania lub interfejsu API PassKit, aby można było zaktualizować datę/godzinę w przypadku biletu wielokrotnego użycia (np. bilet na sezon do teatru lub kompleksu sportowego).

Lokalizacja

Tłumaczenie przekazywanego na wiele języków jest podobne do lokalizowania aplikacji systemu iOS — tworzenie katalogów specyficznych dla języka za pomocą .lproj rozszerzenia i umieszczanie zlokalizowanych elementów wewnątrz. Tłumaczenia tekstu powinny być wprowadzane do pass.strings pliku, podczas gdy zlokalizowane obrazy powinny mieć taką samą nazwę jak obraz, który zastępują w katalogu głównym przekazywania.

Zabezpieczenia

Przebiegi są podpisane przy użyciu certyfikatu prywatnego wygenerowanego w portalu aprowizacji systemu iOS. Kroki podpisywania przebiegu są następujące:

Oblicz skrót SHA1 dla każdego pliku w katalogu przekazywanym (nie dołączaj manifest.jsonsignature ani pliku, żaden z nich nie powinien istnieć na tym etapie).
Zapisz manifest.json jako listę klucz/wartość JSON dla każdej nazwy pliku z jego skrótem.
Użyj certyfikatu manifest.json , aby podpisać plik i zapisać wynik w pliku o nazwie signature .
Spakuj wszystko w górę i nadaj wynikowemu .pkpass plikowi rozszerzenie pliku.

Ponieważ klucz prywatny jest wymagany do podpisania przebiegu, ten proces powinien być wykonywany tylko na bezpiecznym serwerze, który kontrolujesz. Nie dystrybuuj kluczy, aby spróbować wygenerować przekazywanie w aplikacji.

Konfiguracja i instalacja

Ta sekcja zawiera instrukcje ułatwiające skonfigurowanie szczegółów aprowizacji i utworzenie pierwszego przekazania.

Inicjowanie obsługi administracyjnej zestawu PassKit

Aby można było przejść do sklepu App Store, musi być połączony z kontem dewelopera. Wymaga to dwóch kroków:

Przekazywanie musi być zarejestrowane przy użyciu unikatowego identyfikatora o nazwie Identyfikator typu dostępu.
Należy wygenerować prawidłowy certyfikat, aby podpisać passę przy użyciu podpisu cyfrowego dewelopera.

Aby utworzyć identyfikator typu pass, wykonaj następujące czynności.

Tworzenie identyfikatora typu pass

Pierwszym krokiem jest skonfigurowanie identyfikatora typu pass dla każdego innego typu przekazywania, który ma być obsługiwany. Identyfikator dostępu (lub identyfikator typu dostępu) tworzy unikatowy identyfikator dla przekazywania. Użyjemy tego identyfikatora, aby połączyć przekazywanie z kontem dewelopera przy użyciu certyfikatu.

W sekcji Certyfikaty, identyfikatory i profile w portalu aprowizacji systemu iOS przejdź do pozycji Identyfikatory i wybierz pozycję Identyfikatory typu dostępu. Następnie wybierz przycisk , + aby utworzyć nowy typ przekazywania:
Podaj opis (nazwę) i identyfikator (unikatowy ciąg) dla przekazywania. Zwróć uwagę, że wszystkie identyfikatory typu pass muszą zaczynać się od ciągu pass. w tym przykładzie, którego używamy pass.com.xamarin.coupon.banana :
Potwierdź identyfikator dostępu, naciskając przycisk Zarejestruj .

Generowanie certyfikatu

Aby utworzyć nowy certyfikat dla tego identyfikatora typu pass, wykonaj następujące czynności:

Wybierz nowo utworzony identyfikator dostępu z listy, a następnie kliknij pozycję Edytuj :

Następnie wybierz pozycję Utwórz certyfikat... :
Postępuj zgodnie z instrukcjami, aby utworzyć żądanie podpisania certyfikatu (CSR).
Naciśnij przycisk Kontynuuj w portalu dla deweloperów i przekaż csr, aby wygenerować certyfikat.
Pobierz certyfikat i kliknij go dwukrotnie, aby zainstalować go w pęku kluczy.

Teraz, gdy utworzyliśmy certyfikat dla tego identyfikatora typu pass, w następnej sekcji opisano, jak utworzyć przekazywanie ręcznie.

Aby uzyskać więcej informacji na temat aprowizacji portfela, zapoznaj się z przewodnikiem Praca z możliwościami .

Ręczne tworzenie przebiegu

Teraz, gdy utworzyliśmy typ przebiegu, możemy ręcznie utworzyć passę do testowania na symulatorze lub urządzeniu. Kroki tworzenia przebiegu są następujące:

Utwórz katalog zawierający przekazane pliki.
Utwórz plik pass.json zawierający wszystkie wymagane dane.
Dołącz obrazy do folderu (jeśli jest to wymagane).
Oblicz skróty SHA1 dla każdego pliku w folderze i zapisz je w manifest.json.
Podpisz manifest.json przy użyciu pobranego pliku p12 certyfikatu.
Spakuj zawartość katalogu i zmień jego nazwę na rozszerzenie .alzheimerass.

W przykładowym kodzie tego artykułu znajdują się pliki źródłowe, których można użyć do wygenerowania przebiegu. Użyj plików w CouponBanana.raw katalogu CreateAPassManually. Istnieją następujące pliki:

Otwórz pass.json i edytuj kod JSON. Musisz przynajmniej zaktualizować element passTypeIdentifier i teamIdentifer , aby był zgodny z kontem dewelopera firmy Apple.

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

Następnie należy obliczyć skróty dla każdego pliku i utworzyć manifest.json plik. Po zakończeniu będzie wyglądać mniej więcej tak:

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

Następnie należy wygenerować podpis dla tego pliku przy użyciu certyfikatu (pliku p12), który został wygenerowany dla tego identyfikatora typu dostępu.

Logowanie na komputerze Mac

Pobierz materiały pomocy technicznej portfel seed z witryny Apple Downloads. signpass Użyj narzędzia , aby przekształcić folder w przekazywanie (spowoduje to również obliczenie skrótów SHA1 i spakowanie danych wyjściowych w pliku .csvass).

Testowanie

Jeśli chcesz zbadać dane wyjściowe tych narzędzi (ustawiając nazwę pliku na .zip, a następnie otwierając je), zobaczysz następujące pliki (zwróć uwagę na dodanie manifest.json plików i signature ):

Po podpisaniu plik ZIPped i zmieniono jego nazwę (np. na BananaCoupon.pkpass) możesz przeciągnąć go do symulatora, aby go przetestować, lub wysłać wiadomość e-mail do siebie, aby pobrać na rzeczywistym urządzeniu. Powinien zostać wyświetlony ekran Dodawania przekazywania, w następujący sposób:

Zwykle ten proces byłby zautomatyzowany na serwerze, jednak ręczne tworzenie przekazywania może być opcją dla małych firm, które tworzą tylko kupony, które nie wymagają obsługi serwera zaplecza.

Portfel

Portfel jest centralnym elementem ekosystemu PassKit. Ten zrzut ekranu przedstawia pusty portfel oraz wygląd listy dostępu i poszczególnych przebiegów:

Funkcje portfela obejmują:

Jest to jedyne miejsce, w których przebiegi są renderowane przy użyciu ich kodu kreskowego do skanowania.
Użytkownik może zmienić ustawienia aktualizacji. Jeśli to ustawienie jest włączone, powiadomienia wypychane mogą wyzwalać aktualizacje danych w aplikacji Pass.
Użytkownik może włączyć lub wyłączyć integrację ekranu blokady. Jeśli ta opcja jest włączona, umożliwia to automatyczne wyświetlenie przekazywania na ekranie blokady na podstawie odpowiednich danych czasu i lokalizacji osadzonych w przekazaniu.
Odwrotna strona przekazywania obsługuje funkcję ściągania do odświeżenia, jeśli w przekazanym formacie JSON zostanie podany adres URL serwera internetowego.
Aplikacje towarzyszące można otwierać (lub pobierać), jeśli identyfikator aplikacji jest dostarczany w przekazanym formacie JSON.
Passy można usunąć (z uroczym rozdrabnianiem animacji).

Dodawanie przejść do portfela

Przekazywanie można dodać do portfela w następujący sposób:

Aplikacje conduit — nie manipulują bezpośrednio przekazywaniem, po prostu ładują pliki i prezentują użytkownika z opcją dodania ich do portfela.
Aplikacje towarzyszące — są one zapisywane przez dostawców w celu rozpowszechniania podań i oferują dodatkowe funkcje przeglądania lub edytowania. Aplikacje platformy Xamarin.iOS mają pełny dostęp do interfejsu API zestawu PassKit w celu utworzenia i manipulowania przebiegami. Następnie można dodać przekazywanie do aplikacji Portfel przy użyciu elementu PKAddPassesViewController. Ten proces został opisany bardziej szczegółowo w sekcji Aplikacje towarzyszące tego dokumentu.

Aplikacje kanału

Aplikacje typu conduit to aplikacje pośrednie, które mogą otrzymywać przekazywanie w imieniu użytkownika i powinny być zaprogramowane w celu rozpoznawania ich typu zawartości i zapewnienia funkcjonalności w celu dodania do portfela. Przykłady aplikacji kanałowych to:

Poczta — rozpoznaje załącznik jako passę.
Safari — rozpoznaje przekazywany typ zawartości po kliknięciu linku Pass URL (Przekaż adres URL).
Inne aplikacje niestandardowe — każda aplikacja, która odbiera załączniki lub otwiera linki (klienci mediów społecznościowych, czytelnicy poczty itp.).

Na tym zrzucie ekranu pokazano, jak usługa Mail w systemie iOS 6 rozpoznaje załącznik z przekazywaniem i (po dotknięciu) oferuje dodawanie go do portfela.

Jeśli tworzysz aplikację, która może być kanałem dla przebiegów, można je rozpoznać przez:

Rozszerzenie pliku — .xmlass
Typ MIME — application/vnd.apple.gongass
UTI – com.apple.oniaass

Podstawową operacją aplikacji kanału jest pobranie przekazanego pliku i wywołanie zestawu PassKit PKAddPassesViewController w celu nadania użytkownikowi opcji dodania przekazania do portfela. Implementacja tego kontrolera widoku jest omówiona w następnej sekcji dotyczącej aplikacji towarzyszących.

Aplikacje conduit nie muszą być aprowizowane dla określonego identyfikatora typu przekazywanego w taki sam sposób, jak aplikacje towarzyszące.

Aplikacje towarzyszące

Aplikacja pomocnika udostępnia dodatkowe funkcje umożliwiające pracę z przebiegami, w tym tworzenie przekazywania, aktualizowanie informacji skojarzonych z przekazywaniem i zarządzanie przebiegami skojarzonymi z aplikacją.

Aplikacje towarzyszące nie powinny próbować duplikować funkcji aplikacji Portfel. Nie są one przeznaczone do wyświetlania przebiegów skanowania.

W pozostałej części tej sekcji opisano sposób tworzenia podstawowej aplikacji towarzyszącej, która współdziała z zestawem PassKit.

Inicjowanie obsługi

Ponieważ portfel to technologia sklepu, aplikacja musi być aprowizowana oddzielnie i nie może używać profilu aprowizacji zespołu lub identyfikatora aplikacji wieloznacznych. Zapoznaj się z przewodnikiem Praca z możliwościami , aby utworzyć unikatowy identyfikator aplikacji i profil aprowizacji dla aplikacji Portfel.

Uprawnienia

Plik Entitlements.plist powinien zostać uwzględniony we wszystkich ostatnich projektach platformy Xamarin.iOS. Aby dodać nowy plik Entitlements.plist, wykonaj kroki opisane w przewodniku Praca z upoważnieniami .

Aby ustawić uprawnienia, wykonaj następujące czynności:

Visual Studio dla komputerów Mac
Program Visual Studio

Kliknij dwukrotnie plik Entitlements.plist w okienku rozwiązania, aby otworzyć edytor Entitlements.plist:

Entitlements.plst editor

W sekcji Portfel wybierz opcję Włącz portfel

Enable wallet entitlement

Domyślną opcją jest zezwolenie aplikacji na wszystkie typy przekazywane. Można jednak ograniczyć aplikację i zezwolić tylko na podzestaw typów przekazywania zespołu. Aby włączyć tę opcję, wybierz podzbiór typów przekazywania zespołu i wprowadź identyfikator typu dostępu podzestawu, który chcesz zezwolić.

Kliknij dwukrotnie plik Entitlements.plist, aby otworzyć plik źródłowy XML.

Aby dodać uprawnienie Portfel, ustaw właściwość na Passbook Identifiers wartość na liście rozwijanej, która automatycznie ustawi typArray. Następnie ustaw wartość ciągu na :$(TeamIdentifierPrefix)*

Enable wallet entitlement

Umożliwi to aplikacji zezwolenie na wszystkie typy przekazywane. Aby ograniczyć aplikację i zezwolić tylko na podzestaw typów przekazywania zespołu, ustaw wartość ciągu na:

$(TeamIdentifierPrefix)pass.$(CFBundleIdentifier)

Gdzie pass.$(CFBundleIdentifier) to identyfikator dostępu, który został utworzony powyżej

Debugowanie

Jeśli masz problemy z wdrażaniem aplikacji, sprawdź, czy używasz poprawnego profilu aprowizacji i czy Entitlements.plist element jest wybrany jako plik uprawnień niestandardowych w opcjach podpisywania pakietu i Telefon.

Jeśli wystąpi ten błąd podczas wdrażania:

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

tablica pass-type-identifiers uprawnień jest niepoprawna (lub nie jest zgodna z profilem aprowizacji). Sprawdź, czy identyfikatory typu pass i identyfikator zespołu są poprawne.

Klasy

Następujące klasy PassKit są dostępne dla aplikacji w celu uzyskania dostępu do przebiegów:

PKPass — wystąpienie przebiegu.
PKPassLibrary — udostępnia interfejs API umożliwiający dostęp do przejść na urządzeniu.
PKAddPassesViewController — służy do wyświetlania przekazania dla użytkownika w celu zapisania w portfelu.
PKAddPassesViewControllerDelegate — deweloperzy platformy Xamarin.iOS

Przykład

Zapoznaj się z projektem PassLibrary w przykładowym kodzie tego artykułu. Demonstruje ona następujące typowe funkcje, które byłyby wymagane w aplikacji towarzyszącej portfelu:

Sprawdź, czy portfel jest dostępny

Portfel nie jest dostępny na urządzeniu iPad, dlatego aplikacje powinny sprawdzać przed próbą uzyskania dostępu do funkcji PassKit.

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

Tworzenie wystąpienia przekazywanej biblioteki

Biblioteka PassKit nie jest pojedyncza, aplikacje powinny tworzyć i przechowywać wystąpienia w celu uzyskania dostępu do interfejsu API zestawu PassKit.

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

Pobieranie listy przebiegów

Aplikacje mogą zażądać listy przejść z biblioteki. Ta lista jest automatycznie filtrowana według zestawu PassKit, dzięki czemu można zobaczyć tylko przebiegi, które zostały utworzone za pomocą identyfikatora zespołu i które znajdują się na liście uprawnień.

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

Należy pamiętać, że symulator nie filtruje zwracanej listy przebiegów, więc ta metoda powinna być zawsze testowana na rzeczywistych urządzeniach. Tę listę można wyświetlić w widoku UITableView. Przykładowa aplikacja wygląda następująco po dodaniu dwóch kuponów:

Wyświetlanie przebiegów

Ograniczony zestaw informacji jest dostępny do renderowania przebiegów w aplikacjach towarzyszących.

Wybierz z tego zestawu właściwości standardowych, aby wyświetlić listy przebiegów, jak robi przykładowy kod.

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

Ten ciąg jest wyświetlany jako alert w przykładzie:

Możesz również użyć LocalizedValueForFieldKey() metody , aby pobrać dane z pól w zaprojektowanych przebiegach (ponieważ wiesz, jakie pola powinny być obecne). Przykładowy kod nie pokazuje tego.

Ładowanie przekazywania z pliku

Ponieważ dostęp można dodać tylko do aplikacji Portfel z uprawnieniami użytkownika, kontroler widoku musi zostać przedstawiony, aby umożliwić im podjęcie decyzji. Ten kod jest używany w przycisku Dodaj w przykładzie, aby załadować wstępnie skompilowany przebieg osadzony w aplikacji (należy zastąpić go podpisem):

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

Przekazywanie jest wyświetlane z opcjami Dodaj i Anuluj :

Zastępowanie istniejącego przebiegu

Zastąpienie istniejącego przebiegu nie wymaga uprawnień użytkownika, ale zakończy się niepowodzeniem, jeśli pass jeszcze nie istnieje.

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

Edytowanie dostępu

PKPass nie jest modyfikowalny, więc nie można zaktualizować obiektów przekazywanych w kodzie. Aby zmienić dane w przekazaniu aplikacji, musi mieć dostęp do serwera internetowego, który może przechowywać rekord przebiegów i generować nowy przekazany plik ze zaktualizowanymi wartościami, które aplikacja może pobrać.

Należy wykonać przekazywanie tworzenia plików na serwerze, ponieważ przekazywanie musi być podpisane przy użyciu certyfikatu, który musi być przechowywany jako prywatny i bezpieczny.

Po wygenerowaniu zaktualizowanego przekazanego pliku użyj Replace metody , aby zastąpić stare dane na urządzeniu.

Wyświetlanie przekazywania do skanowania

Jak wspomniano wcześniej, tylko portfel może wyświetlać przekazywanie do skanowania. Pass można wyświetlić przy użyciu OpenUrl metody , jak pokazano poniżej:

UIApplication.SharedApplication.OpenUrl (p.PassUrl);

Otrzymywanie powiadomień o zmianach

Aplikacje mogą nasłuchiwać zmian wprowadzonych w bibliotece dostępu przy użyciu elementu PKPassLibraryDidChangeNotification. Zmiany mogą być spowodowane przez powiadomienia wyzwalające aktualizacje w tle, dlatego dobrym rozwiązaniem jest nasłuchiwanie ich w aplikacji.

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

Ważne jest przekazanie wystąpienia biblioteki podczas rejestrowania w celu uzyskania powiadomienia, ponieważ PKPassLibrary nie jest pojedynczym elementem.

Przetwarzanie serwera

Szczegółowa dyskusja na temat tworzenia aplikacji serwera do obsługi zestawu PassKit wykracza poza zakres tego artykułu wprowadzającego.

Zobacz dotnet-passbook open source kod po stronie serwera C#.

Powiadomienia push

Szczegółowa dyskusja na temat używania powiadomień wypychanych do aktualizacji wykracza poza zakres tego artykułu wprowadzającego.

Aby firma Apple odpowiadała na żądania internetowe z aplikacji Portfel, wymagane jest zaimplementowanie interfejsu API przypominającego REST, gdy wymagane są aktualizacje.

Aby uzyskać więcej informacji, zobacz Aktualizowanie przewodnika po przejściu firmy Apple.

Podsumowanie

W tym artykule przedstawiono zestaw PassKit, z których wynika, że jest to przydatne i opisano różne części, które należy zaimplementować dla pełnego rozwiązania PassKit. Opisano w nim kroki wymagane do skonfigurowania konta dewelopera firmy Apple w celu utworzenia przebiegów, procesu ręcznego przekazywania oraz sposobu uzyskiwania dostępu do interfejsów API zestawu PassKit z poziomu aplikacji platformy Xamarin.iOS.

Portfel dla deweloperów
Przykład zestawu PassKit
Przewodnik dla deweloperów aplikacji Portfel
Struktury — Apple Pay i Portfel (filmy WWDC)
Dokumentacja platformy PassKit
Dokumentacja usługi internetowej elementu Passbook
Informacje o przekazywanych plikach
dotnet-passbook , biblioteka typu open source do generowania pakietów portfeli systemu iOS
Wprowadzenie do systemu iOS 6