Experimenting with Stay Actions – Ole Begemann

iOS 16 beta 4 is the primary SDK launch that helps Stay Actions. A Stay Exercise is a widget-like view an app can place in your lock display screen and replace in actual time. Examples the place this may be helpful embody reside sports activities scores or practice departure instances.

These are my notes on enjoying with the API and implementing my first Stay Exercise.

A motorbike pc in your lock display screen

My Stay Exercise is a show for a motorcycle pc that I’ve been growing with a gaggle a pals. Right here’s a video of it in motion:

And right here with simulated information:

I haven’t talked a lot about our bike pc challenge publicly but; that can hopefully change sometime. Briefly, a gaggle of pals and I designed a bit field that connects to your bike’s hub dynamo, measures velocity and distance, and sends the info through Bluetooth to an iOS app. The app data all of your rides and also can act as a reside speedometer when mounted in your bike’s handlebar. It’s this final characteristic that I wished to copy within the Stay Exercise.

Comply with Apple’s information

Including a Stay Exercise to the app wasn’t onerous. I discovered Apple’s information Displaying reside information on the Lock Display with Stay Actions straightforward to observe and fairly complete.

No specific person approval

iOS doesn’t ask the person for approval when an app needs to indicate a Stay Exercise. I discovered this odd because it appears to ask builders to abuse the characteristic, however perhaps it’s OK due to the foreground requirement (see beneath). Plus, customers can disallow Stay Actions on a per-app foundation in Settings.

Customers can dismiss an lively Stay Exercise from the lock display screen by swiping (like a notification).

Most apps will most likely must ask the person for notification permissions to replace their Stay Actions.

The app should be within the foreground to start out an exercise

To start out a Stay Exercise, an app should be open within the foreground. This isn’t superb for the bike pc as a result of the speedometer can’t seem magically on the lock display screen when the person begins using (although iOS wakes up the app within the background at this level to ship the Bluetooth occasions from the bike). The person has to open the app manually a minimum of as soon as.

However, this limitation is probably not a problem for many use circumstances and can most likely minimize down on spamming/abuse considerably.

The app should maintain working within the background to replace the exercise (or use push notifications)

So long as the app retains working (within the foreground or background), it may possibly replace the Stay Exercise as usually because it needs (I believe). That is superb for the bike pc because the app retains working within the background processing Bluetooth occasions whereas the bike is in movement. I assume the identical applies to different apps that may stay alive within the background, equivalent to audio gamers or navigation apps doing steady location monitoring.

Updating the Stay Exercise as soon as per second was no downside in my testing, and I didn’t expertise any price limiting.

Most apps get suspended within the background, nonetheless. They have to use push notifications to replace their Stay Exercise (or background duties or another mechanism to have the system wake you up). Apple launched a brand new form of push notification that’s delivered on to the Stay Exercise, bypassing the app altogether. I haven’t performed with push notification updates, so I don’t know the advantages of utilizing this technique over sending a silent push notification to wake the app and updating the Stay Exercise from there. Most likely much less aggressive price limiting?

Lock display screen coloration matching

I haven’t discovered a great way to match my Stay Exercise’s colours to the present system colours on the lock display screen. By default, textual content in a Stay Exercise is black in mild mode, whereas the built-in lock display screen themes appear to favor white or different mild textual content colours. If there’s an API or setting worth that permits apps to match the colour model of the present lock display screen, I haven’t discovered it. I experimented with varied foreground kinds, equivalent to supplies, with out success.

I ended up hardcoding the foreground coloration, however I’m not glad with the consequence. Relying on the person’s lock display screen theme, the Stay Exercise can look misplaced.

Animations can’t be disabled

Apple’s information clearly states that builders have little management over animations in a Stay Exercise:

Animate content material updates

Once you outline the person interface of your Stay Exercise, the system ignores any animation modifiers — for instance, withAnimation(_:_:) and animation(_:worth:) — and makes use of the system’s animation timing as an alternative. Nonetheless, the system performs some animation when the dynamic content material of the Stay Exercise adjustments. Textual content views animate content material adjustments with blurred content material transitions, and the system animates content material transitions for photographs and SF Symbols. Should you add or take away views from the person interface primarily based on content material or state adjustments, views fade out and in. Use the next view transitions to configure these built-in transitions: opacity, transfer(edge:), slide, push(from:), or mixtures of them. Moreover, request animations for timer textual content with numericText(countsDown:).

It makes complete sense to me that Apple doesn’t need builders to go loopy with animations on the lock display screen, and maybe having full management over animations additionally makes it simpler for Apple to combine Stay Actions into the always-on show that’s most likely approaching the following iPhone.

What shocked me is that I couldn’t discover a method to disable the textual content change animations altogether. I discover the blurred textual content transitions for the massive velocity worth fairly distracting and I believe this label would look higher with none animations. However no mixture of .animation(nil), .contentTransition(.identification), and .transition(.identification) would do that.

A Stay Exercise could be very very similar to a widget: the UI should reside in your app’s widget extension. You begin the Stay Exercise with code that runs in your app, although. Each targets (the app and the widget extension) want entry to a typical information kind that represents the info the widget shows. You must have a 3rd goal (a framework or SwiftPM package deal) that comprises such shared varieties and APIs and that the downstream targets import.

Availability annotations

WidgetBundle apparently doesn’t help widgets with completely different minimal deployment targets. In case your widget extension has a deployment goal of iOS 14 or 15 for an current widget and also you now wish to add a Stay Exercise, I’d anticipate your widget bundle to appear like this:

@predominant
struct MyWidgets: WidgetBundle {
  var physique: some Widget {
    MyNormalWidget()
    // Error: Closure containing management move assertion can not
    // be used with consequence builder 'WidgetBundleBuilder'
    if #accessible(iOSApplicationExtension 16.0, *) {
      MyLiveActivityWidget()
    }
  }
}

However this doesn’t compile as a result of the consequence builder kind utilized by WidgetBundle doesn’t help availability situations. I hope Apple fixes this.

This wasn’t an issue for me as a result of our app didn’t have any widgets till now, so I simply set the deployment goal of the widget extension to iOS 16.0. In case you have current widgets and may’t require iOS 16 but, a workaround is so as to add a second widget extension goal only for the Stay Exercise. I haven’t tried this, however WidgetKit explicitly helps having a number of widget extensions, so it ought to work:

Usually, you embody all of your widgets in a single widget extension, though your app can comprise a number of extensions.