Apple-Geldbörse. Was es ist und wie Sie Ihre Karte darin integrieren

Published on November 08, 2018

Apple-Geldbörse. Was es ist und wie Sie Ihre Karte darin integrieren

    Принято считать, что Wallet – не самый популярный сервис в СНГ. Но уже во втором проекте подряд заказчик ставит задачу «Сделать интеграцию с Wallet». Поэтому я решил написать эту статью, чтобы рассказать о сервисе в целом и показать, как интегрировать в него свой продукт.


    Что такое Wallet? Он позволяет держать в телефоне различного вида карты (билеты, скидочные карты и т.п.), облегчая жизнь пользователям продукта. Более того, есть возможность актуализировать информацию о карте посредством push-уведомлений, но это тема для отдельной статьи. Но если у вас есть карта/билет/абонемент, которые можно интегрировать в телефон, то для этого есть решение! Как это сделать – читайте ниже.


    Как правило, за создание карты отвечает ваш сервер. Приложение получает карту в виде .pkpass файла и уже через приложение пользователь может добавить карту в Wallet.


    Kartenstruktur


    Was ist eine Karte aus Sicht des Entwicklers? Die Karte ist ein Archiv mit der Erweiterung .pkpass. Es enthält alle für die Anzeige und Bedienung der Karte notwendigen Daten. Der Inhalt des Archivs ist in der folgenden Tabelle aufgeführt.


    Datei Zweck
    background.png Hintergrundbild für die Karte.
    footer.png Bild neben dem Barcode
    icon.png Symbol für Benachrichtigungen und Briefe
    logo.png Logo-Karte. Oben links angezeigt
    manifest.json Registrierung aller enthaltenen Dateien
    Unterschrift PKCS7-Signatur
    pass.json Aussehen und Informationen auf der Karte
    strip.png Bild hinter der Beschreibung der Hauptkarte
    thumbnail.png Zusätzliches Bild (bitte angeben)

    Es gibt folgende Kartentypen:


    • Bordkarte: mit dem Flugzeug oder der Bahn. Normalerweise funktioniert der Gutschein auf einer Reise.
    • Coupon: für Coupons und Sonderangebote;
    • Veranstaltungsticket: Kann sowohl für eine Veranstaltung als auch für die gesamte Saison verwendet werden.
    • Rabattkarte: Kundenkarten, Rabatt- oder Geschenkkarten;
    • Allgemeine Ansicht der Karte: Wenn keine der oben genannten Angaben zu Ihrem Fall passt: Zum Beispiel eine Karte für Fahrten mit der U-Bahn oder einen Pass zum Fitnessstudio.

    Betrachten Sie schematisch das Aussehen verschiedener Karten. Es ist besser, die Bilder wie in der obigen Tabelle angegeben aufzurufen.


    Bordkarte



    Gutschein



    Veranstaltungsticket



    Übersichtskarte



    Rabattkarte



    Pass.json Struktur


    Erforderliche Felder Enthält Pass-Typ-ID, Team-ID, Organisationsname usw.
    Schlüssel für verwandte Anwendungen. Benötigt, um Anwendungen anzuzeigen, die mit der Karte "verknüpft" werden müssen.
    Keys "Ablaufdatum" Karten.
    Schlüssel von Relevanz. Zum Beispiel die Koordinaten des Gebiets, in dem die Karte verwendet werden kann, oder der Beginn des Ereignisses, für das sie bestimmt ist.
    Der Schlüssel ist Stil. Zu Beginn des Artikels wurden 5 Kartentypen für Wallet aufgelistet. Jeder von ihnen hat seinen eigenen Stil. Ein solcher Schlüssel muss unbedingt einer sein.
    Keys visuelle Kartendesign. Zusätzlich zu den offensichtlichen Informationen enthalten sie Informationen über den auf der Karte angezeigten Barcode.
    Webservice-Schlüssel. Mithilfe von Webdiensten können Sie mit der Karte interagieren und sie beispielsweise automatisch aktualisieren.
    NFC-Schlüssel. Enthält zusätzliche Informationen für Apple Pay-Transaktionen.


    Jetzt ist alles detaillierter.


    Erforderliche Felder


    JSON-Schlüssel Datentyp Beschreibung
    beschreibung String
    Lokalisierbar
    Kurze Kartenbeschreibung. Lokalisierbar.
    formatVersion Int Dateiformatversion. Der Wert muss 1 sein.
    organisationsname String
    Lokalisierbar
    Der Name der Organisation, die die Karten ausstellt.
    passTypeIdentifier String Pass Type ID und Developer Cabinet.
    Seriennummer String Die Seriennummer der einzelnen Karte
    teamIdentifier String Team ID Entwicklerteam

    Schlüssel für verwandte Anwendungen


    JSON-Schlüssel Datentyp Beschreibung
    AssociatedStoreIdentifiers [Int] Optional Der Karte zugeordnete Anwendungs-ID. Nehmen Sie immer die erste, die mit dem aktuellen Gerät kompatibel ist.
    appLaunchURL String URL, die beim Öffnen an die Anwendung übergeben wird

    Style-Tasten


    JSON-Schlüssel Datentyp Beschreibung
    primaryFields [Json] Grundlegende Informationen zur Karte.
    secondaryFields [Json] Hintergrundinformationen.
    AuxiliaryFields [Json] Felder für zusätzliche Informationen. Optional
    headerFields [Json] Der Titel der Karte. Es wird angezeigt, auch wenn die Karten in der Liste sichtbar sind.
    AuxiliaryFields [Json] Grundlegende Informationen zur Karte.
    transitType String Transportart für Kartentickets. Es kann die folgenden Werte
    annehmen : PKTransitTypeAir,
    PKTransitTypeBoat,
    PKTransitTypeBu`,
    PKTransitTypeGeneric,
    `PKTransitTypeTrain`.
    backFields [Json] Array von Feldern, die für die Rückseite der Karte verantwortlich sind

    JSON hat in diesem Fall die folgende Form:


        "key"   : "value1",
        "label" : "value2",
        "value" : "value3"

    Der Wert des Schlüsselwerts kann entweder numerisch oder ein String sein. Der currencyCode zusammen mit dem String-Wert funktioniert jedoch nicht. AuxiliaryFields und SecondaryFields können mehrere sein, und es lohnt sich, die Länge der in ihnen verwendeten Linien zu überwachen.


    Schlüssel des visuellen Designs


    JSON-Schlüssel Datentyp Beschreibung
    Barcodes [Json] Informationen zum Barcode (siehe unten).
    backgroundColor Farbe als Zeichenfolge Hintergrundfarbe (# Fa32e4)
    Vordergrundfarbe Farbe als Zeichenfolge Farbetiketten mit Werten
    groupingIdentifier String Optional für Eventtickets und Transporttickets. Karten mit demselben Stil - passTypeIdentifier und groupingIdentifier - werden gruppiert
    labelColor Farbe als Zeichenfolge Beschriften Sie den Text mit Feldnamen
    logoText Lokalisierbare Zeichenfolge Text, der neben dem Logo angezeigt wird

    Barcode


    Der wichtigste Teil der Karte. Die Identifikationsnummer der Karte ist eingenäht (z. B. die physische Kartennummer oder die Ticketnummer). Es ist wichtig, dass ein Scanner oder ein anderes Tool Codes in der richtigen Codierung lesen kann.


    JSON-Schlüssel Datentyp Beschreibung
    altText String Optionaler Text, der neben dem Barcode angezeigt wird, wenn der Barcode nicht lesbar ist.
    formatieren String Barcode-Format. Kann Werte annehmen: PKBarcodeFormatQR,
    PKBarcodeFormatPDF417,
    PKBarcodeFormatAztec,
    PKBarcodeFormatCode128
    Nachricht String Code oder Kartennummer in Barcode verschlüsselt.
    messageEncoding String Nachrichtenverschlüsselung Normalerweise iso-8859-1

    Lage


    Diese Schlüssel sind für den Ort verantwortlich, an dem die Karte verwendet werden kann.


    JSON-Schlüssel Datentyp Beschreibung
    altiture String Optionaler Text, der neben dem Barcode angezeigt wird, wenn der Barcode nicht lesbar ist.
    Breitengrad Länge Latitude
    Länge Double Latitude
    relevanterText String Optionaler Text, der auf dem Sperrbildschirm angezeigt wird, wenn der Benutzer den Kartenbereich betritt.

    Nachteil


    Auf dem Reverse-Informationsteil können zusätzliche Informationen platziert werden: Nutzungsbedingungen, Richtlinien zur automatischen Aktualisierung, Kontaktdaten und ein Link zu der Anwendung, zu der die Karte gehört. Die Abbildung zeigt die Entsprechung der Felder in pass.json und das Erscheinungsbild der Rückseite der Karte. Wenn das Wertefeld Links, Telefonnummern usw. enthält, werden diese automatisch hervorgehoben.



    Erstellen Sie eine Karte. Teil 2


    Also, die Bilder sind fertig, pass.json wird gebildet, es bleibt alles zusammen zu setzen. Füllen Sie dazu die Datei manifest.json (siehe Tabelle 1) aus, in die Sie alle Bilder und die Datei pass.json einfügen müssen. Es stellt sich so heraus:


    . . . . . . 
       "pass.json" = 303c753abc39aa732ec74643d6db28348fe8a823;
       "strip.png" = 736d01f84cb73d06e8a9932e43076d68f19461ff;
       "strip@2x.png" = 468fa7bc93e6b55342b56fda09bdce7c829d7d46;
    . . . . . .

    Ab diesem Zeitpunkt müssen keine Änderungen mehr vorgenommen werden, da die SHA fehlerhaft ist und bei Änderungen eine erneute Generierung der SHA erforderlich ist.


    Als nächstes müssen Sie im Büro des Entwicklers eine Pass Type ID erstellen und ein Zertifikat dafür erstellen. Die Vorgehensweise sollte mehr oder weniger vertraut sein, wenn Sie zuvor beispielsweise Bereitstellungsprofile erstellt haben.



    Dann gehen wir zum Key-Keeper (Keychain) und exportieren das Apple Worldwide Developer Relation Certificate (WWDR) von dort als .pem.



    Von dort exportieren wir die erstellte Pass Type ID als .p12. In diesem Stadium werden Sie von der Schlüsselkarte aufgefordert, das Kennwort für das Zertifikat einzugeben. In diesem Fall ist das Passwort optional.
    Bitte beachten Sie, dass alle weiteren Aktionen in einem Ordner ausgeführt werden sollten, in dem sich manifest.json, pass.json und pictures bereits befinden sollten.


    Nun müssen Sie eine Signatur generieren, die wir im Archiv signieren. Exportieren Sie zunächst die Pass Type ID und den Schlüssel als .pem.


    openssl pkcs12 -in certificate.p12 -clcerts -nokeys -out passcertificate.pem -passin pass: your_password

    und


    openssl pkcs12 -in certificates.p12 -nocerts -out passkey.pem -passin pass: -passout pass:new_password

    Jetzt können wir eine Signatur erstellen. Mache dies zu einem Befehl:


    openssl smime -binary -sign -certfile WWDR.pem -signer passcertificate.pem -inkey passkey.pem -in manifest.json -out signature -outform DER -passin pass:пароль_из_предыдущей_команды

    Also, alles ist fertig mit uns, es bleibt nur das Archiv zu sammeln, wir machen es mit dem Befehl:


    zip -r nameOfPass.pkpass manifest.json pass.json signature logo.png logo@2x.png logo@3x.png icon.png icon@2x.png icon@3x.png

    Ich mache Sie darauf aufmerksam, dass alle Dateien, zu denen Sie das Datenarchiv für die Karte (.pkpass) hinzufügen möchten, hier aufgelistet sein sollten.
    Als Ergebnis erhalten wir eine .pkpass-Datei, die auf dem Computer geöffnet werden kann. Es wird eine Vorschau der Karte angezeigt, deren Aussehen möglicherweise vom Aussehen auf dem Telefon abweicht.
    All dies kann etwas einfacher gemacht werden. Apple bietet ein Hilfsprogramm signpass( Apple Wallet Sample Meterials ), das alle SHA-Berechnungen ( manifest.jsonSie können die Datei nicht selbst erstellen ) und das Erstellen von Signaturen übernimmt . Um es zu verwenden, müssen Sie das Projekt sammeln und die Datei signpassin einem Ordner mit allen erforderlichen Ressourcen ablegen.



    Im Allgemeinen sollte die Struktur so aussehen:



    Führen Sie als Nächstes den folgenden Befehl aus:


    ./signpass -p wallet

    Wallet ist der Name des Ordners, in dem sich alle Ressourcen befinden. Am Ausgang erhalten wir die Datei wallet.pkpass. Der Inhalt kann durch Entarchivieren von wallet.pkpass angezeigt werden.


    unzip wallet.pkpass

    Es ist möglich, dass die Erstellung von pkpass im Backend erfolgt. In diesem Fall müssen Sie das Zertifikat für die Pass Type ID in Form von .p12 und das Passwort an die WWDR-Entwickler übertragen.


    Anwendungsintegration


    Damit die Anwendung Karten zur Brieftasche hinzufügen kann, müssen Sie diese Funktion in der App-ID und diese Funktion in den Funktionen im Projekt aktivieren.




    Dies ist für die korrekte Arbeit mit Wallet erforderlich. Andernfalls können keine Karten aus der Brieftasche gelesen werden, und beispielsweise kann nicht verstanden werden, ob unsere Karte hinzugefügt wurde oder nicht. Es ist auch wichtig zu beachten, dass die Team-ID in pass.json mit der c-Team-ID übereinstimmen muss. Andernfalls müssen Sie sie manuell zu den Berechtigungen hinzufügen. Dies kann die Situation korrigieren, ich habe sie jedoch nicht überprüft.



    Eine Karte hinzufügen


    Das Hinzufügen von Karten ist ganz einfach:


    guard let passPath = Bundle.main.path(forResource: "wallet", ofType: "pkpass") else { return }
            let error: ErrorPointer = ErrorPointer(nilLiteral: ())
            guard let passData = NSData(contentsOfFile: passPath) else { return }
            let pass = PKPass(data: passData as Data, error: error)
            let passLibrary = PKPassLibrary()
            passLibrary.addPasses([pass]) { (status) in
                print(passLibrary.containsPass(pass))
            }

    Wieder muss die .pkpass-Datei jedoch häufiger von Ihrem Server heruntergeladen werden.
    Es ist erwähnenswert, dass PassKit gut lesbare Fehler enthält, sodass Sie leicht nachvollziehen können, was genau falsch gemacht wurde.


    Informationen zu hinzugefügten Karten abrufen


    Informationen zu den in der Brieftasche verfügbaren Karten und zu Ihrer Anwendung finden Sie im PKPassLibrary-Objekt.


    let passLibrary = PKPassLibrary()
    let passes = passLibrary.passes()

    Auf diese Weise können Sie nachvollziehen, ob eine Karte hinzugefügt wurde oder nicht, und die Benutzeroberfläche aktualisieren. Darüber hinaus können über PKPassLibrary Karten aktualisiert und gelöscht werden. Sie können Karten auch über Webservices aktualisieren. In diesem Artikel wird diese Option jedoch nicht berücksichtigt.


    Überprüfen Sie die Eindeutigkeit


    Da die Karte zu Ihren Diensten in der Regel an ein Konto gebunden ist, muss die Anwendung höchstwahrscheinlich auf irgendeine Weise feststellen, ob die Karte dem aktuellen Benutzer gehört. Ich schlage vor, es durchzumachen serialNumber. Zum Beispiel als serialNumberBenutzer-ID oder Kartennummer festgelegt.


    Testen


    Apple bietet Beispiele für pkpass für verschiedene Typen, auf die Sie sich konzentrieren können.
    Apple Wallet-Beispiele
    Um zu sehen, wie die Karte aussieht, können Sie pkpass zum Projekt hinzufügen (siehe „Hinzufügen einer Karte“). Der Vorgang des Hinzufügens / Löschens wurde bereits oben erörtert. Es soll nur daran erinnert werden, dass die Anwendung die bereits hinzugefügten Karten nicht sieht, wenn die Karte für Wallet auf einem Entwicklerkonto erstellt und die Entwicklung selbst auf einem anderen Konto ausgeführt wurde (relevant für Outsourcing-Unternehmen). In diesem Fall können Sie problemlos Karten hinzufügen.
    Mit einem QR-Code-Scanner können Sie überprüfen, ob die Informationen im Barcode korrekt codiert sind. Und müssen nur die Richtigkeit der Arbeit mit diesem Scanner überprüfen.


    Fazit


    Der Artikel untersuchte den Prozess der Erstellung und Gestaltung der Karte sowie den Prozess der Integration in die Anwendung und die möglicherweise auftretenden Probleme. Ich habe mich bewusst nicht mit der Integration von Webdiensten und Kartenaktualisierungen befasst und hoffe, dies im nächsten Artikel zu tun.


    Verwendete Materialien:


    https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html
    https://developer.apple.com/library/archive/documentation/UserExperience/Reference/PassKit_Bundle/Chapters/TopLevel .html # // apple_ref / doc / uid / TP40012026-CH2-SW3
    https://itechroof.wordpress.com/2015/11/30/apple-wallet-part-13/
    https://developer.apple.com/ Bibliothek / Archiv / Dokumentation / UserExperience / Conceptual / PassKit_PG / Updating.html


    Besonderer Dank geht an mehdzor für den Entwickleraccount für Tests.