Creating a walk-through for Swift Playgrounds can sometimes feel like wrestling a bag of eels in a room with all the lights burnt out.
Walk-throughs are a great way to set up content that learners can go through at their own pace as if they had a very patient senior software engineer sitting beside them, walking them through the code. I’ve written a few on my Adventures feed (https://www.thecodehub.ie/playgrounds/) and they’re such a good way to help focus on specific app development techniques or tools people may have been asking about, but I’m not necessarily going to be there in the room with them.
There is a great WWDC talk from 2022, when the app launched, walking you through how to create content, but it’s not always so easy:
WWDC 22: Create engaging content for Swift Playgrounds: https://developer.apple.com/wwdc22/110349
I’ve recorded a video of many of these steps, and a few troubleshooting notes down below, even, about some common things you might want in your walk-through.
Walk-Through Surgery
First, you’re going to be doing some surgery inside your app’s folder structure, and they demo it using the Finder to create an App folder and they put everything in there, except for the Package.swift file, which is the file that tells the Swift compiler what the project should look like, how to build it, what to include, and all the rest.
You should then create a Guide folder in the same folder that now contains the App folder (it’s also called a module, if you listen to the video above).
So your app looks like this:
MyApp.swiftpm/
App/
MyApp.swift
ContentView.swift
Guide/
Guide.tutorial
Package.swiftHowever, this isn’t going to display a walk-through, just yet.
In the Guide.tutorial file, you’ll need something that looks like this:
@GuideBook(title: "Get Started with App Walk-Throughs", icon: title.png, background: background.png, firstFile: MyApp.swift) {
@Guide {
@Step(title: "Get Started with App Walk-Throughs") {
@ContentAndMedia {
Our first test step...
}
}
}
}Even if you don’t have the title.png or background.png files, you need to have those parameters in the GuideBook().
This guide contents above is the bare minimum with which I’ve been able to get a walk-through to appear. From there you can follow all the advice and tips in the WWDC video above, and you’ll have a chance to build some amazing content.
Going Further
Now, if you get to the stage where you want to add resources to your guide; images, localized strings, a glossary, you may run into some further issues getting that walk-through to display.
If you try to add a folder in Playgrounds called ‘Resources’ you’ll hit your first roadblock, because Playgrounds won’t let you, because that’s a reserved folder name.
So over to the Mac we go.
As I mentioned in a previous post, you can open Swift Playgrounds apps in Xcode on the Mac (https://www.thecodehub.ie/news/2024/06/19/moving-your-app-from-swift-playgrounds-to-xcode/). We don’t quite need to go that far, but there are some handy things Xcode will help you create if you want to build localized walk-throughs.
On the Mac, right-click or use the action menu to show the package contents of your app.
In the Guide folder, create another folder called Resources. Here we can drop images to display in the guide, like the title.png and background.png above.
If you do want to take the next step and add a localized strings file, just a warning, you will have to dive into the Package.swift file and add a property to the top level:
defaultLocalization: "en",(Or whatever your default localization will be.) Otherwise Playgrounds will complain that you need this key so it knows which strings to load for your walk-through.
If you Show Package Contents on the app and then double-click the Package.swift file. It should open up in Xcode, if you have that installed, and you’ll add that line above just beneath the name: “MyApp”, line.
Troubleshooting
One of the things I always struggle with, when confronted with those “Failed to create… SPCGuideBook.Type” messages, is getting the welcome message to show. The thing I’ve found, to get a Welcome Message to show up properly, is that you need to pick a View file, I’m almost certain.
So if your tutorial file looks like this:
@GuideBook(title: "Get Started with App Walk-Throughs", icon: icon.png, background: background.png, firstFile: MyApp.swift) {
@WelcomeMessage(title: "Get Started with App Walk-Throughs") {
Welcome to the show
}
@Guide {
@Step(title: "Get Started with App Walk-Throughs") {
@ContentAndMedia {
Our first step...
}
}
}
}it’s likely you’ll see the error message about it not being able to be loaded.
So you might try changing your tutorial file to look like this, instead (note the change in bold):
@GuideBook(title: "Get Started with App Walk-Throughs", icon: icon.png, background: background.png, firstFile: ContentView.swift) {
@WelcomeMessage(title: "Get Started with App Walk-Throughs") {
Welcome to the show
}
@Guide {
@Step(title: "Get Started with App Walk-Throughs") {
@ContentAndMedia {
Our first step...
}
}
}
}Remember to close and reload your playground apps when you change the walk-through… that can be one of the biggest hassles about authoring app walk-throughs, but once you get a walk-through loaded it’s usually far, far easier to troubleshoot little missteps here and there.
