Reading one takes two function calls. Earning the right to make those two calls takes considerably longer. And then CoreNFC asks you to earn it a second time.

The first gauntlet is Apple's. A paid developer account, an App ID registered in a web portal, a capability ticked on it, and a provisioning profile regenerated. Get any of it wrong and the build fails with a code-signing error that never says the word "NFC".

The second is CoreNFC's own, and it's the one nobody warns you about. It's a session-based API with delegate callbacks, four nested asynchronous steps, and a set of rules that punish you quietly.

Hold the session in the wrong variable and the system sheet vanishes with no error at all. Let a successful read settle your promise twice and your result is replaced by a failure. Ask for one polling option too many and the whole session refuses to start, without naming the option.

In this handbook, you'll get through both. You'll write an NDEF decoder by hand, which sounds like overkill until you read what the popular library's one actually does to an emoji. You'll write to a tag and discover your business card doesn't fit. You'll build a focus timer you can't stop without walking to another room. You'll delete the NFC dependency entirely and replace it with a native module in Swift. And you'll permanently lock a tag, which is the one thing here that can't be undone.

Two of the things I concluded during this build turned out to be wrong, and both are still in the repository under "superseded" banners. They're in here too, because how I got them wrong is more useful than the what replaced them.

This is an iOS handbook. Everything in the main sections was built, run, and verified on a real iPhone. Android gets its own handbook, and if you can't wait for it there's a preview at the end: the Kotlin counterpart to everything here, with the architectural differences that make the two platforms worth comparing.

Everything below comes from one project, TapCard, which is on GitHub with tagged checkpoints so you can check out the app at any stage and run it.

Table of Contents

• Prerequisites

• What NFC Tags Actually Are

• Where You Have Already Seen This

• Why There Is No Simulator Path

• How the iOS Contract Works

• How to Read Your First Tag

• What an NDEF Record Actually Is

• Why I Wrote My Own Decoder

• How to Write a Tag

• Will It Fit? 137, Not 144

• A Focus Session You Can't End Without the Tag

• Why Your NFC Lock Isn't Secure

• Four Gotchas That Cost Me an Evening Each

• Why You Can't Build Tap to Pay

• Why You Might Write Your Own Native Module

• How to Prove Parity Before You Switch

• What a Config Plugin Was Doing For You

• How to Lock a Tag Forever

• How Would You Actually Ship This?

• A Sneak Peek at the Android Side

• The Demo Repository

• What to Know Before You Start

• Conclusion

• Sources and Further Reading

Prerequisites

To follow along you'll need:

• A physical iPhone, 7 or newer. Core NFC is iPhone-only. Apple's documentation lists iPhone 7 and later, and an Apple engineer on the developer forums puts it directly: "At this time, CoreNFC functionality is only available on iPhones with NFC capability." No iPad supports it.

• A paid Apple Developer account. NFC isn't available on a free provisioning profile. This isn't a soft requirement, and there's no way around it.

• NTAG213 stickers. Twenty of them cost a few pounds. Buy them before you write any code.

• Node 20+ and Xcode. Working knowledge of TypeScript throughout, and of Swift for the last third.

• Optional, for the Android preview only: Android Studio and the API 36 SDK.

The versions I used:

One line in that table is load-bearing and I'll come back to it: the NFC library is listed because it gets deleted. The finished app has no third-party NFC dependency at all.

What NFC Tags Actually Are

An NFC tag is a chip with a tiny antenna and no battery. Your phone powers it over the air, and in return it hands back a few dozen bytes. That's the whole device.

Those bytes are almost always formatted as NDEF, or NFC Data Exchange Format, which is the thing that makes a tag written by one app readable by every other. An NDEF message is a list of records, and each record has a type and a payload.

The tags in this handbook are NTAG213, the ones you'll get if you buy stickers online. They hold 144 bytes of user memory. That's not the number you can actually use, and it turns out to matter enormously.

Two things a tag is not:

1. It's not a beacon. It has no power of its own and does nothing until a phone is within a couple cm.

2. It's not secure by default. Its identifier is world-readable and copyable with cheap hardware. There's a section on this later, because the obvious use of a tag, as a key, is the one most likely to be built wrong.

Where You Have Already Seen This

NFC is in your pocket already, and it's worth separating what you can build from what you can't, because they look identical to a user.

Here are five uses cases you can go and check, each one documented by the company that ships it:

The first three are the thing this handbook builds. A chip holds a few bytes, a reader reads them, and software acts. amiibo is the most complete example of the lot, because some games write to the figure as well, which is the second half of what you're about to build.

One detail on that first row is worth pausing on, because it comes back later. Apple's own NFC automation, the one built into every iPhone, says this about the tag you scan:

"Other than the unique identifier, the contents of the NFC tag are ignored."

Apple's feature ignores everything this handbook teaches you to write, and keys on the serial number alone. There's a section later on what that does and doesn't buy you.

Let's go over two caveats about that table. The passport row is NFC but it's not NDEF: a biometric chip speaks ISO 7816 over the same radio, through NFCISO7816Tag and a different entitlement again, with its own cryptography on top. Same antenna, different world, and out of scope here. And the last row is the half you can't build, which is the rest of this section.

Beyond those five use cases, the pattern repeats everywhere a physical thing needs to say one short sentence to a phone, like museum labels that open an exhibit page, conference badges, product-authentication seals on a bottle, transit posters, restaurant table markers, and the little stickers people put on a desk to start a routine.

What you can't build on iOS is the other half: your phone pretending to be a card. Apple Pay, your bank card in Google Wallet, or a hotel key in your Apple Wallet. Those run on the Secure Element, a separate tamper-resistant chip that stores card credentials and answers terminals on its own. On iOS there's no third-party API for it at all. Not restricted: absent. There's a section later on exactly how closed that is.

So when someone says "NFC", they may mean either. This handbook is about the half you can actually write code for, and it'll explain precisely why the other half is closed.

Why There Is No Simulator Path

Don't skip this section, because it changes how you work.

NFC doesn't exist on the iOS Simulator or the Android emulator. It's not partially supported, nor is it behind a flag. The hardware isn't there and the APIs report it as unavailable. Every single thing you build is tested by holding a physical chip against a physical phone.

The consequences go beyond inconvenience. You can't write a test that proves a tag was read. You can't demo it in CI. If your phone is in another room, you're blocked. When my chips went missing in the post, the project stopped for two weeks.

The app says so permanently, because the question kept coming up:

import * as Device from 'expo-device';

// NFC hardware does not exist on the iOS Simulator or the Android emulator,
// and isSupported() is not reliable there. Bail out early and explicitly.
if (!Device.isDevice) return false;

So split your code in two.

One part talks to the NFC hardware. Start a session, read the tag, write to it, and close the session. The only way to test that part is to hold a chip against a phone.

Everything else is just data handling: turning the bytes off a tag into a URL, turning a contact into the bytes you write back, checking whether a message fits, turning a native error code into a sentence a user can read, or deciding whether a tap should start a focus session or end one.

None of that needs NFC. Most of it doesn't even need React Native. It's plain functions: values go in, values come out.

Write it that way and you can test it on your laptop, with no phone in the room. In this project, that came to about 2,240 lines of TypeScript and 293 tests that finish in about a second. The code that actually calls CoreNFC stays as small as I could make it.

This project stalled on hardware three times, including those two weeks waiting on the post. Each time there was still plenty left to build, because most of it never needed a tag. That's the best decision in the codebase, and I didn't make it deliberately. The constraint made it for me.

Checkpoint: git checkout step-0-scaffold. The app boots on both platforms and does nothing else.

How the iOS Contract Works

Three Apple terms do all the work here, and they're worth pinning down before the steps, because the error messages assume you already know them.

An App ID is the identity your app is registered under on Apple's servers, matching the bundleIdentifier in your config. An entitlement is a line in your app saying "I intend to use this capability", and NFC is one. A provisioning profile is the signed document tying the two together with your developer account, and Xcode embeds it in every build. All three have to agree, or nothing runs on a device.

With that, here's the actual sequence, and every step is important:

1. A paid Apple Developer account.

2. An explicit App ID registered at developer.apple.com, not a wildcard.

3. NFC Tag Reading ticked on that App ID.

4. A provisioning profile regenerated to include the capability.

Then, in app.json:

{
  "expo": {
    "ios": {
      "bundleIdentifier": "com.yourname.tapcard",
      "infoPlist": {
        "NFCReaderUsageDescription": "TapCard uses NFC to read and write your card to a tag."
      },
      "entitlements": {
        "com.apple.developer.nfc.readersession.formats": ["NDEF", "TAG"]
      }
    }
  }
}

Miss step 2 or 3 and the build fails with this:

Provisioning Profile "iOS Team Provisioning Profile: *" does not support
the NFC Tag Reading capability.

That error points at the wrong machine. Apple forbids special capabilities on a wildcard App ID, and Xcode silently falls back to one when there's no explicit match.

The message blames your local provisioning profile, but the missing half is on Apple's servers, in a web form you haven't filled in. Nothing in it suggests opening a browser.

A second-order trap while you're there: App IDs are globally unique across all Apple accounts, not per-team**.** My first choice was taken by a stranger, and my second was too. I renamed the app's identifier twice.

Those renames were painless, and that's worth a word on how this project is set up. Expo's Continuous Native Generation means the ios/ and android/ folders aren't kept in the repo at all. They're regenerated from app.json by expo prebuild whenever you need them, the way node_modules is regenerated from package.json. So renaming the app was two lines of JSON and one prebuild --clean, which rebuilt the iOS project, the Android package and the entire Kotlin source tree. No Xcode surgery.

For scale, the equivalent on Android is one line in a manifest, with no account, no portal, and no cost:

<uses-permission android:name="android.permission.NFC" />

That contrast isn't a complaint. It's worth internalising early, because it tells you where your time will go on this platform: not in the code, which is short, but in the paperwork around it.

How to Read Your First Tag

The reading code is short. This is all of it:

import NfcManager, { NfcTech, type TagEvent } from 'react-native-nfc-manager';

export async function readTagOnce(): Promise<TagEvent | null> {
  await NfcManager.requestTechnology(NfcTech.Ndef, {
    alertMessage: 'Hold your iPhone near the NFC tag.',
  });

  try {
    return await NfcManager.getTag();
  } finally {
    // throwOnError: false because we are already unwinding. A failure to
    // close the session must not mask the original error.
    await NfcManager.cancelTechnologyRequest({ throwOnError: false });
  }
}

There are two calls, and they're identical on both platforms. And what the user sees couldn't be more different.

On iOS, requestTechnology hands control to CoreNFC, which draws a system modal sheet. You can't restyle it. Your app isn't on screen.

On Android, nothing is drawn at all. Dispatch is silent. If your app doesn't tell the user to tap a tag, nobody does.

So the scanning UI is conditional, and this pattern recurs through the whole project:

{
  scanning && (
    <View style={styles.scanCard}>
      <ActivityIndicator />
      <Text>
        {Platform.OS === 'android'
          ? 'Hold a tag against the back of the phone.'
          : 'Waiting for the system NFC sheet…'}
      </Text>
      {/* Android draws no system UI, so the app must offer its own way out. */}
      {Platform.OS === 'android' && <Button title="Cancel" onPress={handleCancel} />}
    </View>
  );
}

That Cancel button exists only on Android, because on iOS the system sheet already has one.

Three Things That Will Catch You

1. The antenna is in different places.

On iPhone: the top edge, near the camera. On Android: the middle of the back. "Hold the tag near the phone" isn't actionable, and someone using the wrong end concludes your app is broken. I ended up drawing a small phone outline with the dot in the right place per platform.

2. The sheet doesn't show the string you think it does.

I assumed it displayed NFCReaderUsageDescription from app.json. It doesn't. It shows the alertMessage passed to each requestTechnology() call. The usage description is a privacy-manifest string: it's mandatory, no session starts without it, and it's never shown to a user.

Both strings were configured correctly and spelled properly, and my assumption about which one appeared was still wrong. I found out by holding a phone. It also means the copy can differ per scan. "Hold your iPhone near the tag to write" beats reusing the read copy.

That second line is the alertMessage from the requestTechnology call above, word for word. The usage description from app.json is nowhere on screen.

3. A blank tag reads as an error on iOS.

A factory-fresh NTAG213 is NDEF-formatted but empty, and readNDEF reports that as a failure rather than an empty message. The distinction has to come from the tag's NDEF status, not the read error. Since every tag you buy starts this way, it's the first thing you'll hit.

What Comes Back

Here's the real output from an NTAG213 on an iPhone 13 Pro:

{
  "id": "04C4FC91DF2A81",
  "tech": "mifare"
}

Two fields. That's everything iOS gives you from a read. No size, no technology list, and no NDEF type. Android returns all of them from the same chip.

I drew the wrong conclusion from this: wrote it into three documents, and planned a whole phase of work around it. That comes later, because the mistake is more useful than the fact. Skip ahead if you'd rather have the correction now.

That id is the tag's UID, a unique serial number burned into the chip at the factory and readable by anything that asks. The 04 prefix is NXP's manufacturer code, and a 7-byte UID is the NTAG21x signature, so the tag is what it claimed to be.

The Max size row is the one to look at. (unknown) is what I built the wrong conclusion on, and it is not what the platform can actually tell you.

Checkpoint: git checkout step-1-first-read. Entitlements configured, a raw NDEF dump on screen.

What an NDEF Record Actually Is

A tag doesn't store a URL. It stores bytes, and bytes are what your app gets handed. This whole section is about turning those bytes into https://example.com and back, and it's a much smaller job than its reputation suggests.

The unit you work with is a record, and a record is three things:

• a payload: the raw bytes of the content

• a type: what that payload is, such as a URI or some text

• a TNF, or Type Name Format: three bits saying how to read the type field itself

That third one is the one people trip on. Think of the type as a label and the TNF as the rule for reading the label. A type byte of U means "URI", but only because the TNF said "this is a well-known NFC Forum type". The same byte under a different TNF would be the start of a MIME string instead.

Two record layouts carry almost all real traffic, and both are tiny.

A URI Record

04 65 78 61 6d 70 6c 65 2e 63 6f 6d
│  └──────── "example.com" ────────┘
└─ prefix index → "https://"

→ https://example.com

The annotations underneath say which byte does what. Everything after the first byte is ordinary text: example.com. The first byte, 04, is an index into a 36-entry table in the NFC Forum spec, and entry 4 is https://.

So the scheme costs one byte instead of eight. On a tag with 137 usable bytes that isn't a micro-optimisation, it's 5% of your budget.

A Text Record

Text needs two things a URI doesn't: which language it's in, and how it's encoded. Both get squeezed into the first byte.

02 65 6e 48 69
│  └─┬─┘ └─┬─┘
│   "en"  "Hi"
└─ status byte

Read that first byte as a number. Here it's 2, and that's how long the language code is. So the next two bytes are the language: 65 6e, "en". Everything after that is the text: 48 69, "Hi".

The encoding hides in the same byte. If its value is 128 or more, the text is UTF-16 instead of UTF-8. That's all a "status byte" means.

That's the whole format. If you're writing the decoder yourself, mask off the low six bits for the length and test the top bit for the encoding.

Why I Wrote My Own Decoder

You reach past a library for one of two reasons. Either it doesn't give you everything you need, or you work somewhere that builds this kind of thing in-house first and takes dependencies second.

The second is more common than the open-source default makes it sound, and for NDEF it has a short answer: yes, you can write this yourself. It's a few hundred lines of pure functions with no platform calls in them, and the format you just read is the whole specification you need.

The first reason is what actually happened here. The library bundles decoders, I read them before using them, and twenty minutes changed the architecture of the app.

It throws away the language code. In ndef-lib/ndef-text.js:

var languageCodeLength = data[0] & 0x3f; // 6 LSBs
// languageCode = data.slice(1, 1 + languageCodeLength),
// utf16 = (data[0] & 0x80) !== 0; // assuming UTF-16BE

// TODO need to deal with UTF in the future

It measures the language code's length, uses it to skip past the code, and the line that would keep it is commented out. decodePayload returns a bare string, so a caller can't recover the language at all. "Which language is this in?" is precisely the question a record with a language field exists to answer.

That TODO is load-bearing. UTF-16 text records are decoded as UTF-8 regardless, producing interleaved NUL characters.

And the shared byte-to-string helper truncates. In ndef-lib/util.js:

str += String.fromCharCode(ch);

String.fromCharCode only keeps the low 16 bits, and an emoji doesn't fit in 16 bits. So I fed it one:

bytes    : 68 69 20 f0 9f 98 80
expected : hi 😀
library  : "hi " codepoints: 68 69 20 f600     ← U+F600, Private Use Area

U+1F600 became U+F600, an invisible character. Three-byte sequences, such as Arabic and CJK, are fine, so the bug hides until someone uses an emoji.

Its URI decoder, meanwhile, is eight lines and completely correct. That asymmetry is the interesting part. This isn't a bad library. It's a library with two stale corners. The only way to know which is which was to read it.

So I wrote the decoder and kept the library for the part that actually talks to the hardware. About 530 lines, all of it plain TypeScript with no React Native imports, which means it runs in Node and tests in milliseconds.

Its job is to turn a record into one of a few known shapes, and that's what this type describes:

export type NdefView =
  | { kind: 'empty' }
  | { kind: 'uri'; uri: string }
  | { kind: 'text'; text: string; lang: string; encoding: TextEncodingName }
  | { kind: 'mime'; mime: string; text?: string; bytes: number[] }
  | { kind: 'aar'; packageName: string }
  | { kind: 'unknown'; tnf: number; type: string; payload: number[] };

Why a union of shapes, rather than one object with lots of optional fields? Because with optional fields, every screen has to guess which ones are filled in. Here you check kind once and TypeScript knows the rest. On a record where kind is 'text', .uri doesn't exist. So a screen that tries to read it fails to compile instead of rendering undefined to somebody holding a phone.

The unknown case still carries the raw tnf, type, and payload, so a record nothing recognises can at least be shown as a hex dump. A reader that silently drops what it doesn't understand is worse than one that says "I don't know what this is, here are the bytes".

One platform difference is buried inside the decoder itself. A record's type field arrives as raw bytes on Android, and sometimes as an already-decoded string on iOS. So the same URI record turns up as [85] on one platform and 'U' on the other, 85 being the byte for the letter U.

That matters because [85] === 'U' is just false. There's no error and no warning: your comparison quietly fails to match, and a perfectly good URI record falls through to "unknown record". Convert the type to a string before you compare it, on both platforms.

Test Against the Thing You Replaced

This is the technique I'd most like people to steal. The tests come in three groups.

Correctness: the decoder against hand-built payloads.

Agreement: where the library is right, prove we match it exactly. Twelve real URIs encoded by the library and decoded by us, plus all 36 prefix indices. That's the cheap way to be confident about a lookup table you typed out by hand.

Divergence is the strange one. Where the library is wrong, write a test that locks in exactly how it's wrong:

✓ the library discards the language code; we keep it
✓ the library truncates 4-byte UTF-8; we do not
✓ both handle 3-byte sequences, so only characters above U+FFFF break
✓ the library ignores the UTF-16 flag; we honour it

That looks backwards. You're writing tests that pass because a dependency is broken, and normally that's a smell.

Two things earn them their place. Each one is a written record of why your own code exists, sitting next to the code instead of in a commit message nobody reads. And because they assert the library's current behaviour, they start failing the day somebody upstream fixes it.

That failure is the whole point. It isn't a broken test, it's a notification: the reason you wrote your own decoder may have just gone away, and you can go and check. A comment saying "the library is buggy" rots quietly while the library changes around it. A test saying so can't.

One detail decides whether these tests are useful or useless. The emoji test asserts the exact wrong answer, the code point 0xf600, rather than just "the library disagrees with us".

If it only checked for disagreement, a future version with a different bug would still pass, and you would never notice the behaviour had changed. Pinning the specific wrong value means any change at all shows up, whether upstream fixed the bug or replaced it with a new one.

Checkpoint: git checkout step-2-decode. Own decoder, a Tag Info screen showing every field and the raw bytes.

How to Write a Tag

Now the other direction. Two options, and they're opposite trades rather than variations.

A URL record is tiny, and every phone opens it with no app installed. It's what most commercial NFC business cards do. It also needs something at the other end: a domain that stays renewed, a server that stays up, or a network connection at the moment someone taps.

A vCard is the whole card. text/vcard as a MIME record, no server, works on a plane. It's also much bigger.

I built both and let the user choose, because the numbers make the argument better than copy could.

Seventeen bytes against 184, for the same person's contact details. That gap is the entire trade, and it's why the choice sits in front of the user instead of being made for them.

How to Encode a vCard

A vCard is just text. This is what the app actually writes onto the tag:

BEGIN:VCARD
VERSION:3.0
N:Doe;Jane;;;
FN:Jane Doe
ORG:Example Ltd
TITLE:Full-stack engineer
TEL;TYPE=CELL:+15550100
EMAIL;TYPE=INTERNET:jane@example.com
URL:https://example.com
END:VCARD

One field per line: a name, a colon, a value, and a carriage return plus newline at the end of every one. Build that string and you have a working card.

The format is from the 1990s and it shows, though, and three of its rules are easy to get wrong. Your encoder has to handle all three.

1. Fold long lines by octets, not characters.

Any line longer than 75 bytes has to be broken and continued on the next one, starting with a space. The obvious way to do that is line.slice(0, 75), which counts characters rather than bytes, so it can cut a two-byte character in half and leave invalid UTF-8 on the tag. Walk the string by code point instead, tracking the byte cost as you go.

2. Emit N, and be up front that you're guessing.

Look at that N: line. vCard 3.0 wants the name split into Family;Given;Additional;Prefix;Suffix, so emitting FN on its own isn't enough. Splitting a display name into those parts is guesswork, and the guess is wrong for Chinese and Hungarian names, for Spanish names with two surnames, and for anyone who goes by a single name. I take the last token, document that it's a guess, and let FN, which is what importers actually display, carry the name exactly as typed.

3. Escape every semicolon inside a value.

The semicolons on that N: line are structural. If someone's job title were "Engineer; Lagos", writing it straight through would turn one field into two and an importer would read the rest as part of the name instead. It has to reach the tag as Engineer\; Lagos.

Get those three right and the whole encoder is about 170 lines of pure string handling, testable without a tag anywhere near it.

The Escaping Bug That Passed Its Tests

That third rule is where my worst bug lived. My escaper had this line:

.replace(/;/g, '\;')   // ← this escapes nothing

vCard wants a literal backslash in front of any semicolon inside a value. '\;' looks like it produces one. It doesn't. JavaScript has no \; escape sequence, so it quietly drops the backslash and hands back a plain ';'. That line was replacing every semicolon with itself.

The fix is '\\;', where the first backslash escapes the second.

Then it got worse. I wrote a test for the escaper and asserted the unescaped output, because I still believed the line worked. The test agreed with the bug, which means it would have failed against correct code.

Then a third test tried to prove a field was absent with not.toContain('N:'). That can never pass. Every vCard starts with BEGIN:VCARD, and BEGIN: ends in N:.

Three mistakes in ten minutes, all the same misunderstanding.

Test-first wouldn't have saved me. The test and the code shared the assumption. String escaping is a domain where they usually do.

Ask the Tag Before You Write to It

A write replaces what's on the chip. The order matters:

1. Query the tag:      is it writable, how big is it really?
2. Refuse early:       read-only, or genuinely too small
3. Write
4. Read it back:       compare with what you sent

Step 2 is the safety property. A refusal before the write leaves the tag untouched, while a failure during one can leave it half-written.

Step 4 exists because a write that reports success and didn't happen is the worst outcome available. Read back inside the same session and compare record content, not raw bytes. A tag may legally return a message whose framing differs from what you sent while carrying identical data.

All four in one session, not four. On iOS each requestTechnology puts a system sheet in front of the user, so splitting them means four sheets and four taps for one logical action. Android wouldn't notice the difference, which is exactly the sort of thing that makes an iOS-shaped design look arbitrary until you see it on the other platform.

You have all four steps in one screen: the tag was asked, the numbers came back measured rather than assumed, the write went out, and the read-back confirmed it byte for byte.

Checkpoint: git checkout step-3-write. Profile editor, vCard encoding, writing with a capacity check.

Will It Fit? 137, Not 144

Here's where the project taught me something.

An NTAG213 has 144 bytes of user memory. That number is in every spec sheet: 36 pages of 4 bytes, pages 4 through 39. I built the capacity check around it.

A realistic vCard (name, title, company, phone, email, one link) comes to 184 bytes of text and 202 bytes once it's wrapped as an NDEF message, which is the figure on the toggle a few sections back.

So an ordinary business card doesn't fit on an ordinary tag. That's a genuine product constraint, not a bug, and the app has to say so rather than fail mysteriously.

Except my number was wrong. When I finally asked a real tag how big it was, it said 137.

144 is the chip's user memory. The number that matters to a writer is the maximum NDEF message, which is smaller by the tag's own bookkeeping. I had been seven bytes too generous, in the direction that tells someone their card fits when it doesn't.

The error hid a second one. A tag doesn't store your message bare: it wraps it in a few bytes of its own bookkeeping, called TLV framing, for type, length and value. I'd been adding those bytes to the message and comparing against user memory. Double-counting. Every capacity figure in play (Android's getMaxSize(), iOS's status query, a sensible assumption) is already a message size with framing excluded.

The Bigger Mistake

Worse than the number was what I'd concluded about the platform.

Because iOS's getTag() returns only { id, tech }, I concluded iOS can't report tag capacity. I wrote that in the code, in the platform comparison, and in the app's own UI, and I planned a native module around closing the gap. Here it is, shipped:

That italic line is the wrong conclusion, stated to the user as fact. Every number in the card above it rests on the guess it forced.

It's false. ndefHandler.getNdefStatus(), which is CoreNFC's queryNDEFStatus, returns both a read/write status and a real capacity, inside the session I was already opening. The capability was one call away from code that had been running for weeks.

Look at the shape of the mistake:

• What I saw: one function, getTag(), hands back two fields and no size. True.

• What I decided: iOS can't tell you how many bytes fit on a tag. That doesn't follow.

One function not answering a question doesn't mean the platform can't answer it. I tried one door, found it locked, and concluded there was no way into the building.

My rule for this project was that nothing gets written down as fact until I've seen it on a device. I followed it for the thing I measured. I forgot it for the thing I concluded from the measurement.

A conclusion you haven't checked is as dangerous as a number you haven't checked, and harder to catch, because it borrows the credibility of the real measurement sitting underneath it.

So the app now asks the tag, and only assumes when no tag has answered yet. When it assumes, it says so, every time:

Too big for this tag
202 bytes, assuming an NTAG213's 137. It is 65 bytes over.
Shorten the profile or write a link instead.

No tag has reported its size yet, so this assumes an NTAG213.
Tags state their real capacity when you write to them.

The word "assuming" appears whenever the number is assumed. It's repetitive by design: the moment the app stops saying it, a reader starts believing it measured something.

Here's the same card once a tag has answered:

"This tag reports" instead of "assuming an NTAG213's". Same card, same layout, and the one word that changes is the one that says whether the number came from a chip or from me.

A Bug That Made This Harder to Find

My pre-flight check threw the library's own TagSizeTooSmall when a message wouldn't fit. So when a write failed, the error said TagSizeTooSmall, exactly what CoreNFC would have produced if it had rejected the write.

There are two things in that developer panel. NfcError.TagSizeTooSmall is the library's class, raised by my own code before the tag was ever consulted. And message: "" (empty) is the defect behind it: the class carried the entire meaning, and the string a screen would print carried none of it.

Our refusal and the tag's refusal were the same string. The one question I was trying to answer (did the platform report a capacity?) was the one the error had erased.

Never throw a dependency's error type from your own logic. It collapses "we refused" and "they refused" into one signal, and you'll want to tell them apart precisely when something is going wrong.

With a dedicated error type carrying the tag's own numbers, the answer was immediate:

WritePreflightError: too-big
tag reported status 2, 137 bytes
needed 202 bytes

There it was. The platform had been reporting capacity all along.

Same screen, same chip, before and after:

Every word under "Capacity" in the first shot is mine, and the confident one is wrong. The blue line beneath it is worse: a whole phase of native work, scheduled to close a gap that wasn't there.

The second reads a number, annotated reported by the tag itself, and nothing was added to the platform in between. Note what didn't change, though. "NDEF type" still says "Not reported", because that one genuinely isn't available. One question the platform can't answer, sitting directly above one it always could, which is exactly why I believed the wrong thing for so long.

A Focus Session You Can't End Without the Tag

A business card is a fine demo, but it only exercises half of what tags are good for. The other half is using a chip as a physical condition: something that must be true in the real world before software will do a thing.

So the app has a second feature: a focus timer you can't stop without walking to the tag.

You leave the chip somewhere inconvenient. Downstairs, in a drawer, at the back of a cupboard. Tap it to start a session. To end the session, you have to go back to it.

This idea isn't mine. Foqos (open source, on the App Store), TapBlok, nfcGuard, and Focusaur all converge on it, and they converge because the insight isn't about NFC at all:

The friction is geography, not the gesture. Tapping costs a second. What costs you is that the tag is downstairs. The tag's location is the product. NFC is merely what makes a location enforceable.

Three rules follow, and each is a line of code.

1. One tag, two meanings.

The same tap starts a session when idle and ends one when focused. Two tags would be two objects to lose and two habits to build. All of the decision lives in one pure function:

export function verdictForTap(
  scannedTagId: string,
  boundTagId: string | null,
  isFocused: boolean
): TapVerdict {
  if (!boundTagId) return { action: 'bind' };

  if (normaliseTagId(scannedTagId) !== normaliseTagId(boundTagId)) {
    return { action: 'wrong-tag', expected: boundTagId };
  }

  return isFocused ? { action: 'end' } : { action: 'start' };
}

