Meet the Screen Time API

Welcome to WWDC.

I'm Christopher Skogen, an engineer on the Screen Time team, and I'm here to talk to you about the new Screen Time API. It's been three years since Apple introduced Screen Time for iOS. And it has been a giant step forward for improving our customers' and families' relationships with their devices.

Over the last three years, Screen Time brought some great new abilities to iPhone, iPad, and Mac. Screen Time helps you keep track of how often you and your family use apps and websites, manage time by setting limits, share usage with family members to provide a view of how your devices are being used, and finally, you can also manage who your children communicate with and more. We've also heard from many of you that you'd like to leverage some of these capabilities in your own parental controls apps.

So we've created the Screen Time API.

It brings the core Screen Time functionality to your apps so you can create dynamic new experiences for your customers. First off, the API will be available on iOS and iPadOS 15. It is 100% Swift and SwiftUI code for easy integration into your modern Swift applications.

The Screen Time API was designed and built with three guiding principles.

First, provide a modern, on-device framework for direct API access to existing restrictions. Our second guiding principle was to protect user privacy. Since Screen Time handles some very sensitive personal information such as apps you've used or web sites you've visited, Screen Time has always taken a very privacy-centric approach. For instance, there is no way for anyone outside of your family or even Apple to know which sites you've visited or what apps you use. For the new API, we continued this approach to privacy, and your customers' usage data will be invisible outside of their device. And finally, our third guiding principle was to ensure that you, the developers, can create fantastic new dynamic parental controls experiences. It's no coincidence that our three guiding principles led us to create three new frameworks. The three frameworks, taken together, comprise the Screen Time API. First, Managed Settings.

Managed Settings gives your app direct access to the same restrictions available in Screen Time. Second, Family Controls. Family Controls drives our privacy policy.

And finally, Device Activity. Device Activity allows you to go beyond Screen Time by giving your app great new abilities to run code without launching your app.

Let's take a closer look at all three frameworks. Let's start with Managed Settings. Your app needs a better way to restrict what a child can do with their devices and ensure that those restrictions remain in place until the parent or guardian says otherwise. With Managed Settings, your app can set a number of restrictions, like locking accounts in place, or preventing a password change, filter web traffic, or shield applications, much like Screen Time does, but customized with your app's branding and functionality. Next is Family Controls. By leveraging Family Sharing, Family Controls prevents access to the Screen Time API without guardian approval. Once your app has been approved by the guardian, it cannot be removed from the device without guardian approval. Additionally, Family Controls provides opaque tokens that represent apps and websites.

These tokens are used throughout the Screen Time API to monitor or restrict usage and ensure that no one outside of a single Family Sharing group will know what apps and websites are being used. And finally, Device Activity.

This framework allows you to go beyond Screen Time by giving your app new ways to monitor web and app usage and execute your code when needed. Because your app is a parental control app, it is very unlikely that a child will have a reason to run your app on their device. So how do you execute your code to set restrictions? The answer is Device Activity schedules and events. Device Activity schedules are time windows that call an extension in your application at the start and end of the time window. Events are usage monitors that call your extension when the user on the device reaches a usage threshold in a Device Activity schedule. Your app simply declares what type of usage it cares about and when it cares.

Combining all three frameworks together looks like this.

After your app is installed on both the guardian's and the child's devices, the guardian opens the app on the child's device. Your app authorizes with Family Controls. Later, your app on the guardian's device chooses settings, restrictions, and rules. Your app sends that information to the child's device. And then on the child's device, your app creates Schedules and Events with Device Activity. The Device Activity extension in your app gets called when the schedule occurs or the events happen.

From the extension, set restrictions with Managed Settings.

This is a good time to introduce Nolan. Nolan is working on a great new demo app, Homework, and he'll walk you through how Homework uses the Screen Time API. Hi, I'm Nolan, an engineer on the Screen Time team. I'd like to introduce you to my demo app, Homework. Homework encourages good habits by restricting a child's access to certain apps until they accumulate usage in other apps the guardian wants them to use. To make Homework functional, I'm gonna use all three frameworks in the Screen Time API.

First, I'll walk you through requesting authorization for Family Controls. Next up, I'll shield the discouraged apps selected by the guardian on a reoccurring schedule. Then I'll show you how to remove those shields after accumulating enough encouraged app usage. Finally, I'll customize the shields used by Homework to fit the app's branding and functionality. I'll start with the project setup and authorizing Family Controls.

