Amy is a cute iOS Developer

The trait of a good look

2026-04-15T00:00:00Z

It's always important to have the right style in any look you go for. The right background. The right shadow. The right fit. The right feel. But by default, any use of a SwiftUI preview lacks all of these. It's just the view, there without adornment for the world to see. So how can these be improved and built upon?

The answer to that is the use of traits and specifically PreviewTrait. So let's unpack things a bit.

PreviewModifier

The first step is to create a modifier that will provide the look and style of the preview. It acts in the same way as ViewModifier that can be used on a View, but has the ability to also provide a Context. The context is what allows you to provide extra data such as setting up a database or creating appropriate mocks for the view.

Consider a spherical modifier in a vacuum

By default, the definition of PreviewModifier will define an associated type for Context as Void. This means that the modifier is just providing a look but avoiding the feel.

public struct BlackBackgroundModifier: PreviewModifier {
  public func body(content: Content, context: Void) -> some View {
    content
      .background(Color.black)
  }
}

As with ViewModifier it is typical to provide a convenience function for it so that it can be used. This would be defined like:

public extension PreviewTrait where T == Preview.ViewTraits {
  static var blackBackground: Self = .modifier(BlackBackgroundModifier()) 
}

To make use of this new trait, we provide it when defining the Preview.

#Preview(traits: .blackBackground) {
  YourAmazingView()
}

Giving it all a bit of love and feeling

A reference is all good and useful, but the view doesn't feel alive unless it has the data it usually expects when it exists within your app. A typical approach here is when using SwiftData you can provide the Context as a ModelContainer. This is the example that is seen everywhere online, but to be honest it can be any type you want. The idea is that the Context gets created once and then it is reused throughout the Canvas lifecycle showing the Preview(s).

So lets work through this example. It sets up a model container and provides it to the view. You can get access to the Context from within the body function and then apply it to the view.

struct PreviewSampleData: PreviewModifier {
  static func makeSharedContext() throws -> ModelContainer {
    let config = ModelConfiguration(
      isStoredInMemoryOnly: true
    )
    
    do {
      let container = try ModelContainer(
        for: FeelGoodJournalEntry.self,
        configurations: config
      )
      try addSampleData(to: container)
      return container
    } catch {
      fatalError("Couldn't create container: \(error.localizedDescription)")
    }
  }
  
  func body(content: Content, context: ModelContainer) -> some View {
    content.modelContainer(context)
  }
}

The sky is the limit

So this is a simplified for teaching example of how a PreviewModifier and PreviewTrait can be used to provide look and feel to your previews. From here, it's a matter of exploring and seeing how you can use them to improve the experience of your development within Xcode.

One thing leads to another

2026-04-06T00:00:00Z

A tale as old as time

Since the introduction of iPhone SDK 3.0 developers have been dealing with data migrations on mobile devices. As mobile apps grow, their data requirements change alongside them and being on top of migrations is a black art that even the most current LLM has difficulty with.

The reliance on magic

When SwiftData was introduced in 2023, it brought with it a new approach to migrations being SchemaMigrationPlan that allows for programatically migrating between versions. Those who have dealt in the dark arts of CoreData migrations know that there exists blog posts and also official apple documentation on the matter. The difference being that with SwiftData, the approach is a lot more approachable.

Where as CoreData relied on mapping files to handle migrations, in SwiftData there is a definite gotcha there where the often used examples say to just put the @Model macro everywhere with abandon in order to get the magic. This works great if you know that you'll only ever do lightweight migrations, but if you need to change anything more substantially, this approach relies to much on magic.

Adoption of VersionedSchema is a way to avoid but if you're app is already in the wild then you need to take a few extra steps to bring everything into line with versioned schemas.

Defining the schemas

The first step is to define all your existing SwiftData models in a VersionedSchema. This can look like the following. The important part to remember is that this first version should match your existing models exactly.

public struct Version1: VersionedSchema {
  public static let models: [any PersistentModel.Type] = [
	Version1.One.self,
	Version1.Two.self,
	Version1.Three.self,
  ]

  public static let versionIdentifier = Schema.Version(1, 0, 0)

  public init() {

  }
}

