Pässe selber machen (2/3)

Hier folgt der zweite Schritt zum eigenen Passbook Pass — das Bauen des eigentlichen Passes. Zur Vorbereitung der Zertifikate siehe Teil 1.

Pass bauen

Alle zu einem Pass gehörigen Dateien werden ähnlich einem Bundle in einem Ordner zusammen gefasst.

Pass-Definition anlegen

Die zentrale Datei im Pass-Ordner ist pass.json. Sie enthält die Beschreibung des Passes als JSON-Struktur. Es gibt unterschiedliche Pass-Typen, die in Passbook eine eigen Darstellunsgsform haben, die Definition in pass.json ist aber für alle (fast) identisch. Jede pass.json enthält dabei genau eine Pass-Definition.

Beispielpass Vorderseite (links), Rückseite (rechts)

Die Definition in pass.json für diesen Beispielpass sieht z.B. so aussehen:

{
    "formatVersion" : 1,
    "passTypeIdentifier" : "pass.com.example.mypass",
    "description" : "Mein Beispielpass",
    "teamIdentifier" : "#Meine Apple Developer Team ID#",
    "organizationName" : "#Mein Apple Developer Team Name#",
    "serialNumber" : "#Seriennummer#",
    "foregroundColor" : "#FFFFFF",
    "backgroundColor" : "#0A7BFF",
    "labelColor" : "#CCCCCC",
    "logoText" : "Logotext",
    "generic" : {
        "headerFields" : [
            {
                "key" : "header",
                "label" : "Header",
                "value" : "Text"
            }
        ],
        "primaryFields" : [
            {
                "key" : "title",
                "label" : "Primary",
                "value" : "Lorem ipsum dolor sit amet, consetetur, adipisci velit, …"
            }
        ],
        "secondaryFields" : [
            {
                "key" : "field1",
                "label": "Secondary 1",
                "value" : "Linksbündig",
                "textAlignment" : "PKTextAlignmentLeft"
            },
            {
                "key" : "field2",
                "label": "Secondary 2",
                "value" : "Zentriert",
                "textAlignment" : "PKTextAlignmentCenter"
            },
            {
                "key" : "field3",
                "label": "Secondary 3",
                "value" : "Rechtsbündig",
                "textAlignment" : "PKTextAlignmentRight"
            }
        ],
        "auxiliaryFields" : [
            {
                "key" : "field1",
                "label": "Auxiliary",
                "value" : "Wird nur mit schmalem Barcode angezeigt"
            }
        ],
        "backFields" : [
            {
                "key" : "field1",
                "label": "Name 1",
                "value" : "Feldtext 1"
            },
            {
                "key" : "field2",
                "label": "Name 2",
                "value" : "Feldtext mit Link zu www.example.com",
                "dataDetectorTypes" : [ "PKDataDetectorTypeLink" ]
            },
            {
                "key" : "field3",
                "label": "Name 3",
                "value" : "Feldtext 3 mit Telefonnummer 0123 456 78 90",
                "dataDetectorTypes" : [ "PKDataDetectorTypePhoneNumber" ]
            },
            {
                "key" : "field4",
                "label": "Name 4",
                "value" : "Feldtext 4 mit Adresse:\nPassstraße 1\n12345 Musterstadt",
                "dataDetectorTypes" : [ "PKDataDetectorTypeAddress" ]
            }
        ]
    },
    "barcode" : {
        "format" : "PKBarcodeFormatPDF417",
        "message" : "http://www.example.com",
        "altText" : "Alternative Beschriftung",
        "messageEncoding" : "iso-8859-1"
    }
}

Wichtig ist, die Werte für die Schlüssel passTypeIdentifier und teamIdentifier korrekt auf die in Teil 1 erzeugte Pass Type ID und die eigene Development Team ID aus dem Developer Portal zu setzen, sonst funktioniert die Signierung später nicht.