That wrong-tag branch is the rule everything rests on. Accept any tag and the ritual becomes "own a sticker" rather than "go to the place where the sticker lives".

The normalising matters more than it looks. The same physical chip is reported as 04C4FC91DF2A81 by one read path and 04:c4:fc:91:df:2a:81 by another. Treating those as different tags is a maddening bug: the right chip, in your hand, silently refused.

The green button isn't a button that ends anything. It starts a scan, and the scan is what ends the session. Underneath it, deliberately quieter, is the way out for the airport.

2. The timer counts up, never down.

A countdown invites you to wait it out on the sofa, since the session ends whether or not you did anything. Counting up measures what actually happened.

3. A broken session is recorded, not prevented.

And this is where the design gets interesting.

What It Can Actually Enforce

It can't block TikTok. Really blocking another app on iOS requires com.apple.developer.family-controls, a privileged entitlement that Apple reviews individually and grants only to apps whose core purpose is digital wellbeing or parental control, and it's required even for TestFlight. Foqos has it. If you're following this handbook, you likely will not, and promising otherwise would be a promise you couldn't keep.

So it enforces the one thing it actually can: the record.

There's an escape hatch, because a commitment device with no way out is one you uninstall the first time you're genuinely stuck at an airport. Taking it costs a permanent, visible mark: this session will be recorded as ended early. That mark is permanent and you'll see it every time you open this tab.

And the history is the vault, not notes or credentials, but the record itself, because that's the only thing in the app worth protecting from its own user. The protection is asymmetric:

A history you can wipe at 11pm from the sofa records nothing. Erasing it costs exactly what earning it did: the walk.

"Ended early" is a column whether or not you have any, which is the point. It sits next to the streak, permanently, so the cost of the escape hatch is visible before you ever use it. And "Clear the record" is the collapsed control at the bottom: the one action in the app that asks for the tag.

Here are two smaller decisions that turned out to matter. A running session survives a relaunch, because it's persisted, so force-quitting isn't a silent way out. The only exits are the tag and the hatch, and one leaves a mark.

And broken sessions still count toward total focused time, because you were focused until you weren't. Zeroing it would be punitive rather than accurate.

The streak, by contrast, is deliberately harsh: one broken session resets it to zero. A number that can't be lost isn't worth looking at.

Two React Bugs the Compiler Caught

Both are general React bugs rather than NFC ones, and neither was caught by me. The React Compiler ships lint rules through eslint-plugin-react-hooks that flag code it can't safely optimise, and two of them fired here. You don't have to adopt the compiler to get them.

const [now, setNow] = useState(Date.now()); // ✗ impure during render

That's the purity rule, and it names this exact case: Date.now() is listed alongside Math.random() and crypto.randomUUID() as an API that "returns a different value for the same inputs". Reading the clock during render makes the component produce different output each time.

The obvious fix (setting it at the top of an effect) trips a second rule. set-state-in-effect puts it plainly: "Setting state immediately inside an effect forces React to restart the entire render cycle", producing "an extra render pass that could have been avoided".

The purity page's own fix is a lazy initialiser, useState(() => Date.now()), and for a clock that starts when the component mounts, that's the right answer. This timer doesn't start at mount, it starts when a session does, so a mount-time stamp would already be stale by then and elapsed would render negative for a frame.

Starting at 0 is both pure and a usable sentinel: falsy means "no tick yet", so the label shows nothing rather than nonsense.

The version that's both correct and clean defers by one task:

useEffect(() => {
  if (!session) return;

  // Deferred rather than called straight away: a synchronous setState inside
  // an effect cascades a second render pass. A zero timeout hands it to the
  // next task, which updates just as promptly without the cascade.
  const first = setTimeout(() => setNow(Date.now()), 0);
  const id = setInterval(() => setNow(Date.now()), 1000);

  return () => {
    clearTimeout(first);
    clearInterval(id);
  };
}, [session]);

Why Your NFC Lock Isn't Secure

The focus feature uses a tag's identifier as a key. So do most NFC "lock" apps. It's worth being blunt about what that is and isn't.

A tag's UID is world-readable and trivially copied. It's not a secret. It's a serial number, broadcast to anything that asks.

This is also what Apple's own Shortcuts automation keys on, as the first section noted, which tells you how the platform itself rates the guarantee: fine for "turn on my desk lamp", never offered as a credential. A £20 device clones one in seconds, and phones can emulate some of them outright. An access system built on "is this UID correct?" is theatre.

For the focus timer, that's completely fine, and worth saying: the threat model is you, being lazy, in your own house. Cloning your own tag to skip a walk is a level of effort that defeats the point of the exercise. Friction is the product, security isn't.

But if you're reaching for a tag as an actual credential (a door, a payment, or a device pairing), the UID is the wrong primitive and you need a chip that can do cryptography.

An NTAG424 DNA is the usual answer. Rather than presenting a static number, it computes a message authentication code over a counter that increments on every tap, using a key that never leaves the chip. Each tap produces a different, signed value, so a captured one is useless a second later. That's the difference between an identifier and an authenticator.

So here's what you take away: A UID answers "which tag is this?" and nothing more. If your security depends on the answer being unforgeable, you need a chip that signs, not one that announces.

Four Gotchas That Cost Me an Evening Each

Each of these looked like a bug in my code and was really a quirk of the platform.

Gotcha 1: The System Sheet Vanishes With No Error

You start a scan. The sheet appears for a moment and disappears. No error, no rejection, and nothing in the console.

This happens because the CoreNFC session was deallocated. Swift frees an object as soon as nothing is holding a reference to it, which is what Automatic Reference Counting, or ARC, does. So if you keep the session in a local variable inside the function that started it, the variable dies when the function returns, and the session goes with it.

To fix this, retain the session on something that outlives the call. In an Expo module, a property:

// Held for the life of the module, not the scan.
private var readSession: Any?

This is the single easiest way to get a CoreNFC integration subtly wrong, and nothing tells you.

Gotcha 2: Your Result Gets Overwritten by the Session Ending

You read a tag successfully, resolve the promise, and JavaScript receives an error instead.

This happens because a successful read also invalidates the session, so didInvalidateWithError fires after your completion handler. If both paths settle the same promise, the later one wins.

To fix this, guard settling so it happens exactly once. One lock, one place:

private func settle(resolving value: [String: Any]) {
  lock.lock()
  defer { lock.unlock() }

  guard let promise else { return }   // already settled: do nothing
  self.promise = nil
  promise.resolve(value)
}

With four nested asynchronous steps and five failure paths, this has to be enforced rather than assumed.

Gotcha 3: Missing required entitlement for an Entitlement You Have

You have NDEF and TAG in your entitlements and the session still refuses to start.

This happens because of polling options, the list of radio standards you tell CoreNFC to listen for when you open a session. Each one is gated by its own entitlement. I asked for [.iso14443, .iso15693, .iso18092], and that last one is FeliCa, a standard used mostly in Japan, which additionally requires com.apple.developer.nfc.readersession.felica.systemcodes. Asking for it without that key fails the entire session, not just that polling mode, and the error never says "FeliCa".

To fix this, ask only for what you can sign for:

pollingOption: [.iso14443, .iso15693],

.iso14443 covers NTAG and MIFARE, which is everything a tag project needs. I'd added the third "so unexpected tags produce better errors". It produced a session that couldn't start.

This is the same lesson as the wildcard-profile error from earlier, arriving from the opposite direction: there, a missing entitlement surfaced as a code-signing failure. Here, an entitlement I never needed surfaced as a runtime one.

Gotcha 4: cannot find 'YourClass' in scope for a File That Exists

You add a Swift file to a local Expo module, build, and the compiler insists the class doesn't exist.