By making use of the Version1 struct you can namespace your types. A public typealias will then allow for continuing to use the existing types without code change. This is also a good chance to define CurrentVersion as a type so that when you move between versions, the references in your code don't require change.

public typealias CurrentVersion = Version1

public typealias One = CurrentVersion.One
public typealias Two = CurrentVersion.Two
public typealias Three = CurrentVersion.Three

When creating your model container, you can then make use of the new VersionedSchema definition.

let schema = Schema(versionedSchema: CurrentVersion.self)

let modelConfiguration = ModelConfiguration(
  schema: schema,
  isStoredInMemoryOnly: false,
  cloudKitDatabase: .private("iCloud.your.app.data")
)

let container = try ModelContainer(
  for: schema,
  configurations: modelConfiguration
)

Not so fast

If you are going from a non versioned schema to a versioned schema, you will unfortunately hit an error when creating the model container "Cannot use staged migration with an unknown model version.". This error is unfortunately not well documented, but there is a common work around you can use. The trick is to explicitly load the Version1 schema first and then continue with any other migrations.

do
{
  return try liveModelContainer()
} catch SwiftDataError.loadIssueModelContainer {
  do {
    let legacySchema = Schema(versionedSchema: Version1.self)
    let legacyModelConfiguration = ModelConfiguration(
      schema: legacySchema,
      isStoredInMemoryOnly: false,
      cloudKitDatabase: .none
    )
    let legacyContainer = try ModelContainer(
      for: legacySchema,
      configurations: [legacyModelConfiguration]
    )

    try legacyContainer.mainContext.save()

    return try liveModelContainer()
  } catch {
    // Log and handle any other errors here
  }
}

At this point, you should be able to successfully load your data as a versioned schema without any issues.

And on and on and on and on

As apps grow in size, you will want to define a SchemaMigrationPlan to allow you to constantly grow your apps data requirements.

As with anything there are a few caveats when using a schema migration plan. The majority of things will hopefully be covered by a .lightweight MigrationStage.

When you need to start modifying your data or changing it between app versions, this can get tricky and you will need to make use of a .custom migration stage.

public class AppMigrationPlan: SchemaMigrationPlan {
  public static var schemas: [any VersionedSchema.Type] {
    [
      Version1.self,
      Version2.self,
    ]
  }

  public static var stages: [MigrationStage] {
    [
      migrateV1toV2,
    ]
  }

  static let migrateV1toV2: MigrationStage = .custom(
	fromVersion: Version1.self,
	toVersion: Version2.self
  ) { context in
    // Your Version1 models are available here
  } didMigrate: { context in
    // Your Version2 models are available here
  }
}

The important thing to remember is that you can't access anything from your old schema version inside of the didMigrate closure as the schema has already changed at that point. So if you are wanting to move data from var foo to a combination of var baz and var blorp then you will need to store this data as part of the willMigrate closure so that it is retained. You can then set it on the corresponding versioned model in didMigrate and save the changes.

There's a lot of hand waving here, but that's intentional. The specific requirements of migrations aren't what's important. The important thing is to get your app into a versioned schema and then start writing the migrations.

The music we share with friends.

2024-03-09T00:00:00Z

It was a dark and stormy stardate 57162.3

The girl slumped down in her office chair. The meeting was over and once again it had been one of those meetings. But that's okay, she knew how to deal with them and how to regain control of her emotions afterwards. One of the group chats she was in served as a great outlet stress and they were all her chosen family. It was a safe place for all of them to vent about what's going on in life. The second thing she needed was some music.

She queued something up on her HomePod's and closed her eyes waiting for the bass to drop and the stress to start slowly leaving her body as the music took hold. Opening her eyes again, she moved to the next step in the ritual. She wanted to share the music she was listening to with the group as it was relevant to her outpouring of emotions and regaining control.

This time though, she was confronted by issues. She had to go looking for the song in music.app and then navigate to the share sheet so that she could simply get the URL for the track she wanted to share. It was all too much and she threw up her arms in frustration, letting out a high pitched wail of frustration. There had to be a better way of handling this situation.

File -> New Project