Über das Schlüssel serialNumber kann man mehrere unterschiedliche Pässe derselben Art (d.h. mit identischem passTypeIdentifier) erzeugen. Jeder Pass wird über diese beiden Schlüssel eindeutig identifiziert. Passbook wiederum gruppiert zusammen gehörige Pässe mit identischem passTypeIdentifier.

Der Pass-Typ (hier „Generisch“) wird durch den Schlüssel generic festgelegt. Andere Typen kann man mit den Schlüsseln boardingPass, eventTicket, storeCard und coupon erzeugen. Die Unter-Objekte sind aber wiederum für alle Typen identisch.

Vorsicht! Nicht jeder Pass-Typ verwendet alle Felder. Mehr Details zu den Typen und Feldern findet sich hier.

Bilder ergänzen

Ein Pass kann (muss aber nicht zwingenderweise) je nach Typ an verschiedenen Stellen Bilder darstellen &#8212. Um ein Bilder in den Pass einzubinden, braucht man es einfach unter dem entsprechenden Namen im Pass-Ordner ablegen. Fertig!

Der obige Beispielpass hat zwei Bilder:

Logo logo.png wird bei generischen Pässen links oben angezeigt

Thumbnail thumbnail.png rechts neben dem Haupttext in den primary Felder angezeigt

und außerdem noch ein Icon, dass nicht im Pass, sondern im Sperrbildschirm des Mobilgeräts angezeigt werden kann

Icon icon.png

Ist ein Bild nicht vorhanden, bleibt die Stelle im Pass frei bzw. wird von den umliegenden Feldern mit benutzt. Vom jeweiligen Pass-Typ nicht verwendete Bilder werden ignoriert (aber trotzdem mit in das Pass-Archiv kopiert, s. unten). Alle Bilder sollten in den bei Apps auch üblichen Retina (@2x) und Retina HD (@3x) Größen vorliegen damit der Pass je nach Display-Auflösung gut aussieht.

Pass signieren

Sind alle Dateien im Pass-Ordner angelegt kann der Pass gebaut werden. Hierzu muss eine Manifest-Datei angelegt werden, die Pass-Daten anschließend signiert werden und der Ordner dann in ein ZIP-Archiv mit der Datei-Endung .pkpass zusammen gepackt werden.

Diese drei Schritte übernimmt praktischerweise alle das in Teil 1 gebaute Kommandozeilen-Programm signpass. Dazu öffnet man Terminal.app und wechselt zum Verzeichnis, in dem Pass-Ordner (z.B. ~/MyPass/mypass) liegt.

cd ~/MyPass
signpass -p ./mypass 

signpass -p ./mypass signiert und packt den Pass aus Ordner mypass in einer signierten Datei mypass.pkpass zusammen. Zum Signieren greift es direkt über den Schlüsselbund auf das zum passTypeIdentifier : "pass.com.example.mypass" gehörige Zertifikat namens Pass Type ID: pass.com.example.mypass sowie das Apple Worldwide Developer Relations Certification Authority Zertifikat zu. Diesen Zugriff muss man bei der ersten Ausführung von signpass erlauben.

Durch Umbenennen der Pass-Datei mypass.pkpass in mypass.zip lässt sich das von signpass erzeugte Archiv entpacken und unter die Lupe nehmen. Dort findet sich dann neben allen Dateien aus dem Pass-Ordner auch das Manifest manifest.json sowie die digitale Signatur signature.

Pass anschauen

Um sich nun das fertige Resultat anzuschauen bevor man es verteilt, kann man die Datei mypass.pkpass im Finder doppelklicken oder in Terminal.app

open mypass.pkpass

aufrufen.

Beispielpass: Vorschau auf dem Mac

Vorsicht! Die Vorschau auf dem Mac stimmt nicht exakt mit dem Layout auf dem Mobilgerät überein. Also am besten gleich von dort aus via iCloud zu Passbook hinzufügen.

Ist der Pass fertig gebaut, muss er nur noch verteilt werden. Dazu mehr im dritten und letzten Teil.

← Pässe selber machen (3/3) Pässe selber machen →