Dwell Actions, first launched in iOS 16, are certainly one of Apple’s most enjoyable 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 and Dynamic Island. Whether or not it is monitoring a meals supply, checking sports activities scores, or monitoring progress towards a aim, this function retains necessary 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 how you can 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 or Dynamic Island. By the tip of the tutorial, you may perceive how you can combine Dwell Actions into your SwiftUI apps.
A Fast Take a look at the Demo App
Our demo app, Water Tracker, is a straightforward and enjoyable solution to preserve observe 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 goal: there is a round progress bar exhibiting how far alongside you might be, and each time you faucet the Add Glass button, the counter goes up by one and the progress bar fills a little bit extra.
Behind the scenes, the app makes use of a WaterTracker class to handle the logic. This class retains observe of what number of glasses you’ve already logged and what your every day aim is, so the UI at all times 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 help to the app. As soon as carried out, customers will be capable to see their progress instantly on the Lock Display 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 venture.
On this demo, the venture is named WaterReminder. To create the extension, choose the venture 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 test the Embody Dwell Exercise choice.
When Xcode asks, you’ll want to activate the brand new scheme. It’s going to then generate the widget extension for you, which seems as a brand new folder within the venture navigator together with the starter code for the Dwell Exercise and the widget.
We’ll be rewriting your complete WaterReminderWidgetLiveActivity.swift file from scratch, so it’s greatest to filter out all of its present code earlier than continuing.
Because the Dwell Exercise doesn’t depend on the widget, you’ll be able to 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 to undertake the protocol and outline the dynamic content material of the exercise.
Since this attributes construction is normally shared between each the primary app and widget extension, I recommend to create a shared folder to host this Swift file. Within the venture 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 consists of an activityName property to establish the exercise. To adapt to the protocol, we outline a nested ContentState struct, which holds the information 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 knowledge for visualization.
Please take notice that the goal membership of the file ought to be accessed by each the primary app and the widget extension. You may confirm it within the file inspector.
Implementing the Dwell Exercise View
Subsequent, let’s implement the reside exercise view, which handles the consumer interface in numerous 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("Objective: (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 primary interface of the Dwell Exercise, which seems on each the Lock Display 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(.middle) {
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(Coloration.blue.opacity(0.2))
.body(width: 24, top: 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 reside exercise ought to seem beneath totally different configurations.
To maintain it easy, we show the identical reside exercise view on the Lock Display 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 middle area. For the compact view, the main facet shows a water drop emoji, whereas the trailing facet adjustments 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 permits you to preview the Dwell Exercise in numerous states while not having to run the app on a simulator or an actual system. By establishing a number of preview snippets, you’ll be able to shortly take a look at how the Dwell Exercise will look on each the Lock Display and the Dynamic Island.
Managing Dwell Actions
Now that we’ve put together the view of the reside 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 reside exercise cycle.
import Basis
import ActivityKit
import SwiftUI
@Observable
class LiveActivityManager {
personal 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 usually are not 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 reside exercise: (error)")
}
}
func updateLiveActivity(currentGlasses: Int, dailyGoal: Int) {
guard let liveActivity = liveActivity else { return }
Job {
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 }
Job {
await liveActivity.finish(nil, dismissalPolicy: .rapid)
self.liveActivity = nil
print("Dwell Exercise ended")
}
}
}
The code works with WaterReminderWidgetAttributes that we’ve outlined earlier for managing the state of the reside exercise.
When a brand new Dwell Exercise begins, the code first checks whether or not Dwell Actions are enabled on the system 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 simple: 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 at the moment energetic Dwell Exercise when wanted.
Utilizing the Dwell Exercise Supervisor
With the reside 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 reside exercise. For subsequent faucets, we merely replace the content material states of the reside exercise.
The reside exercise ought to be ended when the consumer faucets the reset button. Due to this fact, replace the resetDaily methodology like beneath:
func resetDaily() {
currentGlasses = 0
liveActivityManager.endLiveActivity()
}
That’s it! We’ve accomplished all of the code adjustments.
Updating Information.plist to Allow Dwell Actions
Earlier than your app can execute Dwell Actions, we’ve so as to add an entry referred to as Helps Dwell Actions within the Information.plist file of the primary app. Set the worth to YES to allow Dwell Actions.
Nice! At this level, you’ll be able to check out Dwell Actions both within the simulator or instantly on an actual system.
Abstract
On this tutorial, we explored how you can add Dwell Actions to SwiftUI apps. You’ve got realized how these options enhance consumer engagement by delivering real-time info on to the Lock Display and the Dynamic Island, decreasing the necessity for customers to reopen your app. We coated your complete course of, together with creating the information 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.