Once the inevitable break down had subsided, the girl was spurred into action. She had a problem to solve and would not be satisfied until a situation had presented itself. There had to be an easier way to share the music with her friends. Her mental health depended on it. Well, maybe not depend on but it was a distraction.

Breaking apart the task, there were a few things that needed to be accomplished so she could start sharing the music she listened to with her friends.

Obtaining permission
Finding out the playback history
Creating a UI
Sharing the track
Access from anywhere

A plan set out, it was now time for the girl to get to work.

Setting up the project

Surprisingly this turned out to be the most complex of the issues to address. The girl had to set up a complete project in the Apple Developer portal in order to get access to MediaKit from within her application. While impressed by the structure of the MusicKit API, she was caught out by how it interacted with lower level parts of apples platforms. Like WeatherKit and ShazamKit the MusicKit framework made use of a system daemon that handled things such as caching and authentication for all apps making use of the framework. She let a relaxed smile appear on her face having realised this. The extra steps involved were there for a purpose and meant that the task of having her app remain a good citizen when using the MusicKit API was handled by the platform. She noted down the documentation link in her notebook that constantly sat open by her side (what girl doesn't have a stack of notebooks just sitting around with random things contained therein?)

Obtaining permission

A grin crept across the girls face. She had the project set up. She was now ready to get going with the fun part of the project. She would be able to write some code. There would be unit tests, there would be comments. The structure would flow like a well choreographed dance number. Grace, elegance, fluidity. All the things that reflect the girls nature and attitude towards life. Everything about her gets poured out into the work she does.

First up, she needed to ask the for the users permission to access the music library on behalf of the user. This is always an important step as accessing user data without permission is an invasion of the user privacy. She remembered the stories about peoples data being harvested and sold and she didn't want anything about that. Thankfully, there was a type in MusicKit helpfully labeled as MusicAuthorization that contained exactly what she needed.

While reading the documentation, she noticed that there needed to be a property list value added to the info.plist file labeled NSAppleMusicUsageDescription. When requesting authorisation, the text associated with this value is presented to the user. It makes clear what the consent is being requested and why it is being requested.

Well, she thought to herself, that's another point for relying on the platform to take care of the heavy lifting. She doesn't need to make her own implementation. Let's test this out she sang to herself and proceeded to place some code into the view model (structure is important and all business logic gets separated out from the view).

let status = switch await MusicAuthorization.currentStatus {
case .authorized:
  .authorized
case .restricted:
  .restricted
case .denied, .notDetermined:
  MusicAuthorization.request()
@unknown default:
  break
}

if case .authorized = status || case .restricted = status {
  // Handle request here
}

On the first run, she let out a cheer as the prompt appeared to ask for consent. Forward momentum is always a good thing.

Finding out the playback history

Knowing that she could access the music library she could now ask questions of it. These questions were done using a request / response handshake. Thankfully she could make use of the generic types to create a specific query and get the response crafted to her liking. This was a powerful side of the swift programming language that she always enjoyed using. MusicRecentlyPlayedRequest was the type that she needed for the request and looking at it, she could see that it was generic over the type of MusicItem that included things like Album, Playlist, Song and Track that were perfect for her needs. She could easily customise the apps behaviour to show any of these or even more as long as it conformed to the correct protocol. Another point to well designed API's.

With the request created, she then needed to get a response. There was a corresponding response to the request available to her that she could make use of. This was MusicRecentlyPlayedResponse. So it was now time for the girl to get to writing some more code.

var request = MusicRecentlyPlayedRequest<Track>()
request.limit = 1

let response = try await request.response()

guard let track = response.items.first else {
  throw Errors.noRecentlyPlayed
}

// Do something with the track data returned

Creating a UI

With the data now flowing to her app, it was time to create the UI. As the girl had selected a multiplatform app when creating the project, there was only one approach to take for the UI and that was to use SwiftUI as it meant she could be expressive in how she built the UI and know that the platform running the app would happily translate the UI to something appropriate for its conventions and behaviours. Gone were the days having to splatter #if os(macOS) all throughout the codebase and have multiple targets each with their own quirks and conventions.

To get started, the girl envisioned a simple UI. One that started by showing information over delight. She would move onto that at some stage, but for now she was content on getting things on the screen first.

VStack(alignment: .center, spacing: 12) {
  AsyncImage(url: song.imageURL) { image in
    image
      .resizable()
      .frame(width: 400, height: 400)
  } placeholder: {
    ProgressView()
      .progressViewStyle(.circular)
  }
  Text(song.title)
  Text(song.artist)
  HStack {
    if let shareURL = song.shareURL {
      ShareLink(item: shareURL)
    }
    Button("Copy", systemImage: "doc.on.doc") {
      viewModel.copyToPasteboard()
    }
  }
}

Sharing the track

It was here that the girl was faced with a choice. Did she want to implement the standard platform behaviour of a Share Sheet that provided the most extensible way of getting the information about the album / track / song / playlist to others? Did she want to just copy the URL to the clipboard so that she could paste it where she wanted? A lot of her current frustration for building the new app stemmed from the lack of discoverability around the share sheet in Apple's Music app and how it introduced many extra steps to completing the task at hand. She also understood that a URL often lacks the extra information required when sharing. In the end, she needed to provide both options to the users. The first option, using a share sheet, could be achieved by using the ShareLink type in SwiftUI and letting the platform take care of the nuance around presentation.

The second option required a bit more nuance as NSPasteboard and UIPasteboard had their own quirks and the girl needed to resort to having different behaviour between. Thankfully the differences weren't substantial. The girl also took note that the pasteboard was for more than just string and binary values. She could be expressive with the data she provided and that would let other apps determine if and how they responded to a paste event. For her app, specifying that the pasteboard was handling a URL was sufficient.

#if os(macOS)
NSPasteboard.general.setString(url.absoluteString, forType: .URL)
#else
UIPasteboard.general.url = url
#endif

Access from anywhere

At last the girl could get the song she was listening to could be shared easily with her friends. But there were quirks. Apple's platforms were great for multitasking, but they still needed switching between apps. You could scatter multiple windows over the desktop on macOS but you still had to switch between them. On iOS and iPadOS there was a need to switch between them as well. Thankfully on macOS the problem could be addressed by the use of MenuBarExtra as a scene within the app. On iOS and iPadOS she would need to look for other solutions.

MenuBarExtra("Your App Name", systemImage: "music.note.list") {
  // UI goes here
}
.menuBarExtraStyle(.window)

Taking it further

The girls voice rang out in jubilation. She had a solution to her problem and she was keen to share it with the world at large. Her friends first as they received the test flight link and then she put her mind to releasing the app once feedback had been received. This is where her passion lies, her delight is found. Her voice. Her song.

narrators note app is still being finalised though will be released at some point in the future.

A Girl and her @ViewBuilder

2024-01-10T00:00:00Z

note: the story here is fictional, but it's an approach I love to take when solving similar problems. Hope you enjoy it and get a good understanding of how make use of @ViewBuilder in SwiftUI apps.

Once upon a time

One upon a time, a girl was presented with a task. Refactor this code her manager demanded, another team is wanting to reuse this part of the UI. "Happy to" she responded, knowing that there was no getting out of this work. 'Tis much better to build this well and share it around than have many implementations of the same thing with very small differences between them. None of which quite solving the problem. Loading up a Riot Grrrl playlist in Apple Music, she pulled down the latest version of the codebase and began to work. The code she found wasn't the best. If it were, she wouldn't be doing this task now would she? She had seen this kind of code many times before. A few different components wrapped up in what would colloquially be described as a card. There was a VStack with the different bits and pieces stuck in there along with a fairly standard set of view modifiers.

Understanding the requirements

There are many approaches the girl could take to solving this problem. One option would be to rename the existing view, expose properties for things like title, image, text and throw it into a shared part of the project. But she knows well and true that will only cause pain down the track. She needs a way to make the content arbitrary while maintaining style and functionality. This will give her the best base component to allow others to build upon.

Looking at alternatives

In her time working on apps built in SwiftUI the girl knew of a few solutions she could apply to make this all work as she wanted

view builders
view extensions
view modifiers

View Modifiers

View modifiers have been around since the start of SwiftUI and have been a long established way of applying a common set of modifications to a view. The girls team has experience with this and she knows there will be little cognitive overhead for them to pick up the preferred way of doing this. So how would this look to her teammates? This is always an important question to ask and so she opened up a Swift Playground (We all remember those things right? More than just for WWDC scholarship applications) and started roughing out what it would be.

public struct CardModifier: ViewModifier {
  func body(content: Content) -> some View {
    content
      .frame(maxWidth: .infinity, alignment: .leading)
      .fixedSize(horizontal: false, vertical: true)
      .padding(8)
      .background(Color.background)
      .mask(RoundedRectangle(cornerRadius: 8, style: .continuous))
  }
}

And then it's usage in a view

Text("Hello World")
  .modifier(CardModifier())

But is this as good as it could be? The girl sat there in her chair, one leg tucked under her in a posture that confounds her colleagues and sipped on the tea she had recently poured for herself. A miracle that she remembered to take a break and spend time contemplating next steps. She knew that this would solve a problem, but would it encourage the team to use it and have an understanding of what is being accomplished? She gazed at her Swift Playground a bit more, but was not satisfied she could answer that question in the affirmative. One approach down, on to the next one.

View Extensions

Knowing that SwiftUI is very idiomatic, the girl started to ponder the question "What if this was an extension on View?". Thankfully this one could be proven viable or not by a simple addition to her open Swift Playground.

extension View {
  func displayAsCard() -> some View {
    modifier(CardModifier())
  }  
}

This then gave her the freedom to apply it to any view type and have it understandable that the view itself was being displayed as a card. But she knew, even this didn't have what she was looking for. It was a single change to an existing View in the app but it lacked discoverability and had a high cognitive overhead on her colleagues. She didn't want to make life more difficult for her friends that she interacted with ever day. Well, there was one who was super annoying but what work environment doesn't have people like that in them. The girl shuddered and as she was still holding her tea for warmth in both hands took a calming sip of tea. Thankfully, she knew of a solution and where she wanted to go with this bit of work.

View Builders

Each year the girl spent a good amount of her time travelling the world and speaking with others in the industry. She had to be super careful in this as the environments could very easily be toxic. She was there to learn more about what she loved doing day to day. A repeated theme amongst conversations is how Swift as a language allows for the writing of DSL's and this was a super powerful technique to use when writing apps with SwiftUI. She had heard of the idea about result builders and their specific application in SwiftUI being @ViewBuilder. Needing a refresher before continuing, she queued up a few WWDC videos on the topics being Write a DSL in Swift using result builders and Embrace Swift generics that deal with the topic. She couldn't help but be excited that both presenters in the videos were female. With how much progress had been made in recent years, there was still a long way to go towards gender equality.

The girl now had the approach she wanted to take sorted out. She fetched yet another cup of tea and got to work on the solution.

struct Card<Content: View>: View {
  let configuration: CardViewConfiguration
  let content: Content

  init(configuration: CardViewConfiguration = .default, @ViewBuilder content: () -> Content) {
    self.configuration = configuration
    self.content = content()
  }

  var body: some View {
    content
      .frame(maxWidth: .infinity, alignment: .leading)
      .fixedSize(horizontal: false, vertical: true)
      .padding(configuration.padding)
      .background(configuration.backgroundColor)
      .mask(
        RoundedRectangle(
          cornerRadius: configuration.cornerRadius,
          style: .continuous
        )
      )
  }
}

struct CardConfiguration {

  public let backgroundColor: Color
  public let cornerRadius: CGFloat
  public let padding: CGFloat

  public init(backgroundColor: Color, cornerRadius: CGFloat, padding: CGFloat) {
    self.backgroundColor = backgroundColor
    self.cornerRadius = cornerRadius
    self.padding = padding
  }

}

This had the advantage of being usable within the app in a way to simply described what was being created and allowed others to build what they want on top of it.

Card {
  Text("Hello World")
}

Bringing the team on board

Satisfied with how the use of ViewBuilder came out, the next step for the girl was to bring her team onboard with the approach. She could slap together a PR and send it up for others to review, but that wouldn't achieve much. If others were to start adopting a similar approach in how they wrote views, she would need to give them as much help as possible. This was more than just chatting with other engineers. Now it was time for a checklist. She still had a lot of work to do to ensure adoption by others.

Chat with UX designers about upcoming usages.
Chat with accessibility experts about how it would look for vision impaired users.
Inline documentation that covers example usage.
Brown bag (small talk / meeting at work) covering the usage of @ViewBuilder in the app and other possibilities for the use of similar DSL's.
Work with engineers as they adopt the new UI component and adopted similar patterns in their work.

The girl leaned back in her chair, cup of tea firmly grasped in both hands. It will go unmentioned how many she had consumed throughout this day. She was satisfied that she had met the requirements of the work and the team is now in a better place.

Formatters and Measurements

2024-01-05T00:00:00Z

Why data is important

Data is what makes apps viable. It is what drives the user interactions and informs them of what's going on. While some apps use data in the form of text, there are other apps that use very fine grained measurements and need to present these in ways that are appropriate for the user.

Respecting the users locale

When dealing with data relating to measurements we want to be respectful of the users locale and language settings. If we have a value that has been recorded as meters per second and the users default measurement for speed is miles per hour, we want to respect that when we display the value to the user. Similarly if a temperature measurement is in degrees Kelvin, we want to format that in the users default value such as Celsius or Fahrenheit.

Creating a custom Formatter

A lot of formatters already exist and are provided by as part of the respective platforms and should be preferred over a custom implementation of Formatter. There is also sample code from Apple which demonstrates the use of formatters in an app.

Though there are times when we want to take a string such as "ABCD1234EFGH5678" and turn it into something like "ABCD-1234-EFGH-5678" which is then displayed to the user. To do this, we want to create a custom formatter. This sounds complex, but it is as a straight forward and the good thing is that the implementation can be unit tested.

Define the subclass

To get started, define a new value type such as the following.

class SuperAwesomeCustomFormatter {

}

Create the implementation

After defining the class, we can build out the implementation. The amazing thing about how this protocol is defined is that it doesn't case what the value being passed in is. It is the responsibility of the formatter to determine if it knows how to provide an appropriate String as a result.

extension SuperAwesomeCustomFormatter: Formatter {

  override func string(for obj: Any?) -> String? {
    /* 
    super secret custom implementation goes here okay, 
    just make sure you return an optional String value.
    The actual implementation is left as an exercise
    for the reader to look at.
    */
    nil
  }

}

The Formatter class provides the definition string(for:) as well as attributedString(for:withDefaultAttributes:) and editingString(for:). This makes the Formatter subclass super powerful and adaptable to the use case. Do take note of the default behaviour discussion in the apple documentation if you are overriding these values.

Write some unit tests

As we are dealing with formatting strings we want to make sure that it does what is expected. So for this we write some unit tests. These tests can be as simple or as complex as you want.

class SuperAwesomeCustomFormatterTests: XCTestCase {

  func testFormatsString() {
    let testSubject = SuperAwesomeCustomFormatter()
    let expected = "1234-ABCD-4567-EFGH"
    let result = testSubject.string(for: "1234ABCD4567EFGH")
		
    XCTAssertEqual(expected, result)
  }

}

Showing formatted values

A lot of SwiftUI types work with a formatter such as Text and TextField. This is demonstrated by a super simple view like the following which presents a TextField and uses an appropriate custom formatter for the value.

struct ContentView: View {

  @State var superAwesomeString: String = ""

  var body: some View {
    VStack {
      TextField(
        "Super Awesome Value",
        value: $superAwesomeString,
        formatter: .superAwesomeFormatter
      )
    }
    .padding()
  }

}

extension Formatter {

  static var superAwesomeFormatter: Formatter = {
    SuperAwesomeFormatter()
  }()

}

WWDC 23 Wishlist

2023-04-11T00:00:00Z

Each year as it gets close to wwdc developers love to speculate as to what they would love for Apple to release at their annual conference. I'll not get in to the out there rumours (mixed reality headset being the exception) but rather focusing on what would make my live a lot easier as an engineer.

CoreData uplift

We have seen how amazingly flexible Swift as a language is, particularly how easy it is to create a DSL using result builders is. Having a database persistence layer available that feels native to Swift apps would be a huge win.

Modern Swift API
Generated classes use swift types (not NSSet)
Thread and type safety
async / await

SwiftUI Previews from packages

This one has plagued developers for a long time. If you have a SwiftUI view defined in an SPM package along with a preview for the view, you can't use the canvas if your target is set to the main app. Yes you can change the target to be just the SPM package as a work around but that is really an unplesant experience for developers.

SwiftUI Map enhancements

For building RideStats.app I make use of the Map type in SwiftUI and it's amazing. It is rediculously limited though and is lacking 90% of the functionality that exists in the MapKit views.

Polyline paths
Overlays
Every feature that MapKit has but in a SwiftUI View

Mixed Reality headset

Everything makes sense for this to happen this year. I'm keeping my expectations open for just what it looks like but my guess is it will involve widgets and live activities somehow.

Showing heart rate in live activities

2023-04-08T00:00:00Z

Let's have some fun and get to understand two concepts. The first is bluetooth devices and the second is live activities. We'll be walking through some of the interesting parts of a demo app which is available on GitHub and seeing just what makes bluetooth devices behave and send data.

What is Bluetooth?

Bluetooth is a wireless communication method defined by the Bluetooth SIG and is a great way for talking to peripherals that are mounted on a bike such as power meters and cadence sensors. We'll be talking to a heart rate monitor in this example.

On apple platforms, the framework used is CoreBluetooth. As well as providing abstractions around Peripherals, Services, and Characteristics it uses a Central Manager for discovering all of the peripherals that are around.

To start making use of bluetooth peripherals, you need to have an instance of CBCentralManager and a class (yeah, needs to be an NSObject subclass) that conforms to the CBCentralManagerDelegate.

Discovering bluetooth devices

Before we start looking for peripherals, we want to make sure that the required hardware is available for use. Your app will be told about the state of the hardware via the delegate method centralManagerDidUpdateState(_:).

  public func centralManagerDidUpdateState(_ central: CBCentralManager) {
    switch central.state {
    case .poweredOn:
      startScanningForPeripherals()
    default: break
    }
  }

When the manager is asked to discover services we need to tell it what services it should be looking for. If we pass nil to scanForPeripherals(withServices: options:) we will see all peripherals. To limit these to just devices that support heart rate measurements, we use the service UUID of 180D that is defined by the heart rate service.

  public func startScanningForPeripherals() {
    guard manager.state == .poweredOn else {
      return
    }

    manager.scanForPeripherals(withServices: [CBUUID(string: "180D")])
  }

Now that we have asked the manager to scan for peripherals, we need to listen for what is found. As this happens at the discretion of the manager, we make use of the delegate function centralManager(_:didDiscover:advertisementData:rssi:) to perform actions on the peripherals that we find.

  public func centralManager(_ central: CBCentralManager, didDiscover peripheral: CBPeripheral, advertisementData: [String : Any], rssi RSSI: NSNumber) {
    guard peripherals.contains(where: { $0.id == peripheral.identifier }) == false else {
      return
    }

    peripherals.append(peripheral)
  }

As the peripherals are discovered, we want to be able to connect to them so we can start receiving values from them. To do this, we ask the manager to connect to a device. We then get the details of the connected peripheral in the delegate function centralManager(_:didConnect:).

  public func centralManager(_ central: CBCentralManager, didConnect peripheral: CBPeripheral) {
    details = peripheral
  }

Once the peripheral is connected, we then want to discover the services that are available on it. Doing this is requires that we first set the delegate property on the peripheral to a type that conforms to CBPeripheralDelegate which again needs to be a NSObject subclass. Once we have set the delegate we then need to call discoverServices(_:) on the peripheral using the 180D UUID for heart rate monitors.

    peripheral.discoverServices([CBUUID(string: "180D")])

The delegate method peripheral(_:didDiscoverServices:) will then be called with the peripheral having its services property populated. We can then ask the peripheral to discover the characteristics for each of the services. When scanning for characteristics, we use the function on the peripheral instance passing it an instance of CBService

  func peripheral(_ peripheral: CBPeripheral, didDiscoverServices error: Error?) {
    peripheral.services?.forEach { service in
      peripheral.discoverCharacteristics(nil, for: service)
    }
  }

We now have the required data and connection to start receiving values for our peripherals.

Receiving data

As you can guess, our app is told about the discovered characteristics in the delegate method peripheral(_:didDiscoverCharacteristicsFor:error:). There are two types of values which are available. We can either get a value if it is supported and this is great for static values on a device. We can also listen for notifications of when a value changes. This is what we want for heart rate monitors and other characteristics whose values change over time. To listen for a value update notification, we call the setNotifyValue(_:for:) function on the peripheral.

  func peripheral(_ peripheral: CBPeripheral, didDiscoverCharacteristicsFor service: CBService, error: Error?) {
    guard service.uuid.uuidString == "180D" else {
      return
    }

    guard let measurementCharacteristic = service.characteristics?.first(where: { $0.uuid.uuidString == "2A37" }) else {
      return
    }

    peripheral.setNotifyValue(true, for: measurementCharacteristic)
  }

The UUID for the characteristic representing heart rate measurements is 2A37 and is defined as part of the heart rate service specification. The format of the bytes we get in the peripheral(_:didUpdateValueFor:error:) delegate function are defined in the same specification. Being familiar with this dance is important so that we can parse the values.

  func peripheral(_ peripheral: CBPeripheral, didUpdateValueFor characteristic: CBCharacteristic, error: Error?) {
    guard characteristic.uuid.uuidString == "2A37" else {
      return
    }

    guard let data = characteristic.value else {
      return
    }

    heartRate = formatter.valueForData(data)
  }

The formatter is a helper type defined to extract the appropriate values from the raw Data instance that we get in the delegate function. This is defined as the following:

  public func valueForData(_ data: Data) -> Int? {
    let byteArray = [UInt8](data)
    let firstBitValue = byteArray[0] & 0x01

    if firstBitValue == 0 {
      return Int(byteArray[1])
    }

    return (Int(byteArray[1]) << 8) + Int(byteArray[2])
  }

Live Activities

A lot of fun comes when we background the app and can show the current heart rate as either a live activity or using the dynamic island on supported devices.

Handling background updates

To allow bluetooth to function in the background, we need to add some values to the info.plist file. These values are:

NSBluetoothAlwaysUsageDescription for a nice description of why we need to use bluetooth
Required Background Modes must contain App Communicates using Core Bluetooth
Supports Live Activities Frequent Updates set to true so we can send frequent updates

If you've used background fetches before, you would think that we need to handle background tasks. This isn't the case with CoreBluetooth and your CBCentralManagerDelegate conforming type will get called. When those delegate methods get called, it is possible to update the live activity.

Sending data to the live activity

Both Live Activities and the Dynamic Island exist as widgets and make use of configurations to update the data that gets shown. These configurations are value types that conform to the ActivityAttributes protocol like the following:

public struct WidgetsAttributes: ActivityAttributes {
  public typealias Content = ContentState

  public struct ContentState: Codable, Hashable {
    // Dynamic stateful properties about your activity go here!
    public var heartRate: Int

    public init(heartRate: Int) {
      self.heartRate = heartRate
    }
  }

  public init() {}
}

There are two parts to the attributes being the data which doesn't change regularly and then the frequently updated content. For showing the heart rate values we want to be setting the current value in the content. We do this when we receive a value in the CBPeripheralDelegate.peripheral(_:didUpdateValueFor:error:) function. We also want to check that live activities are supported which we do using the areActivitiesEnabled property on ActivityAuthorizationInfo class. When updating the data for a live activity, we create a new content and then ask the activity to update using the content.

    if ActivityAuthorizationInfo().areActivitiesEnabled {
      let content = ActivityContent(state: WidgetsAttributes.ContentState(heartRate: heartRate ?? 0), staleDate: nil)

      if activity == nil {
        do
        {
          let attributes = WidgetsAttributes()
          activity = try Activity.request(attributes: attributes, content: content)
        } catch {

        }
      } else {
        Task {
          await activity?.update(content)
        }
      }
    }

When we are finished displaying the heart rate, we want to end the activity so that it's not being displayed any longer.

    Task {
      await activity?.end(dismissalPolicy: .immediate)
    }

Hello World

2023-03-13T00:00:00Z

Welcome to my part of the Internet. My name is Amy and I'm a macOS and iOS developer.