This happens because of how iOS dependencies are wired up. CocoaPods is the package manager that builds them, and each one ships a podspec, a small file listing which sources belong to it. Yours says "every .swift file in this folder", written as **/*.swift.

The catch: CocoaPods expands that pattern once, when pod install runs. It's a list, not a live rule. A file you create afterwards isn't in the Xcode build at all, so the compiler is telling the truth. As far as it knows, your class doesn't exist.

To fix this, remember the rule and stop losing ten minutes to it each time:

Adding a function to an existing file → rebuild. Adding a file → pod install, then rebuild.

The error message mentions neither.

Why You Can't Build Tap to Pay

This is where the gap between the two platforms stops being a matter of degree. Know it before you promise anything to a product manager.

"Tap to pay" means two different things.

First, there's paying with your phone: Apple Pay, or a bank card in Google Wallet. On iOS the Secure Element is closed. There's no third-party API. Not restricted, not entitled: absent.

Second, there's accepting payments on your phone: Tap to Pay on iPhone, or the ProximityReader framework. This exists, and you still can't just build it:

• An organization-level developer account, requested as the Account Holder

• Separate TEST and LIVE entitlements, applied for individually

• Apple reviews against predefined criteria, and LIVE approval can take weeks

• You must integrate through an approved payment service provider: Stripe, Adyen, or Square

Now Android. HostApduService lets any app emulate a card. No approval, no entitlement, and no PSP. Implement processCommandApdu(), register your AID, and you're done. An AID is an Application Identifier, the number a payment terminal asks for to decide which app on the phone should answer.

There's one real gate: AIDs registered under CATEGORY_PAYMENT only work when your app is the default wallet (the Wallet role holder on Android 15+) or is foregrounded and calls setPreferredService. But CATEGORY_OTHER, which covers closed-loop cards, loyalty, access control and stored value, is open and always active.

Unlike every other difference in this handbook, this isn't a difference of degree or of shape. One platform simply doesn't offer the capability. If your product plan involves a phone pretending to be a card, that plan is Android-only, and it's better to learn it now than after a sprint.

Why You Might Write Your Own Native Module

Up to this point everything has run on react-native-nfc-manager. The last third of this project replaced it, and the reason changed partway through.

The original justification was the capacity gap: iOS can't report capacity, so we need our own native code to read it. That argument evaporated, as you've seen. It was an inference, not an observation.

So rather than quietly keeping the work with its motivation gone, here's the real version: some teams can't take a third-party dependency. Internal-only policies, audit requirements, or simply a package they can't get a fix merged into on any useful timescale. "How would I build this myself?" is worth answering on its own terms.

And for this dependency specifically, the evidence was already gathered, by reading it:

That last one caused a real bug in Phase 1: a failed scan rendered nothing at all, because the screen did setError(err.message), the message was '', and React treats an empty string as falsy. The meaning lived only in the class.

None of these are fixable from JavaScript.

The Scaffolding Is No Longer the Hard Part

npx create-expo-module@latest --local --name NfcNative \
  --package com.you.nfcnative -p apple android --features Function

There are four files, wired into the build automatically by pod install. No Xcode project surgery, RCT_EXPORT_METHOD macros, or hand-written JSI, the C++ layer that lets JavaScript call native code directly. If you last wrote a React Native native module in the bridge era, that's the headline.

There are two snags, and neither are documented: --name sets the native module name, while the directory comes from a positional path argument (so without one it lands in modules/my-module). And the generated podspec declares an iOS deployment target that can silently raise your app's minimum.

Typed Errors That Actually Carry a Message

internal final class NoNfcSettingsException: Exception {
  override var reason: String {
    "iOS has no NFC setting to open. NFC is available whenever the hardware supports it."
  }
}

Expo's Exception gives each one a code and a message, both readable from JavaScript. That's the direct fix for the defect behind the silent failure above.

And here's the part that surprised me: owning the native side doesn't exempt you from error plumbing. Expo wraps your exception:

FunctionCallException: Calling the 'openNfcSettings' function has failed
  → Caused by: NoNfcSettingsException: iOS has no NFC setting to open. …

err.message is now the framework describing its own plumbing. Your sentence is at the end of the cause chain. This is the mirror image of the library's problem. There the message was empty, here it's buried, and both break the same reflex.

Here's that chain rendered in the app, exactly as JavaScript received it:

We have three lines of framework before a single word a person could use. The fix isn't in Swift, it's in the screen: walk the cause chain, show the deepest message first, and put the rest behind a disclosure for whoever actually wants it.

Same failure, same information, with nothing thrown away. The sentence written in Swift is the one that leads, and RAW ERROR CHAIN is one tap away when you need it.

Owning the native side changes which layer surprises you.

The Bug 272 Passing Tests Could Not Catch

After switching the app over, cancelling a scan rendered a red "Could not read the tag" card instead of nothing.

Our Swift throws UserCancelledException. The mapping table was keyed on UserCancelledException. They don't match, because Expo derives the code: strip the trailing Exception, split camelCase, upper-case, prefix ERR_:

UserCancelledException  →  ERR_USER_CANCELLED

Why every test passed:

const wrapped = (code, message) =>
  new Error(`Calling the 'readTag' function has failed → Caused by: ${code}: ${message}`);

There's no code property, because I didn't know Expo set one. The code and its tests shared a single wrong assumption and agreed with each other perfectly.

A fixture you invented can only prove your code is self-consistent. It took a thumb on a Cancel button.

The fix keeps the table keyed on the Swift class names and derives the ERR_ forms, so there's one source of truth instead of two lists that drift. The regression is now pinned by a test using the verbatim device error, code property and all.

Checkpoint: git checkout step-4-own-module. The module alongside the library.

How to Prove Parity Before You Switch

Don't swap implementations on faith. Read the same physical tag through both and diff the results.

The design decision that made this useful: "different" isn't one outcome. Our read reports capacity and writability that the library's read path doesn't carry, and scoring that as a mismatch would be actively misleading.

library-only blocking the swap matters: losing information is a real problem even though it isn't a contradiction.

The result on a real NTAG213: four fields are identical, two are reported only by our module, with zero conflicts. That's the evidence the switch was made on, rather than a feeling that the new code looked right.

What a Config Plugin Was Doing For You

The riskiest part of deleting the dependency wasn't code.

react-native-nfc-manager ships a config plugin, and that plugin was generating the iOS NFC entitlement and NFCReaderUsageDescription. Remove the package and both vanish, and the app loses NFC with no error at all. Nothing fails at build time. The sheet simply never appears again.

So the order was: declare them yourself in app.json, prebuild, verify the output is byte-identical to what the plugin produced, then remove the plugin, verify again, then remove the package.

Removing a dependency means inheriting its build configuration. The code it exports is the visible half.

Keep the Evidence After Deleting the Dependency

The argument for replacing that library rests on defects in a package that no longer exists. Delete it and the tests proving those defects stop running, and the agreement tests go too, leaving a hand-typed 36-entry lookup table unverified.

So the repo keeps a frozen copy under vendor/, with its MIT licence, imported by nothing but one test file, and excluded from ESLint and Prettier, because its value is being wrong in documented ways, and reformatting it would destroy the thing it demonstrates.

✓ every error class is constructed with an empty message
✓ turns U+1F600 into U+F600, a Private Use Area character
✓ discards the language code it just measured
✓ ignores the UTF-16 flag in the status byte

If a future version fixes any of that, these fail, which is the signal to reconsider, not a nuisance.

Checkpoint: git checkout step-5-no-dependency

How to Lock a Tag Forever

One operation in this whole field can't be undone. It's the only place where getting the interaction design wrong destroys something physical, which is why it comes last.

NFCNDEFTag.writeLock on iOS, Ndef.makeReadOnly() on Android. Both burn the chip's lock bits. The tag can be read forever and never written again: not by your app, or any other app, or any phone. There's no undo and no factory reset.

Real deployments do this constantly. An event badge, a product-authentication seal, or a museum label: anything handed to the public gets locked, because a tag you can rewrite is a tag anyone can rewrite.

The Gate Is the Feature

The native call is four lines. Everything interesting happens before it.

Two taps guards a write in this app, and that's right for a write: a write is reversible, you simply write something else. It's plainly not enough here. So the gate borrows the pattern GitHub uses for deleting a repository: type the thing's name to prove you know which thing you're destroying.

The status it takes is the tag's own NDEF state, the same value the write path asks for: not NDEF at all, read-write, or already read-only.

export function lockGate(tagId, status, typed): LockGate {
  if (!tagId) return { state: 'no-tag' };
  if (status === NDEF_STATUS.READ_ONLY) return { state: 'already-locked' };
  if (status === NDEF_STATUS.NOT_SUPPORTED) return { state: 'not-lockable' };

  return normaliseTagId(typed) === normaliseTagId(tagId)
    ? { state: 'armed', tagId }
    : { state: 'needs-confirmation', expected: tagId };
}

A confirmation dialog measures willingness. Typing the identifier measures attention. The failure mode worth designing against isn't someone who wants to lock a tag. It's someone who wants to lock a tag and is holding the wrong one.

Which is also why the screen won't arm until you've read the tag first, and shows what's currently on it. An unintended chip announces itself before it can be spent.

The identifier is on screen and also has to be typed. That looks redundant until you picture the failure it's for: the right person, the wrong chip.

Note the order in that function: already-locked is checked before the typed confirmation, so nobody can type their way into "locking" an already-locked tag and be told it worked. It didn't work. There was nothing to do.

"Nothing to Do" Is Not "Something Went Wrong"

AlreadyLockedException is deliberately distinct from LockFailedException, and the UI renders it green, with no lock button. The tag is in exactly the state you asked for. Reporting that as a failure would alarm someone about a perfectly good chip.

"Nothing to do, and nothing was changed" is doing real work in that sentence. It tells you the app didn't try, which is the part you want to know about an operation that can't be repeated.

This is the same principle as never throwing a dependency's error type from your own logic: two different situations must not arrive as one signal, and the moment you want them apart is the moment something is going wrong.

Verify, Because You Can't Retry to Find Out

Both implementations re-read the status afterwards. That check exists in the write path too, but it carries different weight here:

A failed write is recoverable: write again. A lock that reports success and didn't happen sends a tag into the world believing it's protected, and you can't retry to find out, because retrying is itself the destructive act.

So an unverified lock isn't reported as a soft warning the way an unverified write is. The copy says the chip's state is unknown and to read it before relying on it.

The strongest confirmation comes later, from the tag rather than the app. Try to write to it again and CoreNFC itself refuses, in the system sheet, before your code gets a say:

That sentence is written by iOS, not by this app. It's the only proof that really counts, and the one you can never collect twice.

A Separate Class, Not a Flag

NfcLockSession duplicates a fair amount of the write session: setup, delegate, and settle-once discipline. That's deliberate.

The alternative was a lock: Bool on the write session. A boolean parameter that sometimes destroys the tag is exactly what gets passed by accident in a refactor three months later, by someone who has never read the file. Two call sites, two intentions, and no shared branch reachable from the wrong place.

Sometimes the right response to "this is nearly the same code" is to let it be nearly the same code.

And One Test That Was Right While the Code Was Wrong

it('refuses a tag that is not NDEF at all', () => {
  expect(lockGate(TAG, NDEF_STATUS.NOT_SUPPORTED, TAG).state).toBe('armed');
});

The name says refuses. The assertion says armed. It passed, because the code did arm, and writeLock is a method on NFCNDEFTag, so a non-NDEF chip should never have been offered it.

The name was right and the code was wrong. It was caught by reading a passing test's name next to its assertion, which is the only way it could have been caught: a test that agrees with the wrong code is invisible to a test run.

How Would You Actually Ship This?

Everything above was built locally with expo run:ios, Xcode, CocoaPods, and twice, a completely full disk. The alternative is EAS Build, and it deserves an real comparison rather than a recommendation.

Everything below was run: one production build on EAS, plus a deliberately rigged experiment to test the headline claim rather than assume it. The only thing I have not done is install the resulting .ipa. It's an App Store build, so it can't be side-loaded, and every NFC claim in this handbook still rests on locally-built binaries on a real phone.

The Step EAS Would Have Saved

The worst afternoon of this project was this error:

Provisioning Profile "iOS Team Provisioning Profile: *" does not support
the NFC Tag Reading capability.

The fix was manual and undiscoverable from the message: register an explicit App ID in Apple's portal, tick NFC Tag Reading, and regenerate the profile. Nothing in the error suggests opening a browser.

EAS does that step automatically. If a supported entitlement is in your entitlements file, eas build enables the matching capability on the Apple Developer Console and skips it if it's already on. And com.apple.developer.nfc.readersession.formats, exactly the key this app declares, is on the supported list by name.

So the single most painful manual step in the whole handbook is automated by the thing I didn't use.

How to Prove It Rather Than Believe It

Running eas build against TapCard's real bundle identifier can't demonstrate this, and it's worth understanding why before trusting anyone's screenshot of it working:

✔ Bundle identifier registered com.nfccard.tap
✔ Synced capabilities: No updates

No updates, because that App ID already had NFC Tag Reading enabled. I enabled it by hand, in a browser, in the chapter this section is about. All this proves is that EAS agrees with work I already did. Plenty of "EAS handles it for you" claims rest on exactly this output.

The real test needs a bundle identifier that has never existed. So: a throwaway project, com.nfccard.tap.eastest, containing essentially nothing but the entitlement, deliberately kept separate from the real app rather than temporarily renaming its bundle ID, which risks muddling stored credentials.

✔ Bundle identifier registered com.nfccard.tap.eastest
✔ Synced capabilities: Enabled: NFC Tag Reading

That's the claim, observed. An App ID that didn't exist, registered and given the NFC capability from the entitlements file alone, with no browser and no portal. And because the sync runs at the credentials step, that command was eas credentials:configure-build, and it consumed no build.

One practical note if you repeat this: run the real build first. Distribution certificates are account-wide and Apple limits how many you may hold, so doing the throwaway first would burn one on an app you intend to delete. Done in that order, the scratch app offered to reuse the real certificate and only created its own provisioning profile, which is per bundle ID.

What the CLI Actually Does

The mapping isn't magic and it's not buried. It's a lookup table, and NFC has an entry in it (eas-cli/build/credentials/ios/appstore/capabilityList.js):

{
  name: 'NFC Tag Reading',
  entitlement: 'com.apple.developer.nfc.readersession.formats',
  capability: CapabilityType.NFC_TAG_READING,
  // Technically it seems only `TAG` is allowed, but many apps and packages tell users to add `NDEF` as well.
  validateOptions: createValidateStringArrayOptions(['NDEF', 'TAG']),
  getSyncOperation: getDefinedValueSyncOperation,
}

Read that comment again, because it is quietly about you: NDEF may not be a real value. Every tutorial tells you to write ["NDEF", "TAG"], this handbook's own app.json writes ["NDEF", "TAG"], and the person maintaining the mapping table clearly suspects only TAG means anything, but accepts both, because refusing the pair would break everybody. That's what a convention looks like when nobody checks the spec.

getDefinedValueSyncOperation is the other half. The operation keys off whether the entitlement is defined, which is why the sync runs in both directions rather than only adding things.

And one practical detail the documentation doesn't tell you: the sync is triggered by the credentials step, not the build step.

SetUpTargetBuildCredentials.runAsync()
  └─ ensureBundleIdExistsAsync({ entitlements, … })
       └─ syncCapabilitiesAsync()
            → "Synced capabilities: Enabled: NFC Tag Reading"    (or "No updates")

So eas credentials:configure-build --platform ios registers the App ID and syncs the capabilities without consuming a build. If all you want is Apple's side of the setup done correctly, you don't have to pay for a build to get it.

The Trap That Comes With It

The sync runs both ways: if a capability is enabled for your app remotely, but not present in the native entitlements file, running eas build will automatically disable it.

A team that manages capabilities by hand in the portal and builds with EAS will watch EAS switch things off. The entitlements file becomes the source of truth whether you meant it to or not.

EXPO_NO_CAPABILITY_SYNC=1 opts out, with the caveat that opting out means remote changes stop syncing, which produces provisioning-profile mismatches later. Pick one owner for capabilities and let it own them.

What EAS Would Not Have Helped With

"Use EAS" isn't an answer to most of this project's pain, and pretending otherwise would be selling something:

EAS removes machine problems, not NFC problems. Every finding in this handbook that was actually about NFC would have happened identically.

The Trade

Local builds cost disk, memory, and setup. This project filled a 460 GB disk twice, had three background processes killed under memory pressure, and lost a rebuild to a stale Gradle daemon.

EAS costs queue time and a cloud project, and puts your signing credentials on Expo's servers. What it can't shorten is the loop that actually matters here: you still have to walk to a phone and hold a chip against it. A cloud build that goes green tells you nothing about whether the tag read.

For a solo project with a working local toolchain, local wins on iteration speed. For a team, a CI pipeline, or anyone who has just watched their disk hit 100% mid-build, the capability sync alone is a strong argument.

A Sneak Peek at the Android Side

Android deserves its own handbook, and it's getting one. This section is the preview for anyone who doesn't want to wait: the Kotlin counterpart to the Swift above, and the architectural differences that make NFC on the two platforms genuinely different jobs rather than the same job twice.

Read it as a design preview rather than a verified implementation. The Kotlin compiles against the documented API and mirrors Swift that is verified on hardware, so the shapes are right, and the full treatment with a device in hand is the handbook that follows this one.

The differences that matter are visible from the API surface rather than from a device, and they're the ones that decide how you structure the code.

Android Has No Session

iOS hands you a session, and the session is the model: you begin it, the OS draws a sheet, it hands you a tag, and it invalidates itself. Android gives you reader mode: a callback bound to your foreground Activity that fires whenever a tag comes near.

adapter.enableReaderMode(activity, ::onTagDiscovered, flags, Bundle())

Everything the iOS session did for you becomes yours:

That last row reaches all the way back into the JavaScript. The cross-platform cancelScan() is a real implementation on Android and a documented no-op on iOS, where the system sheet owns cancelling and the Swift module deliberately doesn't implement the function at all:

export async function cancelScanNative(): Promise<void> {
  if (Platform.OS !== 'android') return;
  await NfcNative.cancelScan();
}

Also: pass FLAG_READER_NO_PLATFORM_SOUNDS, or the OS plays its own discovery sound over an app that is already telling the user what to do.

The Kotlin, and One Design Note

private fun onTagDiscovered(tag: Tag) {
  val ndef = Ndef.get(tag) ?: run {
    stopReaderMode(); rejectOnce(NotNdefException()); return
  }

  try {
    ndef.connect()

    val status = NfcTagInfo.status(ndef)
    val capacity = ndef.maxSize

    messageToWrite?.let { message ->
      // Ask before acting, same order as the Swift: refusing leaves the tag
      // untouched, failing partway through a write may not.
      if (!ndef.isWritable) { … }
      if (message.toByteArray().size > capacity) { … }
      ndef.writeNdefMessage(message)
    }

    // Read back in the same connection. For a write this is verification,
    // for a read it is simply the result.
    val onTag = ndef.ndefMessage
    …
  } finally {
    runCatching { ndef.close() }
  }
}

Android has no equivalent of iOS's NFCNDEFStatus, so the status is derived rather than reported.

fun status(ndef: Ndef?): Int =
  when {
    ndef == null -> 1     // not NDEF: signalled by Ndef.get() returning null
    ndef.isWritable -> 2  // read-write
    else -> 3             // read-only
  }

iOS answers that question directly. Android signals "not NDEF" by Ndef.get() returning null and exposes isWritable on a connected tag. Mapping both onto one set of numbers keeps the TypeScript from ever needing to know which platform it's talking to, which is the entire job of a native module.

If You Port This, the Differences That Will Matter

Two patterns come from that table.

iOS front-loads the pain and Android back-loads it. Portals, entitlements and signing before you read a byte, versus reader mode, Activity lifecycle and building your own cancel once you're running.

And the capacity difference is narrower than it looks. It isn't that iOS tells you less. It's that Android volunteers this on an ordinary read while iOS makes you ask a specific question inside a session. Same data, different price of admission. I got that wrong for three documents, as you've seen.

The Demo Repository

Everything above is one project, TapCard, and it's a single app rather than a snippet dump.

293 tests, 15 suites, about a second, and no hardware. That's the payoff of keeping the decoding pure.

And the tagged checkpoints, so you can read the app at any stage rather than only at the end:

git checkout step-0-scaffold        # boots, no NFC
git checkout step-1-first-read      # entitlements + raw dump
git checkout step-2-decode          # own decoder, Tag Info
git checkout step-3-write           # vCard, capacity checks
git checkout step-4-own-module      # native module alongside the library
git checkout step-5-no-dependency   # library removed
git checkout step-6-android         # Kotlin reader mode

Clone it, buy a pack of stickers, check out step-1-first-read, and hold a chip against your own phone. That loop is the fastest way to make everything above concrete.

What to Know Before You Start

Buy the tags first. There's no simulator. When my chips went missing in the post the project stopped dead for two weeks, and no amount of clever architecture substituted for a chip.

Read your dependencies before trusting them. Twenty minutes with ndef-lib found three real defects and changed the architecture of the app. None of them were in an issue tracker I'd have thought to search.

Assume the failure will be silent. Of the seventy-five traps I logged, roughly a dozen produce no error at all: the deallocated session, the removed config plugin, the unescaped semicolon, the truncated emoji, the empty error message, and the gitignored native module. In NFC work "nothing happened" is the most common symptom, so instrument accordingly and confirm on the real surface rather than trusting a return value.

Put the platform difference in the type, not in a comment. Model "this platform doesn't tell us" as a first-class state:

type Fact = {
  label: string;
  value: string | null; // null = the platform did not report it
  unavailable?: string; // why, in plain language
};

A UI that renders a bare dash for both an absent value and a zero teaches nothing.

And don't let a conclusion inherit the credibility of the observation underneath it. That one cost the most, and it wasn't about NFC at all.

Conclusion

You now have the whole picture on iOS: the entitlement maze, a decoder written by hand because the popular one loses data, a write path that asks the tag before it acts, a focus timer enforced by geography, a native module in Swift, a dependency deleted with its evidence preserved, and a tag locked forever behind a gate that makes you type its name.

Three things are worth exploring next.

1. Background tag reading: Tap a tag with the app closed. iOS surfaces a notification the user must tap, and only for certain record types. It's the feature that makes NFC feel magic, and the rules around which records qualify are worth a piece of their own.

2. Cryptographic tags: An NTAG424 DNA signs a counter on every tap. If you ever want a tag to be a credential rather than a label, that's where to start.

3. And Android, which is the next handbook. The preview above is the map, and the full walkthrough on real hardware is what comes after this one.

The interesting part was never requestTechnology. It was everything the two platforms decline to tell you when you get it wrong.

Sources and Further Reading

Apple, CoreNFC and entitlements:

• Core NFC, NFCTagReaderSession, and NFCNDEFTag

• queryNDEFStatus: the call this project wrongly concluded did not exist

• Near Field Communication Tag Reader Session Formats entitlement

• Setting up the entitlement for Tap to Pay on iPhone

• Configuring Family Controls

• CoreNFC availability on iPad: an Apple engineer confirming the framework is iPhone-only

Android:

• NFC basics and Advanced NFC

• NfcAdapter.enableReaderMode

• Ndef: getMaxSize(), isWritable()

• Host-based card emulation

The format:

• NFC Forum NDEF and RTD specifications: the URI prefix table and the Text record status byte

• RFC 2426: vCard 3.0, including the N field and line folding

Expo and React Native:

• eslint-plugin-react-hooks, and the two rules that caught the focus timer: purity and set-state-in-effect

• Expo Modules API and Config plugins

• Continuous Native Generation

• iOS capabilities on EAS Build: which entitlements EAS syncs, and EXPO_NO_CAPABILITY_SYNC

• expo-modules-core, ios/Core/Exceptions/CodedError.swift: where ERR_USER_CANCELLED comes from

Shipped NFC you can go and check, cited in "Where You Have Already Seen This":

• Setting triggers in Shortcuts, Apple. The NFC trigger needs iPhone XS or later and iOS 13.1

• Mark an AirTag or other item as lost in Find My, Apple

• amiibo FAQ, Nintendo, on read-only versus read/write figures

• Using the "UK Immigration: ID Check" app, GOV.UK

• Tap to Pay on iPhone and its supported regions, Apple

Prior art for the focus feature:

• Foqos (open source, App Store) and TapBlok

The library this project replaced:

• react-native-nfc-manager: MIT. The defects described here were found in 3.17.2 by reading the source, and a frozen copy lives in the demo repo's vendor/ with the tests that pin them.

Foundation Models is Apple's Swift framework for working with large language models. It's the on-device model behind Apple Intelligence, Apple's Private Cloud Compute, or another provider's server model.

This tutorial targets the on-device model: you send it a prompt and it runs entirely on the Mac's own hardware locally, free-per-call, and offline-friendly.

Paired with Apple Vision for reading images on device, that's enough to build real AI features like summaries, classification, and structured extraction without the data ever leaving your machine.

Table Of Contents

• What You Will Build

• Prerequisites

• Why a macOS Companion App?

• Foundation Models Can't Read Images Directly

• Project Structure

• Build the React App

  • Check Companion Health

  • Convert the Image to Base64

  • Analyze Immediately After Upload

  • Send the Image to the Companion

  • Render the JSON Output

• Build the macOS Companion App

• Check Foundation Models Availability

• Extract Text with Apple Vision

• Ask Foundation Models to Explain the Vision Output

• Return JSON to the Browser

• Run the App

• Conclusion

• Resources

What You Will Build

You'll build Vision Bridge, a web app that sends an image to a local macOS companion. The companion reads the image with Apple Vision, reasons about it with Foundation Models, and returns structured JSON to the browser: private, on-device AI behind a plain web interface.

You can find the complete source code in this GitHub repository: github.com/03balogun/vision-bridge.

The goal isn't to build a giant product but rather to understand the architecture behind how this works.

Vision Bridge has two parts:

• A React app with a split-screen interface.

• A macOS companion app that exposes a local API.

The React app has:

• An image upload area

• An image preview

• Automatic analysis after upload

• A JSON output viewer

• A companion health status indicator

The macOS companion app has:

• GET /v1/health

• POST /v1/analyze-image

• Apple Vision OCR

• Foundation Models availability checks

• Foundation Models reasoning over Vision output

The final response looks like this:

{
  "support": {
    "visionAvailable": true,
    "foundationModelAvailable": true,
    "foundationModelStatus": "available"
  },
  "image": {
    "filename": "screenshot.png",
    "contentType": "image/png",
    "byteCount": 1048576,
    "width": 1440,
    "height": 900
  },
  "vision": {
    "detectedText": [
      {
        "text": "Build failed",
        "confidence": 0.96,
        "boundingBox": {
          "x": 0.12,
          "y": 0.31,
          "width": 0.45,
          "height": 0.08
        }
      }
    ]
  },
  "model": {
    "summary": "The image appears to show a software build failure.",
    "description": "A developer tool window is showing an error state with diagnostic text.",
    "suggestedTags": ["screenshot", "developer-tool", "error"],
    "possibleUses": [
      "Generate alt text",
      "Summarize screenshots",
      "Extract document data"
    ]
  }
}

Prerequisites

To follow along, you need:

• macOS 26 or newer

• Xcode with the macOS 26 SDK

• Node.js 20 or newer

• Basic React knowledge

• Basic Swift knowledge

• A Mac that supports Apple Intelligence

Foundation Models availability depends on the Mac, the OS version, and Apple Intelligence settings. The companion checks this at runtime, which we'll cover below.

Why a macOS Companion App?

You can't write this in a regular React app:

import FoundationModels from "apple-frameworks";

That API doesn't exist in the browser. A native macOS app, however, can use any Apple framework, so the companion acts as a local bridge. The same pattern works for any native capability the web platform doesn't expose.

Foundation Models Can't Read Images Directly

The public Foundation Models framework is a language model interface. It doesn't currently expose direct image input the way a multimodal cloud model might, so this tutorial never sends the image to the model. Instead, the companion feeds the Vision OCR observations and image metadata into the prompt. The model reasons over structured text, never the original pixels.

That split plays to each framework's strength: Vision is excellent at pulling machine-readable information out of images, and Foundation Models turns that information into summaries, labels, explanations, and structured output.

The above diagram shows the round trip that the rest of this tutorial builds. The browser sends the uploaded image as base64 JSON over localhost to the Swift companion. Inside the companion, Apple Vision runs OCR on the image and produces text observations: the recognized strings, their confidence scores, and their bounding boxes.

Those observations, not the image itself, are formatted into a prompt for Foundation Models, which generates a summary, description, and tags. The companion then bundles the Vision output and the model output into one JSON response and returns it to the browser.

Project Structure

Create a project with this structure:

vision-bridge/
  apps/
    web/
      src/
        main.tsx
        styles.css
      package.json
      vite.config.ts
    macos-companion/
      Package.swift
      Sources/
        VisionBridgeCompanion/
          main.swift
  package.json
  README.md

The root package.json gives us a few convenient commands:

{
  "scripts": {
    "dev": "npm --workspace apps/web run dev",
    "build": "npm --workspace apps/web run build",
    "companion": "swift run --package-path apps/macos-companion VisionBridgeCompanion"
  },
  "workspaces": ["apps/web"]
}

Build the React App

The web app is intentionally simple. It has one job: let the user pick an image and show the JSON returned by the companion.

The web app uses Vite, React, Lucide icons, and a JSON viewer:

{
  "dependencies": {
    "@vitejs/plugin-react": "^6.0.3",
    "lucide-react": "^0.468.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "react-json-view-lite": "^2.5.0",
    "vite": "^8.1.3"
  }
}

After defining the dependencies, install them:

npm install

The API base URL points to the local companion:

const API_BASE_URL = "http://127.0.0.1:43119";

Check Companion Health

The web app pings the companion so the UI can show whether the native bridge is online:

async function checkHealth() {
  setHealthError(null);

  try {
    const response = await fetch(`${API_BASE_URL}/v1/health`);
    if (!response.ok) {
      throw new Error(`Health check failed with ${response.status}`);
    }

    const payload = await response.json();
    setHealth(payload);
  } catch (error) {
    setHealth(null);
    setHealthError(error instanceof Error ? error.message : "Companion unavailable");
  }
}

Convert the Image to Base64

When the user selects a file, the app converts it to base64 so it can be sent as JSON:

function readFileAsBase64(file: File) {
  return new Promise<string>((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => {
      const result = String(reader.result);
      resolve(result.includes(",") ? result.split(",")[1] : result);
    };
    reader.onerror = () => reject(reader.error);
    reader.readAsDataURL(file);
  });
}

This isn't the only way to upload files. You could also use multipart/form-data, but JSON keeps the demo easy to inspect.

Analyze Immediately After Upload

The app starts analysis as soon as an image is uploaded:

async function handleFile(file: File) {
  if (!file.type.startsWith("image/")) {
    setError("Choose a PNG, JPEG, HEIC, or another browser-readable image.");
    return;
  }

  const base64 = await readFileAsBase64(file);
  const nextImage = {
    file,
    previewUrl: URL.createObjectURL(file),
    base64,
  };

  setSelectedImage(nextImage);
  setAnalysis(null);
  setError(null);
  setCopied(false);

  analyzeImage(nextImage);
}

handleFile does the preparation work for every new image. It rejects anything that isn't a browser-readable image, converts the file to base64, and builds a single object holding everything the rest of the flow needs: the original File (for its name and MIME type), an object URL for the preview, and the base64 payload for the API call.

It then clears out the previous run the old analysis, any error message, and the "copied" indicator so the UI never shows results from the last image next to a new one. Finally, it kicks off analyzeImage(nextImage) immediately.

Note that it passes the fresh object directly instead of relying on the selectedImage state: React state updates don't apply until the next render, so reading the state here would still give you the previous image.

The Analyze button still exists in the UI, but it works as a manual rerun button.

Send the Image to the Companion

Here's the core request:

const analysisRequestId = useRef(0);

async function analyzeImage(image = selectedImage) {
  if (!image) {
    setError("Choose an image first.");
    return;
  }

  const requestId = analysisRequestId.current + 1;
  analysisRequestId.current = requestId;

  setRequestState("loading");
  setError(null);
  setCopied(false);

  try {
    const response = await fetch(`${API_BASE_URL}/v1/analyze-image`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        filename: image.file.name,
        mimeType: image.file.type || "application/octet-stream",
        base64: image.base64,
      }),
    });

    const payload = await response.json();

    if (requestId !== analysisRequestId.current) {
      return;
    }

    if (!response.ok) {
      throw new Error(payload.error?.message ?? `Analysis failed with ${response.status}`);
    }

    setAnalysis(payload);
    setRequestState("success");
  } catch (error) {
    if (requestId !== analysisRequestId.current) {
      return;
    }

    setRequestState("error");
    setError(error instanceof Error ? error.message : "Could not analyze image");
  }
}

This function is the entire client side of the bridge. It flips requestState to loading (which drives the spinner and disables the button), then sends a POST to /v1/analyze-image with a JSON body containing three fields: the filename, the MIME type, and the base64 image data. That body maps one-to-one onto the AnalyzeImageRequest struct the Swift companion decodes later.

Notice that the response is parsed as JSON before checking response.ok. That's deliberate: when the companion rejects a request (bad base64, oversized image), it still returns a JSON body with an error.message field, so the UI can show the companion's own explanation instead of a generic status code. On success, the payload goes straight into state, and the JSON viewer re-renders with the result.

The requestId bookkeeping guards against stale responses. If a user uploads a second image while the first is still analyzing, whichever request finishes last would win, and OCR plus model generation takes long enough that responses can genuinely arrive out of order. So every call increments a counter stored in a ref and remembers its own ID.

After the await, it checks whether it's still the newest request; if a newer upload started in the meantime, the older response is silently discarded instead of overwriting the latest image's result. The same check runs in the catch block, so an old failure can't clobber a newer success either. If you also want to cancel the in-flight HTTP request rather than just ignore its result, an AbortController is the natural next step.

Render the JSON Output

The output pane uses react-json-view-lite:

<JsonView
  data={jsonData}
  shouldExpandNode={allExpanded}
  style={jsonViewTheme}
/>

Build the macOS Companion App

The companion is a Swift command-line app. It exposes a small local HTTP API.

If you come from the web side, the mapping is simple: Swift Package Manager is Swift's npm, Package.swift is its package.json, and swift run is its npm start. It ships with Xcode, so there's nothing extra to install.

The Package.swift file looks like this:

// swift-tools-version: 6.0

import PackageDescription

let package = Package(
    name: "VisionBridgeCompanion",
    platforms: [
        .macOS("26.0")
    ],
    products: [
        .executable(
            name: "VisionBridgeCompanion",
            targets: ["VisionBridgeCompanion"]
        )
    ],
    targets: [
        .executableTarget(
            name: "VisionBridgeCompanion"
        )
    ]
)

The companion imports the Apple frameworks it needs:

import Foundation
import FoundationModels
import ImageIO
import Network
import Vision

It listens on 127.0.0.1:43119:

private let defaultPort: UInt16 = 43119

The app exposes two routes:

switch (request.method, request.path) {
case ("GET", "/v1/health"):
    let health = HealthResponse(support: ModelSupport.current)
    return try json(health)

case ("POST", "/v1/analyze-image"):
    let payload = try JSONDecoder().decode(AnalyzeImageRequest.self, from: request.body)
    let response = try await service.analyze(payload)
    return try json(response)

default:
    return try json(
        ErrorResponse(error: APIErrorPayload(message: "Route not found")),
        status: .notFound
    )
}

This switch is the companion's entire routing layer — no web framework, just pattern matching on the method and path.

The two routes split the work cleanly:

• GET /v1/health is the cheap, read-only route. It runs no analysis, it just reports whether Vision and Foundation Models are usable on this Mac via ModelSupport.current (covered in the next section). The React app calls it on load to render the online/offline status pill, so the user knows the bridge is up before they upload anything.

• POST /v1/analyze-image is where the real work happens. It decodes the request body into an AnalyzeImageRequest (with the same filename, mimeType, and base64 fields the browser sent) and hands it to the analysis service. This validates the image, runs Vision OCR, prompts Foundation Models, and returns the combined result. The try await matters here: analysis is asynchronous, and the route simply waits for it before serializing the response.

Anything else falls through to a JSON 404, so even unknown routes respond in the same format the browser already knows how to parse.

Errors work the same way: thrown errors are caught in one place and converted into JSON error responses with an appropriate status code, which is exactly what the web app's payload.error?.message check reads.

One practical detail: because the browser calls the companion from a different origin (the Vite dev server), every response also carries CORS headers, and the router answers preflight OPTIONS requests with an empty 204. Without that, the browser would block the fetch before it ever reached these routes.

Check Foundation Models Availability

The companion shouldn't assume that the model is available. Check it first:

private struct ModelSupport: Encodable {
    let visionAvailable: Bool
    let foundationModelAvailable: Bool
    let foundationModelStatus: String

    static var current: ModelSupport {
        let model = SystemLanguageModel.default

        switch model.availability {
        case .available:
            return ModelSupport(
                visionAvailable: true,
                foundationModelAvailable: true,
                foundationModelStatus: "available"
            )

        case .unavailable(let reason):
            return ModelSupport(
                visionAvailable: true,
                foundationModelAvailable: false,
                foundationModelStatus: "unavailable.\(reason.description)"
            )

        @unknown default:
            return ModelSupport(
                visionAvailable: true,
                foundationModelAvailable: false,
                foundationModelStatus: "unavailable.unknown"
            )
        }
    }
}

A user might have an unsupported Mac, Apple Intelligence might be disabled, or the model might not be ready yet. The response tells the browser which case it's dealing with.

Extract Text with Apple Vision

The companion decodes the base64 image, checks its metadata, then runs Vision OCR.

Here's the text recognition flow:

private func recognizeText(in imageData: Data) async throws -> [DetectedText] {
    var request = RecognizeTextRequest()
    request.recognitionLevel = .accurate
    request.automaticallyDetectsLanguage = true
    request.usesLanguageCorrection = true

    let observations = try await request.perform(on: imageData)

    var detectedText: [DetectedText] = []

    for observation in observations {
        guard let candidate = observation.topCandidates(1).first else {
            continue
        }

        let bounds = NormalizedBox.from(points: [
            observation.topLeft,
            observation.topRight,
            observation.bottomRight,
            observation.bottomLeft
        ])

        detectedText.append(DetectedText(
            text: candidate.string,
            confidence: Double(candidate.confidence),
            boundingBox: bounds
        ))
    }

    return detectedText
}

Vision gives us structured observations:

• recognized text

• confidence scores

• normalized bounding boxes

Those observations become the model’s context.

Ask Foundation Models to Explain the Vision Output

Now the companion creates a prompt from the image metadata and OCR results.

Notice the instruction:

You cannot see the original image. Use only the metadata and OCR observations below.

That keeps the model honest. It shouldn't pretend to see pixels it never received.

Here's the prompt shape:

let textPreview = detectedText
    .prefix(30)
    .map { "- \($0.text) (confidence: \(String(format: "%.2f", $0.confidence)))" }
    .joined(separator: "\n")

let prompt = """
You are summarizing Apple Vision OCR output for a developer tool named Vision Bridge.
You cannot see the original image. Use only the metadata and OCR observations below.

Image:
- filename: \(image.filename)
- content type: \(image.contentType)
- size: \(image.width ?? 0)x\(image.height ?? 0)

OCR observations:
\(textPreview.isEmpty ? "- No text detected." : textPreview)

Return a compact JSON object with these exact keys:
summary: one sentence
description: one short paragraph
suggestedTags: 3 to 6 short tags
possibleUses: 3 to 5 practical use cases for this kind of image analysis
"""

Then call the model:

let session = LanguageModelSession(
    model: .default,
    instructions: "Return valid JSON only. Do not include Markdown fences."
)

let response = try await session.respond(to: prompt)
let raw = response.content.trimmingCharacters(in: .whitespacesAndNewlines)

Even when you ask for JSON, always validate the output. Models can still return Markdown fences or malformed text. The sample app strips simple Markdown code fences and falls back to a raw response if parsing fails.

Return JSON to the Browser

The companion combines the support state, image metadata, Vision results, and model output:

return AnalyzeImageResponse(
    support: support,
    image: metadata,
    vision: VisionPayload(detectedText: detectedText),
    model: modelInsight
)

The browser doesn't need to know how Vision or Foundation Models work. It just receives JSON. The native app owns the native capabilities, while the web app owns the interface.

It's worth pausing on what each of the four blocks actually gives you, because they're not all the same kind of data:

• support tells you what was possible on this Mac. If foundationModelAvailable is false, the model block still exists but contains a fallback message rather than real analysis, and the foundationModelStatus string (for example, unavailable.appleIntelligenceNotEnabled) tells the UI why, so it can explain rather than silently degrade.

• image echoes back the file's metadata plus the measured pixel dimensions. It's useful as a sanity check, and you need the width and height to do anything spatial with the Vision results.

• vision is the ground truth. Each entry in detectedText is a string Vision actually found, with a confidence score between 0 and 1 and a normalized bounding box: coordinates expressed as fractions of the image size, so x: 0.12, width: 0.45 means "starts 12% from the left and spans 45% of the width." Because the boxes are normalized, you can draw highlight overlays on the preview at any display size by multiplying by the rendered dimensions. Low-confidence entries are worth filtering or flagging before you trust them.

• model is interpretation, not observation. The summary, description, suggestedTags, and possibleUses fields are generated by the language model from the OCR text. This is useful as alt text, captions, or tag suggestions, but they inherit whatever the OCR missed and should be treated as a draft, not a fact. When the model's output can't be parsed as JSON, rawResponse carries the unparsed text so nothing is lost.

For a screenshot of a failed build, the model block might come back like this:

{
  "model": {
    "summary": "The image appears to show a software build failure.",
    "description": "A developer tool window is showing an error state with diagnostic text.",
    "suggestedTags": ["screenshot", "developer-tool", "error"],
    "possibleUses": [
      "Generate alt text",
      "Summarize screenshots",
      "Extract document data"
    ]
  }
}

That combination (exact text with positions from Vision, plus a human-readable interpretation from the model) is enough to build real features on top of a searchable screenshot library indexed by detectedText and suggestedTags, automatic alt text for uploaded images, or click-to-highlight overlays powered by the bounding boxes.

And because the prompt lives in the companion, changing what comes back (say, extracting line items from receipts instead of tagging screenshots) is a prompt edit, not an architecture change.

Run the App

Start the companion:

npm run companion

In another terminal, start the web app:

npm run dev

Open the Vite URL:

http://127.0.0.1:5173

If that port is busy, Vite will choose another one.

The companion should be available at:

http://127.0.0.1:43119

You can test it directly:

curl http://127.0.0.1:43119/v1/health

Expected response:

{
  "app": "Vision Bridge Companion",
  "ok": true,
  "support": {
    "foundationModelAvailable": true,
    "foundationModelStatus": "available",
    "visionAvailable": true
  },
  "version": "0.1.0"
}

Conclusion

You now have a React interface that uploads an image, a Swift companion that analyzes it with Apple-native frameworks, and structured JSON flowing between them.

Vision Bridge is intentionally small, but the bridge itself is reusable. Once you have a trusted native companion, a web app can do more than send prompts to a remote model: it can ask the Mac to work with local context, use any Apple framework, and return structured data the browser can render, store, or sync.

Resources

• Apple Foundation Models documentation

• Apple Vision documentation

So if you’re an iOS developer, you should also learn to prioritize security at every stage of app development.

Swift, Apple’s modern programming language, offers a wealth of tools and frameworks that simplify development while enhancing security, but only when used correctly.

This article explores 10 common security pitfalls in Swift-based iOS apps and offers practical strategies to mitigate them.

Prerequisites

Before diving in, you’ll need:

• Working knowledge of Swift and iOS development.

• Access to Xcode.

• Basic understanding of how iOS apps communicate with servers.

• Familiarity with Terminal/command line basics.

The code examples are practical and explained step-by-step, making them accessible to junior developers while still offering value to experienced ones looking to strengthen their app's security.

What we’ll cover:

• What are the Most Prevalent Security Traps in Swift iOS Applications?
  • 1. Insecure Data Storage
  • 2. Weak Network Communication
  • 3. Improper Input Validation
  • 4. Hardcoding Secrets
  • 5. Insufficient Authentication and Authorization
  • 6. Insecure Logging and Error Handling
  • 7. Ignoring Code Obfuscation and Reverse Engineering
  • 8. Insecure Third-Party Libraries
  • 9. Insufficient Biometric and Multi-Factor Authentication
  • 10. Disregarding Periodic Security Testing

What are the Most Prevalent Security Traps in Swift iOS Applications?

Swift and iOS offer robust security features, but mistakes still happen. Following are the most common traps and how to fix them:

1. Insecure Data Storage

Among the most common mistakes developers make is having sensitive data stored insecurely. Passwords, tokens, or even individual user data can be left by accident in UserDefaults or local storage in unencrypted form.

While UserDefaults is convenient for small amounts of data, it is not secure for sensitive data as it is so easily accessible to attackers if the device is compromised.

How to Fix:

Use the Keychain Services API to securely store sensitive data. Keychain encrypts data and binds it to the device so that it can't be accessed by other unauthorized applications or users.

You can securely store credentials using libraries in Swift such as KeychainAccess or the built-in SecItemAdd and SecItemCopyMatching functions.

For example, this how you can store a user password in Keychain so as to ensure sensitive data is stored securely:

do {

try keychain.set("userPassword123", key: "userPassword")

} catch {

    print("Error saving to Keychain: \(error)")

}

Behind the scenes, here’s what happens when you call keychain.set("userPassword123", key: "userPassword") inside a KeychainManager class that uses Apple’s native Security framework for storage:

import Security

class KeychainManager {
 func set(_ value: String, key: String) throws {
     // 1. Convert string to Data
     guard let data = value.data(using: .utf8) else {
         throw NSError(domain: "KeychainManager", code: -1)
     }

     // 2. Build the query dictionary
     let query: [String: Any] = [
         // Store as password
         kSecClass as String: kSecClassGenericPassword,
         // Your app's bundle identifier
         kSecAttrService as String: "com.yourapp.keychain",
         // "userPassword"
         kSecAttrAccount as String: key,
         // "userPassword123" encrypted
         kSecValueData as String: data,
         kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlock
     ]
     // 3. Save to keychain (iOS encrypts it automatically)
     let status = SecItemAdd(query as CFDictionary, nil)
     // 4. Check if successful
     guard status == errSecSuccess else {
         throw NSError(domain: "KeychainManager", code: Int(status))
     }
 }
}

When this function runs, iOS converts the string value, such as "userPassword123", into encrypted binary data and stores it securely in the device’s Keychain database. The entry is saved under the provided key (for example, "userPassword"), and only your app can access it.

Behind the scenes, the Keychain leverages strong security features, including hardware-backed encryption using device-specific keys, optional biometric protection through Face ID or Touch ID, and app-level isolation to ensure that no other app can read or modify your stored credentials.

2. Weak Network Communication

Transmitting sensitive data over the network is another area prone to vulnerabilities. Using unencrypted HTTP connections exposes your app to man-in-the-middle (MITM) attacks, allowing attackers to intercept and modify data in transit.

The Problem: When data travels between your app and server over an insecure connection, attackers on the same network (like public Wi-Fi) can:

• Read sensitive information (passwords, personal data, payment details)

• Modify requests and responses

• Impersonate your legitimate server

How to Fix:

1. Always Use HTTPS
HTTPS encrypts all data in transit, making it unreadable to attackers. iOS's App Transport Security (ATS) enforces this by blocking insecure HTTP connections by default:

// ❌ INSECURE - HTTP connection (blocked by ATS by default)
let url = URL(string: "http://api.example.com/login")

// ✅ SECURE - HTTPS connection
let url = URL(string: "https://api.example.com/login")

You’ll want to avoid adding ATS exceptions to your Info.plist unless absolutely necessary. If a third-party API only supports HTTP, contact them to upgrade or find a more secure alternative.

2. Implement Certificate Pinning (Advanced Protection)

Even with HTTPS, your app could still be vulnerable to sophisticated MITM attacks. An attacker could install a fraudulent certificate on a user's device (through malware or social engineering), for example, and intercept HTTPS traffic that appears valid. The attacker's fake certificate would be trusted by the device, allowing them to decrypt and read "secure" communications.

Certificate pinning solves this by making your app trust only your specific server's certificate, rejecting all others – even if they're otherwise valid.

How Certificate Pinning Works:

Your app stores the expected certificate (or its public key hash) and validates it during each connection:

class SecureNetworkManager: NSObject, URLSessionDelegate {

    // Store your server's certificate hash
    // Get this by running: openssl x509 -in certificate.crt -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64
    private let expectedPublicKeyHash = "YOUR_CERTIFICATE_HASH_HERE"

    func urlSession(
        _ session: URLSession,
        didReceive challenge: URLAuthenticationChallenge,
        completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void
    ) {
        // Step 1: Check if this is a server trust challenge (certificate validation)
        guard challenge.protectionSpace.authenticationMethod == NSURLAuthenticationMethodServerTrust,
              let serverTrust = challenge.protectionSpace.serverTrust
        else {
            // Not a certificate challenge; use default handling
            completionHandler(.performDefaultHandling, nil)
            return
        }

        // Step 2: Validate that the server's certificate matches our pinned certificate
        if isValidServerTrust(serverTrust) {
            // Certificate matches - proceed with the connection
            completionHandler(.useCredential, URLCredential(trust: serverTrust))
        } else {
            // Certificate doesn't match - reject the connection to prevent MITM attack
            completionHandler(.cancelAuthenticationChallenge, nil)
        }
    }

    // Validates the server's certificate against our pinned hash
    private func isValidServerTrust(_ serverTrust: SecTrust) -> Bool {
        // Extract the server's certificate
        guard let serverCertificate = SecTrustGetCertificateAtIndex(serverTrust, 0) else {
            return false
        }

        // Get the public key from the certificate
        let serverPublicKey = SecCertificateCopyKey(serverCertificate)
        guard let publicKey = serverPublicKey else {
            return false
        }

        // Convert the public key to data and hash it
        var error: Unmanaged<CFError>?
        guard let publicKeyData = SecKeyCopyExternalRepresentation(publicKey, &error) as Data? else {
            return false
        }

        // Hash the public key using SHA-256
        let publicKeyHash = SHA256.hash(data: publicKeyData)
        let publicKeyHashString = Data(publicKeyHash).base64EncodedString()

        // Compare with our expected hash
        return publicKeyHashString == expectedPublicKeyHash
    }
}

What this code does, step-by-step:

1. urlSession(_:didReceive:completionHandler:) – This method is called whenever your app makes an HTTPS connection. iOS asks: "Should I trust this server's certificate?"

2. Check authentication method – We verify this is a server trust challenge (certificate validation), not some other type of authentication.

3. Validate the certificate – We call isValidServerTrust(), which:

   • Extracts the server's certificate from the connection

   • Gets the public key from that certificate

   • Hashes the public key using SHA-256

   • Compares the hash to our stored, expected hash

4. Make a decision:

• If hashes match, then the server is legitimate. Proceed with .useCredential.

• If hashes don't match, we have a potential MITM attack. Cancel with .cancelAuthenticationChallenge.

So how does this prevent MITM attacks? Even if an attacker installs a fraudulent certificate on the user's device and intercepts traffic, their certificate's hash won't match your pinned hash. Your app will reject the connection, preventing the attacker from decrypting your traffic.

3. Additional Protection: Recommend a VPN on Public Wi-Fi

You can also recommend that users connect through a VPN when on public Wi-Fi for an added layer of security, and provide guidance on how to use a VPN effectively to keep their data safe.

For developers, maintaining strong app security also depends on having a well-optimized system, learning how to speed up a slow Mac can help ensure smoother builds, faster testing, and a more secure overall development workflow.

3. Improper Input Validation

Some developers neglect correct input validation, leading to a number of vulnerabilities including SQL injection, remote code execution, and data corruption.

While Swift has strong typing support, some developers don’t sanitize user input or API responses. Incorporating real-time API email validation ensures that users provide legitimate, properly formatted email addresses before they are stored or processed, reducing both security risks and data quality issues.

How to Fix:

Input validation is your first line of defense against malicious data. Here's how to protect your iOS applications:

1. Validate User Input with Patterns

Always validate user input using regular expressions or predefined patterns before processing. For example, when accepting email addresses:

func isValidEmail(_ email: String) -> Bool {
    let emailRegex = "[A-Z0-9a-z._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,64}"
    let emailPredicate = NSPredicate(format: "SELF MATCHES %@", emailRegex)
    return emailPredicate.evaluate(with: email)
}

// Only accept properly formatted data
guard isValidEmail(userEmail) else {
    // Reject invalid input
    return
}

This ensures that only properly formatted data is accepted, preventing malformed or malicious input from entering your system.

2. Sanitize API Responses

Never trust external data. Always validate and sanitize API responses before using them:

if let userAge = apiResponse["age"] as? Int,
   userAge >= 0 && userAge <= 150 {
    // Safe to use
    user.age = userAge
} else {
    // Handle invalid data appropriately
    throw ValidationError.invalidAge
}

3. Use Parameterized Queries (Most Critical)

The most dangerous mistake is building database queries through string concatenation. Consider this vulnerable code:

// ❌ NEVER DO THIS - Vulnerable to SQL Injection
let username = userInput  // Could be: "admin' OR '1'='1"
let query = "SELECT * FROM users WHERE username = '\(username)'"
database.execute(query)

If a malicious user enters admin' OR '1'='1 as their username, the query becomes:

SELECT * FROM users WHERE username = 'admin' OR '1'='1'

This would return all users in the database instead of just one, potentially exposing sensitive data. The secure solution uses parameterized queries:

// ✅ SAFE - Using parameterized queries
let query = "SELECT * FROM users WHERE username = ?"
database.execute(query, withArgumentsIn: [username])

In this approach, the ? is a placeholder that the database treats as a parameter, not as part of the SQL command. The username value is passed separately in the withArgumentsIn array.

This means that even if a user tries to inject SQL code like admin' OR '1'='1, the database will treat the entire string as a literal username to search for – not as executable SQL code. The database engine automatically escapes any special characters, completely eliminating the risk of SQL injection.

By separating the query structure from the data, parameterized queries ensure that user input can never alter the intended logic of your SQL statements.

4. Hardcoding Secrets

API keys, credentials, or private tokens hard-coded in the source code is another serious security mistake. Attackers can extract such secrets from compiled binaries using reverse-engineering tools, especially for apps released to the public.

Once exposed, these credentials can be used to access your backend services, potentially leading to data breaches or unauthorized charges.

The Problem – Hardcoded Secrets:

// NEVER DO THIS
class APIClient {
    private let apiKey = "1234567890abcdef"
    private let secretToken = "sk_live_51H..."

    func makeRequest() {
        // These secrets are embedded in your binary
        let headers = ["Authorization": "Bearer \(apiKey)"]
    }
}

How to Fix:

Never store sensitive credentials directly in your code. Here are secure alternatives:

Solution 1: Fetch Secrets from Backend at Runtime

The most secure approach is to never store secrets on the client at all. Instead, authenticate users and let your backend make authorized API calls:

class APIClient {
    private var sessionToken: String?

    // User logs in and receives a temporary session token
    func authenticateUser(email: String, password: String) async throws {
        let response = try await backend.login(email: email, password: password)
        // Store only a temporary, user-specific session token
        self.sessionToken = response.sessionToken
    }

    // Backend handles the actual API calls with the real API key
    func fetchUserData() async throws -> UserData {
        guard let token = sessionToken else {
            throw AuthError.notAuthenticated
        }

        // Your backend receives this request, validates the session token,
        // then uses its own API keys to fetch data from third-party services
        return try await backend.getUserData(sessionToken: token)
    }
}

How this works:

Your app never knows the actual API keys. When a user needs data, your app sends a request to your own backend server with a session token. Your backend validates the token, then uses its own securely stored API keys to make the actual third-party API calls. This way, the real secrets never leave your server.

Solution 2: Environment Variables or Config Files (Development Only)

For development environments, use .xcconfig files that are excluded from version control:

// Secrets.xcconfig (add to .gitignore!)
API_KEY = your_dev_api_key_here
API_SECRET = your_dev_secret_here

// Access in your code through Info.plist
class Config {
    static let apiKey: String = {
        guard let key = Bundle.main.object(forInfoDictionaryKey: "API_KEY") as? String else {
            fatalError("API_KEY not found in configuration")
        }
        return key
    }()
}

Important: This approach is only suitable for non-production environments! Never ship production API keys with your app, even in config files.

5. Insufficient Authentication and Authorization

Relying on client-side authentication and authorization checks is risky. Attackers can cause the app to bypass these checks and access in an unauthorized way by brute forcing or tampering with the app/runtime.

How to Fix:

• Do authentication and authorization on the server side instead of the client-side.

• Use JWT (JSON Web Tokens) or OAuth 2.0 for authenticated user login.

• Token expiration and refresh logic needs to be implemented in order to minimize the likelihood of token theft.

Example: Securely sending JWT:

let request = URLRequest(url: apiURL)

request.setValue("Bearer \(jwtToken)", forHTTPHeaderField: "Authorization")

6. Insecure Logging and Error Handling

Extensive and insecure logging practices, as well as uncaught exceptions, can lead to the exposure of sensitive information including usernames, passwords, and API keys.

How to Fix:

• Log sensitive information carefully.

• Implement controlled error management and provide the minimum amount of information in user-presented messages.

• Implement secure logging libraries that mask or encrypt personal data.

do {
    try someRiskyOperation()
} catch {
    // Log error securely
    Logger.log("Operation failed: \(error.localizedDescription)")
}

7. Ignoring Code Obfuscation and Reverse Engineering

Swift binaries can be reverse-engineered to expose sensitive business logic, algorithms, or hidden secrets. Attackers use tools like Hopper Disassembler, class-dump, or IDA Pro to decompile your app and analyze how it works internally. This risk is often underestimated, especially for smaller apps, but any app can be a target.

This means that when you compile a Swift app, the resulting binary contains:

• Class names and method signatures

• String literals (URLs, error messages, keys)

• The structure of your code logic

• Algorithm implementations

An attacker can extract this information and use it to understand your app's authentication flow and bypass it, copy your proprietary algorithms, find hardcoded API endpoints or keys you thought were "hidden", discover premium features to unlock without paying, and so on.

Why It's Bad – Real Example:

Let's imagine you have a premium feature check in your app:

class FeatureManager {
    func isPremiumUser() -> Bool {
        // Check if user has premium access
        let hasSubscription = UserDefaults.standard.bool(forKey: "premium_unlocked")
        return hasSubscription
    }

    func unlockPremiumFeature() {
        guard isPremiumUser() else {
            showPaywall()
            return
        }
        // Show premium content
        showPremiumContent()
    }
}

An attacker could reverse-engineer your app and discover that the method isPremiumUser() controls access, and that it simply checks a UserDefaults key called premium_unlocked. They would then know that they could use runtime manipulation tools to set this value to true, bypassing your paywall entirely.

How to Fix:

1. Use Swift Compiler Optimizations

Enable optimization flags that strip debugging symbols and make the binary harder to read:

// In your build settings:
// - Set "Optimization Level" to "-O" (or -Osize) for release builds
// - Enable "Strip Debug Symbols During Copy" = YES
// - Set "Strip Style" to "All Symbols"

This removes function names and makes the compiled code less readable – though class/method names remain partially visible.

2. Use Symbol Obfuscation Tools

Tools like SwiftShield can rename your classes, methods, and properties to meaningless names:

// Before obfuscation (readable to attackers):
class FeatureManager {
    func isPremiumUser() -> Bool { ... }
}

// After obfuscation (harder to understand):
class a7f3b2 {
    func x9k2m() -> Bool { ... }
}

While this doesn't prevent reverse engineering, it makes it significantly harder for attackers to understand what the code does.

3. Move Sensitive Logic to the Server (Best Practice)

Instead of checking premium status locally, verify it server-side:

// ✅ Secure approach - Server validates everything
class FeatureManager {
    func unlockPremiumFeature() async {
        do {
            // Server checks if user truly has premium access
            let hasAccess = try await backend.verifyPremiumAccess(userId: currentUserId)

            if hasAccess {
                showPremiumContent()
            } else {
                showPaywall()
            }
        } catch {
            // Handle error
            showPaywall()
        }
    }
}

How this works:

Your backend maintains the source of truth about premium access. Even if an attacker reverse-engineers your app and tries to bypass the check, the server will reject unauthorized requests. The app becomes just a UI layer, while all critical decisions happen server-side – where attackers can't manipulate them.

The key principle is to assume your app code is public: never rely on client-side checks for security-critical operations like payments, access control, or authentication. Use obfuscation to make reverse engineering harder, but ultimately move sensitive logic to your secure backend

8. Insecure Third-Party Libraries

Third-party libraries are at risk if they are hacked or outdated. Developers might inadvertently prioritize app functionality over potential security risks from dependencies, and ETL tools can further help by streamlining the monitoring and processing of dependency-related data to identify vulnerabilities more efficiently.

On a broader scale, implementing strong data center security practices ensures that even if third-party components introduce risks, the underlying infrastructure remains resilient against attacks.

How to Fix:

• Use only high-quality, well-maintained libraries.

• Update dependencies and monitor CVEs (Common Vulnerabilities and Exposures).

• Audit library code if it handles sensitive data.

9. Insufficient Biometric and Multi-Factor Authentication

Most applications rely on passwords alone, which are vulnerable to being hacked. Enabling biometrics like Face ID or Touch ID enhances security for users.

How to Fix:

• Tie LocalAuthentication framework for biometric authentication.

• Combine biometrics with server-based authentication for multifactor authentication (MFA).

import LocalAuthentication

let context = LAContext()

var error: NSError?

if context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &error) {

    context.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics,

                        localizedReason: "Access your account") { success, authError in

        DispatchQueue.main.async {

         if success {

                // Proceed securely

         } else {

                // Handle failure (authError may contain the reason)

                print("Authentication failed: \(authError?.localizedDescription ?? "Unknown error")")

         }

     }

}

} else {

// Biometrics not available, check error for details

    print("Biometrics unavailable: \(error?.localizedDescription ?? "Unknown error")")

}

10. Disregarding Periodic Security Testing

Apps, despite following best practices during development, often contain unexplored vulnerabilities that emerge from complex interactions, third-party dependencies, or newly discovered attack vectors. Regular security testing is absolutely essential to discover these vulnerabilities before attackers exploit them.

Security testing should happen at multiple stages, using accessible tools and practices:

1. Automated security scans: Run automatically with every build to catch common issues.

2. Self-conducted code audits: Regular security-focused reviews of your own code using established guidelines.

3. Vulnerability scanning tools: Use free tools like MobSF to analyze your app for security flaws.

4. Dependency audits: Checking third-party libraries for known security vulnerabilities.

How to Fix:

1. Implement Automated Security Scans in CI/CD

Integrate security scanning tools into your continuous integration pipeline so every code change is automatically checked:

# Example: GitHub Actions workflow for automated security scanning
name: Security Scan

on: [push, pull_request]

jobs:
  security-scan:
    runs-on: macos-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Run MobSF Security Scan
        run: |
          # Mobile Security Framework - scans for common vulnerabilities
          docker run -v $(pwd):/app opensecurity/mobile-security-framework-mobsf

      - name: Dependency Vulnerability Check
        run: |
          # Check CocoaPods/SPM dependencies for known CVEs
          brew install dependency-check
          dependency-check --scan ./Podfile.lock --format JSON

      - name: Secret Detection
        run: |
          # Detect accidentally committed secrets
          brew install truffleHog
          truffleHog filesystem . --json

      - name: Fail build on critical issues
        run: |
          if grep -q "CRITICAL" security-report.json; then
            echo "Critical security issues found!"
            exit 1
          fi

Automated scans check for:

• Hardcoded API keys, tokens, or passwords

• Insecure network configurations (allowing HTTP instead of HTTPS)

• Weak cryptographic algorithms

• Known vulnerabilities in third-party libraries

• Improper SSL/TLS certificate validation

• Insecure data storage (storing sensitive data in UserDefaults)

• Excessive app permissions

Example output from an automated scan:

Security Scan Results:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[CRITICAL] Hardcoded API Key Found
  File: APIClient.swift:15
  Issue: API key "sk_live_abc123..." detected in source code

[HIGH] Insecure HTTP Connection
  File: NetworkManager.swift:42
  Issue: App allows cleartext HTTP traffic to api.example.com
  Fix: Enforce HTTPS or add exception to Info.plist if required

[MEDIUM] Weak Encryption Algorithm
  File: DataEncryption.swift:28
  Issue: Using MD5 for hashing (cryptographically broken)
  Fix: Use SHA-256 or better

[LOW] Outdated Dependency
  Library: Alamofire 4.2.0
  Issue: Known vulnerability CVE-2021-12345
  Fix: Update to version 5.6.0 or later
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Build Failed: 2 critical issues must be fixed before deployment

2. Use MobSF (Mobile Security Framework) for Vulnerability Analysis

MobSF is a free, automated tool that analyzes your iOS app for security issues:

# Install and run MobSF locally
docker pull opensecurity/mobile-security-framework-mobsf
docker run -it -p 8000:8000 opensecurity/mobile-security-framework-mobsf

# Upload your .ipa file through the web interface at localhost:8000
# MobSF will analyze and provide a detailed security report

What MobSF checks:

• Binary analysis for hardcoded secrets

• Insecure data storage patterns

• Weak cryptographic implementations

• Insecure network connections

• Code quality and security best practices

• Compliance with security standards

3. Conduct Regular Code Audits Using OWASP MSTG

Use the OWASP Mobile Security Testing Guide as a checklist to audit your own code:

// Example: Following OWASP MSTG recommendations for secure storage
class SecureStorage {
    // ❌ Insecure - UserDefaults is not encrypted
    func saveTokenInsecurely(_ token: String) {
        UserDefaults.standard.set(token, forKey: "authToken")
    }

    // ✅ Secure - Using Keychain as OWASP recommends
    func saveTokenSecurely(_ token: String) throws {
        let data = token.data(using: .utf8)!
        let query: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrAccount as String: "authToken",
            kSecValueData as String: data,
            kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlockedThisDeviceOnly
        ]

        SecItemDelete(query as CFDictionary)
        let status = SecItemAdd(query as CFDictionary, nil)

        guard status == errSecSuccess else {
            throw StorageError.saveFailed
        }
    }
}

OWASP MSTG Checklist for Self-Audit:

• [ ] Are all sensitive data encrypted at rest?

• [ ] Is HTTPS enforced for all network calls?

• [ ] Are certificates properly validated?

• [ ] Is sensitive data excluded from logs?

• [ ] Are API keys and secrets not hardcoded?

• [ ] Is user input validated and sanitized?

• [ ] Are authentication tokens stored securely in Keychain?

4. Automated Dependency Scanning

Monitor your dependencies continuously for newly discovered vulnerabilities:

# For CocoaPods projects
gem install cocoapods-audit
pod audit

# For Swift Package Manager
# Use GitHub Dependabot (free for public repos) or
brew install swift-outdated
swift-outdated

And set up automated alerts with these tools:

• GitHub Dependabot: Automatically creates PRs when vulnerable dependencies are detected (free)

• Snyk: Free tier available for open-source projects

• OWASP Dependency-Check: Free command-line tool

Conclusion

Developing secure iOS apps using Swift is all about forward-thinking. You should do all you can to avoid these common errors, like insecure storage of data, poor network communication, hard-coded secrets, or poor authentication.

Using Keychain for confidential information, requiring HTTPS, input validation, and multifactor authentication are all steps that decrease risk.

Regular testing for security vulnerabilities and limiting third-party library use can also further enhance your app's security.

Security is a continuous responsibility. Swift provides tools, but the developers need to apply those tools carefully. Security being tackled right from the start protects users' information, creates trust, and protects the reputation of the application.

With the release of Swift 6 and its new Embedded Swift compilation mode, developers now have access to a modern, memory-safe, and performant alternative that’s tailored specifically for resource-constrained systems.

While languages like Rust have also emerged to address these issues, Embedded Swift brings the clarity and safety of Swift to microcontroller environments, without giving up on determinism, binary size, or hardware access.

This article introduces Embedded Swift and explores how it compares to traditional C/C++ development. We’ll cover its key features, programming and memory models, how to set up the toolchain for STM32 microcontrollers, and how to link Swift with existing C drivers.

Along the way, we’ll examine performance trade-offs, growing ecosystem support, and the broader industry movement toward memory-safe languages. As I hope you’ll see, Swift is a serious contender in the future of embedded development.

Prerequisites

To get the most out of this article, you should have a basic understanding of programming in Swift and C. Familiarity with embedded hardware platforms and firmware development concepts will also be helpful.

If you're new to embedded systems, consider reviewing this introductory guide to embedded firmware to build foundational knowledge before diving into Embedded Swift.

Scope

This article is intended as a practical introduction to Embedded Swift. It covers:

• An overview of Embedded Swift and its key language features

• Swift’s programming and memory model in an embedded context

• Setting up the Embedded Swift toolchain on macOS for STM32 microcontrollers

• Interoperability with C code and linking to existing low-level drivers

• A look at memory and instruction-level performance

• Future directions and use cases for Embedded Swift

Note that this article does not provide a full tutorial on the Swift language itself. While the primary focus is on STM32, similar principles apply to other supported platforms such as ESP32, Raspberry Pi Pico, and nRF52.

Table of Contents:

• What is Swift? What is Embedded Swift?

• Swift Programming Model

• Swift Memory Management

• Memory and Instruction Cycle Comparison

• How to Setup Embedded Swift

• C-Swift Linkages:

• Future Work

• Conclusion

What is Swift? What is Embedded Swift?

Swift is a modern programming language developed by Apple that combines the performance of compiled languages with the expressiveness and safety of modern language design. While Swift was originally created for iOS and macOS development, it has evolved into a powerful general-purpose language used in server-side development, systems programming, and increasingly, embedded systems.

Embedded Swift is a special compilation mode introduced in Swift 6 that brings the benefits of Swift to resource-constrained platforms like microcontrollers. It lets developers use a safe, high-level language while still producing compact, deterministic, and performant binaries suitable for embedded applications.

Key Features of Swift

Embedded Swift retains many of the powerful language features that make Swift an attractive alternative to C/C++ in embedded development:

Type Safety: Swift uses a strong static type system, which prevents many programming errors at compile time. Unlike C, where type mismatches can result in undefined behavior, Swift ensures all types are used correctly before code even runs.

Strict Type Checking: Swift doesn't allow implicit type conversions that could lose data or cause unexpected behavior. For example:

// This won't compile in Swift
let integer: Int = 42
let decimal: Double = 3.14
let result = integer + decimal  // Error: Cannot convert value of type 'Int' to expected argument type 'Double'

// You must be explicit about conversions
let result = Double(integer) + decimal  // Correct

Non-nullable Types by Default: In C, pointers can be null by default, which introduces risk. In Swift, variables cannot be nil unless explicitly marked as optionals:

var name: String = "John"
name = nil  // Compile error - String cannot be nil

var optionalName: String? = "John"
optionalName = nil  // This is allowed

Memory Safety via ARC (Covered in detail later):

Swift manages memory automatically using Automatic Reference Counting (ARC). Unlike manual memory management in C/C++, ARC handles object lifecycles efficiently without unpredictable garbage collection pauses. We'll cover ARC and its impact in embedded contexts in a dedicated section later.

Modern Syntax:
Swift's syntax is clean, consistent, and designed for readability. It supports modern paradigms including:

• Functional programming (map, filter, reduce)

• Generics (type-safe abstractions)

• Protocol-Oriented Programming (discussed in the next section)

These features allow you to write more expressive and maintainable code compared to procedural C or inheritance-heavy C++.

Performance:
Swift is designed to perform on par with C++ in many scenarios. Optimizations such as inlining, dead code elimination, and static dispatch help ensure that high-level abstractions don’t compromise performance. In embedded mode, Swift disables features like runtime reflection and dynamic dispatch to further reduce overhead.

To fully leverage Swift for embedded development, it's important to understand its programming model. Unlike C’s procedural approach or C++’s class-heavy design, Swift promotes protocol-oriented programming and composition, which offers both flexibility and safety in embedded system design.

Swift Programming Model

Swift embraces a multi-paradigm programming model that blends object-oriented, functional, and protocol-oriented programming, all underpinned by strong type safety and memory safety.

For embedded developers coming from C or C++, this model may feel different at first. But it provides a more modular and testable way to build complex systems, something especially valuable in embedded applications where hardware abstraction and strict reliability are critical.

Protocol-Oriented Programming (POP)

Swift emphasizes protocols over inheritance, encouraging developers to define behaviors through protocols and implement them using value types like struct and enum, rather than relying heavily on classes.

This philosophy favors composition over inheritance, allowing you to build complex functionality by combining smaller, well-defined components.

Key Concepts:

• protocol defines required behavior.

• Protocol extensions provide default behavior.

• Prefer value semantics using struct.

Example:

protocol Speakable {
    func speak()
}

extension Speakable {
    func speak() {
        print("Default sound")
    }
}

struct Dog: Speakable {
    func speak() {
        print("Woof!")
    }
}

Embedded Swift uses protocols with static dispatch. With static dispatch, the compiler knows the exact memory address of the function to call and can generate a direct jump instruction. There's no runtime lookup, no indirection, and no uncertainty.

Why POP Matters for Embedded Systems

First, you get flexible hardware extraction. Protocols make it easy to define interfaces for hardware components, allowing for mock implementations during testing or platform-specific variations.

Second, you have nice low overhead. Embedded Swift uses static dispatch for protocols, meaning there’s no runtime lookup, and calls are resolved at compile time for maximum performance.

Also, struct and enum types avoid heap allocations, making code more efficient and predictable in low-memory environments.

Now that we’ve explored how Swift’s programming model enables safer and more modular embedded code, let’s turn to another critical piece of the puzzle: memory management. Swift’s use of Automatic Reference Counting (ARC) replaces manual memory handling and offers important benefits, and tradeoffs, for embedded systems.

Swift Memory Management

One of Swift’s most impactful features, especially in the context of embedded systems, is its use of Automatic Reference Counting (ARC) for memory management. Unlike C/C++, where memory must be manually allocated and freed using malloc and free, Swift automates this process while maintaining deterministic performance.

This automation significantly reduces the risk of common memory-related bugs like leaks, dangling pointers, or use-after-free errors, all of which are notorious in low-level C code.

How ARC works

Swift supports ARC not only for the Cocoa Touch API's but for all APIs, providing a streamlined approach to memory management. Unlike garbage collection systems that can cause unpredictable pauses, ARC works deterministically at compile time and runtime to manage memory.

ARC automatically tracks and manages the lifetime of objects in memory based on how many references point to them.

• Reference Counting: Every object has a counter that tracks how many strong references point to it.

• Retain / Release: The compiler inserts retain and release calls automatically during assignment and deinitialization.

• Immediate Deallocation: When the reference count reaches zero, the object is deallocated immediately.

• Deterministic: Unlike garbage collectors, ARC doesn’t introduce unpredictable pauses or runtime scanning.

Swift offers multiple reference types to give you precise control over memory behavior and prevent cycles:

Strong References (default)

• Keeps the referenced object alive.

• Used in most cases.

class MotorController {
    var sensor: SensorData?  // Strong reference

    func updateReading(newData: SensorData) {
        self.sensor = newData  // Previous sensor data automatically deallocated
    }
}

Weak References

• Used to break reference cycles (especially in two-way object relationships).

• Automatically becomes nil when the referenced object is deallocated.

class Device {
    var controller: MotorController?

    deinit {
        print("Device deallocated")
    }
}

class MotorController {
    weak var device: Device?  // ← Weak reference breaks the cycle

    deinit {
        print("MotorController deallocated")
    }
}

func breakCycle() {
    let device = Device()
    let controller = MotorController()

    device.controller = controller
    controller.device = device  // ← This is now a weak reference

    // When this function ends, both objects are properly deallocated
}

breakCycle()
// Output:
// Device deallocated
// MotorController deallocated

Unowned References

• Non-optional version of weak.

• Assumes the object will never be deallocated while still in use.

• More lightweight than weak, but unsafe if misused.

class SensorSystem {
    unowned let controller: MotorController  // unowned reference

    init(controller: MotorController) {
        self.controller = controller
    }
}

class MotorController {
    var sensorSystem: SensorSystem?

    func setupSensors() {
        sensorSystem = SensorSystem(controller: self)
    }

    deinit {
        print("MotorController deallocated")
    }
}

func testUnowned() {
    let controller = MotorController()
    controller.setupSensors()
    // sensorSystem deallocates before controller ends
}

testUnowned()
// Output: MotorController deallocated

ARC Overhead in Embedded Systems

While ARC provides safety benefits, it does introduce some overhead compared to manual memory management:

Memory Overhead:

ARC-managed class instances in Swift typically include an additional 4 or 8 bytes to store reference count metadata, depending on the system architecture, 4 bytes on 32-bit systems and 8 bytes on 64-bit systems. This metadata allows the runtime to track how many active references exist to a given object and deallocate it when no references remain. When developers use weak or unowned references, the memory footprint increases further. These references require additional data structures, such as side tables or tracking mechanisms, to manage object liveness and cleanup. In the case of weak references specifically, Swift maintains zeroing weak reference tables that automatically null out pointers once the referenced object is deallocated, ensuring memory safety.

CPU Overhead:

ARC introduces some runtime overhead due to retain and release operations, which are inserted automatically during reference assignments. These operations involve incrementing or decrementing the reference count and are especially common in code that passes objects between functions or stores them in collections. To ensure thread safety, these updates are typically implemented using atomic operations, which add further instruction cycles. In complex object graphs, ARC may also engage in cycle detection and cleanup through the use of weak references to prevent memory leaks caused by strong reference cycles. While Swift's ARC provides deterministic and efficient memory management, it does so with both memory and CPU costs that developers should consider carefully, especially in performance-critical embedded systems.

Type Safety and Error Prevention

Swift's type system prevents many common errors that plague C/C++ programs:

• Buffer Overflows: Swift arrays are bounds-checked, preventing buffer overflow vulnerabilities that are common in C.

• Null Pointer Dereferences: Swift's optional types make null pointer dereferences impossible at compile time.

• Use After Free: Swift's ownership model prevents use-after-free errors that can cause crashes or security vulnerabilities.

Now that we’ve covered Swift's memory model and ARC behavior, let’s explore how it compares to C in terms of memory usage and instruction cycles, a crucial aspect when evaluating Embedded Swift for real-world deployment.

Memory and Instruction Cycle Comparison

Understanding the performance characteristics of Swift versus C is essential for embedded systems, where every instruction cycle and byte of memory matters. While Swift brings advantages like safety and expressiveness, these benefits come with certain trade-offs in terms of memory usage and runtime behavior that embedded developers must evaluate carefully.

Memory Management:

Swift uses Automatic Reference Counting (ARC) to manage memory. ARC tracks the number of references to each object and deallocates it when no references remain. This eliminates the need for explicit free() calls but introduces overhead.

C, in contrast, uses manual memory management. Developers allocate memory using malloc and release it using free, or rely on the stack for most short-lived data.

The table below provides the memory management comparison between Swift and C:

Swift ensures safety through deterministic cleanup and predictable memory usage. But this comes at the cost of added memory and CPU overhead.

C’s approach offers complete control over memory layout and minimal runtime cost, but increases the risk of memory leaks and fragmentation without disciplined practices.

Instruction Cycle Analysis

The safety features in Swift, such as bounds checking, optional unwrapping, and ARC updates, translate into additional CPU instructions. While this can impact performance, the Swift compiler is aggressive about optimization in release builds. For example, inlining and ARC elision can remove much of the overhead in performance-critical paths.

C has no built-in safety checks, allowing it to generate highly efficient, predictable code. Developers can even use inline assembly for tight control over performance.

The table below provides the instruction cycle comparison between Swift and C:

Although Swift inserts extra instructions for safety, much of this cost can be mitigated through compiler optimization.

C has no such features by default, making it ideal for applications where performance must be tightly controlled and the developer is willing to take full responsibility for safety.

Instruction Count Comparison: Swift vs C Loop Performance

When evaluating Swift and C for embedded use, it's helpful to analyze instruction-level performance on basic operations, such as a loop that processes an array of floating-point numbers. This gives us a concrete sense of the computational cost of each language's safety and abstraction features.

Let’s consider a simple example: summing an array of Float values and returning the average. In Swift, the code uses a high-level for-in loop over an array:

Simple loop performance:

// Swift loop with safety checks
func processData(_ data: [Float]) -> Float {
    var sum: Float = 0.0
    for value in data {  // Iterator with bounds checking
        sum += value     // Safe arithmetic
    }
    return sum / Float(data.count)  // Safe division
}
// Estimated: ~8-10 instructions per iteration

Although elegant and safe, this loop includes several safety mechanisms:

1. Bounds checking on every array access

2. Reference counting if data is passed as a reference type

3. Overflow protection in debug mode

4. Optional handling or runtime checks if data might be empty

These checks introduce runtime overhead, resulting in an estimated 8–10 instructions per iteration on most platforms (depending on optimization level and target architecture). In release builds, Swift aggressively inlines and strips redundant checks, but some level of abstraction cost remains, especially compared to raw memory access in C.

Now, compare that to its equivalent in C:

// C loop without safety checks
float process_data(float* data, int count) {
    float sum = 0.0f;
    for (int i = 0; i < count; i++) {  // Direct pointer arithmetic
        sum += data[i];                // Direct memory access
    }
    return sum / count;  // Direct division (no safety check)
}
// Estimated: ~4-5 instructions per iteration

This version performs direct memory access with pointer arithmetic, no bounds checks, and no type safety. The C code is lower-level, with fewer runtime checks, and compiles down to just 4–5 instructions per iteration, depending on the target CPU and compiler flags. It is lean and fast, ideal for cycles-per-instruction-critical scenarios.

The table below shows the comparison of single loop performance between Swift and C:

Now that we’ve compared Swift and C in terms of memory and cycle costs, let’s move into the practical side: how to set up Embedded Swift on an STM32 platform and get started with real-world development.

How to Setup Embedded Swift

In this section, we'll walk through how to configure and use Embedded Swift for development on STM32 microcontrollers. STM32 is a popular family of ARM Cortex-M–based microcontrollers, commonly used in industrial, consumer, and IoT applications.

Prerequisites

Required Software:

• Swift Development Snapshot (includes the Embedded Swift toolchain)

• Swiftly - Easiest way to manage and install swift toolchains

• Swiftc - Swift Compiler command-line tool

• Python3 - Required to run scripts to convert Mach-O to binary files

• Git (to clone sample repositories) like https://github.com/swiftlang/swift-embedded-examples

• A Unix-like development environment (macOS is currently best supported)

Target Hardware: This guide focuses on STM32 microcontrollers, which are widely used in embedded applications and have excellent community support.

This guide walks you through the full setup process, from installing the required Swift toolchain to flashing the final binary onto your board. We’ll begin by installing the Swift Development Snapshot using Swiftly, a simple command-line utility for managing Swift toolchains. From there, we’ll configure the build system, set up the correct board variant, customize the build script, and compile the Swift and C source code into a binary. Finally, we’ll flash the firmware onto the STM32 using standard tools

Install Swift Development Snapshot

The easiest way to install and manage Embedded Swift toolchains is by using the swiftly tool, which simplifies downloading and using Swift snapshots.

macOS Installation:

The below steps will help install the Swift embedded toolchain:

# Using Swiftly (Recommended)
curl -O https://download.swift.org/swiftly/darwin/swiftly.pkg
installer -pkg swiftly.pkg -target CurrentUserHomeDirectory
~/.swiftly/bin/swiftly init --quiet-shell-followup
source "${SWIFTLY_HOME_DIR:-$HOME/.swiftly}/env.sh"

# Install and use development snapshot
swiftly install main-snapshot
swiftly use main-snapshot

# Verify installation
swift --version

You can clone this Github example repository:

git clone https://github.com/swiftlang/swift-embedded-examples.git 
cd swift-embedded-examples/projects/stm32-blink

The stm32-blink contains:

• Swift code that toggles GPIOs

• A C startup file with vector table

• A build.sh script that uses swiftc, clang, and a custom linker setup

Setup the STM32 Board

Tell the build script which STM32 board is being used:

export STM_BOARD=STM32F746G_DISCOVERY

You can add your own board variant by defining the appropriate memory map and compiler flags in the script.

Modify build.sh (Optional)

Ensure the script correctly locates the following:

• swiftc: should point to the toolchain you installed with Swiftly

• clang: can be macOS’s default Clang

• libBuiltin.a, crt0.s, and macho2bin.py: used to provide minimal runtime support and convert output to flashable binaries

If needed, update these paths:

SWIFT_EXEC=${SWIFT_EXEC:-$(swiftly which swiftc)}
CLANG_EXEC=${CLANG_EXEC:-$(xcrun -f clang)}
PYTHON_EXEC=${PYTHON_EXEC:-$(which python3)}

Ensure the linker flags match your target’s flash and RAM sizes.

Build and Flash the Project:

Run:

./build.sh

This compiles Swift and C code, links them, and produces a blink.bin file.

If successful, you’ll see:

.build/blink.bin  # ready to flash Step 6: Flash the Firmware to STM32

Use ST-Link tools or openocd to flash your board. Example using st-flash:

brew install stlink
st-flash write .build/blink.bin 0x8000000

You should now see an LED blinking.

Here’s a more detailed step by step approach to writing a bare metal code on STM32. For comprehensive installation guides covering other platforms (Raspberry Pi Pico, ESP32, nRF52), detailed IDE configuration, troubleshooting, and advanced examples, you can check out the official documentation:

• Complete Setup Guide: Install Embedded Swift

• Platform Examples: Swift Embedded Examples Repository

• Getting Started Tutorial: Embedded Swift on Microcontrollers

Now that we’ve set up Embedded Swift and explored how to build and run an example project, let’s look at a critical real-world scenario: interfacing Swift with low-level C drivers.

C-Swift Linkages

In many embedded projects, low-level hardware drivers are written in C because of its close-to-metal control and widespread ecosystem support. Embedded Swift supports seamless interoperability with C, which lets you reuse existing C libraries and drivers, write hardware control logic in C, and implement higher-level application logic in Swift.

This hybrid model lets you combine Swift’s safety and productivity with C’s hardware-level control, with no runtime overhead or object translation.

Let’s walk through an example where a low-level sensor driver is implemented in C and the application logic is written in Swift.

C Header File (sensor_driver.h):

This C header file defines the public interface for a low-level sensor driver. It includes standard fixed-width integer types and declares four functions:

• sensor_init(): Initializes the hardware sensor

• sensor_read_temperature() and sensor_read_humidity(): Read raw sensor values

• sensor_delay_ms(): Delays execution for a given number of milliseconds

This interface acts as a bridge between Swift and C. Swift will link to these functions by name, no wrappers or bindings required.

#ifndef SENSOR_DRIVER_H
#define SENSOR_DRIVER_H

#include <stdint.h>

// Low-level sensor driver functions
void sensor_init(void);
uint32_t sensor_read_temperature(void);
uint32_t sensor_read_humidity(void);
void sensor_delay_ms(uint32_t milliseconds);

#endif

C Implementation (sensor_driver.c):

This implementation assumes the sensor is memory-mapped at a fixed address (0x40001000). Each register, temperature, humidity, and control, is accessed by offset from that base address.

The sensor_init() function writes 0x01 to the control register, presumably enabling or starting the sensor hardware.

The sensor_read_temperature() method and sensor_read_humidity() method reads from memory-mapped registers and return the raw ADC values from the sensor.

The sensor_delay_ms() method performs a simple busy-wait loop using nop (no-operation) instructions to approximate a delay. This is suitable for short, coarse-grained delays in bare-metal contexts.

#include "sensor_driver.h"

// Hardware register addresses
#define SENSOR_BASE_ADDR    0x40001000
#define TEMP_REG_OFFSET     0x00
#define HUMIDITY_REG_OFFSET 0x04
#define CONTROL_REG_OFFSET  0x08

void sensor_init(void) {
    // Initialize sensor hardware
    volatile uint32_t* control_reg = (volatile uint32_t*)(SENSOR_BASE_ADDR + CONTROL_REG_OFFSET);
    *control_reg = 0x01; // Enable sensor
}

uint32_t sensor_read_temperature(void) {
    volatile uint32_t* temp_reg = (volatile uint32_t*)(SENSOR_BASE_ADDR + TEMP_REG_OFFSET);
    return *temp_reg;
}

uint32_t sensor_read_humidity(void) {
    volatile uint32_t* humidity_reg = (volatile uint32_t*)(SENSOR_BASE_ADDR + HUMIDITY_REG_OFFSET);
    return *humidity_reg;
}

void sensor_delay_ms(uint32_t milliseconds) {
    // Simple delay implementation
    for (uint32_t i = 0; i < milliseconds * 1000; i++) {
        __asm__("nop");
    }
}

Swift Code Using C Driver:

To use these C functions from Swift, you declare them using @_silgen_name, which tells the Swift compiler to link directly to these symbol names at runtime.

The SensorController class encapsulates sensor-related logic. In its init() method, it calls the sensor_init() function defined in C to initialize the sensor hardware.

The readSensors() method reads the raw values from the C driver, converts them into human-readable units using helper functions, stores them internally, and returns the processed values.

The convertTemperature() and convertHumidity() conversion methods apply a basic linear formula to turn raw ADC values into temperature in Celsius and humidity in percentage, respectively. These formulas would be based on the specific sensor’s datasheet.

The checkThresholds() method applies simple threshold logic, a good example of where Swift’s readability and type safety shine. You could easily expand this logic to include error bounds, state machines, or alerts.

// Import C driver functions

/*
These declarations match the C function signatures exactly. 
They allow Swift to invoke the C functions as if they were native Swift functions 
— with zero overhead.
*/
@_silgen_name("sensor_init")
func sensor_init()

