Supporting iOS 18 Changes

[alexandercerutti]

iOS 18 have been announced a few days ago and, a few hours ago, the session including the upcoming changes to Apple Wallet have been published: https://developer.apple.com/videos/play/wwdc2024/10108/

Some new fields have been published to support the new UI for events.

That said, within september October (when iOS 18.1 will get released), a passkit-generator update will be published.

If anyone wants to attempt to generate the new passes with an iOS 18 Beta through passkit-generator, I kindly ask you to leave a comment here, so I'll know if I should publish an alpha version with some changes.

This issue will be soon updated with a summary of the changes in the schemas. (see below, second comment)

Recap from the discussion until now

• The new eventTicket is a pass that requires NFC Entitlements

• Show hidden and useless updates

  • Schema changes are available in this branch
  • We were able to extract the NFC certificate used by PassKit to generate an NFC pass from its signature and found what are the practical differences between a normal one and and NFC one. A certificate cannot be tampered, so we cannot generate one with NFC capabilities.
  • Although RC was released and new model is cited inside the changelog and the web page, with only the details provided in the WWDC video (and NFC certificate), it seems to be impossible yet to generate a valid eventTicket with the new UI. it is possible now to generate one.
  • Apparently not even with 18 or iOS 18.1, it is possible to generate it.

• Apple made at least one mistake in their video: preferredStyleSchemes is a top level property. All the errors are marked in the second message with a strikethrough style, followed or preceded by the correct property.

• One of semantics.venueRegionName, semantics.venueName or semantics.venueRoom is a required for the new layouto appear.

• The new layout applies to all the semantics.eventType but PKEventTypeSports for which two more properties are needed: semantics.awayTeamAbbreviation and semantics.homeTeamAbbreviation

• The new layout applies to semantics.eventType == PKEventTypeLivePerformance, but semantics.performerNames is required.

• Each relevantDates entry allows a max time span of 1 day, between 00:00 and 23:59, timezone excluded.

• Found lot more of root properties for event guide, for transfering and selling tickets and for live activies.

• A new asset venueMap.png (and resolutions, probably) can be added to bundle to show the map of the venue in the event guide

• iOS 18.1 b6 shows perfectly the live activity, with seat color highlighted, even in case of general admission

• has been released with all the discussed changes. We are waiting for the stable release of iOS 18.1 to release a stable version of this library, in order to see if an updated documentation will come out (other than the N.D.A/private documents shared with companies) and if something more should be added.

• New iOS 18 fields have been discovered after the release of passkit-generator@v3.2.0.

• has been released! 🎉

• Apple updated the documentation, both API and HIG with details about the new Poster event ticket!

[alexandercerutti]

