Session 309 - Introducing Passbook, Part 2

These are confidential sessions—please refrain from streaming, blogging, or taking pictures

Part 2: Framework and Web Service API

Session 309

Introducing Passbook

Ken Ferry and Eliza BlockPassbook Group

ConduitApp

Companion App

Server

Ecosystem

ConduitApp

Companion App

Server

Ecosystem

ConduitApp

Companion App

Server

Ecosystem

ConduitApp

Companion App

Server

Ecosystem

ConduitApp

Companion App

Server

Ecosystem

ConduitApp

Companion App

Server

Ecosystem

Companion AppsModifying passes

Show Installed Passes

PKPassLibrary

PKPass

Show Installed Passes

passLibrary = [[PKPassLibrary alloc] init];

passes = [passLibrary passes];

noteCenter = [NSNotificationCenter defaultCenter];[noteCenter addObserver:self selector:@selector(passLibraryDidChange) name:PKPassLibraryDidChangeNotification object:passLibrary];

PKPassLibraryGet Installed Passes




















alloc/init to instantiatePKPassLibrary Is Not a Singleton

[noteCenter addObserver:self selector:@selector(passLibraryDidChange) name:PKPassLibraryDidChangeNotification object:passLibrary];

•Notifications are per-library• Thread confined

An app must declare the passes it accessesEntitlements


!<key>com.apple.developer.pass-type-identifiers</key>!<array>!! <string>pass.com.oceanic.BoardingPass</string>!</array>

Display a Pass in Table Form

Display a Pass in Table Form

Grabbing text off the passDisplay a Pass in Table Form

[pass localizedValueForFieldKey:@”monkeyProfession”]

{ "key": "monkeyProfession" "label": "PROFESSION", "value": "Butler",}

Display a Pass for Scanning

…in PassbookDisplay a Pass for Scanning

[sharedApp openURL:[tappedPass passURL]]

Don’t write an app if you don’t need oneCompanion Apps Are for Editing

•Avoid duplicating Passbook•A pass should not require an app to be useful

Modifying a Pass

PKPass isn’t mutableModifying a Pass

Your Server


Your Server

request


Your Server

request

.pkpass data

Identifying a pass to your serverModifying a Pass

@property NSString *passTypeIdentifier;@property NSString *serialNumber;

Incorporating a changeModifying a Pass

replacementPass = [[PKPass alloc] initWithData:data error:&error];...[passLibrary replacePassWithPass:replacementPass];

DemoUsing PassKit

Eliza Block

ConduitApp

Companion App

Server

Ecosystem

ConduitApp

Companion App

Server

Ecosystem

PKPassDealing with Incoming Pass Data

Recognizing the dataDealing with Incoming Pass Data

UTI

MIME Type

Extension

com.apple.pkpass

application/vnd.apple.pkpass

.pkpass

[[PKPass alloc] initWithData:data error:&error]

Instantiating PKPassDealing with Incoming Pass Data

Displaying the passDealing with Incoming Pass Data

Displaying the passDealing with Incoming Pass Data

icon

organizationName

localizedName

PKAddPassesViewControllerAdd a Pass to Passbook

addPassesVC = [[PKAddPassesViewController alloc] initWithPass:downloadedPass];

[self presentViewController:addPassesVC animated:YES completion:^{}];

Check for Pass Already Present

[passLibrary containsPass:aPass]

Passbook is not available on iPadCheck for Capability

[PKPassLibrary isPassLibraryAvailable]

PassKit

PKPassLibrary

PassKit

PKPassPKAddPassesViewController

AddAdd

ConduitApp

Companion App

Server

Ecosystem

ConduitApp

Companion App

Server

Ecosystem

Passbook from the Server Side

Eliza Block

How to opt inWeb Services

pass.json:{

...“webServiceURL” : “https://www.foo.com/passes/”,...“authenticationToken” : “PZ8GL23T24JEB41X6U”,...

}

Your Server

Apple Push Notification Service

OverviewWeb ServicesWeb Services

Your Server


Register


Your Server


Register


Your Server


Register


Your Server


Register


What serial numbers changed?

Your Server


Register



8ZA4P2 and 4GR3K9

Your Server


Register



8ZA4P2 and 4GR3K9

Give me 8ZA4P2

Give me 4GR3K9

Your Server


Register



8ZA4P2 and 4GR3K9

Give me 8ZA4P2

.pkpass data

Give me 4GR3K9

.pkpass data

Communication elementsWeb Services

• From pass.json


PassTypeID SerialNo. AuthToken

• From pass.json

• From device



PushTokenDeviceID

• From pass.json

• From device

• From your server



PushTokenDeviceID

UpdateTag

RegistrationWeb Services

Your Server


PassTypeID SerialNo.

PushTokenDeviceID

Register

AuthToken Your Server


PassTypeID SerialNo.PushTokenDeviceID AuthToken

Your Server


PassTypeID SerialNo.PushTokenDeviceID AuthToken

