Booky Demo App
ℹ️ ABOUT
Booky is a work-in-progress, heavily-commented demo app built to explore Apple's new 'App Intents' framework introduced in iOS 16.
This API lets you extend actions from your app into other areas of the OS - for example the Shortcuts app and Siri.
Functionally, Booky is a basic library you can add books to and mark them as read or unread. It's runnable code that is conceptually and structurally similar to the examples provided in WWDC22's 'Dive Into App Intents' session.
Technically, Booky is built using SwiftUI and persists saved books to a local CoreData store. It has only been tested on iPhone but the code should run on iPad (though the UI hasn't been optimised for it yet).
When you first open the app, three dummy books will be added to the library for testing. Please note that the functionality is extremely bare bones. Testing, error handling and localization are all currently absent. Hopefully, however, it'll be a useful playground to help explore some of what the App Intents framework has to offer.
There are some known issues with the app (see 'Known Issues' below) - I'll try and iron these out as the betas progress.
Here are some of the things covered by Booky:
- 5x Shortcut actions
- Foreground & background actions
- Conditional parameter summaries
- Rich confirmation prompts
- Dynamic lookup parameters with thumbnails and subtitles
- Custom entity with queryable properties
- Action library categories
- Custom errors
- Snippet results
⚙️ SHORTCUTS ACTIONS
Booky has five actions (or 'intents') that it provides to the Shortcuts app:
ADD BOOK
Add a new book to the library.
This action has properties of various types which support different input options, such as per-word keyboard capitalization.
It displays a SwiftUI 'Snippet' UI (functionally similar to a Homescreen widget) showing a preview of the new book when it completes successfully.
It also outputs a rich custom 'Book' entity for use in the next action.
MARK BOOKS AS READ
Mark multiple books as either read or unread.
This action has a parameter that accepts an array of a custom Book entities. When tapped, it populates a dynamic, filterable list of Books that display along with images. It is sectioned into a 'read' & 'unread' section using a DynamicOptionsProvider.
It also demonstrates how to use an enum to create a fixed multiple-choice parameter.
OPEN BOOK
Opens the chosen book in the Booky app or navigates to the root library view.
This action demonstrates how to perform a foreground action in your app from Shortcuts. It opens the app and uses the new programmatic navigation API in SwiftUI to either jump to a specific detail view or clear the navigation stack.
It uses the Switch/Case API in ParameterSummary to display a conditional summary depending on which option is chosen.
DELETE BOOKS
Deletes the selected books from the library.
This action demonstrates how to prompt the user with an optional confirmation (containing images in a Snippet) before deleting the books.
It uses the ParameterSummary's When/Otherwise API.
FIND BOOKS ⚠️
New in iOS 16, this action is automatically added when you add a custom entity with a query that conforms to EntityPropertyQuery (Not sure this is actually correct since it currently shows when conforming to EntityStringQuery/EntityQuery too?).
This action allows the user to query Booky's database for Books using combinations of property queries. For example:
Books published after the year 2000 that are unread.
✅ REQUIREMENTS
If Booky's shortcut actions aren't showing in the Shortcuts app, make sure xcode-select is pointing to the correct Xcode, as per the Xcode release notes for Dev Beta 1
⚠️ KNOWN ISSUES (as of dev beta 4)
- The 'Find Books' action isn't working yet.
- As of dev beta 3, Shortcuts won't show in the Shortcuts app when building as
Releaserather thanDebug(TestFlight etc). A workaround for this is to explicitly mark all App Intents asPublic. This is noted under the 'Swift' section of the release notes Adding any code comments to the App Intent'sparameterSummarymethod causes the summary not to render in ShortcutsInput options seem to have no effect - for example the Title & Author parameters in the Add Book action should be capitalized by word (FB10200372)The text colour in a Snippet view doesn't show the correct (lighter) colour in dark mode (FB10209882)The Delete Books parameter sumary doesn't show correctly, instead showing as if none has been set. I believe this is an issue withParameterSummary's When/Otherwise API (FB10208191)Long-pressing a File parameter in the list UI (as opposed to the parameter summary) has no effect, which makes it impossible to select a magic variable (FB10191345)The Book entity display name is not showing correctly (FB10210421)When tapping on an action's parameter that accepts a customShortcutsBookEntity, the filtering isn't working. Theentities(matching String)never seems to get called. (FB10213109)
🎓 STILL TO EXPLORE
- Booky currently uses singletons for CoreData access and ViewModel changes but it seems the better way to access the app's state in the App Intent's 'perform' method is by using dependency injection with IntentDependency & IntentDependencyManager
- PredictableIntent protocol
- App Shortcuts - Shortcuts containing a single action that are automatically added by the developer to the Shortcuts app
- Customising donated intents based on user behaviour & specific sets of parameters
- Intent discovery documentation
- Focus Filters
- Resolvers
- Live Activity Snippets
- Siri dialog improvements (for example for errors)
- Localization
- Matching legacy SiriKit intents to prevent duplicates
📚 FURTHER READING
- WWDC SESSIONS
- DOCUMENTATION
- SAMPLE CODE
- Apple's Food Truck example app. This cross-platform app includes one basic intent that displays a chart in a Snippet. It also implements App Shortcuts.
- RELEASE NOTES
📨 CONTACT
Questions, code contributions & contructive feedback welcome. I don't have a clue what I'm doing.
You can find me on Twitter: @mralexhay.