Creating an App Walk-Through for the Playgrounds App

Swift Playgrounds Icon

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.swift

However, 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.

Moving your app from Swift Playgrounds to Xcode

Swift Playgrounds Icon

There comes a time in every person’s life when they find they need to move from their beautiful little app they created in Swift Playgrounds to the big, bad world of Xcode.

Okay, maybe not every person’s life.

But there might come that time.

Getting it to your Mac

First off, you need to get the Playground app over to your Mac, and my personal favorite way is with AirDrop.

You can share your Playgrounds by tapping on the title, if you have it open in Playgrounds, or you can choose Select and then Share from the screen with all the playgrounds visible. Once you’ve AirDropped the app to your Mac, you’ll see a file that says (if you have show file extensions turned on) My App.swiftpm.

And you can open that in Xcode, by right-clicking on the file (or selecting it in the Finder and choosing the Action menu and selecting Open With… Xcode.app:

When?

But when would we want to do something like that?

More Features from our Development Environment

Well, sometimes we want to take advantage of some of the pro features Xcode has that Playgrounds doesn’t. Things like:

  • Powerful debugging capabilities;
  • Instruments for analyzing your app’s performance;
  • Simulators of all kinds of iPhone, iPad, Apple Watch, and other devices;
  • More information on the bigger screen of your laptop with navigator panes, inspector panes, preview canvas, code editors, and more;
  • Source control integration with platforms like Github…

Especially if we’re familiar with Xcode, we may be super comfortable with all the tools it has built in to help us build our apps quicker and more efficiently.

With this as our main reason, we’re still in pretty good shape. We can leave the app in its .swiftpm project file format.

When we do this, it means we can edit our app in Xcode on our Mac and then AirDrop it (or save it in iCloud) to edit on the iPad in Playgrounds, as well.

We Need More Advanced Features for our App

We can get incredibly far with Playgrounds and app development, even shipping apps all the way to the App Store and selling them!

But there are a few features of Xcode-based projects that might entice you to move over, or you might need to move over, to implement certain features in your app. For example:

  • Easier device and orientation support – Xcode projects make it easier to tick a box and restrict an app to iPhone Portrait view or any number of combinations;
  • Even more capabilities, like iCloud support, Apple Pay support, custom Fonts, Game Center…;
  • Multiple targets, Xcode Cloud support from the development environment;
  • Storyboards and UIKit support with Interface Builder

Making the Leap

If you do decide, yep, I want some of those extra features, so I’m moving to Xcode, just a word of warning: you can’t AirDrop an Xcode Project-based app back onto your iPad and work on it in Playgrounds.

In the video below, I show you one way to do this, and some ways to get out of the trouble you might find yourself in with some common issues that arise.

You can get pretty far with Swift Playgrounds. In fact, at the start of the video I show you how to add functionality to your Playgrounds app using packages, and the way to do the same in Xcode.

But if, for any of the reasons listed above, you feel like you need to move to Xcode, or just want to check it out, the video will help you see how that can be done.

Best of luck, and if it’s your first time using Xcode, welcome to the Show!