Your Server


PassTypeID SerialNo.PushTokenDeviceID

AuthToken

Your Server


PassTypeID SerialNo.PushTokenDeviceID

Your Server

Devices

Your Server

Storage on your serverWeb Services

PassTypeID SerialNo.DeviceID PushToken

Devices

Your Server


PassTypeID SerialNo.DeviceID PushToken

Your Server



Device A PushToken A

Device B PushToken B

Devices

DeviceID PushToken

Your Server





Devices

DeviceID PushToken



Your Server



Devices

PushTokenDeviceID



Your Server



Devices

PushTokenDeviceID

Device A pass.oceanic JA38

Device A pass.oceanic EK91

Device B pass.oceanic XD28

Registrations



Devices

PushTokenDeviceID





Registrations




Devices

PushTokenDeviceID





Registrations

DeviceID




Devices

PushTokenDeviceID





Registrations

DeviceID PassTypeID SerialNo.

Registration endpointWeb Services


• POST/v1/devices/<deviceID>/registrations/<passTypeID>/<serialNo.>



• In the HTTP headerAuthorization: ApplePass <authToken>




• JSON payload{ “pushToken” : <pushToken> }

Unregistration endpointWeb Services


•DELETE/v1/devices/<deviceID>/registrations/<passTypeID>/<serialNo.>


•DELETE/v1/devices/<deviceID>/registrations/<passTypeID>/<serialNo.>




Device C PushToken C

Devices




Device A pass.oceanic CL55


Device C pass.oceanic JA38

Registrations Boarding Passes

JA38

EK91

XD28

CL55

Boarding Passes



Device B pass.oceanic EK91


Device B pass.oceanic CL55

Device C pass.oceanic XD28

JA38

EK91

XD28

CL55

Boarding Passes

Hugo Reyes 9/18, 7pm OA177 SYD PER 19C ...

Hugo Reyes 9/21, 9am OA26 PER SYD 6F ...

Jack Shephard 9/22, 3pm OA815 SYD LAX 22D ...

Hugo Reyes 9/22, 3pm OA815 SYD LAX 20G ...







JA38

EK91

XD28

CL55

Boarding Passes











JA38

EK91

XD28

CL55

Boarding Passes





9/12, 10am

9/12, 10am

8/22, 6pm

9/1, 8pm


Last Updated






JA38

EK91

XD28

CL55

Boarding Passes





9/12, 10am

9/12, 10am

8/22, 6pm

9/1, 8pm

Handling a changeWeb Services





Device Cpass.oceanicpass.oceanicpass.oceanicpass.oceanicpass.ocea

XD28

JA38

EK91

XD28

CL55

Boarding Passes





9/12, 10am

9/12, 10am

8/22, 6pm

9/1, 8pm







XD28

JA38

EK91

XD28

CL55

Boarding Passes





9/12, 10am

9/12, 10am

8/22, 6pm

9/1, 8pm


3ADevice A pass.oceanic JA38





XD28

JA38

EK91

XD28

CL55

Boarding Passes





9/12, 10am

9/12, 10am

8/22, 6pm

9/1, 8pm

9/18, 5pm


3ADevice A pass.oceanic JA38





XD28






JA38 Hugo Reyes 9/18, 7pm OA177 SYD PER 3A ... 9/1, 8pm

EK91 Hugo Reyes 9/21, 9am OA26 PER SYD 6F ... 9/12, 10am

XD28 Jack Shephard 9/22, 3pm OA815 SYD LAX 22D ... 8/22, 6pm

CL55 Hugo Reyes 9/22, 3pm OA815 SYD LAX 20G ... 9/1, 8pm

Boarding Passes

3A 9/18, 5pm









Registrations






Boarding Passes









Registrations






Boarding Passes









Registrations


EK91 Hugo Reyes 9/21, 9am OA26 PER SYD 6F ... 8/22, 6pm


CL55 Hugo Reyes 9/22, 3pm OA815 SYD LAX 20G ... 9/12, 10am

Boarding Passes





Devices





Boarding Passes







Registrations




Devices





Boarding Passes







Registrations

JA38 Hugo Reyes 9/18, 7pm OA177 SYD PER 3A ... 9/12, 10am




Boarding Passes






Registrations




Devices

Sending a push notificationWeb Services

JA38 Hugo Reyes 9/18, 7pm OA177 SYD PER 3A ... 9/12, 10am









Registrations




Devices


Your Server


Your Server


Your Server APNSPassTypeID

PushToken


Your Server APNSPassTypeID

PushToken

PassTypeID

“What changed?”Web Services

PassTypeID






Registrations


PassTypeID






Registrations


PassTypeID


Your Server






Registrations


PassTypeID


DeviceID

Your Server






Registrations


PassTypeID


DeviceID

Your Server






Registrations


PassTypeID


DeviceID UpdateTag

Your Server






Registrations


PassTypeID


DeviceID UpdateTag

SerialNo.

Your Server






Registrations


