Dwell Actions, first launched in iOS 16, are one in all Apple’s most fun updates for creating apps that really feel extra related to customers in actual time. As an alternative of requiring customers to continually reopen an app, Dwell Actions let info stay seen proper on the Lock Display screen and Dynamic Island. Whether or not it is monitoring a meals supply, checking sports activities scores, or monitoring progress towards a aim, this characteristic retains vital updates only a look away.
Later in iOS 17, Apple expanded Dwell Actions even additional by supporting push updates from the server facet, which makes them much more highly effective for apps that depend on real-time info. However even with out server-driven updates, Dwell Actions are extremely helpful for client-side apps that wish to enhance engagement and supply well timed suggestions.
On this tutorial, we’ll discover methods to implement Dwell Actions by constructing a Water Tracker app. The app permits customers to log their every day water consumption and immediately see their progress replace on the Lock Display screen or Dynamic Island. By the tip of the tutorial, you will perceive methods to combine Dwell Actions into your SwiftUI apps.
A Fast Have a look at the Demo App
Our demo app, Water Tracker, is a straightforward and enjoyable solution to preserve monitor of your every day water consumption. You’ve in all probability heard the recommendation that ingesting eight glasses of water a day is an effective behavior, and this app helps you keep aware of that aim. The design is minimal on objective: there is a round progress bar exhibiting how far alongside you’re, and each time you faucet the Add Glass button, the counter goes up by one and the progress bar fills slightly extra.
Behind the scenes, the app makes use of a WaterTracker class to handle the logic. This class retains monitor of what number of glasses you’ve already logged and what your every day aim is, so the UI all the time displays your present progress. Right here’s the code that makes it work:
import Commentary
@Observable
class WaterTracker {
var currentGlasses: Int = 0
var dailyGoal: Int = 8
func addGlass() {
guard currentGlasses < dailyGoal else { return }
currentGlasses += 1
}
func resetDaily() {
currentGlasses = 0
}
var progress: Double {
Double(currentGlasses) / Double(dailyGoal)
}
var isGoalReached: Bool {
currentGlasses >= dailyGoal
}
}
What we’re going to do is so as to add Dwell Actions assist to the app. As soon as carried out, customers will be capable to see their progress instantly on the Lock Display screen and within the Dynamic Island. The Dwell Exercise will present the present water consumption alongside the every day aim in a transparent, easy means.
Dwell Actions are constructed as a part of an app’s widget extension, so step one is so as to add a widget extension to your Xcode undertaking.
On this demo, the undertaking is known as WaterReminder. To create the extension, choose the undertaking in Xcode, go to the menu bar, and select Editor > Goal > Add Goal. When the template dialog seems, choose Widget Extension, give it a reputation, and ensure to examine the Embody Dwell Exercise choice.
When Xcode asks, remember to activate the brand new scheme. It can then generate the widget extension for you, which seems as a brand new folder within the undertaking navigator together with the starter code for the Dwell Exercise and the widget.
We’ll be rewriting your entire WaterReminderWidgetLiveActivity.swift file from scratch, so it’s greatest to filter all of its present code earlier than continuing.
For the reason that Dwell Exercise doesn’t depend on the widget, you possibly can optionally take away the WaterReminderWidget.swift file and replace the WaterReminderWidgetBundle struct like this:
struct WaterReminderWidgetBundle: WidgetBundle {
var physique: some Widget {
WaterReminderWidgetLiveActivity()
}
}
Defining the ActivityAttributes Construction
The ActivityAttributes protocol describes the content material that seems in your Dwell Exercise. We’ve got to undertake the protocol and outline the dynamic content material of the exercise.
Since this attributes construction is often shared between each the principle app and widget extension, I recommend to create a shared folder to host this Swift file. Within the undertaking folder, create a brand new folder named Shared after which create a brand new Swift file named WaterReminderWidgetAttributes.swift.
Replace the content material like this:
import Basis
import ActivityKit
struct WaterReminderWidgetAttributes: ActivityAttributes {
public struct ContentState: Codable, Hashable {
var currentGlasses: Int
var dailyGoal: Int
}
var activityName: String
}
extension WaterReminderWidgetAttributes {
static var preview: WaterReminderWidgetAttributes {
WaterReminderWidgetAttributes(activityName: "Water Reminder")
}
}
extension WaterReminderWidgetAttributes.ContentState {
static var pattern: WaterReminderWidgetAttributes.ContentState {
WaterReminderWidgetAttributes.ContentState(currentGlasses: 3, dailyGoal: 8)
}
static var goalReached: WaterReminderWidgetAttributes.ContentState {
WaterReminderWidgetAttributes.ContentState(currentGlasses: 8, dailyGoal: 8)
}
}
The WaterReminderWidgetAttributes struct adopts the ActivityAttributes protocol and contains an activityName property to determine the exercise. To adapt to the protocol, we outline a nested ContentState struct, which holds the info displayed within the Dwell Exercise—particularly, the variety of glasses consumed and the every day aim.
The extensions are used for SwiftUI previews, offering pattern information for visualization.
Please take be aware that the goal membership of the file must be accessed by each the principle app and the widget extension. You may confirm it within the file inspector.
Implementing the Dwell Exercise View
Subsequent, let’s implement the dwell exercise view, which handles the consumer interface in several settings. Open the WaterReminderWidgetLiveActivity.swift file and write the code like beneath:
import ActivityKit
import WidgetKit
import SwiftUI
struct WaterReminderLiveActivityView: View {
let context: ActivityViewContext
var physique: some View {
VStack(alignment: .main, spacing: 10) {
HStack {
Textual content("💧")
.font(.title)
Textual content("Water Reminder")
.font(.headline)
.fontWeight(.semibold)
Spacer()
}
HStack {
Textual content("Present: (context.state.currentGlasses)")
.font(.title2)
.fontWeight(.daring)
Spacer()
Textual content("Purpose: (context.state.dailyGoal)")
.font(.title2)
}
// Progress bar
Gauge(worth: Double(context.state.currentGlasses), in: 0...Double(context.state.dailyGoal)) {
EmptyView()
}
.gaugeStyle(.linearCapacity)
}
}
}
This view defines the principle interface of the Dwell Exercise, which seems on each the Lock Display screen and the Dynamic Island. It shows a progress bar to visualise water consumption, together with the present variety of glasses consumed and the every day aim.
Subsequent, create the WaterReminderWidgetLiveActivity struct like this:
struct WaterReminderWidgetLiveActivity: Widget {
var physique: some WidgetConfiguration {
ActivityConfiguration(for: WaterReminderWidgetAttributes.self) { context in
// Lock display screen/banner UI goes right here
WaterReminderLiveActivityView(context: context)
.padding()
} dynamicIsland: { context in
DynamicIsland {
// Expanded UI goes right here. Compose the expanded UI by means of
DynamicIslandExpandedRegion(.heart) {
WaterReminderLiveActivityView(context: context)
.padding(.backside)
}
} compactLeading: {
Textual content("💧")
.font(.title3)
} compactTrailing: {
if context.state.currentGlasses == context.state.dailyGoal {
Picture(systemName: "checkmark.circle")
.foregroundColor(.inexperienced)
} else {
ZStack {
Circle()
.fill(Shade.blue.opacity(0.2))
.body(width: 24, peak: 24)
Textual content("(context.state.dailyGoal - context.state.currentGlasses)")
.font(.caption2)
.fontWeight(.daring)
.foregroundColor(.blue)
}
}
} minimal: {
Textual content("💧")
.font(.title2)
}
}
}
}
The code above defines the Dwell Exercise widget configuration for the app. In different phrases, you configure how the dwell exercise ought to seem beneath totally different configurations.
To maintain it easy, we show the identical dwell exercise view on the Lock Display screen and Dynamic Island.
The dynamicIsland closure specifies how the Dwell Exercise ought to look contained in the Dynamic Island. Within the expanded view, the identical WaterReminderLiveActivityView is proven within the heart area. For the compact view, the main facet shows a water drop emoji, whereas the trailing facet modifications dynamically primarily based on the progress: if the every day aim is reached, a inexperienced checkmark seems; in any other case, a small round indicator reveals what number of glasses are left. Within the minimal view, solely the water drop emoji is displayed.
Lastly, let’s add some preview code to render the preview of the Dwell Exercise:
#Preview("Notification", as: .content material, utilizing: WaterReminderWidgetAttributes.preview) {
WaterReminderWidgetLiveActivity()
} contentStates: {
WaterReminderWidgetAttributes.ContentState.pattern
WaterReminderWidgetAttributes.ContentState.goalReached
}
#Preview("Dynamic Island", as: .dynamicIsland(.expanded), utilizing: WaterReminderWidgetAttributes.preview) {
WaterReminderWidgetLiveActivity()
} contentStates: {
WaterReminderWidgetAttributes.ContentState(currentGlasses: 3, dailyGoal: 8)
WaterReminderWidgetAttributes.ContentState(currentGlasses: 8, dailyGoal: 8)
}
#Preview("Dynamic Island Compact", as: .dynamicIsland(.compact), utilizing: WaterReminderWidgetAttributes.preview) {
WaterReminderWidgetLiveActivity()
} contentStates: {
WaterReminderWidgetAttributes.ContentState(currentGlasses: 5, dailyGoal: 8)
WaterReminderWidgetAttributes.ContentState(currentGlasses: 8, dailyGoal: 8)
}Xcode enables you to preview the Dwell Exercise in several states without having to run the app on a simulator or an actual machine. By establishing a number of preview snippets, you possibly can rapidly check how the Dwell Exercise will look on each the Lock Display screen and the Dynamic Island.
Managing Dwell Actions
Now that we’ve put together the view of the dwell exercise, what’s left is to set off it when the consumer faucets the Add Glass button. To make our code extra organized, we’ll create a helper class referred to as LiveActivityManager to managing the dwell exercise cycle.
import Basis
import ActivityKit
import SwiftUI
@Observable
class LiveActivityManager {
non-public var liveActivity: Exercise?
var isLiveActivityActive: Bool {
liveActivity != nil
}
// MARK: - Dwell Exercise Administration
func startLiveActivity(currentGlasses: Int, dailyGoal: Int) {
guard ActivityAuthorizationInfo().areActivitiesEnabled else {
print("Dwell Actions will not be enabled")
return
}
// Finish any present exercise first
endLiveActivity()
let attributes = WaterReminderWidgetAttributes(activityName: "Water Reminder")
let contentState = WaterReminderWidgetAttributes.ContentState(
currentGlasses: currentGlasses,
dailyGoal: dailyGoal
)
do {
liveActivity = attempt Exercise.request(
attributes: attributes,
content material: ActivityContent(state: contentState, staleDate: nil),
pushType: nil
)
print("Dwell Exercise began efficiently")
} catch {
print("Error beginning dwell exercise: (error)")
}
}
func updateLiveActivity(currentGlasses: Int, dailyGoal: Int) {
guard let liveActivity = liveActivity else { return }
Activity {
let contentState = WaterReminderWidgetAttributes.ContentState(
currentGlasses: currentGlasses,
dailyGoal: dailyGoal
)
await liveActivity.replace(ActivityContent(state: contentState, staleDate: nil))
print("Dwell Exercise up to date: (currentGlasses)/(dailyGoal)")
}
}
func endLiveActivity() {
guard let liveActivity = liveActivity else { return }
Activity {
await liveActivity.finish(nil, dismissalPolicy: .fast)
self.liveActivity = nil
print("Dwell Exercise ended")
}
}
}
The code works with WaterReminderWidgetAttributes that we now have outlined earlier for managing the state of the dwell exercise.
When a brand new Dwell Exercise begins, the code first checks whether or not Dwell Actions are enabled on the machine and clears out any duplicates. It then configures the attributes and makes use of the request methodology to ask the system to create a brand new Dwell Exercise.
Updating the Dwell Exercise is easy: you merely replace the content material state of the attributes and name the replacemethodology on the Dwell Exercise object.
Lastly, the category features a helper methodology to finish the presently energetic Dwell Exercise when wanted.
Utilizing the Dwell Exercise Supervisor
With the dwell exercise supervisor arrange, we will now replace the WaterTracker class to work with it. First, declare a property to carry the LiveActivityManager object within the class:
let liveActivityManager = LiveActivityManager()
Subsequent, replace the addGlass() methodology like this:
func addGlass() {
guard currentGlasses < dailyGoal else { return }
currentGlasses += 1
if currentGlasses == 1 {
liveActivityManager.startLiveActivity(currentGlasses: currentGlasses, dailyGoal: dailyGoal)
} else {
liveActivityManager.updateLiveActivity(currentGlasses: currentGlasses, dailyGoal: dailyGoal)
}
}
When the button is tapped for the primary time, we name the startLiveActivity methodology to begin a dwell exercise. For subsequent faucets, we merely replace the content material states of the dwell exercise.
The dwell exercise must be ended when the consumer faucets the reset button. Subsequently, replace the resetDaily methodology like beneath:
func resetDaily() {
currentGlasses = 0
liveActivityManager.endLiveActivity()
}
That’s it! We’ve accomplished all of the code modifications.
Updating Data.plist to Allow Dwell Actions
Earlier than your app can execute Dwell Actions, we now have so as to add an entry referred to as Helps Dwell Actions within the Data.plist file of the principle app. Set the worth to YES to allow Dwell Actions.
Nice! At this level, you possibly can check out Dwell Actions both within the simulator or instantly on an actual machine.
Abstract
On this tutorial, we explored methods to add Dwell Actions to SwiftUI apps. You have realized how these options enhance consumer engagement by delivering real-time info on to the Lock Display screen and the Dynamic Island, decreasing the necessity for customers to reopen your app. We coated your entire course of, together with creating the info mannequin, designing the consumer interface, and managing the Dwell Exercise lifecycle. We encourage you to combine Dwell Actions into your present or future functions to supply a richer, extra handy consumer expertise.