@_silgen_name("sensor_read_temperature")
func sensor_read_temperature() -> UInt32

@_silgen_name("sensor_read_humidity")
func sensor_read_humidity() -> UInt32

@_silgen_name("sensor_delay_ms")
func sensor_delay_ms(_ ms: UInt32)

// Swift sensor controller using C driver
class SensorController {
    private var lastTemperature: Float = 0.0
    private var lastHumidity: Float = 0.0

    init() {
        // Initialize the C driver
        sensor_init()
    }

    func readSensors() -> (temperature: Float, humidity: Float) {
        // Read raw values from C driver
        let rawTemp = sensor_read_temperature()
        let rawHumidity = sensor_read_humidity()

        // Convert raw values to meaningful units in Swift
        let temperature = convertTemperature(rawValue: rawTemp)
        let humidity = convertHumidity(rawValue: rawHumidity)

        // Store for comparison
        lastTemperature = temperature
        lastHumidity = humidity

        return (temperature: temperature, humidity: humidity)
    }

    private func convertTemperature(rawValue: UInt32) -> Float {
        // Convert raw ADC value to Celsius
        return (Float(rawValue) * 3.3 / 4095.0 - 0.5) * 100.0
    }

    private func convertHumidity(rawValue: UInt32) -> Float {
        // Convert raw ADC value to percentage
        return Float(rawValue) * 100.0 / 4095.0
    }