In order to set up my Xcode project to include Family Controls capability, I'll go to the Project editor, select the app target, and under Signing and Capabilities, click the plus button. I'll search for Family Controls to find the capability and add it to my project.

Now that the capability has been added, I'm ready to code. The first thing Homework needs to do is request authorization for Family Controls. I'll use the shared authorization center in the Family Controls framework to make this request when my app launches.

The request can either result in success or failure. Calling this function will require a guardian in the family to approve Family Controls for Homework.

Since my app has never run on this iPhone before, requestAuthorization will ask for a guardian's approval with an alert. Tapping on Allow will then prompt the guardian to authenticate with their Apple ID and password to continue.

Once a guardian has successfully authenticated, calling requestAuthorization will not prompt with an alert again but instead silently return success. To prevent misuse, requestAuthorization will return failure if the signed-in iCloud is is not a child using Family Sharing. It's just that easy to get your app ready to use the Screen Time API.

Thanks, Nolan. We just saw our demo app, Homework, authorizing with Family Controls. Authorizing with Family Controls also grants other magic powers to your app. For instance, once the device is authorized, the user can no longer sign out of iCloud.

Also, on-device web content filters built with the Network Extensions framework can be included in your app and will be installed automatically and cannot be removed. This gives your app the ability to filter web traffic on the device.

One of the challenges in writing a parental controls app is getting your code to run on the child's device when the child will likely never run your app. For the Screen Time API, we created a new way to perform background code execution with Device Activity. A Device Activity extension will be your primary way to interact with the rest of the Screen Time API. Let's go back to Nolan to see how Homework can run code on a repeating schedule to restrict a child's device by placing a Screen Time shield over some apps.

Nolan. Thanks, Chris.

Next up with Homework is shielding the apps the guardian has chosen to discourage on a reoccurring schedule.

Since I cannot count on my app to be running on the child's device, I will use a Device Activity Schedule to set the application shield restriction every day, even when Homework hasn't run since being setup by the guardian.

When my Device Activity Schedule fires, Device Activity will call into a new extension point.

Homework will include an extension for this extension point where I will set the restriction to shield apps. Implementing an extension for this extension point requires you to subclass DeviceActivityMonitor as the principle class.

Here, I've overridden two methods in my extension's principle class: intervalDidStart and intervalDidEnd.

These functions will be called the first time the device is used after the start and end of my schedule.

I'm going to leave the implementation of these functions empty until I've configured my Device Activity schedule from Homework's main app.

Now that my Device Activity monitor extension is set up from the main app, I need to create a Device Activity name and a Device Activity schedule. The Device Activity name is how I can reference the activity from within my extension. And the Device Activity schedule represents the time bounds in which my extension will monitor for activity. Here I've set the name of my activity to "daily," and I've set my schedule to start and end at midnight.

I will also set this schedule to repeat. Finally, I can create a Device Activity center and call startMonitoring with the activity name and schedule I've just defined. With these few lines of code, my Device Activity monitor extension will be called with the activity name whenever the schedule starts and ends.

Another ingredient to shielding apps is figuring out what the guardian wants to discourage. The Family Controls framework has a SwiftUI element just for the job: The family activity picker. From the main app's UI, I can show the family activity picker and allow the guardian to choose from a list of apps, websites, and categories used by the family.

Once the guardian has made their selection, Homework can use opaque tokens returned by the picker to set restrictions on apps, websites, and categories each token represents. Here, I've added the familyActivityPicker view modifier to a Button in the app, and I've bound the picker's selection parameter to a property in the app's model. This will update my model whenever the guardian's selection is updated in the UI. Now that I have the guardian's discouraged app selection stored in my app's model, I'll jump back to the Device Activity Monitor extension. First, I'll drop in an import for the Managed Settings module to get access to the application shield restriction. Then in intervalDidStart, I can pull the selection out of the app's model and configure the application shield restriction accordingly. And in intervalDidEnd, I can remove the restriction by setting it to nil.

With these simple modifications, Homework will shield the guardian selected discouraged apps every day from midnight to midnight.

Back to you, Chris. Thanks, Nolan.

Shielding is not the only restriction available in Managed Settings.

We could also choose to set any number of restrictions at the beginning or end of a Device Activity Schedule.

For instance, your app could choose to prevent account creation or removal, completely block apps and websites, or deny media content by age.

Speaking of media restrictions, Managed Settings also provides an API that allows any app to read the restrictions for Movies and TV content.

No Family Controls authorization is required.

These functions are ideal for any media app to check if a device should be limiting the content presented to the user. In the Homework demo app, the restrictions were set at midnight every day, but what if you want to change restrictions based upon app or web usage? Device Activity has another feature that will allow your app to do just that: Device Activity events. These events are configured with the same tokens you saw from the family activity picker and allow you to execute code when the usage limits are reached. These events are registered alongside the schedules that Nolan showed us in the last segment. Now let's go check in with Nolan and see how these events work. I want to remove the application shield restriction not only when Homework's schedule ends but also when the child accumulates enough usage for a set of guardian-selected encouraged apps. To do that, I'll need to monitor the usage of these encouraged apps by configuring Device Activity to additionally call into my Device Activity monitor extension when a usage threshold is met.

Here, I'll define a Device Activity event name to be "encouraged." This name is how I can reference the event from within my extension.

And then I'll define my encouraged event to include the set of guardian-selected encouraged apps and the threshold of usage desired.

Finally, I'll update the call to startMonitoring to included the event I just defined.

Now that I am monitoring for Device Activity events from the main app, my Device Activity monitor extension is going to be called whenever any of those events meet their usage threshold. The function eventDidReachThreshold will be called with the Device Activity Event Name and the DeviceActivityName to identify which event fired for which scheduled activity. In Homework, I want to set the application shield restriction to nil when the extension gets notified for this event. Setting this restriction to nil will remove the shield from any of the previously shielded apps. Back to Chris. In the previous section, the discouraged apps were shielded with a default Screen Time shield. But you'll likely want to get your own branding and style in these shields.

You'll also probably want to have your own action handlers for the shield's buttons. We've got the tools for both. Custom shields allow you to create a unique branded experience. To customize the shields, you'll need to implement two new extension points defined in Managed Settings. One extension point allows you to customize the look of the shield by changing background material, titles, icon, and appearance of the buttons. And another extension point allows you to create custom button handlers. Let's go back to Nolan and see how you would customize your shields. To configure the look and feel of the custom shields for Homework, I need to start by subclassing ShieldConfigurationProvider as the principle class of the extension. Configuration is the only function you'll need to override here. This function is passed a reference to the application that is currently being shielded, and it is expected to return a ShieldConfiguration struct.

The ShieldConfiguration struct allows you to define the background effect, background color, icon, title, subtitle, primary button label, primary button background color, and secondary button label. Wow, that's a lot of customization. Once this struct is configured and returned by my shield configuration provider extension, the operating system will automatically display these customizations over any app shielded by Homework.

Now that we've styled the shields, I can use the second extension point in Managed Settings to configure the action handlers for the primary and secondary buttons. In this new extension, I'll subclass ShieldActionHandler as the principle class and override the function handle.

The handle function is told whether the primary button action or secondary button action was pressed and which application is currently being shielded.

You are required to call the function's completion handler with a sshield action response. The response can either be to close the shielded application or defer action and redraw the shield configuration.

The ability to defer action in the shield is very powerful because it gives the shield the chance to update its appearance while it waits for a signal on how to proceed.

For instance, it can be used to indicate that the shield is waiting for a guardian's action when the child taps Ask for Access here.

With the addition of these custom shields, my demo app, Homework, is complete. The guardian can choose apps to shield, such as games or entertainment, and remove the shield once the child has done enough positive screen time, like reading, learning, or being creative. Thanks for joining me in building this awesome new demo app. Now back to Chris.

Today we learned how our three goals-- to provide restrictions, protect privacy, and enable new dynamic experiences-- were delivered with the three frameworks that make up the Screen Time API. Managed Settings allows your app to enforce settings and restrictions. Device Activity allows your app to run code on a schedule or on usage events even when your app is not being used. And finally, Family Controls, which grants access to Managed Settings and Device Activity and protects the privacy of your users, guaranteeing that only the guardians will know what the child is doing. Like all frameworks, the Screen Time API will continue to evolve based on feedback from you. So give these a try and let us know how they do or don't support your unique use cases. Thanks for joining us today. Enjoy WWDC 2021. [music]