ueman/passkit

Various Dart & Flutter packages to work with Apple's PassKit

passkit's Issues

bug(passkit): WebServiceUrl with path does not work

When the web service URL of the pass contains a path, it will currently get overriden.

This seems incorrect to me and I think we should fix it.
However, the spec doesn't mention any specific behavior, so the current implementation could be correct.

Add icons for all transit types

See

passkit/passkit_ui/lib/src/widgets/transit_type_widget.dart

Lines 20 to 24 in d3ff006

	TransitType.air => PlaneIcon(color: color, width: width),
	TransitType.boat => PlaneIcon(color: color, width: width),
	TransitType.bus => PlaneIcon(color: color, width: width),
	TransitType.generic => PlaneIcon(color: color, width: width),
	TransitType.train => PlaneIcon(color: color, width: width),

Right now, the only icon used is the plane icon, but we need

• bus
• generic
• boat
• train

Ideally there's a CC0 SVG that can be used via

• https://www.flutterclutter.dev/tools/svg-to-flutter-path-converter/
• https://fluttershapemaker.com/#/

to create a Custom Painter out of it.

☂️ App features

Umbrella issue to collect various app feature ideas:

• Export to calendar support
• Group passes based on the grouping identifier
• hide voided & no longer relevant passes
• Add calendar view
• Personalization & signup flow for supported passes
• Automatic updates of passes that support it
• Support semantic tags
• Support for importing .pkpasses bundles
• Support for .order files
• Homewidget
  • With QR/barcodes for passes
  • order status for orders

Add support for importing PkPass bundles

PkPass bundles are essentially a zip (but with a pkpasses file extension) which contains up to 10 pkpass files.

https://developer.apple.com/documentation/walletpasses/distributing_and_updating_a_pass#3793284

Fix sizing of the passes

The passes seem like they have an aspect ratio of something around of 3 (width) to 4 (height) (310 to 400).
We need to figure out how to properly size the passes so that they're always following this aspect ratio while still having a good a11y.

PkPass creation

• https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/YourFirst.html#//apple_ref/doc/uid/TP40012195-CH2-SW1

• https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html#//apple_ref/doc/uid/TP40012195-CH4-SW1

• https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/DistributingPasses.html#//apple_ref/doc/uid/TP40012195-CH11-SW1

• To create the manifest file, recursively list the files in the package (except the manifest file and signature), calculate the SHA-1 hash of the contents of those files, and store the data in a dictionary. The keys are relative paths to the file from the pass package. The values are the SHA-1 hash (hex encoded) of the data at that path. Write this dictionary to the file manifest.json at the top level of the pass package.

• To create the signature file, make a PKCS #7 detached signature of the manifest file, using the private key associated with your signing certificate. Include the WWDR intermediate certificate as part of the signature. You can download this certificate from Apple’s website. Write the signature to the file signature at the top level of the pass package. Include the date and time that the pass was signed using the S/MIME signing-time attribute.

  • Look into pointycastle and pkcs7 to sign the pass in pure Dart code

The WWDR certificate can be downloaded from here.

Compare signature for pass updates

When updating a pass via the HTTP client, we should check whether the pass is signed with the same certificate to check for its authenticity. This method should also be exposed, so that updates from other sources (downloads etc) can do the same check.

Make links/phone numbers/emails clickable in passes

Description

The text of the back fields is run through data detectors for URLs and phone numbers, which appear as live links. Users can tap the URL to launch it in Safari and can tap phone numbers to dial them. Text on the back of the card can include line breaks, escaped in the JSON file as \n.

• Source

This is currently unsupported in passkit_ui.
Maybe something like flutter_linkify can solve this problem.

Add an async method to parse PkPass files

Description

Synchronous parsing of the PkPass files can lead to skipped frames when this lib is used in Flutter. Provide an option to parse them on a background isolate

UI for coupon passes

Docs:

• https://developer.apple.com/design/human-interface-guidelines/wallet#Coupons
• https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html#//apple_ref/doc/uid/TP40012195-CH4-SW8

Reference images

• 
• 
• 

feat(passkit_ui): make pass theme a theme extension

Description

For reference: ThemeExtension.

Support for localization in PkPass files

