Coder Legion - Recent posts tagged ios

How to give your AI Agent access to a Real iPhone

Thu, 29 Oct 2026 16:16:58 +0000

For a long time, mobile automation has been much easier to demonstrate on Android than on iOS. Android has ADB, emulators, and relatively accessible automation tooling. iOS has a different set of constraints, especially when you want to interact with a physical device and the apps installed on it.

But what if you could give an AI agent access to your actual iPhone, describe a task in plain English, and let it carry out the steps?

That's what we've been working on at Mobilerun.

Why iPhone automation is difficult

AI agents have become good at reasoning, writing code, and interacting with websites. Mobile apps introduce another layer of complexity.

An agent might need to navigate multiple screens, locate a button, enter information, handle a dialog, and verify that an action actually succeeded.

On iOS, automation is harder because of Apple’s restrictions, connection issues, and the setup needed to control a real iPhone.

Traditional automation often relies on predefined scripts or app-specific integrations. These work well when the workflow is known in advance, but they can be restrictive when you want an agent to handle different tasks dynamically.

An AI agent that can interact with a phone's UI has another option: it can observe the screen, decide what to do next, and perform the necessary interactions.

Instead of building a separate integration for every task, you can describe the outcome you want and let the agent work through the interface.

From a prompt to a real iPhone

With Mobilerun Cloud, you can connect your own iPhone through a Mac or Linux or Linux and make it available for automation.

The workflow is straightforward:

Connect your iPhone to your Mac or Linux or Linux using a USB cable.
Follow the setup instructions to connect it to Mobilerun Cloud.
Open your connected device and give your agent a task.
Watch the agent interact with the phone.

Once connected, you can issue a command and let the agent navigate the UI, tap controls, type text, and move between screens.

You don't need to build a dedicated automation script for every prompt.

Setup takes under two minutes in the supported configuration. You'll need an iPhone running iOS 27 or later and a Mac or Linux.

Follow the iPhone connection guide to get started.

What can you automate?

The interesting part isn't simply getting an AI to tap a button. It's being able to describe a task and have the agent work through the steps on a real device.

Here are a few examples worth exploring.

1. Messaging workflows

You could ask an agent to open Messages, find a conversation, and draft or send a message.

For example:

Open Messages, find my conversation with Maa, and send her a message saying I'll call her this evening.

This is a simple example, but it demonstrates the core idea: the task is described in natural language, and the agent translates it into UI interactions.

Always review messages and confirm the intended recipient before allowing an agent to send anything important.

2. Navigating apps

An agent could be asked to open an app, find a particular section, search for information, or navigate through a multi-step workflow.

Rather than specifying every tap in advance, you describe what you want it to accomplish.

3. Repetitive mobile tasks

Many mobile workflows involve repeating the same sequence of actions: opening an app, finding a record, updating information, or navigating through several screens.

These are useful places to experiment with agent-driven automation, particularly when the process is tedious to perform manually.

The exact tasks an agent can complete will depend on the app, the UI, permissions, and the reliability of the underlying automation.

Why use a real iPhone instead of a simulator?

Simulators are valuable for development and testing. They provide a controlled environment where you can reproduce scenarios and inspect application behavior.

Physical devices matter when you need to work with the actual hardware and software environment.

A real iPhone gives you access to the device you already own, including its installed apps and existing setup, subject to the permissions and capabilities available to the automation system.

This is useful for developers experimenting with mobile agents, teams testing real-device workflows, and anyone exploring what AI can do beyond a browser.

It doesn't mean simulators are obsolete. Both approaches have their place, depending on what you're trying to build or test.

Try it yourself

If you have an iPhone and a Mac or Linux, you can connect your device to Mobilerun Cloud and start experimenting.

Connect your iPhone: Read the setup guide
Try Mobilerun Cloud: cloud.mobilerun.ai
Explore Mobilerun: mobilerun.ai
Inspect the benchmark: iOSWorld results

We're curious to see what developers build with this.

What would you want an AI agent to do on your iPhone that you can't easily automate today?

That's probably the most interesting question to explore next.

MarcX Studio

Tue, 27 Oct 2026 23:05:38 +0000

MarcX Studio is an independent studio making simple education and language apps for iPhone. None of the apps are AI products: each does one job clearly, most work without an account, and your data stays on your device unless you choose to back it up or share it.

Apps

RooCards: keep your loyalty cards ready on your iPhone.
Snap Spell: spelling practice from the word lists students bring home. Scan or paste a list and practise it.
NumListen: number listening practice for language learners.
成语拾光 (Idiom Shiguang): a Chinese idiom game.

The apps are free to download, with optional upgrades for people who want more. The studio site, https://www.marcx.app, is available in many languages, including English, Chinese, Japanese, Korean, Spanish, French and German.

Website: https://www.marcx.app

Building a Low-Latency Virtual Piano and Drum Kit on iOS with AVAudioEngine

Tue, 27 Oct 2026 12:40:37 +0000

Originally published at https://bestlatestapps.com/blog/building-a-low-latency-virtual-piano-and-drum-kit-on-ios-with-avaudioe/

Samplers for pitched instruments, a player-node pool for drums, a multi-touch keyboard that handles chords and glissandos, and note names for beginners

The test for a virtual instrument is brutal and immediate: tap a key, and the sound has to arrive with your finger, not after it. Play a chord and you expect three notes, not one. Drag your finger along the keyboard and you expect a glissando, not silence. Hit the snare four times quickly and you expect four hits, not one hit cut off three times.

My app Drums n Piano puts a piano, a drum kit and a xylophone on your phone. The listing promises an instrument that "sounds real, just like the original instrument!", and it's also meant for learning: it teaches beginners "the names & positions of notes on the piano".

This article covers how I'd build the audio and touch parts of an app like that on iOS. That means configuring the session for low latency, using AVAudioUnitSampler for pitched instruments, a pool of AVAudioPlayerNodes for one-shot drum samples, a custom multi-touch keyboard view, and labelling notes for learners. The app supports iOS 12 and later, so the touch layer is UIKit, and I'll explain why that's the right call even today. API names and availability are checked against Apple's documentation, and this is the approach I'd use rather than a tour of the app's source.

1. The three things a virtual instrument must get right

Latency. The gap between touch and sound. Part of it is the audio buffer, and part is your own code: loading a file on tap, or allocating while the user is playing.
Polyphony. Several sounds at once: chords on the piano, overlapping cymbal and kick, a fast roll on the snare.
Touch handling. Many fingers at once, sliding between keys, and no gesture delays.

None of these are hard individually. They get hard when the first prototype plays a sound file with AVAudioPlayer on each tap. That loads, decodes and allocates on the main thread, can't overlap itself, and has noticeably more delay than the engine-based approaches below.

2. Session setup for an instrument

import AVFoundation

enum InstrumentSession {
    static func activate() throws {
        let session = AVAudioSession.sharedInstance()
        // .playback: the instrument IS the app, so play even with the Silent switch on.
        // .mixWithOthers: let people play along with music from another app.
        try session.setCategory(.playback, mode: .default, options: [.mixWithOthers])
        try session.setPreferredIOBufferDuration(0.005)   // ask for ~5 ms; the system decides
        try session.setActive(true)
        print("IO buffer: \(session.ioBufferDuration * 1000) ms, rate: \(session.sampleRate) Hz")
    }
}

Two decisions here deserve a sentence each:

.playback vs .ambient. .ambient respects the Silent switch, which suits a game's background music. For an instrument, silence when the switch is on looks like a broken app, so I use .playback.
A small preferred buffer reduces output latency. It's a preference: read back ioBufferDuration to see what you actually got, and expect Bluetooth headphones to add delay you can't remove. Wired headphones or the built-in speaker are best for playing in time.

3. Pitched instruments: AVAudioUnitSampler

For piano and xylophone, you don't want one audio file per tap. You want a sampler: an instrument that receives MIDI-style "note on/off" messages and plays the right sample, pitch-shifting between recorded notes if needed. AVAudioUnitSampler (iOS 8+) is Apple's sampler, wrapped as an engine node.

import AVFoundation

final class PitchedInstrument {
    private let engine: AVAudioEngine
    private let sampler = AVAudioUnitSampler()

    init(engine: AVAudioEngine) {
        self.engine = engine
        engine.attach(sampler)
        engine.connect(sampler, to: engine.mainMixerNode, format: nil)
    }

    /// Load a SoundFont (.sf2) or DLS bank shipped in the bundle.
    func loadSoundBank(named name: String, program: UInt8 = 0) throws {
        guard let url = Bundle.main.url(forResource: name, withExtension: "sf2") else {
            throw CocoaError(.fileNoSuchFile)
        }
        try sampler.loadSoundBankInstrument(
            at: url, program: program,
            bankMSB: UInt8(kAUSampler_DefaultMelodicBankMSB),
            bankLSB: UInt8(kAUSampler_DefaultBankLSB))
    }

    /// Or: load individual samples (e.g. one recording every few semitones).
    func loadSamples(_ urls: [URL]) throws {
        try sampler.loadAudioFiles(at: urls)
    }

    func noteOn(_ midi: UInt8, velocity: UInt8 = 100) {
        sampler.startNote(midi, withVelocity: velocity, onChannel: 0)
    }

    func noteOff(_ midi: UInt8) {
        sampler.stopNote(midi, onChannel: 0)
    }
}

Why this is the right tool:

Polyphony is built in. Ten fingers, ten notes. The sampler manages voices for you.
Note-off is real. Releasing a key triggers the sample's release, as on a real piano, rather than a hard cut.
Loading happens once, at launch or when the user switches instrument, never on the tap.

Where do the sounds come from? Either a SoundFont you have the rights to ship, or your own recordings, with one sample every few semitones loaded via loadAudioFiles(at:). Sample quality is the single biggest factor in "sounds real", and it's a licensing question as much as a technical one: check the licence of any sound bank before you bundle it.

4. Drums: preloaded buffers and a player-node pool

Drums are different. There's no pitch, every hit is a one-shot, and the same pad is hit repeatedly and fast. You could map drums onto a sampler (General MIDI percussion is exactly that), but a simple, very controllable approach is:

Decode each drum sample into an AVAudioPCMBuffer once, at launch.
Keep a small pool of AVAudioPlayerNodes per pad.
On each hit, schedule the buffer on the next node in the pool, round-robin.

import AVFoundation

final class DrumKit {
    private let engine: AVAudioEngine
    private var buffers: [String: AVAudioPCMBuffer] = [:]
    private var pools: [String: [AVAudioPlayerNode]] = [:]
    private var nextIndex: [String: Int] = [:]
    private let voicesPerPad = 4     // how many overlapping hits per pad

    init(engine: AVAudioEngine) { self.engine = engine }

    /// Call once, before starting the engine.
    func load(pads: [String]) throws {
        for pad in pads {
            guard let url = Bundle.main.url(forResource: pad, withExtension: "caf") else {
                throw CocoaError(.fileNoSuchFile)
            }
            let file = try AVAudioFile(forReading: url)
            guard let buffer = AVAudioPCMBuffer(pcmFormat: file.processingFormat,
                                                frameCapacity: AVAudioFrameCount(file.length)) else {
                throw CocoaError(.fileReadCorruptFile)
            }
            try file.read(into: buffer)
            buffers[pad] = buffer

            pools[pad] = (0..<voicesPerPad).map { _ in
                let node = AVAudioPlayerNode()
                engine.attach(node)
                engine.connect(node, to: engine.mainMixerNode, format: buffer.format)
                return node
            }
            nextIndex[pad] = 0
        }
    }

    /// Call after engine.start().
    func startNodes() {
        pools.values.flatMap { $0 }.forEach { $0.play() }
    }

    func hit(_ pad: String, velocity: Float = 1.0) {
        guard let buffer = buffers[pad], let pool = pools[pad], let i = nextIndex[pad] else { return }
        let node = pool[i]
        nextIndex[pad] = (i + 1) % pool.count
        node.volume = velocity
        // .interrupts: if this voice is still ringing from 4 hits ago, restart it cleanly.
        node.scheduleBuffer(buffer, at: nil, options: .interrupts, completionHandler: nil)
    }
}

The whole setup:

let engine = AVAudioEngine()
let piano = PitchedInstrument(engine: engine)
let drums = DrumKit(engine: engine)

try InstrumentSession.activate()
try piano.loadSoundBank(named: "Piano")
try drums.load(pads: ["kick", "snare", "hihat-closed", "hihat-open", "crash", "tom-high", "tom-low"])
engine.prepare()
try engine.start()
drums.startNodes()

Why a pool? A single player node plays one schedule queue. Scheduling a new hit with .interrupts on a single node cuts the previous hit off, and that's audible on cymbals. With four voices per pad, four overlapping hits all ring naturally, and only the fifth recycles the oldest voice. Ship samples as uncompressed .caf or .wav so decoding at launch is quick and exact. They're short, so the size cost is small.

5. A multi-touch keyboard that feels like a keyboard

This is where many SwiftUI prototypes fall short. A Button per key fires on touch-up, which is far too late for an instrument. A DragGesture per key doesn't hand off to the next key when the finger slides. And coordinating several simultaneous fingers through SwiftUI gestures is awkward.

The direct approach is one UIKit view for the whole keyboard that tracks every UITouch itself:

import UIKit

final class KeyboardView: UIView {
    var firstMidi: UInt8 = 60           // C4
    var octaves = 2
    var onNoteOn: ((UInt8) -> Void)?
    var onNoteOff: ((UInt8) -> Void)?

    private var touchNotes: [ObjectIdentifier: UInt8] = [:]   // which finger holds which note

    override init(frame: CGRect) {
        super.init(frame: frame)
        isMultipleTouchEnabled = true      // essential: off by default
    }
    required init?(coder: NSCoder) { fatalError("init(coder:) is not supported") }

    // MARK: Touch tracking

    override func touchesBegan(_ touches: Set<UITouch>, with event: UIEvent?) {
        for t in touches { press(t) }
    }

    override func touchesMoved(_ touches: Set<UITouch>, with event: UIEvent?) {
        for t in touches {
            let id = ObjectIdentifier(t)
            let newNote = note(at: t.location(in: self))
            guard newNote != touchNotes[id] else { continue }    // still on the same key
            if let old = touchNotes[id] { onNoteOff?(old) }       // glissando: release old…
            touchNotes[id] = newNote
            if let n = newNote { onNoteOn?(n) }                   // …and press new
            setNeedsDisplay()
        }
    }

    override func touchesEnded(_ touches: Set<UITouch>, with event: UIEvent?) {
        for t in touches { release(t) }
    }

    override func touchesCancelled(_ touches: Set<UITouch>, with event: UIEvent?) {
        for t in touches { release(t) }     // never leave a note stuck on
    }

    private func press(_ t: UITouch) {
        guard let n = note(at: t.location(in: self)) else { return }
        touchNotes[ObjectIdentifier(t)] = n
        onNoteOn?(n)
        setNeedsDisplay()
    }

    private func release(_ t: UITouch) {
        if let n = touchNotes.removeValue(forKey: ObjectIdentifier(t)) { onNoteOff?(n) }
        setNeedsDisplay()
    }

    // MARK: Geometry

    private static let whiteOffsets: [UInt8] = [0, 2, 4, 5, 7, 9, 11]          // C D E F G A B
    private static let blackOffsets: [(after: Int, semitone: UInt8)] =
        [(0, 1), (1, 3), (3, 6), (4, 8), (5, 10)]                               // C# D# F# G# A#

    private var whiteKeyWidth: CGFloat { bounds.width / CGFloat(7 * octaves) }

    /// Black keys sit on top, so test them first.
    func note(at p: CGPoint) -> UInt8? {
        guard bounds.contains(p) else { return nil }
        let w = whiteKeyWidth
        if p.y < bounds.height * 0.6 {
            for octave in 0..<octaves {
                for (after, semitone) in Self.blackOffsets {
                    let x = CGFloat(octave * 7 + after + 1) * w - w * 0.3
                    if CGRect(x: x, y: 0, width: w * 0.6, height: bounds.height * 0.6).contains(p) {
                        return firstMidi + UInt8(octave * 12) + semitone
                    }
                }
            }
        }
        let index = Int(p.x / w)
        let octave = index / 7, step = index % 7
        return firstMidi + UInt8(octave * 12) + Self.whiteOffsets[step]
    }
}

The essential details:

isMultipleTouchEnabled = true. It's false by default, and without it you'll only ever get one finger.
Track notes per touch with ObjectIdentifier(touch). Each finger owns its note, so chords and glissandos work independently.
Handle touchesCancelled. A system gesture or an incoming call can cancel touches. If you don't release notes there, you get stuck notes.
Black keys are hit-tested first, because they're drawn on top.

On iOS 12 this is the only option, since SwiftUI needs iOS 13. Even on a SwiftUI app today, I'd wrap this view in a UIViewRepresentable. Touch handling for an instrument is one of the places where UIKit is still simply the better tool.

Drum pads follow the same idea in simpler form: a grid of rectangles, touchesBegan triggers hit(_:), and there's no note-off.

6. Teaching note names and positions

The listing describes the app as "teaching beginners the names & positions of notes on the piano". On the keyboard view, that's two small things: draw a label on each key, and let learners switch between naming systems.

enum NoteNaming: String, CaseIterable {
    case letters      // C D E F G A B
    case solfege      // Do Re Mi Fa Sol La Si

    static let letterNames = ["C", "C♯", "D", "D♯", "E", "F", "F♯", "G", "G♯", "A", "A♯", "B"]
    static let solfegeNames = ["Do", "Do♯", "Re", "Re♯", "Mi", "Fa", "Fa♯", "Sol", "Sol♯", "La", "La♯", "Si"]

    func name(for midi: UInt8, withOctave: Bool = true) -> String {
        let pitchClass = Int(midi) % 12
        let base = self == .letters ? Self.letterNames[pitchClass] : Self.solfegeNames[pitchClass]
        return withOctave ? "\(base)\(Int(midi) / 12 - 1)" : base      // MIDI 60 = C4
    }
}

// NoteNaming.letters.name(for: 60) == "C4"; NoteNaming.solfege.name(for: 64) == "Mi4"

In draw(_:), draw white-key labels near the bottom of each key and black-key labels only when a "show sharps" toggle is on; for beginners, too many labels is noise. Highlighting the pressed key matters more than any label. The immediate visual "this is the key you just played" is how position is learned.

7. Real-world example: Drums n Piano

This is the approach I'd use, and recommend, for Drums n Piano.

At the time of writing, its App Store listing shows:

Free, in Music and Entertainment
First released in September 2022
9 ratings in the US store, averaging about 4.4 stars
Supports iOS 12.0 and later

How the listing maps to this article:

What the listing says	Where it's covered
"Simply play and learn the piano, drums or xylophone wherever you are"	A sampler per pitched instrument; a player-node pool for drums (sections 3–4)
"This virtual app sounds real, just like the original instrument!" / "Premium sound quality"	Real samples loaded once, a low-latency session, natural note-off releases (sections 2–3)
"Teaching beginners the names & positions of notes on the piano"	Note labels and pressed-key highlighting (section 6)
"Play or learn your music chords"	Per-touch tracking with multi-touch enabled (section 5)

The listing's audience is broad: "a music teacher, singer, songwriter, or beginner or joyful kid". That's a good reminder that kids mash several keys with their whole hand. A multi-touch view that never leaves a stuck note is worth more than any feature.

8. Before you ship a virtual instrument: a checklist

Nothing loads on tap. Samples and sound banks load at launch or on instrument switch; taps only trigger notes.
The session is .playback (or a deliberate .ambient), with a small preferred buffer, and you've logged what you actually got.
Polyphony is tested. Ten-finger chords on the piano; rapid repeated hits on every drum pad.
There are no stuck notes. Test cancelled touches, a phone call mid-chord, backgrounding mid-note and Control Center swipes.
isMultipleTouchEnabled is on, and each touch owns its note.
Glissando works: sliding across keys releases and presses notes as you go.
Sample licences are cleared for everything you bundle.
You've tested on real hardware with wired and Bluetooth audio, and the app tells users that wired is tighter.

Wrapping up

A virtual instrument is mostly preparation: decode everything up front, pick the right player for the job (a sampler for pitched instruments, a node pool for one-shots), keep the audio buffer small, and track every finger yourself. Get those right, and the sound arrives with the touch, which is all a player really asks for.

Play it, or explore my other apps:

Drums n Piano (iOS): https://apps.apple.com/us/app/drums-n-piano/id1642061667
All of my free iOS apps: https://apps.apple.com/us/developer/alok-singh/id1508795536
My portfolio: https://bestlatestapps.com/alok/

If you've built an instrument app and found a better way to handle touches or voices, tell me about it in the comments. I'm especially curious about anyone doing velocity from touch force or radius.

— Alok Kumar Singh

Originally published at https://bestlatestapps.com/blog/building-a-low-latency-virtual-piano-and-drum-kit-on-ios-with-avaudioe/

Building a Real-Time Mic-to-Speaker App on iOS with AVAudioEngine

Tue, 27 Oct 2026 12:40:22 +0000

Originally published at https://bestlatestapps.com/blog/building-a-real-time-mic-to-speaker-app-on-ios-with-avaudioengine/

Live audio passthrough in Swift: session setup, permissions, feedback, interruptions and route changes, from shipping an app that does exactly this

Most audio tutorials on iOS cover one of two things: playing a file, or recording one. Very few cover the strange in-between case where the microphone and the speaker are both live at the same time, and whatever goes in comes straight back out.

That in-between case is exactly what my app Mic to Speaker – Virtual Mic does. You plug your iPhone into a speaker, or connect over Bluetooth or AirPlay, tap the screen, and your voice comes out of the speaker. I first shipped it in May 2020. Since then it has collected more than 3,400 ratings on the US App Store, and it is still the most popular of the 24 free apps I have published under my developer name.

It looks like a weekend project, and the first working version really is only a few dozen lines of Swift. But the gap between "it works on my desk" and "it works for thousands of people on random speakers, in cars, during phone calls" is where the real work lives.

This is the guide I wish I'd had: permissions, session setup, the engine graph, feedback, interruptions, route changes, background audio and App Store review. I've checked API names and availability against Apple's developer documentation and flag what's new or recently changed.

1. The problem: what "mic to speaker" really needs

On paper the requirement is one sentence: take audio from the microphone and play it through the speaker, right now. In practice that sentence hides three hard requirements.

Low latency. When you hear your own voice back, your brain notices delay quickly. A little sounds "roomy"; more sounds like an echo and makes it hard to keep talking. Every buffer between mic and speaker adds delay, so you want the smallest buffers the device can reliably handle.

The right output route. By default, when an iPhone records and plays at the same time, output goes to the receiver, the small earpiece you hold to your ear for calls. Users expect the loud bottom speaker, their Bluetooth speaker, the car stereo or an AirPlay device. Getting audio to the right place, and keeping it there, is half the job.

No howling feedback. If the mic can hear the speaker, the sound loops and grows into that painful squeal everyone knows from school assemblies. On a phone, with mic and speaker centimetres apart, that's the default outcome unless you plan for it.

I underestimated all three. My first build played through the earpiece. The second howled as soon as I turned the volume up. The third worked beautifully until a phone call came in, then stayed silent until I killed the app. Each section below is, roughly, one of those lessons.

2. Microphone permission, the modern way

Before anything else, you need the user's permission to use the microphone. Two things are required.

First, a purpose string. Add NSMicrophoneUsageDescription to your Info.plist. Apple's documentation is blunt about this: if your app tries to access the microphone without this key, the app exits. Make it specific, for example: "Virtual Mic uses the microphone to play your voice live through your speaker or headphones."

Second, the request itself. In iOS 17, Apple moved record permission from AVAudioSession to a new class, AVAudioApplication. The old AVAudioSession.requestRecordPermission(_:) is deprecated as of iOS 17. The new API has both a completion-handler version and an async version:

class func requestRecordPermission() async -> Bool

If your deployment target is below iOS 17, you need both paths. Mic to Speaker currently supports iOS 16.6 and later, so this is not theoretical for me. Here's a small helper that handles both, plus the "denied" case:

import AVFoundation
import UIKit

@MainActor
enum MicPermissionManager {

    /// Prompts if needed. Returns true if we may record.
    static func request() async -> Bool {
        if #available(iOS 17.0, *) {
            return await AVAudioApplication.requestRecordPermission()
        } else {
            return await withCheckedContinuation { continuation in
                AVAudioSession.sharedInstance().requestRecordPermission { granted in
                    continuation.resume(returning: granted)
                }
            }
        }
    }

    /// The system will not show the prompt again after a denial,
    /// so the only way forward is the Settings app.
    static func openSettings() {
        guard let url = URL(string: UIApplication.openSettingsURLString) else { return }
        UIApplication.shared.open(url)
    }
}

Three practical notes:

Ask at the moment of need, when the user first taps "start", not at launch.
Denied is permanent from the app's side. The system won't prompt again, so show a short explanation and a button that calls openSettings().
Silence is not an error. Apple's docs note that without permission the app captures only silence. The engine starts "fine" and plays nothing, so always check permission first or you'll get confusing "no sound" bug reports.

3. Configuring AVAudioSession

AVAudioSession is how your app tells iOS what kind of audio it does. Get this wrong and nothing else matters.

Category and options

For simultaneous input and output you need the .playAndRecord category. On top of that, the options do most of the heavy lifting:

.defaultToSpeaker: uses the built-in loudspeaker instead of the earpiece when nothing else is connected. This one option fixes "why is it so quiet?"
.allowBluetoothA2DP: lets output go to high-quality Bluetooth speakers and headphones. A2DP is output-only, so the iPhone's mic stays the input, which is usually what a mic-to-speaker app wants.
.allowBluetoothHFP (formerly .allowBluetooth): lets Bluetooth hands-free devices act as input and output. Apple's current docs mark the old .allowBluetooth name deprecated in favour of .allowBluetoothHFP; on an older SDK, use .allowBluetooth. HFP is the "phone call" profile with noticeably lower quality than A2DP, so I enable it only when the user wants a headset's own microphone.
.allowAirPlay: lets output go to AirPlay devices; for .playAndRecord you must set it explicitly. AirPlay buffers over the network, so expect extra latency you can't control.

Mode

The mode tunes the session for a use case:

.default: no special processing; best for music and singing, and required for echo-cancelled input (below).
.voiceChat: tuned for two-way voice. Apple's docs say it optimises EQ for voice, limits routes to voice-suitable ones and automatically applies the Bluetooth HFP option. Great for speech, not for music.
.measurement: minimises system signal processing for the rawest input.

I default to .default and offer voice processing (section 5) as a user choice.

Buffer duration and sample rate

You can ask for a smaller I/O buffer and a particular sample rate:

try session.setPreferredIOBufferDuration(0.005)  // a request, not a guarantee
try session.setPreferredSampleRate(48_000)

These are preferences; the system decides based on hardware and route. After activating, read ioBufferDuration and sampleRate to see what you actually got, and log them. Bluetooth routes often differ from what you asked for.

Echo-cancelled input (iOS 18.2+)

Starting with iOS 18.2, AVAudioSession has three new members:

isEchoCancelledInputAvailable — whether the device and current setup support it
setPrefersEchoCancelledInput(_:) — ask for it
isEchoCancelledInputEnabled — whether the system actually turned it on

Per Apple's docs, it works only with .playAndRecord and .default mode, on certain 2024-or-later iPhones, on the built-in mic and speaker route. It's tuned for a wider range of sounds than voice processing, and can switch off when the route changes (say, a headset is plugged in). Treat it as a bonus on supported hardware, not your feedback strategy.

Temporary speaker override

For a "force loudspeaker" toggle, use overrideOutputAudioPort(_:). It temporarily changes the current route, and the override clears when the route changes again.

Putting it together

import AVFoundation

enum AudioSessionConfigurator {

    static func configure(allowBluetoothMic: Bool = false,
                          preferEchoCancellation: Bool = true) throws {
        let session = AVAudioSession.sharedInstance()

        var options: AVAudioSession.CategoryOptions = [
            .defaultToSpeaker,
            .allowBluetoothA2DP,
            .allowAirPlay
        ]
        if allowBluetoothMic {
            // Use .allowBluetooth if your SDK predates .allowBluetoothHFP.
            options.insert(.allowBluetoothHFP)
        }

        try session.setCategory(.playAndRecord, mode: .default, options: options)
        try session.setPreferredSampleRate(48_000)
        try session.setPreferredIOBufferDuration(0.005)

        if #available(iOS 18.2, *),
           preferEchoCancellation,
           session.isEchoCancelledInputAvailable {
            try session.setPrefersEchoCancelledInput(true)
        }

        try session.setActive(true)

        print("Sample rate: \(session.sampleRate) Hz, "
            + "IO buffer: \(session.ioBufferDuration * 1000) ms, "
            + "route: \(session.currentRoute.outputs.map(\.portType.rawValue))")
    }

    /// Force the built-in speaker (true) or go back to the normal route (false).
    static func setSpeakerOverride(_ on: Bool) throws {
        try AVAudioSession.sharedInstance()
            .overrideOutputAudioPort(on ? .speaker : .none)
    }

    static func deactivate() {
        try? AVAudioSession.sharedInstance()
            .setActive(false, options: .notifyOthersOnDeactivation)
    }
}

4. The AVAudioEngine graph

AVAudioEngine lets you connect audio nodes like guitar pedals. For mic-to-speaker the graph is short:

inputNode → [EQ] → [Reverb] → mainMixerNode → outputNode

inputNode is the current microphone input.
AVAudioUnitEQ gives bass/treble bands and a globalGain boost (documented range −96 to +24 dB).
AVAudioUnitReverb adds room character; wetDryMix runs 0–100%, where 0 is fully dry.
mainMixerNode is created and wired to outputNode the first time you access it. Its outputVolume (0.0–1.0) is a natural master volume.

Format matching

The most common live-audio crash is a format mismatch. My rule: use the input node's own format for every connection carrying the mic signal, and let the mixer convert for the output hardware. Also validate it first: with no input available, the format can come back with a 0 Hz sample rate or zero channels, and connecting with that raises an exception Swift can't catch.

The complete class

Here's a minimal, complete engine class: one object that owns the engine, exposes a few controls and starts and stops cleanly.

import AVFoundation

enum LiveAudioError: Error {
    case noInputAvailable
}

final class LiveAudioEngine {

    private let engine = AVAudioEngine()
    private let eq = AVAudioUnitEQ(numberOfBands: 2)
    private let reverb = AVAudioUnitReverb()

    private(set) var isRunning = false

    // MARK: Controls

    /// Master volume, 0.0 ... 1.0
    var volume: Float {
        get { engine.mainMixerNode.outputVolume }
        set { engine.mainMixerNode.outputVolume = min(max(newValue, 0), 1) }
    }

    /// Extra input gain in dB, clamped to a sane range.
    var boostDB: Float {
        get { eq.globalGain }
        set { eq.globalGain = min(max(newValue, -24), 24) }
    }

    /// Bass and treble in dB.
    var bassDB: Float {
        get { eq.bands[0].gain }
        set { eq.bands[0].gain = min(max(newValue, -12), 12) }
    }
    var trebleDB: Float {
        get { eq.bands[1].gain }
        set { eq.bands[1].gain = min(max(newValue, -12), 12) }
    }

    /// Reverb amount, 0 (off) ... 100
    var reverbMix: Float {
        get { reverb.wetDryMix }
        set { reverb.wetDryMix = min(max(newValue, 0), 100) }
    }

    // MARK: Setup

    init() {
        let bass = eq.bands[0]
        bass.filterType = .lowShelf
        bass.frequency = 150
        bass.gain = 0
        bass.bypass = false

        let treble = eq.bands[1]
        treble.filterType = .highShelf
        treble.frequency = 6_000
        treble.gain = 0
        treble.bypass = false

        reverb.loadFactoryPreset(.mediumRoom)
        reverb.wetDryMix = 0

        engine.attach(eq)
        engine.attach(reverb)
    }

    // MARK: Start / stop

    func start() throws {
        guard !isRunning else { return }

        let input = engine.inputNode
        let format = input.outputFormat(forBus: 0)
        guard format.sampleRate > 0, format.channelCount > 0 else {
            throw LiveAudioError.noInputAvailable
        }

        // Rebuild connections every time: the input format can change
        // between runs (new route, new sample rate).
        engine.disconnectNodeOutput(input)
        engine.disconnectNodeOutput(eq)
        engine.disconnectNodeOutput(reverb)

        engine.connect(input, to: eq, format: format)
        engine.connect(eq, to: reverb, format: format)
        engine.connect(reverb, to: engine.mainMixerNode, format: format)

        engine.prepare()
        try engine.start()
        isRunning = true
    }

    func stop() {
        guard isRunning else { return }
        engine.stop()
        isRunning = false
    }

    /// Voice processing (echo cancellation, AGC, noise suppression).
    /// Must be changed while the engine is stopped.
    func setVoiceProcessing(_ enabled: Bool) throws {
        let wasRunning = isRunning
        stop()
        try engine.inputNode.setVoiceProcessingEnabled(enabled)
        if wasRunning { try start() }
    }

    /// Exposed so the owner can observe engine configuration changes.
    var underlyingEngine: AVAudioEngine { engine }
}

And using it from a view model:

@MainActor
final class MicViewModel: ObservableObject {
    @Published var isLive = false
    @Published var errorMessage: String?

    let audio = LiveAudioEngine()

    func toggle() async {
        if audio.isRunning {
            audio.stop()
            AudioSessionConfigurator.deactivate()
            isLive = false
            return
        }

        guard await MicPermissionManager.request() else {
            errorMessage = "Microphone access is off. Turn it on in Settings."
            return
        }

        do {
            try AudioSessionConfigurator.configure()
            audio.volume = 0.3          // start low, always
            try audio.start()
            isLive = true
        } catch {
            errorMessage = "Couldn't start audio: \(error.localizedDescription)"
        }
    }
}

Note audio.volume = 0.3. Starting quiet is a safety feature, not a nicety.

5. Taming feedback and latency

No single switch removes feedback. There are trade-offs; pick sensible defaults and let the user adjust.

Headphones vs. speaker

The most reliable fix is physics: if the mic can't hear the speaker, there's no loop. With headphones, feedback basically disappears. With a Bluetooth speaker across the room, it's manageable. With the phone's own loudspeaker centimetres from the mic, you're fighting acoustics at any useful volume.

That's why my App Store listing has plain "Safety tips": start with low volume, connect speakers before turning on, increase volume gradually, keep the device away from speakers. They came straight from user reviews and support emails.

Voice processing

setVoiceProcessingEnabled(_:) (on AVAudioIONode, iOS 13+) turns on Apple's voice processing I/O: echo cancellation, automatic gain control and noise suppression, the same family used for calls. isVoiceProcessingAGCEnabled on the input node lets you keep echo cancellation but drop automatic gain.

Change it while the engine is stopped. It reconfigures the I/O unit and the input format can change, which is why LiveAudioEngine rebuilds connections on every start().
It changes the sound. Tuned for speech, it can make singing and instruments sound processed, so I make it a user choice.
It's not magic. It reduces the loop; at high enough volume on the built-in speaker you can still get feedback.

Buffer size trade-offs

Smaller buffers mean lower latency but less time for the audio thread before the next deadline; miss it and you get clicks and dropouts. Larger buffers are smoother, but you hear yourself later. My approach:

Request a small buffer, then read back what you got.
Keep the chain light. Apple's built-in EQ and reverb are fine; heavy custom DSP is where trouble starts.
Never allocate, lock or do file I/O on the real-time thread. In a tap (level meter, recording), copy what you need and hand it off.
Accept that Bluetooth and AirPlay add buffering you can't remove. I tell users plainly that wired gives the lowest delay.

I'm deliberately not quoting millisecond numbers. Latency depends on device, iOS version, route and granted buffer size; the only honest number is the one you measure on your own devices.

6. Interruptions and route changes

This separates a demo from a shipped app. Real phones get calls, alarms, Siri, other apps taking over audio, and headphones unplugged mid-sentence.

Interruptions

When another session (say, a phone call) takes over, the system posts AVAudioSession.interruptionNotification. On .began, the system has already stopped your audio; update state and UI. On .ended, the options may include .shouldResume, a hint that resuming without user input is appropriate.

What's new: Apple's latest docs mark .shouldResume deprecated as of iOS 27 in favour of a newer resumptionRecommendationNotification. It still works on the versions most apps support, so the sample uses it; on the newest SDK, see Apple's "Handling audio interruptions" article.

For a live mic I'm conservative: auto-resume only if the user was live before and the system says resuming is fine. A mic that silently turns itself back on after a call is a privacy surprise.

Route changes

AVAudioSession.routeChangeNotification carries a reason. The critical one is .oldDeviceUnavailable: headphones unplugged or Bluetooth disconnected. Apple's guidance for media apps is to pause; for a live mic it matters even more, because audio jumps to the loudspeaker and can instantly howl. Stop first, let the user decide. For .newDeviceAvailable, keep going but rebuild the graph, since the input format may have changed.

Media services reset

Rarely, the media server restarts and the system posts AVAudioSession.mediaServicesWereResetNotification. Every audio object is now invalid: recreate the engine and reconfigure the session. Separately, AVAudioEngine posts .AVAudioEngineConfigurationChange when the hardware I/O format changes; the engine stops, and you reconnect and restart.

Putting it together

import AVFoundation

@MainActor
final class AudioEventsHandler {

    private var engine: LiveAudioEngine
    private var wasLiveBeforeInterruption = false
    private var observers: [NSObjectProtocol] = []
    var onStateChange: ((Bool) -> Void)?

    init(engine: LiveAudioEngine) {
        self.engine = engine
        observe()
    }

    deinit {
        observers.forEach { NotificationCenter.default.removeObserver($0) }
    }

    private func observe() {
        let center = NotificationCenter.default
        let session = AVAudioSession.sharedInstance()

        observers.append(center.addObserver(
            forName: AVAudioSession.interruptionNotification,
            object: session, queue: .main) { [weak self] note in
                MainActor.assumeIsolated { self?.handleInterruption(note) }
            })

        observers.append(center.addObserver(
            forName: AVAudioSession.routeChangeNotification,
            object: session, queue: .main) { [weak self] note in
                MainActor.assumeIsolated { self?.handleRouteChange(note) }
            })

        observers.append(center.addObserver(
            forName: AVAudioSession.mediaServicesWereResetNotification,
            object: session, queue: .main) { [weak self] _ in
                MainActor.assumeIsolated { self?.handleMediaServicesReset() }
            })

        observers.append(center.addObserver(
            forName: .AVAudioEngineConfigurationChange,
            object: engine.underlyingEngine, queue: .main) { [weak self] _ in
                MainActor.assumeIsolated { self?.restartIfNeeded() }
            })
    }

    private func handleInterruption(_ note: Notification) {
        guard let info = note.userInfo,
              let raw = info[AVAudioSessionInterruptionTypeKey] as? UInt,
              let type = AVAudioSession.InterruptionType(rawValue: raw) else { return }

        switch type {
        case .began:
            wasLiveBeforeInterruption = engine.isRunning
            engine.stop()
            onStateChange?(false)

        case .ended:
            let optionsRaw = info[AVAudioSessionInterruptionOptionKey] as? UInt ?? 0
            let options = AVAudioSession.InterruptionOptions(rawValue: optionsRaw)
            if wasLiveBeforeInterruption && options.contains(.shouldResume) {
                do {
                    try AVAudioSession.sharedInstance().setActive(true)
                    try engine.start()
                    onStateChange?(true)
                } catch {
                    onStateChange?(false)
                }
            }
            wasLiveBeforeInterruption = false

        @unknown default:
            break
        }
    }

    private func handleRouteChange(_ note: Notification) {
        guard let info = note.userInfo,
              let raw = info[AVAudioSessionRouteChangeReasonKey] as? UInt,
              let reason = AVAudioSession.RouteChangeReason(rawValue: raw) else { return }

        switch reason {
        case .oldDeviceUnavailable:
            // Headphones unplugged / Bluetooth gone: stop before we howl.
            engine.stop()
            onStateChange?(false)
        case .newDeviceAvailable, .categoryChange, .override:
            restartIfNeeded()
        default:
            break
        }
    }

    private func handleMediaServicesReset() {
        // Every audio object is invalid now. Rebuild from scratch.
        engine.stop()
        engine = LiveAudioEngine()
        try? AudioSessionConfigurator.configure()
        onStateChange?(false) // let the user start again
    }

    private func restartIfNeeded() {
        guard engine.isRunning else { return }
        engine.stop()
        do {
            try engine.start()   // reconnects with the new input format
        } catch {
            onStateChange?(false)
        }
    }
}

In production you'd also re-register the configuration observer for the new engine after a reset and hand it back to its owner; I've kept the shape minimal.

7. Background audio and App Store notes

Background audio

To keep the mic live with the screen locked, add audio to UIBackgroundModes (Xcode: Background Modes → "Audio, AirPlay, and Picture in Picture"). With an active .playAndRecord session and a running engine, iOS keeps the app alive and shows its microphone-in-use indicator, so users always know.

The flip side: when the user stops, really stop. Stop the engine and deactivate with .notifyOthersOnDeactivation so paused music and podcasts can resume. Holding the session forever drains battery and blocks other audio.

App Store review considerations

A specific purpose string, in the user's words.
Background audio must be real. Declaring the audio mode means actually producing audible content in the background; an idle app holding the session doesn't qualify.
An obvious "live" state: a big on/off control and a clear indicator.
Honest privacy. If you record sessions, say so and say where they're stored, and keep your App Privacy details consistent.
Don't over-promise. If the app can't act as a system-wide mic for a computer or other apps, don't imply it can.

8. Real-world example: Virtual Mic, a.k.a. Mic to Speaker

Everything above comes from building and maintaining my own apps. The main one is on the App Store as Mic to Speaker – Virtual Mic.

At the time of writing, its public App Store listing shows:

Free, in the Music and Utilities categories
First released in May 2020
About 3,400 ratings in the US store, averaging around 4.5 stars
Supports iOS 16.6 and later, on iPhone and iPad

The listing describes the core idea simply: "Use your device as a live microphone! Connect to any speaker and your voice comes out loud and clear." Here's how the listing's features map to the techniques in this article:

What the listing says	What makes it work
"Open the app and tap the screen. That's it!" / "One tap to turn on or off"	Permission request on first tap (section 2), then session + engine start (sections 3–4)
"Connect via Bluetooth, AirPlay, or cable"	`.playAndRecord` with `.defaultToSpeaker`, `.allowBluetoothA2DP`, `.allowAirPlay` (section 3)
"Works in the background" / "Runs even when screen is locked"	`UIBackgroundModes` → `audio`, active session, running engine (section 7)
"Add echo and reverb… Adjust bass and treble. Make your voice louder or softer. Everything updates in real-time"	`AVAudioUnitReverb`, `AVAudioUnitEQ` bands and gain, mixer volume, all live in the graph (section 4)
"Every session is saved automatically… MP3, WAV, M4A"	A tap on the graph feeding a file writer, off the real-time thread (section 5)
"Safety tips: Start with low volume… Avoid feedback by keeping device away from speakers"	The feedback realities in section 5, and starting at a low volume by default

The listing's use cases range from live streaming, karaoke and podcasts to announcements and hearing assistance: amplifying voices in meetings or classes. That last one shapes my defaults most. For someone using your app to hear better, a feedback squeal or surprise route change isn't a glitch; it hurts. Hence "start quiet" and "stop on .oldDeviceUnavailable". It's also why the app still supports iOS 16.6 and carries the pre-iOS 17 permission path from section 2.

The same idea exists on Android as Virtual Mic on Google Play (10K+ downloads at the time of writing). Its listing highlights real-time noise reduction, echo cancellation, reverb and echo effects, an equaliser, input gain and output volume controls, and support for Bluetooth speakers and wired headphones.

On Android the building blocks are AudioRecord (capture) and AudioTrack (playback), or Google's Oboe C++ library over AAudio/OpenSL ES for low-latency work. Same problems (latency, routing, feedback, audio focus instead of interruptions), very different APIs. That's my next article.

9. Before you ship live audio: a 7-point checklist

Permission flow is complete. NSMicrophoneUsageDescription is specific; you ask at the moment of need; iOS 17+ uses AVAudioApplication, older versions fall back to AVAudioSession; denied users get an "Open Settings" path.
The session is configured on purpose. .playAndRecord, .defaultToSpeaker, the Bluetooth options you actually want (A2DP for quality, HFP only when needed), and you log the real sample rate and buffer duration you got.
Formats come from the hardware. You connect using the input node's format, check it's valid, and rebuild connections whenever the route or configuration changes.
Feedback has defaults. Start at low volume, recommend headphones or distance, offer voice processing as a user choice, and use echo-cancelled input only where isEchoCancelledInputAvailable says you can.
Interruptions and route changes are tested on a real device. Phone call, alarm, Siri, unplugging headphones, Bluetooth disconnecting, AirPlay switching: the app ends up in a sensible, visible state every time.
Background behaviour is honest. The audio background mode is declared only because you really play audio in the background, and you deactivate the session with .notifyOthersOnDeactivation when the user stops.
The real-time thread stays clean. No allocations, locks, logging or file I/O inside render callbacks or taps; heavy work is handed off.

Wrapping up

A mic-to-speaker app is a great way to learn iOS audio because there's nowhere to hide: latency is audible, routing mistakes are obvious, and a missed interruption leaves a silent app. AVAudioSession plus AVAudioEngine give you everything you need in a few hundred lines of Swift, as long as you respect the session, follow the hardware's formats and handle real-world events.

If you want to see the result in action, try my apps:

Mic to Speaker – Virtual Mic (iOS): https://apps.apple.com/us/app/mic-to-speaker-virtual-mic/id1514011963
Virtual Mic (Android): https://play.google.com/store/apps/details?id=com.aryansbtloe.microphone.android
All 24 of my free iOS apps: https://apps.apple.com/us/developer/alok-singh/id1508795536
My portfolio: https://bestlatestapps.com/alok/

If you've shipped live audio on iOS and hit a problem I didn't cover, I'd love to hear about it in the comments. Follow me here on Medium for the Android version of this guide.

— Alok Kumar Singh

Originally published at https://bestlatestapps.com/blog/building-a-real-time-mic-to-speaker-app-on-ios-with-avaudioengine/

Tap-to-Match Marble Game in SpriteKit and SwiftUI: Physics, Cluster Matching, Lives and Power-Ups

Tue, 27 Oct 2026 12:39:50 +0000

Originally published at https://bestlatestapps.com/blog/building-a-tap-to-match-marble-game-with-spritekit-and-swiftui/

A complete walkthrough of the game loop: marbles that settle under real physics, finding touching same-colour clusters, a pause-safe countdown, lives and levels, Lightning, Heart and Bomb power-ups, and particle effects, all hosted in SwiftUI with SpriteView

Every game developer has a "small" game that taught them how games actually work. Mine is Marbles Popperz, a puzzle game where you tap marbles of the same colour to match them and score points before time runs out. It has a lives system, levels that get harder, three power-ups (Lightning Flash, Heart and Bomb) and global leaderboards.

On paper that's a weekend project. In practice it touches nearly every part of a real game: a physics world, hit-testing, a frame-driven clock that has to survive pausing, difficulty tuning, juicy feedback, and a SwiftUI interface laid over a SpriteKit scene.

This article walks through how I'd build each piece with SpriteKit, Apple's 2D game framework. The code is mine, written for this article, and the design choices are labelled as the approach I'd use. Game Center leaderboards get their own article, my Speck Match piece, so here I'll stay on gameplay.

1. Why SpriteKit, and how it fits with SwiftUI

For a 2D casual game on Apple platforms, SpriteKit is the shortest path. It gives you a scene graph (SKScene, SKSpriteNode), actions for animation (SKAction), a built-in physics engine (SKPhysicsBody) and particles (SKEmitterNode), all rendered on the GPU, with no third-party engine to update.

Since iOS 14, SpriteView lets a SwiftUI view host a scene directly. So menus, the HUD and settings can be ordinary SwiftUI, and only the playfield is SpriteKit:

import SwiftUI
import SpriteKit

struct GameScreen: View {
    @StateObject private var state = GameState()
    @State private var scene: MarbleScene = {
        let s = MarbleScene(size: CGSize(width: 390, height: 700))
        s.scaleMode = .resizeFill
        return s
    }()

    var body: some View {
        ZStack(alignment: .top) {
            SpriteView(scene: scene, preferredFramesPerSecond: 60)
                .ignoresSafeArea()
                .onAppear { scene.state = state }

            HUD(score: state.score, lives: state.lives,
                timeLeft: state.timeLeft, level: state.level)
                .padding()
        }
    }
}

@MainActor
final class GameState: ObservableObject {
    @Published var score = 0
    @Published var lives = 3
    @Published var level = 1
    @Published var timeLeft: TimeInterval = 60
    @Published var isGameOver = false
}

The rule I follow: the scene owns the simulation; SwiftUI owns the chrome. The scene writes to a shared GameState, and SwiftUI just renders it. Keep SwiftUI state changes to a few per second, not 60, or you'll pay for view updates every frame.

2. A playfield of marbles that settle under physics

Marbles should behave like marbles. When some pop, the ones above should roll down and fill the gap. Giving each marble a circular physics body, and the scene an edge loop, gets you that for free:

import SpriteKit

enum MarbleColor: CaseIterable { case red, blue, green, yellow, purple }

final class Marble: SKSpriteNode {
    let color: MarbleColor
    static let radius: CGFloat = 22

    init(color: MarbleColor) {
        self.color = color
        let texture = SKTexture(imageNamed: "marble-\(color)")    // from a texture atlas
        super.init(texture: texture, color: .clear,
                   size: CGSize(width: Self.radius * 2, height: Self.radius * 2))
        name = "marble"
        let body = SKPhysicsBody(circleOfRadius: Self.radius)
        body.restitution = 0.2          // a little bounce
        body.friction = 0.3
        body.allowsRotation = true
        physicsBody = body
    }
    required init?(coder: NSCoder) { fatalError() }
}

final class MarbleScene: SKScene {
    weak var state: GameState?
    var config = LevelConfig.forLevel(1)
    var remaining: TimeInterval = 60
    private var lastUpdate: TimeInterval = 0

    override func didMove(to view: SKView) {
        backgroundColor = .black
        physicsBody = SKPhysicsBody(edgeLoopFrom: frame)         // the walls of the jar
        physicsWorld.gravity = CGVector(dx: 0, dy: -9.8)
        view.ignoresSiblingOrder = true                          // lets SpriteKit batch draws
        fill(count: config.marbleCount)
    }

    func fill(count: Int) {
        let palette = Array(MarbleColor.allCases.prefix(config.colorCount))
        for i in 0..<count {
            let marble = Marble(color: palette.randomElement()!)
            marble.position = CGPoint(x: .random(in: 40...(size.width - 40)),
                                      y: size.height + CGFloat(i) * 8)   // drop in from above
            addChild(marble)
        }
    }
}

Two cheap wins: put every marble texture in one texture atlas, so all marbles are drawn in a few batched calls; and set ignoresSiblingOrder so SpriteKit is free to reorder draws for batching.

3. Tap-to-match: finding the touching cluster

The listing describes the core loop simply: "Tap marbles of the same color to match them… The more marbles you match, the higher your score." The approach I'd use is cluster matching. Tapping a marble pops it together with every same-colour marble it is touching, directly or through a chain. A lone marble doesn't pop. Bigger clusters score more, which rewards looking before you tap.

Hit-testing uses nodes(at:). The cluster is a breadth-first search over "touching" neighbours:

extension MarbleScene {
    override func touchesBegan(_ touches: Set<UITouch>, with event: UIEvent?) {
        guard let point = touches.first?.location(in: self),
              let tapped = nodes(at: point).compactMap({ $0 as? Marble }).first else { return }

        let cluster = cluster(from: tapped)
        guard cluster.count >= 2 else {
            tapped.run(.sequence([.moveBy(x: 6, y: 0, duration: 0.04),
                                  .moveBy(x: -12, y: 0, duration: 0.08),
                                  .moveBy(x: 6, y: 0, duration: 0.04)]))   // "no match" wiggle
            return
        }
        pop(cluster)
        state?.score += score(forClusterOf: cluster.count)
    }

    func cluster(from start: Marble) -> [Marble] {
        let all = children.compactMap { $0 as? Marble }.filter { $0.color == start.color }
        let touchDistance = Marble.radius * 2 + 4                  // small tolerance for resting contact
        var visited: Set<ObjectIdentifier> = [ObjectIdentifier(start)]
        var queue = [start], result: [Marble] = []

        while let current = queue.popLast() {
            result.append(current)
            for other in all where !visited.contains(ObjectIdentifier(other)) {
                if hypot(other.position.x - current.position.x,
                         other.position.y - current.position.y) <= touchDistance {
                    visited.insert(ObjectIdentifier(other))
                    queue.append(other)
                }
            }
        }
        return result
    }

    /// Quadratic reward: 2 marbles = 20, 5 marbles = 125, 10 marbles = 500.
    func score(forClusterOf n: Int) -> Int { n * n * 5 }
}

With a few dozen marbles on screen, this brute-force neighbour check is trivially fast. If you ever have hundreds, bucket marbles into a grid by position first. Distance-based neighbours work better than physics contact callbacks here, because resting marbles don't keep reporting contacts.

4. Popping with juice

A match should feel good: a quick scale-up, a fade, a particle burst and a sound. The physics then lets the marbles above fall into the gap.

extension MarbleScene {
    func pop(_ marbles: [Marble]) {
        for (i, marble) in marbles.enumerated() {
            marble.physicsBody = nil                              // stop it interacting while it pops
            let delay = SKAction.wait(forDuration: Double(i) * 0.03)   // a ripple through the cluster
            let burst = SKAction.run { [weak self] in self?.spawnBurst(at: marble.position) }
            let vanish = SKAction.group([.scale(to: 1.4, duration: 0.12), .fadeOut(withDuration: 0.12)])
            marble.run(.sequence([delay, burst, vanish, .removeFromParent()]))
        }
        run(.playSoundFileNamed("pop.caf", waitForCompletion: false))
    }

    func spawnBurst(at point: CGPoint) {
        guard let emitter = SKEmitterNode(fileNamed: "Pop.sks") else { return }   // designed in Xcode
        emitter.position = point
        emitter.numParticlesToEmit = 24
        addChild(emitter)
        emitter.run(.sequence([.wait(forDuration: 0.6), .removeFromParent()]))
    }
}

The 30 ms stagger is the cheapest "juice" there is. A cluster of eight pops as a ripple instead of all at once, and players read that as a chain reaction. Always remove finished emitters, or they pile up invisibly and eat frame time.

5. A countdown that survives pausing

"Watch the timer – you need to match quickly!" The timer must stop when the game is paused, when a phone call comes in and when the app goes to the background. A Timer or Date arithmetic gets this wrong. The robust pattern is to accumulate frame deltas in update(_:), and only while the game is actually running:

extension MarbleScene {
    override func update(_ currentTime: TimeInterval) {
        defer { lastUpdate = currentTime }
        guard lastUpdate > 0, !isPaused, let state, !state.isGameOver else { return }

        // Clamp so a long hitch (or resuming from pause) can't eat seconds at once.
        let dt = min(currentTime - lastUpdate, 1.0 / 20.0)
        remaining -= dt

        // Push to SwiftUI only when the displayed whole second changes.
        let shown = max(0, remaining.rounded(.up))
        if shown != state.timeLeft { state.timeLeft = shown }

        if remaining <= 0 { timeUp() }
        if children.compactMap({ $0 as? Marble }).isEmpty { levelCleared() }
    }
}

(remaining and lastUpdate are the stored properties declared on the scene in section 2.) Three details carry the weight:

Clamp dt. After a pause, currentTime jumps forward. Without the clamp, the first frame back would subtract all of the paused time.
Guard on isPaused. Pausing the SKView stops the frame loop entirely. Pausing just the scene stops its actions and physics, and the explicit guard makes sure the clock stops too, whichever you use.
Throttle UI updates. Writing to @Published state 60 times a second makes SwiftUI re-render the HUD 60 times a second. Write only when the displayed value changes.

Pausing itself is one line, scene.isPaused = true. Wire it to the scene phase going to .inactive or .background in SwiftUI.

6. Lives and levels

The listing has a "Lives system – be careful not to run out!" and "Level progression – difficulty increases as you advance". The approach I'd use: running out of time on a level costs a life and restarts that level, and clearing the jar advances you. Difficulty lives in one small table, so tuning never means touching game logic:

struct LevelConfig {
    let marbleCount: Int
    let colorCount: Int
    let seconds: TimeInterval
    let powerUpChance: Double

    static func forLevel(_ level: Int) -> LevelConfig {
        LevelConfig(
            marbleCount: min(30 + level * 4, 80),       // more marbles
            colorCount: min(3 + level / 3, 5),          // more colours = smaller clusters
            seconds: max(60 - Double(level) * 2, 30),   // less time
            powerUpChance: max(0.08 - Double(level) * 0.004, 0.03)
        )
    }
}

extension MarbleScene {
    func timeUp() {
        guard let state else { return }
        state.lives -= 1
        if state.lives <= 0 { state.isGameOver = true; isPaused = true }
        else { restartLevel() }
    }

    func restartLevel() {
        enumerateChildNodes(withName: "marble") { node, _ in node.removeFromParent() }
        remaining = config.seconds
        fill(count: config.marbleCount)
    }

    func levelCleared() {
        state?.level += 1
        config = .forLevel(state?.level ?? 1)
        remaining = config.seconds
        fill(count: config.marbleCount)
    }
}

Adding a colour is the most powerful difficulty knob in a colour-match game. Each extra colour shrinks the average cluster, which lowers scores and raises pressure without touching the clock.

7. Power-ups: Lightning, Heart and Bomb

The listing names three power-ups: "Lightning Flash – Clear multiple marbles at once", "Heart – Gain an extra life" and "Bomb – Explode surrounding marbles". I'd model them as special marbles that spawn occasionally and trigger when tapped:

enum PowerUp { case lightning, heart, bomb }

extension MarbleScene {
    func trigger(_ powerUp: PowerUp, at point: CGPoint) {
        let marbles = children.compactMap { $0 as? Marble }
        switch powerUp {
        case .lightning:
            // Clear every marble of the most common colour.
            let counts = Dictionary(grouping: marbles, by: \.color)
            if let biggest = counts.max(by: { $0.value.count < $1.value.count })?.value {
                pop(biggest); state?.score += score(forClusterOf: biggest.count)
            }
        case .heart:
            state?.lives += 1
        case .bomb:
            let blastRadius: CGFloat = 110
            let hit = marbles.filter { hypot($0.position.x - point.x, $0.position.y - point.y) < blastRadius }
            pop(hit); state?.score += hit.count * 10
            // Push the survivors outwards for a satisfying shove.
            for m in marbles where !hit.contains(m) {
                let d = CGVector(dx: m.position.x - point.x, dy: m.position.y - point.y)
                let len = max(hypot(d.dx, d.dy), 1)
                m.physicsBody?.applyImpulse(CGVector(dx: d.dx / len * 30, dy: d.dy / len * 30))
            }
        }
    }
}

Which marbles "Lightning" clears is my design choice; the listing only says it clears multiple at once. The bomb's impulse on survivors is where the physics world pays off a second time. The jar visibly reacts, and the new arrangement creates fresh clusters.

8. Real-world example: Marbles Popperz

This walkthrough is based on building Marbles Popperz. The code here is the approach I'd use, not the shipped source.

At the time of writing, its App Store listing shows:

Free, in Games (Puzzle, Board)
First released in December 2021
3 ratings in the US store, averaging about 3.7 stars
Supports iOS 16.0 and later

How the listing maps to this article:

What the listing says	Where it's covered
"Simple tap-to-match gameplay" / "Match marbles by color to remove them"	Hit-testing and cluster matching (section 3)
"Beautiful visual effects and animations"	Staggered pops and particle bursts (section 4)
"Watch the timer - you need to match quickly!"	Pause-safe countdown in `update(_:)` (section 5)
"Lives system" / "Level progression - difficulty increases as you advance"	Lives and a level table (section 6)
"Lightning Flash", "Heart", "Bomb"	Power-ups (section 7)
"Global leaderboards - compete with players worldwide"	Game Center, covered in my Speck Match article

The rating average is a useful honest signal for a small game: three ratings is too few to mean much. The way to learn what players struggle with is to watch someone play your first three levels without saying a word.

9. Before you ship a casual game: a checklist

The timer pauses on pause, on interruptions and in the background, and dt is clamped on resume.
The UI isn't updated every frame, only when displayed values change.
Textures are in an atlas and ignoresSiblingOrder is on. Check the draw count with showsDrawCount during development.
Finished emitters and actions are removed. No invisible nodes pile up.
The difficulty table is data, and each level has been played by someone other than you.
Taps feel fair. The hit area isn't smaller than the visible marble, and a mis-tap gets clear feedback.
Colour isn't the only cue. Add patterns or symbols to marbles for colour-blind players.
Sound respects the silent switch, and there's a mute option.
Test on the oldest supported device at 60 fps with the maximum marble count.

Wrapping up

A tap-to-match game is a perfect classroom. Physics gives you settling for free. A simple search gives you clusters. A clamped delta gives you an honest clock. A table gives you difficulty. And a few milliseconds of stagger turn "it works" into "it feels good". SpriteKit and SwiftUI together cover all of it with nothing to install.

Play the game, or explore my other work:

Marbles Popperz (iOS): https://apps.apple.com/us/app/marbles-popperz/id1601511276
All of my free iOS apps: https://apps.apple.com/us/developer/alok-singh/id1508795536
My portfolio: https://bestlatestapps.com/alok/

What's your favourite bit of game "juice"? Share it in the comments.

— Alok Kumar Singh

Originally published at https://bestlatestapps.com/blog/building-a-tap-to-match-marble-game-with-spritekit-and-swiftui/

AdMob Earnings Dashboard for iOS: OAuth with PKCE, AdMob Reporting API and Offline Caching

Mon, 26 Oct 2026 12:42:23 +0000

Originally published at https://bestlatestapps.com/blog/building-an-admob-earnings-dashboard-for-ios/

Signing in with ASWebAuthenticationSession and PKCE, storing tokens safely in the Keychain, calling networkReport:generate, decoding a streamed report, turning micros into money, why "today" is a Los Angeles day, live earning rates, and caching for offline use

If you have apps with ads, you know the habit: open the AdMob website on your phone, pinch, zoom, wait for the dashboard, then do it again an hour later. I wanted a native, fast, glanceable view of my AdMob earnings, so I built AdEarnings Pro. It's a dashboard for today's earnings, yesterday's comparison, earning rates per second, minute and hour, weekly averages for earnings and clicks, six months of history and currency conversion. It uses Google Sign-In, and the listing states plainly: "Your AdMob data is not saved, shared, or accessible to us."

That promise shapes the whole architecture. There's no server of mine in the middle. The app talks directly to Google's AdMob API using the user's own OAuth token, and everything is cached on the device.

This article walks through how to build that: OAuth for a native app done properly, the AdMob Reporting API's actual request and response format, and a few surprises from Google's documentation. The biggest is that the report time zone currently supports only America/Los_Angeles, which changes what "today" means for everyone outside California. Apple APIs are checked against Apple's documentation and Google APIs against Google's. Where I describe my approach rather than the shipped code, I say so.

1. The shape of the app: no middleman

The data flow is deliberately short:

The user signs in with Google and grants a read-only reporting scope.
The app stores the refresh token in the Keychain, on the device.
The app calls admob.googleapis.com directly with a short-lived access token.
Results are cached locally for offline viewing.

Google's AdMob API getting-started guide lists two scopes. admob.readonly lets an app "See all AdMob data", and Google notes that this "doesn't include sensitive data, such as payments or campaign details". admob.report lets it "See ad performance and earnings reports. See publisher ID, timezone, and default currency code." For an earnings dashboard, admob.report is the narrowest scope that works, and asking for the minimum is both good privacy and good for consent rates. Google's OAuth guide makes the same point: the fewer scopes you request, the more likely users are to grant them.

The listing also notes "This app requires access to your existing Google AdMob account". The API reads accounts; it can't create one.

2. OAuth for a native app: system browser, PKCE, no embedded web views

Google's OAuth documentation is blunt about embedded web views. Opening the authorization page in WKWebView produces a disallowed_useragent error, and Google recommends its Google Sign-In for iOS library or AppAuth instead. Both are built on the same standard flow: the system browser plus PKCE (Proof Key for Code Exchange). Here's that flow with Apple's own ASWebAuthenticationSession (iOS 12+), so you can see every step:

import AuthenticationServices
import UIKit
import CryptoKit
import Foundation

struct PKCE {
    let verifier: String
    let challenge: String

    /// Google: verifier is 43–128 chars of [A-Z a-z 0-9 - . _ ~]; S256 challenge = BASE64URL(SHA256(verifier)).
    static func make() -> PKCE {
        var bytes = [UInt8](repeating: 0, count: 32)
        _ = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)
        let verifier = Data(bytes).base64URLEncoded()                     // 43 chars
        let challenge = Data(SHA256.hash(data: Data(verifier.utf8))).base64URLEncoded()
        return PKCE(verifier: verifier, challenge: challenge)
    }
}

extension Data {
    func base64URLEncoded() -> String {
        base64EncodedString().replacingOccurrences(of: "+", with: "-")
            .replacingOccurrences(of: "/", with: "_").replacingOccurrences(of: "=", with: "")
    }
}

@MainActor
final class GoogleAuth: NSObject, ASWebAuthenticationPresentationContextProviding {
    // An iOS OAuth client in Google Cloud; its redirect uses the reversed client ID as the scheme.
    let clientID = "1234-abc.apps.googleusercontent.com"
    var redirectScheme: String { "com.googleusercontent.apps.1234-abc" }
    var redirectURI: String { "\(redirectScheme):/oauth2redirect" }

    func signIn() async throws -> (code: String, pkce: PKCE) {
        let pkce = PKCE.make()
        let state = UUID().uuidString
        var url = URLComponents(string: "https://accounts.google.com/o/oauth2/v2/auth")!
        url.queryItems = [
            .init(name: "client_id", value: clientID),
            .init(name: "redirect_uri", value: redirectURI),
            .init(name: "response_type", value: "code"),
            .init(name: "scope", value: "https://www.googleapis.com/auth/admob.report"),
            .init(name: "code_challenge", value: pkce.challenge),
            .init(name: "code_challenge_method", value: "S256"),
            .init(name: "state", value: state)
        ]

        let callback: URL = try await withCheckedThrowingContinuation { cont in
            let session = ASWebAuthenticationSession(url: url.url!, callbackURLScheme: redirectScheme) { url, error in
                if let url { cont.resume(returning: url) } else { cont.resume(throwing: error ?? URLError(.cancelled)) }
            }
            session.presentationContextProvider = self
            session.prefersEphemeralWebBrowserSession = false   // reuse an existing Google session if there is one
            session.start()
        }

        let items = URLComponents(url: callback, resolvingAgainstBaseURL: false)?.queryItems ?? []
        guard items.first(where: { $0.name == "state" })?.value == state,       // CSRF check
              let code = items.first(where: { $0.name == "code" })?.value else { throw URLError(.userAuthenticationRequired) }
        return (code, pkce)
    }

    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
        UIApplication.shared.connectedScenes.compactMap { ($0 as? UIWindowScene)?.keyWindow }.first ?? ASPresentationAnchor()
    }
}

Every parameter here comes from Google's OAuth documentation for installed apps:

The authorization endpoint is accounts.google.com/o/oauth2/v2/auth.
response_type=code is required.
The challenge is S256, which Google recommends.
The verifier is 43 to 128 characters. Thirty-two random bytes, base64url-encoded, gives exactly 43.
state protects against cross-site request forgery. Google calls it out as important, and the code checks it.

On iOS 17.4 and later, ASWebAuthenticationSession also accepts a Callback object (ASWebAuthenticationSession.Callback). SwiftUI has a webAuthenticationSession environment value from iOS 16.4. Either is a tidier wrapper around the same flow.

3. Exchanging the code and keeping tokens safe

Next, swap the code for tokens at oauth2.googleapis.com/token, sending the PKCE verifier (not the challenge). Google's docs note that client_secret doesn't apply to iOS clients:

struct TokenResponse: Decodable {
    let access_token: String
    let expires_in: Int
    let refresh_token: String?
    let scope: String
}

extension GoogleAuth {
    func exchange(code: String, pkce: PKCE) async throws -> TokenResponse {
        try await tokenRequest([
            "client_id": clientID, "code": code, "code_verifier": pkce.verifier,
            "grant_type": "authorization_code", "redirect_uri": redirectURI
        ])
    }

    func refresh(using refreshToken: String) async throws -> TokenResponse {
        try await tokenRequest(["client_id": clientID, "grant_type": "refresh_token", "refresh_token": refreshToken])
    }

    private func tokenRequest(_ form: [String: String]) async throws -> TokenResponse {
        var request = URLRequest(url: URL(string: "https://oauth2.googleapis.com/token")!)
        request.httpMethod = "POST"
        request.setValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")
        var body = URLComponents(); body.queryItems = form.map { URLQueryItem(name: $0.key, value: $0.value) }
        request.httpBody = body.percentEncodedQuery?.data(using: .utf8)
        let (data, _) = try await URLSession.shared.data(for: request)
        return try JSONDecoder().decode(TokenResponse.self, from: data)
    }
}

Then store the refresh token in the Keychain, never in UserDefaults, and mark it device-only:

import Security

enum TokenVault {
    static let account = "admob.refresh"

    static func save(_ token: String) {
        let base: [String: Any] = [kSecClass as String: kSecClassGenericPassword,
                                   kSecAttrAccount as String: account]
        SecItemDelete(base as CFDictionary)
        var item = base
        item[kSecValueData as String] = Data(token.utf8)
        item[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
        SecItemAdd(item as CFDictionary, nil)
    }
}

AfterFirstUnlockThisDeviceOnly lets a widget or a background refresh read the token after the first unlock, while keeping it out of backups and off other devices. Two of Google's notes are worth building in. First, check the returned scope: users can grant less than you asked for, and the app should explain what's missing. Second, there are limits on how many refresh tokens are issued per client and user, so keep and reuse the refresh token rather than signing in again each time.

"Revoke consent anytime" maps to two things. The user can remove access from their Google Account settings, and the app can call https://oauth2.googleapis.com/revoke?token=… on sign-out and then delete the Keychain item.

4. Asking AdMob for a report

The AdMob API's core endpoint is accounts.networkReport.generate, a POST to https://admob.googleapis.com/v1/accounts/{publisherId}/networkReport:generate with a reportSpec. Here's a request for daily earnings and clicks over the last seven days:

struct ReportDate: Codable { let year: Int, month: Int, day: Int }

struct NetworkReportRequest: Encodable {
    struct Spec: Encodable {
        struct Range: Encodable { let startDate: ReportDate; let endDate: ReportDate }
        struct Localization: Encodable { let currencyCode: String; let languageCode: String }
        let dateRange: Range
        let dimensions: [String]
        let metrics: [String]
        let localizationSettings: Localization
        let timeZone: String
    }
    let reportSpec: Spec
}

func weeklyRequest(endingOn end: ReportDate, start: ReportDate, currency: String) -> NetworkReportRequest {
    .init(reportSpec: .init(
        dateRange: .init(startDate: start, endDate: end),
        dimensions: ["DATE"],
        metrics: ["ESTIMATED_EARNINGS", "CLICKS", "IMPRESSIONS"],
        localizationSettings: .init(currencyCode: currency, languageCode: "en-US"),
        timeZone: "America/Los_Angeles"
    ))
}

Three facts from Google's reference page shape this request:

ESTIMATED_EARNINGS is in micros. "$6.50 would be represented as 6500000." Never put that number in a Double and divide casually; use Decimal.
Currency comes from localizationSettings.currencyCode. Google says the currency unit of the earnings metrics is "determined by the localization setting for currency". The approach I'd use for "View earnings in your preferred currency" is to ask AdMob for that currency directly, so the figures are AdMob's own.
The time zone currently has only one supported value. Google: "Warning: The 'America/Los_Angeles' is the only supported value at the moment." Section 6 is about what that means.

5. Decoding a streamed report

The response isn't a simple object. It's "the result of a server-side streaming RPC": a JSON array whose first element has a header, then one row per result, then a footer. Each element has exactly one of those keys. So decode each element as an enum-like struct:

struct ReportChunk: Decodable {
    struct Row: Decodable {
        struct DimensionValue: Decodable { let value: String }
        struct MetricValue: Decodable { let microsValue: String?; let integerValue: String?; let doubleValue: Double? }
        let dimensionValues: [String: DimensionValue]
        let metricValues: [String: MetricValue]
    }
    let header: [String: AnyDecodable]?      // dateRange, localizationSettings
    let row: Row?
    let footer: [String: AnyDecodable]?      // matchingRowCount, warnings
}

struct AnyDecodable: Decodable { init(from decoder: Decoder) throws {} }   // we don't need header details here

struct DailyEarnings: Codable, Identifiable {
    var id: String { day }
    let day: String          // "20261022"
    let earnings: Decimal    // in report currency
    let clicks: Int
}

func parse(_ data: Data) throws -> [DailyEarnings] {
    try JSONDecoder().decode([ReportChunk].self, from: data).compactMap(\.row).map { row in
        let micros = Decimal(string: row.metricValues["ESTIMATED_EARNINGS"]?.microsValue ?? "0") ?? 0
        return DailyEarnings(day: row.dimensionValues["DATE"]?.value ?? "",
                             earnings: micros / 1_000_000,
                             clicks: Int(row.metricValues["CLICKS"]?.integerValue ?? "0") ?? 0)
    }
}

Google's example response shows "microsValue": 6500000 as a bare number. The API's JSON mapping for 64-bit integers often uses strings, so I'd decode both forms in production (a small custom init(from:)). The DATE dimension value is YYYYMMDD, as Google's reference describes.

Displaying money is then earnings.formatted(.currency(code: currency)). Don't hand-roll formats, because symbol placement and grouping vary by locale.

6. Why "today" is a Los Angeles day

Here's the subtle part. If reports can only be in America/Los_Angeles, then AdMob's "today" starts at midnight Pacific time. For me in India, that's 12:30 or 1:30 in the afternoon, depending on US daylight saving. A dashboard that labels the latest row "Today" without explanation will confuse anyone outside the Pacific time zone.

The approach I'd use is to compute "today" in the report's calendar and say so in the UI:

struct ReportCalendar {
    static let zone = TimeZone(identifier: "America/Los_Angeles")!
    static var calendar: Calendar { var c = Calendar(identifier: .gregorian); c.timeZone = zone; return c }

    static func reportDate(for date: Date = .now) -> ReportDate {
        let c = calendar.dateComponents([.year, .month, .day], from: date)
        return ReportDate(year: c.year!, month: c.month!, day: c.day!)
    }

    /// Seconds elapsed in the current *report* day; the denominator for live rates.
    static func secondsIntoReportDay(now: Date = .now) -> TimeInterval {
        now.timeIntervalSince(calendar.startOfDay(for: now))
    }
}

The live earning rates in the listing ("per second, minute, and hour") follow naturally. Today's earnings divided by seconds into the report day gives an average rate so far:

func rates(todayEarnings: Decimal, now: Date = .now) -> (perSecond: Decimal, perMinute: Decimal, perHour: Decimal) {
    let seconds = Decimal(max(ReportCalendar.secondsIntoReportDay(now: now), 60))   // avoid tiny denominators just after midnight
    let perSecond = todayEarnings / seconds
    return (perSecond, perSecond * 60, perSecond * 3600)
}

Label it honestly, as "average so far today". Ad revenue isn't evenly spread over a day, and AdMob's figures are estimated earnings that can be revised.

7. Pull to refresh, offline cache and the weekly view

"Pull-to-refresh for fresh data" is one modifier, refreshable (iOS 15+). "Offline-ready with cached data" means saving the last good response, with a timestamp, and showing it whenever the network fails:

import SwiftUI

@MainActor
final class Dashboard: ObservableObject {
    @Published private(set) var days: [DailyEarnings] = []
    @Published private(set) var updatedAt: Date?
    private let cacheURL = URL.cachesDirectory.appending(path: "report-week.json")

    init() {
        if let data = try? Data(contentsOf: cacheURL),
           let cached = try? JSONDecoder().decode(Cached.self, from: data) {
            days = cached.days; updatedAt = cached.at                   // instant first paint, even offline
        }
    }

    func refresh(using api: AdMobAPI) async {
        do {
            let fresh = try await api.lastSevenDays()
            days = fresh; updatedAt = .now
            try? JSONEncoder().encode(Cached(days: fresh, at: .now)).write(to: cacheURL, options: .atomic)
        } catch {
            // Keep showing the cache; the "Updated 2 h ago" label tells the user it's stale.
        }
    }

    var weeklyAverage: Decimal {
        days.isEmpty ? 0 : days.map(\.earnings).reduce(0, +) / Decimal(days.count)
    }

    private struct Cached: Codable { let days: [DailyEarnings]; let at: Date }
}

struct DashboardView: View {
    @StateObject private var model = Dashboard()
    let api: AdMobAPI
    var body: some View {
        List {
            if let updatedAt = model.updatedAt {
                Text("Updated \(updatedAt, format: .relative(presentation: .named))").font(.caption)
            }
            ForEach(model.days.reversed()) { day in
                LabeledContent(day.day, value: day.earnings, format: .currency(code: "USD"))
            }
        }
        .refreshable { await model.refresh(using: api) }
        .task { await model.refresh(using: api) }
    }
}

Putting the cache in Caches is deliberate. It's disposable, it's re-fetchable, and it holds only aggregated numbers from the user's own account on the user's own device. That fits the listing's privacy statement. (AdMobAPI here is the small wrapper around section 4's request, with a valid access token.)

8. Real-world example: AdEarnings Pro

This walkthrough comes from building AdEarnings Pro. The code above is the approach I'd use, written for this article, not a copy of the app's source.

At the time of writing, its App Store listing shows:

Free, in Developer Tools
First released in November 2025
No ratings yet in the US store
Supports iOS 17.6 and later

How the listing maps to this article:

What the listing says	Where it's covered
"Secure Google Sign-In authentication" / "Google OAuth authentication is required to access AdMob API services"	System-browser OAuth with PKCE, tokens in the Keychain (sections 2–3)
"Your AdMob data is not saved, shared, or accessible to us"	Direct device-to-Google calls, no middleman (section 1)
"View today's earnings with live updates. Compare yesterday's performance."	`networkReport:generate` with the `DATE` dimension (sections 4–5)
"Live earning rates per second, minute, and hour"	Rates over the Pacific report day (section 6)
"Weekly average trends for earnings and clicks"	`ESTIMATED_EARNINGS` and `CLICKS` (sections 4 and 7)
"Convert earnings to any currency…"	`localizationSettings.currencyCode` (section 4)
"Pull-to-refresh for fresh data" / "Offline-ready with cached data"	`refreshable` and a timestamped cache (section 7)
"Revoke consent anytime"	Google Account settings and the revoke endpoint (section 3)

The listing also mentions unpaid earnings, last payment history and GDPR consent management. Those are outside this article's scope.

9. Before you ship an OAuth-powered dashboard: a checklist

Use the narrowest scope that works, and check the granted scope in the token response.
Use the system browser, PKCE (S256) and a state check. No WKWebView for sign-in.
Keep the refresh token in the Keychain, device-only, and reuse it.
Sign-out revokes the token and clears the Keychain and caches.
Handle money as Decimal from micros, formatted with the currency's own format.
Make the report time zone explicit. "Today" is a Pacific day, and the UI says so.
Label rates and estimates honestly: "average so far" and "estimated".
Show cached data instantly, with a visible "Updated…" time.
Complete Google's OAuth app verification if your scopes need it before public release. Google's docs describe an "unverified app" screen otherwise.
No third-party analytics touches the earnings data.

Wrapping up

An earnings dashboard looks like a chart, but it's mostly about trust. Sign in the way Google and Apple both recommend, ask for the least access, keep tokens on the device, talk to the API directly, and be honest about what the numbers mean, including the surprising fact that AdMob's "today" is a Los Angeles day. Get those right, and a glance at your phone replaces a dozen trips to a desktop website.

Try the app, or explore my other work:

AdEarnings Pro (iOS): https://apps.apple.com/us/app/adearnings-pro/id6754509445
All of my free iOS apps: https://apps.apple.com/us/developer/alok-singh/id1508795536
My portfolio: https://bestlatestapps.com/alok/

What's the one metric you check most in your ad dashboard? Tell me in the comments.

— Alok Kumar Singh

Originally published at https://bestlatestapps.com/blog/building-an-admob-earnings-dashboard-for-ios/

Offline Quotes App in SwiftUI: 50K-Quote Library, Daily Quote, Streaks and Share-as-Image

Mon, 26 Oct 2026 12:42:11 +0000

Originally published at https://bestlatestapps.com/blog/building-an-offline-quotes-app-in-swiftui/

Bundling and importing a large library into SwiftData, picking a "quote of the day" deterministically, search with recent queries, collections, time-zone-safe streaks, rendering shareable quote cards with ImageRenderer, and Light/Dark/Auto themes

A quotes app looks like the simplest thing in the App Store: a list of text and a share button. Then you build one and the real questions show up. Where do 50,000 quotes live, and how do they get onto the phone without a slow first launch? How does every user get the same "quote of the day" without a server deciding it? What counts as a reading streak when someone flies from Delhi to San Francisco? And how do you turn a quote into an image that looks good on Instagram?

I've worked through those questions building Facts and Quotes, my app of curated quotes, motivational facts and wisdom. It has categories, offline access, search with recent searches, collections, reading streaks and achievements, sharing quotes as images or text, and Light, Dark and Auto themes.

This article walks through how I'd build each of those pieces in SwiftUI and SwiftData. Availability was checked against Apple's documentation. Where I describe an approach rather than the app's exact implementation, I say so.

1. Ship the library in the bundle, import it once

"Offline access, read anywhere" means the quotes ship with the app. A plain JSON file in the bundle is easy to produce, diff and validate. Decoding 50,000 small records is quick, but querying them is better done from a real store, so I'd import into SwiftData on first launch:

import SwiftData
import Foundation

@Model
final class Quote {
    @Attribute(.unique) var id: String
    var text: String
    var author: String
    var category: String
    var isFavorite: Bool = false
    var collections: [QuoteCollection] = []

    init(id: String, text: String, author: String, category: String) {
        self.id = id; self.text = text; self.author = author; self.category = category
    }
}

@Model
final class QuoteCollection {
    var name: String
    var createdAt: Date = Date.now
    @Relationship(inverse: \Quote.collections) var quotes: [Quote] = []
    init(name: String) { self.name = name }
}

struct QuoteRecord: Decodable { let id, text, author, category: String }

The import runs once, in the background, in batches, so memory stays flat and the UI never blocks:

@ModelActor
actor LibraryImporter {
    func importIfNeeded(bundleVersion: Int) throws {
        let key = "library.importedVersion"
        guard UserDefaults.standard.integer(forKey: key) < bundleVersion,
              let url = Bundle.main.url(forResource: "quotes", withExtension: "json") else { return }

        let records = try JSONDecoder().decode([QuoteRecord].self, from: Data(contentsOf: url))
        let existing = Set(try modelContext.fetch(FetchDescriptor<Quote>()).map(\.id))

        for (index, record) in records.enumerated() where !existing.contains(record.id) {
            modelContext.insert(Quote(id: record.id, text: record.text,
                                      author: record.author, category: record.category))
            if index % 2_000 == 0 { try modelContext.save() }   // batch saves
        }
        try modelContext.save()
        UserDefaults.standard.set(bundleVersion, forKey: key)
    }
}

Two design points:

A library version number. When an app update adds quotes, bump the version and the importer adds only the new IDs. Favourites and collections are untouched because existing rows are never rewritten.
Stable IDs. Give every quote a permanent ID in the source file. If you ever key on the text, fixing a typo would orphan a user's favourite.

For a "daily new quotes automatically updated" feature, the same importer can accept a small JSON file downloaded from your own server. The bundled library guarantees it still works offline on day one.

2. A quote of the day with no server

A "daily quote" should be the same all day, change at midnight and need no network. The trick is a deterministic pick from the local date:

import Foundation

enum DailyPick {
    /// Same answer for everyone on the same local calendar day.
    static func index(for date: Date = .now, count: Int, calendar: Calendar = .current) -> Int {
        guard count > 0 else { return 0 }
        let c = calendar.dateComponents([.year, .month, .day], from: date)
        let key = "\(c.year!)-\(c.month!)-\(c.day!)"
        return Int(stableHash(key) % UInt64(count))
    }

    /// FNV-1a: stable across launches and devices (unlike Swift's `hashValue`).
    static func stableHash(_ string: String) -> UInt64 {
        var hash: UInt64 = 0xcbf2_9ce4_8422_2325
        for byte in string.utf8 {
            hash ^= UInt64(byte)
            hash &*= 0x0000_0100_0000_01B3
        }
        return hash
    }
}

The gotcha worth a paragraph: don't use String.hashValue. Swift randomises hashing per process launch, so your "quote of the day" would change every time the app opened. Use a fixed algorithm like FNV-1a.

Then fetch by a sorted offset rather than loading everything:

func quoteOfTheDay(in context: ModelContext) throws -> Quote? {
    let total = try context.fetchCount(FetchDescriptor<Quote>())          // iOS 17+
    var descriptor = FetchDescriptor<Quote>(sortBy: [SortDescriptor(\.id)])
    descriptor.fetchOffset = DailyPick.index(count: total)
    descriptor.fetchLimit = 1
    return try context.fetch(descriptor).first
}

Sorting by the stable ID matters too. Without a sort order, "the 1,234th quote" isn't guaranteed to be the same row tomorrow.

3. Search across content, author and category, with recent searches

SwiftUI's searchable (iOS 16+) and SwiftData's #Predicate (iOS 17+) do most of the work. localizedStandardContains gives the case- and diacritic-insensitive matching people expect from a search box:

import SwiftUI
import SwiftData

struct SearchView: View {
    @State private var text = ""
    @AppStorage("recentSearches") private var recentData = Data()

    var body: some View {
        NavigationStack {
            QuoteResults(query: text)
                .navigationTitle("Search")
                .searchable(text: $text, prompt: "Quotes, authors, categories")
                .searchSuggestions {
                    if text.isEmpty {
                        ForEach(recent, id: \.self) { term in
                            Text(term).searchCompletion(term)
                        }
                    }
                }
                .onSubmit(of: .search) { remember(text) }
        }
    }

    private var recent: [String] { (try? JSONDecoder().decode([String].self, from: recentData)) ?? [] }

    private func remember(_ term: String) {
        let trimmed = term.trimmingCharacters(in: .whitespaces)
        guard !trimmed.isEmpty else { return }
        let updated = ([trimmed] + recent.filter { $0.caseInsensitiveCompare(trimmed) != .orderedSame }).prefix(8)
        recentData = (try? JSONEncoder().encode(Array(updated))) ?? Data()
    }
}

struct QuoteResults: View {
    @Query private var quotes: [Quote]

    init(query: String) {
        let q = query
        _quotes = Query(filter: #Predicate<Quote> {
            q.isEmpty ||
            $0.text.localizedStandardContains(q) ||
            $0.author.localizedStandardContains(q) ||
            $0.category.localizedStandardContains(q)
        }, sort: \Quote.author)
    }

    var body: some View {
        List(quotes) { quote in
            VStack(alignment: .leading, spacing: 4) {
                Text("“\(quote.text)”")
                Text("— \(quote.author)").font(.caption).foregroundStyle(.secondary)
            }
        }
    }
}

Rebuilding the Query in the child view's initialiser is the standard way to drive a dynamic predicate from parent state. Recent searches are small and per-device, so @AppStorage is the right home for them.

4. Collections and favourites

With the many-to-many relationship from section 1, collections are a few lines. Favourites are just a flag. The listing says the Favorites collection "automatically syncs your liked quotes", so I'd treat it as a virtual collection, a query, rather than a stored one that can drift out of sync:

struct FavoritesView: View {
    @Query(filter: #Predicate<Quote> { $0.isFavorite }, sort: \Quote.author)
    private var favorites: [Quote]

    var body: some View {
        List(favorites) { Text($0.text) }
            .overlay { if favorites.isEmpty { ContentUnavailableView("No favourites yet", systemImage: "heart") } }
    }
}

func add(_ quote: Quote, to collection: QuoteCollection) {
    guard !collection.quotes.contains(where: { $0.id == quote.id }) else { return }
    collection.quotes.append(quote)
}

Deleting a collection shouldn't delete its quotes. The default delete rule for a relationship, nullify, does exactly that.

5. Streaks that survive time zones

A streak is "the number of consecutive days, ending today, on which you read". The bugs come from storing timestamps and doing arithmetic in seconds. Then 23:50 and 00:10 count as the same day, or a flight makes a day disappear.

The fix is to store calendar days as the user experienced them, as plain date strings, and count backwards:

import Foundation

struct StreakTracker {
    private(set) var days: Set<String>          // "2026-10-22", in the user's local calendar at the time
    var calendar = Calendar.current

    private func key(_ date: Date) -> String {
        let c = calendar.dateComponents([.year, .month, .day], from: date)
        return String(format: "%04d-%02d-%02d", c.year!, c.month!, c.day!)
    }

    mutating func recordRead(at date: Date = .now) { days.insert(key(date)) }

    func currentStreak(asOf now: Date = .now) -> Int {
        var day = calendar.startOfDay(for: now)
        // Not read yet today? The streak can still be alive from yesterday.
        if !days.contains(key(day)) {
            day = calendar.date(byAdding: .day, value: -1, to: day)!
        }
        var count = 0
        while days.contains(key(day)) {
            count += 1
            day = calendar.date(byAdding: .day, value: -1, to: day)!
        }
        return count
    }
}

Why this is honest:

Each day is recorded in the local calendar at the moment it happens. Reading at 23:55 in Delhi is "the 22nd", whatever happens afterwards.
Today doesn't break the streak until it's over. Opening the app at 8 a.m. shouldn't show zero because you haven't read yet.
Calendar arithmetic, not 86,400-second arithmetic. date(byAdding: .day…) handles daylight-saving days of 23 or 25 hours.

Achievements, like "7-day streak" or "read 100 quotes", are then pure functions of this data. Compute them; don't store them separately.

"Share quotes as beautiful images or text" is two lines of SwiftUI once you have the pieces: ImageRenderer (iOS 16+) to rasterise a SwiftUI view, and ShareLink with a Transferable item (iOS 16+):

import SwiftUI

struct QuoteCard: View {
    let quote: Quote
    var body: some View {
        VStack(alignment: .leading, spacing: 20) {
            Text("“\(quote.text)”").font(.system(size: 44, weight: .semibold, design: .serif))
            Text("— \(quote.author)").font(.title2).foregroundStyle(.white.opacity(0.8))
        }
        .foregroundStyle(.white)
        .padding(80)
        .frame(width: 1080, height: 1350)                        // a 4:5 portrait post
        .background(LinearGradient(colors: [.indigo, .purple], startPoint: .topLeading, endPoint: .bottomTrailing))
    }
}

struct ShareableQuote: Transferable {
    let quote: Quote
    static var transferRepresentation: some TransferRepresentation {
        DataRepresentation(exportedContentType: .png) { item in
            await MainActor.run {
                let renderer = ImageRenderer(content: QuoteCard(quote: item.quote))
                renderer.scale = 1                                // the view is already 1080 px wide
                return renderer.uiImage?.pngData() ?? Data()
            }
        }
        ProxyRepresentation { "“\($0.quote.text)” — \($0.quote.author)" }   // text fallback
    }
}

struct ShareButton: View {
    let quote: Quote
    var body: some View {
        ShareLink(item: ShareableQuote(quote: quote),
                  preview: SharePreview("Quote by \(quote.author)")) {
            Label("Share", systemImage: "square.and.arrow.up")
        }
    }
}

Details that matter:

Design the card at output pixel size and render with scale = 1. Sizes stay predictable, and text is sharp at the size social apps actually use.
Offer text too. The ProxyRepresentation gives the share sheet a plain-text version, so Messages or Notes receive words, not a picture of words.
Rendering happens on the main actor. ImageRenderer is main-actor bound, hence the MainActor.run.

7. Light, Dark and Auto, with colour tokens

"Light, Dark, and Auto" is a three-way setting where Auto means "follow the system". In SwiftUI, preferredColorScheme(nil) is exactly that:

enum ThemeSetting: String, CaseIterable { case auto, light, dark
    var scheme: ColorScheme? { switch self { case .auto: nil; case .light: .light; case .dark: .dark } }
}

@main
struct QuotesApp: App {
    @AppStorage("theme") private var theme = ThemeSetting.auto
    var body: some Scene {
        WindowGroup {
            RootView().preferredColorScheme(theme.scheme)
        }
        .modelContainer(for: [Quote.self, QuoteCollection.self])
    }
}

The listing mentions a design system with 50+ colour tokens. The approach I'd use is to define each token once in the asset catalog with light and dark variants, and refer to it by meaning (Color("surfaceElevated"), Color("textSecondary")) rather than by hue. Then a theme change is free, and no screen hard-codes .black.

8. Real-world example: Facts and Quotes

All of this comes from building Facts and Quotes. The code above is the approach I'd use, written for this article, not a copy of the app's source.

At the time of writing, its App Store listing shows:

Free, in Health & Fitness and Productivity
First released in August 2022
3 ratings in the US store, all 5 stars
Supports iOS 17.6 and later

How the listing maps to this article:

What the listing says	Where it's covered
"50,000+ curated quotes", "Offline access - read anywhere, anytime"	Bundled library imported into SwiftData (section 1)
"Daily new quotes automatically updated"	Versioned importer plus a deterministic daily pick (sections 1–2)
"Search quotes by content, author, or category" / "Recent searches"	`searchable` + `#Predicate` + `searchSuggestions` (section 3)
"Create custom collections…" / "Favorites collection automatically syncs your liked quotes"	SwiftData relationships and a query-based Favorites (section 4)
"Track your reading streak and daily progress" / "Unlock achievements"	Calendar-day streaks (section 5)
"Share quotes as beautiful images or text"	`ImageRenderer` + `Transferable` + `ShareLink` (section 6)
"Light, Dark, and Auto theme support" / "50+ color tokens"	`preferredColorScheme` and semantic colours (section 7)

The listing also mentions AI-powered recommendations and haptic feedback. Those are topics for their own articles. I've written about haptics separately, in my Haptics Explorer piece.

9. Before you ship a content app: a checklist

The first launch is fast. The import runs in the background, in batches, and the UI shows today's quote immediately.
Every item has a stable ID. Updates never break favourites or collections.
The daily pick uses a stable hash. No hashValue, and the fetch has a fixed sort order.
Search is case- and accent-insensitive, and recent searches are capped.
Streaks are tested across midnight, daylight saving and a time-zone change.
Shared images are rendered at their target pixel size, with a text fallback.
Auto theme follows the system; no colour is hard-coded.
Attribution is correct. Every quote has an author, or "Unknown". Misattributed quotes are the most common complaint in this category.
Accessibility. Quote text scales with Dynamic Type, and VoiceOver reads the author after the quote.

Wrapping up

The app is simple to use because the hard parts are hidden. Ship content offline and import it once. Make "daily" deterministic. Store days, not seconds. Render share images at their real size. None of it needs a server, which is also why the app works on a plane.

Try the app, or explore my other work:

Facts and Quotes (iOS): https://apps.apple.com/us/app/facts-and-quotes/id1607878544
All of my free iOS apps: https://apps.apple.com/us/developer/alok-singh/id1508795536
My portfolio: https://bestlatestapps.com/alok/

Got a favourite quote? Drop it in the comments.

— Alok Kumar Singh

Originally published at https://bestlatestapps.com/blog/building-an-offline-quotes-app-in-swiftui/

Offline eBook Reader for iOS: Downloads, Typography, Reading Progress and Highlights

Mon, 26 Oct 2026 12:41:45 +0000

Originally published at https://bestlatestapps.com/blog/building-an-offline-ebook-reader-for-ios/

Downloading and storing public-domain books, previewing before you download, a UITextView-based reader with font, line height, margin and theme settings, saving your place as a character offset instead of a page number, bookmarks and highlights (including iOS 26's multi-range selection), reading time estimates and reading statistics

There's something special about reading a classic on your phone at night, when the book is more than a century old and the screen is the newest thing in the room. Novels Club is my app for that: thousands of public-domain classics, literature, poetry and philosophy, with recommendations, offline downloads, customisable reading settings, progress tracking, bookmarks, highlights and reading statistics.

A reading app sounds like "show text in a scroll view". It isn't, and the interesting problems are subtle. Where does a downloaded book live, and should it go into the user's iCloud backup? How do you let someone preview a book without downloading all of it? And the one that catches everybody: how do you remember someone's place when they change the font size and every "page" moves?

This article walks through how I'd build each part. The APIs are checked against Apple's documentation, including two iOS 27 deprecations in UITextView that matter for highlighting.

1. The library model

A book has metadata you can browse before downloading, and an optional local file once it's downloaded. In SwiftData:

import SwiftData
import Foundation

@Model
final class Book {
    @Attribute(.unique) var id: String
    var title: String
    var author: String
    var categories: [String]
    var wordCount: Int?
    var remoteURL: URL
    var localFileName: String?          // set once downloaded
    var progressOffset: Int = 0         // UTF-16 offset of the first visible character
    var lastOpened: Date?
    @Relationship(deleteRule: .cascade) var marks: [Mark] = []

    init(id: String, title: String, author: String, categories: [String], remoteURL: URL) {
        self.id = id; self.title = title; self.author = author
        self.categories = categories; self.remoteURL = remoteURL
    }

    var isDownloaded: Bool { localFileName != nil }

    /// "About 6 h 40 min" for a 100,000-word novel at 250 words per minute.
    var readingTimeEstimate: Duration? {
        wordCount.map { .seconds(Double($0) / 250 * 60) }
    }
}

@Model
final class Mark {
    enum Kind: String, Codable { case bookmark, highlight }
    var kind: Kind
    var location: Int                   // UTF-16 offset
    var length: Int                     // 0 for bookmarks
    var note: String?
    var created: Date = Date.now
    init(kind: Kind, location: Int, length: Int) { self.kind = kind; self.location = location; self.length = length }
}

Two decisions shape everything later. Positions are character offsets, not page numbers (section 5). And marks cascade-delete with their book, so removing a book never leaves orphaned highlights behind.

The reading-time estimate uses 250 words per minute, a common rule of thumb for adult silent reading. It's an estimate, and the UI should say "about".

2. Downloading books, and keeping them out of iCloud backup

"Download books for offline reading" with URLSession's async API (iOS 15+) is short. The details that matter are where the file goes and whether it's backed up:

import Foundation

enum BookStore {
    static var directory: URL {
        let dir = URL.applicationSupportDirectory.appending(path: "Books", directoryHint: .isDirectory)
        try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
        return dir
    }

    /// Downloads a book, moves it into place and excludes it from iCloud backup.
    static func download(_ book: Book) async throws {
        let (tempURL, response) = try await URLSession.shared.download(from: book.remoteURL)
        guard (response as? HTTPURLResponse)?.statusCode == 200 else { throw URLError(.badServerResponse) }

        var destination = directory.appending(path: "\(book.id).txt")
        try? FileManager.default.removeItem(at: destination)
        try FileManager.default.moveItem(at: tempURL, to: destination)   // the temp file is deleted on return

        var values = URLResourceValues()
        values.isExcludedFromBackup = true        // re-downloadable content doesn't belong in backups
        try destination.setResourceValues(values)

        book.localFileName = destination.lastPathComponent
    }
}

Application Support, not Caches. The system can purge Caches under storage pressure, and a book vanishing mid-read on a plane is exactly what "offline reading" promises won't happen.
isExcludedFromBackup. The books can be downloaded again, so they shouldn't eat the user's iCloud quota. Apple's storage guidance asks for exactly this.
Move the temp file immediately. The async download(from:) gives you a temporary file that's deleted once you're done with it, so move it before doing anything else.

For a progress bar, pass a URLSessionTaskDelegate to download(from:delegate:), or use a URLSessionDownloadTask with a URLSessionDownloadDelegate (iOS 7+) and observe the task's progress.

3. Preview before downloading

"Preview books before downloading" doesn't need a separate preview file. If the server supports range requests, ask for just the first few kilobytes:

extension BookStore {
    static func preview(_ book: Book, bytes: Int = 16_384) async throws -> String {
        var request = URLRequest(url: book.remoteURL)
        request.setValue("bytes=0-\(bytes - 1)", forHTTPHeaderField: "Range")
        let (data, response) = try await URLSession.shared.data(for: request)

        // 206 = Partial Content. A 200 means the server ignored Range and sent everything,
        // so keep only the opening part either way.
        guard let http = response as? HTTPURLResponse, [200, 206].contains(http.statusCode) else {
            throw URLError(.badServerResponse)
        }
        let slice = data.prefix(bytes)
        // A byte cut can split a multi-byte character; trim back to valid UTF-8.
        for trim in 0..<4 {
            if let text = String(data: slice.dropLast(trim), encoding: .utf8) { return text }
        }
        return ""
    }
}

That last loop is easy to forget. A byte range can end in the middle of a multi-byte UTF-8 character, such as an accented letter in a French novel, and then String(data:encoding:) returns nil for the whole preview.

4. A reader with real typography settings

The listing promises "font size, font family, line height, margins" and "light, dark, and custom color schemes". UITextView (read-only) gives you excellent text layout, selection and accessibility for free. Since iOS 16 it can be created explicitly with TextKit 2 via init(usingTextLayoutManager:):

import SwiftUI
import UIKit

struct ReaderSettings: Equatable {
    var fontName = "Georgia"
    var fontSize: CGFloat = 19
    var lineHeight: CGFloat = 1.45       // multiple of the font's natural line height
    var margin: CGFloat = 24
    var theme = ReaderTheme.sepia
}

struct ReaderTheme: Equatable {
    var background: UIColor, text: UIColor
    static let light = ReaderTheme(background: .white, text: .black)
    static let sepia = ReaderTheme(background: UIColor(red: 0.98, green: 0.95, blue: 0.88, alpha: 1),
                                   text: UIColor(red: 0.26, green: 0.20, blue: 0.14, alpha: 1))
    static let dark  = ReaderTheme(background: UIColor(white: 0.08, alpha: 1), text: UIColor(white: 0.85, alpha: 1))
}

struct ReaderView: UIViewRepresentable {
    let text: String
    let settings: ReaderSettings
    @Binding var offset: Int             // reading position, see section 5

    func makeUIView(context: Context) -> UITextView {
        let view = UITextView(usingTextLayoutManager: true)   // TextKit 2 (iOS 16+)
        view.isEditable = false
        view.isSelectable = true                              // needed for highlights
        view.delegate = context.coordinator
        return view
    }

    func updateUIView(_ view: UITextView, context: Context) {
        guard context.coordinator.applied != settings else { return }
        context.coordinator.applied = settings

        let font = UIFont(name: settings.fontName, size: settings.fontSize)
            ?? .systemFont(ofSize: settings.fontSize)
        let paragraph = NSMutableParagraphStyle()
        paragraph.lineHeightMultiple = settings.lineHeight
        paragraph.paragraphSpacing = settings.fontSize * 0.6

        view.attributedText = NSAttributedString(string: text, attributes: [
            .font: UIFontMetrics(forTextStyle: .body).scaledFont(for: font),   // respects Dynamic Type
            .foregroundColor: settings.theme.text,
            .paragraphStyle: paragraph
        ])
        view.backgroundColor = settings.theme.background
        view.textContainerInset = UIEdgeInsets(top: 32, left: settings.margin, bottom: 48, right: settings.margin)

        context.coordinator.restore(offset, in: view)          // keep the reader's place after re-layout
    }

    func makeCoordinator() -> Coordinator { Coordinator(offset: $offset) }
}

The applied != settings guard matters. Rebuilding the attributed string for a 150,000-word novel is expensive, so do it only when a setting actually changes, not on every SwiftUI update. For very long books, the approach I'd use is to split by chapter and load one chapter at a time.

5. Reading progress that survives font changes

Here's the trap. If you save "page 143", or a scroll offset of 18,400 points, then the moment someone bumps the font from 17 to 21 point, page 143 is a different passage. The fix is to save the character the reader is looking at, a UTF-16 offset into the text, which no layout change can move:

final class Coordinator: NSObject, UITextViewDelegate {
    var offset: Binding<Int>
    var applied: ReaderSettings?
    var onHighlight: (([NSRange]) -> Void)?      // set by the reader screen to save Marks
    init(offset: Binding<Int>) { self.offset = offset }

    /// The first character at the top-left of the visible area.
    func currentOffset(in view: UITextView) -> Int {
        let topLeft = CGPoint(x: view.textContainerInset.left + 1,
                              y: view.contentOffset.y + view.textContainerInset.top + 1)
        guard let position = view.closestPosition(to: topLeft) else { return 0 }
        return view.offset(from: view.beginningOfDocument, to: position)    // UTF-16 units
    }

    func scrollViewDidEndDecelerating(_ scrollView: UIScrollView) { save(scrollView) }
    func scrollViewDidEndDragging(_ scrollView: UIScrollView, willDecelerate: Bool) {
        if !willDecelerate { save(scrollView) }
    }
    private func save(_ scrollView: UIScrollView) {
        guard let view = scrollView as? UITextView else { return }
        offset.wrappedValue = currentOffset(in: view)
    }

    /// After re-layout, bring that character back to the top.
    func restore(_ offset: Int, in view: UITextView) {
        DispatchQueue.main.async {                                  // after layout has happened
            guard let start = view.position(from: view.beginningOfDocument, offset: offset),
                  let end = view.position(from: start, offset: 1),
                  let range = view.textRange(from: start, to: end) else { return }
            let rect = view.firstRect(for: range)
            view.setContentOffset(CGPoint(x: 0, y: max(0, rect.minY - view.textContainerInset.top)), animated: false)
        }
    }
}

closestPosition(to:) and offset(from:to:) come from UITextInput (iOS 3.2+), which UITextView adopts. They do exactly what we need: convert between points on screen and positions in the text. With this:

Changing the font, line height or margins keeps the same sentence at the top of the screen.
"Continue reading where you left off" is just opening the book and restoring progressOffset.
Percentage progress is offset / text.utf16.count, which is meaningful whatever the layout.

Save on scroll end, not on every scroll event. Writing to SwiftData 60 times a second while flicking through a chapter is wasted work.

6. Bookmarks and highlights, and the iOS 26 text-selection change

Since positions are character offsets, a highlight is just (location, length) and a bookmark is (location, 0). Both are stable because a public-domain text never changes. Rendering highlights is an attribute pass:

func applyHighlights(_ marks: [Mark], to storage: NSMutableAttributedString, color: UIColor) {
    for mark in marks where mark.kind == .highlight {
        let range = NSRange(location: mark.location, length: mark.length)
        guard NSMaxRange(range) <= storage.length else { continue }
        storage.addAttribute(.backgroundColor, value: color.withAlphaComponent(0.35), range: range)
    }
}

To create highlights, add an item to the text view's edit menu. This is where the APIs are changing:

iOS 16 introduced textView(_:editMenuForTextIn:suggestedActions:), which gives you a single NSRange. Apple's documentation now marks it deprecated in iOS 27.
iOS 26 added textView(_:editMenuForTextInRanges:suggestedActions:), which gives you an array of ranges. Apple's documentation explains that a selection can be several discontiguous ranges, for example when bidirectional text is selected. Correspondingly, UITextView.selectedRange is marked deprecated in iOS 27, alongside the newer selectedRanges.

Since the app supports iOS 16.6 and later, I'd implement both and funnel them into one function:

extension Coordinator {
    private func highlightAction(for ranges: [NSRange]) -> UIAction {
        UIAction(title: "Highlight", image: UIImage(systemName: "highlighter")) { [weak self] _ in
            self?.onHighlight?(ranges.filter { $0.length > 0 })
        }
    }

    // iOS 26+: one or more selected ranges.
    @available(iOS 26, *)
    func textView(_ textView: UITextView, editMenuForTextInRanges ranges: [NSValue],
                  suggestedActions: [UIMenuElement]) -> UIMenu? {
        UIMenu(children: [highlightAction(for: ranges.map(\.rangeValue))] + suggestedActions)
    }

    // iOS 16–25: a single range (deprecated in iOS 27).
    func textView(_ textView: UITextView, editMenuForTextIn range: NSRange,
                  suggestedActions: [UIMenuElement]) -> UIMenu? {
        UIMenu(children: [highlightAction(for: [range])] + suggestedActions)
    }
}

The iOS 26 method's [NSValue] parameter type is taken from Apple's published declaration. Each value wraps an NSRange.

7. Reading statistics without surveillance

"Track your reading statistics: books read, pages read, reading time" and "reading streaks". The honest way to measure reading time is to count only while the reader is on screen and the app is active:

struct ReadingClock {
    private var startedAt: Date?
    private(set) var total: TimeInterval = 0

    mutating func resume() { if startedAt == nil { startedAt = .now } }
    mutating func pause() {
        if let start = startedAt { total += min(Date.now.timeIntervalSince(start), 30 * 60) }  // cap idle sessions
        startedAt = nil
    }
}
// In the reader: resume() on appear and when scenePhase becomes .active;
// pause() on disappear and when it leaves .active.

The 30-minute cap per session stops a phone left open on the nightstand from claiming you read for eight hours. "Pages read" can be derived from the change in character offset divided by a nominal page size (say 1,800 characters), which gives consistent numbers whatever font you use. Streaks follow the calendar-day approach I described in my Facts and Quotes article.

8. Real-world example: Novels Club

Everything here comes from building Novels Club. The code is the approach I'd use, written for this article, not the shipped source.

At the time of writing, its App Store listing shows:

Free, in Magazines & Newspapers and Entertainment
First released in December 2025
No ratings yet in the US store
Supports iOS 16.6 and later

How the listing maps to this article:

What the listing says	Where it's covered
"All books are in the public domain, so you can read them completely"	Why offsets and highlights can be stable (sections 1 and 6)
"Download books for offline reading" / "All your downloaded books are stored locally"	Downloads in Application Support, excluded from backup (section 2)
"Preview books before downloading"	Range-request previews (section 3)
"Customizable reading settings: font size, font family, line height, margins" / "light, dark, and custom color schemes"	The TextKit 2 reader (section 4)
"Reading progress tracking" / "Continue reading where you left off"	Character-offset progress (section 5)
"Bookmarks and highlights for your favorite passages"	Marks and the edit menu (section 6)
"See book ratings, reading time estimates, and difficulty levels"	Reading-time estimates (section 1)
"Track your reading statistics…" / "View reading streaks"	Honest reading time (section 7)

With no ratings yet, the app is at the stage where every piece of feedback shapes it. If you read classics on your phone, I'd love to hear what your current reader gets wrong.

9. Before you ship a reading app: a checklist

Books live in Application Support, excluded from iCloud backup.
Previews handle partial UTF-8 and servers that ignore Range.
Re-layout happens only when settings change; long books load by chapter.
Progress is stored as a character offset and restored after every settings change.
Progress is saved on scroll end, not continuously.
Highlights are offset ranges, with both edit-menu delegate methods (iOS 16 and iOS 26+).
Dynamic Type works, and the custom font size is a multiplier on top of it.
Reading time only counts while the reader is active, with an idle cap.
Themes are tested in a dark room. Pure white on black is harsh; slightly grey text reads better.
Copyright is respected. Check the public-domain status of every title for the regions you distribute in, because it varies by country.

Wrapping up

A good reader disappears. You open the book, you're exactly where you left off, the text looks the way you like, and nothing reminds you it's an app. Getting there means a few unglamorous decisions: store characters instead of pages, keep books out of backups, re-lay out only when you must, and adopt the new multi-range text APIs while keeping the old ones for older systems.

Try the app, or explore my other work:

Novels Club (iOS): https://apps.apple.com/us/app/novels-club/id6755921578
All of my free iOS apps: https://apps.apple.com/us/developer/alok-singh/id1508795536
My portfolio: https://bestlatestapps.com/alok/

Which classic should everyone read at least once? Tell me in the comments.

— Alok Kumar Singh

Originally published at https://bestlatestapps.com/blog/building-an-offline-ebook-reader-for-ios/

Offline-First Bible Reader on iOS: Bundled SQLite, Full-Text Search and iCloud-Synced Notes

Sun, 25 Oct 2026 12:40:54 +0000

Originally published at https://bestlatestapps.com/blog/building-an-offline-first-bible-reader-on-ios/

How I'd structure a scripture app that works on a plane: a read-only text database, fast search, user data that follows you between devices, read-aloud and a verse-of-the-day widget

The first app I ever published under my App Store developer name was a Bible reader. It went live on 20 April 2020, a day ahead of the next few apps I shipped that month, and today it's called Bible Study AI – Read Offline. It has grown a lot since then: reading plans, devotionals, a prayer journal, widgets and an AI study assistant. But the promise in the name has never changed. It works offline.

"Offline" sounds like a feature you tick off. It isn't. It's an architectural decision, and it shapes everything: where the text lives, how search works, where highlights and notes are saved, how sync behaves when the network comes back, and what you do on a device that has never been online since the app was installed.

This article walks through the architecture I'd recommend for this kind of app: a large, read-only text corpus plus a small amount of precious user data. Scripture is the example, but the same shape fits dictionaries, manuals, legal codes, recipe books and course material. All the code is Swift, and I've checked API names and availability against Apple's developer documentation. Where I'm describing the approach I'd use rather than the app's exact internals, I say so.

1. The problem: two kinds of data with opposite needs

A Bible app holds two very different kinds of data.

The text itself. All 66 books, in several translations; the app's listing mentions KJV, ASV, Webster and World English. That's tens of thousands of verses per translation. It's large, it never changes on the device, and it must be searchable in milliseconds. It belongs to you, the developer, not the user.

What the user creates. Highlights in different colours, notes on verses and chapters, bookmarks, reading-plan progress, prayer journal entries. It's small, it changes all the time, and it's the only data the user would be upset to lose. It belongs to them, and they expect it on their iPad as well as their iPhone.

The mistake I see most often is putting both in one store. Then every app update that fixes a typo in the text has to migrate a database full of user notes, and every sync pushes megabytes of scripture to iCloud for no reason.

So split them:

App bundle (read-only)                 User store (read-write, synced)
┌──────────────────────────┐           ┌──────────────────────────────┐
│ bible.sqlite             │           │ Core Data + CloudKit         │
│  translations, books,    │  verse    │  Highlight, Note, Bookmark,  │
│  chapters, verses        │◀─ id ────▶│  PlanProgress, Prayer        │
│  verses_fts (FTS5)       │           │                              │
└──────────────────────────┘           └──────────────────────────────┘

The only thing that links them is a stable verse identifier. Get that right first.

2. A verse ID that will never change

A verse needs an identifier that's identical across translations, app versions and devices. I use a simple integer: book * 1_000_000 + chapter * 1_000 + verse. John 3:16 is book 43, so its ID is 43_003_016.

struct VerseRef: Hashable, Codable, Comparable {
    let book: Int      // 1...66, canonical order
    let chapter: Int
    let verse: Int

    var id: Int { book * 1_000_000 + chapter * 1_000 + verse }

    init(book: Int, chapter: Int, verse: Int) {
        self.book = book; self.chapter = chapter; self.verse = verse
    }

    init(id: Int) {
        book = id / 1_000_000
        chapter = (id / 1_000) % 1_000
        verse = id % 1_000
    }

    static func < (lhs: VerseRef, rhs: VerseRef) -> Bool { lhs.id < rhs.id }
}

Why an integer and not a string like "JHN.3.16"? It sorts correctly, ranges are cheap (BETWEEN 43003001 AND 43003999 is "all of John 3"), and it's a compact key in both SQLite and Core Data. A highlight saved against 43003016 shows up in KJV and in World English alike, because the ID describes the position, not the wording.

One caveat from experience: versification isn't identical in every tradition. A few translations number some verses differently. If you add a translation that disagrees, map it onto your canonical scheme when you build the database, never at runtime.

3. Shipping the text as a bundled, read-only SQLite database

I build the text database offline with a script, add bible.sqlite to the app target and open it read-only straight from the bundle. No copying to Documents, no migrations, no risk of corruption.

The schema is tiny:

CREATE TABLE verses (
  translation TEXT NOT NULL,   -- 'KJV', 'ASV', 'WEB', ...
  id          INTEGER NOT NULL, -- VerseRef.id
  text        TEXT NOT NULL,
  PRIMARY KEY (translation, id)
) WITHOUT ROWID;

-- Full-text index (built by the script, shipped in the file)
CREATE VIRTUAL TABLE verses_fts USING fts5(
  text, translation UNINDEXED, id UNINDEXED,
  tokenize = 'unicode61 remove_diacritics 2'
);

Opening it from Swift with the system SQLite library:

import Foundation
import SQLite3

enum TextStoreError: Error { case openFailed(String), queryFailed(String) }

final class BibleTextStore {
    private var db: OpaquePointer?

    init() throws {
        guard let url = Bundle.main.url(forResource: "bible", withExtension: "sqlite") else {
            throw TextStoreError.openFailed("bible.sqlite missing from bundle")
        }
        // immutable=1 tells SQLite the file can never change, so it skips locking.
        let uri = "file:\(url.path)?immutable=1"
        let flags = SQLITE_OPEN_READONLY | SQLITE_OPEN_URI
        guard sqlite3_open_v2(uri, &db, flags, nil) == SQLITE_OK else {
            throw TextStoreError.openFailed(String(cString: sqlite3_errmsg(db)))
        }
    }

    deinit { sqlite3_close(db) }

    func chapter(_ book: Int, _ chapter: Int, translation: String) throws -> [(VerseRef, String)] {
        let sql = "SELECT id, text FROM verses WHERE translation = ? AND id BETWEEN ? AND ? ORDER BY id"
        var stmt: OpaquePointer?
        guard sqlite3_prepare_v2(db, sql, -1, &stmt, nil) == SQLITE_OK else {
            throw TextStoreError.queryFailed(String(cString: sqlite3_errmsg(db)))
        }
        defer { sqlite3_finalize(stmt) }

        let start = VerseRef(book: book, chapter: chapter, verse: 0).id
        sqlite3_bind_text(stmt, 1, translation, -1, SQLITE_TRANSIENT)
        sqlite3_bind_int64(stmt, 2, Int64(start))
        sqlite3_bind_int64(stmt, 3, Int64(start + 999))

        var rows: [(VerseRef, String)] = []
        while sqlite3_step(stmt) == SQLITE_ROW {
            let id = Int(sqlite3_column_int64(stmt, 0))
            let text = String(cString: sqlite3_column_text(stmt, 1))
            rows.append((VerseRef(id: id), text))
        }
        return rows
    }
}

// The C macro SQLITE_TRANSIENT doesn't import into Swift; this is the usual stand-in.
private let SQLITE_TRANSIENT = unsafeBitCast(-1, to: sqlite3_destructor_type.self)

Why raw SQLite and not Core Data for the text? Core Data is great for object graphs you edit. A read-only corpus with a full-text index is a different job, and SQLite's FTS5 does that job directly. You can wrap this in GRDB or another library if you prefer; the shape doesn't change.

4. Search that feels instant

The listing promises "Search across all books, chapters, and verses" and "Advanced search with history". With an FTS5 index shipped in the file, the query is one statement:

extension BibleTextStore {
    struct Hit { let ref: VerseRef; let snippet: String }

    func search(_ query: String, translation: String, limit: Int = 100) throws -> [Hit] {
        // Turn "love one another" into "love* one* another*": prefix match on every word.
        let terms = query
            .split(whereSeparator: { !$0.isLetter && !$0.isNumber })
            .map { "\($0)*" }
            .joined(separator: " ")
        guard !terms.isEmpty else { return [] }

        let sql = """
        SELECT id, snippet(verses_fts, 0, '[', ']', '…', 12)
        FROM verses_fts
        WHERE verses_fts MATCH ? AND translation = ?
        ORDER BY rank LIMIT ?
        """
        var stmt: OpaquePointer?
        guard sqlite3_prepare_v2(db, sql, -1, &stmt, nil) == SQLITE_OK else {
            throw TextStoreError.queryFailed(String(cString: sqlite3_errmsg(db)))
        }
        defer { sqlite3_finalize(stmt) }
        sqlite3_bind_text(stmt, 1, terms, -1, SQLITE_TRANSIENT)
        sqlite3_bind_text(stmt, 2, translation, -1, SQLITE_TRANSIENT)
        sqlite3_bind_int(stmt, 3, Int32(limit))

        var hits: [Hit] = []
        while sqlite3_step(stmt) == SQLITE_ROW {
            hits.append(Hit(ref: VerseRef(id: Int(sqlite3_column_int64(stmt, 0))),
                            snippet: String(cString: sqlite3_column_text(stmt, 1))))
        }
        return hits
    }
}

A few things that matter more than the SQL:

Sanitise the query. FTS5 has its own query syntax; a stray quote or hyphen from the user can cause a syntax error. Splitting on non-alphanumerics and rebuilding the string, as above, avoids that.
Debounce in the UI. Search on every keystroke, but cancel the previous task. A .task(id: query) modifier in SwiftUI with a short Task.sleep at the top gives you that for free.
Run it off the main thread. It's fast, but "fast" on an older iPhone in Low Power Mode isn't the same as on your desk.
Search history is user data, so it goes in the user store (next section), not the read-only file.

5. User data: Core Data with CloudKit mirroring

The listing says "iCloud sync across all your devices… Access your highlights, notes, and bookmarks anywhere". The app supports iOS 16.0 and later, which rules out SwiftData (iOS 17+). The natural fit is NSPersistentCloudKitContainer (iOS 13+), which keeps a normal local Core Data store and mirrors it to the user's private CloudKit database in the background.

That's exactly the offline-first behaviour you want: every write goes to the local store first and works with no network; sync catches up later.

import CoreData

final class UserStore {
    static let shared = UserStore()
    let container: NSPersistentCloudKitContainer

    private init() {
        container = NSPersistentCloudKitContainer(name: "UserData") // UserData.xcdatamodeld

        guard let description = container.persistentStoreDescriptions.first else {
            fatalError("No store description")
        }
        description.cloudKitContainerOptions =
            NSPersistentCloudKitContainerOptions(containerIdentifier: "iCloud.com.example.bible")
        // Needed so the app can react to changes that arrive from other devices.
        description.setOption(true as NSNumber, forKey: NSPersistentHistoryTrackingKey)
        description.setOption(true as NSNumber,
                              forKey: NSPersistentStoreRemoteChangeNotificationPostOptionKey)

        container.loadPersistentStores { _, error in
            if let error { print("Store failed to load: \(error)") }
        }
        container.viewContext.automaticallyMergesChangesFromParent = true
        container.viewContext.mergePolicy = NSMergeByPropertyObjectTrumpMergePolicy
    }
}

The Highlight entity is deliberately boring: verseID (Integer 64), translation (String, optional), colorName (String), createdAt (Date) and a UUID id. A few CloudKit rules shape that model, and they catch everyone once:

Every attribute must be optional or have a default value. CloudKit can deliver records in any order and partially.
No unique constraints. CloudKit mirroring doesn't support them. If the user highlights the same verse on two offline devices, you'll get two rows; de-duplicate in code (keep the newest per verseID).
Relationships must be optional and need inverses.
Enable the capabilities: iCloud with CloudKit and your container, plus Background Modes → Remote notifications, so pushes from CloudKit can wake the app to sync.
Deploy the schema to production in the CloudKit Console before you ship. A development schema works on your device and silently fails for users. During development, initializeCloudKitSchema(options:) can create the schema from your model for you.

Saving a highlight is then plain Core Data:

extension UserStore {
    func toggleHighlight(_ ref: VerseRef, color: String) throws {
        let context = container.viewContext
        let request = NSFetchRequest<NSManagedObject>(entityName: "Highlight")
        request.predicate = NSPredicate(format: "verseID == %lld", Int64(ref.id))

        let existing = try context.fetch(request)
        if existing.isEmpty {
            let h = NSEntityDescription.insertNewObject(forEntityName: "Highlight", into: context)
            h.setValue(UUID(), forKey: "id")
            h.setValue(Int64(ref.id), forKey: "verseID")
            h.setValue(color, forKey: "colorName")
            h.setValue(Date(), forKey: "createdAt")
        } else {
            existing.forEach(context.delete) // also cleans up offline duplicates
        }
        try context.save()
    }
}

On the reading screen, fetch highlights for the chapter's ID range and merge them with the verse rows from SQLite in a view model. The two stores never need to know about each other.

6. Listen mode with AVSpeechSynthesizer

The listing's "Listen & Read" section mentions text-to-speech and auto-scroll. On iOS that's AVSpeechSynthesizer (iOS 7+), and its delegate tells you which range of text is about to be spoken, which is all you need to highlight and scroll along.

import AVFoundation

@MainActor
final class ReadAloud: NSObject, ObservableObject, AVSpeechSynthesizerDelegate {
    @Published var currentVerse: VerseRef?
    private let synth = AVSpeechSynthesizer()
    private var refs: [ObjectIdentifier: VerseRef] = [:]

    override init() {
        super.init()
        synth.delegate = self
    }

    func speak(chapter verses: [(VerseRef, String)], language: String = "en-US") {
        synth.stopSpeaking(at: .immediate)
        refs = [:]
        for (ref, text) in verses {
            let u = AVSpeechUtterance(string: text)
            u.voice = AVSpeechSynthesisVoice(language: language)
            u.rate = AVSpeechUtteranceDefaultSpeechRate
            u.postUtteranceDelay = 0.15        // a breath between verses
            refs[ObjectIdentifier(u)] = ref
            synth.speak(u)                     // utterances are queued in order
        }
    }

    func pause() { synth.pauseSpeaking(at: .word) }
    func resume() { synth.continueSpeaking() }

    nonisolated func speechSynthesizer(_ s: AVSpeechSynthesizer,
                                       didStart utterance: AVSpeechUtterance) {
        let key = ObjectIdentifier(utterance)
        Task { @MainActor in
            self.currentVerse = self.refs[key]
        }
    }
}

The view observes currentVerse and calls ScrollViewReader.scrollTo(_:anchor:) with the verse ID. For word-level highlighting, implement speechSynthesizer(_:willSpeakRangeOfSpeechString:utterance:) as well.

Two practical notes. If you want speech to continue with the screen locked ("perfect for listening while commuting"), set the audio session category to .playback and add the audio background mode, and only while speech is actually running. And the voices available vary by device and by what the user has downloaded in Settings, so let them pick, and fall back gracefully when AVSpeechSynthesisVoice(language:) returns nil.

7. Verse of the Day on the Home Screen with WidgetKit

The listing has "Home screen widgets: quick access to verse of the day". A widget runs in its own extension process, so it can't reach into the app's memory. Two things make this simple with the architecture above:

The text database is read-only and in the bundle, so the widget extension can ship its own copy (or you can share it through an App Group container). No sync needed.
The verse of the day is a deterministic function of the date. Every device shows the same verse without a server.

import WidgetKit
import SwiftUI

struct VerseEntry: TimelineEntry {
    let date: Date
    let reference: String
    let text: String
}

struct VerseProvider: TimelineProvider {
    func placeholder(in context: Context) -> VerseEntry {
        VerseEntry(date: .now, reference: "John 3:16", text: "For God so loved the world…")
    }

    func getSnapshot(in context: Context, completion: @escaping (VerseEntry) -> Void) {
        completion(entry(for: .now))
    }

    func getTimeline(in context: Context, completion: @escaping (Timeline<VerseEntry>) -> Void) {
        let now = Date()
        let tomorrow = Calendar.current.startOfDay(for: now.addingTimeInterval(86_400))
        completion(Timeline(entries: [entry(for: now)], policy: .after(tomorrow)))
    }

    private func entry(for date: Date) -> VerseEntry {
        // Pick from a curated list by day-of-year: same verse for everyone, every device.
        let day = Calendar.current.ordinality(of: .day, in: .year, for: date) ?? 1
        let pick = DailyVerses.list[(day - 1) % DailyVerses.list.count]
        return VerseEntry(date: date, reference: pick.reference, text: pick.text)
    }
}

struct VerseOfTheDayWidget: Widget {
    var body: some WidgetConfiguration {
        StaticConfiguration(kind: "VerseOfTheDay", provider: VerseProvider()) { entry in
            VStack(alignment: .leading, spacing: 6) {
                Text(entry.text).font(.callout).lineLimit(5)
                Text(entry.reference).font(.caption).foregroundStyle(.secondary)
            }
            .containerBackground(.fill.tertiary, for: .widget) // iOS 17+
        }
        .configurationDisplayName("Verse of the Day")
        .supportedFamilies([.systemSmall, .systemMedium])
    }
}

DailyVerses.list is a small curated array compiled into the extension. With an iOS 16 deployment target, wrap containerBackground in an availability check, since that modifier is iOS 17+. The .after(tomorrow) policy asks WidgetKit to refresh just after midnight. It's a request, not a guarantee, so the entry should still read correctly if WidgetKit refreshes a bit late.

8. Real-world example: Bible Study AI – Read Offline

All of this comes from building and maintaining my own app, Bible Study AI – Read Offline. The patterns above are the approach I'd use and recommend; I'm describing the architecture, not giving a line-by-line tour of the shipping code.

At the time of writing, its public App Store listing shows:

Free, in the Books and Education categories
First released in April 2020: my first app on the store
113 ratings in the US store, averaging about 4.6 stars
Supports iOS 16.0 and later, on iPhone and iPad

Here's how the listing's features map to the sections above:

What the listing says	Where it's covered
"Read all 66 books of the Bible offline" / "Multiple translations: KJV, ASV, Webster, World English, and more"	Bundled read-only SQLite, one table keyed by translation + verse ID (sections 2–3)
"Search across all books, chapters, and verses" / "Advanced search with history"	FTS5 index shipped in the file, sanitised prefix queries (section 4)
"Highlight verses with multiple colors" / "Add personal notes" / "Bookmark favorite passages"	Small Core Data entities keyed by verse ID (section 5)
"iCloud sync across all your devices"	`NSPersistentCloudKitContainer` mirroring to the private database (section 5)
"Text-to-speech support" / "Auto-scroll for hands-free reading"	`AVSpeechSynthesizer` and its delegate driving the scroll position (section 6)
"Home screen widgets: quick access to verse of the day"	WidgetKit `StaticConfiguration`, date-derived entry (section 7)

The listing also covers reading plans, daily devotionals, a prayer journal with reminders and a "Bible Study Assistant" for AI-powered answers. Those all sit on top of the same split: plan progress and prayers are user data in the synced store, reminders are local notifications, and the assistant is the one feature that needs a network. I've left the AI part out of this article on purpose. It's the one piece that isn't offline, and the most important design rule there is simply to make sure the rest of the app never waits on it.

9. Before you ship an offline-first reader: a checklist

Airplane-mode test from a fresh install. Delete the app, turn on Airplane Mode, install from TestFlight… then read, search, highlight, take a note and listen. Everything except network features must work.
Text and user data are separate. The corpus is read-only in the bundle; user data lives in its own store. An app update that changes the text never touches user data.
Stable IDs everywhere. Every highlight, note and bookmark points at a canonical verse ID, never at a row number or a translation-specific string.
The CloudKit model follows the rules. Optional attributes or defaults, no unique constraints, optional relationships with inverses, and the schema is deployed to production.
Duplicates are handled. Two offline devices editing the same verse produce two records; your code merges them predictably.
Search can't crash on user input. Quotes, hyphens, emoji and other scripts are all tested against your FTS query builder.
Background audio is honest. The audio mode is used only while read-aloud is playing, and the session is deactivated when it stops.
The widget works with no app launch. Install, add the widget, never open the app: it should still show a verse.

Wrapping up

Offline-first sounds like a constraint, but for a reading app it makes things simpler. A read-only database in the bundle can't be corrupted and never needs migrating. A small, separate user store syncs cheaply. And a verse ID that never changes ties the two together. Add AVSpeechSynthesizer and WidgetKit and you get most of what people want from a daily reading app, without a single required network call.

If you want to see where this ended up, try the app:

Bible Study AI – Read Offline (iOS): https://apps.apple.com/us/app/bible-study-ai-read-offline/id1508795537
All of my free iOS apps: https://apps.apple.com/us/developer/alok-singh/id1508795536
My portfolio: https://bestlatestapps.com/alok/

If you've built a large offline corpus on iOS and solved sync or search differently, tell me in the comments. I'm always curious how other people draw the line between "bundled" and "user" data.

— Alok Kumar Singh

Originally published at https://bestlatestapps.com/blog/building-an-offline-first-bible-reader-on-ios/

Convert-As-You-Type Currency Conversion in Swift: Decimal Maths, Cached Rates and Formatting

Sun, 25 Oct 2026 12:40:42 +0000

Originally published at https://bestlatestapps.com/blog/convert-as-you-type-currency-conversion-in-swift/

Why Double is the wrong type for money, how to derive any cross rate from one base, keeping rates fresh without a refresh button, and formatting 150+ currencies correctly

A currency converter is used at the worst possible moments: at a market stall abroad, at a checkout page in another currency, in a taxi with a meter running. Nobody wants to tap "Convert". Nobody wants a spinner. And nobody wants to see 0.30000000000000004 on the screen.

Currency Converter : Fast is one of my first apps, published in April 2020. Its listing describes the whole philosophy in a few lines: 150+ currencies, "converts as you type (no need for a 'Convert' button!)", exchange rates "updated automatically — you don't have to do anything!", and 3 decimal places "for greater accuracy".

Each of those promises maps onto a specific technical decision: the number type, the rate model, caching and refresh, and formatting. This article goes through how I'd build each one in Swift. API names and availability are checked against Apple's documentation. I describe the approach I'd use rather than the app's internals, and I deliberately don't name a rate provider: the listing doesn't, and the design is the same whichever one you use.

1. Money is not a Double

Binary floating point can't represent most decimal fractions exactly. 0.1 + 0.2 isn't 0.3, and after a few multiplications by exchange rates, the error shows up in exactly the decimal places you're displaying.

Foundation's Decimal is a base-10 number type, so 0.1 really is 0.1:

import Foundation

let a: Double = 0.1 + 0.2
print(a)                                  // 0.30000000000000004

let b = Decimal(string: "0.1")! + Decimal(string: "0.2")!
print(b)                                  // 0.3

The rule I follow: amounts and rates are Decimal from the moment they enter the app, whether that's the user's typing or the JSON from the rates API, until the moment they're formatted for display. Two gotchas:

Decimal(0.1) converts from a Double, so the binary error comes with it. Initialise from strings: Decimal(string:locale:).
JSONDecoder decodes Decimal fields via Double internally on some systems, which can reintroduce error in the last digits. If exactness matters, decode rates as Strings and convert them yourself, as below.

2. One base, every cross rate

You don't need a 150 × 150 table. Fetch every currency's rate against one base (say USD), and derive any pair:

amount_in_B = amount_in_A × (rate_B / rate_A)       where rate_X = units of X per 1 base

import Foundation

struct RateTable: Codable {
    let base: String                     // "USD"
    let rates: [String: Decimal]         // "EUR": 0.92 means 1 USD = 0.92 EUR
    let fetchedAt: Date

    func rate(from: String, to: String) -> Decimal? {
        guard let a = from == base ? 1 : rates[from],
              let b = to == base ? 1 : rates[to],
              a != 0 else { return nil }
        return b / a
    }

    func convert(_ amount: Decimal, from: String, to: String) -> Decimal? {
        rate(from: from, to: to).map { amount * $0 }
    }
}

// Decode rates exactly: the API sends numbers, but we read them as strings first.
struct RatesResponse: Decodable {
    let base: String
    let rates: [String: Decimal]

    private enum CodingKeys: String, CodingKey { case base, rates }

    init(from decoder: Decoder) throws {
        let c = try decoder.container(keyedBy: CodingKeys.self)
        base = try c.decode(String.self, forKey: .base)
        // Assumes the provider sends rates as JSON strings; if it sends numbers,
        // decode [String: Double] and convert via "\(value)" to limit binary error.
        let raw = try c.decode([String: String].self, forKey: .rates)
        rates = raw.compactMapValues { Decimal(string: $0, locale: Locale(identifier: "en_US_POSIX")) }
    }
}

RateTable.rate(from:to:) is also how you show "the current exchange rate of what you're converting", one of the listing's features: 1 EUR = 1.087 USD, computed from the same table.

Note the en_US_POSIX locale when parsing API data. API numbers always use . as the decimal separator, whatever the user's device language is.

3. Convert as you type

With Decimal maths and a local rate table, conversion is instant and synchronous. There's no reason for a button. In SwiftUI:

import SwiftUI

@MainActor
final class ConverterModel: ObservableObject {
    @Published var input = ""
    @Published var from = "USD"
    @Published var to = "EUR"
    @Published private(set) var table: RateTable?

    private let parser: NumberFormatter = {
        let f = NumberFormatter()
        f.numberStyle = .decimal
        f.generatesDecimalNumbers = true   // parse straight to NSDecimalNumber, never via Double
        f.isLenient = true
        return f
    }()

    var amount: Decimal? {
        (parser.number(from: input) as? NSDecimalNumber)?.decimalValue
    }

    var result: Decimal? {
        guard let amount, let table else { return nil }
        return table.convert(amount, from: from, to: to)
    }

    func swap() { (from, to) = (to, from) }
}

struct ConverterView: View {
    @StateObject private var model = ConverterModel()

    var body: some View {
        Form {
            Section {
                TextField("Amount", text: $model.input)
                    .keyboardType(.decimalPad)
                    .font(.largeTitle.monospacedDigit())
                CurrencyPicker(title: "From", code: $model.from)
            }
            Section {
                Text(model.result.map { CurrencyText.format($0, code: model.to) } ?? "—")
                    .font(.largeTitle.monospacedDigit())
                    .contentTransition(.numericText())          // iOS 17: digits roll smoothly
                    .animation(.snappy, value: model.result)
                CurrencyPicker(title: "To", code: $model.to)
            }
            Button("Swap", systemImage: "arrow.up.arrow.down", action: model.swap)
        }
    }
}

Because result is a computed property, every keystroke recomputes it: there's no debounce and no task. CurrencyPicker is a searchable list of codes (section 5).

The decimal-pad keyboard shows the user's locale separator, and the NumberFormatter uses Locale.current by default, so "12,50" in Germany and "12.50" in the US both parse.

4. Rates that update themselves, and work offline

"Exchange rates are updated automatically" has three parts: a cache that's always there, a refresh when the app comes to the foreground, and an occasional refresh in the background.

import Foundation

actor RateStore {
    static let shared = RateStore()
    private let fileURL: URL = FileManager.default
        .urls(for: .cachesDirectory, in: .userDomainMask)[0]
        .appendingPathComponent("rates.json")
    private let maxAge: TimeInterval = 60 * 60          // refresh if older than an hour

    /// Always returns something if we've ever succeeded, even offline.
    func cached() -> RateTable? {
        guard let data = try? Data(contentsOf: fileURL) else { return nil }
        return try? JSONDecoder().decode(RateTable.self, from: data)
    }

    func refreshIfStale(force: Bool = false) async -> RateTable? {
        if !force, let c = cached(), Date().timeIntervalSince(c.fetchedAt) < maxAge { return c }
        do {
            var request = URLRequest(url: URL(string: "https://rates.example.com/latest?base=USD")!)
            request.timeoutInterval = 10
            let (data, response) = try await URLSession.shared.data(for: request)
            guard (response as? HTTPURLResponse)?.statusCode == 200 else { return cached() }
            let decoded = try JSONDecoder().decode(RatesResponse.self, from: data)
            let table = RateTable(base: decoded.base, rates: decoded.rates, fetchedAt: Date())
            try JSONEncoder().encode(table).write(to: fileURL, options: .atomic)
            return table
        } catch {
            return cached()                                   // offline or failed: keep the last good table
        }
    }
}

Key behaviours:

Show the cache immediately, then refresh. The UI never waits on the network.
On failure, keep the last good table. A slightly old rate is far more useful than an error screen at a market stall.
Show the age. "Rates updated 3 hours ago" in small text is honest, and it's the one piece of UI that explains a surprising number.
Bundle a seed table in the app, so a first launch in Airplane Mode still converts. Label it with its date.

For background refresh, SwiftUI's backgroundTask(_:action:) scene modifier (iOS 16+) with .appRefresh pairs with BGAppRefreshTaskRequest (iOS 13+):

import SwiftUI
import BackgroundTasks

@main
struct CurrencyApp: App {
    @Environment(\.scenePhase) private var phase

    var body: some Scene {
        WindowGroup { ConverterView() }
            .onChange(of: phase) { _, newPhase in
                if newPhase == .active { Task { _ = await RateStore.shared.refreshIfStale() } }
                if newPhase == .background { scheduleRefresh() }
            }
            .backgroundTask(.appRefresh("rates.refresh")) {
                _ = await RateStore.shared.refreshIfStale(force: true)
                scheduleRefresh()
            }
    }
}

func scheduleRefresh() {
    let request = BGAppRefreshTaskRequest(identifier: "rates.refresh")
    request.earliestBeginDate = Date(timeIntervalSinceNow: 4 * 60 * 60)
    try? BGTaskScheduler.shared.submit(request)
}

Add rates.refresh to BGTaskSchedulerPermittedIdentifiers in Info.plist and enable Background Modes → Background fetch. Remember that earliestBeginDate is a floor, not a schedule: the system decides when, based on how the user actually uses the app. The foreground refresh is what really keeps rates fresh.

5. 150+ currencies: names, symbols and decimals

Foundation knows a great deal about currencies, so you don't have to maintain that list by hand:

import Foundation

struct CurrencyInfo: Identifiable, Hashable {
    let code: String
    var id: String { code }
    var name: String { Locale.current.localizedString(forCurrencyCode: code) ?? code }
}

enum CurrencyCatalog {
    /// Intersect what the rates API supports with what Foundation can name.
    static func available(in table: RateTable) -> [CurrencyInfo] {
        let common = Set(Locale.commonISOCurrencyCodes)          // iOS 16+
        return (Array(table.rates.keys) + [table.base])
            .filter(common.contains)
            .map(CurrencyInfo.init)
            .sorted { $0.name.localizedCompare($1.name) == .orderedAscending }
    }
}

enum CurrencyText {
    /// Three decimals, as the listing promises, with the locale's grouping and symbol.
    static func format(_ value: Decimal, code: String) -> String {
        value.formatted(.currency(code: code).precision(.fractionLength(3)))
    }
}

// CurrencyText.format(1234.5678, code: "EUR") → "€1,234.568" in en_US, "1.234,568 €" in de_DE

localizedString(forCurrencyCode:) gives "Colombian Peso" in English and "Peso colombiano" in Spanish for free. Decimal.FormatStyle.Currency (iOS 15+) handles the symbol, its position, grouping and the decimal separator for the user's locale.

About three decimal places: most currencies have two minor units, some have zero (JPY, KRW) and a few have three (KWD, BHD). Showing three everywhere is a deliberate product choice. It gives more precision on small amounts and on the exchange rate itself. If you'd rather respect each currency's standard, use .precision(.fractionLength(0...3)) with rounding, or read the currency's default fraction digits from a NumberFormatter set to .currency style.

Make the picker searchable by code and by name (.searchable(text:)), and put recently used currencies at the top. Most people convert between the same two or three currencies over and over.

6. Real-world example: Currency Converter : Fast

This is the approach I'd use, and recommend, for Currency Converter : Fast.

At the time of writing, its App Store listing shows:

Free, in Finance and Productivity
First released in April 2020
7 ratings in the US store, averaging about 4.7 stars
Supports iOS 17.6 and later

How the listing's features map to this article:

What the listing says	Where it's covered
"Over 150 currencies supported" / "from the US Dollar to the Colombian Peso"	One-base rate table plus Foundation's currency names (sections 2, 5)
"Converts as you type (no need for a 'Convert' button!)"	Synchronous `Decimal` conversion as a computed property (section 3)
"Exchange rates are updated automatically – you don't have to do anything!"	Cache-first store, foreground refresh, background app refresh (section 4)
"Uses 3 decimal places for greater accuracy!"	`Decimal` maths and `.precision(.fractionLength(3))` (sections 1, 5)
"Find the current exchange rate of what you're converting"	`RateTable.rate(from:to:)` (section 2)

Because the app targets iOS 17.6 and later, everything above, including contentTransition(.numericText()), the two-parameter onChange and the SwiftUI background task, is available without availability checks.

7. Before you ship a currency converter: a checklist

Decimal end to end. No Double between parsing and formatting, and no Decimal(someDouble).
API numbers are parsed with en_US_POSIX, and user input with the user's locale.
Cross rates come from one base. Test that A → B → A returns the original amount, within rounding.
The cache is shown first. Launch in Airplane Mode: you see the last rates and their age, not an error.
A seed table ships in the bundle for first-launch offline use.
Background refresh is configured (permitted identifiers, background mode), and foreground refresh does the real work.
Formatting is tested in several locales: en_US, de_DE, fr_FR, ja_JP and ar, at least.
Zero-decimal and three-decimal currencies look right, according to your product decision.
Rates are labelled honestly. These are indicative mid-market-style rates, not what a bank or card will charge.

Wrapping up

The "fast" in a fast currency converter isn't about network speed. It's about never needing the network at the moment of use. Keep money in Decimal, derive every pair from one cached base table, refresh quietly in the foreground and background, and let Foundation handle names, symbols and locale formatting. The result converts as you type, anywhere, even in Airplane Mode.

Try it, or explore my other apps:

Currency Converter : Fast (iOS): https://apps.apple.com/us/app/currency-converter-fast/id1509291290
All of my free iOS apps: https://apps.apple.com/us/developer/alok-singh/id1508795536
My portfolio: https://bestlatestapps.com/alok/

How do you handle money in Swift: Decimal, integer minor units, or a library? I'd love to hear the trade-offs you've found in the comments.

— Alok Kumar Singh

Originally published at https://bestlatestapps.com/blog/convert-as-you-type-currency-conversion-in-swift/

Drag-to-Connect and Game Center Leaderboards in a SwiftUI Puzzle Game, Updated for iOS 26

Sun, 25 Oct 2026 12:40:22 +0000

Originally published at https://bestlatestapps.com/blog/drag-to-connect-and-game-center-leaderboards-in-a-swiftui-puzzle-game/

A dot-matching board drawn with Canvas and TimelineView, drag gestures that chain same-colour dots, speed-based scoring and rising difficulty, pause and resume, and modern Game Center: authentication, submitting scores, the access point, and what iOS 26 deprecates

Speck Match is a puzzle game about speed. You tap and drag to connect matching coloured dots and clear them from the board, and the faster you match, the higher your score. New dots appear faster as you play, until the board is crowded and you're racing to keep up. Then you see where you rank on Game Center leaderboards against players worldwide.

I wrote about tap-based gameplay in SpriteKit in my Marbles Popperz article. Speck Match lets me cover two different things. The first is a drag-to-connect mechanic built entirely in SwiftUI, with Canvas and TimelineView instead of a game engine. The second is Game Center leaderboards in depth, which have changed more in the last few iOS releases than most developers realise. The latest change: Apple's documentation now marks GKGameCenterViewController as deprecated in iOS 26.

As always, the code is written for this article and checked against Apple's documentation. Gameplay rules beyond what the App Store listing says are labelled as the approach I'd use.

1. The board as plain data

Keep the game state free of SwiftUI, so you can unit-test it:

import Foundation
import CoreGraphics

enum SpeckColor: CaseIterable { case coral, mint, sky, lemon, violet }

struct Speck: Identifiable, Equatable {
    let id = UUID()
    var color: SpeckColor
    var position: CGPoint
    let bornAt: TimeInterval            // game time when it appeared, used for speed scoring
    static let radius: CGFloat = 18
}

struct Board {
    var specks: [Speck] = []
    var score = 0
    var elapsed: TimeInterval = 0       // game time only; doesn't advance while paused
    var nextSpawn: TimeInterval = 0
    var difficulty: Difficulty

    /// Seconds between new specks: starts relaxed, tightens as you play.
    var spawnInterval: TimeInterval {
        max(difficulty.minInterval, difficulty.startInterval - elapsed * difficulty.ramp)
    }

    var isOverfull: Bool { specks.count >= difficulty.maxSpecks }
}

struct Difficulty {
    let startInterval: TimeInterval, minInterval: TimeInterval, ramp: Double
    let maxSpecks: Int, colors: Int
    static let easy   = Difficulty(startInterval: 1.4, minInterval: 0.55, ramp: 0.004, maxSpecks: 40, colors: 3)
    static let normal = Difficulty(startInterval: 1.1, minInterval: 0.40, ramp: 0.006, maxSpecks: 36, colors: 4)
    static let hard   = Difficulty(startInterval: 0.9, minInterval: 0.28, ramp: 0.008, maxSpecks: 32, colors: 5)
}

"The game gets faster and more challenging as you progress" becomes one computed property, spawnInterval, and "Multiple difficulty levels" becomes three rows of numbers. The values are illustrative; tune them by playing.

2. Drawing and ticking with Canvas and TimelineView

For a few dozen circles, SwiftUI's Canvas (iOS 15+) is fast and simple. It's immediate-mode drawing, so you're not creating one view per dot. TimelineView(.animation(minimumInterval:paused:)) (iOS 15+) gives you a frame clock that can be paused, which matters later:

import SwiftUI

struct BoardView: View {
    @State private var game = GameModel(difficulty: .normal)
    @Environment(\.scenePhase) private var scenePhase

    var body: some View {
        TimelineView(.animation(minimumInterval: 1.0 / 60, paused: game.isPaused)) { timeline in
            Canvas { context, size in
                for speck in game.board.specks {
                    let rect = CGRect(x: speck.position.x - Speck.radius, y: speck.position.y - Speck.radius,
                                      width: Speck.radius * 2, height: Speck.radius * 2)
                    context.fill(Path(ellipseIn: rect), with: .color(speck.color.swiftUIColor))
                }
                if game.chain.count > 1 {                       // the line you're drawing
                    var path = Path()
                    path.addLines(game.chain.compactMap { id in game.board.specks.first { $0.id == id }?.position })
                    context.stroke(path, with: .color(.white.opacity(0.8)), lineWidth: 6)
                }
            }
            .onChange(of: timeline.date) { _, now in game.tick(now: now) }
        }
        .gesture(dragGesture)
        .onChange(of: scenePhase) { _, phase in if phase != .active { game.pause() } }
    }
}

This code uses iOS 17 conveniences (@Observable and the two-parameter onChange). For the app's iOS 15.6 minimum, the same model works as an ObservableObject with the single-parameter onChange(of:perform:). Two more notes. Keep tick cheap: spawn when due, check the overfull condition, and nothing else. And auto-pause when the scene leaves .active. A phone call shouldn't cost a player their best run, and the listing promises "Pause and resume anytime".

3. Drag to connect

The listing's core loop is "Tap and drag dots to match them by color. Connect matching colored dots to clear them from the board." The approach I'd use: touching down on a dot starts a chain. Dragging over another dot of the same colour, close enough to the last one in the chain, adds it. Lifting your finger clears the chain if it has at least two dots.

@Observable
final class GameModel {
    var board: Board
    var chain: [UUID] = []
    var isPaused = false
    private var lastTick: Date?

    init(difficulty: Difficulty) { board = Board(difficulty: difficulty) }

    func speck(at point: CGPoint) -> Speck? {
        board.specks.first { hypot($0.position.x - point.x, $0.position.y - point.y) <= Speck.radius * 1.4 }
    }

    func dragChanged(to point: CGPoint) {
        guard !isPaused, let hit = speck(at: point) else { return }
        if chain.isEmpty { chain = [hit.id]; return }
        guard let first = board.specks.first(where: { $0.id == chain[0] }),
              hit.color == first.color, !chain.contains(hit.id) else {
            // Dragging back onto the previous dot undoes the last link, like most connect games.
            if chain.count >= 2, hit.id == chain[chain.count - 2] { chain.removeLast() }
            return
        }
        chain.append(hit.id)
    }

    func pause() { isPaused = true; lastTick = nil }
    func resume() { isPaused = false }

    func tick(now: Date) {
        defer { lastTick = now }
        guard !isPaused, let last = lastTick else { return }
        board.elapsed += min(now.timeIntervalSince(last), 0.05)     // clamp hitches and resumes
        if board.elapsed >= board.nextSpawn {
            spawn()
            board.nextSpawn = board.elapsed + board.spawnInterval
        }
        if board.isOverfull { pause() /* game over: submit score, show results */ }
    }

    private func spawn() {
        let palette = Array(SpeckColor.allCases.prefix(board.difficulty.colors))
        board.specks.append(Speck(color: palette.randomElement()!,
                                  position: CGPoint(x: .random(in: 30...360), y: .random(in: 120...700)),
                                  bornAt: board.elapsed))
    }

    func dragEnded() {
        defer { chain = [] }
        guard chain.count >= 2 else { return }
        let cleared = board.specks.filter { chain.contains($0.id) }
        board.specks.removeAll { chain.contains($0.id) }
        board.score += Scoring.points(for: cleared, now: board.elapsed)
    }
}

extension BoardView {
    var dragGesture: some Gesture {
        DragGesture(minimumDistance: 0)                 // 0 so a touch-down starts the chain immediately
            .onChanged { game.dragChanged(to: $0.location) }
            .onEnded { _ in game.dragEnded() }
    }
}

DragGesture(minimumDistance: 0) is the important detail. The default minimum distance means the first few points of a drag are swallowed, which feels laggy in a speed game. Make the hit radius a bit larger than the drawn dot (1.4× here). Fingers are bigger than dots, and fair hit areas are most of what "Smooth, responsive controls" means in practice.

4. Scoring speed

"Speed matters – faster matches = higher scores." There are many ways to express that. The approach I'd use rewards how fresh the dots were when you cleared them, plus a bonus for longer chains:

enum Scoring {
    /// Each dot: 10 points, plus up to 10 more if cleared within 3 seconds of appearing.
    /// Chains: +25% per dot beyond two.
    static func points(for specks: [Speck], now: TimeInterval) -> Int {
        let perDot = specks.map { speck -> Double in
            let age = now - speck.bornAt
            let freshness = max(0, 1 - age / 3)           // 1.0 when brand new, 0 after 3 s
            return 10 + 10 * freshness
        }
        let chainBonus = 1 + 0.25 * Double(max(0, specks.count - 2))
        return Int((perDot.reduce(0, +) * chainBonus).rounded())
    }
}

The bornAt timestamp uses game time (board.elapsed), not wall-clock time. Otherwise pausing would make every dot on screen "old", and the player would be punished for taking a break.

5. Signing in to Game Center

Leaderboards start with authentication. On iOS, you set GKLocalPlayer.local.authenticateHandler once, early. GameKit calls it, possibly more than once, with either a view controller to present or the result:

import GameKit
import UIKit

@MainActor
final class GameCenter: ObservableObject {
    @Published private(set) var isAuthenticated = false

    func authenticate() {
        GKLocalPlayer.local.authenticateHandler = { [weak self] viewController, error in
            if let viewController {
                // GameKit needs to show its sign-in UI.
                UIApplication.shared.connectedScenes
                    .compactMap { ($0 as? UIWindowScene)?.keyWindow?.rootViewController }
                    .first?.present(viewController, animated: true)
                return
            }
            self?.isAuthenticated = GKLocalPlayer.local.isAuthenticated
            if self?.isAuthenticated == true {
                GKAccessPoint.shared.location = .topLeading
                GKAccessPoint.shared.isActive = false        // show it on menus, not during play
            }
            if let error { print("Game Center unavailable: \(error.localizedDescription)") }
        }
    }
}

Rules I follow:

Never block the game on Game Center. If the player declines or is offline, the game plays normally and leaderboards just aren't offered.
Present the sign-in view controller from a real, visible controller. Presenting from a controller that isn't in the window is a classic "Game Center never shows" bug.
Show the access point only on menus. GKAccessPoint (iOS 14+) is a small Game Center badge that the system draws. Set isActive = false during play so it doesn't overlap the board.

6. Submitting scores the modern way

The old GKScore class is deprecated since iOS 14. The current API is a single class method on GKLeaderboard:

extension GameCenter {
    static let leaderboardID = "speck.highscores.normal"   // as configured in App Store Connect

    func submit(score: Int, difficulty: String) {
        guard GKLocalPlayer.local.isAuthenticated else { return }
        GKLeaderboard.submitScore(score, context: 0, player: GKLocalPlayer.local,
                                  leaderboardIDs: ["speck.highscores.\(difficulty)"]) { error in
            if let error { print("Score submit failed: \(error.localizedDescription)") }
        }
    }
}

Design choices:

One leaderboard per difficulty. An easy-mode score and a hard-mode score aren't comparable, and mixing them makes the board meaningless. Each needs its own ID in App Store Connect.
Submit at game over, not per match. One call per run is plenty. Game Center keeps each player's best score according to the leaderboard's settings.
Configure the sort order and format in App Store Connect (high to low, integer). The client just sends numbers.

7. Showing leaderboards in iOS 18 and 26

This is where things have moved. For years the answer was "present a GKGameCenterViewController". Apple's documentation now marks GKGameCenterViewController deprecated in iOS 26. Meanwhile, GKAccessPoint gained trigger(leaderboardID:playerScope:timeScope:handler:) in iOS 18, which opens the system Game Center UI straight to one leaderboard.

Since Speck Match supports iOS 15.6 and later, the approach I'd use branches:

import GameKit
import SwiftUI

extension GameCenter {
    func showLeaderboard(id: String, from presenter: UIViewController) {
        if #available(iOS 18, *) {
            GKAccessPoint.shared.trigger(leaderboardID: id, playerScope: .global, timeScope: .allTime) { }
        } else {
            // iOS 14–17: the dashboard view controller (deprecated in iOS 26, fine on older systems).
            let vc = GKGameCenterViewController(leaderboardID: id, playerScope: .global, timeScope: .allTime)
            vc.gameCenterDelegate = presenter as? GKGameCenterControllerDelegate
            presenter.present(vc, animated: true)
        }
    }

    /// In-game "Top 10" without leaving the app (iOS 14+).
    func topTen(id: String) async throws -> [(rank: Int, name: String, score: String)] {
        let boards = try await GKLeaderboard.loadLeaderboards(IDs: [id])
        guard let board = boards.first else { return [] }
        let (_, entries, _) = try await board.loadEntries(for: .global, timeScope: .allTime,
                                                         range: NSRange(location: 1, length: 10))
        return entries.map { ($0.rank, $0.player.displayName, $0.formattedScore) }
    }
}

loadEntries(for:timeScope:range:) returns the local player's entry, the requested range and the total count. Use formattedScore rather than formatting the raw value yourself, so the display matches what Game Center shows everywhere else.

The app's most recent release notes include "Fixed Game Center leaderboard display issue". That's a reminder that the leaderboard display path is the fragile part. Test it on every iOS version you support, and especially on both sides of the iOS 18 branch.

8. Real-world example: Speck Match

This walkthrough is grounded in building Speck Match. The code is the approach I'd use, written for this article, not the shipped source.

At the time of writing, its App Store listing shows:

Free to play ("with optional ads that can be removed"), in Games (Board, Strategy)
First released in December 2021
1 rating in the US store, 5 stars
Supports iOS 15.6 and later

How the listing maps to this article:

What the listing says	Where it's covered
"Tap and drag to connect matching dots"	`DragGesture` chains (section 3)
"Game gets faster and more challenging as you progress" / "Multiple difficulty levels"	`spawnInterval` and difficulty presets (section 1)
"Speed matters - faster matches = higher scores"	Freshness-based scoring (section 4)
"Pause and resume anytime"	A pausable `TimelineView` and game time (sections 2 and 4)
"Game Center integration" / "Global leaderboards"	Authentication, submitting and display (sections 5–7)
Release notes: "Fixed Game Center leaderboard display issue"	Version-branching the display path (section 7)

9. Before you ship a Game Center game: a checklist

The game plays fully without Game Center. Declined sign-in and offline are both tested.
authenticateHandler is set once, early, and presents from a visible view controller.
There's no GKScore. Use GKLeaderboard.submitScore, once per run.
There's one leaderboard per difficulty, with IDs matching App Store Connect exactly.
The display path is branched. GKAccessPoint.trigger(leaderboardID:…) on iOS 18+, the view controller on older systems, and both tested.
The access point is hidden during play.
Scores use game time. Pausing never changes the outcome.
Hit areas are generous, and minimumDistance: 0 is set for instant drags.
Colour isn't the only cue. Consider shapes for colour-blind players.

Wrapping up

A drag-to-connect game shows how far plain SwiftUI goes. Canvas draws the board, TimelineView ticks it, DragGesture drives it, and nothing needs a game engine. Game Center is the part that keeps evolving. Use the iOS 14 GKLeaderboard APIs, adopt the iOS 18 access-point trigger, and plan for the iOS 26 deprecation of the old dashboard controller.

Play the game, or explore my other work:

Speck Match (iOS): https://apps.apple.com/us/app/speck-match/id1600688336
All of my free iOS apps: https://apps.apple.com/us/developer/alok-singh/id1508795536
My portfolio: https://bestlatestapps.com/alok/

Think you can top the leaderboard? Let me know your score in the comments.

— Alok Kumar Singh

Originally published at https://bestlatestapps.com/blog/drag-to-connect-and-game-center-leaderboards-in-a-swiftui-puzzle-game/

From Barcode to PDF: A Private, Offline Medication Tracker with VisionKit, WidgetKit and PDFKit

Sat, 24 Oct 2026 12:40:29 +0000

Originally published at https://bestlatestapps.com/blog/from-barcode-to-pdf/

Scanning a box to add a medication, a SwiftData model shared with widgets, adherence statistics, a doctor-ready PDF report, and CSV/JSON export that keeps everything on the device

I have two medication apps on the App Store. The first, Daily Pills | Reminder, does one thing: remind you on time and count your supply. I've written about its notification engineering separately. The second, Track Your Pills, came out of what people asked for next: "Can I just scan the box?" "Can I show my doctor what I've actually taken?" "Can I see today's doses without opening the app?"

Track Your Pills launched in February 2023. Its listing covers medications added "with photos, barcodes, or manual entry", tablets, capsules, syrups and injections, adherence calendars and statistics, PDF reports to "share with healthcare providers", home-screen widgets, CSV and JSON export with backup and restore, and a firm privacy line: "All data stored locally on your device… No account creation needed."

This article covers the parts that are different from a plain reminder app. Those are barcode capture with VisionKit, a SwiftData model the app and its widgets can share, adherence maths, a PDF report built with UIGraphicsPDFRenderer, and export and import. I'm leaving out the notification side on purpose, because the Daily Pills article covers it. API names and availability are checked against Apple's documentation, and I describe the approach I'd use rather than the app's exact source.

1. The model, shared by the app and its widgets

The app targets iOS 17.6 and later, so SwiftData is available. The model separates what the medication is from what happened:

import SwiftData
import Foundation

@Model
final class Medication {
    var name: String
    var form: String                 // "tablet", "capsule", "syrup", "injection"
    var strength: String?            // "500 mg", "5 ml"
    var barcode: String?
    @Attribute(.externalStorage) var photo: Data?
    var quantityRemaining: Double    // Double: syrups are measured in ml
    var dosePerIntake: Double
    var scheduleTimes: [DateComponents]
    var startDate: Date
    var endDate: Date?
    @Relationship(deleteRule: .cascade, inverse: \Intake.medication) var intakes: [Intake] = []

    init(name: String, form: String, quantityRemaining: Double, dosePerIntake: Double,
         scheduleTimes: [DateComponents], startDate: Date = .now) {
        self.name = name; self.form = form
        self.quantityRemaining = quantityRemaining; self.dosePerIntake = dosePerIntake
        self.scheduleTimes = scheduleTimes; self.startDate = startDate
    }
}

@Model
final class Intake {
    enum Status: String, Codable { case taken, missed, skipped }
    var scheduledAt: Date
    var loggedAt: Date?
    var statusRaw: String
    var medication: Medication?

    var status: Status { Status(rawValue: statusRaw) ?? .missed }

    init(scheduledAt: Date, status: Status, loggedAt: Date? = .now) {
        self.scheduledAt = scheduledAt; self.statusRaw = status.rawValue; self.loggedAt = loggedAt
    }
}

@Attribute(.externalStorage) keeps photos out of the main database file. Each intake records both the scheduled time and the logged time, which lets the report distinguish "taken on time" from "taken two hours late".

Widgets run in a separate process, so the store has to live somewhere both processes can reach. That's an App Group container:

enum SharedStore {
    static let appGroup = "group.com.example.trackyourpills"

    static func makeContainer() throws -> ModelContainer {
        let config = ModelConfiguration(
            "Medications",
            groupContainer: .identifier(appGroup),   // same file for app and widget extension
            cloudKitDatabase: .none                  // "No cloud sync required"
        )
        return try ModelContainer(for: Medication.self, Intake.self, configurations: config)
    }
}

Add the App Groups capability to both the app and widget targets with the same identifier. cloudKitDatabase: .none is the explicit, privacy-preserving choice. SwiftData otherwise looks for a CloudKit container if the iCloud capability is present.

2. Adding a medication by scanning its barcode

DataScannerViewController (VisionKit, iOS 16+) gives you a live camera view that recognises text and machine-readable codes, with highlighting and guidance built in. You don't need to build a capture session.

import SwiftUI
import VisionKit

struct BarcodeScannerView: UIViewControllerRepresentable {
    var onCode: (String) -> Void

    static var canScan: Bool {
        DataScannerViewController.isSupported && DataScannerViewController.isAvailable
    }

    func makeUIViewController(context: Context) -> DataScannerViewController {
        let scanner = DataScannerViewController(
            recognizedDataTypes: [.barcode(symbologies: [.ean13, .ean8, .upce, .code128, .dataMatrix])],
            qualityLevel: .balanced,
            recognizesMultipleItems: false,
            isHighFrameRateTrackingEnabled: false,
            isHighlightingEnabled: true)
        scanner.delegate = context.coordinator
        try? scanner.startScanning()
        return scanner
    }

    func updateUIViewController(_ controller: DataScannerViewController, context: Context) {}

    func makeCoordinator() -> Coordinator { Coordinator(onCode: onCode) }

    final class Coordinator: NSObject, DataScannerViewControllerDelegate {
        let onCode: (String) -> Void
        private var delivered = false
        init(onCode: @escaping (String) -> Void) { self.onCode = onCode }

        func dataScanner(_ scanner: DataScannerViewController,
                         didAdd addedItems: [RecognizedItem], allItems: [RecognizedItem]) {
            guard !delivered else { return }
            for item in addedItems {
                if case .barcode(let code) = item, let value = code.payloadStringValue {
                    delivered = true
                    scanner.stopScanning()
                    onCode(value)
                    return
                }
            }
        }
    }
}

Practical notes:

Check both flags. Apple's docs say isSupported requires a device with the A12 Bionic chip or later. isAvailable additionally reflects camera permission and restrictions. When either is false, fall back to manual entry; never show a dead button.
Add NSCameraUsageDescription, for example: "Scan the barcode on your medication box to fill in its details."
Pick the symbologies you need. Retail packaging is mostly EAN/UPC, and many pharmaceutical packs carry a GS1 DataMatrix. A narrower list means faster, more reliable recognition.

From code to name: an on-device lookup

The listing mentions "Auto-fill from extensive medication name database" and "Barcode scanning for instant medication lookup", and also says "No internet connection required". The approach that satisfies both is a bundled, read-only lookup table: barcode → name, form and strength. Then fall back to the user's own history: if they've scanned this code before, reuse what they typed.

struct MedicationCatalog {
    struct Entry: Decodable { let name: String; let form: String; let strength: String? }
    private let byBarcode: [String: Entry]

    init() {
        let url = Bundle.main.url(forResource: "catalog", withExtension: "json")!
        byBarcode = (try? JSONDecoder().decode([String: Entry].self, from: Data(contentsOf: url))) ?? [:]
    }

    func lookup(_ code: String) -> Entry? { byBarcode[code] }
}

Always show the result as an editable form, never a silent auto-save. A wrong strength is a dangerous error.

3. Adherence: the numbers behind the calendar

"Visual adherence calendar", "weekly and overall adherence statistics" and "per-medication adherence metrics" all come from one calculation: of the doses that were due, how many were taken?

import Foundation

struct AdherenceStats {
    let due: Int
    let taken: Int
    let late: Int        // taken, but more than the grace window after schedule
    var rate: Double { due == 0 ? 1 : Double(taken) / Double(due) }
}

enum Adherence {
    static let lateThreshold: TimeInterval = 60 * 60     // 1 hour

    static func stats(for intakes: [Intake], in interval: DateInterval) -> AdherenceStats {
        let due = intakes.filter { interval.contains($0.scheduledAt) && $0.status != .skipped }
        let taken = due.filter { $0.status == .taken }
        let late = taken.filter { ($0.loggedAt ?? $0.scheduledAt)
            .timeIntervalSince($0.scheduledAt) > lateThreshold }
        return AdherenceStats(due: due.count, taken: taken.count, late: late.count)
    }

    /// One value per day, for the calendar heat map.
    static func daily(for intakes: [Intake], days: Int, calendar: Calendar = .current)
        -> [(day: Date, rate: Double?)] {
        let today = calendar.startOfDay(for: .now)
        return (0..<days).reversed().compactMap { offset in
            guard let day = calendar.date(byAdding: .day, value: -offset, to: today),
                  let next = calendar.date(byAdding: .day, value: 1, to: day) else { return nil }
            let s = stats(for: intakes, in: DateInterval(start: day, end: next))
            return (day, s.due == 0 ? nil : s.rate)          // nil = nothing scheduled: grey cell
        }
    }
}

Two definitions you have to choose deliberately, and should explain on screen:

Skipped is not missed. If a doctor said "skip today", that dose shouldn't hurt the adherence score. Exclude skipped doses from due.
No dose scheduled ≠ 100%. A day with nothing due should render as empty, not as a perfect green square.

Swift Charts' RectangleMark makes the calendar heat map straightforward, with foregroundStyle(by:) binned into three or four colour bands.

4. A doctor-ready PDF with UIGraphicsPDFRenderer

"Generate detailed medication reports… Share reports with healthcare providers… Printable format for medical records." UIGraphicsPDFRenderer (iOS 10+) turns drawing code into PDF data. A report is just text and table rows drawn page by page:

import UIKit

struct ReportRow { let name: String; let schedule: String; let adherence: String; let remaining: String }

enum PDFReport {
    static func make(title: String, period: String, rows: [ReportRow]) -> Data {
        let page = CGRect(x: 0, y: 0, width: 595, height: 842)          // A4 in points
        let margin: CGFloat = 40
        let format = UIGraphicsPDFRendererFormat()
        format.documentInfo = [kCGPDFContextTitle as String: title,
                               kCGPDFContextCreator as String: "Track Your Pills"]
        let renderer = UIGraphicsPDFRenderer(bounds: page, format: format)

        let titleAttrs: [NSAttributedString.Key: Any] = [.font: UIFont.boldSystemFont(ofSize: 20)]
        let headAttrs: [NSAttributedString.Key: Any] = [.font: UIFont.boldSystemFont(ofSize: 11)]
        let bodyAttrs: [NSAttributedString.Key: Any] = [.font: UIFont.systemFont(ofSize: 11)]
        let columns: [CGFloat] = [margin, 230, 360, 460]

        return renderer.pdfData { ctx in
            var y: CGFloat = 0

            func newPage() {
                ctx.beginPage()
                y = margin
                (title as NSString).draw(at: CGPoint(x: margin, y: y), withAttributes: titleAttrs)
                y += 30
                (period as NSString).draw(at: CGPoint(x: margin, y: y), withAttributes: bodyAttrs)
                y += 28
                for (i, h) in ["Medication", "Schedule", "Adherence", "Remaining"].enumerated() {
                    (h as NSString).draw(at: CGPoint(x: columns[i], y: y), withAttributes: headAttrs)
                }
                y += 20
            }

            newPage()
            for row in rows {
                if y > page.height - margin - 40 { newPage() }       // paginate
                for (i, text) in [row.name, row.schedule, row.adherence, row.remaining].enumerated() {
                    (text as NSString).draw(in: CGRect(x: columns[i], y: y,
                                                       width: (i < 3 ? columns[i + 1] : page.width - margin) - columns[i] - 8,
                                                       height: 32), withAttributes: bodyAttrs)
                }
                y += 34
            }

            let footer = "Generated on this device. Not medical advice; review with your clinician."
            (footer as NSString).draw(at: CGPoint(x: margin, y: page.height - margin),
                                      withAttributes: [.font: UIFont.italicSystemFont(ofSize: 9)])
        }
    }
}

To preview it, wrap PDFView (PDFKit, iOS 11+) in a UIViewRepresentable, set document = PDFDocument(data: data) and autoScales = true. To share or print, write the data to a temporary file named something human, like "Medication report – Oct 2026.pdf", and hand the URL to ShareLink. The system share sheet includes Print, Mail and Files, so you don't need any extra UI for "printable".

5. Widgets that read the shared store

"Home screen widgets for quick medication view… Upcoming medication reminders… Adherence at a glance." The widget's timeline provider opens the same App Group container and computes the next doses:

import WidgetKit
import SwiftData
import SwiftUI

struct NextDoseEntry: TimelineEntry {
    let date: Date
    let upcoming: [(name: String, at: Date)]
    let todayRate: Double?
}

struct NextDoseProvider: TimelineProvider {
    func placeholder(in context: Context) -> NextDoseEntry {
        NextDoseEntry(date: .now, upcoming: [("Vitamin D", .now)], todayRate: 1)
    }

    func getSnapshot(in context: Context, completion: @escaping (NextDoseEntry) -> Void) {
        completion(makeEntry(at: .now))
    }

    func getTimeline(in context: Context, completion: @escaping (Timeline<NextDoseEntry>) -> Void) {
        let entry = makeEntry(at: .now)
        // Refresh just after the next dose time, or in an hour if nothing is due.
        let next = entry.upcoming.first?.at.addingTimeInterval(60) ?? .now.addingTimeInterval(3600)
        completion(Timeline(entries: [entry], policy: .after(next)))
    }

    private func makeEntry(at now: Date) -> NextDoseEntry {
        guard let container = try? SharedStore.makeContainer() else {
            return NextDoseEntry(date: now, upcoming: [], todayRate: nil)
        }
        let context = ModelContext(container)
        let meds = (try? context.fetch(FetchDescriptor<Medication>())) ?? []
        let cal = Calendar.current
        let upcoming = meds.flatMap { med in
            med.scheduleTimes.compactMap { comps in
                cal.nextDate(after: now, matching: comps, matchingPolicy: .nextTime)
                    .map { (name: med.name, at: $0) }
            }
        }
        .sorted { $0.at < $1.at }
        .prefix(3)
        let today = DateInterval(start: cal.startOfDay(for: now), duration: 86_400)
        let stats = Adherence.stats(for: meds.flatMap(\.intakes), in: today)
        return NextDoseEntry(date: now, upcoming: Array(upcoming),
                             todayRate: stats.due == 0 ? nil : stats.rate)
    }
}

When the app logs a dose, call WidgetCenter.shared.reloadTimelines(ofKind:), so the widget updates now rather than at its next scheduled refresh.

Keep widget work small. Fetch, compute three items and return. Widgets have tight time and memory budgets.

6. Export, backup and restore without a server

"Export data in CSV or JSON formats… Complete backup and restore… Privacy-focused: all data stored locally." With no account and no cloud, export is the backup strategy, so treat it as a first-class feature.

import Foundation
import CoreTransferable
import UniformTypeIdentifiers

struct BackupFile: Codable {
    struct Med: Codable {
        let name, form: String; let strength, barcode: String?
        let quantityRemaining, dosePerIntake: Double
        let scheduleTimes: [DateComponents]; let startDate: Date; let endDate: Date?
        let intakes: [IntakeDTO]
    }
    struct IntakeDTO: Codable { let scheduledAt: Date; let loggedAt: Date?; let status: String }

    var version = 1                 // bump when the format changes; migrate on import
    let exportedAt: Date
    let medications: [Med]
}

extension BackupFile: Transferable {
    static var transferRepresentation: some TransferRepresentation {
        DataRepresentation(exportedContentType: .json) { backup in
            let encoder = JSONEncoder()
            encoder.dateEncodingStrategy = .iso8601
            encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
            return try encoder.encode(backup)
        }
        .suggestedFileName("TrackYourPills-backup.json")
    }
}

enum CSVExport {
    static func intakes(_ meds: [Medication]) -> String {
        func esc(_ s: String) -> String { "\"\(s.replacingOccurrences(of: "\"", with: "\"\""))\"" }
        let iso = ISO8601DateFormatter()
        var lines = ["medication,scheduled_at,logged_at,status"]
        for med in meds {
            for i in med.intakes.sorted(by: { $0.scheduledAt < $1.scheduledAt }) {
                lines.append([esc(med.name), iso.string(from: i.scheduledAt),
                              i.loggedAt.map(iso.string(from:)) ?? "", i.statusRaw].joined(separator: ","))
            }
        }
        return lines.joined(separator: "\n")
    }
}

ShareLink(item: backup, preview: SharePreview("Backup")) (iOS 16+) then lets the user save to Files, AirDrop it to another device or email it to themselves, all under their control. For restore, .fileImporter(isPresented:allowedContentTypes:onCompletion:) with [.json] picks the file. Decode it, check version, and import inside a single ModelContext transaction, so a bad file can't leave half a database.

A design rule I'd hold to: JSON is the backup, CSV is the report. CSV is for spreadsheets and doctors and loses structure; only JSON round-trips. Label them that way in the UI.

If you use fileExporter instead of ShareLink, note that Apple's current docs mark the original fileExporter(isPresented:document:contentType:defaultFilename:onCompletion:) as deprecated in iOS 27.2, in favour of the overload that adds onCancellation:.

7. Interaction warnings: handle with great care

The listing includes a "Drug Interaction Checker" with "Safety alerts before adding new medications" and "Medical disclaimers and recommendations". The technical side is simple: a bundled table of known interacting pairs, checked when a medication is added. The responsibility side is not:

Offline data ages. Show the data's version date in the warning.
Absence of a warning isn't safety. Word it as "No interactions found in this app's list", never "safe to combine".
Never block, always refer. Warn, show the source and recommend checking with a pharmacist or doctor.

I won't publish a table here; the content is the hard part, and it must come from a reliable, licensed source.

8. Real-world example: Track Your Pills

All of this describes the approach I'd use, and recommend, for Track Your Pills.

At the time of writing, its App Store listing shows:

Free, in Medical and Health & Fitness
First released in February 2023
7 ratings in the US store, averaging about 4.7 stars
Supports iOS 17.6 and later

How the listing maps to this article:

What the listing says	Where it's covered
"Add medications with photos, barcodes, or manual entry" / "Barcode scanning for instant medication lookup"	`DataScannerViewController` plus a bundled lookup, with manual fallback (section 2)
"Support for tablets, capsules, syrups, and injections"	`form` and a `Double` quantity in the model (section 1)
"Visual adherence calendar… Weekly and overall adherence statistics"	Due vs taken, skipped excluded (section 3)
"Generate detailed medication reports… Share reports with healthcare providers"	`UIGraphicsPDFRenderer`, `PDFView` preview, `ShareLink` (section 4)
"Home screen widgets… Upcoming medication reminders… Adherence at a glance"	App Group SwiftData store read by a `TimelineProvider` (sections 1, 5)
"Export data in CSV or JSON formats… Complete backup and restore"	`Transferable` JSON backup, CSV report, versioned import (section 6)
"All data stored locally… No cloud sync required… No account creation needed"	`cloudKitDatabase: .none`, no server, user-controlled export (sections 1, 6)

The reminder side of the listing (pre-alarms, quiet hours, escalating reminders) is local-notification work. The patterns in my Daily Pills article, deterministic identifiers and the 64-pending-notification budget, apply directly, and escalation makes that budget matter even more.

9. Before you ship a medication tracker: a checklist

Scanning degrades gracefully. Unsupported devices and denied camera access both lead to manual entry.
Scanned data is always reviewed by the user before it's saved.
The store lives in an App Group, and widgets read it without crashing on first launch, before any data exists.
Adherence definitions are explicit: skipped vs missed, late threshold, and days with nothing due.
The PDF paginates, has a title, a date range and a disclaimer, and opens cleanly in Files and Mail.
The JSON backup round-trips. Export, delete the app, reinstall, import: every record comes back.
Backups are versioned, and import is all-or-nothing.
Privacy claims are literally true: no CloudKit, no analytics surprises, and accurate App Privacy details.
Interaction warnings are worded carefully and dated, and always refer the user to a professional.

Wrapping up

A medication tracker becomes trustworthy through small, careful pieces: input that's fast but always confirmed, a clear model of what happened, statistics with honest definitions, and reports and exports that keep the user in control of their own data. VisionKit, SwiftData, WidgetKit and a PDF renderer cover nearly all of it, without a single server.

Try it, or explore my other apps:

Track Your Pills (iOS): https://apps.apple.com/us/app/track-your-pills/id1660782134
Daily Pills | Reminder (iOS): https://apps.apple.com/us/app/daily-pills-reminder/id1510203960
All of my free iOS apps: https://apps.apple.com/us/developer/alok-singh/id1508795536
My portfolio: https://bestlatestapps.com/alok/

If you've built health features with no backend, how did you handle backups? Tell me in the comments.

— Alok Kumar Singh

Originally published at https://bestlatestapps.com/blog/from-barcode-to-pdf/

Medication Reminders That Actually Fire: Local Notifications and the 64-Notification Limit

Sat, 24 Oct 2026 12:40:17 +0000

Originally published at https://bestlatestapps.com/blog/medication-reminders-that-actually-fire/

Repeating calendar triggers, a notification budget, "Taken" and "Snooze" actions, run-out dates and on-device privacy, from building a pill reminder app

Most apps can afford a missed notification. A medication reminder can't. If the 9 p.m. reminder silently doesn't arrive, someone misses a dose, and they stop trusting the app the same evening.

Daily Pills | Reminder is my take on the simplest version of this problem, live since May 2020: set the times you take your pills, get reminded, see how many you have left and know when you'll run out. The listing sums it up as "Never miss your medication again!" and promises that "your medication data stays private on your device."

That combination, reliable reminders with no server, rests entirely on local notifications, and they have more sharp edges than most developers expect: a hard cap on pending notifications, time-zone behaviour, actions that run while the phone is locked, and data that must be readable at that moment. This article covers how I'd build the core: the data model, repeating triggers, a notification budget, actionable notifications, supply maths and on-device storage. API names and availability are checked against Apple's documentation, and this is the approach I'd use rather than the app's exact source.

1. The model: keep it boring

import Foundation

struct ReminderTime: Codable, Hashable, Identifiable {
    var hour: Int          // 0...23, local wall-clock time
    var minute: Int
    var id: String { String(format: "%02d%02d", hour, minute) }
}

struct Medication: Codable, Identifiable {
    var id = UUID()
    var name: String
    var pillsPerDose: Int = 1
    var times: [ReminderTime]                 // multiple reminders per day
    var pillsRemaining: Int
    var lowSupplyWarningDays: Int = 5
    var log: [DoseEvent] = []
}

struct DoseEvent: Codable, Hashable {
    enum Kind: String, Codable { case taken, missed, skipped }
    var date: Date
    var kind: Kind
}

Two choices to notice:

Reminder times are an hour and a minute, not a Date. "8:00 every morning" is a wall-clock intention. Storing it as a Date bakes in a time zone, and the reminder drifts when the user travels or when daylight saving changes.
The log is append-only. Missed and taken doses are facts. Supply and adherence are computed from them, never stored separately where they could disagree.

2. Repeating reminders with UNCalendarNotificationTrigger

For "every day at 08:00", a single repeating calendar trigger is exactly right:

import UserNotifications

enum ReminderScheduler {
    static let doseCategory = "DOSE_REMINDER"

    static func identifier(for med: Medication, time: ReminderTime) -> String {
        "dose.\(med.id.uuidString).\(time.id)"
    }

    static func schedule(_ med: Medication) async throws {
        let center = UNUserNotificationCenter.current()
        // Start clean for this medication so edits never leave stale reminders behind.
        await cancel(med)

        for time in med.times {
            let content = UNMutableNotificationContent()
            content.title = "Time for \(med.name)"
            content.body = med.pillsPerDose == 1 ? "Take 1 pill." : "Take \(med.pillsPerDose) pills."
            content.sound = .default
            content.categoryIdentifier = doseCategory
            content.userInfo = ["medID": med.id.uuidString, "time": time.id]
            if #available(iOS 15.0, *) {
                content.interruptionLevel = .timeSensitive   // needs the Time Sensitive capability
            }

            // Only hour and minute: fires every day at that local wall-clock time.
            var components = DateComponents()
            components.hour = time.hour
            components.minute = time.minute
            let trigger = UNCalendarNotificationTrigger(dateMatching: components, repeats: true)

            let request = UNNotificationRequest(identifier: identifier(for: med, time: time),
                                                content: content, trigger: trigger)
            try await center.add(request)
        }
    }

    static func cancel(_ med: Medication) async {
        let center = UNUserNotificationCenter.current()
        let ids = await center.pendingNotificationRequests()
            .map(\.identifier)
            .filter { $0.hasPrefix("dose.\(med.id.uuidString).") }
        center.removePendingNotificationRequests(withIdentifiers: ids)
    }
}

What makes this reliable:

Deterministic identifiers. dose.<medID>.<HHmm> means rescheduling replaces rather than duplicates, and cancelling one medication can't touch another's reminders.
Date components without a time zone fire at local wall-clock time. If the user flies from Delhi to London, "08:00" stays 08:00 local, which is usually what a daily pill means. (For medications that must be taken at strict intervals regardless of time zone, that's a different design: talk to the user, and consider fixed-interval triggers.)
.timeSensitive (iOS 15+) lets the reminder break through Focus modes, if the user allows it. It requires adding the Time Sensitive Notifications capability. Use it only for genuinely time-sensitive content, which a dose reminder is.

And of course, ask permission first, at the moment the user adds their first reminder, with requestAuthorization(options: [.alert, .sound, .badge]).

3. The 64-notification limit, and a budget

Here's the trap. iOS keeps only a limited number of pending local notifications per app. Apple's documentation for the older UILocalNotification API states it plainly: the system keeps the soonest-firing 64 notifications and discards the rest. Automatically repeating notifications count as a single notification. The same cap is widely observed with UserNotifications, and it fails silently: add(_:) succeeds and the 65th reminder just never fires.

With repeating triggers, one per medication per time, you're usually fine: 5 medications × 3 times a day is 15 requests. The trouble starts when you schedule one-off notifications: a different message per day ("Day 12 of 30"), weekly schedules built from individual dates, snoozes or low-supply warnings. Each of those is its own slot.

So treat the pending queue as a budget, and check it:

enum NotificationBudget {
    static let systemLimit = 64
    static let safetyMargin = 4          // room for snoozes and low-supply warnings

    /// How many requests we'd have after scheduling `meds`.
    static func projected(for meds: [Medication], extraOneOffs: Int = 0) -> Int {
        meds.reduce(0) { $0 + $1.times.count } + extraOneOffs
    }

    static func canSchedule(_ meds: [Medication], extraOneOffs: Int = 0) -> Bool {
        projected(for: meds, extraOneOffs: extraOneOffs) <= systemLimit - safetyMargin
    }

    /// Debug helper: compare what you *think* is scheduled with what the system has.
    static func audit() async {
        let pending = await UNUserNotificationCenter.current().pendingNotificationRequests()
        print("Pending: \(pending.count) / \(systemLimit)")
        pending.forEach { print(" •", $0.identifier, $0.trigger.map(String.init(describing:)) ?? "-") }
    }
}

If you genuinely need more than the budget allows, for example non-repeating schedules, schedule a rolling window (the next N days) and top it up whenever the app becomes active. Never assume "scheduled once" means "scheduled forever".

4. "Taken" and "Snooze" right from the notification

A reminder you have to unlock the phone and open the app to acknowledge is a reminder people ignore. Register a category with actions:

import UserNotifications

enum DoseActions {
    static let taken = "TAKEN"
    static let snooze = "SNOOZE_10"

    static func register() {
        let takenAction = UNNotificationAction(identifier: taken, title: "Taken", options: [])
        let snoozeAction = UNNotificationAction(identifier: snooze, title: "Snooze 10 min", options: [])
        let category = UNNotificationCategory(identifier: ReminderScheduler.doseCategory,
                                              actions: [takenAction, snoozeAction],
                                              intentIdentifiers: [], options: [])
        UNUserNotificationCenter.current().setNotificationCategories([category])
    }
}

final class NotificationHandler: NSObject, UNUserNotificationCenterDelegate {
    let store: MedicationStore
    init(store: MedicationStore) { self.store = store }

    func userNotificationCenter(_ center: UNUserNotificationCenter,
                                didReceive response: UNNotificationResponse) async {
        let info = response.notification.request.content.userInfo
        guard let idString = info["medID"] as? String, let id = UUID(uuidString: idString) else { return }

        switch response.actionIdentifier {
        case DoseActions.taken, UNNotificationDefaultActionIdentifier:
            store.recordDose(for: id, kind: .taken, at: Date())

        case DoseActions.snooze:
            let content = response.notification.request.content.mutableCopy() as! UNMutableNotificationContent
            let trigger = UNTimeIntervalNotificationTrigger(timeInterval: 10 * 60, repeats: false)
            let request = UNNotificationRequest(identifier: "snooze.\(idString)",   // one snooze per med
                                                content: content, trigger: trigger)
            try? await center.add(request)

        default:
            break
        }
    }
}

Register the categories and set the delegate early, in application(_:didFinishLaunchingWithOptions:) or your App initialiser, because the system may launch your app in the background specifically to handle an action.

Notice the action options are empty: no .foreground (which would open the app) and no .authenticationRequired (which forces an unlock). "Taken" works straight from the Lock Screen. That has a consequence for storage, which section 6 covers.

Using one fixed identifier per medication for snoozes means repeated snoozes replace each other instead of filling your 64-slot budget.

5. Supply maths: pills left, run-out date and a warning

The listing promises you'll "know when your supply will run out" and "get notified before you run out". That's arithmetic on the model, plus one more scheduled notification:

import Foundation

extension Medication {
    var pillsPerDay: Int { pillsPerDose * times.count }

    var daysOfSupplyLeft: Int {
        guard pillsPerDay > 0 else { return .max }
        return pillsRemaining / pillsPerDay
    }

    func runOutDate(from now: Date = Date(), calendar: Calendar = .current) -> Date? {
        guard pillsPerDay > 0 else { return nil }
        return calendar.date(byAdding: .day, value: daysOfSupplyLeft, to: calendar.startOfDay(for: now))
    }

    var missedCount: Int { log.filter { $0.kind == .missed }.count }
}

extension ReminderScheduler {
    /// One-off "running low" reminder at 09:00, `lowSupplyWarningDays` before run-out.
    static func scheduleLowSupplyWarning(for med: Medication, calendar: Calendar = .current) async throws {
        let id = "supply.\(med.id.uuidString)"
        let center = UNUserNotificationCenter.current()
        center.removePendingNotificationRequests(withIdentifiers: [id])

        guard let runOut = med.runOutDate(),
              let warnDay = calendar.date(byAdding: .day, value: -med.lowSupplyWarningDays, to: runOut),
              warnDay > Date() else { return }

        var components = calendar.dateComponents([.year, .month, .day], from: warnDay)
        components.hour = 9
        let content = UNMutableNotificationContent()
        content.title = "Running low on \(med.name)"
        content.body = "About \(med.lowSupplyWarningDays) days left. Time to refill."
        content.sound = .default

        try await center.add(UNNotificationRequest(
            identifier: id, content: content,
            trigger: UNCalendarNotificationTrigger(dateMatching: components, repeats: false)))
    }
}

Recalculate and reschedule the warning whenever supply changes: when a dose is taken, when pills are added, or when the schedule is edited. It's one slot per medication, kept accurate by a fixed identifier.

Missed doses. The system can't tell you a reminder was ignored. When the app becomes active, compare each scheduled time since the last check against the log, and record .missed for any slot without a .taken event within a grace window (say, 2 hours). Then show it honestly and let the user correct it ("I took it, I just didn't tap").

6. Private, on-device storage that works on a locked phone

The listing makes a clear promise: "Your medication data stays private on your device. We don't collect or share your personal health information." The simplest way to keep that promise is to have no server at all: a small Codable file in Application Support.

There's one subtlety. The "Taken" action from section 4 can run while the device is locked. If you save with the strongest file protection (.completeFileProtection), the file is unreadable while locked, and the write fails exactly when the user taps "Taken" on the Lock Screen.

import Foundation

final class MedicationStore {
    private(set) var medications: [Medication] = []
    private let url: URL

    init() {
        let dir = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
        try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
        url = dir.appendingPathComponent("medications.json")
        load()
    }

    func load() {
        guard let data = try? Data(contentsOf: url) else { return }
        medications = (try? JSONDecoder().decode([Medication].self, from: data)) ?? []
    }

    func save() {
        do {
            let data = try JSONEncoder().encode(medications)
            // Encrypted at rest, but readable after the first unlock since boot,
            // so Lock Screen actions can update it.
            try data.write(to: url, options: [.atomic, .completeFileProtectionUntilFirstUserAuthentication])
        } catch {
            print("Save failed: \(error)")
        }
    }

    func recordDose(for id: UUID, kind: DoseEvent.Kind, at date: Date) {
        guard let i = medications.firstIndex(where: { $0.id == id }) else { return }
        medications[i].log.append(DoseEvent(date: date, kind: kind))
        if kind == .taken {
            medications[i].pillsRemaining = max(0, medications[i].pillsRemaining - medications[i].pillsPerDose)
        }
        save()
    }
}

.completeFileProtectionUntilFirstUserAuthentication (iOS 5+) is the trade-off I'd choose: encrypted when the phone has just rebooted and never been unlocked, and accessible afterwards, so background actions work. Also keep the App Privacy section of your App Store listing consistent with "data not collected", and don't add an analytics SDK that quietly breaks that promise.

7. Real-world example: Daily Pills | Reminder

These are the techniques I'd use, and recommend, for Daily Pills | Reminder.

At the time of writing, its App Store listing shows:

Free, in Health & Fitness and Medical
First released in May 2020
8 ratings in the US store, averaging about 4.4 stars
Supports iOS 16.0 and later

How the listing maps to this article:

What the listing says	Where it's covered
"Set daily reminder times that work for you" / "Multiple reminders per day"	One repeating calendar trigger per time, deterministic IDs (section 2)
"Never miss a dose"	Time-sensitive delivery, a notification budget, a rolling window if needed (sections 2–3)
"Add pills with one tap" / "Mark missed pills instantly"	An append-only dose log; Lock Screen actions (sections 1, 4)
"See how many pills you have left" / "Know when your supply will run out" / "Get notified before you run out"	Supply maths and a one-off low-supply warning (section 5)
"Your medication data stays private on your device"	Local `Codable` storage with the right file protection, no server (section 6)

I also have a second, more feature-rich medication app, Track Your Pills, with barcode scanning, PDF reports for doctors and widgets. I'm writing that one up separately, because its technical story is quite different.

A necessary note for anyone building in this space: a reminder app is a convenience tool, not medical advice. Say so in the app, and never let a bug in your scheduling be the only thing between someone and their medication. Clear, honest UI about what's scheduled helps a lot.

8. Before you ship a reminder app: a checklist

Permission is requested at the moment of need, and a denied state shows how to enable notifications in Settings.
Identifiers are deterministic, and edits cancel and reschedule only what they own.
The pending count is audited. You know how many of the 64 slots you use, with a safety margin.
Times are wall-clock components, tested across a time-zone change and a daylight-saving change.
Actions work from the Lock Screen, including right after a reboot, once the phone has been unlocked once.
Supply and run-out dates are recomputed on every change, and the warning is rescheduled.
Missed doses are detected on launch and are easy to correct.
Privacy claims match reality. No hidden analytics, and the App Privacy details are accurate.
You've tested on a real device over several days. The Simulator won't show you what happens after a week of real use.

Wrapping up

Reliable reminders on iOS come down to a few disciplined habits: repeating calendar triggers with deterministic identifiers, a budget for the 64-notification cap, actions that work from the Lock Screen, and storage that can be written while the phone is locked. Add simple, honest supply maths and you have an app people can rely on.

Try it, or explore my other apps:

Daily Pills | Reminder (iOS): https://apps.apple.com/us/app/daily-pills-reminder/id1510203960
All of my free iOS apps: https://apps.apple.com/us/developer/alok-singh/id1508795536
My portfolio: https://bestlatestapps.com/alok/

Have you hit the 64-notification limit in production? I'd love to hear how you discovered it. Tell me in the comments.

— Alok Kumar Singh

Originally published at https://bestlatestapps.com/blog/medication-reminders-that-actually-fire/

Shipping a 4K Wallpaper App Without Running Out of Memory: ImageIO Downsampling and Core Image

Sat, 24 Oct 2026 12:40:06 +0000

Originally published at https://bestlatestapps.com/blog/shipping-a-4k-wallpaper-app-without-running-out-of-memory/

Decoded-image maths, thumbnails that don't decode the full file, a blur editor that keeps edges clean, saving with the minimum permission, and why your app can't set the wallpaper itself

A wallpaper app looks like the simplest kind of app there is: a grid of pictures, tap one, save it. Then you load forty 4K images into a scrolling grid on an older iPhone, and the system terminates your app for using too much memory.

My app Wallpapers HD: Exotic 4K lists "fresh 4K HD wallpapers", "parallax-ready backgrounds that look sharp on every iPhone display", a Create mode to "edit photos and add blur effects", categories from Nature and Anime to Space and Minimalism, search, and saving so you can set an image as your Lock Screen or Home Screen. It's been on the App Store since December 2022.

Every one of those features runs into the same physical fact: a decoded image costs width × height × 4 bytes, no matter how small the file is. This article covers how I'd build a wallpaper app around that fact. That means downsampled thumbnails with ImageIO, full-resolution images only when needed, a Core Image blur editor, saving with add-only Photos access, and an honest explanation of the "set as wallpaper" step. API names and availability are checked against Apple's documentation, and this is the approach I'd use rather than the app's exact source.

1. The memory maths everyone forgets

A 4K image (3840 × 2160) might be a 2 MB JPEG on disk. Decoded for display, it's:

3840 × 2160 pixels × 4 bytes (RGBA) ≈ 33 MB

A grid showing 12 of those at once is around 400 MB of bitmap memory before you've scrolled anywhere. Yet a grid cell might be 120 × 260 points, about 360 × 780 pixels on a 3× display, which needs roughly 1.1 MB decoded.

So the rule is: never decode a bigger image than you're going to display. UIImage(data:) decodes at full size. ImageIO can decode straight to the size you need.

2. Downsampling with ImageIO

CGImageSourceCreateThumbnailAtIndex (iOS 4+) creates a smaller image directly from the compressed data, without ever holding the full-size bitmap in memory:

import ImageIO
import UIKit

enum Downsampler {
    /// Decodes `data` at most `maxPixelSize` on its longest side.
    static func image(from data: Data, maxPixelSize: CGFloat, scale: CGFloat) -> UIImage? {
        let sourceOptions = [kCGImageSourceShouldCache: false] as CFDictionary
        guard let source = CGImageSourceCreateWithData(data as CFData, sourceOptions) else { return nil }

        let options = [
            kCGImageSourceCreateThumbnailFromImageAlways: true,
            kCGImageSourceShouldCacheImmediately: true,      // decode now, off the main thread
            kCGImageSourceCreateThumbnailWithTransform: true, // respect EXIF orientation
            kCGImageSourceThumbnailMaxPixelSize: maxPixelSize
        ] as CFDictionary

        guard let cg = CGImageSourceCreateThumbnailAtIndex(source, 0, options) else { return nil }
        return UIImage(cgImage: cg, scale: scale, orientation: .up)
    }

    /// Same, from a file URL: avoids loading the whole file into memory first.
    static func image(at url: URL, maxPixelSize: CGFloat, scale: CGFloat) -> UIImage? {
        let sourceOptions = [kCGImageSourceShouldCache: false] as CFDictionary
        guard let source = CGImageSourceCreateWithURL(url as CFURL, sourceOptions) else { return nil }
        let options = [
            kCGImageSourceCreateThumbnailFromImageAlways: true,
            kCGImageSourceShouldCacheImmediately: true,
            kCGImageSourceCreateThumbnailWithTransform: true,
            kCGImageSourceThumbnailMaxPixelSize: maxPixelSize
        ] as CFDictionary
        return CGImageSourceCreateThumbnailAtIndex(source, 0, options)
            .map { UIImage(cgImage: $0, scale: scale, orientation: .up) }
    }
}

Two options do the important work:

kCGImageSourceShouldCache: false on the source stops ImageIO from caching a full-size decode as a side effect.
kCGImageSourceShouldCacheImmediately: true on the thumbnail forces decoding now, which you'll do on a background task, instead of lazily on the main thread during the first draw, where it causes scroll hitches.

On iOS 15+, UIImage.preparingThumbnail(of:) is a convenient alternative when you already have a UIImage. But a UIImage made from data hasn't necessarily been decoded yet, and ImageIO gives you the most control.

3. A grid that stays smooth

Better still: don't download 4K images for the grid at all. Have your image host serve a small rendition for browsing and the full file only for the detail screen. Then downsample whatever arrives to the cell's pixel size anyway, because servers change.

import SwiftUI

actor ThumbnailCache {
    static let shared = ThumbnailCache()
    private let cache = NSCache<NSURL, UIImage>()
    init() { cache.totalCostLimit = 80 * 1024 * 1024 }    // ~80 MB of decoded thumbnails

    func image(for url: URL, pixelSize: CGFloat, scale: CGFloat) async -> UIImage? {
        if let hit = cache.object(forKey: url as NSURL) { return hit }
        guard let (data, _) = try? await URLSession.shared.data(from: url),
              let image = Downsampler.image(from: data, maxPixelSize: pixelSize, scale: scale)
        else { return nil }
        let cost = Int(image.size.width * image.scale * image.size.height * image.scale * 4)
        cache.setObject(image, forKey: url as NSURL, cost: cost)
        return image
    }
}

struct WallpaperCell: View {
    let thumbnailURL: URL
    @Environment(\.displayScale) private var scale
    @State private var image: UIImage?

    var body: some View {
        GeometryReader { geo in
            ZStack {
                Color(.secondarySystemBackground)
                if let image { Image(uiImage: image).resizable().scaledToFill() }
            }
            .frame(width: geo.size.width, height: geo.size.height)
            .clipped()
            .task(id: thumbnailURL) {
                let px = max(geo.size.width, geo.size.height) * scale
                image = await ThumbnailCache.shared.image(for: thumbnailURL, pixelSize: px, scale: scale)
            }
        }
        .aspectRatio(9.0 / 19.5, contentMode: .fit)
        .clipShape(RoundedRectangle(cornerRadius: 12))
    }
}

The details that matter:

NSCache with a cost limit sized in decoded bytes, not image count, so the system can also evict under memory pressure.
.task(id:) cancels the load when a cell scrolls off-screen before finishing.
@Environment(\.displayScale), not UIScreen.main.scale. Apple's docs now mark UIScreen.main as deprecated in iOS 26. Read the scale and screen size from the view's environment or window scene instead.

Why not just AsyncImage (iOS 15+)? It's fine for small images, but it decodes whatever it downloads at full size and has no memory-cost cache. For a wallpaper grid, owning the pipeline pays off.

4. The detail screen: full resolution, exactly once

When the user opens a wallpaper, they deserve every pixel, but only one full-size image should be alive at a time. Download to a file (it streams to disk instead of RAM) and decode to the device's native screen size rather than the source's 4K:

import UIKit

enum FullImageLoader {
    /// Downloads to a temporary file, then decodes at the screen's native pixel size.
    static func load(_ url: URL, nativeScreenSize: CGSize, scale: CGFloat) async throws -> (UIImage, URL) {
        let (tempURL, _) = try await URLSession.shared.download(from: url)
        // Move out of the system's temporary location before it's cleaned up.
        let kept = FileManager.default.temporaryDirectory.appendingPathComponent(url.lastPathComponent)
        try? FileManager.default.removeItem(at: kept)
        try FileManager.default.moveItem(at: tempURL, to: kept)

        let longest = max(nativeScreenSize.width, nativeScreenSize.height)
        guard let image = Downsampler.image(at: kept, maxPixelSize: longest, scale: scale) else {
            throw CocoaError(.fileReadCorruptFile)
        }
        return (image, kept)    // keep the file: saving uses the original bytes
    }
}

UIScreen.nativeBounds (iOS 8+) gives the screen's size in physical pixels. Get the screen from the current window scene (view.window?.windowScene?.screen) rather than UIScreen.main.

What about "parallax-ready"? iOS can apply motion and depth effects to wallpapers, and the system crops and zooms to fit the device. The practical rule: supply images at least as large as the native screen, in portrait, with the subject away from the edges, so the system has room to crop and move. That's why a 4K source is useful even though you decode the preview smaller. You save the original, not the preview.

5. Create mode: blur that keeps clean edges

"Create your own wallpapers — edit photos and add blur effects." Core Image's Gaussian blur is the right tool, with one classic gotcha: blurring pulls in transparent pixels from outside the image, which gives you a dark, soft border. Clamp the image to its extent first, then crop back:

import CoreImage
import CoreImage.CIFilterBuiltins
import UIKit

final class BlurEditor {
    private let context = CIContext(options: [.useSoftwareRenderer: false])
    private let source: CIImage

    init?(image: UIImage) {
        guard let ci = CIImage(image: image) else { return nil }
        source = ci
    }

    /// radius in pixels of the *output*; scale it if you preview at a smaller size.
    func render(radius: Double, dim: Double = 0) -> UIImage? {
        let blur = CIFilter.gaussianBlur()
        blur.inputImage = source.clampedToExtent()     // no dark edges
        blur.radius = Float(radius)
        var output = blur.outputImage?.cropped(to: source.extent) ?? source

        if dim > 0 {                                   // darken for legible clock and widgets
            let controls = CIFilter.colorControls()
            controls.inputImage = output
            controls.brightness = Float(-dim)
            output = controls.outputImage ?? output
        }

        guard let cg = context.createCGImage(output, from: source.extent) else { return nil }
        return UIImage(cgImage: cg)
    }
}

Performance tips for a live slider:

Preview on the downsampled image and render the full-resolution output only when the user taps Save. Blur cost grows with the pixel count and the radius.
Scale the radius between preview and export. A 20-pixel blur on a 1,290-pixel-wide preview is about a 60-pixel blur on a 3,840-pixel export.
Reuse one CIContext. Creating a context per slider tick is the slowest possible way to use Core Image.

The optional dim parameter is a small design touch: a slightly darker, blurred background keeps the Lock Screen clock and widgets readable.

6. Saving with the minimum permission

Saving an image to Photos doesn't require read access to the user's library. iOS has an add-only access level for exactly this:

import Photos
import UIKit

enum PhotoSaver {
    enum SaveError: Error { case denied }

    /// Saves the original file bytes (not a re-encoded UIImage) to Photos.
    static func saveOriginal(fileURL: URL) async throws {
        let status = await PHPhotoLibrary.requestAuthorization(for: .addOnly)   // iOS 14+
        guard status == .authorized || status == .limited else { throw SaveError.denied }

        try await PHPhotoLibrary.shared().performChanges {
            let request = PHAssetCreationRequest.forAsset()
            request.addResource(with: .photo, fileURL: fileURL, options: nil)
        }
    }

    /// For edited images from Create mode.
    static func save(_ image: UIImage) async throws {
        let status = await PHPhotoLibrary.requestAuthorization(for: .addOnly)
        guard status == .authorized || status == .limited else { throw SaveError.denied }
        try await PHPhotoLibrary.shared().performChanges {
            PHAssetChangeRequest.creationRequestForAsset(from: image)
        }
    }
}

Declare NSPhotoLibraryAddUsageDescription (iOS 11+), not the full-library key. For example: "Save wallpapers you choose to your photo library."
requestAuthorization(for: .addOnly) (iOS 14+) asks only for what you need. Users are far more likely to allow it, and you never see their photos.
Save the original file with PHAssetCreationRequest.addResource(with:fileURL:options:) (iOS 9+). Re-encoding a UIImage can cost quality and strip metadata.

7. The honest part: you can't set the wallpaper for the user

There's no public iOS API that lets an app set the Lock Screen or Home Screen wallpaper. A wallpaper app's job ends at "saved to Photos", and the user sets it from the Photos app or from Settings → Wallpaper.

So make that last step effortless:

After saving, show a short, illustrated guide: Photos → open the image → Share → Use as Wallpaper.
Offer a button that opens Photos. Don't promise a one-tap "Set" button you can't deliver; App Review and users both dislike that.
Mention that the system lets you pinch and position the image, and that depth and motion options depend on the device and iOS version.

The listing's own wording handles this well: "Save the image… Set it as your Lock Screen or Home Screen wallpaper". It's a user step, described as one.

8. Real-world example: Wallpapers HD: Exotic 4K

These are the techniques I'd use, and recommend, for Wallpapers HD: Exotic 4K.

At the time of writing, its App Store listing shows:

Free with an optional Premium tier, in Photo & Video and Graphics & Design
First released in December 2022
6 ratings in the US store, all 5 stars
Supports iOS 16.0 and later

How the listing maps to this article:

What the listing says	Where it's covered
"Fresh 4K HD wallpapers added regularly" / "Browse by category… Quick search"	A small rendition for the grid, downsampled and cost-cached (sections 2–3)
"Parallax-ready backgrounds that look sharp on every iPhone display"	Native-size preview, original saved, room for system cropping (section 4)
"Create your own wallpapers — edit photos and add blur effects"	Clamped Gaussian blur with optional dimming (section 5)
"Save the image… Set it as your Lock Screen or Home Screen wallpaper"	Add-only Photos saving, then a guided user step (sections 6–7)
"Free: Browse and download HD wallpapers with ads / Premium: … advanced blur effects… ad-free"	Gate the content and editor features by entitlement; the pipeline is the same

9. Before you ship an image-heavy app: a checklist

Nothing is decoded larger than it's displayed. Grid cells use downsampled thumbnails sized in pixels.
The cache is costed in decoded bytes with a sensible limit, and it responds to memory pressure.
Scrolling is profiled on your oldest supported device with Instruments' Allocations and Animation Hitches tools.
Full-resolution images are downloaded to disk, previewed at screen size, and saved as original bytes.
Blur previews run on the small image and export at full size with a scaled radius.
Photos access is add-only, with NSPhotoLibraryAddUsageDescription and graceful handling of denial.
You don't promise "set wallpaper" automation. Guide the user through Photos instead.
UIScreen.main is gone from new code. Use the environment's displayScale and the window scene's screen.
Image licensing is clear for every image you serve.

Wrapping up

A wallpaper app is really a memory-management app with nice pictures. Downsample with ImageIO, cache by decoded cost, keep exactly one full-size image alive, preview edits small and export big, save with the narrowest permission, and be straight with users about the last step only they can take.

Try it, or explore my other apps:

Wallpapers HD: Exotic 4K (iOS): https://apps.apple.com/us/app/wallpapers-hd-exotic-4k/id6443850234
All of my free iOS apps: https://apps.apple.com/us/developer/alok-singh/id1508795536
My portfolio: https://bestlatestapps.com/alok/

What's the largest memory spike an image grid has ever given you? Tell me in the comments.

— Alok Kumar Singh

Originally published at https://bestlatestapps.com/blog/shipping-a-4k-wallpaper-app-without-running-out-of-memory/

Text Plus Audio, Fully Offline: Building a Prayer App with AVAudioPlayer and Lock-Screen Controls

Fri, 23 Oct 2026 16:38:02 +0000

Originally published at https://bestlatestapps.com/blog/text-plus-audio-fully-offline/

Bundled recitation audio, verse-by-verse highlighting from a cue sheet, background playback, Now Playing controls and the interruptions you must handle, on an app that still supports iOS 11

Some apps are used in a very particular moment. A prayer app is opened in the morning, often before anything else, frequently by someone older who isn't interested in settings screens, and sometimes somewhere with no signal at all. It has to open instantly, play immediately and never ask for an account.

Hanuman Chalisa : Offline was the second app I published, in April 2020, one day after my Bible app. The Hanuman Chalisa is a devotional hymn to Lord Hanuman, attributed to the poet-saint Tulsidas. The app does two things: it shows the Chalisa in English-language script for reading, and it plays an audio recitation, all without an internet connection.

That combination, text plus audio that stay in step, is a pattern you'll find in language-learning apps, audiobooks with text, karaoke lyrics and guided meditations. This article walks through how I'd build it on iOS: bundling text and audio, a cue sheet for verse timing, AVAudioPlayer with a proper .playback session, highlighting the current verse, lock-screen controls through MPNowPlayingInfoCenter and MPRemoteCommandCenter, and the interruptions and route changes a real device throws at you. The app supports iOS 11 and later, so the code is UIKit-first and stays on long-established APIs. I'm describing the approach I'd use and recommend, not the app's exact source.

1. What "offline text plus audio" requires

Three requirements shape the design:

Zero network, zero setup. Everything ships in the app bundle. First launch is the same as the hundredth.
Audio and text are one experience. When the recitation reaches a verse, that verse is highlighted and scrolled into view. When the user taps a verse, the audio jumps there.
It behaves like a real audio app. It keeps playing with the screen locked, shows controls on the Lock Screen and in Control Center, pauses for a phone call, and stops when headphones are pulled out.

The first two are about your data model. The third is about respecting the system.

2. Bundle the content with a cue sheet

I keep the text and the timing together in one small JSON file in the bundle, next to the audio file:

{
  "title": "Hanuman Chalisa",
  "audio": "chalisa.m4a",
  "verses": [
    { "id": 1, "kind": "doha",  "start": 0.0,  "text": "…" },
    { "id": 2, "kind": "doha",  "start": 14.2, "text": "…" },
    { "id": 3, "kind": "chaupai", "start": 27.8, "text": "…" }
  ]
}

Each verse carries the time, in seconds, at which its recitation starts. That's the whole cue sheet. You produce it once, by listening with a waveform editor open, and it never changes unless the recording does.

import Foundation

struct Verse: Decodable {
    let id: Int
    let kind: String
    let start: TimeInterval
    let text: String
}

struct Recitation: Decodable {
    let title: String
    let audio: String
    let verses: [Verse]

    static func loadBundled(named name: String = "chalisa") throws -> Recitation {
        guard let url = Bundle.main.url(forResource: name, withExtension: "json") else {
            throw CocoaError(.fileNoSuchFile)
        }
        let recitation = try JSONDecoder().decode(Recitation.self, from: Data(contentsOf: url))
        // Cue sheets must be sorted; fail loudly in debug if someone edits one by hand.
        assert(zip(recitation.verses, recitation.verses.dropFirst()).allSatisfy { $0.start < $1.start })
        return recitation
    }

    /// Index of the verse being recited at `time` (binary search over start times).
    func verseIndex(at time: TimeInterval) -> Int {
        var low = 0, high = verses.count - 1, answer = 0
        while low <= high {
            let mid = (low + high) / 2
            if verses[mid].start <= time { answer = mid; low = mid + 1 } else { high = mid - 1 }
        }
        return answer
    }
}

A few practical notes:

AAC (.m4a) is the right format for a bundled spoken or sung recording: small, and decoded in hardware.
Keep the text as Unicode text, not images. It scales with Dynamic Type, it works with VoiceOver, and you can offer other scripts later from the same structure.
Binary search is overkill for 40-odd verses, but it costs nothing, and the same code works for a 300-chapter audiobook.

3. AVAudioPlayer and a session that keeps playing

For a single bundled file, AVAudioPlayer (available since iOS 2.2) is all you need. There's no engine graph and nothing to stream. What matters is the audio session category:

import AVFoundation

final class RecitationPlayer: NSObject, AVAudioPlayerDelegate {
    private(set) var player: AVAudioPlayer?
    var onFinish: (() -> Void)?

    func load(_ recitation: Recitation) throws {
        guard let url = Bundle.main.url(forResource: recitation.audio, withExtension: nil) else {
            throw CocoaError(.fileNoSuchFile)
        }
        let player = try AVAudioPlayer(contentsOf: url)
        player.delegate = self
        player.enableRate = true          // must be set before prepareToPlay() to allow rate changes
        player.prepareToPlay()
        self.player = player
    }

    func play() throws {
        let session = AVAudioSession.sharedInstance()
        // .playback: audio is central to the app; it plays with the Silent switch on
        // and, with the "audio" background mode, keeps going when the screen locks.
        try session.setCategory(.playback, mode: .spokenAudio, options: [])
        try session.setActive(true)
        player?.play()
    }

    func pause() { player?.pause() }

    func seek(to time: TimeInterval) {
        guard let player else { return }
        player.currentTime = max(0, min(time, player.duration))
    }

    func audioPlayerDidFinishPlaying(_ player: AVAudioPlayer, successfully flag: Bool) {
        try? AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
        onFinish?()
    }
}

Three details that matter more than they look:

.playback, not the default. The default category (.soloAmbient) is silenced by the ring/silent switch and stops when the screen locks. For a prayer app, both are bugs.
Add the background mode. In Xcode, enable Background Modes → "Audio, AirPlay, and Picture in Picture" (audio in UIBackgroundModes). Without it, .playback alone won't keep you alive after the screen locks.
The .spokenAudio mode (iOS 9+) is meant for continuous spoken audio. Per Apple's docs, your audio pauses rather than ducks when another app plays a short spoken prompt, such as a navigation instruction, and you can resume afterwards. A sung recitation sits somewhere between speech and music, so .default is a reasonable choice too. setCategory(_:mode:options:) is iOS 10+, so it's safe on an iOS 11 target.

4. Highlighting the current verse

To keep the text in step with the audio, poll currentTime a few times a second and move the highlight when the verse index changes. On iOS 11 I use a CADisplayLink (or a plain Timer) rather than anything newer:

import UIKit

final class RecitationViewController: UITableViewController {
    private let recitation: Recitation
    private let audio = RecitationPlayer()
    private var link: CADisplayLink?
    private var currentIndex = -1

    init(recitation: Recitation) {
        self.recitation = recitation
        super.init(style: .plain)
    }
    required init?(coder: NSCoder) { fatalError("init(coder:) is not supported") }

    override func viewDidLoad() {
        super.viewDidLoad()
        tableView.register(UITableViewCell.self, forCellReuseIdentifier: "verse")
        tableView.rowHeight = UITableView.automaticDimension
        try? audio.load(recitation)
    }

    func startPlayback() {
        try? audio.play()
        link = CADisplayLink(target: self, selector: #selector(tick))
        link?.preferredFramesPerSecond = 10     // plenty for text; saves battery
        link?.add(to: .main, forMode: .common)
    }

    func stopUpdates() {
        link?.invalidate(); link = nil
    }

    @objc private func tick() {
        guard let time = audio.player?.currentTime else { return }
        let index = recitation.verseIndex(at: time)
        guard index != currentIndex else { return }
        let previous = currentIndex
        currentIndex = index
        let rows = [previous, index].filter { $0 >= 0 }.map { IndexPath(row: $0, section: 0) }
        tableView.reloadRows(at: rows, with: .fade)
        tableView.scrollToRow(at: IndexPath(row: index, section: 0), at: .middle, animated: true)
    }

    // Tap a verse to jump the audio there.
    override func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
        audio.seek(to: recitation.verses[indexPath.row].start)
        tableView.deselectRow(at: indexPath, animated: true)
    }

    override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
        recitation.verses.count
    }

    override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
        let cell = tableView.dequeueReusableCell(withIdentifier: "verse", for: indexPath)
        let isCurrent = indexPath.row == currentIndex
        cell.textLabel?.text = recitation.verses[indexPath.row].text
        cell.textLabel?.numberOfLines = 0
        cell.textLabel?.font = UIFont.preferredFont(forTextStyle: isCurrent ? .headline : .body)
        cell.textLabel?.adjustsFontForContentSizeCategory = true
        cell.backgroundColor = isCurrent ? UIColor.orange.withAlphaComponent(0.15) : .clear
        return cell
    }
}

Two accessibility points that matter especially for this audience:

Dynamic Type everywhere (preferredFont(forTextStyle:) with adjustsFontForContentSizeCategory). Many people reading a prayer app use larger text sizes.
Don't fight the user's scrolling. If they've scrolled away to read ahead, pause auto-scrolling for a few seconds. Detect it in scrollViewWillBeginDragging(_:).

Stop the display link when the view disappears or playback ends. A display link running in the background is wasted battery.

5. Lock Screen and Control Center

Once you're a real .playback app, people expect to control it from the Lock Screen, Control Center, headphones and the car. That's two APIs: MPNowPlayingInfoCenter (iOS 5+) for what's playing and MPRemoteCommandCenter (iOS 7.1+) for what the buttons do.

import MediaPlayer
import UIKit

final class NowPlayingController {
    private weak var audio: RecitationPlayer?

    init(audio: RecitationPlayer, title: String, artwork: UIImage?) {
        self.audio = audio
        configureCommands()
        var info: [String: Any] = [
            MPMediaItemPropertyTitle: title,
            MPMediaItemPropertyArtist: "Recitation",
            MPMediaItemPropertyPlaybackDuration: audio.player?.duration ?? 0
        ]
        if let artwork {
            info[MPMediaItemPropertyArtwork] =
                MPMediaItemArtwork(boundsSize: artwork.size) { _ in artwork }
        }
        MPNowPlayingInfoCenter.default().nowPlayingInfo = info
    }

    /// Call on play, pause and seek, not every frame. The system extrapolates
    /// elapsed time from the rate you give it.
    func update() {
        guard let player = audio?.player else { return }
        var info = MPNowPlayingInfoCenter.default().nowPlayingInfo ?? [:]
        info[MPNowPlayingInfoPropertyElapsedPlaybackTime] = player.currentTime
        info[MPNowPlayingInfoPropertyPlaybackRate] = player.isPlaying ? 1.0 : 0.0
        MPNowPlayingInfoCenter.default().nowPlayingInfo = info
    }

    private func configureCommands() {
        let center = MPRemoteCommandCenter.shared()

        center.playCommand.addTarget { [weak self] _ in
            try? self?.audio?.play(); self?.update(); return .success
        }
        center.pauseCommand.addTarget { [weak self] _ in
            self?.audio?.pause(); self?.update(); return .success
        }
        center.togglePlayPauseCommand.addTarget { [weak self] _ in
            guard let player = self?.audio?.player else { return .commandFailed }
            if player.isPlaying { self?.audio?.pause() } else { try? self?.audio?.play() }
            self?.update(); return .success
        }
        center.changePlaybackPositionCommand.addTarget { [weak self] event in
            guard let e = event as? MPChangePlaybackPositionCommandEvent else { return .commandFailed }
            self?.audio?.seek(to: e.positionTime); self?.update(); return .success
        }
        // Commands you don't support should be disabled, so the UI doesn't show dead buttons.
        center.nextTrackCommand.isEnabled = false
        center.previousTrackCommand.isEnabled = false
    }
}

MPMediaItemArtwork(boundsSize:requestHandler:) is iOS 10+, so it's fine on iOS 11. The scrubber on the Lock Screen needs changePlaybackPositionCommand (iOS 9.1+); without it, the scrubber is display-only.

Don't update Now Playing on every tick. Set elapsed time and rate on play, pause and seek, and the system animates the progress itself.

6. Interruptions and route changes

Real phones ring. Here are the two notifications every audio app must handle:

import AVFoundation

final class AudioInterruptionHandler {
    private weak var audio: RecitationPlayer?
    private var tokens: [NSObjectProtocol] = []
    private var wasPlaying = false
    var onChange: (() -> Void)?

    init(audio: RecitationPlayer) {
        self.audio = audio
        let center = NotificationCenter.default
        let session = AVAudioSession.sharedInstance()

        tokens.append(center.addObserver(forName: AVAudioSession.interruptionNotification,
                                         object: session, queue: .main) { [weak self] note in
            self?.handleInterruption(note)
        })
        tokens.append(center.addObserver(forName: AVAudioSession.routeChangeNotification,
                                         object: session, queue: .main) { [weak self] note in
            self?.handleRouteChange(note)
        })
    }

    deinit { tokens.forEach(NotificationCenter.default.removeObserver) }

    private func handleInterruption(_ note: Notification) {
        guard let raw = note.userInfo?[AVAudioSessionInterruptionTypeKey] as? UInt,
              let type = AVAudioSession.InterruptionType(rawValue: raw) else { return }
        switch type {
        case .began:
            wasPlaying = audio?.player?.isPlaying ?? false   // the system has already paused us
        case .ended:
            let optionsRaw = note.userInfo?[AVAudioSessionInterruptionOptionKey] as? UInt ?? 0
            if wasPlaying, AVAudioSession.InterruptionOptions(rawValue: optionsRaw).contains(.shouldResume) {
                try? audio?.play()
            }
            wasPlaying = false
        @unknown default: break
        }
        onChange?()
    }

    private func handleRouteChange(_ note: Notification) {
        guard let raw = note.userInfo?[AVAudioSessionRouteChangeReasonKey] as? UInt,
              let reason = AVAudioSession.RouteChangeReason(rawValue: raw) else { return }
        // Headphones unplugged / Bluetooth gone: pause, as Apple recommends for media apps,
        // instead of suddenly reciting out loud on the speaker.
        if reason == .oldDeviceUnavailable { audio?.pause(); onChange?() }
    }
}

Two version notes. The Swift names AVAudioSession.interruptionNotification and routeChangeNotification are the modern spellings; on the very oldest SDKs they were NSNotification.Name.AVAudioSessionInterruption and AVAudioSessionRouteChange. And Apple's current docs mark .shouldResume as deprecated in iOS 27 in favour of a newer resumption-recommendation mechanism. It still works on every version this app supports, so I've kept it here.

7. Real-world example: Hanuman Chalisa : Offline

This is the approach I'd use for Hanuman Chalisa : Offline, and for any text-plus-audio app.

At the time of writing, its App Store listing shows:

Free, in the Book and Music categories
First released in April 2020
22 ratings in the US store, averaging about 4.8 stars, the highest average among my apps with ten or more ratings
Supports iOS 11.0 and later, on iPhone, iPad and iPod touch

The listing describes the content simply: "This version has both Chalisa in English Language Script (for reading) and Audio." Here's how that maps to this article:

What the listing says	Where it's covered
"Hanuman Chalisa : Offline"	Text, cue sheet and audio all bundled; no network code at all (section 2)
"Chalisa in English Language Script (for reading)"	Unicode text with Dynamic Type in a table view (section 4)
"…and Audio"	`AVAudioPlayer` with a `.playback` session and background mode (section 3)
"The iPhone, iPod & iPad version"	UIKit-first code on long-standing APIs, iOS 11 and up (throughout)

I later built a much larger devotional app, Mandir Darshan, with live temple streams, the Bhagavad Gita and a chalisa collection. That one's a very different technical story, built on live streaming and picture-in-picture, and I'm covering it in its own article.

8. Before you ship a text-plus-audio app: a checklist

It works in Airplane Mode from a fresh install: text, audio and highlighting.
The category is .playback and the audio background mode is enabled, so audio survives the Silent switch and the Lock Screen.
The cue sheet is validated. Start times are sorted, and every verse has one. Assert it in debug builds.
Tapping a verse seeks the audio, and the highlight follows the audio, never the other way round.
Lock-screen controls work, including the scrubber, and unsupported commands are disabled.
A phone call pauses playback, and it resumes only if it was playing and the system says it may.
Unplugging headphones pauses playback.
Text respects Dynamic Type and VoiceOver. Test at the largest accessibility sizes.
The session is deactivated when playback finishes, with .notifyOthersOnDeactivation, so other audio can resume.

Wrapping up

A text-plus-audio app looks simple, and it can be, as long as you treat the audio session with respect. Bundle everything, describe timing with a tiny cue sheet, let AVAudioPlayer play, keep the highlight driven by currentTime, and give the system what it needs for the Lock Screen and for interruptions. It's well-established API, which is exactly why it still runs on iOS 11.

Try the app, or explore my other work:

Hanuman Chalisa : Offline (iOS): https://apps.apple.com/us/app/hanuman-chalisa-offline/id1509206340
All of my free iOS apps: https://apps.apple.com/us/developer/alok-singh/id1508795536
My portfolio: https://bestlatestapps.com/alok/

Have you built synchronised text and audio for lyrics, language lessons or audiobooks? I'd love to hear how you produced your timings. Tell me in the comments.

— Alok Kumar Singh

Originally published at https://bestlatestapps.com/blog/text-plus-audio-fully-offline/

Stop Hand-Rolling Unit Conversions: Foundation's Measurement, Dimension and MeasurementFormatter

Fri, 23 Oct 2026 14:38:22 +0000

Originally published at https://bestlatestapps.com/blog/stop-hand-rolling-unit-conversions/

Built-in units, custom dimensions, non-linear converters, locale-aware input and output, and the temperature trap that catches everyone

Every unit converter I've seen in a code review starts the same way: a dictionary of conversion factors, a switch on the category and a special case for temperature that someone added after the bug report. It works, until the third person adds a unit and gets one factor upside down.

My app Units Converter & Calculator converts across 30+ categories and 200+ units, completely offline. Alongside it sit a library of 180+ physical constants, learning modes and a conversion history. On a project like that, the conversion table becomes the code you trust least, unless you hand the job to Foundation.

Apple has shipped a proper units system since iOS 10: Measurement, Unit, Dimension and UnitConverter, plus MeasurementFormatter and the newer Measurement.FormatStyle for output. Most developers I talk to have never used more than UnitLength.meters. This article goes further: built-in units, custom dimensions for the categories Foundation doesn't cover, a non-linear converter, locale-correct input and output, the temperature-difference trap, and a sensible way to persist history. API names and availability are checked against Apple's documentation, and I describe the approach I'd use rather than claiming the app's exact internals.

1. Why conversion tables rot

A hand-written table has three problems:

N² relationships. If you store "A to B" factors, you need a factor for every pair. Add one unit and you owe the table N new entries.
Hidden non-linearity. Temperature has an offset; fuel economy is reciprocal (L/100 km vs mpg). These get special-cased, and special cases breed bugs.
Formatting is an afterthought. "1.0000000000002 km" shows up in the UI, and users in Germany type "1,5" and get an error.

Foundation's model fixes the first two by design: every unit in a dimension knows how to convert to and from that dimension's base unit. That's N relationships, not N². Converting A to B is always A → base → B. For the third problem, Foundation ships formatters that understand locales.

2. The basics: Measurement and built-in dimensions

import Foundation

let marathon = Measurement(value: 42.195, unit: UnitLength.kilometers)
let miles = marathon.converted(to: .miles)
print(miles.value)  // ≈ 26.219

// Arithmetic across units just works: both sides convert to the base unit first.
let total = Measurement(value: 1, unit: UnitLength.miles)
          + Measurement(value: 500, unit: UnitLength.meters)
print(total.converted(to: .kilometers))  // ≈ 2.109 km

// Comparison works across units too.
print(Measurement(value: 1, unit: UnitMass.kilograms)
      > Measurement(value: 2, unit: UnitMass.pounds))  // true

Foundation ships a little over twenty Dimension subclasses: length, mass, volume, area, speed, temperature, pressure, energy, power, duration, frequency, angle, acceleration, fuel efficiency, electric current, charge, potential difference and resistance, illuminance, concentration, dispersion and information storage (UnitInformationStorage, iOS 13+). Each has many units: UnitEnergy.kilowattHours, UnitSpeed.knots, UnitPressure.inchesOfMercury and so on.

For a converter UI, wrap the dimension in a small description type so a category screen can list its units generically:

struct UnitCategory: Identifiable {
    let id: String                 // stable key, e.g. "length"
    let name: String
    let units: [Dimension]
}

let length = UnitCategory(id: "length", name: "Length", units: [
    UnitLength.millimeters, UnitLength.centimeters, UnitLength.meters,
    UnitLength.kilometers, UnitLength.inches, UnitLength.feet,
    UnitLength.yards, UnitLength.miles, UnitLength.nauticalMiles
])

func convert(_ value: Double, from: Dimension, to: Dimension) -> Double {
    Measurement(value: value, unit: from).converted(to: to).value
}

Measurement<Dimension> works here because converted(to:) is available whenever UnitType is a Dimension. Just make sure from and to belong to the same dimension, because converting metres to kilograms is a programmer error that Foundation won't catch for you at compile time with this erased type.

3. Custom dimensions for what Foundation doesn't cover

Getting to 30+ categories means going beyond the built-ins: density, torque, data transfer rate, radiation dose, flow rate. A custom dimension is a Dimension subclass with a base unit and static units defined by UnitConverterLinear:

final class UnitDensity: Dimension {
    // Base unit: kilograms per cubic metre.
    static let kilogramsPerCubicMeter = UnitDensity(
        symbol: "kg/m³", converter: UnitConverterLinear(coefficient: 1))
    static let gramsPerCubicCentimeter = UnitDensity(
        symbol: "g/cm³", converter: UnitConverterLinear(coefficient: 1_000))
    static let gramsPerLiter = UnitDensity(
        symbol: "g/L", converter: UnitConverterLinear(coefficient: 1))
    static let poundsPerCubicFoot = UnitDensity(
        symbol: "lb/ft³", converter: UnitConverterLinear(coefficient: 16.018_463))

    override class func baseUnit() -> UnitDensity { kilogramsPerCubicMeter }
}

let water = Measurement(value: 1, unit: UnitDensity.gramsPerCubicCentimeter)
print(water.converted(to: .poundsPerCubicFoot).value)   // ≈ 62.43

The coefficient is "how many base units in one of this unit". One g/cm³ is 1,000 kg/m³, so its coefficient is 1,000. Get that sentence right and you'll never flip a factor again.

UnitConverterLinear(coefficient:constant:) also takes a constant, applied as base = value × coefficient + constant. That's how Foundation models Celsius and Fahrenheit against kelvin. You'll rarely need it for custom units, but it's there.

Write a round-trip test for every unit. It catches typos instantly:

import XCTest

final class DensityTests: XCTestCase {
    func testRoundTrip() {
        let units: [UnitDensity] = [.kilogramsPerCubicMeter, .gramsPerCubicCentimeter,
                                    .gramsPerLiter, .poundsPerCubicFoot]
        for a in units {
            for b in units {
                let x = Measurement(value: 123.456, unit: a)
                XCTAssertEqual(x.converted(to: b).converted(to: a).value, 123.456,
                               accuracy: 1e-9, "\(a.symbol) ↔ \(b.symbol)")
            }
        }
    }
}

Round-trips catch arithmetic mistakes, not wrong factors, so add one "known value" assertion per unit from a trusted reference too.

4. Non-linear conversions: write your own UnitConverter

Some relationships aren't a × x + b. The classic one is fuel economy: litres per 100 km and miles per gallon are reciprocals. Foundation's UnitFuelEfficiency already handles that internally, but you'll hit the same shape in your own categories. Runners, for example, want pace (minutes per kilometre) and speed (km/h) to convert into each other.

UnitConverter is an open class with two methods to override:

/// base = k / value, value = k / base
final class UnitConverterReciprocal: UnitConverter {
    private let k: Double
    init(reciprocal k: Double) { self.k = k }

    override func baseUnitValue(fromValue value: Double) -> Double {
        value == 0 ? .infinity : k / value
    }
    override func value(fromBaseUnitValue baseUnitValue: Double) -> Double {
        baseUnitValue == 0 ? .infinity : k / baseUnitValue
    }
}

final class UnitPace: Dimension {
    // Base unit: seconds per metre.
    static let secondsPerMeter = UnitPace(symbol: "s/m",
        converter: UnitConverterLinear(coefficient: 1))
    static let minutesPerKilometer = UnitPace(symbol: "min/km",
        converter: UnitConverterLinear(coefficient: 60.0 / 1_000))
    static let minutesPerMile = UnitPace(symbol: "min/mi",
        converter: UnitConverterLinear(coefficient: 60.0 / 1_609.344))
    // Speed expressed inside the pace dimension: s/m = 3.6 / (km/h)
    static let kilometersPerHour = UnitPace(symbol: "km/h",
        converter: UnitConverterReciprocal(reciprocal: 3.6))

    override class func baseUnit() -> UnitPace { secondsPerMeter }
}

let pace = Measurement(value: 5, unit: UnitPace.minutesPerKilometer)
print(pace.converted(to: .kilometersPerHour).value)  // 12.0
print(pace.converted(to: .minutesPerMile).value)     // ≈ 8.05

Guard against zero. A pace of 0 is a meaningless input, and .infinity displays far better than a crash.

5. Input and output that respect the user's locale

Parsing what the user typed

Double("1,5") is nil. In much of Europe, that's how you write one and a half. Parse with the user's locale:

struct LocalizedNumberParser {
    private let formatter: NumberFormatter

    init(locale: Locale = .current) {
        formatter = NumberFormatter()
        formatter.locale = locale
        formatter.numberStyle = .decimal
        formatter.isLenient = true
    }

    func parse(_ text: String) -> Double? {
        let trimmed = text.trimmingCharacters(in: .whitespaces)
        guard !trimmed.isEmpty else { return nil }
        return formatter.number(from: trimmed)?.doubleValue
    }
}

Pair it with .keyboardType(.decimalPad), which shows the locale's decimal separator automatically.

Formatting the result

Raw doubles leak floating-point noise. Measurement.FormatStyle (iOS 15+) formats value and unit together, localised, with the precision you choose:

let result = Measurement(value: 26.218_757_5, unit: UnitLength.miles)

let text = result.formatted(.measurement(
    width: .abbreviated,
    usage: .asProvided,                       // keep the unit the user chose
    numberFormatStyle: .number.precision(.significantDigits(1...6))
))
// "26.2188 mi" in en_US; "26,2188 mi" in de_DE

Two options matter for a converter:

usage: .asProvided. Without it, formatters may "helpfully" switch to the locale's preferred unit. That's great in a weather app and wrong in a converter.
Significant digits, not fixed decimals. 0.000 012 3 and 12,300,000 both deserve a readable result.

On iOS 10–14, MeasurementFormatter with unitOptions = .providedUnit gives the same "don't switch my unit" behaviour.

Custom units format fine too. Their symbol is used, so choose symbols you're happy to show on screen.

6. The temperature trap: points vs differences

Here's a bug that ships in real apps:

let delta = Measurement(value: 10, unit: UnitTemperature.celsius)
print(delta.converted(to: .fahrenheit).value)   // 50.0

If the user meant "it's 10 °C outside", 50 °F is right. If they meant "the temperature rose by 10 °C", the answer is 18 °F: a difference doesn't carry the 32° offset.

Foundation's UnitTemperature models points on a scale. For differences, convert with the coefficient only:

enum TemperatureDelta {
    /// Kelvin-sized steps per unit: 1 °C step = 1 K, 1 °F step = 5/9 K.
    static func convert(_ value: Double, from: UnitTemperature, to: UnitTemperature) -> Double {
        func coefficient(_ u: UnitTemperature) -> Double {
            (u.converter as? UnitConverterLinear)?.coefficient ?? 1
        }
        return value * coefficient(from) / coefficient(to)
    }
}

print(TemperatureDelta.convert(10, from: .celsius, to: .fahrenheit))  // 18.0

In the UI, a "temperature difference" toggle, or a separate category, makes the intent explicit. It's a good teaching moment for a learning-focused app too.

7. History, constants and challenges

Persisting history with stable keys

Measurement is Codable, but I don't persist units by trusting the encoded symbol: symbols can change, and custom units need to come back as your static instances. Store your own stable IDs instead:

struct ConversionRecord: Codable, Identifiable {
    var id = UUID()
    let categoryID: String     // "length"
    let fromUnitID: String     // "km"
    let toUnitID: String       // "mi"
    let input: Double
    let date: Date
}

// A registry maps IDs back to Dimension instances.
enum UnitRegistry {
    static let length: [String: UnitLength] = [
        "m": .meters, "km": .kilometers, "mi": .miles, "ft": .feet, "in": .inches
    ]
}

Recompute the output on display, rather than storing it. If you ever fix a factor, old history entries silently become correct.

Constants are data, not code

A library of physical constants is a bundled JSON file: name, symbol, value, unit, uncertainty, plus the explanatory text. Use exact CODATA values. Since the 2019 SI redefinition, constants such as the speed of light, Planck's constant and the elementary charge are exact by definition, which is a nice fact to surface in a "why it's important" field.

Challenge mode: scoring an estimate

For estimation games ("how many feet in a kilometre?"), score by ratio, not absolute difference, so being off by 10% feels the same at every scale:

/// 100 for a perfect answer, falling to 0 at a factor-of-two error.
func estimationScore(guess: Double, truth: Double) -> Int {
    guard guess > 0, truth > 0 else { return 0 }
    let error = abs(log2(guess / truth))    // 0 = exact, 1 = off by 2×
    return Int((max(0, 1 - error) * 100).rounded())
}

8. Real-world example: Units Converter & Calculator

These are the techniques I'd use, and recommend, for a converter like Units Converter & Calculator.

At the time of writing, its App Store listing shows:

Free, in Productivity and Education
First released in May 2020
32 ratings in the US store, averaging about 4.7 stars
Supports iOS 16.0 and later

How the listing lines up with this article:

What the listing says	Where it's covered
"Convert 200+ units across 30+ categories… completely offline"	Built-in dimensions plus custom `Dimension` subclasses, all on-device (sections 2–4)
"Real-time conversions with instant results"	Locale-aware parsing on every keystroke, formatted output (section 5)
"180+ physical constants with detailed explanations"	Constants as bundled data (section 7)
"Challenge Mode: Test your estimation skills"	Ratio-based scoring (section 7)
"Automatic saving of all conversions… Organized by category"	History with stable unit IDs, output recomputed on display (section 7)

The listing's audience is "students learning physics and chemistry, engineers and scientists". That's exactly the audience that will notice a wrong factor or a temperature-delta mistake, and the reason I lean on Foundation rather than hand-written tables.

9. Before you ship a unit converter: a checklist

Every unit has a round-trip test and at least one known-value test from a trusted reference.
The coefficient means "base units per one of this unit", and it's written that way everywhere.
Non-linear units use a real UnitConverter subclass, and zero and negative inputs are handled.
Input parsing uses the user's locale, and the decimal-pad keyboard matches it.
Output uses significant digits and usage: .asProvided (or .providedUnit), so the unit the user picked is the unit they see.
Temperature differences are a separate, explicit mode.
History stores IDs and inputs, not outputs, so fixes apply retroactively.
Everything works in Airplane Mode, including constants and learning content.

Wrapping up

Unit conversion is one of those problems that looks like a lookup table and is really a type system. Foundation's Measurement and Dimension give you that type system: one base unit per dimension, linear and custom converters, unit-aware arithmetic and comparisons, and formatters that respect the user's locale. Add custom dimensions for whatever Foundation doesn't cover, test every unit, and treat temperature differences with suspicion.

Try the app, or browse the rest of my work:

Units Converter & Calculator (iOS): https://apps.apple.com/us/app/units-converter-calculator/id1515811220
All of my free iOS apps: https://apps.apple.com/us/developer/alok-singh/id1508795536
My portfolio: https://bestlatestapps.com/alok/

Which unit has bitten you in production? For me, temperature differences top the list. Let me know in the comments.

— Alok Kumar Singh

Originally published at https://bestlatestapps.com/blog/stop-hand-rolling-unit-conversions/

The Device Side of APNs: Building a Push Notification Test Client in Swift

Fri, 23 Oct 2026 12:43:45 +0000

Originally published at https://bestlatestapps.com/blog/the-device-side-of-apns/

Permission, registration, device tokens, foreground presentation and payload inspection, plus the exact HTTP/2 request your backend needs to send

Every backend developer who has implemented Apple push notifications knows this moment. The server code is written and the request goes out. APNs answers 200, and nothing appears on the phone. Or APNs answers 400 BadDeviceToken, and you have no idea whether the problem is your token, your certificate, your environment or your JSON.

The hard part is that the backend developer usually doesn't own the iOS app. They have to ask the mobile team for a build, a device token and the right certificate, and then wait again every time something changes.

That's why I built Push Notification – Client, a small iPhone app with one job: be a known-good receiver. It hands you a device token, a bundle identifier and a certificate, so you can point your server code at it and see exactly what arrives. It's been on the App Store since June 2020 and is one of my more popular developer tools.

This article covers both halves of that loop. First, the device side: what an iOS app has to do to receive a push, written so you can build your own test client. Then the server side: the exact request APNs expects, and the error codes you'll see when it's wrong. I've checked API names, header names and limits against Apple's documentation.

1. How a push actually travels

It helps to have the whole picture before writing code:

┌──────────┐ 1. register  ┌──────┐
│ iOS app  │─────────────▶│ APNs │
│          │◀─────────────│      │ 2. device token
└────┬─────┘              └──▲───┘
     │ 3. send token           │ 5. HTTP/2 POST /3/device/<token>
     ▼                         │    (cert or JWT, topic = bundle ID)
┌──────────────────────────────┴──┐
│ Your provider server            │ 4. store token
└─────────────────────────────────┘
               6. APNs delivers to the device → system shows it / app handles it

Three identities have to line up for delivery to work:

The app's bundle ID is the APNs topic.
The environment. A development build gets a sandbox token; an App Store or TestFlight build gets a production token. Tokens aren't interchangeable.
The credential. A push certificate for that bundle ID, or a token-signing key from the same team.

Most "it doesn't arrive" bugs are one of these three not matching. A test client makes all three visible.

2. Capabilities and permission

In Xcode, add the Push Notifications capability. This adds the aps-environment entitlement, whose value (development or production) is set by your signing. If you want to test silent pushes too, add Background Modes → Remote notifications.

Then ask for permission. UNUserNotificationCenter.requestAuthorization(options:) (iOS 10+) has an async form:

import UserNotifications
import UIKit

enum PushPermission {
    /// Returns true if the user allowed alerts, sounds or badges.
    @MainActor
    static func request() async -> Bool {
        let center = UNUserNotificationCenter.current()
        do {
            let granted = try await center.requestAuthorization(options: [.alert, .sound, .badge])
            // Register even if denied: you still get a token,
            // and silent (background) pushes don't need alert permission.
            UIApplication.shared.registerForRemoteNotifications()
            return granted
        } catch {
            print("Authorization request failed: \(error)")
            return false
        }
    }

    static func currentStatus() async -> UNAuthorizationStatus {
        await UNUserNotificationCenter.current().notificationSettings().authorizationStatus
    }
}

Two details people often miss:

Registering and authorising are separate. registerForRemoteNotifications() gets you a device token whether or not the user allows alerts. Permission decides only how a push is shown.
Provisional authorisation (.provisional, iOS 12+) delivers quietly to Notification Center without prompting. For a test tool I want the real prompt, because I want the full alert, but provisional is worth knowing about for consumer apps.

3. Getting and showing the device token

APNs returns the token to your app delegate as raw Data. Servers expect a lowercase hex string. Getting this conversion wrong (for example, using description on the Data) is the classic cause of BadDeviceToken.

In a SwiftUI app you wire the app delegate in with @UIApplicationDelegateAdaptor (iOS 14+):

import SwiftUI
import UserNotifications

@MainActor
final class PushModel: ObservableObject {
    static let shared = PushModel()
    @Published var deviceToken: String?
    @Published var registrationError: String?
    @Published var received: [ReceivedPush] = []
}

struct ReceivedPush: Identifiable {
    let id = UUID()
    let date = Date()
    let json: String
}

final class AppDelegate: NSObject, UIApplicationDelegate, UNUserNotificationCenterDelegate {

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
        UNUserNotificationCenter.current().delegate = self
        return true
    }

    func application(_ application: UIApplication,
                     didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        let hex = deviceToken.map { String(format: "%02x", $0) }.joined()
        Task { @MainActor in PushModel.shared.deviceToken = hex }
    }

    func application(_ application: UIApplication,
                     didFailToRegisterForRemoteNotificationsWithError error: Error) {
        // Common on the Simulator without a configured environment,
        // or when the entitlement is missing.
        Task { @MainActor in PushModel.shared.registrationError = error.localizedDescription }
    }
}

@main
struct PushClientApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) private var appDelegate

    var body: some Scene {
        WindowGroup { ContentView().environmentObject(PushModel.shared) }
    }
}

The token screen should make the token trivially easy to get off the phone: a big monospaced label, a Copy button (UIPasteboard.general.string = token) and a Share button (ShareLink(item: token)). Show the bundle ID next to it (Bundle.main.bundleIdentifier), plus a clear label for the environment this build uses, because the person on the other end will need all three.

One more rule: treat the token as changeable. The system can issue a new one, for example after a restore to a new device. Real apps send it to their server on every launch, not only the first.

4. Seeing pushes while the app is open

By default, if your app is in the foreground when a push arrives, iOS doesn't show a banner. For a test client that's backwards: the user is staring at the app, waiting for the push. Implement userNotificationCenter(_:willPresent:withCompletionHandler:) and ask for a banner anyway. While you're there, capture the payload so you can show it.

extension AppDelegate {

    // Foreground delivery: show it AND log it.
    func userNotificationCenter(_ center: UNUserNotificationCenter,
                                willPresent notification: UNNotification,
                                withCompletionHandler completionHandler:
                                    @escaping (UNNotificationPresentationOptions) -> Void) {
        log(notification.request.content.userInfo)
        completionHandler([.banner, .list, .sound, .badge])
    }

    // The user tapped a notification (app was in background or not running).
    func userNotificationCenter(_ center: UNUserNotificationCenter,
                                didReceive response: UNNotificationResponse,
                                withCompletionHandler completionHandler: @escaping () -> Void) {
        log(response.notification.request.content.userInfo)
        completionHandler()
    }

    // Silent pushes ("content-available": 1) arrive here, if Background Modes allows it.
    func application(_ application: UIApplication,
                     didReceiveRemoteNotification userInfo: [AnyHashable: Any],
                     fetchCompletionHandler completionHandler:
                        @escaping (UIBackgroundFetchResult) -> Void) {
        log(userInfo)
        completionHandler(.newData)
    }

    private func log(_ userInfo: [AnyHashable: Any]) {
        // userInfo is the decoded JSON payload. Re-serialise it so you see exactly what arrived.
        let dict = Dictionary(uniqueKeysWithValues: userInfo.map { ("\($0.key)", $0.value) })
        let data = (try? JSONSerialization.data(withJSONObject: dict,
                                                options: [.prettyPrinted, .sortedKeys])) ?? Data()
        let json = String(decoding: data, as: UTF8.self)
        Task { @MainActor in PushModel.shared.received.insert(ReceivedPush(json: json), at: 0) }
    }
}

.banner and .list are iOS 14+. They replaced the older .alert option.

Showing the raw JSON is the single most useful debugging feature in a test client. Half the "my custom data didn't arrive" bugs turn out to be a backend nesting a key inside aps that belongs outside it, or the other way round.

5. Payload anatomy, and the limits that bite

A push payload is a JSON dictionary with an aps key for Apple-defined fields. Your own data goes alongside aps, never inside it:

{
  "aps": {
    "alert": { "title": "Order shipped", "body": "Your parcel is on its way." },
    "sound": "default",
    "badge": 1,
    "thread-id": "orders",
    "interruption-level": "active"
  },
  "orderId": "A-1042"
}

The fields I test most often:

alert: a string, or a dictionary with title, subtitle and body.
content-available: 1: a background (silent) push. Apple's docs say to omit alert, badge and sound for a silent update, and to send it with apns-push-type: background and apns-priority: 5.
mutable-content: 1: sends the push through your Notification Service Extension (UNNotificationServiceExtension, iOS 10+) before it's shown. This is how you attach images or decrypt content.
interruption-level: passive, active, time-sensitive or critical. Time-sensitive needs its own capability; critical needs an entitlement from Apple.

And the hard limit: 4 KB (4,096 bytes) for a normal remote notification (VoIP pushes get 5 KB). Over that, APNs answers 413 PayloadTooLarge. Push an ID and fetch the details; don't push the whole document.

6. The other half: what your server sends

Here's the request in its plainest form. APNs uses HTTP/2 over TLS 1.2 or later, at api.sandbox.push.apple.com (development) or api.push.apple.com (production), on port 443 (or 2197).

With a certificate (the listing's flow: use the device token, bundle ID and certificate from the app), curl is enough to prove the pipeline end to end:

TOKEN=<hex device token from the app>
TOPIC=<bundle id shown in the app>

curl -v --http2 \
  --cert-type P12 --cert ./push-cert.p12:<p12-password> \
  -H "apns-topic: ${TOPIC}" \
  -H "apns-push-type: alert" \
  -H "apns-priority: 10" \
  -d '{"aps":{"alert":{"title":"Hello","body":"From curl"},"sound":"default"}}' \
  "https://api.sandbox.push.apple.com/3/device/${TOKEN}"

With token-based auth, you sign a short JWT with your .p8 key instead. Apple's docs require ES256, a 10-character key ID (kid) and your team ID (iss). Refresh the token no more than once every 20 minutes and no less than once every 60. In Python, with PyJWT and httpx[http2]:

import time, jwt, httpx

TEAM_ID, KEY_ID = "ABCDE12345", "FGHIJ67890"
P8 = open("AuthKey_FGHIJ67890.p8").read()

def provider_token() -> str:
    # Cache this and reuse it for ~30-50 minutes; don't mint one per request.
    return jwt.encode({"iss": TEAM_ID, "iat": int(time.time())}, P8,
                      algorithm="ES256", headers={"kid": KEY_ID})

def send(device_token: str, topic: str, payload: dict, sandbox: bool = True):
    host = "api.sandbox.push.apple.com" if sandbox else "api.push.apple.com"
    with httpx.Client(http2=True) as client:
        r = client.post(f"https://{host}/3/device/{device_token}", json=payload, headers={
            "authorization": f"bearer {provider_token()}",
            "apns-topic": topic,
            "apns-push-type": "alert",
            "apns-priority": "10",
        })
    print(r.status_code, r.headers.get("apns-id"), r.text)

The app's listing includes guidance and code examples for Java, Go, Python, Ruby, Erlang and Node.js. The shape is the same in every language: an HTTP/2 POST to /3/device/<token>, the topic header, the push-type header, and either a client certificate or a bearer token.

7. Reading APNs errors like a checklist

When it fails, APNs tells you why, in a JSON body with a reason. These are the ones I see most, straight from Apple's response table:

Status	`reason`	What it usually means
400	`BadDeviceToken`	Token is malformed, or doesn't match the environment (sandbox token sent to production, or vice versa)
400	`DeviceTokenNotForTopic`	The token belongs to a different bundle ID than your `apns-topic`
400	`TopicDisallowed` / `BadTopic`	The topic isn't one your credential may push to
403	`BadCertificateEnvironment`	Development certificate against the production host, or the reverse
403	`ExpiredProviderToken` / `InvalidProviderToken`	JWT too old (over an hour), or signed with the wrong key, key ID or team
410	`Unregistered` / `ExpiredToken`	The token is no longer active: stop sending to it
413	`PayloadTooLarge`	Over 4 KB
429	`TooManyRequests`	Too many pushes to the same token; back off

Apple's docs are explicit that you shouldn't retry BadDeviceToken, DeviceTokenNotForTopic, Forbidden, ExpiredToken, Unregistered or PayloadTooLarge; only TooManyRequests is worth retrying after a delay. And a 200 means APNs accepted the push, not that the device displayed it. That's precisely the gap a test client closes.

8. Real-world example: Push Notification – Client

This is what Push Notification – Client is for. The code above is the approach I'd use to build any receiver like it; I'm describing the technique rather than publishing the app's source.

At the time of writing, its App Store listing shows:

Free, in Developer Tools and Utilities
First released in June 2020
58 ratings in the US store, averaging about 4.1 stars
Supports iOS 17.6 and later

The listing describes it in one line: "Test your server-side APNS implementation by sending push notifications to this testing app." Mapping that to the sections above:

What the listing says	Where it's covered
"Simply use the device token, bundle identifier, and certificate provided through the app"	Token capture and display (section 3), the three identities (section 1), certificate-based `curl` (section 6)
"Guidelines with code examples… Java, Go, Python, Ruby, Erlang, Node.js"	The request shape in section 6, which is identical across languages
"Perfect for backend and server-side developers… who want to test their code"	Foreground presentation and raw-payload logging (section 4), the error table (section 7)

It has a sibling on the Mac: Push Notification – Tester sends APNs pushes from your Mac using a certificate from Keychain, with no server at all. Between the two you can test both ends of the pipe. I'm writing up the Mac side, Keychain identities and client-certificate auth in URLSession, as a separate article.

9. Before you ship push notifications: a checklist

The capability and entitlement are present in every target that needs them, and your build's aps-environment matches the APNs host your server uses.
The token is hex-encoded correctly, sent to your server on every launch, and replaced when it changes.
Foreground behaviour is deliberate. willPresent returns the options you actually want; don't leave it to the default.
Custom data sits outside aps, and the whole payload is comfortably under 4 KB.
Silent pushes are silent. content-available: 1, no alert, badge or sound, apns-push-type: background, priority 5. Don't rely on them for anything critical; the system may throttle them.
Server credentials are rotated safely. JWTs are cached and refreshed every 20–60 minutes; certificates have a calendar reminder before they expire.
Errors drive cleanup. On 410 Unregistered, delete the token. On BadDeviceToken, check the environment before blaming the token.
You've tested on a real device in both environments: a development build and a TestFlight build.

Wrapping up

Push notifications are a three-party protocol, and when it breaks the problem is usually a mismatched identity, not your code. Build the device side once, properly: permission, registration, a correctly encoded token, foreground presentation and raw-payload logging. The server side then becomes a single, well-understood HTTP/2 request with a readable error table.

If you'd rather skip building the receiver, the apps are free:

Push Notification – Client (iOS): https://apps.apple.com/us/app/push-notification-client/id1516378834
Push Notification – Tester (Mac): https://apps.apple.com/us/app/push-notification-tester/id1516154713
All of my free apps: https://apps.apple.com/us/developer/alok-singh/id1508795536
My portfolio: https://bestlatestapps.com/alok/

What's the strangest APNs bug you've chased? The one I hear about most is a perfectly valid sandbox token sent to the production host. Tell me yours in the comments.

— Alok Kumar Singh

Originally published at https://bestlatestapps.com/blog/the-device-side-of-apns/

The Sending Side of APNs: A Mac Push Tester with Keychain Certificates and URLSession Client Auth

Fri, 23 Oct 2026 12:31:01 +0000

Originally published at https://bestlatestapps.com/blog/the-sending-side-of-apns/

Finding push certificates in the Keychain, importing .p12 files, answering APNs's client-certificate challenge in URLSession, building the exact request (path, headers, payload), sandbox vs production, silent pushes, and reading APNs's error responses, all without a server

In my article on Push Notification – Client, I covered the device side of APNs: permission, registration, device tokens and showing what arrives. This is the other end of the pipe.

When you're building push notifications, the slowest part of the loop is often the sending side. The backend isn't ready. Or it's owned by another team, or every test means deploying a change to a server just to see whether a payload renders. Push Notification – Tester is my Mac app for skipping all of that. You choose a push certificate from Keychain, paste a device token, write a JSON payload, pick Development (sandbox) or Production, and send. There's no server dependency.

This article shows how a tool like that works under the hood. It's all standard Apple API: the Security framework to find identities, URLSession to authenticate with a client certificate over HTTP/2, and Apple's documented APNs request format. The protocol facts are taken from Apple's APNs documentation. Where I describe how I'd build something rather than the shipped app, I say so.

1. Two ways to authenticate with APNs, and why a tester uses certificates

APNs accepts two kinds of provider authentication:

Token-based (a .p8 signing key): you sign a short-lived JWT and send it in an authorization: bearer … header. One key works for all your apps.
Certificate-based (a push certificate, often exported as .p12): the TLS connection itself proves who you are, using a client certificate.

Apple's docs show both. For a desktop testing tool, certificates have a practical advantage: developers already have them in their Keychain, and the whole authentication step happens in the TLS handshake. Nothing needs to be signed per request.

One consequence, straight from Apple's documentation of the request headers: the authorization: bearer <provider_token> header is for token auth only, and "APNs ignores this header if you use certificate-based authentication." apns-topic is still required: "In general, the topic is your app's bundle ID/app ID." Keep the two modes clearly separate in your code.

2. Finding push identities in the Keychain

An identity in Keychain terms is a certificate plus its private key, which is what TLS client auth needs. SecItemCopyMatching with kSecClassIdentity lists them. I'd filter to push certificates by their subject summary, which for APNs certificates names the push service and your bundle ID:

import Security
import Foundation

struct PushIdentity: Identifiable, Hashable {
    let id: String              // subject summary, also used as the display name
    let identity: SecIdentity
    var isProbablyPush: Bool { id.localizedCaseInsensitiveContains("Push") }
}

enum KeychainIdentities {
    static func all() -> [PushIdentity] {
        let query: [String: Any] = [
            kSecClass as String: kSecClassIdentity,
            kSecReturnRef as String: true,
            kSecMatchLimit as String: kSecMatchLimitAll
        ]
        var result: CFTypeRef?
        guard SecItemCopyMatching(query as CFDictionary, &result) == errSecSuccess,
              let identities = result as? [SecIdentity] else { return [] }

        return identities.compactMap { identity in
            var cert: SecCertificate?
            guard SecIdentityCopyCertificate(identity, &cert) == errSecSuccess, let cert,
                  let summary = SecCertificateCopySubjectSummary(cert) as String? else { return nil }
            return PushIdentity(id: summary, identity: identity)
        }
        .sorted { ($0.isProbablyPush ? 0 : 1, $0.id) < ($1.isProbablyPush ? 0 : 1, $1.id) }
    }
}

Sorting push certificates to the top and keeping the others is deliberate. Names vary by certificate type and era, and a tester that hides the one certificate you need is worse than one that shows a few extras.

3. Importing a .p12 file

The listing mentions ".p12 / .pem workflows". For a .p12 (PKCS #12), the Security framework does the parsing. SecPKCS12Import returns the identity inside, given the export password:

enum P12Import {
    enum Failure: Error { case wrongPassword, noIdentity, status(OSStatus) }

    static func identity(from data: Data, password: String) throws -> SecIdentity {
        let options = [kSecImportExportPassphrase as String: password] as CFDictionary
        var items: CFArray?
        let status = SecPKCS12Import(data as CFData, options, &items)
        switch status {
        case errSecSuccess: break
        case errSecAuthFailed: throw Failure.wrongPassword
        default: throw Failure.status(status)
        }
        guard let first = (items as? [[String: Any]])?.first,
              let identity = first[kSecImportItemIdentity as String] else { throw Failure.noIdentity }
        return identity as! SecIdentity      // CF type bridging: the dictionary value is a SecIdentity
    }
}

A clear "wrong password" message matters more than it looks. It's by far the most common failure when importing a .p12, and a generic error code makes people think the certificate itself is broken.

.pem files hold the certificate and key as text. The approach I'd recommend is to convert them to .p12 with openssl pkcs12 -export and import that. The import path then stays the same either way.

4. Answering the client-certificate challenge in URLSession

When URLSession connects to APNs, the server asks for a client certificate. You answer in a delegate method by building a URLCredential from the identity:

import Foundation

final class APNsClient: NSObject, URLSessionDelegate {
    private let identity: SecIdentity
    private lazy var session = URLSession(configuration: .ephemeral, delegate: self, delegateQueue: nil)

    init(identity: SecIdentity) { self.identity = identity }

    func urlSession(_ session: URLSession, didReceive challenge: URLAuthenticationChallenge,
                    completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void) {
        switch challenge.protectionSpace.authenticationMethod {
        case NSURLAuthenticationMethodClientCertificate:
            let credential = URLCredential(identity: identity, certificates: nil, persistence: .forSession)
            completionHandler(.useCredential, credential)
        default:
            // Server trust etc.: let the system evaluate Apple's certificate normally.
            completionHandler(.performDefaultHandling, nil)
        }
    }
}

Two notes:

Use a session-level delegate. The client-certificate challenge is a connection-level challenge, delivered to urlSession(_:didReceive:completionHandler:). There's also a task-level variant; implement the session one at minimum.
Don't override server trust. .performDefaultHandling for everything else means the system still validates Apple's server certificate. A testing tool is no excuse to disable TLS validation.

URLSession negotiates HTTP/2 automatically with servers that support it, and APNs requires HTTP/2 and TLS 1.2 or later. You don't need a custom HTTP/2 library.

5. Building the request: path, headers, payload

Apple's documentation spells out the request precisely: a POST to /3/device/<device token> on one of two hosts. I'd model it directly:

enum APNsEnvironment: String, CaseIterable {
    case development, production
    var host: String {
        switch self {
        case .development: "api.sandbox.push.apple.com"
        case .production:  "api.push.apple.com"
        }
    }
}

enum PushType: String, CaseIterable { case alert, background }

struct PushRequest {
    var environment: APNsEnvironment
    var deviceToken: String
    var topic: String                 // usually your bundle ID
    var pushType: PushType
    var payloadJSON: String

    func urlRequest() throws -> URLRequest {
        let token = deviceToken.filter(\.isHexDigit).lowercased()   // tolerate pasted spaces and <>
        var request = URLRequest(url: URL(string: "https://\(environment.host)/3/device/\(token)")!)
        request.httpMethod = "POST"
        request.setValue(topic, forHTTPHeaderField: "apns-topic")
        request.setValue(pushType.rawValue, forHTTPHeaderField: "apns-push-type")
        request.setValue(pushType == .background ? "5" : "10", forHTTPHeaderField: "apns-priority")
        request.setValue(UUID().uuidString.lowercased(), forHTTPHeaderField: "apns-id")

        let body = Data(payloadJSON.utf8)
        _ = try JSONSerialization.jsonObject(with: body)          // fail fast on invalid JSON
        guard body.count <= 4096 else { throw PushError.payloadTooLarge(body.count) }
        request.httpBody = body
        return request
    }
}

enum PushError: Error { case payloadTooLarge(Int) }

Each line maps to Apple's documentation:

Hosts. api.sandbox.push.apple.com is the development server and api.push.apple.com is production. A device token from a debug build only works against the sandbox, which is the single most common "my push never arrives" cause.
apns-push-type. It must "accurately reflect the contents of your notification's payload". It's required for watchOS and recommended for iOS, macOS, tvOS and iPadOS.
Payload size. Apple's docs say it's limited to "a maximum size of 4 KB (4096 bytes)", and must not be compressed. Checking it locally saves a round trip and a 413 response.
apns-id. It's optional, but setting your own UUID makes it easy to match a response to a request in your log.

6. Alerts, badges, sounds and silent pushes

The listing promises "Custom JSON payloads for alerts, badges, sounds, and silent content". I'd offer templates for each, since the shape of aps is where most mistakes happen:

enum PayloadTemplate: String, CaseIterable {
    case alert, badge, sound, silent

    var json: String {
        switch self {
        case .alert:  #"{ "aps": { "alert": { "title": "Hello", "body": "From my Mac" } } }"#
        case .badge:  #"{ "aps": { "badge": 3 } }"#
        case .sound:  #"{ "aps": { "alert": "Ding", "sound": "default" } }"#
        case .silent: #"{ "aps": { "content-available": 1 }, "refresh": "inbox" }"#
        }
    }
    var pushType: PushType { self == .silent ? .background : .alert }
}

The silent template follows Apple's "Pushing background updates to your app" guide: the aps dictionary contains only content-available, with custom keys alongside it, and the request uses apns-push-type: background with apns-priority: 5. The same guide warns that the system treats background notifications as low priority and "doesn't guarantee their delivery", and may throttle them. A tester should say that in the UI, so nobody spends an afternoon debugging a throttled silent push.

7. Sending, and reading APNs's answer

APNs replies with an HTTP status and, on failure, a small JSON body with a reason. Surfacing that reason verbatim is the most useful thing a tester does:

extension APNsClient {
    struct Outcome { let status: Int; let apnsID: String?; let reason: String? }

    func send(_ push: PushRequest) async throws -> Outcome {
        let (data, response) = try await session.data(for: try push.urlRequest())
        let http = response as! HTTPURLResponse
        let reason = (try? JSONSerialization.jsonObject(with: data) as? [String: Any])?["reason"] as? String
        return Outcome(status: http.statusCode,
                       apnsID: http.value(forHTTPHeaderField: "apns-id"),
                       reason: reason)
    }
}

And a human explanation for the common reasons, taken from Apple's "Handling notification responses from APNs":

Status / reason	What it means in practice
`200`	Accepted by APNs. Delivery to the device is a separate step.
`400 BadDeviceToken`	The token is invalid. Usually a sandbox token sent to production, or the reverse; Apple says to check "that the token matches the environment".
`403 BadCertificate` / `BadCertificateEnvironment`	The certificate is invalid, or doesn't match the server you chose.
`410 Unregistered` / `ExpiredToken`	"The device token is inactive for the specified topic", or has expired. Typically the app was deleted or the token changed; stop sending to it.
`413 PayloadTooLarge`	Over 4 KB.
`429 TooManyRequests`	Too many pushes to the same token. Apple says you can retry with a delay.

Apple's guidance is explicit that you shouldn't retry BadDeviceToken, DeviceTokenNotForTopic, Forbidden, ExpiredToken, Unregistered or PayloadTooLarge. A tester can turn that into a "fix this first" hint instead of a Retry button.

8. Real-world example: Push Notification - Tester

This is the approach behind Push Notification - Tester. The code above is written for this article, not the app's source.

At the time of writing, its Mac App Store listing shows:

Free, in Developer Tools
First released in June 2020
No ratings yet in the US store
Requires macOS 14.6 or later

How the listing maps to this article:

What the listing says	Where it's covered
"Select the push certificate directly from Keychain (.p12 / .pem workflows)"	Keychain identities and PKCS #12 import (sections 2–3)
"Send APNs pushes from your Mac with no server dependency"	`URLSession` client-certificate auth over HTTP/2 (section 4)
"Paste any device token and send in seconds"	Token clean-up and the request path (section 5)
"Target Development (sandbox) or Production environments"	The two APNs hosts (section 5)
"Custom JSON payloads for alerts, badges, sounds, and silent content"	Payload templates and silent-push rules (section 6)
"Perfect for verifying device tokens, validating certificates…"	Reading APNs's status and reason (section 7)

Pair it with its iOS sibling, Push Notification – Client, which shows the device token to paste and displays what arrives. Between the two, you can test both ends without a backend.

9. Before you trust a push test: a checklist

The environment matches the build. Debug and development builds use the sandbox; TestFlight and App Store builds use production.
The topic is the bundle ID the certificate was issued for.
apns-push-type matches the payload: alert for visible pushes, background (priority 5) for silent ones.
The payload is valid JSON, under 4,096 bytes, and not compressed.
Server trust is never disabled. Only answer the client-certificate challenge.
The reason string is read, and non-retryable errors aren't retried.
Silent pushes aren't expected to be guaranteed. Throttling is normal.
Certificates expire. Check the expiry date when you pick an identity.
For production backends, consider token-based (.p8) auth. Certificates are handy for testing, but tokens don't need yearly renewal.

Wrapping up

Sending a push is less magic than it seems: an identity from the Keychain, a credential in a URLSession delegate, and a POST to /3/device/<token> with four headers and a small JSON body. A good tester makes each step visible and turns APNs's terse reasons into plain advice, so the next time a push "doesn't arrive", you know within a minute whether it's the token, the environment, the certificate or the payload.

Try the app, or explore my other work:

Push Notification - Tester (Mac): https://apps.apple.com/us/app/push-notification-tester/id1516154713
Push Notification – Client (iOS): https://apps.apple.com/us/app/push-notification-client/id1516378834
All of my apps: https://apps.apple.com/us/developer/alok-singh/id1508795536
My portfolio: https://bestlatestapps.com/alok/

What's the strangest push-delivery bug you've chased? Share it in the comments.

— Alok Kumar Singh

Originally published at https://bestlatestapps.com/blog/the-sending-side-of-apns/

Tic Tac Toe in SwiftUI, Done Properly: Game State, Win Detection and Minimax AI

Fri, 23 Oct 2026 12:02:18 +0000

Originally published at https://bestlatestapps.com/blog/tic-tac-toe-in-swiftui-done-properly/

The smallest game worth architecting: an immutable board, testable rules, a view that just renders state, and the classic AI you can bolt on in 40 lines

Tic tac toe is the "hello world" of game development, which is exactly why it's worth doing properly. It's small enough to hold in your head, but it still has every piece a real game needs: state, rules, turns, an end condition, a UI that reflects state, and, if you want it, an opponent that thinks.

One of my earliest App Store apps is Tic Tac Toe : Time Pass, published in April 2020. Its listing is as short as the game: "Put away your pencil and paper", with one-player and two-player modes, so you can play against another person or against yourself.

This article uses tic tac toe to show an architecture I'd use for any turn-based game: a value-type model that owns all the rules, a SwiftUI view that only renders state and forwards taps, unit tests for the rules, and a minimax opponent as an optional extension. To be clear: the listing doesn't say the app has a computer opponent. The minimax section is the approach I'd add, not a description of the app. API names are checked against Apple's documentation.

1. Why architecture matters even here

The quick version of tic tac toe puts nine @State strings in a view and checks for a winner inside the button action. It works for an afternoon. Then you want an undo button, a computer player, a "new game" animation, a stats screen and tests, and every one of those features has to reach into the view.

Instead, split it like this:

Game (struct)      ← all rules: whose turn, legal moves, winner, draw
   ▲     │
   │     ▼
GameViewModel      ← owns a Game, applies moves, triggers AI, publishes state
   ▲     │
   │     ▼
GameView (SwiftUI) ← renders state, sends taps; no rules at all

The model is a plain struct with no UIKit, SwiftUI or timers, which means you can test it, copy it (undo is free), and hand a copy to an AI to explore future moves without touching the real game.

2. The model: a board that can't be wrong

enum Player: String, CaseIterable {
    case x = "X", o = "O"
    var opponent: Player { self == .x ? .o : .x }
}

enum Outcome: Equatable {
    case inProgress
    case win(Player, line: [Int])
    case draw
}

struct Game: Equatable {
    private(set) var cells: [Player?] = Array(repeating: nil, count: 9)
    private(set) var current: Player = .x
    private(set) var moves: [Int] = []          // history, for undo and replays

    static let lines: [[Int]] = [
        [0, 1, 2], [3, 4, 5], [6, 7, 8],         // rows
        [0, 3, 6], [1, 4, 7], [2, 5, 8],         // columns
        [0, 4, 8], [2, 4, 6]                     // diagonals
    ]

    var outcome: Outcome {
        for line in Self.lines {
            if let p = cells[line[0]], cells[line[1]] == p, cells[line[2]] == p {
                return .win(p, line: line)
            }
        }
        return cells.allSatisfy { $0 != nil } ? .draw : .inProgress
    }

    var legalMoves: [Int] {
        guard outcome == .inProgress else { return [] }
        return cells.indices.filter { cells[$0] == nil }
    }

    /// Returns a new game with the move applied, or nil if the move is illegal.
    func playing(_ index: Int) -> Game? {
        guard legalMoves.contains(index) else { return nil }
        var next = self
        next.cells[index] = current
        next.moves.append(index)
        next.current = current.opponent
        return next
    }

    func undoing() -> Game {
        guard let last = moves.last else { return self }
        var previous = self
        previous.cells[last] = nil
        previous.moves.removeLast()
        previous.current = current.opponent
        return previous
    }
}

A few deliberate choices:

private(set) everywhere. Nothing outside the model can put an X in an occupied square or skip a turn. The only way to change the game is playing(_:), and it validates.
playing(_:) returns a new value instead of mutating. That makes the AI trivial, because it explores copies, and it makes "what if?" previews free.
Eight hard-coded lines beat a clever loop. For a 3×3 board, a literal table is the most readable rules engine possible. (For an N×N variant, you'd generate the lines instead.)

3. Testing the rules

Because the model is pure, the tests read like the rules of the game:

import XCTest

final class GameTests: XCTestCase {

    private func play(_ moves: [Int]) -> Game {
        moves.reduce(Game()) { game, move in
            guard let next = game.playing(move) else {
                XCTFail("Illegal move \(move)"); return game
            }
            return next
        }
    }

    func testRowWin() {
        // X: 0, 1, 2   O: 3, 4
        XCTAssertEqual(play([0, 3, 1, 4, 2]).outcome, .win(.x, line: [0, 1, 2]))
    }

    func testDiagonalWinForO() {
        // X: 0, 1, 5   O: 2, 4, 6
        XCTAssertEqual(play([0, 2, 1, 4, 5, 6]).outcome, .win(.o, line: [2, 4, 6]))
    }

    func testDraw() {
        // X O X / X O O / O X X
        XCTAssertEqual(play([0, 1, 2, 4, 3, 5, 7, 6, 8]).outcome, .draw)
    }

    func testCannotPlayOccupiedSquareOrAfterWin() {
        let game = play([0, 3, 1, 4, 2])          // X has won
        XCTAssertNil(Game().playing(0)?.playing(0))
        XCTAssertNil(game.playing(8))
    }

    func testUndoRestoresTurn() {
        let game = play([4]).undoing()
        XCTAssertEqual(game, Game())
    }
}

These run in milliseconds, with no simulator UI. When you later add an AI or a new mode, they're your safety net.

4. The view: render state, forward taps

The view model holds the game and the mode. The view is a grid:

import SwiftUI

@MainActor
final class GameViewModel: ObservableObject {
    enum Mode { case twoPlayer, onePlayer(computer: Player) }

    @Published private(set) var game = Game()
    @Published var mode: Mode = .twoPlayer
    @Published private(set) var isThinking = false

    func tap(_ index: Int) {
        if case .onePlayer(let computer) = mode, game.current == computer { return }
        guard let next = game.playing(index) else { return }
        game = next
        computerMoveIfNeeded()
    }

    func undo() { game = game.undoing() }
    func reset() { game = Game(); computerMoveIfNeeded() }

    private func computerMoveIfNeeded() {
        guard case .onePlayer(let computer) = mode,
              game.current == computer, game.outcome == .inProgress else { return }
        isThinking = true
        let snapshot = game
        Task {
            try? await Task.sleep(for: .milliseconds(350))   // feels less robotic
            let move = Minimax.bestMove(in: snapshot)
            if let move, let next = game.playing(move) { game = next }
            isThinking = false
        }
    }
}

struct GameView: View {
    @StateObject private var model = GameViewModel()
    private let columns = Array(repeating: GridItem(.flexible(), spacing: 8), count: 3)

    var body: some View {
        VStack(spacing: 20) {
            Text(status).font(.title2.bold())

            LazyVGrid(columns: columns, spacing: 8) {
                ForEach(0..<9, id: \.self) { index in
                    let mark = model.game.cells[index]
                    Button { model.tap(index) } label: {
                        Text(mark?.rawValue ?? " ")
                            .font(.system(size: 56, weight: .heavy, design: .rounded))
                            .frame(maxWidth: .infinity, minHeight: 96)
                            .background(background(for: index),
                                        in: RoundedRectangle(cornerRadius: 12))
                    }
                    .buttonStyle(.plain)
                    .disabled(mark != nil || model.game.outcome != .inProgress)
                    .accessibilityLabel(label(for: index, mark: mark))
                }
            }
            .padding(.horizontal)

            HStack {
                Button("Undo", action: model.undo).disabled(model.game.moves.isEmpty)
                Spacer()
                Button("New Game", action: model.reset)
            }
            .padding(.horizontal)
        }
        .animation(.easeOut(duration: 0.2), value: model.game)
        .sensoryFeedback(.selection, trigger: model.game.moves.count)   // iOS 17+
    }

    private var status: String {
        switch model.game.outcome {
        case .inProgress: return model.isThinking ? "Thinking…" : "\(model.game.current.rawValue) to play"
        case .win(let p, _): return "\(p.rawValue) wins!"
        case .draw: return "It's a draw"
        }
    }

    private func background(for index: Int) -> Color {
        if case .win(_, let line) = model.game.outcome, line.contains(index) {
            return .green.opacity(0.3)
        }
        return Color(.secondarySystemBackground)
    }

    private func label(for index: Int, mark: Player?) -> String {
        let row = index / 3 + 1, column = index % 3 + 1
        return "Row \(row), column \(column), \(mark.map { $0.rawValue } ?? "empty")"
    }
}

Notice what the view doesn't do: it never decides who won or whether a move is legal. Even the disabled state just reads the model.

Version notes, since the app supports iOS 12: LazyVGrid is iOS 14+, .sensoryFeedback is iOS 17+, and Task.sleep(for:) is iOS 16+. On an older target, use nested HStacks, UIImpactFeedbackGenerator and Task.sleep(nanoseconds:), or build the same view model behind a UIKit grid. SwiftUI itself starts at iOS 13, so a genuinely iOS 12-compatible app is UIKit. The architecture doesn't change; only the view layer does.

5. Adding a computer opponent: minimax

Tic tac toe is small enough to search completely. Minimax explores every possible continuation and assumes both players play perfectly: the computer picks the move with the best guaranteed outcome, and assumes you'll pick the one that's worst for it.

enum Minimax {
    /// Best move for `game.current`, or nil if the game is over.
    static func bestMove(in game: Game) -> Int? {
        let me = game.current
        var best: (move: Int, score: Int)?
        for move in game.legalMoves {
            guard let next = game.playing(move) else { continue }
            let score = minimax(next, maximizing: false, me: me, depth: 1,
                                alpha: Int.min, beta: Int.max)
            if best == nil || score > best!.score { best = (move, score) }
        }
        return best?.move
    }

    private static func minimax(_ game: Game, maximizing: Bool, me: Player,
                                depth: Int, alpha: Int, beta: Int) -> Int {
        switch game.outcome {
        case .win(let p, _): return p == me ? 10 - depth : depth - 10   // win sooner, lose later
        case .draw: return 0
        case .inProgress: break
        }
        var alpha = alpha, beta = beta
        var best = maximizing ? Int.min : Int.max
        for move in game.legalMoves {
            guard let next = game.playing(move) else { continue }
            let score = minimax(next, maximizing: !maximizing, me: me,
                                depth: depth + 1, alpha: alpha, beta: beta)
            if maximizing {
                best = max(best, score); alpha = max(alpha, best)
            } else {
                best = min(best, score); beta = min(beta, best)
            }
            if beta <= alpha { break }      // alpha-beta pruning: this branch can't matter
        }
        return best
    }
}

Two details make this feel right:

Depth in the score. 10 - depth makes the AI prefer winning now over winning later, and losing later over losing now. Without it, a perfect AI sometimes "plays with its food" and looks broken.
Alpha-beta pruning skips branches that can't change the result. The full game tree is only a few hundred thousand positions, so the AI is instant either way, but pruning is a habit worth building for bigger games.

Making it beatable

A perfect tic tac toe opponent never loses, which makes it boring quickly. A simple difficulty dial:

extension Minimax {
    /// skill 0.0 = random, 1.0 = perfect
    static func move(in game: Game, skill: Double) -> Int? {
        if Double.random(in: 0..<1) > skill { return game.legalMoves.randomElement() }
        return bestMove(in: game)
    }
}

"Easy" around 0.3, "medium" around 0.7 and "hard" at 1.0 gives three genuinely different games from one function.

6. Real-world example: Tic Tac Toe : Time Pass

The patterns above are how I'd structure Tic Tac Toe : Time Pass today, or any small turn-based game.

At the time of writing, its App Store listing shows:

Free, in Games (Strategy, Casual) and Entertainment
First released in April 2020
13 ratings in the US store, averaging about 3.9 stars
Supports iOS 12.0 and later

The listing says: "Tic Tac Toe supports one player and two player gameplay, so you can play against another human or against yourself."

What the listing says	Where it's covered
"Put away your pencil and paper"	A value-type `Game` model that enforces the rules (section 2)
"Two player gameplay… against another human"	`.twoPlayer` mode: one device, alternating turns (section 4)
"One player… against yourself"	`.onePlayer` mode; minimax is the extension I'd add for a computer opponent (section 5)
iOS 12.0 and later	UIKit is required below iOS 13; the model is identical either way (section 4)

A 3.9 average on a game this simple tells me something too. Casual players expect polish even from "time pass" games: clear win highlighting, a satisfying tap, an easy rematch. The architecture above is what makes that polish cheap to add.

7. Before you ship a small game: a checklist

Rules live in one pure model, with no UI framework imports.
Illegal states are impossible: private(set) state, and validated moves that return new values.
Every rule has a test: each kind of win, a draw, illegal moves, moves after a win, and undo.
The view only renders and forwards. If a view contains if winner… logic, move it.
The AI works on copies and never on the live game. It's tested too: it should never lose from any position where a draw is possible.
Difficulty is a dial, not three AIs.
Accessibility: every cell has a spoken label with row, column and contents, and the result is announced.
Rematch is one tap. The fastest way to a better rating in a casual game.

Wrapping up

Tic tac toe is small, but the lessons scale. Put the rules in a value type that can't be put into an illegal state, test it like a spec, keep the view dumb, and treat the AI as just another consumer of the model, one that explores copies. The same shape works for chess, card games and anything else turn-based.

Play it, or explore my other apps:

Tic Tac Toe : Time Pass (iOS): https://apps.apple.com/us/app/tic-tac-toe-time-pass/id1509555889
All of my free iOS apps: https://apps.apple.com/us/developer/alok-singh/id1508795536
My portfolio: https://bestlatestapps.com/alok/

What's your favourite "tiny game, big lesson" project? Tell me in the comments.

— Alok Kumar Singh

Originally published at https://bestlatestapps.com/blog/tic-tac-toe-in-swiftui-done-properly/

Two native apps into one React Native codebase in six months

Sun, 11 Oct 2026 18:35:56 +0000

I owned mobile for Pulse, an offline-first inspection app for auditors, on Android and iOS, from an early prototype to 100+ B2B enterprise clients. For most of that time it was two native apps: Kotlin on Android, Swift on iOS, kept in feature parity. In 2025 I led a full rewrite of both into a single React Native codebase. I architected it and built it alongside the team, and we completed it in six months, before I left in May 2025.

This isn’t a “native versus React Native” post. The native apps worked. The earlier posts onPulse’s sync engine and ona local-only app cover why they were built the way they were. This one is about the rewrite: why we did it, what we kept, and how it reached users.

Why rewrite two apps that worked
Keeping two native apps in feature parity has a simple cost: every feature is built twice, once in Kotlin and once in Swift, and every fix has to land in both. That was the reason for the rewrite, in two parts:

One codebase to maintain instead of two.
Shipping faster , because a feature or a fix reaches Android and iOS at the same time.
Neither reason says the native apps were bad. They say that keeping two of them had a cost, and one codebase removes it.

Replicate the behaviour, don’t redesign it
The native apps’ behaviour had years of field use behind it: records that get a temporary local ID and are remapped to a server ID when they sync, photos uploaded before the form that references them, upload progress the auditor can see, and inspection forms built dynamically. So the React Native app replicated that behaviour rather than redesigning it.

The alternative is harder than it looks. A rewrite that also changes how sync works is two projects at once, and every difference between the old app and the new one is something to explain to an auditor in the field. Replicating proven behaviour keeps the rewrite to one question: does the new app do what the old one did?

I built the core, the team built on top
I set the architecture and built the core myself: sync, offline storage and uploads. The team built the screens and features on top of it.

In an offline-first app, that core is where the risk sits. Everything on screen depends on the core behaving the way the native apps did, and in an offline-first app the core is where data gets lost if something is wrong. Screens are easier to see, test and fix; a sync bug can hide until an auditor’s work goes missing.

Rolling out gradually
The new app didn’t replace the native ones for everyone at once. It rolled out gradually, with the native app still available while users moved over.

For an offline-first app that isn’t caution for its own sake. Auditors work without signal, so at any moment someone may have work on the phone that hasn’t reached the server yet. A gradual rollout means a problem in the new app reaches a few users rather than all of them, and there is still a working app to fall back on while it’s fixed.

What I’d tell another team
If you’re rewriting an offline-first app, roll it out gradually. Keep the old app available and move users over in stages. A big-bang switch bets every auditor’s unsynced work on the new app being right on day one.

The bug that survived being recycled: automaticallyAdjustKeyboardInsets and Fabric view recycling on iOS

Thu, 08 Oct 2026 09:12:17 +0000

After logging a meal in Anovi, the nutrition app I build, the next screen opened normally. The content was there. Then the first scroll ran past the end of it, into empty space that should not have existed, and stopped.

Dragging in that space did nothing. Not a slow scroll, not a bounce. Nothing moved, because there was nothing under my finger. The content was somewhere above me and there was no way to reach it. The only way out was to kill the app.

It was not every screen and not every time, which is what kept it alive through earlier rounds of testing. It produced no crash, no error, and no failed request.

In short. On iOS with the New Architecture, a scroll view that opted into keyboard inset handling can leave that behaviour switched on when React Native recycles it. The next screen to inherit that view gets a phantom inset it never asked for. Filed as react-native#57755.

If you just want to check and fix your own app, that is a separate, shorter piece.

The evidence that was missing

Every request in the sequence returned what it should, in the time it should. Nothing failed, nothing timed out, nothing appeared in the logs at the moment things went wrong. The app had not crashed and was not in an error state.

Healthy logs are usually read as the absence of a finding. Here they were the finding, because they eliminated the entire category I had been searching in. That is what promoted the next detail from background noise to the only lead.

The next detail was the keyboard. On the broken screens it appeared, briefly, and went away again. On a screen with no text input on it and nothing focused.

A keyboard reacting where there is nothing to type into is not a rendering bug. Something was still listening.

The screen that broke was not the screen at fault

React Native's new architecture recycles native views. Rather than destroying a component's native view and building a fresh one, it resets the existing view and hands it to the next component that needs the same kind. On iOS, that reset happens in a method called prepareForRecycle.

Recycling is only safe if the reset is complete. Anything left behind belongs to whoever inherits the view next.

A scroll view can opt into having iOS adjust its insets when the keyboard moves, with a prop called automaticallyAdjustKeyboardInsets. Underneath, that sets a flag on the native view and gates a keyboard observer that lives for as long as the view does. prepareForRecycle does not clear that flag.

So the broken screen was innocent. It had no text input, no keyboard props, and nothing to do with any of this. It had simply been handed a view that came out of the pool still holding someone else's settings.

Where the keyboard came from

The view came from the meal logging modal, which does have a scroll view with the prop set and a search field that focuses itself.

The interesting part is what happened when I closed it. Tapping Done dismissed the keyboard, reset the modal's internal flow back to its search step, and hid the modal, all in the same render batch. Resetting the flow remounted the search field, its autoFocus fired, and the app opened a keyboard inside a modal that was already closing.

That is the flicker. Not a leftover from typing, but a keyboard my own code summoned into a dying screen. Its scroll view then went into the recycle pool while that keyboard was still up.

None of that is a bug. A keyboard being up while a screen goes away is ordinary, and the framework is meant to survive it. What it did instead was hand the next screen a view that was still holding the last one's settings.

Building something that fails on demand

An explanation that only reproduces inside a nutrition app is not much use to anyone, and it is not something a framework maintainer can act on. So the next step was the smallest thing that still fails: a modal with the prop and a focused input that kills itself mid-animation, then a plain scroll view that mounts straight afterwards and reports its own geometry.

The detector that cried wolf

Getting the measurement right took longer than finding the bug.

The first version reported failures that were not failures. A scroll view settling after a bounce moves on its own, and sampling at the wrong moment records that jitter as displacement. Several iterations went into separating "this view is still settling" from "this view has been moved by something else".

A detector that reports a bug which is not there is worse than no detector, because it makes the real signal unfalsifiable.

Everything downstream of it, including the controls, would have been noise interpreted as evidence.

Once it was honest, the numbers were unambiguous. A scroll view that never asked for keyboard insets, with the keyboard hidden, reporting a bottom inset of 217.3 points. Its content was 840 points tall in a 234 point window, so the furthest it should ever scroll is 606. It went to 823.

Physical iPhone, iOS 26.5.2, Release build, React Native 0.86.2, New Architecture. The victim sets no keyboard props of any kind.

The controls are the argument

A reproducer that fails is a claim. A reproducer that fails, and stops failing when you remove exactly one ingredient, is evidence.

Two controls, each from a freshly killed process. Turn off the inset prop: nothing. Dismiss the keyboard and let it settle before the modal closes: nothing. Each ingredient is necessary and neither is sufficient. The failure needs a view configured for keyboard insets to be recycled while its observer is still live.

Measuring it instead of reasoning about it

Everything so far was inference, from reading source and watching behaviour. The mechanism deserved a measurement, so I instrumented the framework itself: every keyboard delivery logged with the view's address and whether it was on screen or in the recycle pool.

rec-in  view=0x108118c00 ivar=1          entering prepareForRecycle
rec-out view=0x108118c00 ivar=1          leaving it, flag still set
kbd     view=0x108118c00 ivar=1 POOLED
write   view=0x108118c00 bottom=217.3 POOLED    ‚Üê inset written while pooled
props   view=0x108118c00 old=1 new=0 ivar=0     ‚Üê next screen mounts, flag cleared

The write lands while the view is sitting in the pool, 105ms before anything mounts on it. When a screen does mount, the flag is cleared immediately, so the screen you can see is never written to at all.

That ruled out the explanation I had been carrying. An earlier test, where a poisoned view's scroll position moved after I focused an unrelated text field, had looked like proof that the recycled view was still listening while mounted. It was not. The keyboard changed the layout, the window grew from 234 points to 299, the furthest legal scroll position dropped by 65, and iOS pulled the offset back to the new limit. Arithmetic, not a live listener.

What is actually happening

The pooled view keeps receiving keyboard notifications and keeps writing insets onto itself. It is not stale; it is current. It tracks the keyboard continuously, taking a real value when a keyboard rises and zero when it falls.

Whatever value it happens to be holding at the moment someone inherits it is what that screen is stuck with, because the inset is only reassigned when a component's props change it, and a component that never set the prop has nothing to reassign.

Which means the whole thing turns on timing. Sweeping the delay before the modal tears itself down, ten cycles each from a fresh process:

modal torn down after	corrupt readings	phantom inset
~120ms	36	217.3
~220ms	0	0.0
~320ms	0	0.0
~520ms	0	0.0
keyboard dismissed first	0	0.0

Only the earliest teardown reproduces. Wait longer and the keyboard's own disappearance reaches the pooled view first, zeroes the inset, and the pool quietly cleans itself. The bug needs a screen to mount during the narrow window while a keyboard is up.

That is also why it was intermittent in production, and why it survived earlier testing rounds. Most of the time nothing mounts inside that window.

Why it could not be scrolled back

The phantom inset extends the scrollable range past the end of the content, and that extra region has no view underneath it. So it takes no touches. A drag there produces no scroll events at all.

In the reproducer a sliver of the last row stays visible, so you can grab that and pull yourself back. In the app the scroll views were full screen. Once the content had left the viewport there was nothing to grab, and no gesture in the app could recover it.

A screen recording of the reproducer on a physical device is on the original article: several poison cycles, a scroll up into the space that should not exist, then taps on an unrelated input.

That is the difference between a layout glitch and a screen that is finished until you kill the process.

What happened after filing

I reproduced it unchanged on React Native 0.86.2, the latest release at the time, and filed it as react-native#57755 with a public reproducer.

Two pull requests followed, from people I have never met. The second carries a regression test covering the whole lifecycle, and a Meta engineer imported it for internal review the same morning it appeared.

Its two lines are small: clear the flag when the view is recycled, and stop guarding the assignment behind a props comparison so a recycled view can be re-armed properly. I applied them to the reproducer and ran it on the phone that found the bug in the first place. Baseline immediately before: 36 corrupt readings in 10 cycles. With the patch: 49 cycles, zero.

What I would take from this

The healthy logs were the finding. They eliminated a whole category, which is what turned a flicker into the only lead.

Controls before claims. Any bug can be explained by a plausible story. The question is which single ingredient you can remove to make it stop, and whether you have actually tried removing it.

A detector that lies is worse than no detector. Most of the reproducer work went into eliminating false positives, not into finding the failure.

Instrument the explanation, not just the bug. A story that fits every observation is not the same as a correct one. Mine was in the right place and the wrong moment, and only logging the framework showed the difference.

If you think your own app has this, the checks and the three ways to fix it are in a shorter companion piece.

The reproducer is at github.com/PragathiJ/rn-aaki-recycle-repro.

I write about production engineering and applied AI at pragathijayaram.com.

automaticallyAdjustKeyboardInsets is leaking into your other screens: how to check and fix it

Thu, 08 Oct 2026 08:56:07 +0000

A screen opens normally, then scrolls past the end of its content into empty
space, and dragging in that space does nothing at all. Restarting the app is the
only way out.

If that sounds familiar, this is a React Native framework defect, not your code.
This page is the operational version: how to confirm it, how to find every source
in your project, and what to do. The investigation behind it, including why it
took a while to understand, is here.

Scope. iOS only, New Architecture only. The code involved is the Fabric iOS
scroll view, so the old architecture and Android take different paths.
Reproduced on React Native 0.81.4 and 0.86.2. Filed as
react-native#57755.

What is going wrong

A scroll view that sets automaticallyAdjustKeyboardInsets keeps that behaviour
switched on when React Native recycles its native view. While the view sits in the
recycle pool it carries on receiving keyboard notifications and writing insets
onto itself. The next component to be handed that view inherits whatever value was
there, and nothing puts it back, because a component that never set the prop has
no inset of its own to assign.

The result is a scroll view with extra scrollable space below its content. That
space has no view underneath it, so it takes no touches, which is why you cannot
drag your way back out of it.

Confirm it

The first sign is a keyboard appearing on a screen with nothing focused. That is
the tell, not the bug.

The test is to read the inset on a scroll view that should not have one. Put this
on a screen that sets no insets of its own, scroll it with the keyboard hidden,
and watch the console:

const reported = React.useRef(false);

<ScrollView
  scrollEventThrottle={16}
  onScroll={(e) => {
    // contentInset is iOS-only; on Android nativeEvent has no such field.
    const bottom = e.nativeEvent.contentInset?.bottom ?? 0;
    if (bottom > 0 && !reported.current) {
      reported.current = true;
      console.warn('phantom bottom inset', bottom);
    }
  }}
>
  <View style={{ height: 2000 }} />
</ScrollView>;

Two details decide whether this test is worth anything. The scroll view needs
content taller than itself, or it never scrolls, onScroll never fires, and you
will conclude you are clean without having tested anything. And the reading has to
be gated, because at a 16ms throttle an ungated console.warn buries your log.

A scroll view that never opted in should report zero. Anything else means it is
sitting on a view that came out of the pool still armed.

Find every source

grep -rn "automaticallyAdjustKeyboardInsets" src/
grep -rn "contentInset" src/   # also catches contentInsetAdjustmentBehavior

The second search matters more than it looks. Any prop that writes native insets
belongs to the native view, and therefore to the recycling pool, so a static
contentInset combined with an automatic contentInsetAdjustmentBehavior is the
same class of risk even though it has nothing to do with keyboards. In my own
sweep that turned up a grid component the first search had missed.

Then run both again against node_modules. The pool is per process, not per
module, so a scroll view inside a dependency arms it exactly as well as one of
yours. You can clean your own code completely and still be handed a poisoned view by a library you did not write.

Fix it

Option 1, remove the prop. Handle keyboard layout explicitly instead. This is
what I shipped.

// Before: the flag does the layout, and the native view keeps listening
<Modal visible={visible}>
  <ScrollView automaticallyAdjustKeyboardInsets>
    <TextInput autoFocus />
  </ScrollView>
</Modal>

// After: explicit layout, nothing left armed on the native view
<Modal visible={visible}>
  <KeyboardAvoidingView behavior="padding" style={{ flex: 1 }}>
    <ScrollView contentContainerStyle={{ paddingBottom: 24 }}>
      <TextInput autoFocus={visible} />
    </ScrollView>
  </KeyboardAvoidingView>
</Modal>

The autoFocus={visible} change matters more than it looks. Focusing on mount is
what starts a keyboard animation during modal presentation, which is exactly the
window the defect needs. Watch for the same shape anywhere a modal resets its
internal state as it closes: that can remount a focused field and open a keyboard
inside a screen that is already going away.

One caveat: KeyboardAvoidingView with behavior="padding" inside a Modal
behaves differently depending on presentation style and often wants a
keyboardVerticalOffset. Treat it as a shape to adapt, not a drop-in.

Option 2, keep the prop but dismiss the keyboard first. Dismiss it and let it
settle before the screen unmounts. This came back at zero in the reproducer. It is
narrower than option 1, because it depends on every exit path from that screen
doing the same thing.

Option 3, patch the framework locally. Until the upstream fix ships you can
carry it as a patch-package patch. In RCTScrollViewComponentView.mm, clear the
flag on recycle and assign it on every update instead of only when it changes:

// prepareForRecycle: disarm before the view goes back in the pool
_automaticallyAdjustKeyboardInsets = NO;

// updateProps: drop the old-vs-new condition around the assignment
_automaticallyAdjustKeyboardInsets = newScrollViewProps.automaticallyAdjustKeyboardInsets;

Both lines are needed. The first stops the leak. The second matters because
prepareForRecycle does not reset the stored props, so once the flag is cleared a
view being reused by another component that also wants keyboard insets would
skip the assignment and silently lose the behaviour.

This is the substance of react-native#57811, which a Meta engineer has imported for internal review. I verified those changes against the reproducer on a physical device: 49 cycles, zero failures, where the unpatched build produced 36 failures in 10 cycles.

If you are on 0.86.2 and patching the framework, note that React core ships
prebuilt, so edits to RCTScrollViewComponentView.mm in node_modules never
reach the binary. You need RCT_USE_PREBUILT_RNCORE=0 and a fresh pod install,
or the patch silently does nothing.

What does not work

Scrolling the screen back to the top when it opens. I shipped that early and it
does clear the wrong opening position, which is enough to make it look like a
cure. It does not remove the phantom inset, so the dead space is still waiting at
the bottom.

How to tell you have fixed it

Run the confirmation check again after the flow that used to break things. Zero
inset, and a scroll to the bottom that stops at the end of your content with
nothing beneath it.

The reproducer is at
github.com/PragathiJ/rn-aaki-recycle-repro.

I write about production engineering and applied AI at
pragathijayaram.com.

Native, Kotlin Multiplatform or React Native: how I'd choose

Tue, 06 Oct 2026 08:23:00 +0000

title: Native, Kotlin Multiplatform or React Native: how I'd choose
published: true
date: 2026-09-25 00:00:00 UTC
tags: kotlinmultiplatform,reactnative,android,ios

canonical_url: https://abhishekgoyal.me/writing/native-kmp-or-react-native

“Should we build this in Kotlin Multiplatform or React Native?” is a question teams often ask before anyone has written down what the app has to do. That’s backwards. I’ve shipped all three approaches to production: native Android and iOS apps, a shared Kotlin Multiplatform data layer in HelperBook, and a React Native rewrite of two native apps at Pulse. The framework has never been the first decision. The features are.

Start with the features, not the framework

Before choosing anything, I list what the app actually has to do, and which of those things lean on the platform. Camera capture, video playback, background work, offline data, sensors, OS integrations. Then I weigh each option against that list, along with the team that will maintain it and the time and money available.

Most of the heat in “Kotlin Multiplatform vs React Native” debates comes from people comparing the tools in the abstract. For a specific app, the answer is usually much clearer than the debate suggests.

When I’d stay fully native

Sharing code is not free, so sometimes the right amount to share is none.

The market is on one platform. HelperBook is for Indian households, where Android is the phone most people carry, so it shipped on Android first. Its records still live in a shared Kotlin Multiplatform module with SQLDelight, so an iOS app could reuse that data layer rather than rewrite it, but the app itself is native Android.
The app leans hard on platform APIs. On a video-first hiring platform I built 100% of the Android client, and the core of it was CameraX capture, Media3 playback and on-device speech transcription. That is exactly the kind of work where you want the platform’s own APIs directly, not through a layer.
The two apps look and behave differently. If the Android and iOS versions don’t share much UI or flow, a shared UI codebase saves less than it costs.

When Kotlin Multiplatform fits

Kotlin Multiplatform shares business logic and data while each platform keeps a fully native UI. I reach for it when:

Native apps already exist. You can add a shared module to the apps you have and move code into it gradually, instead of rewriting both.
The team writes Kotlin. Android developers can own the shared code without learning a new stack.
The business logic is complex and must match on both platforms. Rules, calculations and offline data that behave slightly differently on Android and iOS are a bug factory. Writing them once removes a whole class of problems.
Native feel matters. The UI stays Jetpack Compose on Android and SwiftUI or UIKit on iOS.

When React Native fits

React Native gives you one codebase for the UI as well as the logic. I recommend it when the timeline is short and the budget is small, and one team has to ship both platforms quickly. It also makes more sense when the screens are the same on both platforms, and when there’s already a React web team whose skills carry over.

Performance, honestly

People search for “Kotlin Multiplatform vs React Native performance” a lot, so here’s my view. Kotlin Multiplatform keeps the UI fully native, and native UI is smoother. For most business apps (forms, lists, dashboards) React Native is fine, and the difference users feel comes far more from the architecture than from the framework.

I haven’t shipped a Flutter app, so I won’t argue for or against it from experience. It’s a real option; it’s just not one I can speak to first-hand.

What Pulse taught me

At Pulse I owned mobile, Android and iOS, from an early prototype to 100+ B2B enterprise clients. For years it ran as two native apps, Kotlin on Android and Swift on iOS, kept at feature parity. Keeping two native apps at parity meant building every feature twice.

In 2025 I led the rewrite of both apps into one React Native codebase, architected and co-built with the team in six months, and it replaced both native apps in production. React Native fitted the situation: one codebase suited the timeline and budget, the web app was already built in React, and the screens were the same on both platforms.

The hardest part of the port was reliable background uploads, which the offline engine depended on. The inspections could run to 500+ questions and 1,000+ photos, captured offline and uploaded in the background once a connection came back, so the upload behaviour had to be as dependable after the rewrite as before it.

Looking back, React Native was a reasonable call for that timeline, budget and team. Knowing what I know now, I’d weigh Kotlin Multiplatform harder for an app with that much offline logic. The sync rules and the upload queue are exactly the kind of code you want written once and shared, while each platform keeps its own native background APIs.

How I’d decide for your app

If your app…	I’d lean towards
Targets one platform first, or leans hard on camera, video, sensors	Native
Already has native apps, or complex logic that must match on both	Kotlin Multiplatform
Needs both platforms fast, on a small budget, with the same screens	React Native

None of these is a rule. They’re where I start, and the feature list decides the rest. If you’re weighing this for a real app, here’s how I help teams adopt Kotlin Multiplatform, and every engagement starts with a paid discovery sprint that ends in a written recommendation you can use with anyone.

The Pitfalls of Migrating from Xamarin.Forms to .NET MAUI

Sat, 03 Oct 2026 17:04:00 +0000

Why the migration is not a simple upgrade

On paper, migrating from Xamarin.Forms to .NET MAUI looks like a namespace change. In practice, the time goes into three areas: custom renderers, navigation, and plugins that are no longer maintained. Microsoft's support for Xamarin ended in May 2024, and the apps still on it are getting harder to publish as Apple and Google raise their minimum SDK requirements.
The mechanical part is relatively easy. The project moves to the single-project format, Xamarin.Forms becomes Microsoft.Maui.Controls, and Xamarin.Essentials is built directly into the framework. Automated upgrade tools and AI assistants handle this part well.
What they don't handle well is understanding why a custom renderer existed, what the code assumed about the order in which pages load, or what hidden behavior an old plugin provided. This article walks through those pitfalls, with code examples and solutions that work in real projects.

From renderers to handlers

The biggest conceptual change is that MAUI no longer customizes controls through inheritance, but through mappers: dictionaries that link each property of a cross-platform control to the native code that applies it.
In Xamarin.Forms, removing the underline from an Entry on Android meant writing an entire renderer:

[assembly: ExportRenderer(typeof(BorderlessEntry), typeof(BorderlessEntryRenderer))]
public class BorderlessEntryRenderer : EntryRenderer
{
    public BorderlessEntryRenderer(Context context) : base(context) { }

    protected override void OnElementChanged(ElementChangedEventArgs<Entry> e)
    {
        base.OnElementChanged(e);
        if (Control != null)
            Control.Background = null;
    }
}

In MAUI, the same effect comes from adding an entry to the existing mapper, usually in MauiProgram.cs:

Microsoft.Maui.Handlers.EntryHandler.Mapper.AppendToMapping("Borderless", (handler, view) =>
{
    if (view is not BorderlessEntry)
        return;
#if ANDROID
    handler.PlatformView.Background = null;
#elif IOS || MACCATALYST
    handler.PlatformView.BorderStyle = UIKit.UITextBorderStyle.None;
#endif
});

Pitfall 1: mappers are global

A renderer applied only to the type registered with ExportRenderer. An entry added to EntryHandler.Mapper applies to every Entry in the app. The if (view is not BorderlessEntry) return; check in the example above is not optional. Without it, every form in the app loses its border, and the bug only shows up during testing, on screens you weren't looking at.

Pitfall 2: OnElementChanged has no direct equivalent

Old renderers mixed three things in OnElementChanged: creating the native control, subscribing to events, and unsubscribing. In MAUI these are separate. For a custom handler, the native control is created in CreatePlatformView, subscriptions go in ConnectHandler, and cleanup goes in DisconnectHandler. Moving the old code without splitting it across these three methods usually leads to memory leaks or events that fire twice.
Also watch when DisconnectHandler gets called. In early MAUI versions it had to be called manually, while newer versions have a configurable policy via HandlerProperties.DisconnectPolicy. Check the documentation for the .NET version you're using.

Pitfall 3: the temptation of compatibility renderers

MAUI lets you register old renderers through AddCompatibilityRenderer. That's useful for getting the app running quickly, but it's technical debt: the compatibility package is marked obsolete and doesn't benefit from the new pipeline's optimizations. My recommendation is to use it only as an intermediate step, with a clear ticket for each remaining renderer.

Pitfall 4: the native control type has changed

Old code often cast to specific native classes. In MAUI, handler.PlatformView may be a MAUI-derived class (for example MauiTextField on iOS), not the UIKit or Android class you knew. A wrong cast doesn't produce a compile error but an InvalidCastException at runtime, usually on only one platform.

Shell existed in Xamarin.Forms too, but many older apps used NavigationPage, TabbedPage, and MasterDetailPage. In MAUI, Shell becomes the recommended approach, and moving to it changes more than the syntax.

Pitfall 5: Shell doesn't accept every page type

A ShellContent must contain a ContentPage. A TabbedPage or FlyoutPage (formerly MasterDetailPage) placed inside Shell is not supported. Tabs and the side menu are defined through the Shell structure (TabBar, Tab, FlyoutItem). If the app had tabs nested inside detail pages, the structure has to be rethought, not just moved.

Pitfall 6: routes and parameters

Pages that don't appear in the Shell visual hierarchy must be registered explicitly, otherwise navigation fails at runtime:

Routing.RegisterRoute(nameof(PatientDetailPage), typeof(PatientDetailPage));

await Shell.Current.GoToAsync($"{nameof(PatientDetailPage)}?id={patient.Id}");

Two details take the most time. First, the // prefix means an absolute route and resets the navigation stack, which is right after login but wrong in a list-detail flow. Second, query string parameters are text. For complex objects, use the parameter dictionary (or ShellNavigationQueryParameters in recent versions, valid for a single navigation) and receive them through IQueryAttributable, not through manual serialization in the URL.

Pitfall 7: page lifecycle

With ContentTemplate, Shell creates pages the first time they are shown, not when the app starts. Code that assumed a ViewModel already existed (for example, subscribing in a constructor to messages sent by another page) can miss events. In addition, pages in tabs usually stay in memory, so OnAppearing is called every time you return, not just once. Data-loading logic needs to be idempotent.

Pitfall 8: dependency injection in pages

MAUI has built-in DI, and Shell can resolve pages and ViewModels from the container if they are registered in MauiProgram.cs. Pay attention to the lifetime you choose: a page registered as a singleton keeps its state between navigations, while a transient one loses it. Code that used DependencyService.Get<T>() still works, but this is a good moment to move it to constructor injection.

Plugins that no longer exist

In many projects, plugins block the migration more than your own code does. The Xamarin ecosystem was built on community-maintained packages: some were abandoned, some were folded into the framework, and others were rewritten under a different name. The first step is an inventory of every NuGet package, with a replacement for each one.

Xamarin.Essentials - built into MAUI - namespaces change (Microsoft.Maui.Devices, Microsoft.Maui.Storage, Microsoft.Maui.ApplicationModel, etc.)
Plugin.Permissions - Permissions (built in) - similar API, but manifest/Info.plist declarations are still required
Plugin.Connectivity - Connectivity (built in)
Plugin.Media - MediaPicker (built in) - for full camera control, CommunityToolkit.Maui.Camera
Xamarin.CommunityToolkit - CommunityToolkit.Maui - many APIs renamed; check behaviors and converters one by one
Rg.Plugins.Popup - Mopups or Popup from CommunityToolkit.Maui - Mopups keeps a similar API, faster migration
FFImageLoading - standard Image or community forks for MAUI - the original package is no longer maintained
Xamarin.Forms.Maps - Microsoft.Maui.Controls.Maps - requires UseMauiMaps() in MauiProgram.cs
SkiaSharp.Views.Forms - SkiaSharp.Views.Maui.Controls - requires UseSkiaSharp()
Lottie (Xamarin) - SKLottieView from SkiaSharp.Extended.UI.Maui
MessagingCenter - WeakReferenceMessenger from CommunityToolkit.Mvvm - MessagingCenter is marked obsolete
Visual Studio App Center - Sentry, Firebase Crashlytics, etc. - App Center was retired in March 2025

Pitfall 9: the plugin “works”, but only on one platform

Some packages have versions that install without errors in a MAUI project but cover only some platforms or depend on old native libraries. The build passes, and the problem appears in the iOS build, at publishing time, or on the first run on a real device. Check on NuGet which frameworks each package targets (for example net8.0-android, net8.0-ios) and the date of its latest release.

Pitfall 10: hidden behaviors

Old plugins often did things you couldn't see in your code. Plugin.Media, for example, requested permissions on its own and could compress or rotate the image. MediaPicker doesn't do all of that, so after migration you may get photos several MB in size or with the wrong orientation. Every replacement has to be tested for behavior, not just for compilation.

Small pitfalls that eat up time

None of the issues below is hard, but together they can add whole days to an estimate.

Image resources. In the single project, images live in Resources/Images and must follow Android rules: lowercase letters, digits and underscores, no hyphens. SVG files are converted to PNG at build time and are referenced in XAML with the .png extension.
Layouts. Default spacing values have changed, RelativeLayout has moved to the compatibility package, and Frame is replaced by Border. Screens look “almost” the same, which is more dangerous than looking obviously broken.
Device APIs. Device.RuntimePlatform becomes DeviceInfo.Platform, and Device.BeginInvokeOnMainThread becomes MainThread.BeginInvokeOnMainThread or Dispatcher. The old code compiles with warnings, so it's easy to ignore.
ListView vs. CollectionView. ListView still exists, but CollectionView is the recommended option and behaves differently for selection, separators and row height.
Compiled bindings. Adding x:DataType in XAML brings a visible performance gain and catches, at compile time, wrong bindings that failed silently in Xamarin.
Trimming and AOT. Release builds can strip code accessed through reflection (serialization, dynamically configured DI). An app that works perfectly in Debug can stop at startup in Release. Test the Release build on a real device in the first week, not at the end.

Conclusion: a lower-risk strategy

A successful migration starts with the inventory, not the code. The order that has worked best in practice is:

Inventory every NuGet package, custom renderer, effect and DependencyService call, with a replacement decided for each.
Do the mechanical part (single project, namespaces, Essentials) and get the app compiling, temporarily using compatibility renderers where needed.
Build and run the Release build on real devices, on both platforms, before any other change.
Rewrite renderers as handlers or mappers, one at a time, with visual tests on every affected screen.
Move navigation to Shell only after everything else is stable. It's the change with the biggest impact on behavior.

MAUI is a cleaner and faster framework than Xamarin.Forms, and the handler model makes customization much simpler once you understand it. The real cost of the migration lies in what the old code did implicitly. If you identify those things early, the estimate stays realistic and the app reaches the stores without surprises.

I built a habit tracker that doesn’t track anything

Tue, 29 Sep 2026 12:51:03 +0000

I get distracted easily.

And I have exactly the same problem with habits.

Every day brings a new urgent task. By the end of the day, there’s often neither the time nor the energy left for the things I actually wanted to do consistently.

At some point, I realized I didn’t need yet another habit tracker with a giant calendar, streaks, and progress charts.

I just needed to see one thing:

what matters today.

For example, I want to go to the gym three times a week.

If I’ve already been three times, why should the app keep showing me that workout for the rest of the week?

Or Portuguese. I only have time to study on Wednesdays and Fridays. So why would I want to see that task on Monday?

That’s why I built Yet Another Habit.

The app only shows the activities that are relevant today.

Not today? Don’t show it.

Already completed the required number of times this week? Don’t show it anymore.

Didn’t get to it today? Just skip it. The activity will come back on the next day when it actually matters.

And there’s one more thing I left out on purpose:

there are no stats.

No fancy charts, no streaks, no reports reminding you what a terrible person you’ve been for the last 27 days.

I think that when you’re building a habit, the process matters more than constantly measuring the result.

You open the app, see what matters right now, and focus on that.

I originally built Yet Another Habit just for myself, but eventually decided to share it and released it on the App Store.

🌱 Website: https://izebit.com/yet-another-habit/
App Store: https://apps.apple.com/br/app/yet-another-habit/id6809048979

Track. Don’t judge. Repeat.

Mantra Meditation Timer (iOS)

Fri, 25 Sep 2026 12:30:00 +0000

MANTRATimer is a minimalist, privacy-first meditation timer specifically designed for practitioners of mantra-based meditation techniques on iOS.   It offers a distraction-free environment, ensuring your focus remains solely on your practice without intrusive features common in other apps. This app is ideal for individuals seeking a simple, reliable, and respectful tool for their daily mantra meditation.

Key Features

Opens directly to your timer for immediate practice.
Completely silent notifications that respect your meditation.
No tracking, social features, or distractions.
Configurable warm-up and cool-down phases with tricolour progress arc.
Optional post-session reflections and notes for personal insights.
One-time purchase for Pro features, offering lifetime access with no subscriptions.

Use Cases

MANTRATimer is perfectly suited for individuals engaged in mantra-based meditation practices, such as Transcendental Meditation, who require a dedicated and uncluttered timer.   If you've found other popular meditation apps like Headspace or Calm to be overly complex, filled with guided meditations you don't use, or disruptive with streaks and upgrade prompts, MANTRATimer provides the absolute simplicity you need. It serves as a dedicated space for your daily ritual, ensuring a seamless transition from activity to silence.

It's also beneficial for meditators who prioritize privacy and wish to keep their practice data local and secure. The app's design caters to those who understand that mantra meditation thrives on silence and focus, offering a tool that truly 'gets it' by removing all unnecessary elements that break concentration.

Pricing Information

MANTRATimer operates on a freemium model. The Free Version provides all essentials for daily practice, including built-in timers (Standard, Extended, plus one custom), configurable warm-up/cool-down, session reflections, notes, local history, and basic statistics.

For advanced practitioners, 'Mantra+' is available as a one-time purchase for lifetime access to all features and future updates, including unlimited custom timers, advanced statistics, iCloud sync, Apple Family Sharing, and more, with no subscription ever.

User Experience and Support

The user experience is centered around pure simplicity and focus. The app opens directly to your timer, eliminating menus and choices to ensure a seamless transition into meditation. Notifications are completely silent, respecting your practice. Crafted for iPhone, it offers smooth, quiet, native interactions. While extensive tutorials aren't explicitly mentioned, the app's minimalist design aims for intuitive use. Contact information is provided for support.

Technical Details

MANTRATimer is an iOS native application, meticulously crafted for iPhone from day one. It leverages Apple's ecosystem, including iCloud for private and encrypted data synchronization across your devices. This design ensures that your personal meditation history, timers, and settings remain private and never touch external servers, upholding a strong privacy-first commitment.

Pros and Cons

Pros:
- Purpose-built for mantra-based meditation, ensuring absolute simplicity.
- Privacy-first approach with no ad trackers, social features, or data collection on external servers.
- One-time purchase for Pro features, avoiding recurring subscriptions.
- Seamless, distraction-free user experience with silent notifications.
- iOS native design for smooth and quiet interactions.
- Configurable timers, warm-up/cool-down phases, and optional reflections.
Cons:
- Exclusively available on iOS and iPadOS (Apple Watch integration coming in 2026).
- Not designed for guided meditations or other non-mantra practices.
- Lacks social or community features (intentional, but a con for some users).
- No explicit mention of extensive in-app tutorials, though simplicity aims to mitigate this.

In summary

MANTRATimer is the definitive meditation timer for practitioners of mantra-based techniques, offering an unparalleled blend of simplicity, focus, and privacy. It eliminates common distractions found in other apps, providing a truly dedicated space for your daily practice. If you seek a reliable, respectful, and distraction-free tool to support your silent meditation journey, explore MANTRATimer today and experience the difference.

Available on the Apple App Store

How to Fix Apple Silicon CocoaPods Errors Without Messy Terminal Aliases

Mon, 06 Jul 2026 12:55:19 +0000

The Crash

You pull down a fresh React Native repo, or you upgrade your Expo project, navigate to your ios directory, and run your standard installation command:

pod install

Instead of a clean build, your terminal drops a wall of text pointing to a compilation or architecture conflict:

LoadError - dylib library not found for ffi_c - /Library/Ruby/Gems/2.6.0/gems/ffi-1.15.5/lib/ffi_c.bundle

Or you are hit with an explicit architecture clash during compilation:

Ignoring ffi-1.15.5 because its extensions are not built.
Arch mismatch: x86_64 vs arm64

Why the Common Internet Advice is a Trap

If you search for this error on Stack Overflow or Reddit, the top answers almost always tell you to run your terminal in Rosetta mode or force compilation with an architecture flag:

sudo arch -x86_64 gem install ffi
arch -x86_64 pod install

Do not do this.

While this might bypass the error temporarily, it introduces a highly unstable configuration to your machine. It forces an Apple Silicon Mac to use Intel x86 emulation for specific Ruby gems while running an underlying system interpreter that expects native ARM (arm64) code.

This mixed-architecture setup will inevitably break your bundler, conflict with Node native modules, and cause random, hard-to-diagnose failures during local builds.

The real problem isn't your hardware; it's that your environment is attempting to load global, system-level Intel configurations inside a modern ARM environment.

The Fix: Resolving the Conflict Natively

To resolve the issue permanently, you need to purge the conflicting configurations and ensure your dependency manager runs natively on Apple Silicon.

Step 1: Purge the Broken System Gems

First, clear out any global, system-level gems that were compiled incorrectly under mixed architectures.

Run the following command from your root directory to remove CocoaPods configurations managed by the system Ruby installation:

sudo gem uninstall cocoapods

Step 2: Install the Native ARM Version of CocoaPods via Homebrew

Instead of relying on the default macOS system Ruby interpreter to manage your gems, install CocoaPods through Homebrew.

Homebrew automatically detects your M-series architecture and fetches the dedicated, optimized native arm64 binary.

brew install cocoapods

Step 3: Isolate Your Ruby Environment (Optional but Highly Recommended)

Using the default pre-installed macOS system Ruby (/usr/bin/ruby) frequently causes permissions and architecture locks.

For a stable environment, switch to a local Ruby version manager like rbenv or chruby to handle your project dependencies cleanly.

# Install rbenv via Homebrew
brew install rbenv ruby-build

# Initialize rbenv in your shell configuration
rbenv init

# Install and set a modern native Ruby version
rbenv install 3.2.2
rbenv global 3.2.2

Step 4: Clear the Local State and Install Natively

Now that your environment relies on native binaries, clear your project's cached build configurations to ensure no stale artifacts remain:

cd ios
pod deintegrate
rm -rf Podfile.lock

Finally, run your installation command normally.

It will complete natively without requiring any arch -x86_64 prefixes or Rosetta terminal wrappers:

pod install

Wrestling with local environment drift, corrupted build paths, and conflicting architectures can pull you out of the development loop for hours.

If you are tired of decoding cryptic terminal logs and tracking down configuration bugs by hand, take a look at FixMyError. It is a clean diagnostic workspace built to parse your build outputs instantly, giving you clear solutions so you can get right back to building your app.

How to Fix "Module Could Not Be Found" in React Native & Expo

Tue, 16 Jun 2026 11:45:20 +0000

We’ve all been there.

You find an awesome library, you run npx expo install, you import it into your code, and you start your development server.

You expect magic.

Instead, your simulator turns blindingly red with an error that looks something like this:

ERROR Invariant Violation: TurboModuleRegistry.getEnforcing(...):
'RNGestureHandlerModule' could not be found.

Verify that your native modules are linked correctly.

Your app is completely bricked, your Metro bundler is acting confused, and you’re left wondering why a package you just installed is allegedly missing from the face of the earth.

Let's look at exactly why this happens and the 3-step checklist to clear it up without losing your sanity.

The Root Cause: JavaScript vs. Native Code

Modern Expo apps are beautifully split into two worlds:

The JS Bundle:

Your components, logic, and regular styles. Metro can hot-reload this in milliseconds.

The Native Layer:

The underlying Kotlin/Java and Swift/Objective-C code that actually talks to the phone's hardware.

When you install a package that uses native code (like react-native-gesture-handler, react-native-reanimated, or a map library), Metro cannot hot-reload native code into an active app binary.

If you are running a pre-built Development Client or using Expo Go, it only knows about the native modules that were compiled the last time you built the app.

It has no idea this new native module exists yet, so the registry panics and throws an Invariant Violation.

The Ultimate "Un-Brick My App" Checklist

Next time this red screen of death pops up, run through these three steps in order.

1. Rebuild the App Binary (The Absolute Must)

Simply restarting the Metro bundler won’t cut it.

You need to recompile your native code so the new library gets bundled into the actual simulator app.

Stop your server and run:

# For Android Simulators / Devices
npx expo run:android

# For iOS Simulators
npx expo run:ios

2. Force a Clean Prebuild (If Using Custom Native Directories)

If you are managing your own android or ios directories and things get desynced, force Expo to regenerate them with the new native dependencies linked:

npx expo prebuild --clean

This removes the generated native projects and recreates them from your Expo configuration, ensuring newly installed native packages are correctly integrated.

3. Nuke the Metro Cache

Sometimes Metro holds onto a stale dependency graph like a grudge.

If you’ve rebuilt the binary and it still complains, start your project while forcing a total cache clearance:

npx expo start -c

This clears Metro's cache and forces it to rebuild the dependency graph from scratch.

Final Thoughts

Native linking issues can feel incredibly frustrating because nothing appears wrong in your JavaScript code.

The problem is usually that your app binary and your JavaScript bundle have fallen out of sync.

Whenever you see errors like:

RNGestureHandlerModule could not be found
Native module cannot be null
TurboModuleRegistry.getEnforcing(...) failed
Module has not been registered

Run through this checklist:

Rebuild the app binary.
Run a clean prebuild if you're using native directories.
Clear the Metro cache.

Most of the time, one of those three steps will get you back up and running.

If you're reading this at 2:00 AM while violently copy-pasting cryptic mobile stack traces into search engines, I feel your pain deeply.

I got so tired of hunting down hidden Gradle errors and obscure CocoaPods issues that I decided to build a tool to automate the headache.

It's called Fix My Error.

I set up a completely registration-free sandbox right on the homepage using this exact native linkage error so you can see how it works in real time without handing over your data.

If you like how it parses the logs, you can drop your own daily errors into the core engine with a free account (which gives you 5 free fixes per day), or check out the Pro tier if you're working in a heavy production environment.

Give the sandbox a spin next time Expo decides to ruin your afternoon, and let me know if it helps your workflow.

How do you usually handle these types of native linking bugs?

Drop a comment if this checklist worked for you, or let me know if there's an obscure Expo error that's currently driving you crazy.

Why Your Mobile App Works Perfectly Locally But Crashes Instantly in TestFlight

Thu, 11 Jun 2026 09:01:21 +0000

We’ve all been there. You spend weeks building a feature, testing it on your local simulator or a physical device running a development stream. Everything is butter. No lag, no warnings.

You confidently bundle the app, ship it to TestFlight, wait for Apple to finish processing, download it... and the moment you tap the app icon, it instantly flashes and closes. Hard crash.

Before you lose your mind or start blindly tweaking code, remember that production builds behave entirely differently than development environments.

Here are the four most common reasons your app dies the literal second it hits production, and exactly how to fix them.

1. The Missing Privacy Keys String (`Info.plist`)

If your app requests permissions for features like Location Services (maps, background location), the Camera, or the Photo Library, Apple requires you to explicitly state why in your Info.plist file using usage description keys (like NSCameraUsageDescription or NSLocationWhenInUseUsageDescription).

The Gotcha

In a local development environment, sometimes a framework will let a missing string slide, fallback to a default, or catch the exception gracefully.

The Production Reality

Apple’s iOS security layer will ruthlessly and instantly terminate the application binary on launch if your production code attempts to initialize a library requiring these permissions without the matching text string configured.

The Fix

Double-check your Info.plist (or your Expo app.json plugins). Make sure every single hardware or permission API your code imports has a clear, user-facing explanation string attached.

2. Missing Push Notification Entitlements

If your application includes code for push notifications (even if you haven’t fully wired up the backend yet), your binary needs specific clearance to launch.

The Gotcha

Local builds often bypass strict entitlement checks, or run using a wildcard development provisioning profile that covers everything loosely.

The Production Reality

When built for distribution, if your app contains code for handling remote notifications but the App Store Provisioning Profile doesn't explicitly have the Push Notifications entitlement enabled, the OS will trigger a fatal launch mismatch exception.

The Fix

Head to your Apple Developer Account under Identifiers, verify that your App ID has Push Notifications checked, and regenerate your production profile.

3. Dead Code Elimination & Aggressive Minification

When building locally, your JS bundling or native compilation keeps debug code, metadata, and helper functions intact.

When you build for production, optimization tools like ProGuard/R8 (for Android native engines) or aggressive tree-shaking strip away "unused" code to shrink the binary size.

The Gotcha

Sometimes, these optimization tools accidentally strip away native modules or reflection classes used by third-party packages, assuming they are dead code because they aren't explicitly referenced in the main thread.

The Production Reality

The app boots up, looks for a compiled native library or native method bridge, finds a missing reference, and triggers a fatal crash right during initialization.

The Fix

If you are using native dependencies, make sure your obfuscation/minify configuration files explicitly include rules to keep specific third-party library paths intact.

4. Broken Initialization Flow (Environment Variables)

How does your app determine its backend URL or third-party service tokens?

If you are relying on a local .env file that is git-ignored, those values might not be making it into your production build machine or CI/CD pipeline.

The Gotcha

The app builds successfully because the compiler doesn't care if a string variable is blank or null at build time.

The Production Reality

On launch, your application's root mounting sequence tries to parse an undefined API key or a null base URL during setup. If your code doesn't have a fallback check, it throws a fatal JavaScript or runtime error before the first screen even renders.

The Fix

Always verify that your build dashboard (like Expo Application Services, GitHub Actions, or local production scripts) has your production environment variables explicitly mapped before hitting compile.

How to Stop Guessing and Find the Proof

Stop guessing and changing random lines of code hoping for a miracle. Apple leaves an exact paper trail for immediate launch crashes.

On Your Test Device

Open up the TestFlight app on your iPhone, tap on the application name, scroll down to Crash Logs, and you can view or share the exact file.

Inside Xcode

Navigate to:

Xcode > Window > Organizer > Crashes

Apple aggregates logs directly from TestFlight users here, often highlighting the exact line of compiled code that triggered the crash (look for terms like SIGABRT or EXC_CRASH).

What's the absolute strangest "works locally, breaks in production" bug you've ever had to hunt down?

Let's talk in the comments!

The React Native Native-Dependency Trap: How to Fix Demanding Build Failures Without Nuking node_mod

Tue, 09 Jun 2026 09:26:33 +0000

It’s the same story every time. You run a simple package upgrade, or you decide it's time to bump your Expo SDK version. Locally, JavaScript compiled perfectly. But the second you run a native build, your terminal explodes with hundreds of lines of red text.

On iOS, it’s a cryptic CocoaPods could not find compatible versions for pod or a sudden compilation failure in AppDelegate.mm. On Android, it’s a fatal Gradle lifecycle error or a missing namespace exception.

When native dependencies break, most developers fall back on the classic loop: delete node_modules, delete package-lock.json, clear cache, reinstall, and pray.

But blind-nuking your files rarely fixes the underlying architectural conflict. Here is how to actually diagnose and surgically resolve native dependency hell in modern React Native and Expo apps.

1. The Root Cause: Transitive Dependency Syncing

When you install a library like react-native-reanimated or a native camera module, that library relies on specific versions of underlying native libraries (Pods or Android libraries).

If two different third-party packages require the same native dependency but expect completely different versions, your package manager forces a compromise in JavaScript. But when the native build tool (Xcode or Gradle) steps in, it sees two conflicting native frameworks trying to occupy the same space.

For Expo Users: Always Prioritize the Pinned Versions

Running npm install can bypass Expo's guardrails. Always use:

npx expo install --fix

This forces Expo to look at your current SDK version and automatically downgrade or upgrade conflicting community packages to their exact validated native counterparts.

2. The iOS Podfile.lock Paradox

If your team introduces a package or you pull down main and suddenly iOS won't build, the culprit is usually an out-of-sync Podfile.lock. Running pod install blindly sometimes isn't enough if cached pods are conflicting.

The Surgical Fix

Instead of deleting your whole project configuration, clear the native iOS build cache specifically:

cd ios && pod cache clean --all
rm -rf Pods Podfile.lock
pod install

This forces CocoaPods to re-evaluate the dependency tree from absolute scratch based on your current package.json, without losing your local JS settings.

3. The Android Gradle Namespace Meltdown

With newer versions of Gradle and React Native, the way native Android modules declare their packages has changed (moving entirely to namespace inside build.gradle).

If you are using an older, unmaintained community package, Gradle will completely fail to compile the app on launch.

The Surgical Fix

Instead of waiting for an open-source maintainer to update a dead repository, you can use patch-package or Expo Config Plugins to alter the third-party library’s build.gradle file locally.

Alternatively, ensure your android/gradle.properties has the proper architecture properties enabled:

android.useAndroidX=true
android.enableJetifier=true

Triage Your Terminal Output

The biggest mistake developers make is trying to read the very bottom of a failed build log.

Xcode and Gradle put the actual error at the beginning of the failure block, while the bottom lines are just the generic system telling you the process exited with code 1.

Always scroll back up to locate the first root error flag.

I'm currently tracking down these weird native compilation bugs and building a database of exact solutions for them. If you are currently fighting a messy React Native or Expo native stack trace that makes absolutely no sense, I built a live beta engine to parse them and spit out precise resolutions over at fix-my-error-app.com. Drop your errors in there if you're stuck, and let me know in the comments what your most hated native build error is!

Drop your errors in there if you're stuck, and let me know in the comments what your most hated native build error is!

WWDC26 Highlights

Tue, 09 Jun 2026 07:41:20 +0000

Apple Intelligence 2.0 and Siri AI

Apple used the WWDC26 keynote to introduce a new generation of Apple Intelligence that expands on last year's generative features. The upgraded system runs on a privacy‑preserving architecture that uses on‑device models and Private Cloud Compute. The new Siri AI is deeply integrated across iPhone, iPad, Mac, Apple Watch and Vision Pro. Siri can now understand what's on screen and draw on personal context to search across messages, photos, emails and third‑party apps. When needed, it reaches out to the web to provide up‑to‑date answers. A dedicated Siri app lets users revisit past conversations and syncs history across devices via iCloud.

Apple Intelligence also powers new experiences across the system. Spatial Reframing in Photos lets users re‑compose pictures after they are taken. Image Playground can generate high‑quality images, and Messages and Mail offer AI‑driven suggestions for replies and reminders. The intelligence features support multiple languages, run on devices with A17 Pro or M‑series chips and will be available in the fall with iOS 27.

Foundation Models framework

For developers, the most transformative announcement is the Foundation Models framework in iOS 27. It is a native Swift API that gives apps direct access to the same on‑device language model powering Apple Intelligence. Developers can switch between Apple's model, cloud models (such as Claude or Google Gemini) or any provider that implements the new Language Model protocol. The framework supports multimodal prompts, allowing apps to pass images alongside text and use Vision tools like OCR and barcode readers. Dynamic Profiles let developers swap models, tools and instructions during a session so their app's behavior adapts to the user's needs.

Smaller teams benefit from cost‑free access: developers enrolled in the App Store Small Business Program and with fewer than 2 million first‑time downloads can use Apple's next‑generation models on Private Cloud Compute at no cloud API cost. A new Evaluations framework helps verify that AI features behave correctly across dynamic conditions.

Core AI

Where Foundation Models provides access to generative models, the new Core AI framework lets developers bring their own models on‑device. Core AI offers a memory‑safe Swift API and accompanying Python tools to load, specialize and run models entirely on Apple hardware. It delivers zero server dependencies and zero token costs while supporting everything from compact vision models on iPhone to multi‑billion‑parameter language models on Mac. Core AI integrates with ahead‑of‑time compilation, a visual tensor debugger and optimization tools to convert PyTorch models for the Core AI runtime. Apple noted that Core AI is optimized for Apple Silicon and also powers Apple Intelligence experiences across the system.

App Intents and System‑wide Intelligence

The App Intents framework has been expanded so Siri and Apple Intelligence can perform more actions with third‑party apps. Entity schemas allow an app's content to be indexed in the Spotlight semantic index, making it discoverable by Siri. Intent schemas define actions that users can take naturally without pre‑defined phrases. A new View Annotations API maps views to entities so users can reference on‑screen content conversationally. Apple also introduced an App Intents Testing framework to validate integrations without UI automation.

The Platforms State of the Union elaborated on how App Intents works with the System Orchestrator, Spotlight semantic index and the App Toolbox to route user requests across apps. Siri AI can now surface your app's content and actions through widgets, the Action button and voice interactions, and these integrations automatically improve as Siri learns new languages or dialects.

Last year's Liquid Glass design language unified Apple's platforms. For 2026, Apple tuned it to improve readability and depth. Liquid Glass now diffuses complex content more effectively and adds a darkened edge with brighter specular highlights. Users can personalize the effect with a slider ranging from ultra‑clear to fully tinted. Apps already using Liquid Glass get these improvements automatically without recompiling. The design adapts to accessibility settings (e.g., reduced transparency and increased contrast) and introduces colored sidebars, refined toolbar behavior and improved icon rendering with refraction effects.

Resizability and SwiftUI

With iOS apps appearing on iPad and Mac via iPhone Mirroring, Apple introduced resizable iOS apps. Rebuilding with the latest SDK automatically opts an app into resizability. SwiftUI and auto layout provide basic support, while the new Resizable iOS Simulator and Previews let developers test across sizes. A built‑in agentic coding skill helps find and fix resizability issues.

SwiftUI itself gains richer interactions such as reorderable containers, allowing drag‑to‑reorder lists and grids with minimal code. SwiftUI's improvements target speed, dynamic interactions and new capabilities, making it easier for developers and encouraging migration from cross‑platform technologies.

Xcode 27: Enhanced Productivity with Agentic Coding

Apple’s flagship IDE saw major updates. The new Xcode 27 focuses on two pillars: intelligence and daily usability. Performance improvements make projects load faster, debug sessions more reliable and the console capable of handling heavy logging. Xcode 27 is 30 % smaller, now runs only on Apple Silicon and downloads agents and documentation in the background to stay up‑to‑date.

Personalization options now sync settings via iCloud. When setting up a new Mac, Xcode imports preferences and Git configuration automatically. Creating a new project jumps straight into the editor, deferring file names and bundle IDs until later. Developers can customize the toolbar and choose from new color themes such as Emerald, Neon Noir and Coral Reef. Xcode Cloud builds are up to twice as fast and require no App Store Connect setup, supporting Apple Vision Pro and Metal apps.

A Device Hub merges the simulator and physical device management into one interface. It supports pinch‑to‑zoom, two‑finger scrolling, dynamic resizing and testing of various system settings like dark mode and text size.

Agentic Coding

Xcode 27 weaves coding agents into every layer. Agents can plan, implement and test features. Developers start by describing their idea; the agent generates a plan, asks clarifying questions and produces code and UI previews. Agents can run tests in the simulator, localize strings, and even identify and fix crashes based on crash logs. Xcode 27 includes specialized skills—for SwiftUI, accessibility and performance—that help agents produce high‑quality code.

Other Notable Frameworks and Tools

Platform improvements: The new SDK makes apps launch faster and adds enhancements across frameworks, media, search and accessibility.
Game Porting Toolkit 4: Features agentic coding skills for Metal and game development, speeding up ports to Apple platforms.
Music Understanding framework: Enables six‑dimensional audio analysis and works with NowPlaying to integrate playback with Lock Screen, Control Center, Dynamic Island and CarPlay.
Photo and camera APIs: Core Image RAW processing APIs (version 9) provide improved sharpness and color, and new APIs support high‑resolution photo capture and Center Stage front‑camera features

How to Fix Xcode C++ Compiler Errors in React Native (Yoga / glog / constexpr)

Sat, 06 Jun 2026 09:39:12 +0000

You just upgraded your local development environment, updated Xcode, or bumped a minor patch version in your React Native project. You open your terminal, run your standard iOS build command, and instead of a clean bundling process, the terminal throws a massive wall of raw C++ compiler text at you.

The error logs likely point to internal framework files like Yoga.cpp, glog, or the fmt library, screaming about constexpr or consteval issues, or complaining that a specific language standard identifier is missing.

This is one of the single most frustrating traps in mobile development. Your JavaScript is perfect. Your React components are clean. But your entire build is dead because an underlying C++ compilation standard is fighting your new Xcode tooling.

Why This Happens to JavaScript Developers

React Native relies heavily on a core C++ layout engine called Yoga under the hood. When Apple updates Xcode, they also update the underlying compiler tools (Clang) and shift the default C++ language dialect standard forward (for example, enforcing strict C++20 or C++23 rules).

If an older version of a library in your node_modules uses a syntax decoration that the new compiler now considers illegal or deprecated, the native compilation step fails instantly. Because most mobile developers do not actively write pure C++, looking at a raw Clang compiler failure feels like looking at alien code.

Nuking DerivedData or running pod install twenty times will not change the fact that the compiler rules have changed.

The Solution: Force the C++ Language Standard Backwards

Instead of attempting to manually modify source code deep inside your native node_modules dependencies (which will just get overwritten the next time you install packages), you can use a CocoaPods post-install hook to force the compiler to accept the specific language dialect your dependencies need to pass the check.

Open the Podfile located inside your project's native ios directory. Scroll down to the bottom where your post_install loop lives, and inject this compiler flag override block:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      # Force the compiler to use the stable C++17 standard for all sub-dependencies
      config.build_settings['CLANG_CXX_LANGUAGE_STANDARD'] = 'c++17'
    end
  end
end

By adding this configuration script, CocoaPods will automatically modify the native build files for every single sub-dependency when you run your installation pipeline, forcing Xcode to evaluate the underlying C++ libraries under a compatible standard framework.

Clear the Native Caches and Rebuild

Once the project configurations are updated, you must completely destroy the old build artifacts that were compiled under the conflicting settings, or Xcode will continue to throw the same syntax exception.

Run this quick command chain in your project terminal to wipe the native cache layers and execute a clean compilation:

# Clear Xcode's local compilation cache
rm -rf ~/Library/Developer/Xcode/DerivedData

# Re-evaluate the Podfile with the new compiler hook
cd ios
pod install --repo-update

# Return to root and boot the iOS simulator
cd ..
npx react-native run-ios

As soon as the native build pipelines evaluate your sub-dependencies through the consistent compiler standard, the cryptic layout exceptions will vanish and your bundle will build cleanly.

Essential Claude Code Skills for Mobile Developers

Thu, 02 Apr 2026 07:22:03 +0000

Claude Code skills are packaged folders of instructions, scripts and resources that teach the AI coding agent how to perform specialised tasks.

Each skill has a SKILL.md file containing YAML metadata and step by step instructions. Claude scans the names and descriptions of installed skills and loads the full content only when your request matches.

Because skills are part of an open standard adopted by multiple agent frameworks, a single skill can work across Claude Code, OpenAI Codex, Cursor and other tools.

Installing Claude Code skills

Skills can be installed globally or per project. Personal skills go into ~/.claude/skills/ and become available across all your projects, while project specific skills live in .claude/skills/ inside your repository so everyone who clones the repo can use them.

Most skills are plain Markdown folders: clone the repository and copy the skill directory into the appropriate folder. For example, the Swift Development skill’s README shows that you can install it by copying the Swift Development skill directory into ~/.claude/skills/ and then invoking it via /swift-development.

Recommended skills for mobile developers

Below is a curated list of Claude Code skills that are particularly valuable for mobile developers working with native iOS, Android or Kotlin Multiplatform (KMP). The list covers a range of design and development tasks. Each skill is linked to its repository or marketplace page along with a brief description.

Swift Development
https://github.com/hmohamed01/swift-development
This comprehensive skill turns Claude into a competent Swift engineer. It packages patterns for SwiftUI navigation, concurrency (async/await, actors) and testing frameworks, along with helper scripts for building, running tests, formatting code and managing simulators. Installation is simple: copy the Swift Development directory into your personal skills folder and invoke it with /swift-development.

iOS Mobile Design
https://mcpmarket.com/tools/skills/ios-mobile-design
For designers and developers building polished iOS apps, this skill provides expert guidance on Apple’s Human Interface Guidelines. It teaches Claude how to apply SwiftUI layout systems, dynamic type, SF Symbols and modern navigation patterns so interfaces feel native to iPhone, iPad and visionOS. Key features include accessible design with dynamic type, responsive layouts, Material You style theming and Dark Mode optimisation.

iOS App Builder
https://mcpmarket.com/tools/skills/ios-app-builder
This skill transforms Claude into a senior iOS developer who builds and ships native apps using a command line only workflow. It uses Xcode’s xcodebuild and simctl tools to scaffold projects, run tests and launch apps without opening Xcode. The skill emphasises a “prove, don’t promise” methodology: it verifies logic through tests and simulator screenshots, manages the full app life cycle from scaffolding to App Store readiness and includes features like performance profiling and memory leak detection

SwiftUI agent skill
https://github.com/twostraws/swiftui-agent-skill
A SwiftUI skill create by Paul Hudson (hacking with swift).
This skill helps identify and fix common mistakes AI agents make when writing SwiftUI – things like modern API usage, performance, accessibility, and more.

Android Development
https://github.com/dpconde/claude-android-skill
Designed for modern Android projects, this skill teaches Claude clean architecture with separate UI, domain and data layers. It covers Jetpack Compose patterns and best practices, multi module project structures, offline first architecture using Room and reactive streams, dependency injection with Hilt and comprehensive testing strategies. After cloning the repository into your skills folder, you can ask the agent to scaffold features, create Compose screens or set up repositories following Android best practices.

Android Kotlin Development
https://fastmcp.me/skills/details/241/android-kotlin-development
This skill focuses on building native Android apps with Kotlin. The description explains that it covers Model-View-ViewModel architecture with Jetpack, Compose for declarative user interfaces, Retrofit for API calls, Room for local storage and navigation patterns. It includes detailed instructions and code samples for models, API services and MVVM view models, making it a practical guide for Kotlin developers.

Mobile Android Design
https://fastmcp.me/skills/details/644/mobile-android-design
When you need to design Android interfaces that follow Google’s Material Design 3 guidelines, this skill is indispensable. It teaches Claude how to build adaptive layouts with Jetpack Compose, implement navigation patterns like bottom navigation and drawers, use dynamic colour and Material You theming, and create accessible UI for phones, tablets and foldables. It is especially helpful for modernising existing apps or ensuring new designs comply with Material Design principles.

Jetpack Compose Expert
https://github.com/aldefy/compose-skill
This skill provides Claude with real source code and extensive reference guides for Jetpack Compose. Without it, AI tools often misuse remember, generate inefficient recompositions or misorder modifiers; with the skill, Claude picks the right state primitive, applies stability annotations and orders modifiers correctly. The reference guides cover state management, view composition, performance, navigation, animation, lists, side effects, modifiers, theming, accessibility and deprecated patterns. Installation requires cloning the repository and copying the Jetpack Compose expert skill directory into your skills folder; Claude will automatically activate it when you mention Compose or related API names.

Kotlin Multiplatform (KMP) Abstraction Guide
https://fastmcp.me/skills/details/2190/kotlin-multiplatform
KMP projects often involve tough decisions about what to share between platforms and what to keep platform specific. This skill guides those decisions by providing a platform abstraction decision tree. It explains when to use commonMain, jvmAndroid or expect/actual patterns, covers targets like Android, JVM/Desktop and iOS, and offers triggers for questions such as "should I share this ViewModel?". It helps developers place code correctly and prepare for future web or WebAssembly targets.

I open-sourced 5 tiny SwiftUI utilities I use in every project

Mon, 23 Mar 2026 14:37:01 +0000

Sharing 5 lightweight SwiftUI packages I built — keyboard avoider, scroll offset tracker, shimmer effect, flow layout, and App Store review link

Hey everyone! I've been building iOS apps for a while and kept copying the same utilities across projects, so I finally packaged them up as SPM libraries.

1. swiftui-keyboard-avoider

One-line modifier that moves your view when the keyboard appears.

TextField("Email", text: $email)
  .keyboardAvoider()

2. swiftui-scroll-offset

Track ScrollView offset — great for collapsing headers.

OffsetTrackingScrollView { offset in
  print(offset.y)
} content: {
  // your content
}

3. swiftui-shimmer-loading

Shimmer / skeleton loading effect for any view.

Text("Loading...")
  .shimmer()

4. swiftui-flow-layout

Wrapping HStack for tags and chips. Uses the Layout protocol.

FlowLayout(spacing: 8) {
  ForEach(tags, id: \.self) { Text($0) }
}

5. ios-appstore-review-link

Open App Store review page with one line.

AppStoreReview.open(appID: "123456789")

Or grab them all at once: SwiftUI Essentials

All MIT licensed, zero dependencies. Would love any feedback or suggestions!

How a Bug Report Led Me to Give Flutter Developers Full Control of Crisp Chat Modals on iOS

Sun, 15 Mar 2026 07:25:41 +0000

One of the things I enjoy most about maintaining open-source software is that sometimes the best improvements start with something very small.

A simple bug report.
A curious investigation.
And sometimes… a new feature idea.

This story started exactly like that.

The Bug Report That Started Everything

While reviewing issues for the Flutter Crisp Chat plugin, I noticed a report opened by Nikita Alexeev.

The title immediately caught my attention:

“Taps pass through chat modal to underlying UI on iOS 13+.”

That sounded strange.

A modal should block interactions with the UI behind it. So how could taps reach the Flutter app underneath?

I opened the issue and read the details carefully.

The behavior was simple but frustrating:

Open the Crisp chat on an iPhone
Tap near the top area of the chat
Suddenly the Flutter UI behind it reacts

Buttons could be pressed. Navigation could trigger. All while the chat was still visible.

That’s definitely not the experience anyone wants when they open a support chat.

So I started digging.

Learning Something Interesting About iOS

While reading the issue discussion and the explanation from Nikita Alexeev, I discovered something interesting about iOS.

Starting with iOS 13, Apple changed how modal presentations behave by default.

Before iOS 13, most modals were presented using:

.fullScreen

Which means the modal covers the entire screen. Nothing behind it is visible, and more importantly, nothing behind it can receive touches.

But iOS 13 introduced a new default style:

.pageSheet

This creates the modern sheet-style UI where the modal slides up from the bottom and leaves part of the background visible.

It looks elegant and more native to modern iOS design.

But there was a catch.

In this case, the dimmed background area was still allowing touch events to reach the Flutter UI underneath.

That explained exactly why users were accidentally triggering buttons behind the chat window.

Suddenly the bug made perfect sense.

The Pull Request That Fixed It

Soon after reporting the issue, Nikita Alexeev submitted a pull request with a very straightforward fix.

Instead of relying on the default modal style, he forced the chat view controller to use full screen presentation.

The change looked like this:

let chatVC = ChatViewController()
chatVC.modalPresentationStyle = .fullScreen
viewController.present(chatVC, animated: true)

It was a very small change, but it solved the problem completely.

By forcing .fullScreen, the chat now covered the entire screen again, which meant no touches could leak through to the Flutter UI behind it.

The issue was fixed.

But while reviewing the pull request, a new idea came to my mind.

The Moment the Idea Appeared

Yes, .fullScreen solved the issue.

But iOS actually supports several modal presentation styles.

For example:

.fullScreen
.pageSheet
.formSheet
.overFullScreen
.overCurrentContext
.popover

Different apps use different modal styles depending on their design.

Some apps prefer full screen.

Some prefer sheet-style modals.

Some prefer overlays.

So instead of hardcoding .fullScreen, I thought:

What if Flutter developers could choose the modal style themselves?

That way:

The touch-through bug stays fixed
Developers get flexibility
The plugin becomes more powerful

That’s when the idea shifted from a bug fix to a developer-focused feature.

Turning the Idea into a Feature

To make this possible, I needed to expose the modal presentation style all the way from Flutter to the native iOS implementation.

So I started with the Flutter configuration.

Step 1 — Extending the Flutter Configuration

First, I added a new enum to represent the iOS modal styles.

enum ModalPresentationStyle {
  fullScreen,
  pageSheet,
  formSheet,
  overFullScreen,
  overCurrentContext,
  popover,
}

Then I added it to the CrispConfig class.

class CrispConfig {
  final String websiteID;
  final String? tokenId;
  final ModalPresentationStyle? modalPresentationStyle;

  CrispConfig({
    required this.websiteID,
    this.tokenId,
    this.modalPresentationStyle,
  });
}

Now Flutter developers could specify how the chat modal should appear.

Step 2 — Bridging the Setting to iOS

Next, I needed to convert that Flutter value into a native iOS presentation style.

Inside the Swift plugin code, I mapped the configuration to UIModalPresentationStyle.

switch modalPresentationStyleString {
case "fullScreen":
    modalPresentationStyle = .fullScreen
case "pageSheet":
    modalPresentationStyle = .pageSheet
case "formSheet":
    modalPresentationStyle = .formSheet
case "overFullScreen":
    modalPresentationStyle = .overFullScreen
case "overCurrentContext":
    modalPresentationStyle = .overCurrentContext
case "popover":
    modalPresentationStyle = .popover
default:
    modalPresentationStyle = .fullScreen
}

This ensured a safe default while still allowing flexibility.

Step 3 — Applying the Configuration

Finally, instead of hardcoding .fullScreen, the plugin now uses the configured style.

let chatVC = ChatViewController()
chatVC.modalPresentationStyle = crispConfig.modalPresentationStyle

viewController.present(chatVC, animated: true)

Now Flutter developers have full control over the presentation style.

Making the Feature Easy to Discover

After implementing the improvements, I wanted to make sure developers could easily explore and understand them.

So I also improved the developer experience around the plugin.

I added an interactive demo inside the example app where developers can test different iOS modal styles.

There’s a button called “iOS Modal Style Demo” that opens the chat using different presentation styles so developers can see how each one behaves.

I also updated the documentation to clearly explain:

How iOS modal presentation works
Why .fullScreen fixes the touch-through issue
How to configure the modal style in Flutter

What Developers Gain From This

What started as a small bug report now gives Flutter developers several benefits.

Better User Experience

No more accidental taps on the UI behind the chat.

Flexible Modal Presentation

Developers can choose the modal style that fits their app design.

Platform Awareness

These changes only affect iOS behavior, while Android remains unchanged.

What I Love About Open Source

This experience reminded me why I enjoy maintaining open-source projects.

Sometimes improvements don’t start with big feature ideas.

They start with a simple issue report.

A developer noticing something strange.

A pull request proposing a fix.

And a moment of curiosity that turns a bug fix into something better.

So huge thanks to Nikita Alexeev for reporting the issue and submitting the original fix that inspired this improvement.

Try It Yourself

If you’re using the Flutter Crisp Chat plugin, you can try the new configuration like this:

final config = CrispConfig(
  websiteID: 'YOUR_WEBSITE_ID',
  modalPresentationStyle: ModalPresentationStyle.pageSheet,
  enableNotifications: false,
);

And if you’re curious to see how each modal style behaves, check out the example app in the repository.

Sometimes the best features don’t start with a roadmap.

They start with a bug report…
and a little curiosity.

React Native Quote Audit - USA

Mon, 02 Mar 2026 14:30:00 +0000

A Quick Test to See if your Quote is Missing Money.
If you are building a React Native app in the USA, a quote can look fine and still be missing big items.

Missing items do not stay missing.
They show up later as extra invoices, delays, and stress.

This post is a simple quote audit.
You can use it in 10 minutes before you sign.

Download the printable checklist PDF
React Native Budget Checklist USA 2026
Use it while reading the quote. Use it again during kickoff.

Section 1
---------
A Quick Test
Is your quote missing money?
Answer yes or no.

Does the quote show a clear list of what is included
Does it show what is not included
Does it include testing time and bug fixing time
Does it include store release work for iOS and Android
Does it include payment failure cases and double order prevention
Does it include device testing on more than two phones
Does it include who owns accounts, code, and access
Does it include change request rules and pricing

If you said no to three or more, the quote is likely missing money.

Section 2
---------
The 5 line items that are usually missing from quotes
These five items are where cost and time jump.

1. Testing and bug fixing
Many quotes say development, but they hide testing.

What this should include
QA testing time
Bug fixing time
Retesting time
Basic regression testing before release

If it is missing, you will pay later.

2. Device list and device testing
Testing on one iPhone and one Android is not real testing.

What this should include
A short device list
At least one mid range Android phone
A plan for bugs that happen on one device only

3. Store release work
Many quotes end at build ready.
Real work still remains.

What this should include
Signing and build setup
Store listing details
Screenshots
Privacy forms
Review notes
Buffer time for rejection and resubmission

4. Payments and failure cases
If your app has payments, the happy path is not enough.

What this should include
Payment failed handling
Payment success but order not confirmed
User taps pay again
Status checks to stop duplicate orders

5. Upload failure handling
If your app has uploads, failures will happen.

What this should include
Slow internet handling
Retry steps
Clear error messages
Safe continue steps so users do not get stuck

Section 3
---------
Questions to ask your developer before you sign
Ask these questions in a call.
If answers are vague, expect trouble.

Scope and plan

What is out of scope for version one
What are the hard screens in this app
Which parts have the most risk

QA and devices

What is your test device list
How many rounds of QA are included
Is bug fixing included or billed extra
What happens when a bug only happens on one Android model

Payments and uploads

How will you stop duplicate orders if payment is slow
How will you handle payment success but order not updated
How will uploads work on slow internet
What happens when users deny camera or photo access

Release and ownership

Who owns the Apple and Google store accounts
Who owns the code repo
Will you hand over all keys and access at the end
How many days do you keep for store review and fixes

Change control

How do you price a change request
What counts as a change
Who approves changes and how fast

If the team cannot answer these clearly, the quote is not ready.

Section 4
---------
Red flags checklist
Here are the red flags. If you see these, pause.

Red flag 1
One total number with no phases

Red flag 2
No QA time mentioned

Red flag 3
No device list mentioned

Red flag 4
No store release work mentioned

Red flag 5
Payments included but no talk about failure cases

Red flag 6
Uploads included but no talk about slow internet failures

Red flag 7
No clear list of what is included and not included

Red flag 8
No mention of who owns the repo and accounts

Red flag 9
No change request rules

Section 5
---------
Example
Medicine delivery app quote audit

Example app
A healthcare shopping app that sells medicines and daily use products.

Core features
Product list
Product page
Cart
Checkout
Order tracking
Prescription upload for some medicines
Notifications for order updates

Now the audit.

What many quotes cover
Screens and basic flows
Basic backend endpoints
Basic login
Basic checkout screen

What many quotes miss
Prescription upload details
Camera and photo permissions
Users deny access
Slow internet upload failures
Retry steps and clear messages

Payment edge cases
Payment success but order status not updated
Users retry and create duplicate orders
Need status checks and duplicate order prevention

Device testing
Android device differences
Notifications blocked by battery settings
Camera issues on certain models

Store release
Privacy forms
Permission text
Store review changes
Resubmission buffer

If the quote does not mention these items, the quote is missing money.

This is why a simple app can move from 8 weeks to 14 weeks.
Not because of new screens.
Because missing items show up late.

Section 6
---------
What a good quote looks like
A good quote is split into clear parts. Each part has a line item and a clear output.

1. Discovery
What it should include
Requirements list
User flows
Out of scope list
Hard screens list
Risk list

What you should receive
A written scope document
A clear list of what is included and not included

2. Design
What it should include
Key screens
All states for key screens
Error messages
Permission screens

What you should receive
Final screen designs
A simple flow for each key feature

3. Development
What it should include
App build work
Backend work
Admin work if needed

What you should receive
Working builds you can test
Access to the code repo

4. Integrations
What it should include
Payments
Push notifications
Analytics
Uploads
Maps or other tools

What you should receive
A list of all tools used
Proof that each tool works on iOS and Android

5. QA
What it should include
Device list
Test plan for key flows
Bug fixing time
Retesting time

What you should receive
A test report or bug list
A stable build before release

6. Release
What it should include
Signing and build setup
Store listing tasks
Screenshots
Privacy forms
Time buffer for review and resubmission

What you should receive
Store ready builds
A release checklist

7. Handover
What it should include
Repo access
Accounts access
Keys
Basic documentation

What you should receive
Full ownership and access
A handover checklist

8. Change rules
What it should include
What counts as a change
How changes are priced
Who approves changes

What you should receive
Clear change request rules in writing

If your quote does not look like this, ask for a rewrite.

App Maintenance In The USA (2026): $500 To $25,000 Per Month Depending On Stage

Wed, 18 Feb 2026 09:42:29 +0000

Most founders budget the build. Then launch happens, and the monthly bills start.

In the United States, app maintenance is not just bug fixes. These include updates, store submissions, OS changes, payments, crashes, analytics cleanup, and support issues that only appear with real users.

Here are a few numbers from our 2026 benchmark page that surprised people on calls.

What Most US Startups Pay Per Month

These are planning ranges, not quotes, but they are useful when you are setting budgets.

Small MVP with light traffic:
500 to 2,000 USD per month
6,000 to 24,000 USD per year

Growing app with regular releases:
2,000 to 7,000 USD per month
24,000 to 84,000 USD per year

Complex app with revenue and multiple integrations:
7,000 to 25,000 USD per month
84,000 to 300,000 USD per year or more

A quick rule many teams use: maintenance often lands around 15 to 25 percent of the original build cost per year, depending on complexity and release frequency.

The Hidden Calendar Cost Nobody Mentions

Even if your fix is ready today, store review cycles still add time.

Apple’s own guidance says about 50 percent of apps are reviewed within 24 hours and 90 percent within 48 hours on average. That sounds fast until you hit resubmissions, missing test accounts, or policy changes. So a small fix can take days on the calendar.

We Looked At 30 Agency Proposals And Found The Same Gaps

We did a small review of 30 proposals and statements of work. It's not a perfect study, but the pattern was loud.

These were missing or unclear most often:
Dependency and library upgrade cadence
Missing in 24 of 30 proposals, about 80 percent

QA device and OS test matrix
Missing in 23 of 30 proposals, about 77 percent

Push notification rules like quiet hours and caps
Missing in 22 of 30 proposals, about 73 percent

Bug severity definitions and response time
Missing in 21 of 30 proposals, about 70 percent

Analytics scope and event naming
Missing in 20 of 30 proposals, about 67 percent

These gaps are exactly where surprise fees show up after launch.

If You Are Budgeting For 2026, This Page Helps You

The full blog includes:
Monthly retainer tier you can use for vendor calls
A contract ready maintenance line items table
A copy paste maintenance checklist for weekly, monthly, quarterly
When it's smarter to rebuild instead of keep patching

Read it here!

If you are a founder or dev, what was the most annoying after launch cost you ran into?

Magic Beyond Hogwarts: How to Build "Expensive" UI Without Overloading the GPU

Sat, 07 Feb 2026 17:06:01 +0000

You've probably seen this scenario before: a developer falls in love with a concept from Dribbble, spends two days implementing the most complex transition chain, and then wonders why their iPhone 15 Pro starts heating up after five minutes of app usage. Animation is always a deal with the devil (hardware). The question is just how favorable an exchange rate you can negotiate.

The Price of Every Frame: CPU, GPU, and Battery

When we launch an animation, we force the system to work at its limit for a short period of time. In an ideal world (60 or 120 FPS), we have about 8–16 milliseconds to prepare a frame.

CPU (Layout & Preparation): This is where the most "expensive" stuff happens. Recalculating constraints, creating view hierarchies, calculating paths - all of this falls on the central processor's shoulders. If you animate frame or bounds on a view with tons of child elements, expect trouble: the system will call layoutSubviews() at every step.
GPU (Rendering): The graphics chip takes care of rasterization and layer compositing. The main enemies here are transparency (Alpha Blend), blur (Visual Effects), and shadows without a specified shadowPath.
Battery: This is the "invisible" metric. High CPU/GPU Usage directly converts into percentage points of charge. Users might not notice a drop to 55 FPS, but they'll definitely notice that your messenger "ate" 20% of their battery in half an hour.

Implicit Animations: The Magic of `withTransaction`

In SwiftUI, we're used to .animation(.easeInOut, value: target). But sometimes we need finer control over the process, especially when we want to synchronize changes or suppress animation for specific elements.

I prefer using withTransaction for complex transitions. This allows you not just to "turn on" animation, but to pass context: for example, disable animation for a specific change inside the block while preserving it for everything else.

var transaction = Transaction(animation: .spring())
transaction.disablesAnimations = false // Flexible control over the logic

withTransaction(transaction) {
    self.showDetails.toggle()
    // This change will pick up the transaction settings
}

This is much cleaner than trying to wrap every view with its own .animation(). Plus, it helps avoid the "jello effect," when elements fly off in different directions due to conflicting instructions.

UIView.animate vs SwiftUI Animation

If you're still maintaining UIKit projects (or writing wrappers for SwiftUI), the question arises: what to use?

UIView.animate is good old-fashioned classic, working on top of Core Animation. It's predictable. But in SwiftUI, animations are built on a different principle: they depend on state changes (State-driven).

My rule is simple:

If you need to animate CALayer properties (for example, borderWidth or specific masks) - go with UIKit/Core Animation.
If you're working with navigation and content updates in SwiftUI - use native tools.

The main mistake in SwiftUI is animating everything with .animation(.default). Always specify the concrete value (value) that the animation should react to. Otherwise, you risk getting parasitic movements when other screen properties update.

The Cardinal Sin: Layout on Main Thread

The fastest way to kill performance is to force the Main Thread to calculate geometry during animation. When you change constraints inside an animation block, you trigger a heavy recalculation process for the entire tree.

How to do it right: Instead of changing height or width, use CGAffineTransform (in UIKit) or .scaleEffect() / .offset() (in SwiftUI). These properties are handled by the GPU. The system simply takes an already prepared "snapshot" of the view and transforms it without recalculating the positions of neighboring elements.

// Bad: triggers Layout recalculation
view.frame.size.height = 200 

// Good: just a visual transformation
view.transform = CGAffineTransform(scaleX: 1.2, y: 1.2)

Xcode Instruments: The Developer's Eyes

If animation "lags" to the naked eye - you've already lost. But how do you understand why it lags? I run Animation Hitches in Xcode Instruments at least once a week.

Core Animation Instrument: Shows frame rate and, more importantly, "Color Offscreen-Rendered Yellow". If your screen is flooded with yellow - you're forcing the GPU to do double work (for example, rendering masks or shadows without optimization).
Hitch Rate: Apple introduced this term to measure interface "stuttering". A good metric is less than 5 ms/s.

Accessibility: Respect Your User

Remember people who get motion sick from abrupt movements. iOS has a Reduce Motion setting.

Ignoring it is a sign of poor taste and unprofessionalism. If a user asked the system not to move, your full-screen zoom effect should turn into a simple and elegant crossfade.

In SwiftUI, this is done elementarily:

@Environment(\.accessibilityReduceMotion) var reduceMotion

var body: some View {
    Circle()
        .offset(x: moveIt ? 100 : 0)
        .animation(reduceMotion ? nil : .easeInOut, value: moveIt)
}

I always check this flag. Trust me, users with vestibular disorders will thank you (even though you'll never know about it).

The "Sufficiency" Guideline

Polish is cool, but it's easy to turn an app into a Christmas tree. Here are my internal criteria for "healthy" animation:

Duration: Most UI animations should fit within the 0.2 – 0.3 second range. Anything longer starts to irritate with frequent use.
Functionality: Animation should explain where an element came from and where it went. If it's just "for beauty" and doesn't carry meaning - delete it.
Responsiveness: If a user tapped a button, the reaction should be instant. Don't make them wait for an animation to finish to perform the next action (Interruptible animations are everything).

Animation is a balance between art and mathematics. Try right now to open your most complex screen in Xcode Instruments and look at the Hitch Rate. If you see red zones - start by replacing constraint animations with CGAffineTransform.

How much does it take to “finish” an app

Fri, 06 Feb 2026 01:40:00 +0000

Quite strange equation, don’t you think? But in a developer’s world, math works in unexpected ways.

Six months ago, I decided to build the best EPUB reader for Apple devices. I started immediately and, in four months, I had a working prototype with about 90% of the functionality. Everything worked as expected. Without fear, I launched my first TestFlight.

I expected anything and everything, but not this: I slid back to 10% done.

Somewhere in 2025, I watched Sean Allen’s video on the “90/90 rule.” Now I truly know, what that second 90% means.

TestFlight revealed two truths to me:

Developers are always wrong
When you think you’re almost done, you’ve barely started

These two things forced me to rethink the app’s internals, design, and UI.

I spent the last two to three weeks working harder than in the previous four months. I spent nights fixing bugs, unifying the interface, working on promised features, and making sure, that basics are there (like a consistent close button: top-right X, always).

And even now, I’m not “finished.”

Since this series is about justRead.app development, here’s the latest state with tech details.

What was fixed

The killer problem was simple: the app was freezing and crashing. Something I didn’t experience in development, something TestFlight users experienced a lot.

justRead.app loads epub files from the cloud, often buried deep in subfolders (not yet downloaded). When folder with books is selected, it ran three heavy processes:

Analyze all the (sub)directories for epub files (no files downloaded)
Extract thumbnails and some accessible data from those files (still no files downloaded)
Parse metadata (downloading of files starts now)
Users saw a “frozen” app, they tried everything, then app then crashed. What was worse: on relaunch with a selected library, it repeated the exact same cycle with the exact same result for user.

The fix:

The app is running the same processes, but now in the background with clear user progress indicators. Users can read downloaded books while those three processes are running. Simple and completely avoided with better testing.

Smaller bugs got fixed too: streak calculations, read-time tracking, bookmark saves.

What was changed

Non-crashing users gave me around 20 ideas like:

Tap anywhere on a book row to open it (not just the cover)
Hide settings on book start
Load font manually from menu, not automatically from folder

I experimented with all the ideas, iterated on users feedback and implemented what was the best fit.

What was added

No breakage risk here. Those were added:

Statistics dashboard
Roadmap with user voting
Alphabet jump bar for libraries
Extra settings tweaks.

Plus about 50 other small things, like highlighting your current TOC chapter.

TestFlight #2

It’s live today.
This time, I’m expecting crashes, freezes, and issues.

As a user, why is this all important?

You want polished apps, no crashes, intuitive user interface. You are expecting a developer who cares about the app, because he uses it.

That’s why TestFlight matters. Apple enables it, testers refine the app and the users get app as polished as possible.

The voting roadmap builds on this: you shape justRead.app’s future, prioritizing what you want.

As a developer, why is this all important?

We build apps and systems because we love to.

Sean’s rule reminds us: the final 90% polish is the app.

Rush development and release, and you ship a prototype.

Deliver the app polished, and you create something users love.

That’s why 90% + 90 % makes 100%.

And to answer the question in the beginning: it does take a lot more than what you have planned. Even if you have years of experience in development.

_justRead.app is an epub reader for iPhone, currently in TestFlight.__
Peter
Reader, Developer, justRead.app Creator

When Your App Freezes in Front of Your Testers: What I Learned About Ego & iOS Development

Mon, 26 Jan 2026 00:14:00 +0000

Development of justRead app in six parts; part five.

I’ve been building software for almost 15 years. Manufacturing systems, backend services, databases that handle millions of transactions. Things that actually matter, production lines depend on them. I thought I knew what I was doing.

Then I shipped my first TestFlight, and my app crashed for 50% of my testers.

The confidence trap

When you’ve spent a decade and a half solving hard problems, you develop a certain… confidence. Not arrogance, exactly. Just the quiet assumption that you understand your domain. You’ve debugged memory leaks in enterprise systems. You’ve optimized database queries for millions of records. You’ve shipped products to paying customers who depended on your code.

Building a native iOS app in SwiftUI felt manageable by comparison. Smaller scope. Single platform. Modern tooling. Surely the hard parts were the product design and the business strategy, not the code.

So when I invited 157 testers to try justRead, my e-book reader app, I was genuinely unprepared for what came next.

The day everything broke

The numbers seemed reasonable at first:

157 people applied for TestFlight
88 actually run the TestFlight
4 unsubscribed immediately (missing features they wanted)
84 stayed and used TestFlight
10–15 engaged deeply with feedback

What I wasn’t ready for: approximately 50% of those users experienced crashes and freezes. Not occasionally. Repeatedly.

The feedback came in waves on the first day. “App froze.” “Crashed when I opened a book.” “Keeps crashing during search.” “Freezes and won’t respond.”

I felt it immediately: shame & embarrassment. That specific kind of ego hit you get when you assumed you were competent and the evidence suggests otherwise.

My first instinct was to fix it immediately. I pushed four quick builds in rapid succession, each targeting what I thought were the culprits. Each time I was convinced I’d found it. Each time, I learned I hadn’t.

The problem I didn’t expect

I totally not anticipated: the app was trying to download data from cloud storage to local iPhone storage in the background while users were trying to interact with it. The process wasn’t properly managed. It wasn’t being cancelled. It wasn’t communicating with the UI that it was happening.

The result? The app would freeze while syncing. Then crash when users tried to do anything else.

This is a foundational problem. Not a bug. A design oversight. And it required rethinking how the entire cloud-sync system works.

That’s not fixed in a quick build. That’s fixed in the next major revision: the one I’m working on now, scheduled for next week.

Why this mattered more than I expected

I wrote the post-TestFlight email to my testers laying out exactly what we found, exactly what we’re fixing. It’s detailed. 27 separate items across stability fixes, functional improvements, experience enhancements, and new features.

When I look at that list, I feel two things simultaneously:
(1) genuine gratitude that TestFlight caught these problems before actual users did, and …
(2) the uncomfortable knowledge that I shipped something to real people that wasn’t ready.

But this thing hit harder than the crashes themselves: I wasn’t expecting problems in the first place.

Not intellectually. Obviously, you expect problems when you’re building in public and testing. That’s the point of TestFlight.

But emotionally? I thought I knew what I was doing. My experience did translate — to the architectural thinking, the debugging methodology, the understanding that stability matters. But it didn’t translate to the specifics of how iOS manages background tasks, memory pressure, and network state. That requires learning deeply iOS, not just applying general software engineering. I thought the hard parts would be the things I expected them to be, not the foundational infrastructure that I’d glossed over.

The humility reboot

Every developer who’s shipped something meaningful knows this feeling: the moment your assumptions collide with reality. It’s not special. It’s not even novel. Thousands of indie developers ship broken first versions to TestFlight every week.
What is interesting is that I didn’t see it coming, even though I should have.

I think it’s because there’s a category error in how we talk about indie app development. The content I read before shipping was almost entirely about growth metrics, monetization strategy, App Store Optimization, and how to build profitable businesses. Very little about the actual problem-solving journey. Very little about the moment when your code meets real devices, real networks, real edge cases, and fails spectacularly.

Everyone talks about MRR and unit economics and customer acquisition cost. Almost nobody talks about the humbling moment when you realize your search implementation is leaking memory, or your cloud-sync strategy is fundamentally broken, or your assumptions about how iOS handles background tasks were incomplete.

So I wasn’t prepared for the specific ways iOS exposes stability problems: background task lifecycle, memory pressure, network interruption, concurrent file access. I knew stability mattered. I didn’t anticipate how differently it manifests.

What I know now (that I didn’t know last week)

Confidence and competence are not the same thing.

I’ve built complex systems. I understand databases, performance optimization, distributed systems. But iOS development operates by different rules. Memory management is different. Concurrency is different. The operating system’s lifecycle management is different. And my 15 years of experience didn’t automagically transfer to these domains.
The apps that freeze on 50% of devices aren’t built by incompetent people. They’re built by people who didn’t anticipate the specific, non-obvious ways that iOS handles background tasks, network requests, and memory pressure.

Testing on the simulator is not the same as testing on real devices.

I tested extensively. On the simulator. On my own devices. But real users with different network speeds, device generations, cloud storage providers, and actual reading patterns found problems in 48 hours that I didn’t find in months.
The testers weren’t doing anything wrong. They were using the app the way it’s supposed to be used. And that’s exactly when the problems appeared.

The gap between “it works for me” and “it works” is massive.

This is obvious when you say it out loud. But it was a genuine surprise living through it. My devices are development machines. They have good connectivity, fresh iOS versions, ample memory. Real users have older iPhones running older iOS versions on spotty WiFi networks while the app is trying to download a 500MB library from cloud storage.
The problem wasn’t the code. The problem was that the code had never met these conditions before.

Freezes and crashes are not small bugs. They’re design problems.

I initially approached the crashes as debugging exercises. Find the null pointer. Find the memory leak. Find the race condition. But the core issue was architectural: my app’s approach to cloud sync didn’t account for the reality that syncing might take a long time, might fail, might be interrupted, and the UI should probably tell the user what’s happening instead of just freezing.

That’s not a bug fix. That’s a redesign.

The week ahead

I’m rebuilding the cloud-sync system from the ground. I’m adding proper error handling, user notifications, timeout mechanisms, and background task management. I’m making sure the app doesn’t try to open files that haven’t finished downloading. I’m creating feedback loops so users know what’s happening instead of wondering why their app is frozen.

The new build goes to TestFlight next week.

And I have to admit that I’m nervous about it. Not because I think there will still be crashes (I’m 100% confident there won’t be, and yes, I know what that overconfidence sounds like now). But because I’ve learned that my confidence is not a reliable predictor of reality.

The 84 people who stuck with the app deserve a product that works. The 10–15 who gave detailed feedback deserve to know that their investment of time was the thing that made the difference between shipping something broken and shipping something real.

The thing nobody writes about

This is why I’m writing this. Not to tell you that my app is great (it’s not, yet). Not to tell you about my growth metrics or my monetization strategy (I have neither, we’re literally in TestFlight week one). And not to tell you that building an indie app is easy if you follow these ten steps.

I’m writing this because the indie dev content I read before shipping was almost entirely about the business side, the metrics, the strategy and the market opportunity. Almost none of it was about the moment when you realize that iOS stability requires entirely different thinking than backend systems. That managing cloud sync while the OS kills background tasks while the user is on spotty WiFi requires architectural decisions, not just debugging. Stability as a principle? Everyone knows that. Stability as iOS execution? That’s what nobody talks about.

Almost none of it was about the feeling of shipping something to real people and having it fail for half of them, even though you thought you knew what you were doing.

Almost none of it was about the humility that comes from learning, in real time, why your confidence was misplaced.

And maybe that’s because those stories are harder to write. They require admitting that despite 15 years of experience, despite months of development, despite testing that felt comprehensive, you still got something fundamentally wrong.

But they’re also the stories that matter most, because they’re the ones that prepare you for what actually happens when you ship.

What comes next

For justRead: a rebuilt cloud-sync system, more thorough testing with real devices, and a deep respect for what I still have to learn about iOS development.

For this journey: continued transparency about what works and what doesn’t. Continued gratitude for the 84 testers who are willing to help us figure this out. And continued proof that the hard part of building an app isn’t the idea or the design, it’s the relentless, humbling work of making it actually work.

The next TestFlight build will be better. And I’ll be more honest about what “better” actually means: not that we fixed everything, but that we learned something.

That’s progress, even if it doesn’t feel like it when your app is freezing in front of real people.
justRead is an EPUB reader for iPhone, currently in TestFlight. If you’re interested in early access or want to share your own story of shipped-too-early products, I’d love to hear from you. The next build ships next week.

Peter
Reader, Developer, justRead Creator

Preserving Scroll Position and Cursor State During Navigation Transitions

Sun, 25 Jan 2026 16:57:20 +0000

Have you ever noticed the difference between a simply good app and one that feels "native," polished, and premium? Often it's not about design or animations, but about small details we take for granted until they break. One such critical detail is an app's ability to remember where you left off. You're reading a long article, minimize the app to respond to a message, come back a minute later, and boom - you're thrown back to the very beginning of the text. Annoying, right? Or you're writing a note, switch to the browser, come back, and the keyboard is hidden with the cursor lost. In this article, we'll break down how to technically implement scroll position and cursor state preservation in iOS apps properly. We'll go beyond banal advice and examine real scenarios with navigation, tabs, and asynchronous data loading, so your users never feel lost.

Why Losing Context Hurts

Let's be honest: users don't know terms like "controller lifecycle" or "memory unloading." But they can absolutely feel when an app behaves stupidly. Losing scroll position or cursor during navigation is exactly that kind of stupid behavior. It destroys the interaction flow.

Imagine you're working in a code editor on an iPad. You scroll a file to line 500, place the cursor in the middle of a complex function, then open the side menu to check the project structure. You close the menu - and bam! - you're back at line one. At this moment, the app transforms from a professional tool into a toy.

Another classic example is news feeds or product catalogs. The user has scrolled down through a hundred items, drilled into a product detail screen, tapped Back, and their list reloaded, throwing them back to the top. This isn't just inconvenient, it's wasting the user's time. In a world with cutthroat competition for attention, such UX mistakes are unforgivable. An app that doesn't remember my state feels like a cheap web wrapper, even if it's written in pure Swift.

The Foundation: State Restoration in iOS

Apple has long provided us with a powerful mechanism to solve these problems - UI State Restoration. But in my observations, many developers ignore it, preferring to reinvent the wheel by saving data in UserDefaults or singletons. I was guilty of this myself for a long time, until I understood how the system works under the hood.

The built-in mechanism is good because it's systemic. It triggers not only when you push a controller onto the navigation stack, but also when the system kills your app in the background due to memory pressure, and then the user relaunches it.

The cornerstone of the entire mechanism is the restorationIdentifier property.

// In viewDidLoad
self.restorationIdentifier = "MyDetailViewController"

If a controller (or any UIView) doesn't have this identifier set, the system won't even attempt to save its state. This is your entry ticket. Once the identifier is set, two methods from the UIStateRestoring protocol come into play, which every UIViewController already has:

override func encodeRestorableState(with coder: NSCoder) {
    super.encodeRestorableState(with: coder)
    // Here we encode what we want to save
    coder.encode(someImportantData, forKey: "dataKey")
}

override func decodeRestorableState(with coder: NSCoder) {
    super.decodeRestorableState(with: coder)
    // And here we retrieve it back
    if let data = coder.decodeObject(forKey: "dataKey") as? DataToRestore {
        self.someImportantData = data
    }
}

Sounds simple, but the devil is in the implementation details. State Restoration doesn't save your model data (that's what Core Data or files are for). It saves interface state, which helps display that data exactly as it was before the user left.

Saving Scroll Position (ScrollView Offset)

The most common case is UITableView or UICollectionView. When the user leaves the screen (for example, pushes the next controller), we want to remember the contentOffset.

Many try to save the offset in viewWillDisappear. This is a working strategy for simple transitions within the navigation stack, when the controller stays in memory. But if we're talking about full-fledged State Restoration (with app termination), it's better to use specialized methods.

Let's say we have a UITableViewController. Fortunately, UITableView and UICollectionView already know how to save a lot themselves, if they (and their cells!) have restorationIdentifier set. But sometimes we need more control, especially if the scroll view is complex.

I prefer an explicit approach. Let's create a structure to store our screen's state:

struct ListViewState: Codable {
    let contentOffsetY: CGFloat
    // Can add selected cell ID, etc.
}

Now in the controller:

class MyListViewController: UIViewController, UITableViewDelegate {
    
    @IBOutlet weak var tableView: UITableView!
    private let stateKey = "ListViewControllerState"

    override func viewDidLoad() {
        super.viewDidLoad()
        // Critical for the mechanism to work
        self.restorationIdentifier = "MyListVC"
    }

    // MARK: - State Restoration

    override func encodeRestorableState(with coder: NSCoder) {
        super.encodeRestorableState(with: coder)
        
        // Save current offset
        let state = ListViewState(contentOffsetY: tableView.contentOffset.y)
        do {
            let data = try JSONEncoder().encode(state)
            coder.encode(data, forKey: stateKey)
        } catch {
            print("Failed to encode state: \(error)")
        }
    }

    override func decodeRestorableState(with coder: NSCoder) {
        super.decodeRestorableState(with: coder)
        
        guard let data = coder.decodeObject(forKey: stateKey) as? Data,
              let state = try? JSONDecoder().decode(ListViewState.self, from: data) else {
            return
        }
        
        // HERE'S THE MAIN GOTCHA
        // You can't just set contentOffset right now.
        // The table data might not be loaded yet.
        self.restoreScrollPosition(to: state.contentOffsetY)
    }
    
    private var pendingScrollOffset: CGFloat?

    private func restoreScrollPosition(to offset: CGFloat) {
        // Save the offset "for later"
        self.pendingScrollOffset = offset
    }
    
    // Call this method when data is definitely loaded and table has redrawn
    func dataDidFinishLoading() {
        tableView.reloadData()
        
        if let offset = pendingScrollOffset {
            // Sometimes need to give the Layout engine time to work
            DispatchQueue.main.async {
                self.tableView.setContentOffset(CGPoint(x: 0, y: offset), animated: false)
                self.pendingScrollOffset = nil
            }
        }
    }
}

Notice the pendingScrollOffset. This is a key moment when working with async data. If you try to restore contentOffset in decodeRestorableState when your table has 0 rows, the scroll will simply reset to 0. You must apply the saved offset only after the data is received and reloadData() has executed.

Hunting for the Cursor in UITextView

With text editors, things get even more interesting. Here we need to save not only scroll, but also cursor position (or text selection). This is handled by the selectedRange property of UITextView.

The problem is that cursor position is inextricably linked to keyboard focus. If during state restoration we simply set selectedRange but don't make the text field active (becomeFirstResponder), the user will see the text, possibly even scrolled to the right place, but without the cursor and keyboard. They'll have to tap again. This isn't the "seamless" experience we're aiming for.

Here's how I typically approach solving this in an editor controller:

class EditorViewController: UIViewController {
    
    @IBOutlet weak var textView: UITextView!
    private let selectionKey = "EditorSelectionRange"
    private let textKey = "EditorTextContent" // If text isn't saved in model

    override func viewDidLoad() {
        super.viewDidLoad()
        self.restorationIdentifier = "EditorVC"
        // Important: the textView itself also needs an ID if we want
        // the system to help us with scroll
        self.textView.restorationIdentifier = "EditorTextView"
    }
    
    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        // If we restored state and should show keyboard
        if shouldRestoreFocus {
            textView.becomeFirstResponder()
            shouldRestoreFocus = false
        }
    }

    // MARK: - State Restoration

    override func encodeRestorableState(with coder: NSCoder) {
        super.encodeRestorableState(with: coder)
        
        // Save range. NSRange encodes perfectly.
        let range = textView.selectedRange
        if range.location != NSNotFound {
             coder.encode(NSValue(range: range), forKey: selectionKey)
        }
        
        // Save whether this field had focus
        coder.encode(textView.isFirstResponder, forKey: "wasFirstResponder")
    }

    private var shouldRestoreFocus = false

    override func decodeRestorableState(with coder: NSCoder) {
        super.decodeRestorableState(with: coder)
        
        // Restore text (if needed)
        // textView.text = ...

        // Restore range
        if let value = coder.decodeObject(forKey: selectionKey) as? NSValue {
            let range = value.rangeValue
            // Critical moment: need to ensure range is valid for current text
            if range.upperBound <= textView.text.count {
                textView.selectedRange = range
                
                // Often need to force scroll to cursor,
                // as automatic scroll might not work during restoration
                textView.scrollRangeToVisible(range)
            }
        }
        
        // Remember if we need to restore focus
        shouldRestoreFocus = coder.decodeBool(forKey: "wasFirstResponder")
    }
}

I deliberately moved becomeFirstResponder() to viewDidAppear. Calling it in decodeRestorableState or viewDidLoad is often premature, since the view hierarchy isn't fully ready yet, and the system might ignore the keyboard request. Plus, keyboard appearance changes the UITextView insets, which can affect scroll. By doing this in viewDidAppear, we let the interface "settle."

Tabs, Modals, and App Backgrounding: A Unified Strategy

Developers often implement different mechanisms for different navigation types. For UINavigationController they use viewWillDisappear to save offset. For tab bar - UITabBarControllerDelegate methods. For app backgrounding - they subscribe to UIApplication.didEnterBackgroundNotification notifications.

This is a path to code duplication and bugs. I'm a proponent of a unified strategy.

The State Restoration mechanism described above (encodeRestorableState/decodeRestorableState) works perfectly for the "kill and resurrect" app scenario.

But what about simple navigation within a live app? Switching tabs or push/pop controllers. Here State Restoration in its pure form doesn't quite fit, since it's about "cold restart."

For "hot" navigation I prefer using lifecycle methods viewWillDisappear and viewWillAppear as the most reliable triggers.

Leaving the screen (viewWillDisappear): This is the perfect place to save current "ephemeral" state (scroll, focus) to a local controller variable or associated ViewModel. Doesn't matter why the screen is disappearing - new one being pushed, tab switching, or modal presenting. This method will be called.
Returning to screen (viewWillAppear / viewDidAppear): Here we check if there's saved state and apply it.

Example for "hot" saving in a list:

class HotListViewController: UIViewController {
    @IBOutlet weak var tableView: UITableView!
    
    // Store offset right in controller for quick transitions
    private var lastScrollOffset: CGPoint?

    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        // Leaving? Remember where we were.
        lastScrollOffset = tableView.contentOffset
    }
    
    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
        
        // Returned? If there's something to restore, and data hasn't changed critically.
        if let offset = lastScrollOffset {
            // Important: check table isn't empty, otherwise crash or glitch
            if tableView.contentSize.height > offset.y {
                 tableView.setContentOffset(offset, animated: false)
            }
        }
    }
}

This approach works great when switching tabs in UITabBarController. Controllers in tabs usually aren't unloaded from memory, so the local lastScrollOffset variable will hold the value indefinitely, as long as the app session is alive.

If you're using custom navigation where controllers are recreated, you'll need to save this "hot" state somewhere external - for example, in a navigation service or global state storage tied to screen ID.

Testing: Breaking What We Built

The biggest mistake when implementing these features is improper testing. Simply minimizing the app with the Home button and reopening it is not a State Restoration test. In this case, the app simply "sleeps" in RAM, and when awakened, all views and controllers remain in place untouched. No decodeRestorableState is called.

To test for real, you need to simulate system actions:

Simulating memory pressure: In iOS Simulator, select Debug -> Simulate Memory Warning from the menu. If your controller is deep in the navigation stack or in an inactive tab, and it's "heavy," the system might unload it (call didReceiveMemoryWarning, and then possibly free its view). When returning to it, the restoration mechanism should trigger.
App termination in background: This is the main test.
- Launch the app from Xcode.
- Minimize it (go to Home Screen).
- In Xcode, press the "Stop" button (square). This kills the process, but as if the system did it in the background (saving state), not like a crash.
- Launch the app again from the icon on simulator/device (not the Run button in Xcode, otherwise the saved state will be wiped).
- If you did everything right, the app should launch not from scratch, but restore the controller hierarchy and their state, including scroll and cursors.

Common Pitfalls: Asynchronicity Is My Enemy

I've touched on this before, but I'll repeat it, as this is the most frequent cause of bugs.

The Problem: You saved contentOffset.y = 2000. When the app launches, decodeRestorableState fires, and you dutifully try to do tableView.setContentOffset(CGPoint(0, 2000)). But at this moment, your ViewModel has just started an asynchronous network request for data. The table is empty. Its contentSize is zero. Setting the offset is either ignored or gets reset to zero at the first data reload.

The Solution: Never restore scroll position (or text cursor) until the content is ready.

In decodeRestorableState, only decode the parameters and save them to temporary properties of the controller.
Wait for the data loading to complete.
Call reloadData().
Only after this (sometimes it's useful to wrap in DispatchQueue.main.async to let the layout cycle pass) apply the saved parameters.

If you're using reactive frameworks like RxSwift or Combine, this is convenient to do in a subscription to data updates, right after new data has been passed to the diffable data source or table reload has been called.

Careful attention to state preservation is what distinguishes a mature product from an MVP. It's care for the user that they may not consciously notice, but will definitely feel its absence if you decide to cut corners on this.

SwiftUI vs UIKit in 2026: When to Use What

Sat, 24 Jan 2026 16:38:16 +0000

The Myth That SwiftUI Will Replace UIKit

Let's get this straight right away: if someone tells you SwiftUI is the future and UIKit is legacy, don't believe them. Apple itself continues writing critical parts of its apps in UIKit. Open Settings on your iPhone - that's UIKit. Music? UIKit with sprinkles of SwiftUI. Photos? Same story.

Why is this happening? Because SwiftUI, despite all its advantages, can't handle certain tasks as efficiently as UIKit. I've seen projects where teams tried to write everything in SwiftUI "because it's trendy," then spent three months fighting navigation bugs and ended up rewriting in UIKit.

Over the past few years, SwiftUI has grown significantly. The Navigation API got better with NavigationStack and NavigationSplitView. We got proper scroll position tracking support. But the fundamental limitations haven't gone anywhere. When you need pixel-perfect control over layout or complex animation with precise synchronization between elements, SwiftUI starts struggling.

The truth is that in 2026, both frameworks have a right to exist. The question isn't what to choose, but when to use what. And most importantly - do you even need to pick just one?

Where SwiftUI Really Wins

SwiftUI shines when you need to quickly assemble UI from standard components. Declarative syntax isn't just pretty marketing words from Apple, it actually works.

Compare:

// UIKit
let label = UILabel()
label.text = "Hello"
label.textColor = .systemBlue
label.font = .systemFont(ofSize: 16, weight: .bold)
view.addSubview(label)
label.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
    label.centerXAnchor.constraint(equalTo: view.centerXAnchor),
    label.centerYAnchor.constraint(equalTo: view.centerYAnchor)
])
// SwiftUI
Text("Hello")
    .font(.system(size: 16, weight: .bold))
    .foregroundColor(.blue)

The difference is obvious. But it's not just about lines of code.

Live previews in SwiftUI - that's what made me actually fall in love with this framework. When you're writing a registration form and see changes in real-time without rebuilding the project, that saves hours. In UIKit you either launch the simulator every time or struggle with Interface Builder, which periodically breaks storyboards.

Yes, previews crash sometimes. Yes, after an Xcode update they might stop working for a couple days. But when everything works - it's incredibly convenient. You can set up multiple preview configurations with different data, screen sizes, dark/light mode simultaneously. Try doing the same in UIKit - you'll have to either write a playground or create separate view controllers for each case.

Cross-platform development - another SwiftUI ace. The same code works on iOS, macOS, watchOS, and - importantly in 2026 - visionOS. Apple is clearly betting on Vision Pro, and if you want to port your app there without a complete rewrite, SwiftUI gives you a head start.

Real-world example: I made a habit tracking app. The main screen was a list with checkboxes and statistics. Wrote the entire UI in SwiftUI in one day. Then the client asked for a macOS version. Added a couple #if os(macOS) checks to adapt the menu, and done. If this were UIKit, I'd have to write the entire macOS interface from scratch using AppKit.

Here's another point many people miss: state management in SwiftUI is built into the framework. @State, @Binding, @ObservableObject - these aren't just property wrappers, they're a whole philosophy of data management. In UIKit you have to build architecture yourself: MVVM, VIPER, Coordinator pattern. In SwiftUI basic cases work out of the box.

struct CounterView: View {
    @State private var count = 0
    
    var body: some View {
        VStack {
            Text("Count: \(count)")
            Button("Increment") {
                count += 1
            }
        }
    }
}

This code just works. No delegates, target-action, KVO, or notification center. Pressed button - state updated - UI redrawn. In UIKit the same task requires more code and explicit update management.

Personally, I use SwiftUI for:

App settings (forms with toggles, sliders)
Onboarding (five screens with animations between them)
Simple forms (registration, login)
Prototypes that need to be shown to clients in a couple days
Dashboards with charts and statistics
Any new features in existing apps where there are no strict performance requirements

When UIKit Is Still Irreplaceable

UIKit is older, which means more stable. There are no unexpected surprises that SwiftUI loves to deliver in every Xcode release.

Take gestures. SwiftUI has .gesture(), but try doing something more complex than a simple tap - for example, simultaneous pan and pinch recognition with different priorities. In UIKit it's UIPanGestureRecognizer + UIPinchGestureRecognizer with delegates, everything's clear and works predictably. In SwiftUI you'll have to build workarounds through UIViewRepresentable.

I had a project with a custom image editor. Users could zoom photos, rotate them, apply filters in real-time. On SwiftUI this turned into a nightmare. Gesture modifiers conflicted with each other, priorities didn't always trigger correctly. Rewrote it in UIKit in two days, and everything worked like clockwork.

Libraries. Almost the entire powerful iOS ecosystem is written for UIKit. Want to integrate a cool charting library like Charts (not Apple Charts, but third-party)? Most likely it's UIKit. Yes, you can wrap it through representable, but that's an additional layer of abstraction and potential lifecycle problems.

Performance control. In UIKit you know exactly when layout happens, when a view renders, you can optimize layoutSubviews, use drawRect for custom drawing. In SwiftUI the framework decides when to redraw something, and sometimes does it too often.

I encountered a situation where a complex SwiftUI view was redrawing 60 times per second for no visible reason. Profiling showed the problem was implicit state changes - somewhere deep in the hierarchy a @State was updating, and the entire subtree was redrawing. Debugging that was quite the quest. In UIKit this doesn't happen: if a view updates, someone explicitly called setNeedsDisplay or setNeedsLayout.

Another point: memory management. In SwiftUI it's very easy to catch a retain cycle through capturing self in closures. All those @StateObject and @ObservedObject add magic that sometimes doesn't work as you expect. In UIKit everything's explicit: there's weak, unowned, and you know exactly who's holding whom.

Collection views with custom layout. UICollectionView with custom UICollectionViewLayout is an incredibly powerful tool. You can do Pinterest-style masonry grids, circular layouts, complex transition animations between cells. SwiftUI has LazyVGrid and LazyHGrid, but they only cover basic cases. As soon as you need something non-standard - back to UIKit.

Accessibility. Strangely enough, in UIKit the accessibility API is more mature and predictable. In SwiftUI modifiers like .accessibilityLabel() work, but when you start doing something more complex - custom rotor actions, adjustable traits, grouped elements - UIKit gives more control.

I choose UIKit for:

Custom controls with non-standard behavior (slider with non-uniform scale, circular progress with animations)
Apps where every millisecond matters (video editors, games)
Projects with minimum iOS 13-14 (SwiftUI there is too raw)
Complex animations with CALayer and Core Animation
Working with large tables (thousands of rows with good performance)
Integration with complex third-party SDKs

Hybrid Approach: Best of Both Worlds

The most reasonable solution - combine them. Apple itself does this, why shouldn't we? A hybrid approach lets you use SwiftUI where it's convenient and UIKit where it's necessary.

UIKit in SwiftUI via UIViewRepresentable

Say you need a rich text editor in a SwiftUI app. The standard TextEditor is too simple - no formatting, can't change fonts or colors. Ready-made SwiftUI solutions either don't exist or cost money. Take the proven UITextView and wrap it:

struct RichTextEditor: UIViewRepresentable {
    @Binding var text: NSAttributedString
    var placeholder: String
    
    func makeUIView(context: Context) -> UITextView {
        let textView = UITextView()
        textView.delegate = context.coordinator
        textView.font = .systemFont(ofSize: 16)
        textView.backgroundColor = .clear
        textView.textContainerInset = UIEdgeInsets(top: 8, left: 8, bottom: 8, right: 8)
        return textView
    }
    
    func updateUIView(_ uiView: UITextView, context: Context) {
        // Important: only update if text actually changed
        if uiView.attributedText != text {
            let selectedRange = uiView.selectedRange
            uiView.attributedText = text
            // Preserve cursor position
            uiView.selectedRange = selectedRange
        }
    }
    
    func makeCoordinator() -> Coordinator {
        Coordinator(self)
    }
    
    class Coordinator: NSObject, UITextViewDelegate {
        var parent: RichTextEditor
        
        init(_ parent: RichTextEditor) {
            self.parent = parent
        }
        
        func textViewDidChange(_ textView: UITextView) {
            // Update binding only when text changes
            parent.text = textView.attributedText
        }
        
        func textViewDidBeginEditing(_ textView: UITextView) {
            if textView.text == parent.placeholder {
                textView.text = ""
            }
        }
    }
}

It works. But there are nuances. The most important - state synchronization between SwiftUI and UIKit can be painful. Make sure not to create unnecessary updates in updateUIView, otherwise you'll get an infinite redraw loop or lose focus in text fields.

Another example - custom map view with annotations. MKMapView from MapKit works great, but natively it's a UIKit component. Wrap it:

struct MapView: UIViewRepresentable {
    @Binding var region: MKCoordinateRegion
    var annotations: [MKPointAnnotation]
    
    func makeUIView(context: Context) -> MKMapView {
        let mapView = MKMapView()
        mapView.delegate = context.coordinator
        return mapView
    }
    
    func updateUIView(_ mapView: MKMapView, context: Context) {
        mapView.setRegion(region, animated: true)
        
        // Update annotations only if changed
        if mapView.annotations.count != annotations.count {
            mapView.removeAnnotations(mapView.annotations)
            mapView.addAnnotations(annotations)
        }
    }
    
    func makeCoordinator() -> Coordinator {
        Coordinator(self)
    }
    
    class Coordinator: NSObject, MKMapViewDelegate {
        var parent: MapView
        
        init(_ parent: MapView) {
            self.parent = parent
        }
        
        func mapView(_ mapView: MKMapView, regionDidChangeAnimated animated: Bool) {
            parent.region = mapView.region
        }
    }
}

SwiftUI in UIKit via UIHostingController

Reverse task: you have a large UIKit app, but a new settings screen is easier to write in SwiftUI. Or you need to add a beautiful dashboard with charts, and doing it in UIKit is pure hell.

class MainViewController: UIViewController {
    
    func showSettings() {
        let settingsView = SettingsView(onDismiss: { [weak self] in
            self?.dismiss(animated: true)
        })
        
        let hostingController = UIHostingController(rootView: settingsView)
        hostingController.modalPresentationStyle = .formSheet
        
        present(hostingController, animated: true)
    }
}

struct SettingsView: View {
    @AppStorage("notifications") private var notifications = true
    @AppStorage("darkMode") private var darkMode = false
    var onDismiss: () -> Void
    
    var body: some View {
        NavigationView {
            Form {
                Section("Preferences") {
                    Toggle("Enable Notifications", isOn: $notifications)
                    Toggle("Dark Mode", isOn: $darkMode)
                }
            }
            .navigationTitle("Settings")
            .toolbar {
                Button("Done", action: onDismiss)
            }
        }
    }
}

This is simpler than UIViewRepresentable. Main thing - properly handle lifecycle to avoid memory leaks. SwiftUI view inside hosting controller holds strong references to all its @ObservedObject and @StateObject, so be careful with closures.

Another important point: sizing. UIHostingController doesn't always correctly determine its size. If adding a SwiftUI view as a child view controller, explicitly set frame or constraints:

let hostingController = UIHostingController(rootView: mySwiftUIView)
addChild(hostingController)
view.addSubview(hostingController.view)

hostingController.view.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
    hostingController.view.topAnchor.constraint(equalTo: view.topAnchor),
    hostingController.view.leadingAnchor.constraint(equalTo: view.leadingAnchor),
    hostingController.view.trailingAnchor.constraint(equalTo: view.trailingAnchor),
    hostingController.view.heightAnchor.constraint(equalToConstant: 300)
])

hostingController.didMove(toParent: self)

I use a hybrid approach in most projects. The main architecture can be UIKit, but individual screens - SwiftUI. Or vice versa: SwiftUI base, but custom controls through UIViewRepresentable. Main thing - don't obsess over one technology and choose the right tool for the job.

Performance: Numbers, Not Myths

I ran tests on iPhone 15 Pro, iPhone 12 mini, and iPhone SE 2020. Here's what I got.

Startup time:

SwiftUI app (clean project): ~180ms
UIKit app (clean project): ~140ms

SwiftUI is slightly slower on startup due to additional runtime and framework initialization. On new devices the difference is imperceptible, on old ones - you feel it. If your app needs to launch instantly (camera, calculator), every millisecond matters.

Memory footprint: When displaying a list of 1000 elements with images:

SwiftUI List: ~45MB
UIKit UITableView: ~38MB

Again SwiftUI loses, but not critically. The 7MB difference for modern devices with 6-8GB RAM is insignificant. But if you're making an app for emerging markets where users are on old iPhones, those megabytes can become a problem.

Scroll performance: Here it gets more interesting. Complex list with images, text, and buttons:

SwiftUI on iPhone 15 Pro: stable 60 FPS (120 on ProMotion)
SwiftUI on iPhone 12 mini: drops to 45-50 FPS during fast scrolling
SwiftUI on iPhone SE 2020: drops to 40 FPS
UIKit on all devices: stable 60 FPS

SwiftUI works better on new hardware, but if your audience is on old iPhones, UIKit gives more predictable results. The difference is especially noticeable when cells have asynchronous image loading or complex calculations.

Navigation stacks: Deep navigation (7-8 screens) in SwiftUI sometimes glitches - screens don't dismiss correctly, especially with custom transitions or when combining sheets, fullScreenCover, and NavigationStack. In UIKit navigation controller works like a Swiss watch for 15 years already.

Animations: Simple animations (fade, scale, rotation) in SwiftUI are written in seconds and work smoothly:

@State private var isAnimating = false

Circle()
    .scaleEffect(isAnimating ? 1.5 : 1.0)
    .animation(.spring(response: 0.5), value: isAnimating)

Beautiful, simple, works. But try making a complex sequence of animations with dependencies - for example, element A moves, then element B fades in, then both rotate. In SwiftUI you'll have to use withAnimation, DispatchQueue.asyncAfter and pray the timings align.

In UIKit through UIView.animate or CAAnimation you have full control. You can set exact curves, completion handlers, group animations. For simple cases SwiftUI is more convenient, for complex ones - UIKit is more reliable.

Concrete case: Instagram-like feed Made a test: feed with posts (image, author name, likes, comments). 500 posts, scroll through the entire list.

SwiftUI version:

Memory: 65MB
Frame drops: 15-20% on iPhone 12
Code: ~150 lines

UIKit version:

Memory: 52MB
Frame drops: 2-3% on iPhone 12
Code: ~300 lines

UIKit wins on performance but requires twice as much code. What to choose? Depends on priorities. If development speed matters more than the last few percent of performance - SwiftUI. If the app needs to fly even on old hardware - UIKit.

Decision-Making Checklist

Here's how I make decisions for each new feature or project:

Use SwiftUI if:

Minimum iOS version of the project is 15+ (better 16+)
Need a quick prototype or MVP
UI consists of standard components (buttons, text, lists, forms)
Planning to support visionOS, macOS, or watchOS
Team is ready to deal with bugs and unstable API
Performance on old devices isn't critical
No dependency on complex UIKit libraries
Project is new or you can isolate the feature into a separate module

Use UIKit if:

Need to support iOS 13-14 (or even older)
Performance on old devices is critical
Complex custom gestures or animations required
Strong dependency on third-party UIKit libraries
No time for experiments with unstable API
Need pixel-perfect control over layout
Working with large data volumes (thousands of elements)
App needs to be maximally stable (fintech, medicine)

Use hybrid approach if:

Migrating from UIKit to SwiftUI gradually
Have legacy code that works and you're scared to touch it
Different screens have different requirements
Want new features in SwiftUI but base in UIKit
Need custom UIKit components in SwiftUI app
Team knows both frameworks

Red flags for SwiftUI:

Client requires iOS 13 support
App lags even on new devices
Xcode previews haven't worked for a week
Spending more time fighting the framework than on features
Need to integrate 10+ UIKit libraries

Red flags for UIKit:

Writing 500 lines of code for a simple form
Spending an hour on layout constraints for one screen
Junior developer can't figure out storyboards
Every UI change requires full rebuild

Conclusion: It's About Trade-offs, Not Trends

I manage several projects simultaneously. In one - pure SwiftUI, because it's an internal team tool with minimal performance requirements. In another - UIKit with small SwiftUI inclusions for simple screens like settings or onboarding. In the third - pure UIKit, because the client requires iOS 14 support and performance on old devices is critical.

Choosing a framework is about context, not hype. SwiftUI is a great tool for certain tasks. But it's not a silver bullet. UIKit isn't going anywhere for a very long time, and that's okay.

If SwiftUI solves your problem faster and more reliably - use it. If not - don't hesitate to write in UIKit. If you need both - combine them. Your job is to deliver a product that works, not follow trends from conferences.

Final advice: learn both frameworks. Even if you're a SwiftUI fanatic, knowing UIKit will make you a better developer. And vice versa. Understanding how UIKit works under the hood helps write more efficient SwiftUI code. And knowing SwiftUI patterns can improve your UIKit architecture.

In 2026, the best iOS developer isn't the one who only knows SwiftUI or only UIKit. It's the one who knows both and can choose the right tool for the specific task.

Coder Legion - Recent posts tagged ios

How to give your AI Agent access to a Real iPhone

Why iPhone automation is difficult

From a prompt to a real iPhone

What can you automate?

1. Messaging workflows

2. Navigating apps

3. Repetitive mobile tasks

Why use a real iPhone instead of a simulator?

Try it yourself

MarcX Studio

Apps

Building a Low-Latency Virtual Piano and Drum Kit on iOS with AVAudioEngine

1. The three things a virtual instrument must get right

2. Session setup for an instrument

3. Pitched instruments: AVAudioUnitSampler

4. Drums: preloaded buffers and a player-node pool

5. A multi-touch keyboard that feels like a keyboard

6. Teaching note names and positions

7. Real-world example: Drums n Piano

8. Before you ship a virtual instrument: a checklist

Wrapping up

Building a Real-Time Mic-to-Speaker App on iOS with AVAudioEngine

1. The problem: what "mic to speaker" really needs

2. Microphone permission, the modern way

3. Configuring AVAudioSession

Category and options

Mode

Buffer duration and sample rate

Echo-cancelled input (iOS 18.2+)

Temporary speaker override

Putting it together

4. The AVAudioEngine graph

Format matching

The complete class

5. Taming feedback and latency

Headphones vs. speaker

Voice processing

Buffer size trade-offs

6. Interruptions and route changes

Interruptions

Route changes

Media services reset

Putting it together

7. Background audio and App Store notes

Background audio

App Store review considerations

8. Real-world example: Virtual Mic, a.k.a. Mic to Speaker

Android sidebar: Virtual Mic on Google Play

9. Before you ship live audio: a 7-point checklist

Wrapping up

Tap-to-Match Marble Game in SpriteKit and SwiftUI: Physics, Cluster Matching, Lives and Power-Ups

1. Why SpriteKit, and how it fits with SwiftUI

2. A playfield of marbles that settle under physics

3. Tap-to-match: finding the touching cluster

4. Popping with juice

5. A countdown that survives pausing

6. Lives and levels

7. Power-ups: Lightning, Heart and Bomb

8. Real-world example: Marbles Popperz

9. Before you ship a casual game: a checklist

Wrapping up

AdMob Earnings Dashboard for iOS: OAuth with PKCE, AdMob Reporting API and Offline Caching

1. The shape of the app: no middleman

2. OAuth for a native app: system browser, PKCE, no embedded web views

3. Exchanging the code and keeping tokens safe

4. Asking AdMob for a report

5. Decoding a streamed report

6. Why "today" is a Los Angeles day

7. Pull to refresh, offline cache and the weekly view

8. Real-world example: AdEarnings Pro

9. Before you ship an OAuth-powered dashboard: a checklist

Wrapping up

Offline Quotes App in SwiftUI: 50K-Quote Library, Daily Quote, Streaks and Share-as-Image

1. Ship the library in the bundle, import it once

2. A quote of the day with no server

3. Search across content, author and category, with recent searches

4. Collections and favourites

5. Streaks that survive time zones

6. Share as a beautiful image