What I Was Trying To Do

My app, Walk Mate, has a Heatmap screen with two filters: “You” and “Others”. The “You” filter shows places where the current user walked. The “Others” filter shows anonymous walks from all other users around the world. The data goes through CloudKit Public Database so every user can see everyone else’s walk place in a circular region. (i.e. over Taipei City and Kaohsiung City)

I shipped version 3.4.2 on App Store last week. Real users from Turkey, USA, Taiwan, Sweden, Japan and Canada started using the app. I could see their accounts in App Store Connect Analytics. But when I opened my Heatmap “Others” tab in the simulator from Xcode, I saw nothing from those countries. Only my own old test walks from Izmir, Turkey.

This was the start of the confusion. 🤯

First Mistake: I Trusted The Dashboard Without Checking The Environment

I opened CloudKit Dashboard. I picked Production. I picked Public Database. I picked the record type HeatmapContribution. I saw a lot of records. Some had latitude around 25 (Taiwan), some around 35 (Japan), and so on. So I thought “the data is there, the bug must be in my app.”

I asked an AI agent to help me debug. We added log lines to the fetch function. We ran the app from Xcode. The logs said the fetch returned 134 records. All of them were near Izmir. None from Taiwan or Japan.

This made no sense to me at first. The dashboard clearly showed Taiwan records. The app clearly did not return them. We tried many things. We checked sort orders. We checked permissions. We checked if records were lost during parsing. Nothing explained it.

The Real Cause: Two CloudKit Worlds

Then we tried one direct test. We picked one record name (9A85DFF-089E-4435-90E5-XXXXX) from the dashboard for a Taiwan record. We told the app to fetch that exact record by its name. The app got back “Record not found”.

That was the moment everything clicked.

CloudKit has two separate databases for every container. One is called Development. One is called Production. They look the same in code. They have the same name, the same record types, and the same fields. But they hold different data and they live on different servers.

When you build and run your app from Xcode with your normal Apple developer signing, your app talks to Development. When Apple builds your app for App Store or TestFlight with distribution signing, your app talks to Production. This switch happens because of the signing profile, not because of your build configuration. So even if I changed Xcode scheme to Release, my Xcode build still talked to Development as long as I used my normal developer certificate.

So my picture was like this:

• My old test walks from past development runs went into Development.

• Real App Store users on 3.4.2 wrote their walks into Production.

• The CloudKit Dashboard tab said “Production” at the top and showed me Production data.

• My Xcode debug build read only Development data.

Two different worlds. Looking at one in the dashboard, and reading the other in the app. They never met.

A Second Bug Hiding Behind The Confusion

While we were fixing the environment confusion, we found another real problem. The “Others” fetch in 3.4.2 was failing silently for every real user. Why? Because the Production schema needed a Queryable index on the system field recordName, and a Queryable + Sortable index on the timestamp field. These indexes were not deployed in Production. Without them, every “Others” query returned the error “Field ‘recordName’ is not marked queryable”.

The good news is that CloudKit indexes apply right away once you deploy them. So I went into the dashboard, added the indexes in Development, then clicked “Deploy Schema Changes to Production”. After that, my live App Store users could finally see global heatmap data without me shipping a new version.

I tested this by deleting Walk Mate from my iPhone, reinstalling 3.4.2 from the App Store, and opening the Heatmap. I saw my own Izmir walks under “You” and global walks by others under “Others”. It worked. 🚀

The Confusion Came Back

Then I built and ran the same code from Xcode in Debug mode. The others walks were gone again. Only my local one under both “You” and “Others”. I thought I broke something. 😮‍💨

I did not break anything. The Xcode debug build was reading Development again. Development still has no Taiwan or others records because no real user ever writes to Development. Only my past tests wrote to Development. So the Heatmap “Others” looks empty in Xcode debug runs and that is the correct expected behavior.

How To Verify Production Data From Xcode If You Want

There are two ways:

1. Add this temporary key in your entitlements file:

   <key>com.apple.developer.icloud-container-environment</key>
   <string>Production</string>

This forces Xcode builds to talk to Production. Use it only for testing and remove it after. Apple’s archive flow does not need this key. It picks Production by itself when it signs with a distribution profile.

2. Distribute the build through TestFlight Internal Testing. TestFlight builds use Production by default. So if you install your TestFlight build on a simulator or a device, you will see real user data.

What I Learned

A few simple things I now keep in mind:

• CloudKit Development and CloudKit Production are not the same database. They look the same in code. They are not the same at runtime.

• The CloudKit Dashboard tab you are looking at controls only the dashboard view. Your app picks its own database based on signing.

• Schema changes and index changes only apply to one environment. You must click “Deploy Schema Changes” to push them from Development to Production.

• Indexes are not auto created in Production by save. Records can be saved without indexes but cannot be queried. So users will quietly upload data that nobody can ever read until you deploy the indexes.

• A simple query log that prints the count of records returned would have saved me hours. I added that log on day one for next time.

• A direct fetch by record name is the fastest way to confirm “is this record actually in the database my app talks to”. If you get back “Record not found” for a record you can clearly see in the dashboard, you are not in the same database.

The bug felt huge while I was inside it. The fix in code was tiny. The fix in dashboard was just a few clicks. The real lesson was about understanding which CloudKit world I was talking to at any moment. 🤔

Short answer is;

Frame = a view’s location and size using the parent view’s coordinate system. Placing the view on the parent.

Bounds = a view’s location and size using its own coordinate system. Placing the view’s content or subview within itself.

If you think about the view frame in its parent coordinate system when you are rotating, you are changing parent view’s coordinate system. Bounds value will be same and frame value changes. Figure 1.0 shows how it looks like before transformation (rotating) and look carefully to the values.

The values in CGRect(x: 5, y: 5, width: 30, height: 40) define the rectangle's position and size:

• x (5): The horizontal distance from the left edge of the parent view to the rectangle’s origin.

• y (5): The vertical distance from the top edge of the parent view to the rectangle’s origin.

• width (30): The horizontal span of the rectangle.

• height (40): The vertical span of the rectangle.

These values specifically define the frame of the view, representing its location and size within its superview (parent) coordinate system.

View:

frame = { 5, 5, 30, 40 }
bounds = { 0, 0, 30, 40 }
center = { 20, 25 }

When the view rotated:

• Frame (changed): Because the view is now at an angle, it occupies more “horizontal and vertical space” relative to the parent’s X and Y axes.

• Bounds (unchanged): The view’s internal size remains (30 x 40) because the object itself hasn’t grown.

The dashed line in Figure 1.1 shows rotation and parent view’s location. Its width (52) and height (54) are calculated based on the rotated corners of the original (30 x 40) rectangle. Its corners push further out along the X and Y axes. To keep the view contained the parent system must calculate a new bounding box (the dashed line in Figure1.1) that reaches these new outermost points. The distance between its leftmost corner and rightmost corner is now 52, and the distance between its topmost and bottommost corner is 54.

View:

frame = { -6, -2, 52, 54 } // changed
bounds = { 0, 0, 30, 40 } // unchanged
center = { 20, 25 } // unchanged

I’m back with another concurrency question asked in one of the interviews like:

“When you have a Singleton (shared resource) in a multi-threaded environment, multiple queues can access to Singleton, the same shared state. You need to use a mechanism for accessing the common resource synchronously. What else do you remember for synchronizing the access to the common resource other than NSLock and DispatchSemaphore?”

I answered with DispatchBarrier by trying my best to explain. Let’s deep dive into the DispatchBarrier and then the modern way!

DispatchBarrier

It tells the compiler; “Wait. Let’s finish all the work that has already started. Then, just ME will work. Once I’m finished, the other tasks can continue.” In order to prevent data race, run tasks in an ordered way. Don’t run read and write operations at the same time! Once at a time!

Let’s explain it with a real life scenario;

Concurrent queue = multi-lane highway 🛣️

• Read operations = normal cars 🚗

• Write operations = road maintenance car 🚧

When the Dispatch Barrier arrives;

1. All cars pass first,

2. Road is closed completely,

3. Road maintenance car works alone,

4. Road opens again once the maintenance completed.

Let’s jump into the code example:

final class Highway {

    private let roadQueue = DispatchQueue( // 1
        label: "highway.queue",
        attributes: .concurrent
    )

    // Current road status
    private var roadStatus = "Road is Open"

    // Normal cars
    func carPass(carName: String) {

        roadQueue.async { // 2
            print("🚗 \(carName) is passing...")
            sleep(2)
            print("✅ \(carName) passed")
        }
    }

    // Road maintenance car is coming
    func roadMaintenance() {

        roadQueue.async(flags: .barrier) { // 3
            print("🛑 Road is closing...")
            print("🛠️ Maintenance car is working...")
            
            sleep(3)

            self.roadStatus = "Maintenance Completed!"

            print("✅ Maintenance is done")
            print("🟢 Road opens again")

            // new cars can pass concurrently again
        }
    }
}

Let’s dive into comment number lines:

1. Create a concurrent queue

2. async + concurrent queue

3. Use barrier. At this point queue behaves as serial temporarily.

Usage:

let highway = Highway()

highway.carPass(carName: "Car 1")
highway.carPass(carName: "Car 2")
highway.carPass(carName: "Car 3")

highway.roadMaintenance()

highway.carPass(carName: "Car 4")
highway.carPass(carName: "Car 5")

The workflow would roughly be like:

🚗 Car 1 is passing...
🚗 Car 2 is passing...
🚗 Car 3 is passing...

✅ Car 1 passed
✅ Car 2 passed
✅ Car 3 passed

🛑 Road is closing...
🛠️ Maintenance car is working...

✅ Maintenance is done
🟢 Road opens again

🚗 Car 4 is passing...
🚗 Car 5 is passing...

The critical points are here:

• The first 3 car can go at the same time (concurrent)

• Everybody waits when the maintenance car arrive (barrier)

• Road opens again when the maintenance completed.

Modern Way Actor

In a modern Swift Concurrency way, actors allow us to protect shared mutable state from data races. It means that an actor can help us fix a data race in a same way we had before by serializing access to mutable state. This is what we did manually with the DispatchBarrier earlier except actors are a lot smarter than the naive .barrier approach we took earlier.

Let’s update the code example with the modern and safer way:

// 1
actor Highway {

    // Current road status
    private var roadStatus = "Road is Open" // 2

    // Normal cars
    func carPass(carName: String) async {

        print("🚗 \(carName) is passing...")
        try? await Task.sleep(for: .seconds(2)) // 3
        print("✅ \(carName) passed")
    }

    // Road maintenance car is coming
    func roadMaintenance() async {

        print("🛑 Road is closing...")
        print("🛠️ Maintenance car is working...")

        try? await Task.sleep(for: .seconds(3))

        roadStatus = "Maintenance Completed!"

        print("✅ Maintenance is done")
        print("🟢 Road opens again")
    }

    func currentStatus() -> String {
        roadStatus
    }
}

Let’s dive into comment number lines:

1. I will queue access to the mutable state within this object.

   • No need .barrier definition

   • No queue creation

   • No synchronization code

2. actor protects state of private var roadStatus

   • Two tasks cannot change state simultaneously

   • One cannot interrupt while the other is changing state

   • No data race

Similarity with DispatchBarrier

Mentally that’s what actor makes under the hood: concurrent queue + barrier. But the main difference is: in the .barrier approach you write synchronization manually, in the actor, Swift runtime manages synchronization automatically.

Conclusion

In the Dispatch Barrier version of our Highway example, every car that wanted to access the road had to wait for the barrier operation to finish before continuing. During this waiting period, the underlying thread was blocked. In other words, the thread could not do any other useful work until the road maintenance operation completed.

This is one of the biggest differences between traditional GCD synchronization techniques and Swift Concurrency.

With Dispatch Barrier, we manually tell the queue: “Stop all traffic temporarily and let this critical operation run alone.” While this approach is safe and effective, waiting tasks often end up blocking threads.

Actors take a different approach. By converting our Highway type from a class into an actor, Swift automatically serializes access to mutable state for us. Instead of blocking threads while waiting for access, Swift Concurrency suspends tasks.

So mentally, you can think of the difference like this:

Dispatch Barrier

“Block the road until maintenance is done.”

Actor

“Cars waiting for maintenance don’t block the road itself. They pause and resume later.”

This is one of the core ideas behind Swift Concurrency: Suspend tasks, not threads.

Sources:

• Apple Developer - Managing a Shared Resource Using a Singleton

• Thread safe singleton in swift - Stack Overflow

• Stack Overflow Legend Rob 🤩

• Practical Swift Concurrency - Donny Wals

Most recently, when I was trying to end Live Activities completely and immediately and remove from both Dynamic Island and lock screen when the app terminated, I had a nondeterministic behavior. That Live Activity was sometimes removed sometimes not. After conducting some research, I discovered the solution using both modern Swift Concurrency and old Semaphore like below.

final class AppDelegate: NSObject, UIApplicationDelegate {
    
    func applicationWillTerminate(_ application: UIApplication) {
        let semaphore = DispatchSemaphore(value: 0)
        
        // Intentional: on termination we have a tiny window to end Live Activities.
        // A detached task avoids main-actor inheritance while we do a short bounded wait.
        Task.detached(priority: .high) {
            for activity in Activity<WalkActivityAttributes>.activities {
                let finalContent = ActivityContent(state: activity.content.state, staleDate: nil)
                await activity.end(finalContent, dismissalPolicy: .immediate)
            }
            // the semaphore’s .signal method is called to increment the number of available resources
            // so that whoever is waiting to access our resource can eventually gain access
            semaphore.signal()
        }
        // Every time we call .wait on the semaphore, the number of available resources either
        // decreases, or we wait for a resource to become available.
        _ = semaphore.wait(timeout: .now() + 2)
    }
}

Let’s visualize that code in the Dining Philosopher Problem manner but from the restaurant staff perspective.

The main purpose here is to clear the Live Activity as quickly as possible before the app completely terminates.

But the problem is;

• activity.end(...) works async,

• the process may be interrupted,

• Result: Live Activity stays remaining in both screens.

That semaphore solution does; wait for a while before the app termination and Live Activity cleaning ends.

Let’s visualize in the restaurant analogy 👇

Restaurant Analogy

You are the restaurant owner. Restaurant will close soon. But there are still customers eating:

• Live Activities appear in lock screen

• Live Activities in the Dynamic Island

You say: “Get out all customers before restaurant close 🤬”

1. Creating Semaphores

let semaphore = DispatchSemaphore(value: 0)

It means, put a waiter to the door. But the waiter at first in “None of the customers have not completed their dinner.“ status. So, the restaurant owner (app) has to wait.

value: 0 means there is no allowance to close restaurant.

2. Cleaning starts in background

Task.detached(priority: .high) {}

Send waiters to clean tables quickly.

Logic behind detached is “have a separate team work without involving the main restaurant manager”

3. Remove all customers

for activity in Activity<WalkActivityAttributes>.activities {
    await activity.end(...)
}

This means, the waiter goes to all tables and says “Restaurant is closing, you must leave.“

await is important because, the waiter is really expecting customers to leave. But, this doesn’t happen immediately.

4. Notify the waiter when the job is finished

semaphore.signal()

It means, the waiter comes and tells “Finally, all customers are gone 😮‍💨“

DispatchSemaphore value becomes 0 → 1. So, we can close the restaurant.

5. App waits for a bit

_ = semaphore.wait(timeout: .now() + 2)

The restaurant owner waits on the doorstep and yells to staff “I’ll wait for 2 sec until cleaning completes“.

If:

• Staff finish their job → restaurant closes properly.

• If they can’t → time’s up → restaurant closes.

Why this code is important?

Because iOS doesn’t wait async jobs while app is terminating.

So, normally if you do that app can directly close:

await activity.end()

Semaphore solution says, “One minute, let’s finish this job before close”.

What does Semaphore represent here?

In the restaurant example:

wait(): The waiter waits on the doorstep.

signal(): The staff says “Job is done”.

value: 0: No close.

value: 1: Can be close now.

Briefly

1. App will terminate

2. Start closing Live Activities

3. Wait a short while so the app doesn’t close immediately

4. Continue when the work is finished

5. Close again after 2 sec max

Semaphore here works like a:

“Traffic police who manages closing road for a short time” 🙂

The Modern Way

DispatchSemaphore is an old school synchronization tool which comes from Grand Central Dispatch world. In the modern swift concurrency approach async/await and Task usage will be chosen.

In theory we can use something like below for terminating Live Activities:

func endAllActivities() async {
    for activity in Activity<WalkActivityAttributes>.activities {
        let finalContent = ActivityContent(
            state: activity.content.state,
            staleDate: nil
        )

        await activity.end(
            finalContent,
            dismissalPolicy: .immediate
        )
    }
}

and we can call it:

Task {
    await endAllActivities()
}

However, there is an important problem here is the applicationWillTerminate is not an async lifecycle callback. iOS doesn’t guarantee the completion of async tasks when terminating and application. Therefore, while using only Task {} is more modern in theory, it may not be reliable in practice.

Hence, the most healthier approach is not doing Live Activity cleanup while app termination but doing it in either while switching to background or doing it before the scene has been inactive.

For instance:

func sceneDidEnterBackground(_ scene: UIScene) {
    Task {
        await endAllActivities()
    }
}

This approach:

• It is natively compatible with Swift Concurrency

• It does not cause thread blocking

• It removes Semaphore requirement

• It increases completion possibility of async tasks

Conclusion

Task + async/await is the modern approach but there is no 100% guarantee during the app termination. Hence, the best approach is doing cleanup at the early stages of the lifecycle.

Nowadays, I’m brushing up my iOS concurrent programming skills based on my past iOS interview experiences. I’ve been creating an interview questions pool for the past 5 years based on the interviews that I have so far. Just after a week, the modern Swift Concurrency officially announced by Apple, I had a technical interview with Spotify and faced beautiful concurrency questions. Based on these questions, I decided to write some comparison article between DispatchGroup(legacy way) and TaskGroup (modern way). Let’s start with the legacy one!

DispatchGroup

It’s briefly used when you have a bunch of asynchronous tasks running in parallel and wait for all work to be completed in a given queue and you want to be notified when all of them are finished. Dispatch group have various work items to execute, and perform another work item once all of our work items are completed. A dispatch group doesn’t actually execute work and it’s up to you to decide where and how all of your work runs. It only tracks the number of tasks that you’ve started, and the number of tasks that you’ve completed.

Let’s look at the example:

func fetchUserProfiles() {
    let group = DispatchGroup() // 1
    var results = [Data]()
    let userIDs = [1, 2, 3]
    let urls = userIDs
        .compactMap { URL(string: "https://jsonplaceholder.typicode.com/users/\($0)") }

    for url in urls {
        group.enter() // 3
        URLSession.shared.dataTask(with: url) { data, response, error in
            if let data {
                results.append(data)
            }
            defer { group.leave() } // 4
        }.resume()
    }

    group.notify(queue: .main) { [weak self] in // 2
        self?.textLabel.text = "All jobs have completed!"
    }
}

The code above kicks off an API call for each url, appends the fetched user data to an array, and once all API calls done the textLabel.text will be “All jobs have completed!”.

Let’s deep dive into comment lines:

1. Create a new DispatchGroup() to track the number of times we start work, and the number of times we complete work.

2. Schedule a work item (update textLabel’s text) that will be executed on the main thread (indicated dispatch queue) once all work in the group is done. Note: The notification is itself asynchronous, so it’s possible to submit more jobs to the group after calling notify, as long as the previously submitted jobs haven’t already completed. (Source: Concurrency by Tutorials - Ray Wenderlich)

3. For each url that was created, enter the dispatch group. It will increment the counter for the number of running tasks every time we enter the group.

4. Once the API call done, independently from the error or success cases, leave the dispatch group. Otherwise, you will never be signaled of completion. Once the last task is completed, notify(queue:) callback method will be informed.
   
   As you can see the dispatch groups are very handy tool. Now, let’s see the Swift Concurrency version.

TaskGroup

It’s pretty much like DispatchGroup, but in the modern Swift Concurrency world. A TaskGroup manages a dynamic number of child tasks, and automatically waits for all of them to complete before returning. Unlike DispatchGroup, it doesn’t track counters manually (comment line // 3 in the previous code block) instead, it ties the lifetime of child tasks directly to the group itself.

Let’s look at the example:

@MainActor
func fetchUserProfiles() async {
    var results = [Data]()
    let userIDs = [1, 2, 3]
    let urls = userIDs
        .compactMap { URL(string: "https://jsonplaceholder.typicode.com/users/\($0)") }

    await withTaskGroup(of: Data?.self) { group in // 1
        for url in urls {
            group.addTask { // 3
                let (data, _) = try? await URLSession.shared.data(from: url)
                return data
            }
        }

        for await data in group { // 2
            if let data {
                results.append(data)
            }
        }
    } // 4

    textLabel.text = "All jobs have completed"
}

I used exact same code example in a TaskGroup way.

Let’s deep dive into comment lines:

1. withTaskGroup(of:) creates a new task group, similar to DispatchGroup(). Unlike DispatchGroup though, you declare upfront what type each child task will produce (i.e Data?.self).

2. for await data in group replaces group.notify(queue:). Instead of scheduling a callback to fire when all work is done, you iterate over results as each child task completes. The loop ends naturally once every child task finishes.

3. group.addTask {} replaces the group.enter() + closure + group.leave() threes*me 🙊. Adding a task implicitly enters the group, and returning from the closure implicitly leaves it, no risk of forgetting a leave().

4. The closing brace of withTaskGroup is the moment all child tasks are guaranteed to be done. This is where group.notify(queue:) would have fired in the DispatchGroup world. After this point, results is safe to use.

Note: Even though fetchUserProfiles() is marked @MainActor, the network calls inside addTask will never run on the main thread. URLSession is in charge of its own execution context, not the caller. So marking the function @MainActor is completely safe and won’t block the main thread. Thanks Matt for pointing out! 🤩

As you can see, TaskGroup achieves the exact same goal as DispatchGroup but the structured approach eliminates the enter/leave counter belly dance, and await replaces the callback entirely, making the code read easily like synchronous code.

If you find modern concurrency super confusing like me, let’s start with these WWDC videos first:

- WWDC21 - Swift concurrency: Behind the scenes
- WWDC22 - Visualize and optimize Swift Concurrency
- WWDC23 - Beyond the basics of structured concurrency

- the adaptee (UK wall socket) has the incompatible interface the client (MacBook charger) can’t plug directly,
- your MacBook charger is the client that has the protocol it was built with EU 2-pin,
- the adapter that we bought from the store, sits in between, translating one protocol to the other without changing either side’s behavior

Here's the Swift code demonstrated on the plug analogy. UK wall socket as Adaptee, MacBook EU charger as Client, and the travel adapter as the Adapter:

// MARK: - Adaptee
// The UK wall socket — it only has UK 3-pin
 
class UKWallSocket {
    func provideUKPower() -> String {
        return "⚡️ 240V via UK 3-pin socket"
    }
}

The MacBook charger expects EU 2-pin power and it only works with EUPowerProvider. It has no idea whether the power comes from an EU socket
or a UK socket adapted via TravelAdapter. MacBookCharger depends on the protocol (EUPowerProvider), not the concrete adapter. This keeps it decoupled.

// MARK: - Client Protocol
// The MacBook charger expects EU 2-pin power
 
protocol EUPowerProvider {
    func provideEUPower() -> String
}

// MARK: - Client
 
class MacBookCharger {
    
    private let powerProvider: EUPowerProvider
 
    init(powerProvider: EUPowerProvider) {
        self.powerProvider = powerProvider
    }
 
    func charge() {
        let power = powerProvider.provideEUPower()
        print("MacBook charging... %\(power)")
    }
}

The travel adapter sits between the two. It plugs into the UK socket (Adaptee) and
exposes the EU interface the MacBook charger (Client) expects. TravelAdapter wraps the adaptee(UKWallSocket) via composition (not inheritance), which is the preferred Swift approach.

// MARK: - Adapter
 
class TravelAdapter: EUPowerProvider {
 
    private let ukSocket: UKWallSocket
 
    init(ukSocket: UKWallSocket) {
        self.ukSocket = ukSocket
    }
 
    func provideEUPower() -> String {
        let ukPower = ukSocket.provideUKPower()
        return "🔌 Adapted to EU 2-pin -> \(ukPower)"
    }
}

Doing so, the UK socket's behavior is unchanged and the adapter only translates, exactly as the pattern intends.

// MARK: - Usage
 
let ukSocket = UKWallSocket() // Adaptee
// Plug adapter into the ukSocket
let adapter = TravelAdapter(ukSocket: ukSocket) // Adapter
// Plug MacBook charger into the adapter
let macCharger = MacBookCharger(powerProvider: adapter) // Client
 
macCharger.charge()
// MacBook charging... 🔌 Adapted to EU 2-pin -> ⚡️ 240V via UK 3-pin socket

Conclusion

In this article, I explained how the Adapter Pattern is used to make two classes with incompatible APIs work together. I demonstrated how to define an adapter by creating a class that wraps around the object being adapted, conforming to the interface the client expects.

Sources:
- https://www.amazon.com/Design-Patterns-Swift-Adam-Freeman/dp/148420395X

The lesson is not never use LLMs. It is don’t trust the diff until you’ve validated size, bundle contents, and build configuration. The same things we should have checked before shipping anything, human or AI-written.

What went wrong

Apple’s Game Center integration in modern Xcode often uses a GameCenterResources.gamekit package: JSON plus optional localized images, Pull / Push with App Store Connect. That file belongs in the project for authoring and sync.

What it typically does not need, for a standard achievement setup, is to sit in Copy Bundle Resources for your Release app target. `GameKit` loads achievement metadata and art from Apple’s services when your app uses the right IDs. Much of that art lives on Apple’s CDN (you will see `mzstatic.com` URLs inside `gameCenterResources.json`). If some locales instead use relative paths (for example `da/AchievementImage-….png`), those files are candidates to be bundled. If the entire `.gamekit` tree is copied into the app, every user pays for that download and disk use.

In Walk Mate, the package had been wired like ordinary app resources including many megabytes of achievement images. It had also landed in more than one target (including an extension), where it had no runtime purpose.

That’s the edge case: Game Center is configured with only what must ship in the IPA should ship.

What I changed

1. GameCenterResources.gamekit was removed from Copy Bundle Resources for the main iOS app and the notification service extension (it should never have been duplicated there).

2. The `.gamekit` bundle stays in the repository under version control so you can still use Xcode → (Game Center editor) … → Pull from / Push to App Store Connect; you simply stop embedding that package in the built product shipped to users.

3. gameCenterResources.json clarified the mechanics: many locales referenced CDN URLs, Localization entries used local relative paths, which is how multi-megabyte PNGs became part of the payload while other languages did not!

After a clean Archive, the App Thinning Size Report moved from roughly ~125–130 MB compressed for representative iPhone/iPad variants down to roughly ~23–26 MB compressed 😀 for comparable slices, a drop on the order of ~100 MB of avoidable bundle weight, consistent with removing the mistaken resource package. 🤨

How to check size

After Xcode → Product → Archive, use the workflow that produces App Thinning analysis from Xcode Organizer when working with an App Store archive. Open App Thinning Size Report.txt.

• Compare compressed vs uncompressed per variant: compressed is closest to download perception, uncompressed reflects expansion for that thinned slice.

• Keep two reports (before / after a change) and diff the same variant family. That is a cheap regression guard for accidental resource bloat.

Reducing app size in general

• Judge shipping app size from Release/Archive, not default Debug Run.

• Asset catalogs: correct scales, avoid overweight PNGs where better formats or simplification suffice.

• Dependencies: every Swift package and framework has a cost! Periodic review of what links into the main target matters!

• Extensions: each target has its own resources rules, so, avoid duplicating large blobs.

• When prompting an LLM, state non-goals explicitly like: “Do not add to Copy Bundle Resources unless runtime-required; verify with Archive + App Thinning diff.”

Why we shouldn’t use LLMs blindly

Models optimize for edit from your prompt and visible code. For instance, they don’t automatically enforce your download size or budget, the distinction between authoring / sync assets and runtime bundle contents.

Conclusion

AI can speed things up, -but it’s anyways your responsibility to triple-check- so you don’t embed authoring assets nobody needed at runtime 😅



Source: https://developer.apple.com/documentation/xcode/reducing-your-app-s-size

Even almost every people can speak English in Nordic countries, we’re supporting 7 different Nordic languages in my company.

We’re using POEditor for faster localization processes.

POEditor

In this article, I will explain how to add a language, export, and import localization files in a faster way.

First of all, we have a String extension like this:

extension String {
    public func localized(_ bundle: Bundle = .locales) -> String {
        NSLocalizedString(self, bundle: bundle, comment: "")
    }
}

//Usage
class Foo: UIViewController {
    let title = "settings_title".localized()
}

When the new strings are added to the code base,

“settings_title”.localized()

then you need to add these new strings to

Add the string to the English version of Supporting Files/Localizable.strings
i.e.: Project_Directory/Project_Name/Sources/Locales/en.lproj/Localizable.strings

and send to POEditor (either manually or automatically). Then someone(licensed translator) does the translation in POEditor manually.
After that, you should be able to fetch them (either manually or automatically) from POEditor.

How do we extract/import translations from/to POEditor automatically?

We can either manually send the new strings to poeditor.com using
fastlane translations_extract fastlane script or GitLab CI doing it for us automatically.

After someone(licensed translator) does the translation in POEditor manually.

After all of that has been done we can run the following command
fastlane translations_import to fetch the new translations and check them into the codebase.

Conclusion

POEditor is a great localization tool to increase user experience and save time since you will be waiting for translations for the new strings.

What is VoiceOver?

As you guess disabled people use smartphone apps as well. Designing your apps with accessibility in mind helps everyone use them, including people with vision, or hearing disabilities.

VoiceOver is a screen reader built into Apple Inc.’s macOS, iOS, tvOS, watchOS, and iPod operating systems. By using VoiceOver, the user can access their Macintosh or iOS device based on spoken descriptions and, in the case of the Mac, the keyboard.

Why Accessibility?

In my current company, we’re also supporting Accessibilities, especially VoiceOver. In our e-paper applications, we have active 2K blind users.

• You’ll reach a larger group.

• It feels good to know you’re making a noticeable difference in more people’s life.

How to Activate and Use VoiceOver?

You can find detailed information about activation and usage of VoiceOver on iPhone on Apple’s website:
https://support.apple.com/guide/iphone/iph3e2e415f/ios

• Single-tap anywhere and VoiceOver will read information from the item’s accessibility attributes loudly.

• Single-swipe left or right and VoiceOver will select the next visible accessibility item and read it loudly.

• Single-swipe down to spell the focused item letter-by-letter.

• Double-tap to select the specific item.

• Three-finger-swipe left or right to navigate forward or backward in a page view.

For the complete list of VoiceOver gestures, check out Apple’s Learn VoiceOver gestures on iPhone. So now you know how VoiceOver works.

Accessibility Attributes

An accessibility attribute has five properties:

First of all, you should define the accessibility element of the UI element.

titleLabel.isAccessibilityElement = true

1. accessibilityLabel: A concise way to identify the control or view.

titleLabel.accessibilityLabel = foo.title

2. accessibilityTraits: These describe the element’s state or behavior. A cell trait might be .button, for example.

cell.accessibilityTraits = .none

cell.accessibilityTraits = .button

cell.accessibilityTraits = .link

cell.accessibilityTraits = .header

cell.accessibilityTraits = .adjustable

cell.accessibilityTraits = .allowsDirectInteraction

cell.accessibilityTraits = .causesPageTurn

cell.accessibilityTraits = .image

cell.accessibilityTraits = .keyboardKey

cell.accessibilityTraits = .notEnabled

cell.accessibilityTraits = .playSound

cell.accessibilityTraits = .searchField

cell.accessibilityTraits = .startsMediaSession

cell.accessibilityTraits = .staticText

cell.accessibilityTraits = .selected

cell.accessibilityTraits = .summaryElement

cell.accessibilityTraits = .tabBar

3. accessibilityHint: Describes the action an element completes. For example:

playButton.accessibilityHint = "double_tap_to_pause"
loginCell.accessibilityHint = "double_tap_to_log_out"

4. accessibilityFrame: The frame of the element within the screen, in the format of a CGRect. VoiceOver speaks the contents of the CGRect.

5. accessibilityValue: The value of an element. For example, with a progress bar or a slider, the current value might read: 5 out of 100.

Using the Accessibility Inspector

There’s a tool named Accessibility Inspector, which does the following:

• Lets you check the accessibility attributes of UI elements in Inspection Mode.

• Provides live previews of accessibility elements without leaving your app.

• Supports all platforms including macOS, iOS, watchOS, and tvOS.

To do all of these things, open it in the Xcode menu by navigating to Xcode ▸ Open Developer Tool ▸ Accessibility Inspector.

Conclusion

You learned about VoiceOver. You used the Accessibility Inspector to perform audits by scrolling through every accessible element. See you 🖖🏼

@MainActor Attribute:

- The `@MainActor` attribute plays a crucial role in Swift Concurrency by ensuring specific parts of your code always run on the main thread.

- Particularly useful in SwiftUI, where UI updates must be performed on the main thread.

- SwiftUI views are implicitly marked as `@MainActors` when they have `@ObservableObject` properties like `@StateObject`, `@ObservedObject`, and `@EnvironentObject`.

struct MyView: View {
  @StateObject var vm = MyViewModel()
  
  var body: some View {
   Button {
    Task {
      await vm.performSomeWork()
    }
   } label: {
     Text("Test")
   }
  }
}

Key Points:

- `await` doesn’t block the current thread; it allows suspension of the current task, enabling other operations to continue.

- Functions decide the execution context, not where they are called from.

Changing Execution Context:

- You can explicitly specify the execution context using `@MainActor` or opt out of `MainActor` isolation with `noisolated`.

class MyViewModel: ObservableObject {
 // This will always run on the Global executor
 func performSomeWork() async {}
// This will always run on the Main actor / thread
 @MainActor func performSomeWork() async {}
// This will _not_ run on the Main actor / thread
 nonisolated func performSomeWork() async {}
}

Structured Concurrency and Tasks:

- A Task represents a unit of work, and there are two types: unstructured and detached.

- Unstructured tasks inherit parts of their creation context but are not child tasks of their creation context.

- Detached tasks inherit nothing and work independently.

// Creating an unstructured Task
Task {
 // I'm an unstructured task
}
// Creating a detached Task
Task.detached {
 // I'm a detached task
}

Key Takeaways:

- Unstructured tasks are not child tasks of their creation context.

- Detached tasks inherit nothing and are their own islands of concurrency.

Structured Concurrency:

- Structured concurrency ensures that child tasks are completed before the parent task finishes.

- Unstructured tasks can outlive their parent tasks, but structured tasks enforce completion of child tasks before the parent task concludes.

Example:

func runTask() async {
  let result = await withTaskGroup(of: Int.self) { group -> Int in
  group.spawn {
  await longRunningTask()
 }

// Wait for all child tasks to finish and collect the results
 var total = 0
 for await result in group {
  total += result
 }
  return total
 }
  print("Result: \(result)")
}

Actor Isolation:

- Actors provide a safe way to access and modify mutable state concurrently.

- Methods and properties marked with `@MainActor` are actor-isolated.

- Using `@MainActor` ensures that the method or property runs on the main thread.

@MainActor
class SafeActorIsolatedClassExample {
 var foo = Foo(bar: "baz")

 func thisIsSafe() {
   Task {
     foo.bar = "qux"
   }
  }
}

Key Insights:

- Whole classes or properties can be marked as `@MainActor`.

- `UIViewController` is actor-isolated to `@MainActor`, ensuring safe concurrent access.

Conclusion:

Swift Concurrency brings powerful features to the table, allowing developers to create responsive and efficient asynchronous code. Understanding the nuances of `@MainActor`, structured concurrency, and actor isolation is essential for building robust and reliable Swift applications. Donny Wals’s presentation at iOS Conf SG 2023 provides valuable insights into mastering Swift Concurrency.

Sources:
- [Your Brain 🧠 on Swift Concurrency — iOS Conf SG 2023](

)
- [Mutating a mutable Struct within a Swift Task](https://stackoverflow.com/a/76868102/4442254)

Introduction:

Map annotation clustering is a technique used to group nearby annotations on a map into a single cluster, which is represented by a single annotation. This is important for improving performance and user experience, especially when dealing with large datasets. Without clustering, a map with many annotations can become cluttered and difficult to read, leading to a poor user experience. Clustering reduces the number of annotations displayed on the map, making it easier to read and improving performance by reducing the amount of data that needs to be rendered.

Overview of Map Annotation Clustering

First of all, I got a lot of help from this open-source project (ClusterMap) in order to implement map annotation clustering in iOS 17 SwiftUI Map. I highly recommend checking it out if you want to learn more about how it works.

Difference between working with UIKit Map and SwiftUI Map

In terms of data handling and performance, ClusterMap library provides a solution for implementing map annotation clustering in SwiftUI Map() by changing the data structure from an array or dictionary to a tree.

The most critical difference from the native implementation in UIKit is that the ClusterMap library handles adding data asynchronously, avoiding lags when adding significant quantities of data. In contrast, Apple handles adding data to the MainThread, which can cause lags when scrolling or zooming. The library requires the dimensions of the grid used in clustering to be provided through a custom configuration object. This allows for custom configuration of the grid size used in clustering, improving performance during scrolling or zooming. While Apple’s implementation is more straightforward, the performance issue could be critical (e.g. Memory usage reduced from ~500 MB to ~230 MB).

Integration with SwiftUI Map

When working with iOS 17, the library can be placed in an object marked with the @Observable macro and added to the hierarchy via the .environment modifier. The map will automatically reload when needed, such as when the camera position changes, and annotations can be added or removed in any other views. In my case I was trying to MKLocalSearch to search for places and display them on the map through a tabbar button.

An asynchronous local search is started using the MKLocalSearch class and the initialized request. The result of the search is stored in an async let variable called searchResult. After the search is completed, the clusterManager object is used to remove all existing annotations from the map. The mapItems property of the searchResult is then added to the clusterManager using the add method. Finally, the reloadAnnotations method is called to update the map view with the new annotations.

import ClusterMap
import Foundation
import MapKit
 
struct ExampleClusterAnnotation: Identifiable {
    var id = UUID()
    var coordinate: CLLocationCoordinate2D
    var count: Int
}
    
@Observable
class LocalSearchCompleter: NSObject {
var mapSize: CGSize = .zero
var currentRegion: MKCoordinateRegion = .userLocation
var annotations = [MKMapItem]() // #1 element of the tree
var clusters = [ExampleClusterAnnotation]() // #2 element of the tree
 
let customConfig = ClusterManager<MKMapItem>.Configuration(
    cellSizeForZoomLevel: { (zoom: Int) -> CGSize in
        switch zoom {
        case 13...15: return CGSize(width: 64, height: 64) // grid size used in clustering
        case 16...18: return CGSize(width: 32, height: 32)
        case 19...: return CGSize(width: 16, height: 16)
        default: return CGSize(width: 88, height: 88)
        }
    }
)
 
var clusterManager: ClusterManager<MKMapItem>
 
override init() {
    clusterManager = ClusterManager<MKMapItem>(configuration: customConfig)
}
 
func search(for query: String) async {
        let request = MKLocalSearch.Request()
        request.naturalLanguageQuery = query
        request.region = currentRegion
        do {
            async let searchResult = MKLocalSearch(request: request).start()
            await clusterManager.removeAll()
            try await clusterManager.add(searchResult.mapItems)
            await reloadAnnotations()
        } catch {
            assertionFailure("Error: \(error.localizedDescription)")
        }
    }
 
    func reloadAnnotations() async {
        async let changes = clusterManager.reload(mapViewSize: mapSize, coordinateRegion: currentRegion)
        await applyChanges(changes)
    }
 
    @MainActor
    private func applyChanges(_ difference: ClusterManager<MKMapItem>.Difference) {
        for removal in difference.removals {
            switch removal {
            case .annotation(let annotation):
                annotations.removeAll { $0 == annotation }
            case .cluster(let clusterAnnotation):
                clusters.removeAll { $0.id == clusterAnnotation.id }
            }
        }
        for insertion in difference.insertions {
            switch insertion {
            case .annotation(let newItem):
                annotations.append(newItem)
            case .cluster(let newItem):
                clusters.append(ExampleClusterAnnotation(
                    id: newItem.id,
                    coordinate: newItem.coordinate,
                    count: newItem.memberAnnotations.count
                ))
            }
        }
    }
}
 
extension MKMapItem: CoordinateIdentifiable, Identifiable {
  public var id: String {
      placemark.region?.identifier ?? UUID().uuidString
  } 
 
  public var coordinate: CLLocationCoordinate2D {
      get { placemark.coordinate }
      set(newValue) { }
  }
}

The customConfig object is defined using the ClusterManager class, which allows for custom configuration of the grid size used in clustering. Finally, the clusterManager property is initialized with the custom configuration.

Usage of the LocalSearchCompleter() in SwiftUI View:

import SwiftUI
import MapKit
import ClusterMap
 
struct LocationRequestIsOnView: View {
    
    @State private var searchClient = LocalSearchCompleter()
 
    var body: some View {
        NavigationStack {
            ZStack {
                mapView
            }
        }
    }
    
    var mapView: some View {
        Map(
            initialPosition: .region(searchClient.currentRegion),
            selection: $selectedResult
        ) {
            if !showSettingsView {
                ForEach(searchClient.annotations) { result in
                    if systemImageName == "bolt.car.circle.fill" {
                        Marker(result.placemark.name ?? "", systemImage: "bolt.car.circle.fill", coordinate: result.coordinate)
                            .tag(result)
                    } else {
                        Marker(result.placemark.name ?? "", systemImage: "fuelpump.circle.fill", coordinate: result.coordinate)
                            .tag(result)
                    }
                }
 
                ForEach(searchClient.clusters) { result in
                    if systemImageName == "bolt.car.circle.fill" {
                        Marker("\(result.count)", systemImage: "bolt.car.fill", coordinate: result.coordinate)
                    } else {
                        Marker("\(result.count)", systemImage: "fuelpump.circle.fill", coordinate: result.coordinate)
                    }
                }
                
                UserAnnotation()
                
                if let route {
                    MapPolyline(route)
                        .stroke(.blue, lineWidth: 5)
                }
            }
        }
        .readSize(onChange: { newValue in
            searchClient.mapSize = newValue
        })
        .onChange(of: selectedResult) {
            if selectedResult != nil {
                getDirections()
                isShowingBottomSheet = true
            } else {
                isShowingBottomSheet = false
            }                
        }
        .sheet(isPresented: $isShowingBottomSheet) {
            ItemInfoView(
                isShowingBottomSheet: $isShowingBottomSheet,
                route: $route,
                selectedResult: $selectedResult, selectedTabBarButton: selectedTabBarButton,
                url: self.shareLocation()
            )
            .presentationDetents([.medium, .fraction(0.12), .large])
            .presentationBackgroundInteraction(.enabled(upThrough: .medium))
            .presentationDragIndicator(.visible)
        }
        .onMapCameraChange { context in
            searchClient.currentRegion = context.region
        }
        .onMapCameraChange(frequency: .onEnd) { context in
            Task.detached {
                await searchClient.reloadAnnotations()
            }
        }
        .mapControls {
            MapUserLocationButton()
            MapCompass()
            MapScaleView()
        }
        .environment(searchClient)
    }
}

There is a ForEach loop that iterates over the searchClient.annotations array (which are the first element of the tree). For each annotation, a Marker view is created and displayed on the map. The Marker represents a location on the map and includes a title, a system image, and a coordinate. Similarly, there is another ForEach loop that iterates over the searchClient.clusters array (which are the second elements of the tree). For each cluster, a Marker view is created and displayed on the map. The Marker represents a cluster of locations and includes the count of locations in the cluster, a system image, and a coordinate. The mapView also includes various modifiers and event handlers. For example, the readSize modifier is used to update the searchClient's mapSize property when the size of the map view changes. The onChange event handler is used to perform actions when the selectedResult changes, such as getting directions and showing or hiding a bottom sheet.

Performance Benefits of ClusterMap

…and so many other hangs, hitchs and lags that I was experiencing with the native MapKit implementation which I couldn’t add the Xcode Instruments screenshots.

Overall, the project demonstrates how the combination of SwiftUI Map, ClusterMap, and other technologies can be used to create a performant and customizable map view in iOS 17. “Thanks Apple 🤣” By following best practices for implementing map annotation clustering, such as using a third-party library and providing custom configuration for the grid size, you can create a better user experience and improve the performance of your MapKit projects.

See you ✌🏼

The Composable Architecture (TCA, for short)(opens in a new tab) is a library for building applications in a consistent and understandable way, with composition, testing, and ergonomics in mind, developed by Brandon Williams(opens in a new tab) and Stephen Celis(opens in a new tab) from Point-Free. It can be used in SwiftUI, UIKit, and more, and on any Apple platform (iOS, macOS, tvOS, and watchOS).”

Core tools

• State management

How to manage the state of your application using simple value types, and share state across many screens so that mutations in one screen can be immediately observed in another screen.

• Composition

How to break down large features into smaller components that can be extracted to their own, isolated modules and be easily glued back together to form the feature.

• Side effects

How to let certain parts of the application talk to the outside world in the most testable and understandable way possible.

• Testing

How to not only test a feature built in the architecture, but also write integration tests for features that have been composed of many parts, and write end-to-end tests to understand how side effects influence your application. This allows you to make strong guarantees that your business logic is running in the way you expect.

• Ergonomics

How to accomplish all of the above in a simple API with as few concepts and moving parts as possible.

Basic Usage

To build a feature using the Composable Architecture you define some types and values that model your domain:

• State: A type that describes the data your feature needs to perform its logic and render its UI.

• Action: A type that represents all of the actions that can happen in your feature, such as user actions, notifications, event sources and more.

• Reducer: A function that describes how to evolve the current state of the app to the next state given an action. The reducer is also responsible for returning any effects that should be run, such as API requests, which can be done by returning an Effect value.

• Store: The runtime that actually drives your feature. You send all user actions to the store so that the store can run the reducer and effects, and you can observe state changes in the store so that you can update UI.

The benefits of doing this are that you will instantly unlock testability of your feature, and you will be able to break large, complex features into smaller domains that can be glued together.

Demo Project

As a basic example, consider a UI that shows a 2-columns grid list along with “#” team/player ids, names and, team logos. When the views appear, there is an API request to fetch NBA teams and players and then displays in a 2-columns grid list.

🧑🏼‍🦳👨🏼‍🦳 To implement this root (grand-parent) feature we create a new type that will house the root domain and behavior of the feature by conforming to Reducer:

import ComposableArchitecture

struct RootFeature: Reducer {}

In here we need to define a type for the root feature’s state, which consists of a selected tab, as well as parent feature states that are TeamListFeature.State() and PlayerListFeature.State():

struct RootFeature: Reducer {
    struct State: Equatable {
        var selectedTab = Tab.teams
        var teamListState = TeamListFeature.State()
        var playerListState = PlayerListFeature.State()
    }
}

We need to define a type for the feature’s tabs. There are the obvious tabbar items, such as teams, favorites and players.

struct RootFeature: Reducer {
    struct State: Equatable {
        var selectedTab = Tab.teams
        var teamListState = TeamListFeature.State()
        var playerListState = PlayerListFeature.State()
    }
    enum Tab {
        case teams
        case favorites
        case players
    }
}

We also need to define a type for the root (grand-parent) feature’s actions. There are the obvious actions, such as tabbar item selected, and the actions that are encapsulate all actions from the child domain/feature of the root (grand-parent) domain/feature, providing a comprehensive and cohesive approach.

struct RootFeature: Reducer {
    struct State: Equatable {
        var selectedTab = Tab.teams
        var teamListState = TeamListFeature.State()
        var playerListState = PlayerListFeature.State()
    }
    enum Tab {
        case teams
        case favorites
        case players
    }
    enum Action: Equatable {
        case tabSelected(Tab)
        case teamList(TeamListFeature.Action)
        case playerList(PlayerListFeature.Action)
    }
}

And then we implement the reduce method which is responsible for handling the actual logic and behavior for the feature. It describes how to change the current state to the next state, and describes what effects need to be executed. Some actions don’t need to execute effects, and they can return .none to represent that:

struct RootFeature: Reducer {
    struct State: Equatable {
        var selectedTab = Tab.teams
        var teamListState = TeamListFeature.State()
        var playerListState = PlayerListFeature.State()
    }
    
    enum Tab {
        case teams
        case favorites
        case players
    }
    
    enum Action: Equatable {
        case tabSelected(Tab)
        case teamList(TeamListFeature.Action)
        case playerList(PlayerListFeature.Action)
    }
    
    // Dependencies
    var fetchTeams: () async throws -> TeamsModel
    var fetchPlayers:  @Sendable () async throws -> PlayersModel
    var uuid: @Sendable () -> UUID
    
    static let live = Self(
        fetchTeams: MatchScoresClient.liveValue.fetchTeams,
        fetchPlayers: MatchScoresClient.liveValue.fetchPlayers,
        uuid: { UUID() }
    )
    
    var body: some Reducer<State, Action> {
        Reduce { state, action in
            switch action {
            case .teamList:
                return .none
            case .playerList:
                return .none
            case .tabSelected(let tab):
                state.selectedTab = tab
                return .none
            }
        }
        Scope(state: \.teamListState, action: /RootFeature.Action.teamList) {
            TeamListFeature(uuid: uuid)
        }
        Scope(state:  \.playerListState, action: /RootFeature.Action.playerList) {
            PlayerListFeature(uuid: uuid)
        }
    }
}

And then finally we define the view that displays the feature. It holds onto a StoreOf<RootFeature> so that it can observe all changes to the state and re-render, and we can send all user actions to the store so that state changes. WithViewStore is a view helper that transforms a Store into a ViewStore so that its state can be observed by a view builder:

struct RootView: View {
    let store: StoreOf<RootFeature>
    
    var body: some View {
        WithViewStore(self.store, observe: { $0 }) { viewStore in
            TabView(
                selection: viewStore.binding(
                    get: \.selectedTab,
                    send: RootFeature.Action.tabSelected
                )
            ) {
                TeamListView(
                    store: self.store.scope(
                        state: \.teamListState,
                        action: RootFeature.Action
                            .teamList
                    )
                )
                .tabItem {
                    Image(systemName: "list.bullet")
                    Text("Teams")
                }
                .tag(RootFeature.Tab.teams)
                
                PlayerListView(
                    store: self.store.scope(
                        state: \.playerListState,
                        action: RootFeature.Action.playerList
                    )
                )
                .tabItem {
                    Image(systemName: "person.fill")
                    Text("Players")
                }
                .tag(RootFeature.Tab.players)
            }
            .accentColor(Color("launch-screen-background"))
        }
    }
}

Once we are ready to display these views, for example in the app’s entry point, we can construct a store. This can be done by specifying the initial state to start the application in, as well as the reducer that will power the application:

import SwiftUI
import ComposableArchitecture

@main
struct MatchScoresTCAApp: App {
    var body: some Scene {
        WindowGroup {
            RootView(
                store: Store(initialState: RootDomain.State()) {
                    RootDomain(fetchTeams: { TeamsModel.sample}, fetchPlayers: { PlayersModel.sample }, uuid: { UUID() }
                    )
                }
            )
        }
    }
}

👱🏻‍♂️👱🏼To implement this parent feature we create a new type that will house the domain and behavior of the feature by conforming to Reducer:

import ComposableArchitecture

struct TeamListFeature: Reducer {
}

In here we need to define a type for the feature’s state, which consists of a data loading status, as well as an TeamsModel that is an Identified collection which are designed to solve all of the collection problems by providing data structures for working with collections (teams and meta) of identifiable elements in an ergonomic, performant way:

struct TeamListFeature: Reducer {
    struct State: Equatable {
        var dataLoadingStatus = DataLoadingStatus.notStarted
        var resultTeamRequestInFlight: TeamsModel?
        var teamList: IdentifiedArrayOf<TeamFeature.State> = []
        
        var shouldShowError: Bool {
            dataLoadingStatus == .error
        }
        
        var isLoading: Bool {
            dataLoadingStatus == .loading
        }   
    }
}

We also need to define a type for the feature’s actions. There are the obvious action, such as view on appear and the action that occurs when we receive a response from the team/player API request, and define a team(id: TeamFeature.State.ID, action: TeamFeature.Action) case to handle actions sent to the child domain (TeamFeature: Reducer):

struct TeamListFeature: Reducer {
    struct State: Equatable {
        var dataLoadingStatus = DataLoadingStatus.notStarted
        var teamList: IdentifiedArrayOf<TeamFeature.State> = []
        var shouldShowError: Bool {
            dataLoadingStatus == .error
        }
        var isLoading: Bool {
            dataLoadingStatus == .loading
        }   
    }
    enum Action: Equatable {
        case fetchTeamResponse(TaskResult<TeamsModel>)
        case team(id: TeamFeature.State.ID, action: TeamFeature.Action)
        case onAppear
    }
}

And then we implement the reduce method which is responsible for handling the actual logic and behavior for the feature. It describes how to change the current state to the next state, and describes what effects need to be executed. Some actions don’t need to execute effects, and they can return .none to represent that:

struct TeamListFeature: Reducer {
  struct State: Equatable { /* ... */ }
  enum Action: Equatable { /* ... */ }

func reduce(into state: inout State, action: Action) -> Effect<Action> {
        switch action {
        case .fetchTeamResponse(.failure(let error)):
            state.dataLoadingStatus = .error
            print(error)
            print("Error getting products, try again later.")
            return .none
            
        case let .fetchTeamResponse(.success(teamData)):
            state.teamList = IdentifiedArrayOf(
                uniqueElements: teamData.data.map {
                    TeamFeature.State(
                        id: uuid(),
                        team: $0
                    )
                }
            )
            state.dataLoadingStatus = .loading
            return .none
            
        case .onAppear:
            return .run { send in
                await send (
                    .fetchTeamResponse(
                        TaskResult { try await MatchScoresClient.liveValue.fetchTeams()
                        }
                    )
                )
            }
        case .team:
            return .none
        }
    }
}

And then finally we define the view that displays the feature. It holds onto a StoreOf<TeamListFeature> so that it can observe all changes to the state and re-render, and we can send all user actions to the store so that state changes. ForEachStore loops over a store’s collection with a store scoped to the domain of each element. This allows us to extract and modularize an element’s view and avoid concerns around collection index math and parent-child store communication:

struct TeamListView: View {
    let store: StoreOf<TeamListFeature>
    
    private let columns = Array(
        repeating: GridItem( .flexible()),
        count: 2
    )
    
    var body: some View {
        WithViewStore(self.store, observe: { $0 }) { viewStore in
            ZStack{
                ScrollView {
                    LazyVGrid(columns: columns,
                              spacing: 16) {
                        ForEachStore(
                            self.store.scope(
                                state: \.teamList,
                                action: TeamListFeature.Action.team(id:action:)
                            )
                        ) {
                            TeamView(store: $0)
                        }
                    }
                              .padding()
                              .accessibilityIdentifier("peopleGrid")
                }
                .refreshable {
                    viewStore.send(.onAppear)
                }
            }
            .navigationTitle("Teams")
            .onAppear {
                viewStore.send(.onAppear)
            }
        }
    }
}

👶🏼👶🏼 To implement this child (grand-child of RootFeature or child of TeamListFeature) feature we create a new type that will house the domain and behavior of the child feature by conforming to Reducer:

struct TeamFeature: Reducer {
    struct State: Equatable, Identifiable {
        let id: UUID
        let team: TeamData
    }
    enum Action: Equatable { }
    
    func reduce(into state: inout State, action: Action) -> Effect<Action> { }
}

And then we define the view that displays the feature. It holds onto a StoreOf<TeamFeature> so that it can observe all changes to the state and re-render, and we can send all user actions to the store so that state changes. WithViewStore is a view helper that transforms a Store into a ViewStore so that its state can be observed by a view builder:

import SwiftUI
import ComposableArchitecture

struct TeamView: View {
    let store: StoreOf<TeamFeature>
    
    var body: some View {
        WithViewStore(self.store, observe: {$0} ) { viewStore in
            VStack(spacing: .zero) {
                
                background
                
                VStack(alignment: .leading) {
                    Text(viewStore.team.fullName)
                        .foregroundColor(Theme.text)
                        .font(
                            .system(.largeTitle, design: .rounded)
                        )
                        .background(
                            Image(avatars[viewStore.team.id - 1])
                                .opacity(0.4)
                                .aspectRatio(contentMode: .fill)
                        )
                }
                .frame(maxWidth: .infinity, alignment: .leading)
                .frame(height: 150.0)
                .padding(.horizontal, 8)
                .padding(.vertical, 5)
                .background(Theme.detailBackground)
                
                VStack {
                    PillView(id: viewStore.team.id)
                        .padding(.leading, 10)
                        .padding(.top, 10)
                }
                
            }
            .clipShape(
                RoundedRectangle(cornerRadius: 16,
                                 style: .continuous)
            )
            .shadow(color: Theme.text.opacity(0.1),
                    radius: 2,
                    x: 0,
                    y: 1)
            .edgesIgnoringSafeArea([.top, .leading, .trailing])
        }
    }
}

Result:

You can find all the codes in here.

First Touch with the Vision Pro :D

Experience at iOSKonf 24:

iOSKonf 24 was a remarkable event that brought together developers, enthusiasts, and industry experts from around the world. The conference was filled with insightful sessions, engaging discussions, and hands-on experiences with the latest advancements in iOS development. One of the highlights of the event was the chance to get my hands on VisionPro.

Testing the EV Charger Finder App:

As a passionate advocate for sustainable transportation, I have been developing an EV charger finder application that aims to enhance the accessibility and convenience of electric vehicle charging. One of the main functionalities of the application is a long-distance route planner, which assists EV owners in planning their trips by identifying charging stations along their route.

During my time at iOSKonf 24, I had the opportunity to put this feature to the test. With VisionPro’s advanced capabilities, the route planner provided accurate and real-time information about nearby charging stations, their availability, and compatibility with my EV model. This feature proved to be invaluable, especially during long-distance trips where finding reliable charging infrastructure is crucial.

Conclusion:

In conclusion, my experience with VisionPro and the EV charger finder app at iOSKonf 24 was nothing short of amazing. The combination of Apple’s latest technology and my app’s long-distance route planner feature has the potential to revolutionize the way electric vehicle owners plan their journeys. I am grateful to iOSKonf and the organizers for providing me with this opportunity, and I look forward to further enhancing my app’s capabilities based on the valuable feedback I received.

Stay tuned for more updates and exciting developments in the world of EV charging and route planning!

Download here: EV Charge Stations Map

Here is the demo video of the EV Charger Finder App on VisionPro:

Photo by Art Wall - Kittenprint on Unsplash

When users uninstall your app, all their data stored in UserDefaults is lost forever. For a walking app like Walk Mate, this means losing:

- Years of walking statistics

- Favorite routes they’ve curated

- Milestones and achievements unlocked

- Personal preferences and settings

This was unacceptable. I needed a solution that would persist user data even after app uninstallation, while seamlessly syncing across all their devices.

The Solution: A Hybrid iCloud Approach

After evaluating several options (SQLiteData with CloudKit, Core Data with CloudKit, and direct CloudKit), I settled on a hybrid approach that balances simplicity, reliability, and performance:

1. iCloud Key-Value Store (KVS) for small, frequently accessed data (milestones, medal counts, stats)

2. File-based iCloud Storage for larger, structured data (routes, favorites, avoided segments)

This approach gives us:

✅ Automatic iCloud sync across devices

✅ Data persistence even after app uninstallation

✅ Simple, straightforward API

✅ No complex database migrations

✅ Built-in conflict resolution

Architecture Overview

iCloud Key-Value Store Wrapper

For small data like milestone progress and medal counts, I created a wrapper around NSUbiquitousKeyValueStore:

class iCloudKeyValueStore {
    static let shared = iCloudKeyValueStore()
    
    private let store = NSUbiquitousKeyValueStore.default
    private let migrationKeyPrefix = "iCloudMigration_"
    
    private init() {
        // Listen for iCloud sync notifications
        NotificationCenter.default.addObserver(
            self,
            selector: #selector(handleiCloudSync),
            name: NSUbiquitousKeyValueStore.didChangeExternallyNotification,
            object: store
        )
    }
    
    /// Migrates a key from UserDefaults to iCloud KVS if not already migrated
    func migrateIfNeeded(key: String, from userDefaults: UserDefaults = .standard) -> Bool {
        let migrationKey = migrationKeyPrefix + key
        
        // Check if already migrated
        if store.bool(forKey: migrationKey) {
            return false
        }
        
        // Check if data exists in UserDefaults
        guard let value = userDefaults.object(forKey: key) else {
            store.set(true, forKey: migrationKey)
            store.synchronize()
            return false
        }
        
        // Migrate the value
        store.set(value, forKey: key)
        store.set(true, forKey: migrationKey)
        store.synchronize()
        
        AppLogger.info("Migrated key '\(key)' from UserDefaults to iCloud KVS")
        return true
    }
    
    // Convenience methods for common types
    func set(_ value: Int, forKey key: String) {
        store.set(Int64(value), forKey: key)
        store.synchronize()
    }
    
    func integer(forKey key: String) -> Int {
        return Int(store.longLong(forKey: key))
    }
    
    // ... similar methods for String, Double, Date, [String], etc.
}

Key Features:

- Automatic directory creation

- Handles files that aren’t downloaded yet

- One-time migration from UserDefaults

- Fallback support for offline scenarios

Implementation Example: Milestone Storage

Here’s how I migrated milestone data to use iCloud KVS:

class MilestoneStorage {
    private static let store = iCloudKeyValueStore.shared
    private static let milestonesKey = "milestones"
    private static let totalWalksKey = "totalWalks"
    private static let totalDistanceKey = "totalDistanceWalked"
    /// Migrates all milestone data from UserDefaults to iCloud KVS
    static func migrateFromUserDefaults() {
        let userDefaults = UserDefaults.standard
        _ = store.migrateIfNeeded(key: milestonesKey, from: userDefaults)
        _ = store.migrateIfNeeded(key: totalWalksKey, from: userDefaults)
        _ = store.migrateIfNeeded(key: totalDistanceKey, from: userDefaults)
    }
    static func saveMilestones(_ milestones: [Milestone]) {
        do {
            let data = try JSONEncoder().encode(milestones)
            store.set(data, forKey: milestonesKey)
        } catch {
            AppLogger.error("Failed to save milestones", error: error)
        }
    }
    static func loadMilestones() -> [Milestone] {
        guard let data = store.data(forKey: milestonesKey) else {
            return initializeDefaultMilestones()
        }
        do {
            return try JSONDecoder().decode([Milestone].self, from: data)
        } catch {
            AppLogger.error("Failed to load milestones", error: error)
            return initializeDefaultMilestones()
        }
    }
    static func incrementTotalWalks() {
        let current = store.integer(forKey: totalWalksKey)
        store.set(current + 1, forKey: totalWalksKey)
    }
}

Implementation Example: Route Storage

For routes, I use file-based storage:

class RouteStorage {
    private static let fileStorage = iCloudFileStorage.shared
    private static let routesKey = "routes"
    private static let fileName = "routes.json"
    /// Migrates routes from UserDefaults to iCloud file
    static func migrateFromUserDefaults() {
        _ = fileStorage.migrateArrayIfNeeded(
            Route.self,
            from: routesKey,
            to: fileName
        )
    }
    static func saveRoutes(_ routes: [Route]) {
        do {
            try fileStorage.save(routes, to: fileName)
        } catch {
            AppLogger.error("Failed to save routes to iCloud", error: error)
            // Fallback to UserDefaults if iCloud is unavailable
            do {
                let data = try JSONEncoder().encode(routes)
                UserDefaults.standard.set(data, forKey: routesKey)
            } catch {
                AppLogger.error("Failed to save routes to UserDefaults fallback", error: error)
            }
        }
    }
    static func loadRoutes() -> [Route] {
        // Try loading from iCloud first
        let routes = fileStorage.loadArray(Route.self, from: fileName)
        if !routes.isEmpty {
            return routes
        }
        // Fallback to UserDefaults if iCloud file doesn't exist
        guard let data = UserDefaults.standard.data(forKey: routesKey) else {
            return []
        }
        do {
            return try JSONDecoder().decode([Route].self, from: data)
        } catch {
            AppLogger.error("Failed to load routes from UserDefaults fallback", error: error)
            return []
        }
    }
}

App Launch Integration

I trigger migrations once on app launch:

@main
struct WalkMateApp: App {
    init() {
        MilestoneStorage.migrateFromUserDefaults()
        MedalStorage.migrateFromUserDefaults()
        RouteStorage.migrateFromUserDefaults()
        FavoriteRouteStorage.migrateFromUserDefaults()
        AvoidedRouteManager.migrateFromUserDefaults()
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Key Lessons Learned

1. Migration Tracking is Critical

Always track which keys have been migrated to prevent duplicate migrations. I use a simple boolean flag in iCloud KVS:

let migrationKey = "iCloudMigration_\(originalKey)"
if store.bool(forKey: migrationKey) {
    return false
}

2. Handle Offline Scenarios

iCloud might not always be available. Always provide a fallback to UserDefaults:

static func saveRoutes(_ routes: [Route]) {
    do {
        try fileStorage.save(routes, to: fileName)
    } catch {
        let data = try JSONEncoder().encode(routes)
        UserDefaults.standard.set(data, forKey: routesKey)
    }
}

3. Files May Not Be Downloaded Yet

When loading files from iCloud, they might exist in the cloud but not be downloaded locally yet. Always check the download status:

if let status = resourceValues.ubiquitousItemDownloadingStatus,
   status == .notDownloaded {
    try? fileManager.startDownloadingUbiquitousItem(at: fileURL)
    return nil
}

4. Use Atomic Writes

Always use .atomic option when writing files to prevent corruption:

try jsonData.write(to: fileURL, options: .atomic)

5. Synchronize After Writes

For iCloud KVS, always call synchronize() after writes to ensure data is synced:

func set(_ value: Int, forKey key: String) {
    store.set(Int64(value), forKey: key)
    store.synchronize() // Important!
}

Benefits of This Approach

1. Simple API: No complex database queries, just save/load methods

2. Automatic Sync: iCloud handles syncing automatically

3. Data Persistence: Data survives app uninstallation

4. Cross-Device: Works seamlessly across iPhone, iPad, and Mac

5. No Server Costs: Uses Apple’s free iCloud storage

6. Privacy: Data is encrypted and stored in user’s iCloud account

When to Use Each Approach

Use iCloud Key-Value Store for:

- Small data (< 1 MB total)

- Simple key-value pairs

- Frequently accessed data

- Settings and preferences

- Counters and statistics

Use File-Based Storage for:

- Larger data structures

- Complex objects and arrays

- Data that changes infrequently

- Files that users might want to access outside the app

Conclusion

Migrating from UserDefaults to iCloud storage doesn’t have to be complicated. By using a hybrid approach with iCloud Key-Value Store for small data and file-based storage for larger data, I achieved:

✅ Zero data loss on app uninstallation

✅ Seamless cross-device sync

✅ Simple, maintainable code

✅ Automatic migration from existing UserDefaults data

The implementation is straightforward, and the user experience is significantly improved. Users can now uninstall and reinstall the app without losing their progress, and their data automatically syncs across all their devices.

This migration was implemented for WalkMate, a daily route generator app that helps users discover new walking routes. The app uses The Composable Architecture (TCA) and SwiftUI, with data persistence handled through iCloud.

Resources:

• Apple’s iCloud Documentation

• NSUbiquitousKeyValueStore Reference

• FileManager iCloud Methods

Photo by Element5 Digital on Unsplash

When building Walk Mate, a daily route generator app that gamifies walking with medals and achievements, I faced a critical decision: build a custom leaderboard and achievements backend, or use Apple’s Game Center (GameKit)?

Many developers suggested building a custom solution for more control and flexibility. But I went with Game Center, and here’s why it was the right choice, plus a complete implementation guide with code examples.

Why Game Center?

• Native iOS Integration: Game Center is built into iOS. Users already have accounts, and the integration feels native to the platform.

• Zero Backend Maintenance: No servers to manage, no databases to maintain, no scaling concerns. Apple handles everything.

• Built-in Social Features: Friend lists, challenges, and multiplayer support come out of the box.

• User Trust: Users are already familiar with Game Center, and it’s a trusted Apple service.

• Cost-Effective: Free to use, with no infrastructure costs.

Sometimes the simplest solution is the best!

Architecture Overview

I created a centralized GameCenterManager class using Swift’s @Observablemacro (iOS 17+) to manage all Game Center interactions.

This singleton class handles:

• Authentication 🔑

• Leaderboard submissions and loading 👑

• Achievement unlocking 🔓

• Challenge management ⛓️‍💥

• Friend loading 👭

Let’s dive into the implementation 🤿

1. Setting Up Game Center Manager

First, let’s create the manager class:

import Foundation
import GameKit
import Observation
import OSLog

@MainActor
@Observable
class GameCenterManager {
    static let shared = GameCenterManager()
    
    var isAuthenticated = false
    var localPlayer: GKLocalPlayer?
    var authenticationError: Error?
    var pendingChallenges: [GKChallenge] = []
    
    private let leaderboardID = "walkmate_total_medals"
    
    private init() {
        authenticatePlayer()
    }
}

The @Observable macro makes this class automatically observable, perfect for SwiftUI views that need to react to authentication state changes.

2. Authentication

Game Center authentication is straightforward. The system handles the UI, and we just need to set up the authentication handler:

func authenticatePlayer() {
    localPlayer = GKLocalPlayer.local
    
    localPlayer?.authenticateHandler = { [weak self] viewController, error in
        guard let self = self else { return }
        
        if let viewController = viewController {
            // Present authentication view controller
            if let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene,
               let rootViewController = windowScene.windows.first?.rootViewController {
                rootViewController.present(viewController, animated: true)
            }
            return
        }
        
        if let error = error {
            self.authenticationError = error
            self.isAuthenticated = false
            return
        }
        
        if self.localPlayer?.isAuthenticated == true {
            self.isAuthenticated = true
            // Sync existing data after authentication
            Task {
                await self.syncAllData()
                await self.loadChallenges()
            }
        }
    }
}

The authentication handler is called automatically by the system. If a view controller is provided, we present it. If there’s an error, we handle it. If authentication succeeds, we sync our app’s data to Game Center.

3. Leaderboards

Submitting Scores:

Submitting scores to a leaderboard is simple with the modern async/await API:

func submitMedalsToLeaderboard(_ medalCount: Int) async {
    guard isAuthenticated, let localPlayer = localPlayer else {
        return
    }
    
    do {
        try await GKLeaderboard.submitScore(
            medalCount,
            context: 0,
            player: localPlayer,
            leaderboardIDs: [leaderboardID]
        )
    } catch {
        AppLogger.error("Failed to submit score", error: error)
    }
}

Loading Leaderboard Entries:

Loading leaderboard entries requires two steps: first load the leaderboard object, then load its entries:

func loadLeaderboard(limit: Int = 100) async throws -> [GKLeaderboard.Entry] {
    guard isAuthenticated else {
        throw GameCenterError.notAuthenticated
    }
    
    // Load the leaderboard object
    let leaderboards = try await GKLeaderboard.loadLeaderboards(IDs: [leaderboardID])
    guard let leaderboard = leaderboards.first else {
        throw GameCenterError.leaderboardNotFound
    }
    
    // Load entries
    let result = try await leaderboard.loadEntries(
        for: .global,
        timeScope: .allTime,
        range: NSRange(location: 1, length: limit)
    )
    
    return result.1 // Returns the entries array
}

Displaying in SwiftUI:

Here’s how we display the leaderboard in a SwiftUI view:

struct LeaderboardView: View {
    @State private var leaderboardEntries: [GKLeaderboard.Entry] = []
    @State private var isLoading = false

    private let gameCenterManager = GameCenterManager.shared    

    var body: some View {
        ScrollView {
            if isLoading {
                ProgressView()
            } else {
                ForEach(leaderboardEntries, id: \.player.gamePlayerID) { entry in
                    LeaderboardRowView(entry: entry)
                }
            }
        }
        .task {
            await loadLeaderboard()
        }
    }
    
    private func loadLeaderboard() async {
        isLoading = true
        do {
            leaderboardEntries = try await gameCenterManager.loadLeaderboard()
        } catch {}
        isLoading = false
    }
}

4. Achievements

Unlocking Achievements:

When a player reaches a milestone, we unlock the corresponding achievement:

func unlockAchievement(for milestoneType: MilestoneType) async {
    guard isAuthenticated else { return }
    
    guard let achievementID = achievementIDs[milestoneType] else {
        return
    }
    
    do {
        let achievement = GKAchievement(identifier: achievementID)
        achievement.percentComplete = 100.0
        achievement.showsCompletionBanner = true
        
        try await GKAchievement.report([achievement])
    } catch {
        AppLogger.error("Failed to unlock achievement", error: error)
    }
}

Incremental Achievements:

For achievements that track progress (like “Walk 100km total”), we can update progress incrementally:

func updateAchievementProgress(for milestoneType: MilestoneType, progress: Double) async {
    guard isAuthenticated else { return }
    
    guard let achievementID = achievementIDs[milestoneType] else {
        return
    }
    
    // Check if already completed
    let achievements = try await GKAchievement.loadAchievements()
    if let existingAchievement = achievements.first(where: { $0.identifier == achievementID }),
       existingAchievement.percentComplete >= 100.0 {
        return
    }
    
    let achievement = GKAchievement(identifier: achievementID)
    achievement.percentComplete = min(100.0, progress)
    achievement.showsCompletionBanner = progress >= 100.0
    
    try await GKAchievement.report([achievement])
}

5. Challenges (The Tricky Part)

Game Center’s challenge feature is powerful but has a deprecated UI. The `challengeComposeController` method presents an outdated interface that doesn’t match modern iOS design.

The Problem:

The deprecated `challengeComposeController` method shows an old, ugly UI that doesn’t fit modern apps.

The Solution (Custom SwiftUI UI):

I built a custom SwiftUI interface for challenge composition, then use the deprecated API internally with preselected friends:

struct ChallengeComposeView: View {
    let friends: [GKPlayer]
    let defaultMessage: String
    let onSend: ([GKPlayer], String) -> Void
    let onCancel: () -> Void
    
    @State private var selectedFriendIDs: Set<String> = []
    @State private var message: String
    @State private var searchText = ""
    
    var body: some View {
        NavigationStack {
            VStack(spacing: AppConstants.UI.defaultRadius) {
                // Message Section
                VStack(alignment: .leading, spacing: AppConstants.UI.standardSpacing) {
                    Text(String(localized: "Challenge Message"))
                        .heading3()
                    
                    TextEditor(text: $message)
                        .frame(minHeight: AppConstants.minHeight)
                        .padding(AppConstants.UI.smallSpacing)
                        .background(Color(.secondarySystemGroupedBackground))
                        .clipShape(.rect(cornerRadius: AppConstants.UI.standardRadius))
                    
                    Text(String(localized: "\(message.count) characters"))
                        .caption()
                }
                .padding()
                
                Divider()
                
                // Friends Selection Section
                VStack(alignment: .leading, spacing: AppConstants.UI.standardSpacing) {
                    Text(String(localized: "Select Friends"))
                        .heading3()
                    
                    // Search Bar
                    HStack {
                        Image(systemName: UIConstants.SystemImages.magnifyingGlass)
                        TextField(String(localized: "Search friends", text: $searchText))
                    }
                    .padding(12)
                    .background(Color(.secondarySystemGroupedBackground))
                    .clipShape(.rect(cornerRadius: AppConstants.UI.standardRadius))
                    
                    // Friends List
                    ScrollView {
                        LazyVStack(spacing: 8) {
                            ForEach(filteredFriends, id: \.gamePlayerID) { friend in
                                FriendSelectionRow(
                                    friend: friend,
                                    isSelected: selectedFriendIDs.contains(friend.gamePlayerID),
                                    onToggle: {
                                        if selectedFriendIDs.contains(friend.gamePlayerID) {
                                            selectedFriendIDs.remove(friend.gamePlayerID)
                                        } else {
                                            selectedFriendIDs.insert(friend.gamePlayerID)
                                        }
                                    }
                                )
                            }
                        }
                    }
                }
                .padding()
            }
            .navigationTitle("Challenge Friends")
            .toolbar {
                ToolbarItem(placement: .topBarLeading) {
                    Button("Cancel") { onCancel() }
                }
                ToolbarItem(placement: .topBarTrailing) {
                    Button("Send") {
                        let selectedFriends = friends.filter { 
                            selectedFriendIDs.contains($0.gamePlayerID) 
                        }
                        onSend(selectedFriends, message)
                    }
                    .disabled(selectedFriendIDs.isEmpty)
                }
            }
        }
    }
}

Sending Challenges:

The manager method uses the deprecated API internally but with preselected friends, minimizing exposure to the old UI:

func sendScoreChallenge(
    score: Int, 
    message: String, 
    players: [GKPlayer],
    completion: @escaping (Bool, [GKPlayer]?) -> Void
) async {
    guard isAuthenticated else {
        completion(false, nil)
        return
    }
    
    // Get leaderboard entry
    let leaderboards = try await GKLeaderboard.loadLeaderboards(IDs: [leaderboardID])
    guard let leaderboard = leaderboards.first else {
        completion(false, nil)
        return
    }
    
    let result = try await leaderboard.loadEntries(
        for: .global,
        timeScope: .allTime,
        range: NSRange(location: 1, length: 1)
    )
    
    guard let entry = result.0 else {
        completion(false, nil)
        return
    }
    
    // Use deprecated method but with preselected players
    let controller = entry.challengeComposeController(
        withMessage: message,
        players: players, // Pre-selected from our custom UI
        completion: { viewController, didIssueChallenge, playersSentChallenge in
            viewController.dismiss(animated: true)
            completion(didIssueChallenge, playersSentChallenge)
        }
    )
    
    // Present the controller
    if let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene,
       let rootViewController = windowScene.windows.first?.rootViewController {
        var topController = rootViewController
        while let presented = topController.presentedViewController {
            topController = presented
        }
        topController.present(controller, animated: true)
    }
}

This approach gives users a modern UI for friend selection and message composition, while still using Game Center’s API for the actual challenge sending.

6. Loading and Managing Challenges

Players can receive challenges from friends. Here’s how to load and display them:

func loadChallenges() async -> Error? {
    guard isAuthenticated else { return nil }
    
    do {
        let challenges = try await withCheckedThrowingContinuation { 
            (continuation: CheckedContinuation<[GKChallenge], Error>) in
            GKChallenge.loadReceivedChallenges { challenges, error in
                if let error = error {
                    continuation.resume(throwing: error)
                } else {
                    continuation.resume(returning: challenges ?? [])
                }
            }
        }
        
        await MainActor.run {
            self.pendingChallenges = challenges
        }
        
        return nil
    } catch {
        return error
    }
}

Challenges are automatically accepted when the player beats the score or achievement. There’s no explicit accept method… Game Center handles it automatically!

7. Data Synchronization

When a user authenticates, we sync their existing app data to Game Center:

func syncAllData() async {
    guard isAuthenticated else { return }
    
    // Sync total medals to leaderboard
    let totalMedals = MedalStorage.getTotalMedalsCollected()
    await submitMedalsToLeaderboard(totalMedals)
    
    // Sync unlocked milestones as achievements
    let milestones = MilestoneStorage.loadMilestones()
    for milestone in milestones where milestone.unlocked {
        await unlockAchievement(for: milestone.type)
    }
}

This ensures that existing players don’t lose their progress when they first sign in to Game Center.

8. Best Practices and Tips

Error Handling:

Game Center can return various error codes. Some are gentle (like “no challenges available”), so handle them gracefully:

let nsError = error as NSError
if nsError.domain == "GKErrorDomain" {
    switch nsError.code {
    case 2, 6, 15, 38:
        // Gentle errors - treat as "no data available"
        return []
    default:
        throw error
    }
}

Testing:

• Use sandbox Game Center accounts for testing

• Challenges require the app to be approved in App Store Connect

• Test with multiple accounts to verify friend functionality

App Store Connect Setup:

Before your app goes live, you need to:

1. Create leaderboards in App Store Connect

2. Create achievements in App Store Connect

3. Submit your app version with Game Center items

4. Wait for approval (challenges become available after approval)

Privacy

Game Center requires a privacy description in your `Info.plist`:

<key>NSGKFriendListUsageDescription</key>
<string>Walk Mate needs access to your Game Center friends list to allow you to challenge friends and compete together.</string>

Conclusion

Game Center provided everything Walk Mate needed for social features without the complexity of a custom backend. The implementation was straightforward, and users get a native iOS experience.

The only challenge was the deprecated challenge UI, which I solved with a custom SwiftUI interface. This gives us the best of both worlds: modern design and Game Center’s robust infrastructure.

If you’re building an iOS app with social gaming features, give Game Center a serious look. It might be the simplest solution for your needs too.

Walk Mate is available on the App Store.

Check it out at: (https://walk-mate.app/apps/walkmate.html)

What is EDCarousel?

EDCarousel is a lightweight Swift library that gives you a carousel-style UICollectionView layout with overlapping items and smooth scaling animations. The center item appears at full scale, while side items shrink, fade, and shift slightly giving you that polished carousel look you see in many popular apps.

It’s built on top of UICollectionViewFlowLayout, so it works with the UIKit patterns you already know. No need to learn a new framework.

Here’s what it looks like in action:

Features

• Smooth scale, alpha, and shift animations while scrolling

• Two spacing modes: fixed spacing or overlapping items

• Custom page control with image-based indicators

• Type-safe UICollectionView cell registration and dequeuing

• Supports both Swift Package Manager and CocoaPods

• Works with iOS 14.0+ and Swift 5.9+

Installation

Swift Package Manager

In Xcode, go to File → Add Package Dependencies and enter:

https://github.com/emrdgrmnci/EDCarousel.git

Or add it directly to your Package.swift:

dependencies: [
    .package(url: "https://github.com/emrdgrmnci/EDCarousel.git", from: "1.0.0")
]

CocoaPods

Add this to your Podfile:

pod 'EDCarousel'

Then run:

pod install

How to Use It

Step 1: Set Up the Carousel Layout

You can set the layout either from Interface Builder or from code. I’ll show the code approach here since it’s more clear:

import EDCarousel

let layout = CarouselFlowLayout()
layout.sideItemScale = 0.8
layout.sideItemAlpha = 0.8
layout.sideItemShift = 0.8
layout.spacingMode = .overlap(visibleOffset: 30)
layout.scrollDirection = .horizontal
layout.itemSize = CGSize(width: 250, height: 350)

let collectionView = UICollectionView(frame: .zero, collectionViewLayout: layout)

That’s it. You now have a carousel with overlapping items that scale down as they move away from the center.

Let me explain what each property does:

• sideItemScale — How much the side items shrink. 0.8 means they’re 80% of the center item’s size.

• sideItemAlpha — The opacity of side items. Lower values make them more transparent.

• sideItemShift — How much side items shift vertically (or horizontally, depending on scroll direction).

• spacingMode — This is the interesting one. You have two options:

• .fixed(spacing: 10) — Items have a fixed gap between them.

• .overlap(visibleOffset: 30) — Items overlap each other. The visibleOffset controls how much of the side items peek out.

Step 2: Register and Dequeue Cells

EDCarousel includes type-safe extensions for UICollectionView, so you don’t have to deal with string-based reuse identifiers:

// Register
collectionView.register(MyCell.self)

// Or register from a nib file
collectionView.registerNib(MyNibCell.self)

// Dequeue
if let cell = collectionView.dequeue(MyCell.self, for: indexPath) {
    // Configure your cell
}

Clean, simple, and no more typos in reuse identifier strings.

Step 3: Add a Custom Page Control

EDCarousel comes with CustomPageControl, a UIPageControl subclass that lets you use custom images for the dots:

let pageControl = CustomPageControl()
pageControl.numberOfPages = 5
pageControl.currentPageImage = UIImage(systemName: "circle.fill")
pageControl.otherPagesImage = UIImage(systemName: "circle")

The dots update automatically when you change currentPage or numberOfPages. No extra calls needed.

Step 4: Track the Current Page While Scrolling

To keep the page control in sync with scrolling, use the scrollViewWillEndDragging delegate method:

func scrollViewWillEndDragging(
    _: UIScrollView,
    withVelocity _: CGPoint,
    targetContentOffset: UnsafeMutablePointer<CGPoint>
) {
    let targetOffset = targetContentOffset.pointee.x
    let width = (collectionView.frame.size.width - padding) / 1.21
    let rounded = Double((images.count / 2)) * abs(targetOffset / width)
    let scale = round(rounded)
    pageControl.currentPage = Int(scale)
}

Step 5: Navigate Programmatically

You can add previous/next buttons to navigate between pages:

// Go to previous page
let prevIndex = max(pageControl.currentPage - 1, 0)
let indexPath = IndexPath(item: prevIndex, section: 0)
pageControl.currentPage = prevIndex
collectionView.isPagingEnabled = false
collectionView.scrollToItem(at: indexPath, at: .centeredHorizontally, animated: true)

// Go to next page
let nextIndex = min(pageControl.currentPage + 1, images.count - 1)
let indexPath = IndexPath(item: nextIndex, section: 0)
pageControl.currentPage = nextIndex
collectionView.isPagingEnabled = false
collectionView.scrollToItem(at: indexPath, at: .centeredHorizontally, animated: true)

Important: Make sure isPagingEnabled is set to false. The carousel layout handles the snapping behavior on its own. If paging is enabled, it conflicts with the custom layout.

How It Works Under the Hood

If you’re curious about the internals, here’s a quick overview. CarouselFlowLayout overrides a few key methods from UICollectionViewFlowLayout:

1. prepare(): Checks if the layout state (size + scroll direction) has changed. If it has, it recalculates insets and spacing.

2. layoutAttributesForElements(in:) Returns the layout attributes for all visible items, with custom transformations applied.

3. transformLayoutAttributes(_:) This is where the magic happens. For each cell, it calculates the distance from the collection view’s center and uses that to determine the scale, alpha, shift, and z-index. Items closer to the center get a higher scale and opacity.

4. targetContentOffset(forProposedContentOffset:withScrollingVelocity:) Handles the snapping. When the user stops scrolling, it finds the nearest item and adjusts the content offset to center it.

The result is a smooth, performant carousel that works with standard UIKit patterns.

A Full Example

Here’s a data source setup from the example project that shows how everything comes together:

import EDCarousel

final class ExampleCollectionDataSource: NSObject, UICollectionViewDataSource {
    private var items = [Onboarding]()
    private weak var collectionView: UICollectionView?

    init(collectionView: UICollectionView) {
        self.collectionView = collectionView
        super.init()
        setupLayout(collectionView: collectionView)
    }

    private func setupLayout(collectionView: UICollectionView) {
        guard let layout = collectionView.collectionViewLayout as? CarouselFlowLayout else { return }
        let padding = 10.0
        layout.itemSize = CGSize(
            width: (collectionView.frame.size.width - padding) / 1.21,
            height: (collectionView.frame.size.width - padding) / 0.76
        )
        layout.spacingMode = .overlap(visibleOffset: 200)
        layout.sideItemScale = 0.8
        layout.scrollDirection = .horizontal
        collectionView.registerNib(ExampleCollectionViewCell.self)
        collectionView.isPagingEnabled = false
    }

    func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
        guard let cell = collectionView.dequeue(ExampleCollectionViewCell.self, for: indexPath) else {
            fatalError("Unable to dequeue cell")
        }
        let item = items[indexPath.row]
        cell.set(item: item)
        return cell
    }

    func collectionView(_: UICollectionView, numberOfItemsInSection _: Int) -> Int {
        return items.count
    }
}

You can also check out the full example project on GitHub: EDCarousel Example

Why I Built This

Building carousels in iOS with UICollectionView always felt like reinventing the wheel. Every time I needed one, I ended up writing the same flow layout code, the same snapping logic, the same scaling math. EDCarousel packages all of that into a reusable library that you can drop into any project.

Get Started

• GitHub: https://github.com/emrdgrmnci/EDCarousel

• Requirements: iOS 14.0+, Swift 5.9+, Xcode 15.0+

If you find EDCarousel useful, give it a star on GitHub. And if you run into any issues or have ideas for improvements, feel free to open an issue. Contributions are always welcome.

Goals

• Keep the route in view during a walk (Live Activity + Dynamic Island).

• Keep motivation visible throughout the day (home screen widgets).

• Make the UX “summary-first”: streak, medals, and distance.

Live Activity Architecture

At the core is a compact set of ActivityAttributes that capture just the data I want to present: distances, medals, and unit preferences. I use a @MainActor manager to create, update, and end activities keeping activity state in a single place and avoiding multiple active routes.

import ActivityKit

struct WalkActivityAttributes: ActivityAttributes {
    struct ContentState: Codable, Hashable {
        var distanceWalked: Double
        var totalDistance: Double
        var medalsCollected: Int
        var medalsTotal: Int
        var distanceUnitRawValue: String
    }

    var routeId: String
    var routeName: String
}

The manager handles:

• Route switching (end previous activity when the route changes).

• Update vs. create logic (update if already active, otherwise request a new activity).

• End and cleanup in a single function.

@MainActor
final class LiveActivityManager {
    static let shared = LiveActivityManager()

    private var activity: Activity<WalkActivityAttributes>?
    private var currentRouteId: String?

    func startActivity(route: Route, distanceWalked: Double, distanceUnit: DistanceUnit) async {
        guard #available(iOS 16.1, *) else { return }

        let routeId = route.id.uuidString
        if let currentRouteId, currentRouteId != routeId {
            await endActivity(dismissalPolicy: .immediate)
        }

        let state = WalkActivityAttributes.ContentState(
            distanceWalked: distanceWalked,
            totalDistance: route.distance,
            medalsCollected: route.medals.filter(\.isCollected).count,
            medalsTotal: route.medals.count,
            distanceUnitRawValue: distanceUnit.rawValue
        )

        if let activity {
            let content = ActivityContent(state: state, staleDate: nil)
            await activity.update(content)
            return
        }

        let attributes = WalkActivityAttributes(
            routeId: routeId,
            routeName: AppConstants.App.name
        )

        do {
            let content = ActivityContent(state: state, staleDate: nil)
            activity = try Activity.request(
                attributes: attributes,
                content: content,
                pushType: nil
            )
            currentRouteId = routeId
        } catch {
            activity = nil
            currentRouteId = nil
        }
    }
}

Lock Screen + Dynamic Island UI

The Live Activity view emphasizes “walked vs total” and medal progress. The Dynamic Island gives a compact icon + stat treatment, then expands into progress.

@available(iOS 16.1, *)
struct WalkMateLiveActivity: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: WalkActivityAttributes.self) { context in
            WalkMateLiveActivityLockScreenView(context: context)
        } dynamicIsland: { context in
            DynamicIsland {
                DynamicIslandExpandedRegion(.leading) {
                    HStack(spacing: 8) {
                        Image(systemName: "figure.walk")
                            .font(.title2)
                            .foregroundStyle(.white)
                            .frame(width: 32, height: 32)
                            .background(.blue, in: .rect(cornerRadius: 8))
                        VStack(alignment: .leading, spacing: 2) {
                            Text("\(context.state.medalsCollected)/\(context.state.medalsTotal)")
                                .font(.headline)
                                .bold()
                            Text(String(localized: "Medals"))
                                .font(.caption2)
                                .foregroundStyle(.secondary)
                        }
                    }
                    .padding(.top, 4)
                    .padding(.bottom, 4)
                    .padding(.leading, 4)
                }
                // ... trailing + bottom progress
            } compactLeading: {
                Image(systemName: "figure.walk")
                    .foregroundStyle(.white)
                    .frame(width: 22, height: 22)
                    .background(.blue, in: .rect(cornerRadius: 6))
            } compactTrailing: {
                Text(formattedDistance(context.state.totalDistance, unitRawValue: context.state.distanceUnitRawValue))
                    .font(.caption2)
                    .bold()
            } minimal: {
                Image(systemName: "figure.walk")
                    .foregroundStyle(.white)
                    .frame(width: 18, height: 18)
                    .background(.blue, in: .rect(cornerRadius: 5))
            }
        }
    }
}

Widgets: Two “at a glance” surfaces

I shipped two widgets with a shared provider:

• Progress Snapshot: streak + distance + next milestone.

• Motivation Highlights: achievements + medals + gentle nudge.

@main
struct WalkMateWidgetsBundle: WidgetBundle {
    var body: some Widget {
        ProgressSnapshotWidget()
        MotivationHighlightsWidget()
    }
}

The provider uses a simple timeline that refreshes hourly:

struct WalkMateWidgetProvider: TimelineProvider {
    func placeholder(in context: Context) -> WalkMateWidgetEntry {
        WidgetStatsStore.placeholderEntry()
    }

    func getSnapshot(in context: Context, completion: @escaping (WalkMateWidgetEntry) -> Void) {
        completion(WidgetStatsStore.snapshotEntry())
    }

    func getTimeline(in context: Context, completion: @escaping (Timeline<WalkMateWidgetEntry>) -> Void) {
        let entry = WidgetStatsStore.snapshotEntry()
        let nextUpdate = Calendar.current.date(byAdding: .hour, value: 1, to: entry.date) ?? entry.date.addingTimeInterval(3600)
        completion(Timeline(entries: [entry], policy: .after(nextUpdate)))
    }
}

Shared storage: keep widgets simple

I store aggregate stats in NSUbiquitousKeyValueStore, which lets the widget fetch the latest totals without needing the app to be running.

static func snapshotEntry() -> WalkMateWidgetEntry {
    let store = NSUbiquitousKeyValueStore.default
    store.synchronize()

    let totalDistance = store.double(forKey: totalDistanceKey)
    let totalRoutes = Int(store.longLong(forKey: totalWalksKey))
    let longestStreak = Int(store.longLong(forKey: longestStreakKey))
    let currentStreak = Int(store.longLong(forKey: consecutiveDaysKey))
    let totalMedals = totalMedalsCollected(from: store)

    let milestones = loadMilestones(from: store)
    let achievementsUnlocked = milestones.filter { $0.unlocked }.count
    let achievementsTotal = milestones.count
    let nextMilestone = nextMilestoneProgress(from: milestones)
    let motivationText = motivationText(currentStreak: currentStreak, unlockedCount: achievementsUnlocked)

    return WalkMateWidgetEntry(
        date: Date(),
        totalMedals: totalMedals,
        totalDistanceMeters: totalDistance,
        totalRoutes: totalRoutes,
        currentStreak: currentStreak,
        longestStreak: longestStreak,
        achievementsUnlocked: achievementsUnlocked,
        achievementsTotal: achievementsTotal,
        nextMilestone: nextMilestone,
        motivationText: motivationText
    )
}

UX Decisions That Mattered

• Distance formatting is intentional: Live Activity view formats meters into km/mi (and uses unit saved in state), while widgets use lightweight ~km formatting to keep layout stable.

• Progress-driven copy: the motivation widget’s text changes based on streak or milestone unlocks.

private static func motivationText(currentStreak: Int, unlockedCount: Int) -> String {
    if currentStreak >= 7 {
        return String(localized: "Week streak. Keep going.")
    }
    if currentStreak >= 1 {
        return String(localized: "Day \(currentStreak) streak. Keep walking.")
    }
    if unlockedCount > 0 {
        return String(localized: "New goals are within reach.")
    }
    return String(localized: "Start your first walk.")
}

Lessons Learned (the honest list)

• Activity lifetime is tricky: always clean up old activities when a new route starts, or you’ll end up with stale islands. I explicitly end old activities when the route ID changes.

• Timeline updates are conservative: hourly refresh is stable and safe for battery. More frequent updates require a good reason.

• Different formatting per surface: Live Activity can be more precise; widgets should be glanceable.

• Context limits are real: keep ActivityKit state small and only include what you need to render.

• Localization should be baked in: I use String(localized:) for widget copy to avoid English-only UI.

What I’d Do Next

• Add a widget configuration intent to let users choose metric vs. imperial.

• Add an “in-walk” widget that surfaces current route only when active.

• Explore activity relevance and alerting to make “in walk” more visible.

This wasn’t just a storage swap. It was about making the app more resilient, queryable, and future-proof without breaking users’ existing data.

Why Migrate at All?

For a while, persistence looked like this:

• state spread across UserDefaults keys

• arrays in iCloud Drive JSON files (routes.json, favoriteRoutes.json, avoidedSegments.json)

That works early on, but eventually you hit limits:

• hard to evolve schema safely

• hard to merge data from multiple sources/devices

• hard to reason about partial corruption or shape drift

• hard to support structured CloudKit sync semantics

So I moved to normalized tables with explicit migrations, and kept backward compatibility during rollout.

The New Storage Core

The app now centralizes persistence in SQLitePersistenceStore, which owns database setup, migration, CRUD, and cross-source merge behavior:

func rebuildFromLegacySourcesIfNeeded() {
    guard !UserDefaults.standard.bool(forKey: Constants.migrationKey) else { return }
    ...
    writeFullState(state)
    UserDefaults.standard.set(true, forKey: Constants.migrationKey)
}

At app startup, database + sync dependencies are prepared first, then migration runs once:

let database = SQLitePersistenceStore.makeDatabase()
do {
    let syncEngine = try WalkMateSyncEngineFactory.make(for: database)
    prepareDependencies {
        $0.defaultDatabase = database
        $0.defaultSyncEngine = syncEngine
    }
} catch { ... }

SQLitePersistenceStore.shared.configure(database: database)
SQLitePersistenceStore.shared.rebuildFromLegacySourcesIfNeeded()

Schema Design: What’s Normalized vs What Stays as Payload

I used @Table models for stable entities:

• wm_user_stats

• wm_milestones

• wm_routes

• wm_favorite_routes

• wm_avoided_segments

• wm_neighborhoods

@Table("wm_user_stats")
nonisolated struct WalkMateUserStatsRow: Hashable {
    @Column(primaryKey: true)
    var id: String
    var totalMedalsCollected: Int = 0
    ...
}

A deliberate hybrid choice: complex domain objects like routes/favorites are still stored as encoded payload blobs (Data) inside normalized row identities. That keeps schema churn lower while still enabling proper table-level sync/versioning.

Migration Strategy in Practice

I split migration into two layers:

1. GRDB schema migrations (versioned)

2. One-shot app-layer import from legacy sources

v1: Create new tables + import legacy blob if present

static func register(migrator: inout DatabaseMigrator) {
    migrator.registerMigration("walkmate_wm_tables_v1") { db in
        ...
        try migrateLegacyAppStorageBlobIfPresent(db: db)
        try ensureDefaultUserStatsRow(db: db)
    }
}

v2: CloudKit compatibility cleanup

CloudKit sync has stricter assumptions. In my case I had to:

• remove non-primary UNIQUE constraints that SyncEngine dislikes

• migrate tables to UUID primary keys for distributed row identity

migrator.registerMigration("walkmate_cloudkit_v2") { db in
    try migrateMilestonesDropMilestoneTypeUniqueIfNeeded(db)
    try migrateAvoidedSegmentsUUIDPrimaryKey(db)
    try migrateNeighborhoodsUUIDPrimaryKey(db)
}

This was one of the most important “learned the hard way” points: CloudKit-friendly schema rules should be baked in early :D

Data Rebuild: Merging Multiple Legacy Sources Safely

The app layer migration (rebuildFromLegacySourcesIfNeeded) reconstructs a canonical state by merging:

• existing table data

• iCloud key-value entries (stats/streak/etc.)

• iCloud JSON files (routes/favorites/avoided)

• UserDefaults fallback blobs

Merging is intentionally “max/union” oriented (keep higher counters, merge arrays by IDs, single neighborhoods), reducing risk of silent data loss from stale sources.

That design gives users a better chance of retaining progress even if one source is out of date.

Sync Integration with SQLiteData

The SyncEngine wiring is straightforward once schema is ready:

enum WalkMateSyncEngineFactory {
    static func make(for database: any DatabaseWriter) throws -> SyncEngine {
        try SyncEngine(
            for: database,
            privateTables: WalkMateUserStatsRow.self,
            WalkMateMilestoneRow.self,
            WalkMateRouteRow.self,
            ...
        )
    }
}

A nice side effect: sync concerns are isolated from UI and feature modules. Existing feature APIs (RouteStorage, FavoriteRouteStorage, MilestoneStorage) stayed mostly stable, while internals swapped to SQLite backed operations.

Operational Details That Matter

A few production-minded choices made this migration safer:

• One-time migration flag (sqliteDataMigration_v1_completed) prevents repeated destructive rebuilds.

• On-disk DB with in-memory fallback if file opening fails.

• Mirror writes to iCloud files for continuity.

• Sync status snapshot in settings for observability (iCloud availability, last sync date, debug counts).

• Widget snapshot refresh after mutations to keep widgets consistent.

What I’d Recommend If You’re Doing Similar

1. Model migration as identical steps, not one giant conversion.

2. Keep old read paths for one release while writing to new storage.

3. Use conservative merge rules (max, union, identical by stable ID).

4. If CloudKit is in scope, validate schema against sync constraints early.

5. Add lightweight in-app observability so you can debug real user devices.

Closing

This migration moved Walk Mate from fragile, fragmented persistence to a sync-capable SQLite backbone without forcing users to lose historical progress.

If you’re shipping an app that started with UserDefaults + JSON shortcuts, this is your sign: you can migrate safely, incrementally, and with far less risk than a hard cutover.