• (root).bagPolicyURL (string) (link to message)
• (root).orderFoodURL (string) (link to message)
• (root).parkingInformationURL (string) (link to message)
• (root).contactVenuePhoneNumber (string) (link to message)
• (root).contactVenueWebsite (string) (link to message)
• (root).accessibilityURL (string) (link to message)
• (root).addOnURL (string) (link to message)
• (root).purchaseParkingURL (string) (link to message)
• (root).merchandiseURL (string) (link to message)
• (root).transitInformationURL (string) (link to message)
• (root).eventTicket.preferredStyleSchemes (["posterEventTicket", "eventTicket"])
• (root).preferredStyleSchemes (["posterEventTicket", "eventTicket"])
• (root).sellURL (string) (link to message)
• (root).transferURL (string) (link to message)
• (root).suppressHeaderDarkening (boolean) (link to message
• (root).footerBackgroundColor (boolean) (link to message
• (root).useAutomaticColor (boolean) (link to message
• (root).auxiliaryStoreIdentifiers (boolean) (link to message
• (root).eventTicket.additionalInfoFields (Field[]) (link to message)
• (root).relevantDates[].startDate (date time string) (link to message, link to message)
• (root).relevantDates[].endDate (date time string) (link to message, link to message)
• (root).relevantDates[].relevantDate (date time string) (link to message)
• semantics.relevantDates[].startDate (date time string) (link to message)
• semantics.relevantDates[].endDate (date time string) (link to message)
• semantics.seats[].venueEntranceGate (string)
• semantics.venueEntranceGate (string) (link to message)
• semantics.admissionLevel (string)
• semantics.eventStartDateInfo (object) (link to message
• semantics.venueParkingLotsOpenDate (date time string) (link to message)
• semantics.venueGatesOpenDate (date time string) (link to message)
• semantics.venueRegionName (string) (link to message)
• semantics.entranceDescription (string) (link to message)
• semantics.attendeeName (string) (link to message)
• semantics.eventLiveMessage (string) (link to message)
• semantics.playlistIDs (link to message)
• semantics.albumIDs (link to message)
• semantics.venueBoxOfficeOpenDate (link to message)
• semantics.venueOpenDate (date time string) (link to message
• semantics.venueCloseDate (link to message)
• semantics.venueDoorsOpenDate (link to message)
• semantics.venueFanZoneOpenDate (link to message)
• semantics.tailgatingAllowed (link to message)
• semantics.additionalTicketAttributes (link to message)
• semantics.seats[].seatAisle (link to message)
• semantics.venueEntranceDoor (link to message)
• semantics.venueEntrancePortal (link to message)
• semantics.admissionLevelAbbreviation (link to message)
• semantics.airplay[].airPlayDeviceGroupToken (link to message)
• semantics.seats[].seatLevel (link to message)
• semantics.seats[].seatSectionColor (link to message, link to message)

iOS 18.1 changes (released in v3.5.5)

• eventLogoText
• EventDateInfo.unannounced
• EventDateInfo.undetermined

[nickwelsh]

I'm able and willing to test if you're publishing an alpha!

[alexandercerutti]

@nickwelsh Okay great! I'll work on it, probably this weekend.

Before having a stable release, I'll wait for them to publish the updated documentation.

I think these are the new fields but some more could appear possibly.

P.s. Did you leave a 🌟 on the project? 👀

[alexandercerutti]

Schema changes are available in this branch, so you can install the package in NPM from git and build it.

I'll release a version in the next days if I have some time.

If you can successfully test, can you provide me screenshots of the results? I'm very curious!

[nickwelsh]

I built a minimal version using the stable build to make sure things worked:

Code

// index.ts
import pk from "passkit-generator"
import 'dotenv/config'
import fs from "fs"

const PKPass = pk.PKPass;

try {
    const pass = await PKPass.from({
        model: "./model.pass",
        certificates: {
            wwdr: process.env.WWDR,
            signerCert: process.env.CERT,
            signerKey: process.env.KEY,
            signerKeyPassphrase: process.env.CHALLENGE
        },
    }, {
        // keys to be added or overridden
        serialNumber: "AAGH44625236dddaffbda"
    });

    const buffer = pass.getAsBuffer();

    fs.writeFile('pass.pkpass', buffer, (err) => {
        if (err) throw err;
        console.log('Buffer saved to file');
    });

} catch (err) {
    console.error(err)
}

{
  "organizationName": "My Org",
  "description": "My Event Description",
  "teamIdentifier": "******",
  "passTypeIdentifier": "******",
  "backgroundColor": "rgb(248,252,252)",
  "foregroundColor": "rgb(111,162,163)",
  "labelColor": "rgb(0,52,68)",
  "formatVersion": 1,
  "eventTicket": {
    "preferredStyleSchemes": [
      "posterEventTicket",
      "eventTicket"
    ]
  },
  "semantics": {
    "eventType": "PKEventTypeLivePerformance",
    "eventName": "South Bay Jazz Festival",
    "eventStartDate": "2024-07-15T10:00:00-06:00",
    "seats": [
      {
        "seatDescription": "Normal Seat",
        "seatIdentifier": "112-12-16",
        "seatNumber": "5",
        "seatRow" : "3",
        "seatSection": "100",
        "venueEntranceGate": "3"
      }
    ]
  }
}

Which, indeed, builds a pass that works, obviously using the old UI. Swapping out to the alpha you provided throws an error:

error: Object schema cannot be a joi schema
      at /Users/nick/Downloads/passkit/node_modules/passkit-generator/node_modules/@hapi/hoek/lib/error.js:25:1
      at /Users/nick/Downloads/passkit/node_modules/passkit-generator/node_modules/@hapi/hoek/lib/assert.js:19:30
      at method (/Users/nick/Downloads/passkit/node_modules/passkit-generator/node_modules/joi/lib/types/keys.js:413:21)
      at method (/Users/nick/Downloads/passkit/node_modules/passkit-generator/node_modules/joi/lib/types/keys.js:323:15)
      at /Users/nick/Downloads/passkit/node_modules/passkit-generator/lib/schemas/index.js:17:1
      at require (native:1:1)
      at /Users/nick/Downloads/passkit/node_modules/passkit-generator/lib/FieldsArray.js:48:25
      at require (native:1:1)
      at /Users/nick/Downloads/passkit/node_modules/passkit-generator/lib/PKPass.js:677:50
      at require (native:1:1)

[alexandercerutti]

@nickwelsh Are you able to see which property failed to validate?

[nickwelsh]

Seems like it's the new preferredStyleSchemes or rather the newly appended object in the schema. Removing the append() allows the pass to be built, but then preferredStyleSchemes isn't part of the schema and won't be included in the created pass.json.

// schemas/index.ts
// ...
eventTicket: PassFields.disallow("transitType").append(
		Joi.object<PassProps["eventTicket"]>().keys({
			/**
			 * New field coming in iOS 18
			 * `"eventTicket"` is the legacy style.
			 *
			 * If used, passkit will try to render following the old style
			 * first.
			 *
			 * Which means that `primaryFields`, `secondaryFields` and
			 * so on, are not necessary anymore for the new style,
			 * as semantics are preferred.
			 */
			preferredStyleSchemes: Joi.array().items(
				Joi.string().allow("posterEventTicket", "eventTicket"),
			),
		}),
	),
// ...

[alexandercerutti]

@nickwelsh interesting. Maybe I should have used .concat instead of that .append. What happens if you replace it? I've the commit ready, just in case.

[rayriffy]

I tried replace with .concat, and now PKPass are able to build without crashes. Verified with pass.json payload that data actually written.

Although, I have concerns with preferredStyleSchemes field, since it not as a part of PassFields. It means that I have to override it via .props which could make type-checking a bit tricky.

[alexandercerutti]

@rayriffy Hey, thanks for testing!

Two things:

1. Using .props to edit things it not the suggested way to do that as .props returns a deep clone of pass.json;

2. What Typescript says is tecnically right, eventTicket property might not exist cause your pass might not be of a type eventTicket. In a new version I could try to find a way to make it more safe, but I'm not exactly sure how. I could create and expose some Typescript narrowing guards...

Other than that, I still didn't provide a way to set manually the preferredStyleSchemes just like primaryFields and so on... maybe I should provide a just like the others.

[rayriffy]

thanks, although it's not a blocker though. you can make an improvements to an interface later in future version. for now i will have to forcefully mark that eventTicket actually exists.

pass.props.eventTicket!.preferredStyleSchemes = [...]

also i have another suggestion, currently i help testing your library by manually clone a project because referencing package with gtihub: in package.json does not includes any source code nor built code to use. my suggestion is in files also includes src/ directory, and make a script field prepare to run build:src should do the job

[alexandercerutti]

I've committed .concat and added a new getter/setter .preferredStyleSchemes to access and to set them with validation. Of course, both will throw if the type is not an eventTicket.

also i have another suggestion, currently i help testing your library by manually clone a project because referencing package with gtihub: in package.json does not includes any source code nor built code to use. my suggestion is in files also includes src/ directory, and make a script field prepare to run build:src should do the job

I never used github: protocol in NPM, but I think you can also get rid of it, as explained here and above in the same page: https://docs.npmjs.com/cli/v10/configuring-npm/package-json#github-urls

It should clone and provide the content from the repository. There, you should have the source.

Once you install the package from github, you can just change the directory to the dependency and use npm run build.

Let me know if it works.

Getting back to the pass, so, are you able to generate with with the new format?

[rayriffy]

unfortunately not at this moment, i tried with multiple relevant semantics fields and could not get it to work. lacking of documentation from apple is killing me, my best guess is maybe new event ticket format has not been added to the developer beta 1 yet.

maybe someone else also have a success? i would like to know as well.