    func checkThresholds() -> Bool {
        // Swift logic for threshold checking
        let tempThreshold: Float = 25.0
        let humidityThreshold: Float = 60.0

        return lastTemperature > tempThreshold || lastHumidity > humidityThreshold
    }
}

// Main application loop
func main() -> Never {
    let sensorController = SensorController()

    while true {
        // Read sensors using Swift controller with C driver
        let readings = sensorController.readSensors()

        // Process data with Swift's type safety and expressiveness
        if sensorController.checkThresholds() {
            print("Warning: Temperature: \(readings.temperature)°C, Humidity: \(readings.humidity)%")
        } else {
            print("Normal: Temperature: \(readings.temperature)°C, Humidity: \(readings.humidity)%")
        }

        // Delay using C driver function
        sensor_delay_ms(1000) // 1 second delay
    }
}

The func main() is the main event loop standard for embedded systems. It creates the sensor controller, reads sensor data in a loop, checks thresholds, and prints results accordingly. The loop includes a delay (via the C driver) to avoid hammering the sensor continuously.

In an actual embedded context, instead of using print(), you might blink an LED, send UART messages, or log data to memory.

With Embedded Swift and C now working together, let’s explore what lies ahead. The next section outlines ongoing improvements, emerging use cases, and research directions that are shaping the future of Embedded Swift.

Future Work

Embedded Swift is still a young but rapidly evolving technology. Its modern language features, type safety, and performance make it an attractive option for embedded development, and ongoing work is expanding its capabilities, reach, and ecosystem.

Ongoing Improvements

Compiler Optimizations: The Swift compiler team is actively improving code generation for embedded targets, including:

• Reducing binary size

• Minimizing ARC overhead

• Improving static dispatch performance

Hardware Support: Embedded Swift can target a wide variety of ARM and RISC-V microcontrollers, which are popular for building industrial applications. Support for additional architectures is being developed.

Tooling Enhancements: Tooling support for Embedded Swift is still evolving, but several community-driven and open-source efforts are making development more accessible:

• Build Systems: The Swift Embedded Working Group provides example projects that adapt Swift Package Manager (SwiftPM) for cross-compilation. Custom linker scripts and build helpers are available for platforms like STM32 and nRF52.

• Debugging Support: Developers can debug Embedded Swift programs using existing tools like GDB or OpenOCD, provided the build includes appropriate debug symbols. While not yet officially streamlined, this approach enables step-through debugging on real hardware.

• IDE Integration: There is no official IDE support yet, but some developers use VSCode with Swift syntax highlighting and external build tasks. These setups are still manual but serve as early prototypes for embedded workflows.

Emerging Use Cases

There are a number of emerging use cases for embedded Swift. For example, Swift’s memory safety, type guarantees, and protocol-oriented design make it ideal for secure and scalable IoT devices, especially where firmware bugs could affect user safety or privacy.

The automotive sector is also exploring Swift for infotainment systems, driver assistance features, and safety-critical logic (where deterministic execution and safety matter).

Swift’s expressive syntax and compile-time safety make it suitable for industrial automation – think real-time control loops, sensor fusion systems, and edge devices in smart manufacturing.

It’s also useful for medical devices, as it aligns well with strict medical regulations around memory safety, type guarantees, and predictable resource usage.

Community and Ecosystem

Open Source Projects

The Swift Embedded working group maintains example repositories showcasing how to use Embedded Swift on microcontrollers such as STM32, nRF52, and ESP32. Early-stage libraries for UART, GPIO, and basic peripherals are emerging, though the ecosystem is still young compared to C or Rust.

Learning Resources

While Embedded Swift is not yet widely taught in formal curricula, community tutorials and exploratory projects (for example, Swift for Arduino) are lowering the barrier for hobbyists and independent learners. As tooling matures, educational adoption is likely to follow.

Industry Interest

Embedded Swift is beginning to draw attention from developers and companies looking for safer, more maintainable alternatives to C. Although large-scale adoption remains limited, use cases like rapid prototyping, IoT development, and internal experimentation are gaining traction.

Conclusion

Embedded Swift represents a major step forward in embedded programming. By combining the power and safety of Swift with the low-level control needed for microcontrollers, it offers an exciting alternative to traditional C and C++ development.

While C will remain essential for hardware-level programming and performance-critical paths, Swift brings compelling advantages to many embedded scenarios:

• Memory safety: Swift eliminates entire categories of bugs such as buffer overflows, use-after-free, and null pointer dereferencing.

• Type safety: Many logic errors are caught at compile time, long before they can cause runtime failures.

• Modern language features: Developers can use functional paradigms, generics, and protocol-oriented design even in embedded code.

• C interoperability: Swift works seamlessly with existing C libraries, allowing gradual adoption without rewriting low-level drivers.

• Developer productivity: Clear syntax, automatic memory management, and strong tooling lead to faster development and easier maintenance.

Government and regulatory bodies are increasingly encouraging or mandating the use of memory-safe programming languages to reduce vulnerabilities in critical software systems. For example:

• In 2022, the U.S. National Security Agency (NSA) recommended moving away from unsafe languages like C/C++ for new software projects, promoting memory-safe alternatives.

• In June 2025, the NSA and CISA released a joint Cybersecurity Information Sheet titled “Memory Safe Languages: Reducing Vulnerabilities in Modern Software Development”, which emphasized that memory safety flaws remain a persistent risk, and organizations should develop strategies to adopt memory-safe programming languages in new systems.

• The U.S. Cybersecurity and Infrastructure Security Agency (CISA) and NIST have echoed similar guidance in the context of national cybersecurity.

While these documents do not mention Swift explicitly, Swift's strong type system, ARC-based memory model, and compile-time safety guarantees align closely with the goals outlined in these recommendations. As such, it offers a practical, developer-friendly path toward safer embedded development.

Swift may not be the right fit for every embedded system. In applications where every byte of memory or instruction cycle is critical, real-time guarantees are hard requirements, or toolchain maturity is essential (for example, RTOS integration, static analyzers), C or Rust may still be preferred.

But in many modern embedded applications, especially those involving rapid prototyping, fast product iteration, safety-critical or maintainable firmware, and interoperability with existing C codebases, Swift offers a highly productive and safe development experience.

Embedded Swift is still maturing, but its momentum is undeniable. With ongoing compiler work, community-driven examples, and growing interest from developers, it’s poised to play a major role in the future of embedded systems.

Whether you're building an IoT device, a piece of industrial equipment, or a proof-of-concept wearable, Swift can help you write safer, more expressive firmware, without giving up performance or control.

Swift can be especially powerful during the prototyping phase, when the primary goal is to validate functionality quickly and safely. And with its increasing support for multiple hardware platforms, it offers a strong foundation for bringing modern software development practices to the embedded world.

For many app developers, including me, writing the networking layer of an application is a familiar and tedious process. You write and test your first call and after that, it involves a repetitive cycle of tasks.

This is how it would look in the case of Swift:

1. You create a URLSession Instance.

2. You create a URLRequest Object.

3. You create the @Codable models to match the expected input and output from the server.

You do the above steps for each API endpoint you have on your backend that your app uses. Not only is this process time-consuming and not challenging for developers, it’s also error prone.

In the above case, if there was a minor change in the backend API – perhaps a renamed field or a new property – this would lead to the app potentially breaking. But you wouldn’t know this until you shipped it to QA or in a worse case, your consumer. This is where the OpenAPI Specification emerges as a modern, robust solution.

In this tutorial, you’ll learn what OpenAPI is and how it can help make your development process better. After that, we’ll implement OpenAPI by creating a small SwiftUI app and using OpenAPI methodologies to interface with the JSONPlaceholder API. Let’s get started.

Who is This Guide For?

This guide is intended both for new developers looking for best practices and for experienced developers looking to implement or learn more about the OpenAPI Specification. Let’s get into it.

Table of Contents

• What is OpenAPI and Why Should You Care?

  • Benefits for Swift (iOS) Developers

• A Practical Guide to Implementing This Solution

  • Step 1: Create a good openapi.yaml file (the specification)

  • Step 2: Set up your project

  • Step 3: Write a wrapper

  • Step 4: Call the wrapper and display the data

• Potential Pitfalls

  • Verbose or ugly generated code

  • Large Specs and Performance Issues

  • Unsupported Spec Features

• Conclusion: Embrace Spec-Driven Development

What is OpenAPI and Why Should You Care?

At its core, the OpenAPI Specification provides a standard, language-agnostic interface for describing RESTful APIs. This specification, once populated, allows both humans and computers to discover and understand the capabilities of a service without needing to access the source code or the network requests.

The power of OpenAPI is that it acts as a formal contract between different parts of the system. This contract helps both frontend and backend programmers by removing ambiguity during design process. This also has added benefit of using code generators to generate boiler-plate code both on backend and on the client ( which we will also discuss today ).

Traditionally when you want to create a new API in a team, either the PM, the frontend engineer, or the backend engineer takes it upon themselves to request it. Then the backend team builds it and documents it. This in turn is used by the front end team to use the API.

Some Requester → Backend Team → Documentation → Frontend Team

If you’re using OpenAPI, when someone makes a request for a new API, it is formalized into a specification after deliberations with both the frontend and the backend team. This then serves as the source of truth and is used to generate the backend and the frontend code without as much interdependence.

Some Requester → All Teams → Specification → All Teams.

This not only streamlines the process of adding new APIs, but provides a definitive source of truth for each endpoint. This also makes it so that frontend engineers and backend engineers are not misaligned about a provided parameter in the result being an Int or a String and so on. It’s all in the Spec.

Benefits for Swift (iOS) Developers

Adopting OpenAPI and swift-openapi-generator brings a host of tangible benefits to the Swift/App development process. It transforms how applications interact with web services in a few key ways.

Reduced Development Time and Cost

The most immediate improvement you will see is the significant reduction in boilerplate code you have to write. The generator automates the creation of what is called boilerplate code or ceremonial code. This is the repetitive logic for network requests, response handling, and data model definitions.

By delegating this work, developers can work on the core features of the application which leads to faster and more interesting development cycles.

Compile Time Type Safety

This has been a major improvement for me personally. Instead of relying on the “strongly” typed keys for JSON parsing, we now work with strongly typed models. The generator creates native Swift struct and enum types directly from the schemas defined in the OpenAPI document. This brings the power of a strongly-typed system to the networking and parsing layer.

For example, if the return value of an API is made optional, instead of crashing at runtime, we will fail to compile at build time. This forces us to address this issue right away.

Improved Collaboration and Interoperability

This makes sure that all the developers are on the same page with regard to a given endpoint. And since this specification is language agnostic, it will serve as a universal language for all teams involved in the project – mobile, web and backend.

Other Tooling

Once you have a specification, you can use that to power a wide variety of tools. You can generate interactive documentation, create mock servers for frontend development, and run automated tests.

Alright hopefully you’re sold – so now how do you implement this into your project?

A Practical Guide to Implementing This Solution

We’ll now take a look at a practical example so you can understand how you can implement this in a project. This involves:

• Creating an openapi.yaml file to describe the API specification.

• Configuring and integrating swift-openapi-generator into a SwiftUI application.

• Prototyping an app that fetches and displays a list of posts from the https://jsonplaceholder.typicode.com/

To follow along, you will need Xcode installed and a basic understanding of Swift programming and SwiftUI for App development.

Step 1: Create a good openapi.yaml file (the specification)

The quality of a specification is really important because it directly determines the quality of the code produced by swift-openapi-generator. If you don’t have a good specification, you might run into several issues that developers often complain about, like confusing and long method names.

For example, it might generate something like get_all_my_meal_recipes_hyphen_detailed. This might happen because the generator is forced to create a new name based on the API path if the identifier is not provided in the spec. So, instead of dealing with these issues one after the other, we will create a good clear specification to start with.

Since we’re using the jsonplaceholder as our backend server, we are limited by what tweaks we can make – but it is a fantastic project that lets us mimic a backend server.

In general, an OpenAPI.yaml file contains:

1. OpenAPI Info and servers – This will provide the metadata about the API like the OpenAPI version, which server to point to for calls, and so on.

2. Paths – This will provide the available endpoints. In our case, it can contain /posts as one of them. We also will have to mention the kind of endpoint (get, post, put, and so on)

3. OperationID – This field instructs the generator to create a clear method with this name.

4. Responses – This defines the possible outcomes of an API call. We will specify the structure of a successful 200 OK response or any other errors here.

5. Components / Schemas – This defines all the reusable components and data models. If we have a Post schema definer here, the generator will use this to create a Post struct in Swift to match this.

Keeping in mind all these elements, I compiled a yaml file for us to use for this tutorial:

# openapi.yaml
openapi: "3.0.3"
info:
  title: "JSONPlaceholder API"
  version: "1.0.0"
servers:
  - url: "https://jsonplaceholder.typicode.com"
paths:
  /posts:
    get:
      summary: "Get all posts"
      operationId: "getPosts"
      responses:
        "200":
          description: "A list of posts"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Post"
components:
  schemas:
    Post:
      type: object
      required:
        - userId
        - id
        - title
        - body
      properties:
        userId:
          type: integer
        id:
          type: integer
        title:
          type: string
        body:
          type: string

The first line here, openapi: “3.0.3”, just tells the generators and parsers that we are using version 3.0.3.

Next, we have some more metadata – the name and version of the API. We also have the server we are calling with our APIs.

After defining this metadata, we now define our endpoints. For the sake of this example, let’s assume that we only have one endpoint to call to get posts. We represent this by saying /posts under paths. We then specify which kind it is by specifying get:.

We give a short description of what it does in the summary and then specify an operationId which is what we this function will be called in our generated code. We also specify exactly what structure the response will have, that is, a JSON of an array of Posts.

We then list any components we have across our APIs like the Post. Note that we are using the Post schema in the return response structure before we define it further down. The schemas in components will determine the Model structs we will generate using this yaml file.

Step 2: Set up your project

Create a new SwiftUI project. For the purpose of this tutorial, we’ll use an iOS app – but you can do this with any app. Select Swift as the language and SwiftUI for the interface.

Add the openapi.yaml file we just created to this project. (You can also create this file in Xcode and copy, paste from the script above.)

Now, add the following swift packages to the project. (Note: Please read the entire section about adding packages before you proceed.)

1. Swift OpenAPI Generator – https://github.com/apple/swift-openapi-generator – The Core Generator Plugin.

   

   

2. Swift OpenAPI Runtime – https://github.com/apple/swift-openapi-runtime – This contains the common types and protocols used by the code generated by the generator plugin.

   

3. Swift OpenAPI URLSession – https://github.com/apple/swift-openapi-urlsession – This is a transport layer that allows the generated code to use the Apple URLSession to make network requests.

   

One major caveat to note here when adding these packages is that The Swift OpenAPI Generator should not be added to your project target. This is because we’re only using this to generate the code, but we’re not using it in the app.

If you get this error: swift-openapi-generator/Sources/_OpenAPIGeneratorCore/PlatformChecks.swift:21:5 _OpenAPIGeneratorCore is only to be used by swift-openapi-generator itself—your target should not link this library or the command line tool directly. – then you made this mistake.

The easiest way to fix this is removing the package and adding it again. Or you can go to Project → Target → Build Phases → Link Binary with Libraries → Remove Swift OpenAPI Generator.

Now that we added these generator and runtime plugins, we need to give the generator some instructions on what to generate. You can do this with an openapi-generator-config.yaml file. For our project, use the following file. It’s really simple:

generate:
  - types
  - client

This tells our generator to generate the types – the swift structs, enums, and so on from the schema section of the file, and the client – the main class which interacts with the networking logic.

Save this into an openapi-generator-config.yaml file as shown.

And finally, we want the generator to run whenever we want to build this application/target. We can specify this in the Build Phases tab of the target. Under the “ Target → Build Phases → Run Build Tool Plug-ins” , add the OpenAPIGenerator Plugin.

The first time the project is built after setting this, Xcode will display a security dialog. This will let us “Trust and Enable” for this plugin. It’s a one time confirmation that gives this plugin the permission required to run during the build process.

As soon as you build the second time after giving these permissions, you will generate the files. You might not see any changes in the Xcode window itself. But if you’re curious to see the result, go to this folder.

DerivedData → <ProjectName>*identifier → Build → intermediates.noindex → BuildToolPluginIntermediates → <TargetName>.output → <TargetName> → OpenAPIGenerator → GeneratedSources

More on derived data folder here: https://gayeugur.medium.com/derived-data-2e9468c6da9b if you’re curious.

Keep in mind that this location might vary based on Xcode version, OpenAPI version, and your project settings. But you don’t need to worry about the file location.

You will see three files called Client.swift, Types.swift, and Server.swift.

These are the files that the our generator created and populated with the types and functions we need.

In the next section, we discuss how to use these files to make calls to the server.

Step 3: Write a wrapper

While it’s certainly possible to make the calls to server using just the generated code (Client) type throughout our application, a more maintainable approach is to use a wrapper around these types. This will provide a stable, clean interface for the rest our our app to use, and it decouples feature code from the generated code.

I can hear you thinking: “Wait a second. Isn’t the entire purpose of generating this code to avoid this boilerplate abstraction?”

While it adds some abstraction on top of the generated code, it’s valuable to have this for number of reasons. Here are but a few of them:

1. Better naming. The generated Post struct right now will be called Components.Schemas.Post.

2. If you ever want to move away from the generator, an abstraction is really helpful.

3. If you want to Mock this server call, you can do this via the abstraction.

4. UI Optimization. You might want to flatten the structure of a model to reduce the number of computed variables in there, and so on.

So, we want to wrap this around a file called WebService.swift:

// WebService.swift
import Foundation
import OpenAPIURLSession

// A clean, app-specific Post model.
// This decouples views from the generated types.
struct AppPost: Identifiable, Codable {
    let id: Int
    let title: String
    let body: String
}

class WebService {
    private let client: Client

    init() {
        // The server URL and transport are from the generated code.
        // `Servers.Server1.url()` corresponds to the first URL in the `servers` array of the spec.
        self.client = Client(
            serverURL: try! Servers.Server1.url(),
            transport: URLSessionTransport()
        )
    }

    func getPosts() async throws -> [AppPost] {
        // Call the generated method, which was named using `operationId`.
        let response = try await client.getPosts(.init())

        // The generated response is a type-safe enum covering all documented status codes.
        switch response {
        case.ok(let okResponse):
            // The body is also a type-safe enum for different content types.
            switch okResponse.body {
            case.json(let posts):
                // Map the generated `Components.Schemas.Post` to our clean `AppPost` model.
                return posts.map { post in
                    AppPost(id: post.id, title: post.title, body: post.body)
                }
            }
        // The generator forces the handling of other documented responses.
        // Our simple spec only has a 200, so any other response is undocumented.
        case.undocumented(statusCode: let statusCode, _):
            throw URLError(.badServerResponse, userInfo: ["statusCode": statusCode])
        }
    }
}

Let’s go through this file to understand what we’re doing.

First, we import OpenAPIUrlSession along with Foundation. This allows us to call the server, get a response and parse that response.

Next, we define the new AppPost struct. This is meant to be the representation of a Post in the App. In the generated Types.Swift file, we have the generated Post structure. This is defined as:

/// - Remark: Generated from `#/components/schemas/Post`.
        internal struct Post: Codable, Hashable, Sendable {
            /// - Remark: Generated from `#/components/schemas/Post/userId`.
            internal var userId: Swift.Int
            /// - Remark: Generated from `#/components/schemas/Post/id`.
            internal var id: Swift.Int
            /// - Remark: Generated from `#/components/schemas/Post/title`.
            internal var title: Swift.String
            /// - Remark: Generated from `#/components/schemas/Post/body`.
            internal var body: Swift.String
            /// Creates a new `Post`.
            ///
            /// - Parameters:
            ///   - userId:
            ///   - id:
            ///   - title:
            ///   - body:
            internal init(
                userId: Swift.Int,
                id: Swift.Int,
                title: Swift.String,
                body: Swift.String
            ) {
                self.userId = userId
                self.id = id
                self.title = title
                self.body = body
            }
            internal enum CodingKeys: String, CodingKey {
                case userId
                case id
                case title
                case body
            }
        }

As you can see, our AppPost struct is different from this generated type. We omit the userId since we do not care about it (at least for now).