PassTypeID


DeviceID UpdateTag

SerialNo.UpdateTag

Your Server

Device A pass.oceanic 9/12, 10am






Registrations


PassTypeID


DeviceID UpdateTag

SerialNo.UpdateTag

Your Server







Registrations

Figuring out what changedWeb Services

Your Server







Registrations


Your Server







Registrations


Your Server






Boarding Passes







Boarding Passes







Boarding Passes


9/18, 5pm






Boarding Passes







Boarding Passes

Device A pass.oceanic 9/12, 10am JA38






Boarding Passes

Device A pass.oceanic 9/12, 10am JA38 9/18, 5pm

DeviceID

Device A



UpdateTag

pass.oceanic 9/12, 10am

PassTypeID

JA38 9/18, 5pm

Your Server

SerialNo.

DeviceID

Device A



UpdateTag


PassTypeID

JA38 9/18, 5pm

Your Server

UpdateTag

SerialNo.

DeviceID

Device A



UpdateTag


PassTypeID

JA389/18, 5pm

Your Server

UpdateTag

“What changed?” endpointWeb Services


•GET/v1/devices/<deviceID>/registrations/<passTypeID>


•GET/v1/devices/<deviceID>/registrations/<passTypeID>?passesUpdatedSince=<tag>



• Server responds with JSON payload{ “serialNumbers” : [ <serialNo.>, <serialNo.>, ... ], “lastUpdated” : <tag>}

?passesUpdatedSince=<tag>




?passesUpdatedSince=<tag>

•GET/v1/devices/<deviceID>/registrations/<passTypeID>?passesUpdatedSince=<tag>



“passesUpdatedSince” vs. “if-modified-since”Web Services


• “if-modified-since” applies to a single resource


• “if-modified-since” applies to a single resource■ Returns either the whole resource or 304 (not modified)



• “passesUpdatedSince” applies to a collection



• “passesUpdatedSince” applies to a collection■ Picks out the individual elements that have changed

Getting up-to-date passWeb Services

Your Server


Get pass

Your Server



Get pass

Your Server


.pkpass

Get pass endpointWeb Services

•GET/v1/passes/<passTypeID>/<serialNo.>








• Server responds with signed, zipped .pkpass data


• In the HTTP headerAuthorization: ApplePass <authToken>If-modified-since: <timestamp>


• Server responds with signed, zipped .pkpass data



• Server responds with signed, zipped .pkpass data or 304




• Server responds with signed, zipped .pkpass data or 304

• In the response headerLast-modified: <timestamp>


Pass signing algorithmWeb Services


• Create a JSON dictionary and save it as manifest.json


• Create a JSON dictionary and save it as manifest.json■ Each key is a relative path in the pass directory


• Create a JSON dictionary and save it as manifest.json■ Each key is a relative path in the pass directory■ Each value is the SHA1 hash of the file data at that path, hex encoded



• Sign the manifest data with your cert; save the result as signature



• Sign the manifest data with your cert; save the result as signature

• Zip the contents of the pass directory

DemoRunning the sample web service implementation

Ken Ferry

Rules of the roadWeb Services


•Don’t send unnecessary push notifications


•Don’t send unnecessary push notifications■ Only send pushes when something has changed


•Don’t send unnecessary push notifications■ Only send pushes when something has changed■ Respect unregistration requests: Only send pushes for registered passes



• Verify authentication tokens




• Implement passesUpdatedSince/lastUpdated for the “what changed?” endpoint




• Implement passesUpdatedSince/lastUpdated for the “what changed?” endpoint

• Implement if-modified-since/last-modified for the “get pass” endpoint

Enforcement and feedbackWeb Services


• Standard APNS feedback mechanism applies


• Standard APNS feedback mechanism applies■ If APNS bounces messages to a device, clear it from your database



• Passbook-specific feedback about Web Services API misuse



• Passbook-specific feedback about Web Services API misuse■ Additional “log” endpoint




POST /v1/log




POST /v1/log■ Payload: Human-readable description of the problem





■ We may rate-limit your updates or tell APNS to stop delivering your pushes altogether





■ We may rate-limit your updates or tell APNS to stop delivering your pushes altogether

■ Angry phone call

Summing Up

• PassKit■ PKPass■ PKPassLibrary■ PKAddPassesViewController

•Web Services API /v1/devices/<deviceID>/registrations/<passTypeID>/<serialNo.> /v1/devices/<deviceID>/registrations/<passTypeID>?passesUpdatedSince=<tag> /v1/passes/<passTypeID>/<serialNo.> /v1/log

More Information

Paul MarcosApplication Services [email protected]

DocumentationPass Kit Programming Guidehttp://developer.apple.com

Apple Developer Forumshttp://devforums.apple.com

Related Sessions

Introducing Passbook, Part 1 PresidioWednesday 11:30AM

Passbook Lab App Services Lab BFriday 9:00AM

Labs

Documents

Session 309 - Introducing Passbook, Part 2