Text can be localized, but images can be localized too.

PkPass docs for localizations (text and images):

• https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html#//apple_ref/doc/uid/TP40012195-CH4-SW54
• https://developer.apple.com/documentation/walletpasses/creating_the_source_for_a_pass

Docs for .strings file format description:

• https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/LoadingResources/Strings/Strings.html

.strings files are UTF-16 not UTF-8, so the files have to be read like this StackOverflow post suggests. This issue dart-lang/convert#30 contains some hints too.

---

There are various approaches to parsing a .strings file:

• use a regex (I believe strings files for pkpasses technically can't have placeholders)
• write a custom parser using petiteparser
• naive custom string parsing

Personally, I would like to see a custom parser based on petiteparser with all the bells and whistles, but I think using a RegEx at first should be sufficient.

---

The API could look like one of the following examples:

class PkPass {
  String getTranslated(String key, Locale locale) { ... }
}

// and then you can use it something like this:

PkPass pass = ...;
pass.getTranslated(pass.pass.description, locale);

With intl

pass.pass.description;
// provide a localized getter that makes use of Intl.defaultLocale or is alternatively set somehow
pass.pass.descriptionLocalized;

---

This paragraph is only relevant for passkit_UI

Language fallback rules (should be applied on a per field basis):

1. No translations -> Nothing gets translated
2. The users' language gets chosen if available (e.g. de_DE)
   • Localizations.of(context).locale
3. The users' language without country code gets chosen if available (e.g. de instead of de_DE)
   • Localizations.of(context).locale
4. Otherwise, fallback to what's reported via PlatformDispatcher.locales (while skipping already tried languages)
   • First the languages are tested with country codes (de_DE), then without (just de)
5. If a translation is missing, fall back to the translation key

Formatted values like dates, numbers, etc are always localized to the users' current language (as described here)

---

The default localized value should be https://api.dart.dev/stable/3.4.4/dart-io/Platform/localeName.html on dart:io and whatever browser equivalent there is. On Flutter it should use the Localization.of().locale as default.

Support for PkPass personalization fields

See https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/PassPersonalization.html#//apple_ref/doc/uid/TP40012195-CH12-SW2

Use CarouselView for currently relevant passes

https://main-api.flutter.dev/flutter/material/CarouselView-class.html

The currently relevant passes are selected based on the location and date.

Support Googles wallet format

Relevant links:

• https://developers.google.com/wallet
• https://github.com/google-wallet/rest-samples
• https://developers.google.com/wallet/retail/loyalty-cards/resources/pass-builder

PassKit creation UI

It would be nice if it's possible to create PkPass files with a WYSIWYG editor.
Depends on #11

Signature verification

Description

Currently, a PkPass files checksums is not verified. This functionally should be added. I also would like an option to optionally skip checksum verification.

I guess this can easily be done by using package:crypto, for signature verification, look into pointycastle and pkcs7

Docs: https://developer.apple.com/documentation/walletpasses/building_a_pass#3732525

• Checksum validation
• Signature validation

Trigger pull request verification on each change

Right now, the pull request verification doesn't get triggered when the title changes and the job has to be manually restarted. That's quite annoying and should be fixed

UI for generic passes

Docs:

• https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html#//apple_ref/doc/uid/TP40012195-CH4-SW8
• https://developer.apple.com/design/human-interface-guidelines/wallet#Generic-passes

Reference images:

PkPass diffing for change messages

When a PkPass file is updated, the system is supposed to show a change message notification/hint (depending on whether it was updated in background/foreground).
This is done by comparing the fields of the old and updated pass.

Those fields with a change message should be returned with a properly formatted change message. Otherwise, a generic message should be returned.

An open question is whether those fields support localization, but I would assume so.

We could provide an API that looks something like this:

class PkPass {
  List<String> getChangeMessages(PkPass oldPass, String locale) {
    // ...
  }
}

final changeMessages = newPass.getChangeMessages(oldPass, 'de_DE');

Show NFC icon in the lower right corner for NFC enabled passes

Passes show an icon in the lower right corner if they're NFC enabled. The passkit_ui package should show it too. Ideally, it can be toggled though, since it still has to be enabled by the consuming application.

Support wallet orders

Description

For documentation, see the following links:

• https://developer.apple.com/documentation/walletorders
• https://developer.apple.com/documentation/walletorders/order
• https://developer.apple.com/design/human-interface-guidelines/wallet#Order-tracking
• Examples: https://developer.apple.com/documentation/walletorders/example_order_packages
  • Direct download
• https://applepaydemo.apple.com/order-tracking

Tasks:

• web service support
• readme additions
• UI for orders

Improve readme

• explain limitations of the packages
• add some motivation
  • why is it needed, what does it solve?
• add images to packages (and maybe automate via golden image tests?)
• Improve linking to Apple docs in the readme
• Encourage people to contribute by directing them to relevant issues by making use of the tags
• Add a contributors section to each readme
• add cross references to each package
• cross check readme guidance from here: https://dart.dev/tools/pub/writing-package-pages

Individual check marks can be done in separate PRs

Maintenance: Add JsonKey annotations

By adding JsonKey annotations, we ensure that deserialization is less prone to break due to refactorings. Additionally, we're able to give properties names that are idiomatic to Dart.
It probably also makes it easier to migrate to macros when the time comes.

UI for Event passes

Docs:

• https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html#//apple_ref/doc/uid/TP40012195-CH4-SW8
• https://developer.apple.com/design/human-interface-guidelines/wallet#Event-tickets

Reference images:

Concrete example

The event example PkPass from the Apple Docs should look like the following image:

Add missing `row` attribute

https://developer.apple.com/documentation/walletpasses/passfields/auxiliaryfields

UI for boarding passes

Docs:

• https://developer.apple.com/design/human-interface-guidelines/wallet#Boarding-passes
• https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html#//apple_ref/doc/uid/TP40012195-CH4-SW1

(https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html#//apple_ref/doc/uid/TP40012195-CH4-SW8).

Reference images

Concrete example

This pass file example.zip (change file extension back to pkpass) should look like the following screenshot

refactor(passkit_ui): turn widget tests to golden

Description

If there are purely presentational widgets with no added functionality, they should be migrated to be a golden test.
Worth checking package:alchemist.

PassKit Web Service

General docs: https://developer.apple.com/documentation/walletpasses/adding_a_web_service_to_update_passes

• Log a message (works everywhere)
  • https://developer.apple.com/documentation/walletpasses/log_a_message
  • #7
• Get a pass update (works everywhere)
  • https://developer.apple.com/documentation/walletpasses/send_an_updated_pass
  • #7
• Register for notifications (iOS only due to APNS requirement)
  • https://developer.apple.com/documentation/walletpasses/register_a_pass_for_update_notifications
• Get a list of updatable passes (Maybe works on non-Apple platforms?)
  • https://developer.apple.com/documentation/walletpasses/get_the_list_of_updatable_passes
• Unregister notifications updates (again iOS only)
  • https://developer.apple.com/documentation/walletpasses/unregister_a_pass_for_update_notifications
• Personalized passes (probably works cross platform)
  • https://developer.apple.com/documentation/walletpasses/return_a_personalized_pass

Notes

Is there a test server that implements all of these thingies? Otherwise, I'm not sure how to properly end-to-end test this.

Add method to `FieldDict` which formats the value

Something along the lines of

String getFormatted(String locale) {
  if(numberstyle != null) {
    // return formatted number
  }
  if(datestyle != null) {
    // return formatted date
  }
  // and so on
}

UI for StoreCard passes

Docs:

• https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html#//apple_ref/doc/uid/TP40012195-CH4-SW8
• https://developer.apple.com/design/human-interface-guidelines/wallet#Store-cards

Reference images:

Create PkPass server package

Description

Create a package, which implements the backend interface for the various services mentioned in #9

There are multiple popular Dart web frameworks:

• dart_frog
• serverpod
• shelf

shelf and dart_frog are somewhat compatible, so it may make sense to choose shelf as a target.

---

The push notification format is described here https://stackoverflow.com/a/15878404 and a sample implementation can be found here https://github.com/drallgood/jpasskit

Rewards enrollment for NFC enabled passes

Docs can be found at https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/PassPersonalization.html#//apple_ref/doc/uid/TP40012195-CH12-SW2