Back to the WebService class, we see a client attribute. This is a generated type variable that will let us interact with the servers. In the initializer of the WebService class, we create a new Client using the first server URL we specified in the schema and use the URLSessionTransport object for making these calls.

We then define our methods. In this case, our getPosts() function which returns [AppPost] array.

let response = try await client.getPosts(.init()) will call the function getPosts() on the Client object. The Client.getPosts() function here takes in an input struct called Operations.getPosts.Input which is initialized by the .init() passed here.

This generated response is a type-safe enum covering all documented codes. (Currently only 200 in our yaml file). So, we use a simple switch to look at both these cases and further use more switch statements to get the proper response. You can see how much easier this is than to parse the response manually.

Once we get the Components.Schemas.Post response, we map and convert it into [AppPost] array and return it.

Now, let’s use this wrapper to display data in our app.

Step 4: Call the wrapper and display the data

We’re at the final step now. We’ll use the wrapper we created to display the fetched posts. We’ll also use a state variable to store our AppPost array in our ContentView view. We’ll then call getPosts() when the view is first displayed to the user.

// ContentView.swift
import SwiftUI

struct ContentView: View {
    @State private var posts: [AppPost] = []
    @State private var errorMessage: String?

    private let webService = WebService()

    var body: some View {
        NavigationStack {
            List(posts) { post in
                VStack(alignment:.leading, spacing: 8) {
                    Text(post.title)
                       .font(.headline)
                    Text(post.body)
                       .font(.subheadline)
                       .foregroundColor(.secondary)
                }
               .padding(.vertical, 4)
            }
           .navigationTitle("Posts")
           .task {
                await loadPosts()
            }
           .overlay {
                if let errorMessage {
                    ContentUnavailableView("Error", systemImage: "xmark.octagon", description: Text(errorMessage))
                } else if posts.isEmpty {
                    ProgressView()
                }
            }
        }
    }

    func loadPosts() async {
        self.errorMessage = nil
        do {
            self.posts = try await webService.getPosts()
        } catch {
            self.errorMessage = error.localizedDescription
        }
    }
}

#Preview {
    ContentView()
}

You can see the dummy posts in the Preview. As you can see, all we had to do was call the webService.getPosts() to populate the variable.

You might be thinking that this is a lot of setup for a simple struct like Post for which we had to create a wrapper called AppPost anyway. But if you had ten types like this and twenty endpoints to call? You wouldn’t have to deal with a lot of repetitive, error-prone code.

Potential Pitfalls

Unfortunately, no process is perfect. You might still face a lot of issues with generated code and this method. I’ve listed some of them here and how to deal with them.

Verbose or ugly generated code

If you have very verbose or ugly generated code, the problem is almost always the missing operationId for an API path. If you don’t specify one, the generator must create a name from the path and the HTTP method with results in long unwieldy names. Adding a clear operationId will mitigate this issue.

Large Specs and Performance Issues

If you have a very large Spec file, generating a client for this entire specification can significantly increase the compile time. It can also result in absolutely massive Types.swift and Client.swift files.

There is a filter option in the openapi-generator-config.yaml file that will allow the generator to include only parts of the spec that are relevant to the application to improve build times and so on. But if you want everything in an API that has hundreds of endpoints, the only way to reduce compile times is to avoid regenerating this every time and decouple this step from the regular build process.

Unsupported Spec Features

While the swift package, swift-openapi-generator, is robust, it does not support all the features included in the specification. I had issues with some features of the newer spec version ( 3.1.1 and had to downgrade to 3.0.3 to make it work well ).

There are also known issues like lack of support for certain types of recursive schemas. Sometimes, the generator errors out and fails and some other times, it generates incomplete types – which can result in a few hours of debugging (I speak from experience).

In any case, knowing the limits of this generator can be helpful in avoiding issues it might cause. Also keep in mind that it is always getting better thanks to its open source nature.

Conclusion: Embrace Spec-Driven Development

In this guide, you navigated the journey of adopting swift-openapi-generator – from understanding the power of API contracts to building a functional SwiftUI app. You also learned about the real life challenges of this process. While there is an initial learning curve, the benefits of this approach are profound.

The core tenet of this approach is to foster more disciplined and more robust method for building applications. By making the OpenAPI document the single source of truth, you make sure that both the frontend and backend are perfectly in sync in perpetuity.

Using this approach also results in more type-safe, maintainable code. The result is less time spent on writing boilerplate and debugging random integration errors and more time spent creating the app itself.

For developers ready to explore further, please checkout the official swift-openapi-generator repository on Github here: https://github.com/apple/swift-openapi-generator.

You can follow me on GitHub and Hashnode for my other posts and projects.

We just released a full course on the freeCodeCamp.org YouTube channel that will teach you the Swift programming language.

Vandad Nahavandipoor teaches this course. He currently works as a lead iOS developer and he has created many other popular courses.

In this course you will learn every modern aspect of Swift as a programming language including, variables, constants, functions, structures, classes, protocols. extensions, asynchronous programming, generics and much more. This course will lay the foundation for learning Swift for those who are not familiar with Swift already.

Here are the sections in this course:

• Variables
• Operators
• If and else
• Functions
• Closures
• Structures
• Enumerations
• Classes
• Protocols
• Extensions
• Generics
• Optionals
• Error Handling
• Collections
• Equality and Hashing
• Custom Operators
• Asynchronous Programming

Watch the full course on the freeCodeCamp.org YouTube channel (7-hour watch).

The Swift programming language was created by Apple in 2014. It's the official language that works with the whole Apple Operating Systems lineup: iOS, iPadOS, watchOS, macOS, and tvOS.

Swift is an open source, general purpose, compiled programming language that's statically typed.

Every value has a type assigned. The type of a value is always checked when used as an argument or returned, at compile time. If there is a mismatch, the program will not compile.

Swift's compiler is LLVM, and it is included within Xcode, the standard IDE you use for Apple software development.

Swift is a modern programming language that was designed to "fit" in an ecosystem that was previously designed for a different programming language called Objective-C.

Most of the software running on the iPhone and Mac today is based on Objective-C code, even for official Apple apps. But Swift usage is gaining traction year after year. While Objective-C will be used for years to maintain and improve existing apps, new applications are likely going to be created with Swift.

Before Apple introduced Swift, Objective-C was heavily developed to introduce new capabilities and features. But in the recent years this effort has decreased a lot in favor of Swift development.

This does not mean Objective-C is dead or not worth learning: Objective-C is still an essential tool for any Apple developer.

That said, I am not going to cover Objective-C here, because we're focusing on Swift – the present and future of the Apple platform.

In just 6 years, Swift has gone through 5 major versions, and we're now (at the time of writing) at version 5.

Swift is famously Apple's products language, but it is not an Apple-only language. You can use it on several other platforms.

It is open source, so porting the language to other platforms does not require any permission or licensing, and you can find Swift projects to create Web servers and APIs (https://github.com/vapor/vapor) as well as projects to interact with microcontrollers.

Swift is a general-purpose language, built with modern concepts, and it has a bright future.

What We'll Cover Here

The goal of this book is to get you up and running with Swift, starting from zero.

If you have a Mac or an iPad, I recommend you to download the Playgrounds application made by Apple from the App Store.

This app lets you run snippets of Swift code without having to create a full app first. It's a very handy way to test your code, not just when you start learning, but whenever you need to try some code.

It also contains a series of awesome examples and tutorials to expand your Swift and iOS knowledge.

Note: You can get a PDF and ePub version of this Swift Beginner's Handbook

• Introduction to Swift
• Variables in Swift
• Objects in Swift
• Operators in Swift
• Conditionals in Swift
• Loops in Swift
• How to Write Comments in Swift
• Semicolons in Swift
• Numbers in Swift
• Strings in Swift
• Booleans in Swift
• Arrays in Swift
• Sets in Swift
• Dictionaries in Swift
• Tuples in Swift
• Optionals and nil in Swift
• Enumerations in Swift
• Structures in Swift
• Classes in Swift
• Functions in Swift
• Protocols in Swift
• Where to Go From Here

Variables in Swift

Variables let us assign a value to a label. We define them using the var keyword:

var name = "Roger"
var age = 8

Once a variable is defined, we can change its value:

age = 9

Variables that you do not want to change can be defined as constants, using the let keyword:

let name = "Roger"
let age = 8

Changing the value of a constant is forbidden.

You can't change the value of a constant or you'll get this error

When you define a variable and you assign it a value, Swift implicitly infers the type of it.

8 is an Int value.

"Roger" is a String value.

A decimal number like 3.14 is a Double value.

You can also specify the type at initialization time:

let age: Int = 8

But it's typical to let Swift infer it, and it's mostly done when you declare a variable without initializing it.

You can declare a constant, and initialize it later:

let age : Int

age = 8

Once a variable is defined, it is bound to that type. You cannot assign to it a different type, unless you explicitly convert it.

You can't do this:

var age = 8
age = "nine"

Cannot assign value of type 'String' to type 'Int' error

Int and String are just two of the built-in data types provided by Swift.

Objects in Swift

In Swift, everything is an object. Even the 8 value we assigned to the age variable is an object.

In some languages, objects are a special type. But in Swift, everything is an object and this leads to one particular feature: every value can receive messages.

Each type can have multiple functions associated to it, which we call methods.

For example, talking about the 8 number value, we can call its isMultiple method, to check if the number is a multiple of another number:

isMultiple method

A String value has another set of methods.

A type also has instance variables. For example the String type has the instance variable count, which gives you the number of characters in a string:

instance variable count

Swift has 3 different object types, which we'll see more in details later on: classes, structs and enums.

Those are very different, but they have one thing in common: to object type, we can add methods, and to any value, of any object type, we can send messages.

Operators in Swift

We can use a wide set of operators to operate on values.

We can divide operators in many categories. The first is the number of targets: 1 for unary operators, 2 for binary operators or 3 for the one and only ternary operator.

Then we can divide operators based on the kind of operation they perform:

• assignment operator
• arithmetic operators
• compound assignment operators
• comparison operators
• range operators
• logical operators

plus some more advanced ones, including nil-coalescing, ternary conditional, overflow, bitwise and pointwise operators.

Note: Swift allows you to create your own operators and define how operators work on your types you define.

Assignment operator in Swift

You use the assignment operator to assign a value to a variable:

var age = 8

Or to assign a variable value to another variable:

var age = 8
var another = age

Arithmetic operators in Swift

Swift has a number of binary arithmetic operators: +, -, *, / (division), % (remainder):

1 + 1 //2
2 - 1 //1
2 * 2 //4
4 / 2 //2
4 % 3 //1
4 % 2 //0

- also works as a unary minus operator:

let hotTemperature = 20
let freezingTemperature = -20

You can also use + to concatenate String values:

"Roger" + " is a good dog"

Compound assignment operators in Swift

The compound assignment operators combine the assignment operator with arithmetic operators:

• +=
• -=
• *=
• /=
• %=

Example:

var age = 8
age += 1

Comparison operators in Swift

Swift defines a few comparison operators:

• ==
• !=
• >
• <
• >=
• <=

You can use those operators to get a boolean value (true or false) depending on the result:

let a = 1
let b = 2

a == b //false
a != b //true
a > b // false
a <= b //true

Range operators in Swift

Range operators are used in loops. They allow us to define a range:

0...3 //4 times
0..<3 //3 times

0...count //"count" times
0..<count //"count-1" times

Here's a sample usage:

let count = 3
for i in 0...count {
  //loop body
}

Logical operators in Swift

Swift gives us the following logical operators:

• !, the unary operator NOT
• &&, the binary operator AND
• ||, the binary operator OR

Sample usage:

let condition1 = true
let condition2 = false

!condition1 //false

condition1 && condition2 //false
condition1 || condition2 //true

Those are mostly used in the if conditional expression evaluation:

if condition1 && condition2 {
  //if body
}

Conditionals in Swift

if statements in Swift

if statements are the most popular way to perform a conditional check. We use the if keyword followed by a boolean expression, followed by a block containing code that is run if the condition is true:

let condition = true
if condition == true {
    // code executed if the condition is true
}

An else block is executed if the condition is false:

let condition = true
if condition == true {
    // code executed if the condition is true
} else {
    // code executed if the condition is false
}

You can optionally wrap the condition validation into parentheses if you prefer:

if (condition == true) {
    // ...
}

And you can also just write:

if condition {
    // runs if `condition` is `true`
}

or

if !condition {
    // runs if `condition` is `false`
}

One thing that separates Swift from many other languages is that it prevents bugs caused by erroneously doing an assignment instead of a comparison. This means you can't do this:

if condition = true {
    // The program does not compile
}

The reason is that the assignment operator does not return anything, but the if conditional must be a boolean expression.

switch statements in Swift

Switch statements are a handy way to create a conditional with multiple options:

var name = "Roger"

switch name {
case "Roger":
    print("Hello, mr. Roger!")
default: 
    print("Hello, \(name)")
}

When the code of a case ends, the switch exits automatically.

A switch in Swift needs to cover all cases. If the tag, name in this case, is a string that can have any value, we need to add a default case, mandatory.

Otherwise with an enumeration, you can simply list all the options:

enum Animal {
    case dog
    case cat
}

var animal: Animal = .dog

switch animal {
case .dog:
    print("Hello, dog!")
case .cat:
    print("Hello, cat!")
}

A case can be a Range:

var age = 20

switch age {
case 0..<18:
    print("You can't drive!!")
default: 
    print("You can drive")
}

Ternary conditional operator in Swift

The ternary conditional operator is a shorter version of an if expression. It allows us to execute an expression if a condition is true, and another expression if the condition is false.

Here is the syntax:

`condition` ? `value if true` : `value if false`

Example:

let num1 = 1
let num2 = 2

let smallerNumber = num1 < num2 ? num1 : num2 

// smallerNumber == 1

The syntax is shorter than an if statement, and sometimes it might make more sense to use it.

Loops in Swift

for-in loops in Swift

You can use for-in loops to iterate a specific amount of times, using a range operator:

for index in 0...3 {
  //iterate 4 times, `index` is: 0, 1, 2, 3
}

You can iterate over the elements of an array or set:

let list = ["a", "b", "c"]
for item in list {
  // `item` contains the element value
}

And on the elements of a dictionary:

let list = ["a": 1, "b": 2, "c": 2]
for (key, value) in list {
  // `key` contains the item key
  // `value` contains the item value
}

while loops in Swift

A while loop can be used to iterate on anything, and will run while the condition is true:

while [condition] {
    //statements...
}

The condition is checked at the start, before the loop block is executed.

Example:

var item = 0
while item <= 3 { //repeats 3 times
    print(item)
    item += 1
}

repeat-while loops in Swift

A repeat-while loop in Swift is similar to the while loop. But in this case the condition is checked at the end, after the loop block, so the loop block is executed at least once. Then the condition is checked, and if it is evaluated as true, the loop block is repeated:

repeat {
    //statements...
} while [condition]

Example:

var item = 0
repeat { //repeats 3 times
    print(item)
    item += 1
} while item < 3

continue and break statements in Swift

Swift provides you 2 statements that you can use to control the flow inside a loop: continue and break.

You use continue to stop the current iteration, and run the next iteration of the loop.

break ends the loop, not executing any other iteration.

Example:

let list = ["a", "b", "c"]
for item in list {
  if (item == "b") {
    break
  }
  //do something
}

How to Write Comments in Swift

A comment in Swift can take 2 forms: a single-line comment, and a multi-line comment.

A single-line comment looks like this:

//this is a comment

and and you can put it at the end of a line of code:

let a = 1 //this is a comment

A multi-line comment is written using this syntax:

/* this
 is
    a multi-line
 comment
*/

Swift allows you to nest multi-line comments:

/* this
 is
    a /* nested */ multi-line
 comment
*/

This is handy especially when commenting out large portions of code that already contain multi-line comments.

Semicolons in Swift

In Swift, semicolons are generally optional.

You can write statements on separate lines, and you don't need to add a semicolon:

let list = ["a", "b", "c"]
var a = 2

You can add a semicolon, but it adds nothing meaningful in this case:

let list = ["a", "b", "c"];
var a = 2;

But if you want to write more than one statement on the same line, then you need to add a semicolon:

var a = 2; let b = 3

Numbers in Swift

In Swift, numbers have 2 main types: Int and Double.

An Int is a number without decimal point. A Double is a number with decimal point.

Both use 64 bits, on modern computers that work with 64 bits, and 32 bit on 32-bit platforms.

The range of values they can store depends on the platform used, and can be retrieved using the int property of each type:

Range of int values

Then, in addition to Int and Double, we have lots of other numeric types. These were mostly used to interact with APIs built in the past and that needed to interact with C or Objective-C, and you must be aware that we have them:

• Int8 is an integer with 8 bits
• Int16 is an integer with 16 bits
• Int32 is an integer with 32 bits
• Int64 is an integer with 64 bits
• UInt8 is an unsigned integer with 8 bits
• UInt16 is an unsigned integer with 16 bits
• UInt32 is an unsigned integer with 32 bits
• UInt64 is an unsigned integer with 64 bits
• UInt is like Int, but unsigned, and it ranges from 0 to Int.max * 2.
• Float is a decimal number with 32 bits.

Then using Cocoa APIs you might use other numeric types like CLong, CGFloat, and more.

You will always use Int or Double in your code, and use those specific types only in particular cases.

Remember that you can always convert any of those types to Int and Double types, instantiating a number passing the value inside parentheses to Double() or Int():

let age : UInt8 = 3
let intAge = Int(age)

You can also convert a number from Double to Int:

let age = Double(3)
let count = Int(3.14)

How to convert a number from Double to Int

Strings in Swift

Strings are one of the most popular tools in programming.

In Swift, you can define a string using the string literal syntax:

let name = "Roger"

We use double quotes. Single quotes are not valid string delimiters.

A string can span over multiple lines using 3 double quotes:

let description = """
    a long
      long 
          long description
    """

You can use string interpolation to embed an expression in a string:

let age = 8

let name = """
    Roger, age \(age)
    Next year he will be \(age + 1)
    """

You can concatenate two strings with the + operator:

var name = "Roger"
name = name + " The Dog"

And you can append text to a string with the += operator:

var name = "Roger"
name += " The Dog"

Or using the append(_:) method:

var name = "Roger"
name.append(" The Dog")

You can count the characters in a string using the count string property:

let name = "Roger"
name.count //5

Any string comes with a set of useful methods, for example:

• removeFirst() to remove the first character
• removeLast() to remove the last character
• lowercased() to get a new string, lowercased
• uppercased() to get a new string, uppercased
• starts(with:) which returns true if the string starts with a specific substring
• contains() which returns true if the string contains a specific character

and many, many more.

When you need to reference an item in the string, since strings in Swift are unicode, we can't simply reference the letter o in let name = "Roger" using name[1]. You need to work with indexes.

Any string provides the starting index with the startIndex property:

let name = "Roger"
name.startIndex //0

To calculate a specific index in the string, you calculate it using the index(i:offsetBy:) method:

let name = "Roger"
let i = name.index(name.startIndex, offsetBy: 2)
name[i] //"g"

You can also use the index to get a substring:

let name = "Roger"
let i = name.index(name.startIndex, offsetBy: 2)
name.suffix(from: i) //"ger"

//Or using the subscript:

name[i...] //"ger"

When you get a substring from a string, the type of the result is Substring, not String.

let name = "Roger"
let i = name.index(name.startIndex, offsetBy: 2)
print(type(of: name.suffix(from: i))) 
//Substring

Substrings are more memory efficient, because you do not get a new string, but the same memory structure is used behind the scenes. But you need to be careful when you deal with strings a lot, as there are optimizations you can implement.

Strings are collections, and they can be iterated over in loops.

Booleans in Swift

Swift provides the Bool type, which can have two values: true and false.

var done = false
done = true

Booleans are especially useful with conditional control structures like if statements or the ternary conditional operator:

var done = true

if done == true {
    //code
}

Arrays in Swift

We use arrays to create a collection of items.

In this example we create an array holding 3 integers:

var list = [1, 2, 3]

We can access the first item using the syntax list[0], the second using list[1], and so on.

Elements in an array in Swift must have the same type.

The type can be inferred if you initialize the array at declaration time, like in the case above.

Otherwise the type of values an array can include must be declared, in this way:

var list: [Int] = []

Another shorthand syntax is:

var list = [Int]()

You can also explicitly declare the type at initialization, like this:

var list: [Int] = [1, 2, 3]

A quick way to initialize an array is to use the range operator:

var list = Array(1...4) //[1, 2, 3, 4]

To get the number of items in the array, use the count property:

var list = [1, 2, 3]
list.count //3

If an array is empty, its isEmpty property is true.

var list = [1, 2, 3]
list.isEmpty //false

You can append an item at the end of the array using the append() method:

var list: [Int] = [1, 2, 3]
list.append(4)

or you can insert an item at any position of the array using insert(newElement: <Type> at: Int):

var list: [Int] = [1, 2, 3]
list.insert(17, at: 2)
//list is [1, 2, 17, 3]

An array must be declared as var to be modified. If it's declared with let, you cannot modify it by adding or removing elements.

To remove one item from the array, use remove(at:) passing the index of the element to remove:

var list: [Int] = [1, 2, 3]
list.remove(1)
//list is [1, 3]

removeLast() and removeFirst() are two handy ways to remove the last and first element.

To remove all items from the array, you can use removeAll() or you can assign an empty array:

var list: [Int] = [1, 2, 3]
list.removeAll()
//or
list = []

The sort() method sorts the array:

var list = [3, 1, 2]
list.sort()
//list is [1, 2, 3]

There are a lot more methods, but those are the basic ones.

Arrays are equal when they contain the same elements, of the same type:

[1, 2, 3] == [1, 2, 3] //true

Arrays are passed by value, which means if you pass an array to a function, or return it from a function, the array is copied.

Arrays are collections, and they can be iterated over in loops.

Sets in Swift

You use sets to create collections of non-repeated items.

While an array can contain many times the same item, you only have unique items in a set.

You can declare a set of Int values in this way:

let set: Set<Int> = [1, 2, 3]

or you can initialize it from an array:

let set = Set([1, 2, 3])

You can add items to the set using insert():

var set = Set([1, 2, 3])
set.insert(17)

Unlike arrays, there is no order or position in a set. Items are retrieved and inserted randomly.

The way to print the content of a set so it's ordered is to transform it into an array using the sorted() method:

var set = Set([2, 1, 3])
let orderedList = set.sorted()

To check if a set contains an element, use the contains() method:

var set = Set([1, 2, 3])
set.contains(2) //true

To get the number of items in the set, use the count property:

let set = Set([1, 2, 3])
set.count //3

If a set is empty, its isEmpty property is true.

let set = Set([1, 2, 3])
set.isEmpty //false

To remove one item from the array, use remove() passing the value of the element:

var set = Set([1, 2, 3])
set.remove(1)
//set is [2, 3]

To remove all items from the set, you can use removeAll():

set.removeAll()

Sets, like arrays, are passed by value. This means that if you pass it to a function, or return it from a function, the set is copied.

Sets are great to perform set math operations like intersection, union, subtracting, and more.

These methods help with this:

• intersection(_:)
• symmetricDifference(_:)
• union(_:)
• subtracting(_:)
• isSubset(of:)
• isSuperset(of:)
• isStrictSubset(of:)
• isStrictSuperset(of:)
• isDisjoint(with:)

Sets are collections, and they can be iterated over in loops.

Dictionaries in Swift

We use dictionaries to create a collection of key-value pairs.

Here is how to create a dictionary with 1 key-value pair, where the key is a String and the value is an Int:

var dict = ["Roger": 8, "Syd": 7]

In this case the type is inferred. You can also explicitly set the type at declaration time:

var dict: [String: Int] = ["Roger": 8, "Syd": 7]

In this example we create an empty dictionary of Int keys and String values:

var dict = [String: Int]()

//or

var dict: [String: Int] = [:]

You can access the value assigned to a key using this syntax:

var dict = ["Roger": 8, "Syd": 7]

dict["Roger"] //8
dict["Syd"] //7

You can change the value assigned to a key in this way:

dict["Roger"] = 9

A dictionary must be declared as var to be modified. If it's declared with let, you cannot modify it by adding or removing elements.

Use the same syntax to add a new key/value pair:

dict["Tina"] = 4

To remove a key/value pair, assign the value to nil:

dict["Tina"] = nil

Or call the removeValue(forKey:) method:

dict.removeValue(forKey: "Tina")

To get the number of items in the dictionary, use the count property:

var dict = ["Roger": 8, "Syd": 7]
dict.count //2

If a dictionary is empty, its isEmpty property is true.

var dict = [String: Int]()
dict.isEmpty //true

There are a lot of methods related to dictionaries, but those are the basic ones.

Dictionaries are passed by value, which means if you pass it to a function, or return it from a function, the dictionary is copied.

Dictionaries are collections, and they can be iterated over in loops.

Tuples in Swift

You use tuples to group multiple values into a single collection. For example you can declare a variable dog containing a String and an Int value:

let dog : (String, Int)

And you can initialize them with a name and an age

let dog : (String, Int) = ("Roger", 8)

But as with any other variable, the type can be inferred during initialization:

let dog = ("Roger", 8)

You can use named elements:

let dog = (name: "Roger", age: 8)

dog.name //"Roger"
dog.age //8

Once a tuple is defined, you can decompose it to individual variables in this way:

let dog = ("Roger", 8)
let (name, age) = dog

and if you need to just get one of the values, you can use the special underscore keyword to ignore the other ones:

let dog = ("Roger", 8)
let (name, _) = dog

Tuples are an awesome tool for various needs.

The most obvious one is that they're a short way to group similar data.

Another one of those needs is returning multiple items from a function. A function can only return a single item, so a tuple is a convenient structure for that.

Another handy functionality allowed by tuples is swapping elements:

var a = 1
var b = 2

(a, b) = (b, a)

//a == 2
//b == 1

Optionals and nil in Swift

Optionals are one key feature of Swift.

When you don't know if a value will be present or absent, you declare the type as an optional.

The optional wraps another value with its own type. Or maybe not.

We declare an optional by adding a question mark after its type, like this:

var value: Int? = 10

Now value is not an Int value. It's an optional wrapping an Int value.

To find out if the optional wraps a value, you must unwrap it.

You do so using an exclamation mark:

var value: Int? = 10
print(value!) //10

Swift methods often return an optional. For example the Int type initializer accepts a string, and returns an Int optional:

Int type initializer takes in a string and returns an int optional

This is because it does not know if the string can be converted to a number.

If the optional does not contain a value, it evaluates as nil, and you cannot unwrap it:

Evaluating to nil

nil is a special value that cannot be assigned to a variable. Only to an optional:

You can only assign nil to an optional (not an int)

You typically use if statements to unwrap values in your code, like this:

var value: Int? = 2

if let age = value {
    print(age)
}

Enumerations in Swift

Enumerations are a way to group a set of different options under a common name.

Example:

enum Animal {
    case dog
    case cat
    case mouse
    case horse
}

This Animal enum is now a type.

A type whose value can only be one of the cases listed.

If you define a variable of type Animal:

var animal: Animal

you can later decide which value to assign it using this syntax:

var animal: Animal
animal = .dog

We can use enumerations in control structures like switches:

enum Animal {
    case dog
    case cat
    case mouse
    case horse
}

let animal = Animal.dog

switch animal {
case .dog: print("dog")
case .cat: print("cat")
default: print("another animal")
}

Enumeration values can be strings, characters, or numbers.

You can also define an enum on a single line:

enum Animal {
    case dog, cat, mouse, horse
}

And you can also add type declaration to the enumeration, and each case has a value of that type assigned:

enum Animal: Int {
    case dog = 1
    case cat = 2
    case mouse = 3
    case horse = 4
}

Once you have a variable, you can get this value using its rawValue property:

enum Animal: Int {
    case dog = 1
    case cat = 2
    case mouse = 3
    case horse = 4
}

var animal: Animal
animal = .dog

animal.rawValue //1

Enumerations are a value type. This means they are copied when passed to a function, or when returned from a function. And when we assign a variable pointing to an enumeration to another variable.

Structures in Swift

Structures are an essential Swift concept.

Structures are everywhere in Swift. Even the built-in types are structures.

We can create instances of structures, which we call objects.

In most languages, objects can only be created from classes. Swift has classes, too, but you can create objects also from structures. The official documentation actually advises that you should prefer structures because they are easier to use.

Structures are a light versions of classes.

A struct can:

• have properties
• have methods (functions)
• define subscripts
• define initializers
• conform to protocols
• be extended

One important thing classes allow is inheritance, so if you need that, you have classes.

A struct is defined using this syntax:

struct Dog {

}

Inside a structure you can define stored properties:

struct Dog {
    var age = 8
    var name = "Roger"
}

This structure definition defines a type. To create a new instance with this type, we use this syntax:

let roger = Dog()

Once you have an instance, you can access its properties using the dot syntax:

let roger = Dog()
roger.age
roger.name

The same dot syntax is used to update a property value:

roger.age = 9

You can also create a struct instance by passing the values of the properties:

let syd = Dog(age: 7, name: "Syd")
syd.age
syd.name

To do so, properties must be defined variables with var, not as constants (with let). It's also important to respect the order those properties are defined.

Structures can have instance methods: functions that belong to an instance of a structure.

struct Dog {
    var age = 8
    var name = "Roger"
    func bark() {
        print("\(name): wof!")
    }
}

And we also have type methods:

struct Dog {
    var age = 8
    var name = "Roger"
    func bark() {
        print("\(name): wof!")
    }
    static func hello() {
        print("Hello I am the Dog struct")
    }
}

This is invoked as Dog.hello().

Structures are a value type. This means they are copied when passed to a function, or when returned from a function. And when we assign a variable pointing to a structure to another variable.

This also means that if we want to update the properties of a structure we must define it using var and not let.

All types in Swift are defined as structures: Int, Double, String, arrays and dictionaries, and more are structures.

Classes in Swift

Classes are a bit similar to structures, but they have some key differences.

A class is defined using this syntax:

class Dog {

}

Inside a class you can define stored properties:

class Dog {
    var age = 0
}

A class definition defines a type. To create a new instance with this type, we use this syntax:

let roger = Dog()

Once you have an instance, you can access its properties using the dot syntax:

let roger = Dog()
roger.age

You use the same dot syntax to update a property value:

roger.age = 9

One big difference is that classes are reference types. Structures (and enumerations) are value types.

This means that assigning a class instance to another variable does not copy the instance. Both variables point to the same instance:

class Dog {
    var age = 0
}

let roger = Dog()
let syd = roger

roger.age = 9
//syd.age == 9

This also means we can define a reference to a class using let, and we can change its properties, as you saw in the example above.

We can create instances of classes, and we call them objects.

As with structs, classes can have properties, methods, and more.

Contrary to structs, we must define an initializer in order to initialize the values when we create an instance:

class Dog {
    var age : Int

    init(age: Int) {
        self.age = age
    }
}

let roger = Dog(age: 9)

You can only declare properties without initializing them if you have an initializer.

See the use of self. We need it because age is both an instance property and the init(age:) method parameter. self.age references the age instance property.

Classes can have instance methods: functions that belong to an instance of a class.

class Dog {
    var age = 8
    var name = "Roger"

    func bark() {
      print("\(name): wof!")
    }
}

And we also have type methods:

class Dog {
    var age = 8
    var name = "Roger"

    func bark() {
        print("\(name): wof!")
    }
    static func hello() {
        print("Hello I am the Dog struct")
    }
}

Invoked as Dog.hello().

One important thing classes allow is inheritance.

A class can inherit all the properties and methods from another class.

Say we have a class Animal. Every animal has an age:

class Animal {
    var age: Int
}

Not every animal has a name. Dogs have a name. So we create a Dog class extending from Animal:

class Dog: Animal {
    var name: String
}

Now we must add an initializer for both classes. In the Dog case, after we do the class-specific initialization, we can call the parent class initializer using super.init():

class Animal {
    var age: Int

    init(age: Int) {
        self.age = age
    }
}

class Dog: Animal {
    var name: String

    init(age: Int, name: String) {
        self.name = name
        super.init(age: age)
    }
}

var horse = Animal(age: 8)
var roger = Dog(age: 8, name: "Roger")

Animal is now a superclass, and Dog is a subclass.

There's more to say about classes, but this is a good introduction.

Functions in Swift

Your program's code is organized into functions.

You can declare a function using the func keyword:

func bark() {
    print("woof!")
}

Functions can be assigned to structures, classes and enumerations, and in this case we call them methods.

A function is invoked using its name:

bark()

A function can return a value:

func bark() -> String {
    print("woof!")
      return "barked successfully"
}

And you can assign it to a variable:

let result = bark()

A function can accept parameters. Each parameter has a name and a type:

func bark(times: Int) {
    for index in 0..<times {
        print("woof!")
    }
}

The name of a parameter is internal to the function.

We use the name of the parameter when we call the function to pass in its value:

bark(times: 3)

When we call the function we must pass all the parameters defined.

Here is a function that accepts multiple parameters:

func bark(times: Int, repeatBark: Bool) {
    for index in 0..<times {
        if repeatBark == true {
            print("woof woof!")
        } else {
            print("woof!")
        }            
    }
}

In this case you call it in this way:

bark(times: 3, repeat: true)

When we talk about this function, we don't call it bark(). We call it bark(times:repeat:).

This is because we can have multiple functions with the same name, but different set of parameters.

You can avoid using labels by using the _ keyword:

func bark(_ times: Int, repeatBark: Bool) {
    //...the function body
}

So you can invoke it in this way:

bark(3, repeat: true)

It's common in Swift and iOS APIs to have the first parameter with no label, and the other parameters labeled.

It makes for a nice and expressive API, when you design the names of the function and the parameters nicely.

You can only return one value from a function. If you need to return multiple values, it's common to return a tuple:

func bark() -> (String, Int) {
    print("woof!")
      return ("barked successfully", 1)
}

And you can assign the result to a tuple:

let (result, num) = bark()

print(result) //"barked successfully"
print(num) //1

You can nest functions inside other functions. When this happens, the inner function is invisible to outside the outer function.

Protocols in Swift

A protocol is a way to have different objects, of different types, have a common set of functionalities.

You define a protocol like this:

protocol Mammal {

}

Structs and classes can adopt a protocol in this way:

struct Dog: Mammal {

}

class Cat: Mammal {

}

A protocol can define properties and methods, without providing values and implementations, and a struct/class must implement them:

protocol Mammal {
    var age: Int { get set }
    func walk()
}

The property can be defined as get or get set. If it's get, the property must be implemented as read only, with a getter.

Any type that adopts the protocol must conform to the protocol by implementing those methods or providing those properties:

struct Dog: Mammal {
    var age: Int = 0
    func walk() {
        print("The dog is walking")
    }
}

class Cat: Mammal {
    var age: Int = 0
    func walk() {
        print("The cat is walking")
    }
}

Structs and classes can adopt multiple protocols:

struct Dog: Mammal, Animal {

}

class Cat: Mammal, Animal {

}

Notice that for classes, this is the same syntax used to define a superclass. If there is a superclass, list it as the first item in the list, after the colon.

Where to Go From Here

I hope this little handbook was useful in shining a light on how to get started with Swift. And I hope you are now interested to learn more about it!

I can now point you to a few places to learn more:

• The official Swift Language Guide
• The Swift Standard Library
• WWDC Swift videos

You can get a PDF and ePub version of this Swift Beginner's Handbook here.

In this article we will talk about why and how to implement the GameCenter's Leaderboard within your app.

Why GameCenter is Making a Huge Revival

You can make iPhone games without a scoreboard, but leaderboards can help make the game feel more competitive, like people are competing against one another around the World.

Instead of creating and managing your own backend, the GameCenter Leaderboard allows you to scale with traffic infinitely, skip an entire login page for authorization, get the Image, Name, and friends playing the same game – all without your users having to enter anything.

Especially with iOS 16, Apple is investing more in improving it, and driving more app usage, like through Push Notifications when your friend beats your score in the game.

In my journey of learning SwiftUI, I have been creating and publishing apps, because IMO that's the best way to learn.

There wasn't much updated documentation on how to do a lot of this, especially none with SwiftUI nor with the advent of async and await in Swift. So I consolidated and simplified it for everyone to build amazing apps. So feel free to invite me to test your apps too!

Pre-Requisites:

• You'll need to have an Apple Developer paid account
• You have to create the App Id for your app in the provisioning profiles section of the Apple Developer Portal
• You have to create the App in the iTunes Connect Connect portal

How to Implement Your iOS Leaderboard in 6 Steps

Most of the code logic for the leaderboard is in this file if you want to skip ahead. Here's the steps as follows:

1. How to Create the App Store Connect Leaderboard

Screenshot from the Apple iTunes Connect Portal

Once you have created the app in the App Store Connect portal successfully, go to the Services tab for the app -> and make sure you're in the GameCenter page.

Then add a new leaderboard using the "+" sign, which can either be "Classic" (scores never reset) or "Recurring" (scores reset based on your frequency settings).

Most games prefer a recurring leaderboard so that the leaderboard isn't cluttered with older impossible to reach high scores.

The LeaderboardID you input there is the one that you need to use in all the places in the code that ask for it.

Details required to create a new Leaderboard

2. How to Set Up GameCenter Authentication

First, you'll need to authenticate users to GameCenter in order for any of this functionality to work.

So we'll use this code to do that, which basically makes sure that you (GKLocalPlayer.local) are authenticated, or prints an error if there is one:

func authenticateUser() {
    GKLocalPlayer.local.authenticateHandler = { vc, error in
        guard error == nil else {
            print(error?.localizedDescription ?? "")
            return
        }
    }
}

If the user is authenticated, you will see a little popup in the UI. If not, the user will be taken to a page to login to their GameCenter account.

A sign that displays when a user is logged in

3. How to Display Leaderboard Items in the UI

In order to get the data away from the GameCenter ViewController leaderboards (GKLeaderboard), you need to use the loadLeaderboards .

You can switch up the loadEntries function from .global to .friends in order to only pull your friends.

You can also retrieve the image for each player by iterating over each player and performing a loadPhoto.

Using NSRang(1...5), you can choose how many players to display. This pulls the users with the highest 5 scores from the leaderboard and returns none if there's no users, such as in the case when the cycle refreshes for a recurring Leaderboard.

This is what pulling data from a leaderboard could look like if you take advantage of async-await:

func loadLeaderboard() async {
    playersList.removeAll()
    Task{
        var playersListTemp : [Player] = []
        let leaderboards = try await GKLeaderboard.loadLeaderboards(IDs: [leaderboardIdentifier])
        if let leaderboard = leaderboards.filter ({ $0.baseLeaderboardID == self.leaderboardIdentifier }).first {
            let allPlayers = try await leaderboard.loadEntries(for: .global, timeScope: .allTime, range: NSRange(1...5))
            if allPlayers.1.count > 0 {
                try await allPlayers.1.asyncForEach { leaderboardEntry in
                    var image = try await leaderboardEntry.player.loadPhoto(for: .small)
                    playersListTemp.append(Player(name: leaderboardEntry.player.displayName, score:leaderboardEntry.formattedScore, image: image))
                                print(playersListTemp)
                    playersListTemp.sort{
                        $0.score < $1.score
                    }
                }
            }
        }
        playersList = playersListTemp            
    }
}

You can get leaderboard data into your app

4. How to Call Functionality in SwiftUI as the View/Page Appears

You can take advantage of the onAppear lifecycle function of the view to actually make the calls to authenticate and load, but you can also do it on the tap of a button if you prefer that:

.onAppear(){
    if !GKLocalPlayer.local.isAuthenticated {
        authenticateUser()
    } else if playersList.count == 0 {
        Task{
            await loadLeaderboard()
        }
    }
}

5. How to Load the Submitted Scores

In order to load the scores, you need to submit them as well. The submitScore function can help you with that.

• The flightsClimbed variable should contain the score that you would like to submit.
• GameKit makes sure to only display your best score for the life of the leaderboard.
• The leaderboardId contains the value that you manually enter in your App Store Connect account:

func leaderboard() async{
    Task{
        try await GKLeaderboard.submitScore(
            flightsClimbed,
            context: 0,
            player: GKLocalPlayer.local,
            leaderboardIDs: ["com.tfp.stairsteppermaster.flights"]
        )
    }
    calculateAchievements()
}

6. How to display the GameCenter ViewController Portal

When you're logged into GameCenter, a little annoying icon appears in the top right of your screen. When you tap on it, you are taken to the GameCenter ViewController. Luckily you can hide it if it's not part of your design, using GKAccessPoint.shared.isActive = false.

Since the GameCenter UI is a UIKit ViewController and not a simple SwiftUI View, you need to create this UIViewControllerRepresentable first (as you can see here), to launch GameCenter using a different button,

Once you add that file to your project, you can display the GameCenter portal simply using this: GameCenterView(format: gameCenterViewControllerState) where gameCenterViewControllerState can be help you go to a detail page in GameCenter.

GameCenter's Leaderboard View

Things to Keep in Mind While using GameCenter's Leaderboards:

• Simulator Debugging – For some reason the authenticate to GameCenter is extremely slow on a simulator, so it might make sense to even create a mock of data when using the simulator.
• Challenges – You can't programmatically issue GameKit Challenges to your friends anymore due to deprecation. Instead, you have to do those manually within the user's GameCenter dashboard against GameKit Achievements. Also, there's no way to view challenges you have sent.
• Achievements – Leaderboards are different from the GameKit Achievements, which is calculated and displayed differently, but a lot easier. Those can also be pulled into the app as well, as you can see below:

GameKit Challenges and Achievements

Wrapping Up

You can try out the free open-source Stair Master Climber iPhone Health & Fitness app that I shared above. I would love to know what you think so that we can learn together.

Feel free to reach out to me on social media or by email if you have any questions.

Hello everyone! In this article we are going to learn how to use UISearchController in iOS Apps.

What are we going to build?

We are going to build a movie search application which uses the TMDB API to fetch movie info and display it using a UICollectionView based on a user's search query.

Project Setup

Open up Xcode and create a new blank iOS App project – make sure you select UIKit and not SwiftUI.

In this app we are going to use the MVC Pattern so organise the project by creating the following groups and Swift files:

Now close your Xcode project. Open up the terminal and move to your project directory. Here we need to add SD WebImage Cocoa Pods to asynchronously download and cache the movie poster images.

Type the following command in the terminal:

pod init

Now when you list the contents of the directory, you can see that there is a new Podfile. Open the file using any text editor (here I've used Vim). Edit your Podfile so that it looks similar to the below image. Save and close the Podfile.

Now that we have specified the SD WebImage, we can install the dependencies by running the below command:

pod install

As you can see, we have successfully added the SD WebImage pod in our iOS project. Now run the below command to open our project in Xcode.

open PROJECT_NAME.xcworkspace

After opening Xcode, make sure you build your project by hitting Command+B.

How to Design the User Interface using UIKit and Programmatic UI

Our app needs three UIElements navigation bars to hold the search bar, UISearchBarController for actual search, and a UICollectionView to display the search results.

Open up your Scenedelegate.swift file and add the following code inside it which will connect to the session method:

func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        guard let scene = (scene as? UIWindowScene) else { return }
        window = UIWindow(windowScene: scene)       window?.rootViewController=UINavigationController(rootViewController:HomeVC())
        window?.makeKeyAndVisible()
    }

Since we are using a programatic UI, first we need to mention our Root View controller – that is, the first screen which will be displayed when the user launches the app.

Here in this app we're using only one View Controller, so we wrap it inside a UINavigationController. This provides a navigation bar where we can place our UISearchController.

Open up the HomeVC.swift file and add the following properties:

 private var SearchBar: UISearchController = {
        let sb = UISearchController()
        sb.searchBar.placeholder = "Enter the movie name"
        sb.searchBar.searchBarStyle = .minimal
        return sb
    }()

    private var MovieCollectionView: UICollectionView = {
        let layout = UICollectionViewFlowLayout()
        layout.scrollDirection = .vertical
        layout.itemSize = CGSize(width: UIScreen.main.bounds.width/3 - 10, height: 200)
        let cv = UICollectionView(frame: .zero, collectionViewLayout: layout)
        cv.register(MovieCell.self, forCellWithReuseIdentifier: MovieCell.ID)
        return cv
    }()

First we create our UISearchController and configure its properties such as placeholder text and style.

Then we create a UICollectionView and specify the type of layout our collection view should use. In this case it is UICollectionViewFlowLayout and other properties such as scroll direction, item size, and specifying a custom CollectionView cell class which we will create later in our project.

Inside the HomeVC class create a new function and add the following code to configure auto-layout constraints programmatically for our UICollectionView:

    //MARK: - HELPERS
    func configureUI(){
        MovieCollectionView.translatesAutoresizingMaskIntoConstraints = false
        MovieCollectionView.topAnchor.constraint(equalTo: view.topAnchor).isActive = true
        MovieCollectionView.bottomAnchor.constraint(equalTo: view.bottomAnchor).isActive = true
        MovieCollectionView.leftAnchor.constraint(equalTo: view.leftAnchor).isActive = true
        MovieCollectionView.rightAnchor.constraint(equalTo: view.rightAnchor).isActive = true
    }

First we say that we don't need to convert the auto resizing mask into the constraints. Then we pin our collection view to all four sides of our View Controller.

Inside the viewDidLoad() method add the following lines of code:

  override func viewDidLoad() {
        super.viewDidLoad()

        navigationItem.title  = "Movie Search"
        view.backgroundColor = .systemBackground
        SearchBar.searchResultsUpdater = self
        navigationItem.searchController = SearchBar
        view.addSubview(MovieCollectionView)
        MovieCollectionView.delegate = self
        MovieCollectionView.dataSource = self
        configureUI()
    }

Here we first specify the title for our ViewController followed by the background color which is the systemBackground color. If the device is in light mode it shows a white background. If it is in dark mode, then it shows a dark background.

Then we set current the view controller as the search result updater, then add our SearchController to the navigation bar, add the UICollectionView to the ViewController, and setup delegate and datasource. Finally we pin the UICollectionView by using auto-layout.

Create an extension for HomeVC and implement the UISearchResultsUpdating protocol and its stub method updateSearchResults.

extension HomeVC: UISearchResultsUpdating{

    func updateSearchResults(for searchController: UISearchController) {
        guard let query = searchController.searchBar.text else{return}

        }

    }


}

The updateSearchResults() method will be called whenever the text entered in the search bar changes or when the user taps the search button on their keyboard.

Next we need to create that custom UICollectionView cell. Inside the MovieCell.swift file, add the following code:

import Foundation
import UIKit
import SDWebImage

class MovieCell: UICollectionViewCell{

    static let ID = "MovieCell"
    private var MoviePosterImageView: UIImageView = {
        let imageView = UIImageView()
        imageView.contentMode = .scaleAspectFit
      //  imageView.image = UIImage(systemName: "house")
        return imageView
    }()

    override init(frame: CGRect) {
        super.init(frame: frame)
        addSubview(MoviePosterImageView)
        configureUI()
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

}

extension MovieCell{
    func configureUI(){
        MoviePosterImageView.translatesAutoresizingMaskIntoConstraints = false
        MoviePosterImageView.topAnchor.constraint(equalTo: topAnchor).isActive = true
        MoviePosterImageView.bottomAnchor.constraint(equalTo: bottomAnchor).isActive = true
        MoviePosterImageView.leftAnchor.constraint(equalTo: leftAnchor).isActive = true
        MoviePosterImageView.rightAnchor.constraint(equalTo: rightAnchor).isActive = true
    }
    func updateCell(posterURL: String?){
        if let posterURL = posterURL {
            guard let CompleteURL = URL(string: "https://image.tmdb.org/t/p/w500/\(posterURL)") else {return}
            self.MoviePosterImageView.sd_setImage(with: CompleteURL)
        }

    }
}

Here we create our custom collection view cell by sub-classing the UICollectionView class and implementing the init() functions.

We create a UIImageView to display the movie poster image and setup auto-layout constraints for it. Then we create a user defined function which takes the Movie poster URL string a parameter and downloads it asynchronously without affecting the UI Thread/Main thread. It does this by using the SD WebImage CocoaPod which we added earlier.

How to Set Up Our API

Before moving on, you'll need to get your API key for the TMDB API by creating an account (it's free). We are going to use the Movie Search end point of the API which takes the API Key and movie name as parameters.

https://api.themoviedb.org/3/search/movie?api_key=API_KEY_HERE&query=batman

You can examine the API response by running it in Postman.

How to Create a Model for the API Response

Now we get a JSON response from the API. We need to decode them to Swift which we can do by creating a model struct that implements the Codable protocol.

WE can generate the model struct for our JSON response easily by using JSON to Swift websites. Here is the model code for the API response – you can just copy and paste it inside the Model.swift file:

import Foundation

struct TrendingTitleResponse: Codable {
    let results: [Title]
}

struct Title: Codable {
    let id: Int
    let media_type: String?
    let original_name: String?
    let original_title: String?
    let poster_path: String?
    let overview: String?
    let vote_count: Int
    let release_date: String?
    let vote_average: Double
}

struct YoutubeSearchResponse: Codable {
    let items: [VideoElement]
}


struct VideoElement: Codable {
    let id: IdVideoElement
}


struct IdVideoElement: Codable {
    let kind: String
    let videoId: String
}

How to Perform HTTP Requests Using Swift

Now we need to write some Swift code to perform HTTP GET requests which return the JSON response of the API.

Swift provides a URLSession class which makes it easier to write networking code without needing any third party libraries like AFNetworking, AlamoFire, and so on.

Open APIService.swift and add the following code:

import Foundation

class APIService{
    static var shared = APIService()
    let session = URLSession(configuration: .default)

    func getMovies(for Query: String,completion:@escaping([Title]?,Error?)->Void){
        guard let FormatedQuery = Query.addingPercentEncoding(withAllowedCharacters: .urlHostAllowed)  else{return}

        guard let  SEARCH_URL = URL(string: "https://api.themoviedb.org/3/search/movie?api_key=API_KEY_HERE&query=\(FormatedQuery)") else {print("INVALID")
            return}



        let task = session.dataTask(with: SEARCH_URL) { data, response, error in
            if let error = error {
                print(error.localizedDescription)
                completion(nil,error)
            }
            if let data = data {
                do{
                    let decodedData = try JSONDecoder().decode(TrendingTitleResponse.self, from: data)
                 //   print(decodedData)
                    completion(decodedData.results,nil)
                }
                catch{
                    print(error)
                }
            }
        }
        task.resume()
    }
}

Here we created a class named API Service with the singleton pattern so we need an instance for this class as a static member of the class. Then we created a session for our networking task with the default configuration, followed by a user defined method getMovies().

Then we created our networking task – in this case we need to perform HTTP GET requests which can be performed using the dataTask() method of the URLSession class. It takes the URL as a parameter and gives a completion handler which contains data returned from the API, error data if any error has occurred, and a response which has HTTP Response information such as status codes and their corresponding messages.

If there is any error, then we escape out of this function with error data. If not, then we decode our JSON data based on our Swift Model and escape out of this function with the decoded data.

How to Display the Search Results on the UICollectionView

In HomeVC.swift, create a private property which is an array of Title objects. These will hold each movie's info returned by the API.

private var Movies = [Title]()

In HomeVC.swift create an extension for the HomeVC class and implement the UIColletionViewDelegate and UICollectionViewDatasource protocols. Then implement numberOfItemsInSection (which is equal to the number of movies returned by the API) and cellForItemAt (which actually populates the cell with API responses, like download and set the poster image).

 func collectionView(_ collectionView: UICollectionView, numberOfItemsInSection section: Int) -> Int {
        return Movies.count
    }
    func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
        if let cell = collectionView.dequeueReusableCell(withReuseIdentifier: MovieCell.ID, for: indexPath) as? MovieCell{
           // cell.backgroundColor = .systemBackground

            cell.updateCell(posterURL: Movies[indexPath.row].poster_path)
            return cell
        }
        return UICollectionViewCell()

    }

Finally we need to make actual API call which we do inside the updateSearchResults() delegate method which we have implemented previously. Inside that method add the following code:

    func updateSearchResults(for searchController: UISearchController) {
        guard let query = searchController.searchBar.text else{return}
        APIService.shared.getMovies(for:query.trimmingCharacters(in: .whitespaces)) { titles, error in
            if let titles = titles {
                self.Movies = titles
                DispatchQueue.main.async {
                    self.MovieCollectionView.reloadData()
                }

            }
        }

    }

Here, whenever the user types in the search bar or presses the search button, we make an HTTP GET request to fetch a movie (based on the name entered in the search bar). Then we reload the CollectionView which updates the collection view cells with the movie poster.

Note that we need to do this in the Main Thread/UI Thread, because by default iOS automatically makes HTTP request in background thread. This means that we need to use UI/Main Thread to update our UI elements.

Now run your app in the simulator to see the result:

Congratulations! You have learned to use UISearchController in iOS apps.

We just published a 5-hour course on the freeCodeCamp.org YouTube channel that will teach you how to use Swift 5, UIKit, and Xcode to develop iOS apps by building a Netflix clone.

Amr created this course. Amr is an iOS developer who has created many popular tutorials.

In this course you will learn how to implement the MVVM design pattern and create the app from scratch in Xcode. The Netflix code will play videos using the YouTube API.

Here are the sections in this course:

• Introduction and App Demo
• Creating new Xcode Project
• Creating MainTabBarViewController
• Setting HomeViewController TableView
• Setting home TableViewCell and it’s CollectionView
• Creating Table’s HeaderView
• Customizing the navigation bar
• Setting Tableview sections titles
• Sending URL Requests and Parsing JSON response
• Using Extensions
• Consuming API To Fetch Data for each Section
• Refactoring Models
• Creating Custom CollectionViewCell
• Passing data to the CollectionView
• Viewing poster images inside CollectionViewCell
• Creating Upcoming TableView inside Upcoming Tab
• Creating custom TableViewCell from the upcoming table
• Creating TitleViewModel
• Creating Top Search TableView inside TopSearch tab
• Creating SearchResultsViewController to display search results
• Querying database for individual movie
• Using YouTube API
• Parsing YouTube API Response
• Handling selections of cells (Tapping on cells)
• Creating TitlePreviewViewController
• Refactoring TableViewHeader Hero title
• Handling Tapping across all ViewControllers
• Core Data (Best Practices)
• Using Notification Center to update ViewControllers

Watch the full course below or on the freeCodeCamp.org YouTube channel (5-hour watch).

In this tutorial for beginners, you will learn the basics of using SwiftUI to make API calls using the popular Internet Chuck Norris DataBase (ICNDB) as an example. It will display a joke quickly and easily using Swift and SwiftUI.

You'll see how the cross-platform framework SwiftUI lets us use the exact same code across iOS, iPadOS, macOS, watchOS, App Clips and tvOS, which otherwise would have been impossible.

Along with that, you will use async-await that was introduced in Swift 5.5, which works for newer operating systems including iPhones running iOS > v15.0. This really simplifies our work of making data network calls asynchronously on click of a button without freezing the UI thread.

I will share the code changes you'll need to make first. Then in the following section, I will share a brief analysis of the code so beginners can understand what's going on as well.

tvOS app running the code displays a button that retrieves the joke on click

How to Make API Calls in Swift and SwiftUI

First, you'll need a Mac to install Xcode. Once it's installed, open Xcode and create a new project. Then select "App" for iOS, macOS, tvOS, or watchOS.

ContentView

Just update your existing ContentView SwiftUI file to add a Button and use the State variable to refresh the text displayed as the joke returns from ICNDB API:

import Foundation
import SwiftUI
struct ContentView: View {
    @State private var joke: String = ""
    var body: some View {
        Text(joke)
        Button {
            Task {
                let (data, _) = try await URLSession.shared.data(from: URL(string:"https://api.chucknorris.io/jokes/random")!)
                let decodedResponse = try? JSONDecoder().decode(Joke.self, from: data)
                joke = decodedResponse?.value ?? ""
            }
        } label: {
            Text("Fetch Joke")
        }
    }
}
struct ContentView_Previews: PreviewProvider {
    static var previews: some View {
        ContentView()
    }
}
struct Joke: Codable {
    let value: String
}

Fetch a joke!

If you press build/play, the app will build in whatever platform you selected above:

Screenshots of watchOS, macOS, and iOS apps running the same exact code

Code Analysis

If you go to the random joke URL, you'll notice that the data is in JSON format. You can copy that and use a JSON Linter to view its structure to figure out what property of the Joke object is needed.

Based on that, you determine the code above. You use the Codable protocol (aka interfaces) to go from a JSON data object to an actual Swift class or struct, and you create properties for the data you want to store (value in our case).

JSONDecoder helps us parse the JSON string using the Codable object. This works regardless of platform because the page that loads on launching the app has the same name ContentView regardless of platform.

App Clips

App Clips are Apple's latest way of using native app functionality using an "App Clip Code" without having to download the whole application from the App Store.

App Clips work similar to an iOS app – the only difference is that you don't create a new App Clip project. You just need to add the App Clip as a target to an existing iOS app by going to File->New->Target->iOS->App Clip when an existing iOS app is open in Xcode.

If you you wondering about iPhone/iPad Widgets, well they don't animate. So button clicks will just open the corresponding app and can't update text through an external API independently.

Conclusion

In this article, you learned how to make RESTful GET API calls from SwiftUI in the simplest possible way!

Feel free to reach out to me if you have any questions. I figured this out using another article and I thought of simplifying it further. So for more details and ways to make this code more complex, check out that article:

If you're coming from Java, C++, or other object-oriented languages, chances are that you've never come across optional types or "optionals". And you might be quite surprised to know that such a concept exists in Swift.

Optionals are a fundamental topic that you need to thoroughly understand to code in Swift. If you're just getting started with Swift and you're learning about optional types for the first time, make sure to read this article until the end.

To understand what optional types are, let's quickly brush up on constants and variables.

Constants and Variables in Swift

A constant is a data item whose value, once assigned, cannot be mutated (modified or changed) throughout the scope of the program.

On the other hand, a variable is a data item whose value can be changed limitlessly.

There are some nuances in how declare constants and variables in Swift. Let's look at that syntax:

<data-item-type> <var-name>:<data-type> = <value>

Here's an example of a constant:

let pi:Double = 3.1415

And here's an example of a variable:

var message:String = "Hello, this is prajwal"
message = "Coding in swift is awesome" //variable value changed.

Notice that of the keywords we've used here for declaring constants and variables, you use let to declare a constant, and var to declare a variable.

The keyword is then followed by the constant/variable name, a colon and its data type, and then the assigning value.

Swift is a type-safety language, which means that you can assign variables and constants values without specifying the data type. It can make appropriate assumptions based on the assigned value, for example:

let const:String = "String"

can also be written as,

let const = "String"

And,

var speed:Int = 20

can be written as,

var speed = 35

You might be wondering, if you can omit the data type then what's the need to specify it anyway? Well, you're right to wonder that – but you need to specify the data type once you're working with optional types, which are different from conventional data types.

Optional types or Optionals in Swift

Coming to the main point, what are optional types in Swift?

Let's see what the docs have to say about it:

You use optionals in situations where a value may be absent. An optional represents two possibilities: Either there is a value, and you can unwrap the optional to access that value, or there isn’t a value at all.

That's a pretty straightforward definition. So optionals are basically used to handle null values at compile-time to ensure that no crashes occur at runtime.

Any operations on the optional variable are performed only if it contains non-null values.

An optional type can be of any data type, like a String, Integer, Double, Float, or any user defined non-primitive data type (object).

But, it is important to note that the Optional data type is not equivalent to its base data type. For instance, an Optional String is not the same as a string, an Optional integer is not the same as an integer, and so forth. This is because primitive data types cannot handle nil values, but Optional types can.

Optional Types Syntax and Usage in Swift

Here's the syntax for an optional type:

<data-item> <var-name>:<data-type>?

The declaration is similar to declaring regular variables, except that you add a question mark (?) beside the data type which makes it an Optional type.

Fire up your XCode playground and try running these snippets:

let someVal:Double?
someVal = 5.6324

print(someVal)
//Output : Optional(someVal)

var str:String? = nil

str = "Hello, World!"
print(str)
//Output : Optional("Hello, World!")

You can see that the outputs are not regular values. Instead, they're optional values.

How to Unwrap Optional Types in Swift

You won't use optional types upfront for any operations or tasks, as they should be cast in their primitives or user-defined instances before using it elsewhere (an optional string should be cast to a string, an optional integer should be cast to an integer, and so on).

This casting is what's known as unwrapping. You can better understand this concept by thinking about Schrödinger's cat.

In this thought experiment, a cat is placed in a closed box along with a vial of poison. Unless you open the box, you can't assure whether the cat is dead or alive ( nil or non-nil). This means that it is both dead and alive at the same time (nil and non-nil) according to your perception.

Only when you open the box (unwrapping) can you learn if the cat is alive or not (nil or not).

Unwrapping in Swift is essentially verifying if the Optional value is nil or not, and then it performs a task only if it's not nil.

You can perform unwrapping in the following ways:

1. Using an if else block
2. Using Forced unwrapping
3. Using Optional binding
4. Using Optional chaining
5. Using a nil coalescing operator

Unwrap an optional type with an if-else block

Unwrapping means to make sure that the Optional value is not nil. You can do this by using a simple if-else block like this:

var variable:String? //evaluates to nil

if variable != nil{
 print("Not nil")
}
else{
 print("Nil")
}
//Output : Nil

Unwrap an optional type with forced unwrapping

Forced unwrapping is quite contradictory because you're accessing the optional value regardless of its value (nil or not nil). If a nil optional is unwrapped, an error is thrown saying "Unexpectedly found nil while unwrapping an Optional value."

You're supposed to use forced unwrapping only in a pre-defined environment where you're certain that the optional value won't be nil.

You can forcefully unwrap an optional using the exclamatory(!) operator like this:

var color:String?;

print(color!) // Unexpectedly found nil while unwrapping an Optional value

color = "Black";

print(color!) // Black

Unwrap an optional type with optional binding

Optional binding is similar to using an if-else block. The only subtle difference is that if the optional value is not nil, the unwrapped value is assigned to a new constant and further operations are performed on the constant.

You can do this using the if-let statement:

var password:String? = "$tr0ngp@$$w0rd"

if let unwrappedpass = password {
    print("Password is \(unwrappedpass)") //Password is $tr0ngp@$$w0rd
}

An optional string password is assigned the value $tr0ngp@$$w0rd. Then in the if-let block, the optional value password is unwrapped and assigned to the variable unwrappedpass only if the optional value password is not nil. unwrappedpass now contains the unwrapped value and can be used within the block's scope.

var password:String?

if let unwrap = password{ // Block unexecuted, as optional password is nil.
    print("value is not nil")
}

Unwrap an optional type with optional chaining

You use optional chaining in places where you're dealing with multiple optional values at once. You use it to access and mutate or assign far-fetched attributes whose value depends on other constraints.

For example, we get our food from plants, which in turn get their food from sunlight and water.

This means that there is a chained dependency of events – we are dependent on plants for our food, and plants themselves are dependent on water and light for their food.

Optional chaining involves verifying at each dependency if the instance is nil or not.

Let's see how this works with a code example:

class ShipmentCar{
    var seats:Int?
    var quality:String?

    init(seatQty:Int){
        seats = seatQty
    }

    func displaySeatQuality(){
        if let seatQuality = quality{
            print("The seat covering is made of:\(seatQuality)")
        }
    }



}

class CheckSeats{
    var seatExists:ShipmentCar?

}


var obj = ShipmentCar(seatQty:4)
var obj2:CheckSeats?
obj2 = CheckSeats()
obj2?.seatExists = obj
obj2?.seatExists?.quality = "Leather" //Optional chaining, set leather quality of seats, only if seats exist.
obj.displaySeatQuality()
//Output: The seat covering is made of: Leather

In the above example, we have two classes, ShipmentCar which is cargo, and CheckSeats to check if there are any seats in the vehicle.

We first create an instance of the class ShipmentCar and pass the argument as 4 for the number of seats – meaning that there are 4 seats in the vehicle.

Further, we create an optional instance of the class CheckSeats and instantiate it. The attribute seatExists of the class CheckSeats is of the type optional ShipmentCar.

Next, we perform optional chaining on the instance obj2, which we write as obj2?.seatExists?.quality = "Leather". This means that we check if seats exist in the car, and if the seats exist, we define the quality of the seat cover which is Leather. Then we verify by calling the displaySeatQuality and get the desired result.

Here's a small caveat: in the above example, if you set the value of seatQty as 0 instead of 4, it'd still output the same result. This implies that the seat covers are made of leather even though there are 0 seats, which would make no sense.

So, I'd like to mention that this is just an example and the main objective here is to emphasize that the attributes are assigned values only if the dependent attributes are not-nil.

Unwrap an optional type with the nil coalescing operator

The nil coalescing operator works as shorthand notation for the regular if-else block. If a nil value is found when an optional value is unwrapped, an additional default value is supplied which will be used instead.

var text:String?

var output = text ?? "Default value"

print(output) // Default value

text = "This is a string"

output = text ?? "Default String"

print(output) // This is a string

You can also write default values in terms of objects.

Wrapping up

There you have it! In this article, you've learned all about optional types and how to use them.

I'd like to thank you for reading this far and I hope this article has helped you understand optional types in Swift.

If you've any queries, feel free to contact me on Twitter and/or LinkedIn. I'll be happy to help you. Cheers!

Hello, everyone! In this article we are going to learn how to add the Realm database to an iOS app.

We'll create a simple ToDo app so you can learn how to perform CRUD (Create, Read, Update, Delete) operations in the Realm database.

What is Realm?

Realm is an open-source mobile database which is developer friendly and easy to use. You can also use it as an alternative to Core Data in iOS apps.

Realm is a cross platform mobile database, which means that you can use it in native Android and iOS apps and also in cross platform apps like those created using React Native. It supports Objective-C, Swift, Java, Kotlin, C#, and JavaScript.

How to Set Up Realm in Your iOS Project

We can add Realm to our iOS project using SPM (the Swift Package Manager), Cocoa Pods, or Carthage. Here, we are going to use Cocoa Pods to add Realm Pod to our iOS project.

1. Open up Xcode and create a blank iOS app project with UIKit and Swift without using Core Data.
2. Now close Xcode and open up the terminal. Navigate to your project directory using the terminal.
3. Run the following command to create a PodFile.

pod init

4. Now when you list the contents of the directory you can see that there is a new Podfile. Open the file using any text editor (here I've used Vim). Edit your Podfile so that it looks similar to the below image. Save and close the Podfile.

Now that we have specified the dependence for Realm DB, we can install the dependencies by running the below command:

pod install

As you can see, we have successfully added the Realm DB dependency in our iOS project. Now run the below command to open our project in Xcode.

open YOUR_APP_NAME.xcworkspace

Note: after opening Xcode, make sure you build your project by pressing Command+B.

How to Design Your User Interface in Realm

We are going to keep our app's UI simple. Open up Main.storyboard and create a simple UI as shown below by adding a table view with a prototype cell. Then embed a navigation controller and create the IBOutlets for the tableview in the ViewController.swift file:

How to Create a Data Model in Realm

In our ToDo app, each task has a task name and a task id. We are going to create a Model class to represent the todo task. In the project navigator right click and create a new Swift file, and add the below code.

import Foundation
import RealmSwift


class ToDoTask:Object
{
    @objc dynamic var tasknote: String?
    @objc dynamic var taskid: String?
}

Her we created our model class named ToDoTask. It inherits the Object class which is a class that comes with RealmDB. This class handles all the under the hood processes of saving the data created using this model class in the database.

We also added two properties: tasknote, which is the task to be done, and taskid – both of type string. @objc means that your Swift code is visible to Objective C and dynamic means you want to use Objective C dynamic dispatch.

Basic CRUD App functions

Our app will perform the following functions:

1. Get input from the user using AlertViewController.
2. Add the input to the database and also to the table view.
3. Allow the user to edit their input.
4. Swipe to delete a row to remove the data from both the table view and the database.
5. Fetch all the data (if present) from the database and display it in the table view.

How to get input from the user using AlertViewController

Open up ViewController.swift and add the below code inside the ViewDidLoad() method. And create a new function called addTask() and add the code to display the alert view controller with a text box to get input from the user.

Now when the right bar button is pressed it will call the addTask() function which will display the alertviewcontroller with a text field to get user input.

navigationItem.rightBarButtonItem = UIBarButtonItem(image: .add, style: .done, target: self, action: #selector(addTask))

navigationController?.navigationBar.prefersLargeTitles = true

title = "RealmDB"

@objc
    func addTask()
    { 
        let ac = UIAlertController(title: "Add Note", message: nil, preferredStyle: .alert)

        ac.addTextField(configurationHandler: .none)

        ac.addAction(UIAlertAction(title: "Add", style: .default, handler: { (UIAlertAction) in

              if let text = ac.textFields?.first?.text
            {
                print(text)
            }

        }))
        ac.addAction(UIAlertAction(title: "Cancel", style: .cancel, handler: nil))
        present(ac, animated: true, completion: nil)
    }

How to add the input to the database and table view

To save data into Realm, first we need obtain an instance for Realm through which we can access all the methods needed for CRUD operations. Create a property of type Realm in the ViewController.swift file and initialise it in the viewDidLoad() method.

 var realmDB: Realm!

 override func viewDidLoad() {
        super.viewDidLoad()

        navigationItem.rightBarButtonItem = UIBarButtonItem(image: .add, style: .done, target: self, action: #selector(addTask))
        navigationController?.navigationBar.prefersLargeTitles = true
        title = "RealmDB"

        realmDB = try! Realm()

    }

Create an empty array of type our DataModel (ToDoTask). This array will hold all the tasks which need to be added to the table view and database.

Now inside the addTask() function modify the Add action closure so that it gets the user input and creates a random ID for that input. Then append it to our array and save it to the database.

var tasks = [ToDoTask]()

 if let text = ac.textFields?.first?.text
            {
                //Add data to data model array
                let t = ToDoTask()
                t.taskid = UUID().uuidString
                t.tasknote = text
                self.tasks.append(t)

                //Add data to database
                try! self.realmDB.write {
                    self.realmDB.add(t)
                }
                //Update table view UI
                self.tasktv.reloadData()
            }

Now when you run the app, the data will be saved in the database. But it will not show in table view because we have not implemented the delegate methods.

Make the ViewController class implement the UITableViewDelegate and UITableViewDataSource protocols and add the protocol stubs.

Now inside the numberOfRowsInSection method, return the count of our tasks array which gives the number of rows to be added to the table view. This is equal to the number of elements in tasks array.

 func tableView(_ tableView: UITableView, numberOfRowsInSection section: 
 Int) -> Int 
 {
        return tasks.count;
 }

The next thing we need to do is specify the content in each row. We can do this using the cellForRowAt delegate method. Here we dequeue a cell using the identifier which we have mentioned in storyboard and specify the label text as the tasks array element tasknote property.

 func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
        if let cell = tableView.dequeueReusableCell(withIdentifier: "cell")
        {
            cell.textLabel?.text = tasks[indexPath.row].tasknote
            return cell
        }
        return UITableViewCell()
    }

How to allow users to edit their input

Now we have to allow the user to edit their entered tasks and update the changes in both the database and UI. We can do this using similar methods of getting input from the user. Implement the didSelectRowAt delegate method which will be called when user taps the table view row.

Add the below code which displays an AlertViewController with a text view. Then update the content of the cell with the entered text, and at the same time update the database contents.

func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {

        let tasktomodify = tasks[indexPath.row]
        let ac = UIAlertController(title: "Update task", message: nil, preferredStyle: .alert)

        ac.addTextField(configurationHandler: .none)
        ac.addAction(UIAlertAction(title: "Ok", style: .default, handler: { (UIAlertAction) in
            if let text = ac.textFields?.first?.text
            {
                if(!text.isEmpty)
                {
                try! self.realmDB.write({
                    tasktomodify.tasknote = text
                })
                self.tasktv.reloadData()
                }
            }
        }))

        present(ac, animated: true, completion: nil)
    }

How to swipe to delete a row & remove the data from both the table view and database

Here we are going to implement a swipe to delete feature in our table view so that users can delete their tasks. But under the hood when the user swipe deletes a table view row then it should delete the data from database, data model array, and update the UI of the table view.

We can do this by implementing the commit editingStyle delegate method and adding the following code:

 func tableView(_ tableView: UITableView, commit editingStyle: UITableViewCell.EditingStyle, forRowAt indexPath: IndexPath) {
        if editingStyle == .delete
        {
            let tasktoDelete = tasks[indexPath.row]
            try! realmDB.write({
                realmDB.delete(tasktoDelete)
                self.tasks.remove(at: indexPath.row)
                self.tasktv.deleteRows(at: [indexPath], with: .fade)
            })
        }
    }

How to fetch all the data (if present) from the database and display it in the table view

Now we are going to implement our last operation, Read. Whenever the user launches the app, it should fetch data from the database (if data is present) and display it in the table view.

We can do this by creating a function getTodo in the view controller swift file and adding the following code inside it:

func getTodos()
    {
       //Get all the data from the database
        let notes = realmDB.objects(ToDoTask.self)

        //Clear the model data array to prevent duplicates
        self.tasks.removeAll()

        /*If the fetched data is not empty then add it to model data array and update the UI */
        if(!notes.isEmpty)
        {
        for n in notes
        {

            self.tasks.append(n)

        }
            self.tasktv.reloadData()
        }


    }

Bonus Tip: How to View Your Database Content in an iOS Simulator

Now when you run your app, you can see that it works as expected. But how can we check if the data is really stored in the database? We can use an app called MongoDB Realm Studio through which we can view our data stored in the Realm database of the simulator.

Note that this method works only when you test the app using iOS simulator

In the viewDidLoad() method, add the below line of code which will print the real file path of our app:

 print(realmDB.configuration.fileURL!)

Now copy the file path printed in the console, open up the terminal, and run the following command:

open REALM_FILE_PATH_HERE

Make sure you have downloaded MongoDB Realm Studio from the browser before running the above command.

Now it will open the RealmFile of the app in MongoDB Realm Studio. This will display the data stored in the database in a table format.

If you make changes to your data by editing or deleting the task, the changes will be reflected in the MongoDB Realm Studio app:

Congratulations! You have made a simple app which implements CRUD operations in iOS apps.

This is the second part of an article on building a Spotify UI clone with autoLayout programmatically. If you missed the first part, no worries - just please go and check it now.

In this article, we are going to add some mocked pictures and try to make the UI look the same as Spotify's.

This is what we are going to do today ?

This is were we left off in the first part:

The next step is to create customized cells. So let's start by creating one with the name SubCustomCell.

First, create a new Swift file inside the project folder and name it SubCustomCell.swift. This file will contain our custom cell that will represent the Playlist. After creating the file, try to add in the code below and initialize the cell, maybe with backgroundColor, to see the UI changes when we register the cell with the collectionView.

import UIKit

class SubCustomCell: UICollectionViewCell {
        override init(frame: CGRect) {
        super.init(frame: frame)
        backgroundColor = .red
    }

    required init?(coder aDecoder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }
}

Then we register the SubCustomCell inside CustomCell.swift within the init block. Replace UICollectionViewCell.self with SubCustomCell like below.

 collectionView.register(SubCustomCell.self, forCellWithReuseIdentifier: cellId)

Also we need to make a modification on the cellForItemAt method and make it conform to SubCustomCell like the following.

 func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
        let cell = collectionView.dequeueReusableCell(withReuseIdentifier: cellId, for: indexPath) as! SubCustomCell
        // cell.backgroundColor = .yellow

        return cell
    }

You should see the backgroundColor changed to red .

Swift CustomCell

Up until this point everything should be straightforward and clear.

Now we're going to fill the cells with some mocked pictures and create an ImageView inside each cell. I already downloaded some random pictures from pexels.com, but feel free to use any pictures you like (including these). You can find them in the project files on Github.

Let's create the UIImageView inside SubCustomCell.swift and make some constraints.

    let ImageView : UIImageView = {
       let iv = UIImageView()
        iv.backgroundColor = .yellow
        return iv

    }()

And add it to the view within the init block using addSubView.

 override init(frame: CGRect) {
        super.init(frame: frame)
        addSubview(ImageView)

    }

Now let's make the ImageView take up all the space within the cell with the constraints below.

 ImageView.translatesAutoresizingMaskIntoConstraints = false
            ImageView.topAnchor.constraint(equalTo: topAnchor).isActive = true
            ImageView.leftAnchor.constraint(equalTo: leftAnchor).isActive = true
            ImageView.rightAnchor.constraint(equalTo: rightAnchor).isActive = true
            ImageView.bottomAnchor.constraint(equalTo: bottomAnchor).isActive = true

• LeftAnchor represents the left anchor of the cell
• rightAnchor represents the right anchor of the cell
• bottomAnchor represents the bottom anchor of the cell
• topAnchor represents the top anchor of the cell

And by making ImageView 's top anchor equal to the cell's top anchor (and doing the same for ImageView 's left, right, and bottom anchor) it makes the ImageView take up all the space of the SubCustomCell (cell).

Note: first you need to use translatesAutoresizingMaskIntoConstraints to be able to apply the constraints to the elements. Also don't forget to call isActive property and assign it to true – without doing that the constraints won't work and nothing will change.

The ImageView should have an image, so let's add one.

 let ImageView : UIImageView = {
       let iv = UIImageView()
        iv.backgroundColor = .yellow
        // we have >image1< file inside the project 
        iv.image = UIImage(named: "image1")
        iv.contentMode = .scaleAspectFill
        iv.clipsToBounds = true

        return iv

    }()

And if you build and run the app, you should see the results and picture we added to the SubCustomCell.

Cool ?. Now there is an element we should add to the SubCustomCell to finish up. We need a title that will represent the title of the playlist: UILabel.

For the title it will be like this:

 let TitleLabel : UILabel = {
        let lb = UILabel()
        lb.textColor = UIColor.lightGray
        lb.font = UIFont.systemFont(ofSize: 16)
        lb.font = UIFont.boldSystemFont(ofSize: 20)
        lb.text = "Evening Music"

        return lb
    }()

I just put some random text there – you can put whatever you like. The next step is to add the element to the view and give it some constraints. The title will be placed at the bottom of the ImageView.

Add to view:

addSubview(TitleLabel)

Applying the constraints for both the ImageView and the TitleLabel

 ImageView.translatesAutoresizingMaskIntoConstraints = false
            ImageView.topAnchor.constraint(equalTo: topAnchor).isActive = true
            ImageView.leftAnchor.constraint(equalTo: leftAnchor).isActive = true
            ImageView.rightAnchor.constraint(equalTo: rightAnchor).isActive = true
            ImageView.heightAnchor.constraint(equalToConstant: 240).isActive = true
            ImageView.bottomAnchor.constraint(equalTo: TitleLabel.topAnchor).isActive = true



            TitleLabel.translatesAutoresizingMaskIntoConstraints = false
            TitleLabel.topAnchor.constraint(equalTo: ImageView.bottomAnchor,constant: 10).isActive = true
            TitleLabel.leftAnchor.constraint(equalTo: leftAnchor, constant: 5).isActive = true
            TitleLabel.rightAnchor.constraint(equalTo: rightAnchor, constant: -5).isActive = true

And here we go!

We made the picture take up most of the space in the cell, and the rest is taken up by the title. As you can see, you can scroll horizontally in each section and also vertically in the entire screen.

Now we are put some mock data into the cells to make it feel like it's real. For that I created a JSON file that contains some random data for sections and playlists.

First let's create a two structs, Section and Playlist . We create a separate file for each struct.

section.swift

import Foundation
struct Section {
    var title : String
    var playlists : NSArray
    init(dictionary:[String : Any]) {
        self.title = dictionary["title"] as? String ?? ""
        self.playlists = dictionary["playlists"] as? NSArray ?? []

}
}

playlist.swift

//
//  playlist.swift
//  spotifyAutoLayout
//
//  Created by admin on 12/6/19.
//  Copyright © 2019 Said Hayani. All rights reserved.
//

import Foundation
struct PlayList {
    var title: String
    var image : String
    init(dictionary : [String : Any]) {
        self.title = dictionary["title"] as? String ?? ""
        self.image = dictionary["image"] as? String ?? ""
    }

}

And then inside ViewController.swift we create a function that fetches the JSON for us and stores the results in an array.

        print("attempt to fetch Json")
        if let path = Bundle.main.path(forResource: "test", ofType: "json") {
            do {
                  let data = try Data(contentsOf: URL(fileURLWithPath: path), options: .mappedIfSafe)
                  let jsonResult = try JSONSerialization.jsonObject(with: data, options: .mutableLeaves)
                if let jsonResult = jsonResult as? [ Any] {
                            // do stuff
                    jsonResult.forEach { (item) in

                        let section = Section(dictionary: item as! [String : Any])
                       // print("FEtching",section.playlists)
                        self.sections.append(section)
                    }


                  self.collectionView.reloadData()
                  }
              } catch {
                   // handle error
              }
        }
    }

The fetchJson function is called within the ViewDidLoad method. We also have a variable called sections where we store the results:

 var sections = [Section]()

The next step is to pass the data from ViewController to CustomCell. For that we create a variable inside CustomCell which will receive the data for each section:

 var section : Section?{
        didSet{
            print("section ✅",self.section)
        }
    }

We use cellForItemAt inside the ViewController method to pass the data directly to the CustomCell .

override func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
        let cell = collectionView.dequeueReusableCell(withReuseIdentifier: cellId, for: indexPath) as! CustomCell

        cell.section = sections[indexPath.item]

        return cell
    }

Note: we always call self.collectionView.reloadData() every-time fetchJson is called so the block below, inside CustomCell, will be called as well. Check the console, shift + command + C:

 var section : Section? {
        didSet{
            print("section ✅",self.section)
        }
    }

The first thing we change is to set the the section title:

 var section : Section? {
        didSet{
            print("section ✅",self.section)
            guard let section = self.section else {return}
            self.titleLabel.text = section.title
        }
    }

And then you should see that each section has a specific title on the screen ?.

Now it's time to pass the data down to SubCustomCell. We do the same thing as we did above. We need to pass the playlists array, so we create a variable named playlists inside CustomCell.

 var playlists : [PlayList]() //empty

First, we map through the playlists from the JSON. Then we add each playlist with the playlists var.

 var section : Section? {
        didSet{
            print("section ✅",self.section)
            guard let section = self.section else {return}
            self.titleLabel.text = section.title
            // append to playlists array
             self.section?.playlists.forEach({ (item) in
                let playlist = PlayList(dictionary: item as! [String : Any])
                self.playlists.append(playlist)

            })
            self.collectionView.reloadData()
        }
    }

Attention! If you try to run the app it may crash. This is because we forgot to set the number of sections. Since we are now receiving the data from JSON, the number should be dynamic based on the number of sections we have. The number of sections should be equal to the number of sections inside the JSON, so we need to modify numberOfItemsInSection inside ViewController to the below :

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

We do the same thing with the same method inside CustomCell.swift – but here we consider the number of the playlists instead.

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

The last step we have to complete is to pass each single playlist Object to SubCustomCell within cellForItemAt in CustomCell.swift.

 func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
        let cell = collectionView.dequeueReusableCell(withReuseIdentifier: cellId, for: indexPath) as! SubCustomCell
        // here ?
        cell.playlist = playlists[indexPath.item]
        return cell
    }

And we are going to get that data inside SubCustomCell via the playlist variable and finally display the title and image of the playlist.

var playlist : PlayList? {
           didSet{
               print("Playlist ?",self.playlist)
            guard let playlist = self.playlist else {return}
            // The Image ?
            self.ImageView.image = UIImage(named: playlist.image)
            // the playlist title ?
            self.TitleLabel.text = self.playlist?.title

           }
       }

I think everything should work fine now, just as below ?

One last update to the UI: we have to add some padding and margins to the section and playlist titles and make the playlist a little bit smaller.

Let's first add some padding for the section titles. To do that, we need just to give the constant property some number value inside the section cell CustomCell and within setupSubCells:

 collectionView.topAnchor.constraint(equalTo: titleLabel.bottomAnchor,constant: 15).isActive = true

And if you see the entire collectionView come in at the bottom of the titleLabel, all we need to do is add more space by adding 15:

Next we come to the title of the playlist. This will be inside SubCustomCell, and we just need to add more space at the bottom of the ImageView.

 ImageView.bottomAnchor.constraint(equalTo: TitleLabel.topAnchor,constant: -15).isActive = true

We already have the constant there. In order for it to work, the value should be -15

Finally the playlist needs to be a little bit smaller. This is easy: we just make the playlist cell's height and width equal to the section cell's height divided by 2, just like below:

CustomCell.swift

 func collectionView(_ collectionView: UICollectionView, layout collectionViewLayout: UICollectionViewLayout, sizeForItemAt indexPath: IndexPath) -> CGSize {

        let width = frame.height / 2
        let height = frame.height / 2

        return CGSize(width: width, height: height)

    }

Make the ImageView's height equal to 150 as well.

  //SubCutomCell.swift
  ImageView.heightAnchor.constraint(equalToConstant: 150).isActive = true

And here we go ?.

Perfect! I think that's enough for today – I don't want to make this article too long. So we will have another part where we will add the TabBar and the description, as well as some icons for the playlist.

View the Full source code on GitHub?.

Thanks for your time. I hope I haven't missed anything. If I did please @mention me on Twitter, or if you have any questions or an addition to this post the doors are always open to anyone. Thanks??.

Subscribe to my email list to be notified when the third part of this tutorial is published.

By the way, I’ve recently worked with a strong group of software engineers for one of my mobile applications. The organization was great, and the product was delivered very quickly, much faster than other firms and freelancers I’ve worked with, and I think I can honestly recommend them for other projects out there. Shoot me an email if you want to get in touch — said@devsdata.com.

If you are looking to become an iOS developer, there are some fundamental skills worth knowing. First, it's important to be familiar with creating table views. Second, you should know how to populate those table views with data. Third, it's great if you can fetch data from an API and use this data in your table view.

The third point is what we'll cover in this article. Since the introduction of Codable in Swift 4, making API calls is much easier. Previously most people used pods like Alamofire and SwiftyJson (you can read about how to do that here). Now the Swift way is much nicer out of the box, so there's no reason to download a pod.

Let's go through some building blocks that are often used to make an API call. We'll cover these concepts first, as they are important parts to understanding how to make an API call.

• Completion handlers
• URLSession
• DispatchQueue
• Retain cycles

Finally we'll put it all together. I'll be using the open source Star Wars API to build this project. You can see my full project code on GitHub.

Disclaimer alert: I am new to coding and am largely self-taught. Apologies if I misrepresent some concepts.

Completion handlers

Poor patient Pheobe

Remember the episode of Friends where Pheobe is glued to the phone for days waiting to speak with customer service? Imagine if at the very start of that phone call, a lovely person called Pip said: "Thanks for calling. I have no idea how long you'll need to wait on hold, but I'll call you back when we're ready for you." It wouldn't have been as funny, but Pip is offering to be a completion handler for Pheobe.

You use a completion handler in a function when you know that function will take a while to complete. You don't know how long, and you don't want to pause your life waiting for it to finish. So you ask Pip to tap you on the shoulder when she's ready to give you the answer. That way you can go about your life, run some errands, read a book, and watch TV. When Pip taps on you on the shoulder with the answer, you can take her answer and use it.

This is what happens with API calls. You send a URL request to a server, asking it for some data. You hope the server returns the data quickly, but you don't know how long it will take. Instead of making your user wait patiently for the server to give you the data, you use a completion handler. This means you can tell your app to go off and do other things, such as loading the rest of the page.

You tell the completion handler to tap your app on the shoulder once it has the information you want. You can specify what that information is. That way, when your app gets tapped on the shoulder, it can take the information from the completion handler and do something with it. Usually what you'll do is reload the table view so the data appears to the user.

Here's an example of what a completion handler looks like. The first example is setting up the API call itself:

func fetchFilms(completionHandler: @escaping ([Film]) -> Void) {
  // Setup the variable lotsOfFilms
  var lotsOfFilms: [Film]

  // Call the API with some code

  // Using data from the API, assign a value to lotsOfFilms  

  // Give the completion handler the variable, lotsOfFilms
  completionHandler(lotsOfFilms)
}

Now we want to call the function fetchFilms. Some things to note:

• You don't need to reference completionHandler when you call the function. The only time you reference completionHandler is inside the function declaration.
• The completion handler will give us back some data to use. Based on the function we've written above, we know to expect data which is of type [Film]. We need to name the data so that we can refer to it. Below I'm using the name films, but it could be randomData, or any other variable name I'd like.

The code will look something like this:

fetchFilms() { (films) in
  // Do something with the data the completion handler returns 
  print(films)
}

URLSession

URLSession is like the manager of a team. The manager doesn't do anything on her own. Her job is to share the work with the people in her team, and they'll get the job done. Her team are dataTasks. Every time you need some data, write to the boss and use URLSession.shared.dataTask.

You can give the dataTask different types of information to help you achieve your goal. Giving information to dataTask is called initialization. I initialism my dataTasks with URLs. dataTasks also use completion handlers as part of their initialization. Here's an example: