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.

The product requirement is identical on both platforms. The contracts underneath are opposites.

On iOS, Apple Push Notification service (APNs) updates a system-owned SwiftUI widget for you, and your app code never runs. On Android there's no system-managed remote update at all. A data-only Firebase Cloud Messaging (FCM) message wakes a background service, and your own code re-posts the notification every single time.

In this handbook you'll build both. You'll write one TypeScript API backed by two native implementations: a Swift one that talks to ActivityKit and a Kotlin one that talks to NotificationManager. You'll also write an APNs client and an FCM client from scratch, in about sixty lines each, with no libraries. And you'll learn the silent failure modes that make this API hard, because almost every mistake here produces no error at all.

I built a delivery-tracking demo called DropTrack to work through this. Everything below comes from that build, including a three-device Samsung investigation that ends with a screenshot of a hardcoded allowlist.

Table of Contents

1. Prerequisites

2. What Live Activities and Live Updates Actually Are

3. Where You Have Already Seen This Feature

4. Why You Need a Custom Native Module

5. How the iOS Contract Works

6. How to Build the Widget in SwiftUI

7. How to Bridge ActivityKit to JavaScript

8. Four iOS Gotchas That Cost Me an Evening Each

9. How to Drive iOS From a Server With APNs

10. How to Write an APNs Client From Scratch

11. How to Test on Real Hardware

12. Why Android Has No ActivityKit

13. How to Build the Kotlin Side

14. How to Drive Android From a Server With FCM

15. Three UX Gaps the Naive Implementation Leaves

16. How to Script the Simulators and Devices

17. How iOS and Android Compare

18. The Samsung Reality Check

19. The Demo Repository

20. What to Know Before You Start

21. Conclusion

22. Sources and Further Reading

Prerequisites

To follow along, you'll need:

• Node.js 20 or later.

• Xcode 26 or later, plus a paid Apple Developer account. APNs requires a real signing key and a device build. The simulator can't receive Live Activity pushes.

• Android Studio with an API 36 emulator built from a google_apis system image. Google Play services are required for FCM, and a bare Android Open Source Project image doesn't include them.

• A Firebase project, for the Android half.

• Working knowledge of Swift, Kotlin, and TypeScript. This is a native modules article, not a JavaScript-only one.

The versions I used throughout:

The androidx.core version isn't optional. Version 1.17.0 backports the Android 16 promotion APIs so they compile against base SDK 36. I'll explain why in a moment.

What Live Activities and Live Updates Actually Are

A Live Activity isn't a push notification. A notification is a fire-and-forget event. A Live Activity is a persistent, glanceable card with its own state that changes in place, a bounded lifetime, and dedicated system surfaces.

Here's where each platform landed:

• iOS 16.1 introduced lock-screen Live Activities. 16.2 added the Dynamic Island. 17.2 added push-to-start. 18 added broadcast channels. See Apple's ActivityKit documentation and the Live Activities Human Interface Guidelines.

• Android 16 (API 36) introduced Notification.ProgressStyle, the segmented progress bar.

• Android 16 QPR1 (API 36.1), the first Quarterly Platform Release, introduced the promotion pipeline: the status-bar chip and the elevated lock-screen slot. Google calls the whole feature progress-centric notifications.

I built DropTrack to exercise all of it. An order moves through seven steps, from "Order placed" to "Arriving now". A courier can be reassigned mid-run. The card is driven either locally from an in-app console or remotely from a push.

Where You Have Already Seen This Feature

Before any code, it helps to know why this API exists, because "a card on the lock screen" undersells it.

Think about the last time you ordered food. You place the order, lock your phone, and then what? Without a Live Activity, the app's only way to reach you is a push notification per state change. Order confirmed. Restaurant is preparing your food. Rider assigned. Rider is two stops away. Rider has arrived.

That's five notifications for one order. Multiply that by every order, and you've trained the user to mute you.

A Live Activity replaces all five with one card that mutates in place. Same information with one surface and no notification fatigue. That's the entire product argument.

Apple's own Human Interface Guidelines name the recurring use cases: sports scores, workouts, rides, and deliveries. Google's progress-centric notifications documentation converges on almost the same list, stating that "key use cases include rideshare, delivery, and navigation." That page even describes the delivery example in terms of progress points for food preparation and delivery milestones, and segments colored by traffic conditions, which is precisely the widget you're about to build.

Apps That Have Shipped it

Rather than repeat the roundup posts, I checked each app's own App Store listing, because a company describing its own feature is the strongest evidence available. Every app below states that it uses Live Activities in its own words:

Apple ships them in its own software, too. The Apple Sports support page says that with Live Activities turned on "you can get real-time information on your iPhone Lock Screen or your Apple Watch so that you can follow every moment of the game."

Two more are well documented by the technology press rather than by the companies themselves. Uber Eats rolled out Live Activities in May 2023, showing order status, estimated time of arrival, and the driver's name and photo. DoorDash followed in December 2023 with a real-time estimated time of arrival in the Dynamic Island.

Two honest caveats about that table. First, an app not mentioning Live Activities in its listing doesn't mean it lacks the feature, only that I couldn't confirm it first-hand. Uber Eats is exactly that case. Second, this reflects the listings as I read them, and any app can add or drop the feature in a release.

Food delivery is the canonical case, and it's what DropTrack models. Ride-hailing is the highest-stakes version: "driver arriving in 3 minutes", the plate number, the trip in progress, glanced at while you stand on a curb with a locked phone. The Dynamic Island's compact presentation exists almost for this: a glyph and a percentage read in half a second.

Finance is the case people forget, and it's where a segmented bar would earn its keep. A crypto deposit isn't "pending, then done". It's "3 of 12 network confirmations", which is a segmented progress bar with discrete steps, mapping cleanly onto ProgressStyle's segments and points and onto the SwiftUI capsules you will write below. The same shape fits a bank transfer clearing or a card payment settling.

I want to be careful here, though: I checked the App Store listings for the major exchanges and neobanks and found none that documents a Live Activity. Treat this one as an obvious fit that the category hasn't yet taken up, not as prior art.

Here's the table I wish someone had shown me before I started:

Look at the third column. In every commercially interesting case the update is driven by your server, not by the device. That means the entire value of the feature lives in the push path. And the push path is exactly where the two platforms diverge, where the failures are silent, and where most of this handbook's pain is concentrated.

The pretty SwiftUI card is the easy half. Getting a backend to reliably mutate that card while the app is dead is the hard half, and it's different on each platform.

Why You Need a Custom Native Module

Before writing a line of Swift, I evaluated the shortcuts. Both fail, for instructive reasons.

expo-live-activity ships a predefined widget layout and a fixed content-state shape. DropTrack needs a custom segmented progress bar, a rider-reassignment treatment, and its own Dynamic Island layouts. All of those require owning ActivityAttributes and the SwiftUI that renders it. You reach first render fastest, and then you eject.

Notifee, the notification library most React Native developers reach for, is archived. As of this writing its GitHub repository is marked archived, its last published release was @notifee/react-native@9.1.8 in December 2024, and its Android module still targets compileSdk 34. It has no Live Updates support. A custom module is currently the only React Native route to Android 16 Live Updates.

So: one local Expo module, one TypeScript API, two native backends.

modules/droptrack-live/
├── expo-module.config.json   ← autolinking (apple + android)
├── index.ts                  ← the public JS API
├── src/                      ← TS types, native binding, web no-op
├── ios/
│   ├── DeliveryAttributes.swift    ← the ActivityKit contract
│   └── DroptrackLiveModule.swift   ← JS to ActivityKit
└── android/
    ├── DroptrackLiveModule.kt      ← JS to NotificationManager
    ├── DeliveryNotifier.kt         ← the shared notification builder
    └── DroptrackFcmService.kt      ← push to NotificationManager

The JavaScript surface is deliberately small, and identical across platforms:

// The dynamic half of the card: every update replaces this object wholesale.
// Keep it small. iOS rejects an ActivityKit push payload over 4 KB.
export type DeliveryState = {
  status: string;           // free text shown as the headline: "Picked up"
  progress: number;         // 0.0 to 1.0, drives the bar on both platforms
  etaEpochMillis: number;   // Unix ms, the shape JS speaks. Swift converts it.
  stopsRemaining: number;   // renders as "2 stops away" / "you're next"
  courierName: string;      // dynamic, because riders get reassigned mid-run
  riderReassigned: boolean; // flips the courier row to the "new rider" style
};

// Three verbs, mirroring the ActivityKit lifecycle. Android fakes the same
// shape with notify / notify / cancel, so callers never branch on platform.

// Starts the activity and returns the system-assigned id. Hold on to it:
// every later call needs it, and it does NOT survive an app restart.
startDelivery(info: DeliveryInfo, state: DeliveryState): Promise<string>;

// Replaces the ContentState in place. The card mutates, it does not re-appear.
updateDelivery(id: string, state: DeliveryState): Promise<void>;

// Final state, then dismissal. Omit dismissAfterSeconds to let the card linger.
endDelivery(id: string, state: DeliveryState, dismissAfterSeconds?: number): Promise<void>;

isSupported(): boolean;          // false on iOS < 16.2, Android < 16, and web
areActivitiesEnabled(): boolean; // false if the USER switched them off in Settings

Those last two are separate on purpose. A device can support Live Activities while the user has switched them off in Settings, and only areActivitiesEnabled() catches that. Activity.request throws in that case, so startDelivery throws too.

The dismissAfterSeconds argument maps onto ActivityKit's dismissal policy. Under the default policy, Apple's documentation says "the system keeps a Live Activity that ended on the Lock Screen for up to four hours after it ends." Passing a value shortens that window.

This project uses Expo's Continuous Native Generation (CNG), which means the ios and android folders are generated by prebuild and aren't committed. Every line of native code therefore lives in the module or in a config plugin, so it survives prebuild --clean. The widget extension itself is generated by @bacons/apple-targets for the same reason.

One structural detail matters later: the module compiles as its own CocoaPod, not into the app target.

How the iOS Contract Works

An ActivityKit activity is split in two. ActivityAttributes holds static data, set once and never changed. Its nested ContentState holds the dynamic half, which every update replaces wholesale.

Most tutorials state that rule and move on. It's worth understanding why the platform forces it, because the reason tells you exactly which half any given field belongs in.

Why the Split Exists

The split isn't a style convention. It's about what can physically cross the wire.

When you call Activity.request(...), you hand ActivityKit two things at once: the attributes and the first content state. The system files the attributes away and never accepts a new copy of them. From that moment on, the only thing you can ever send is a new ContentState.

You can see this in the shape of an ActivityKit push payload. Here's what my APNs client actually transmits:

aps: {
  // Older-than-last timestamps are discarded by APNs (ordering guard).
  timestamp: Math.floor(Date.now() / 1000),
  event,                        // "update" or "end"
  'content-state': contentState, // the only field that carries data
}

There is no attributes key. There can't be one. Nothing in the payload can reach the static half.

So "should this field be static or dynamic?" is really the question "will my server ever need to change this value?" If the answer is yes, the field must live in ContentState, because that's the only thing a push can move.

That's the whole design. ActivityAttributes is the activity's identity, fixed at birth. ContentState is its current reading, replaced wholesale on every update rather than patched. Send a content state that omits a field and you haven't left that field alone, you've failed to decode. The Codable conformance is what lets the system serialize the state across a process boundary, and the Hashable conformance lets it tell whether an incoming state actually differs from the one already on screen.

The Bet I Lost

Here's what I wrote first. It looks reasonable:

// BEFORE: courierName is static. This compiles, ships, and works fine,
// right up until a dispatcher reassigns the rider mid-delivery.
struct DeliveryAttributes: ActivityAttributes {
  public struct ContentState: Codable, Hashable {
    var status: String
    var progress: Double
    var eta: Date
    var stopsRemaining: Int
  }
  var orderId: String
  var courierName: String   // the bet: a delivery has one courier
}

Putting a field in the static half is a bet that it can never change for the activity's lifetime. I bet that a delivery has one courier. Then I built rider reassignment, where a dispatcher swaps the courier mid-run, and the bet came due.

Because courierName was static, there was no way to express the change. Not through activity.update(), not through a push, not at all. The only escape would have been to end the activity and start a new one, which means the card disappears from the lock screen and returns as a different card, mid-delivery. That's not a fix, it's a regression.

So the field moved:

// AFTER: only orderId is genuinely immutable. Everything a dispatcher
// can change lives in ContentState, because ContentState is the only
// thing an APNs push can carry.
struct DeliveryAttributes: ActivityAttributes {
  public struct ContentState: Codable, Hashable {
    /// Human-readable status, e.g. "Picked up", "2 stops away"
    var status: String
    /// Overall delivery progress, 0.0 ... 1.0
    var progress: Double
    /// Estimated arrival time
    var eta: Date
    /// Stops before the courier reaches the user
    var stopsRemaining: Int
    /// Courier display name, dynamic since riders can be reassigned mid-run
    var courierName: String
    /// True right after a reassignment, drives the "new rider" treatment
    var riderReassigned: Bool
  }

  /// Order identifier shown on the card, the only truly immutable fact
  var orderId: String
}

Moving one field touched twelve files, because the contract is duplicated at every layer that has to encode or decode it:

9  DeliveryNotifier.kt          Android notification builder
3  DroptrackLive.types.ts       the TypeScript contract
3  DroptrackLiveModule.swift    the Swift bridge record
3  App.tsx                      React state and the push handler
2  DeliveryLiveActivity.swift   the widget's SwiftUI
2  DeliveryAttributes.swift     the module's copy
2  DeliveryAttributes.swift     the widget's copy (yes, twice)
2  DroptrackLiveModule.kt       the Kotlin bridge record
1  DroptrackFcmService.kt, dispatch-server.mjs, push-update.mjs,
   apns.test.mjs, delivery.ts

The asymmetry here is what matters. A dynamic field you never change costs you a few bytes in every push. A static field you need to change costs you the entire stack. When in doubt, put the field in ContentState. In the end, only orderId earned its place in the static half.

The Identical-Copy Trap

The widget extension is a separate binary. It's a different process, launched by the system, that doesn't link your app's code. Your app target compiles the module's DeliveryAttributes.swift. The widget target compiles its own. Two compilations produce two independent types that merely share a name.

At runtime, ActivityKit has to connect them. Your app says "start an activity of type DeliveryAttributes", and the system asks the widget whether it has a WidgetConfiguration for a type by that name whose ContentState decodes this data. The match is structural, on the type's name and its Codable shape, performed by a system daemon, at runtime, across a process boundary.

Now rename courierName to riderName in one copy and forget the other. The app compiles. The widget compiles. Both are internally consistent. Activity.request() succeeds and returns an id. But when the system hands the encoded state to the widget, the widget's decoder looks for riderName, doesn't find it, and throws inside a daemon in another process, where your breakpoints and your log statements don't exist.

The card never appears. No crash, no warning, no console line, and Activity.activities still lists the activity as running. You'll spend an hour on your SwiftUI layout, and the layout was never the problem.

Two things follow. A shared source file doesn't save you, because the module compiles as its own CocoaPod rather than into the app target, so no build phase naturally covers both. And since the compiler will never catch this, the check has to be external:

diff modules/droptrack-live/ios/DeliveryAttributes.swift \
     targets/widgets/DeliveryAttributes.swift

If that command ever prints anything, your Live Activity is already broken. It costs nothing to wire into a pre-commit hook, and it's the single highest-value guardrail in this project.

How to Build the Widget in SwiftUI

The widget declares one Widget with two presentations: the lock-screen card and the Dynamic Island.

Before reading the code, hold one idea in your head: these closures are a pure function from state to view. The widget extension isn't a running program. The system launches the process, calls your closure with the current ContentState, keeps the rendered result, and kills the process.

When a push delivers a new state, it runs the closure again. There's no @State, no timer, no network call, and no onAppear doing work. That's also why widget extensions have no network access: there's nobody home to make a request.

Two things about the type signature before the code. Widget is a WidgetKit protocol, not a SwiftUI View, and body returns some WidgetConfiguration, not some View. You're not describing pixels, you're declaring what kind of widget this is.

And the for: argument on line 3 is the binding point from the previous section: this is the exact spot where the app's DeliveryAttributes and the widget's copy are matched by name and Codable shape, so it's where the identical-copy trap either works or silently fails.

struct DeliveryLiveActivity: Widget {
  var body: some WidgetConfiguration {
    ActivityConfiguration(for: DeliveryAttributes.self) { context in
      // Closure 1 of 2: the lock screen and banner.
      DeliveryCardView(context: context)
        .activityBackgroundTint(Color(red: 0.07, green: 0.07, blue: 0.12))
        .activitySystemActionForegroundColor(.white)

    } dynamicIsland: { context in          // closure 2 of 2, labelled
      DynamicIsland {
        // Expanded (long-press): four named slots, arranged around the cutout.
        DynamicIslandExpandedRegion(.leading) {
          Image(systemName: "bicycle").foregroundStyle(brandOrange)
        }
        DynamicIslandExpandedRegion(.trailing) {
          Text(context.state.eta, style: .time).font(.callout.bold())
        }
        DynamicIslandExpandedRegion(.center) {
          Text(context.state.status).font(.callout.weight(.semibold)).lineLimit(1)
        }
        DynamicIslandExpandedRegion(.bottom) {
          VStack(spacing: 4) {
            SegmentedProgressBar(progress: context.state.progress)
            HStack {
              CourierLabel(state: context.state, compact: true)
              Spacer()
              Text(stopsLabel(context.state.stopsRemaining))
            }
            .font(.caption2).foregroundStyle(.secondary)
          }
        }
      } compactLeading: {                   // the default pill, left of the cutout
        Image(systemName: "bicycle").foregroundStyle(brandOrange)
      } compactTrailing: {                  // ...and right of it
        Text("\(Int(context.state.progress * 100))%").font(.caption2.bold())
      } minimal: {                          // when another app shares the island
        Image(systemName: "bicycle").foregroundStyle(brandOrange)
      }
      .keylineTint(brandOrange)
    }
  }
}

That's one state object rendered four ways, and a few of the choices are load-bearing:

• The two closures: ActivityConfiguration takes a content closure and a dynamicIsland: closure. The bare-then-labelled form is Swift's multiple-trailing-closure syntax, not two separate statements. The first is the lock-screen and banner card, and the second is every Dynamic Island form.

• context: Each closure receives context.state, the dynamic ContentState replaced on every update, and context.attributes, the static half, read exactly once, for the order id on the card.

• The two .activity… modifiers: These are ActivityKit-specific, not general SwiftUI. You don't draw the system's swipe-to-end chrome, so all you can do is tint it.

• eta, style: .time renders a localized clock time such as "5:42 PM", honouring the user's 12- or 24-hour setting. It's not a countdown. A ticking countdown would use style: .timer, which the system animates with no push at all, which is how a timer-style activity stays live with zero server traffic.

• lineLimit(1) isn't decoration. The centre slot is a few dozen points wide, and an unbounded status string wraps and wrecks the layout. The bar lives in .bottom for the opposite reason: it's the only region wide enough.

• .font and .foregroundStyle on the HStack apply to both children through SwiftUI's environment, and a child's explicit modifier still wins over the inherited one, which is how CourierLabel overrides the colour on a reassignment.

• Int(progress * 100) truncates rather than rounds, so 0.999 would render as "99%". The scripted steps end on exactly 1.0 so it lands on 100, but server-computed progress would want .rounded().

• minimal is the presentation people forget. When another app's activity is also running, the island shrinks yours to a single circle. Skip it and your activity looks broken whenever a timer is going. keylineTint sets the glow the system draws around the whole island on update.

The Segmented Progress Bar

The capsule bar is an HStack of rounded rectangles. ContentState carries progress as a double rather than a step index, so the widget derives how many segments to fill.

private struct SegmentedProgressBar: View {
  let progress: Double
  var segments: Int = 7   // one capsule per delivery step

  // ContentState carries a 0...1 fraction, never a step index, so the bar has
  // to work backwards to a segment count. Keeping the wire format numeric means
  // the widget never needs to know what the seven steps are called.
  private var filled: Int {
    // Clamp first: a server that sends 1.4 must not paint 10 of 7 segments.
    let clamped = min(max(progress, 0), 1)
    // .rounded(.up) so a step that has merely BEGUN already lights its capsule.
    // progress 0.05 * 7 = 0.35 -> ceil -> 1 segment lit, not 0.
    // The outer min() guards the exact 1.0 case against a 8th segment.
    return min(segments, Int((clamped * Double(segments)).rounded(.up)))
  }

  var body: some View {
    HStack(spacing: 5) {
      // ForEach over a constant range, so `id: \.self` on the index is safe.
      ForEach(0..<segments, id: \.self) { i in
        RoundedRectangle(cornerRadius: 3, style: .continuous)
          // The only stateful decision in the whole view: lit, or track colour.
          .fill(i < filled ? brandOrange : trackGray)
          // Fixed height, no width: the HStack divides the width evenly, so the
          // same view fits the wide lock-screen card and the narrow island.
          .frame(height: 7)
      }
    }
  }
}

With progress values of 0.05, 0.15, 0.35, 0.55, 0.7, 0.85, 0.95, and 1.0, rounding progress * 7 upward fills one through seven segments in lockstep with the steps. The same view renders on the lock-screen card and inside the expanded island, so the component reads as one thing across surfaces.

The Reassignment Treatment

Reassignment is an in-place update: same activity id, same step, new courierName, and riderReassigned set to true. The courier row swaps its icon and copy.

// Shared by the lock-screen card and the expanded island, so a reassignment
// reads identically wherever the user happens to be looking.
private struct CourierLabel: View {
  let state: DeliveryAttributes.ContentState
  let compact: Bool   // true inside the island, where horizontal space is scarce

  var body: some View {
    // Both branches are driven purely by ContentState. No local state, because
    // the widget process does not live long enough to hold any.
    if state.riderReassigned {
      Label(
        // The island cannot fit "New rider · Tunde", so it drops the prefix and
        // leans on the swap icon plus the orange tint to carry the meaning.
        compact ? state.courierName : "New rider · \(state.courierName)",
        systemImage: "arrow.triangle.2.circlepath"
      )
      // An explicit style on the child overrides the .secondary the parent
      // HStack pushed down through the environment. This is what makes the
      // swapped rider the one thing on the card that draws the eye.
      .foregroundStyle(brandOrange).bold()
    } else {
      // Steady state: inherits the parent's caption font and secondary colour.
      Label(state.courierName, systemImage: "bicycle")
    }
  }
}

Advancing a step retires the badge. That's the whole feature, and the reason courierName had to leave the static half.

How to Bridge ActivityKit to JavaScript

Expo's Record type gives you type-safe bridging. Expo validates the JavaScript object against these fields before your function body runs.

// A Record is Expo's typed bridge struct. Every @Field is decoded out of the
// JS object BEFORE your function body runs, so a missing or wrong-typed key
// fails at the boundary with a clear error rather than deep inside Swift.
// The defaults are what a field falls back to when JS omits it.
struct DeliveryStateRecord: Record {
  @Field var status: String = ""
  @Field var progress: Double = 0
  @Field var etaEpochMillis: Double = 0   // Double, not Int: JS numbers are f64,
                                          // and epoch ms overflows Int32.
  @Field var stopsRemaining: Int = 0
  @Field var courierName: String = ""
  @Field var riderReassigned: Bool = false

  // The bridge type and the ActivityKit type are deliberately NOT the same
  // struct. This function is the single place the two vocabularies meet.
  @available(iOS 16.2, *)
  func toContentState() -> DeliveryAttributes.ContentState {
    DeliveryAttributes.ContentState(
      status: status,
      // Clamp at the boundary, so no downstream view has to defend itself.
      progress: min(max(progress, 0), 1),
      // JS speaks Unix milliseconds; Foundation.Date wants seconds. Divide once,
      // here, rather than scattering /1000 through the codebase.
      eta: Date(timeIntervalSince1970: etaEpochMillis / 1000),
      stopsRemaining: stopsRemaining,
      courierName: courierName,
      riderReassigned: riderReassigned
    )
  }
}

And the module itself:

AsyncFunction("startDelivery") { (info: DeliveryInfoRecord, state: DeliveryStateRecord) -> String in
  // Runtime OS guard: the module compiles against older targets, so this is
  // what stops it calling into a framework that isn't there.
  guard #available(iOS 16.2, *) else { throw LiveActivityUnsupportedException() }

  let activity = try Activity.request(
    attributes: DeliveryAttributes(orderId: info.orderId),                  // static half, set once
    content: ActivityContent(state: state.toContentState(), staleDate: nil), // dynamic half
    pushType: .token                                                        // ask APNs for a token
  )
  return activity.id   // the only handle JS gets, and the one it forgets on reload
}

AsyncFunction("updateDelivery") { (activityId: String, state: DeliveryStateRecord) in
  let activity = try Self.findActivity(id: activityId)
  // .update() replaces the whole ContentState. There is no partial-patch API.
  await activity.update(ActivityContent(state: state.toContentState(), staleDate: nil))
}

A few notes on the arguments, so they stay out of the code. AsyncFunction (rather than Function) is what makes the JS side a Promise, and Expo infers the rest of the signature from the parameter types.

staleDate: nil means the card is never marked stale. Pass a date and, once it passes, the system flips the activity's state so your widget can read context.isStale and render a degraded view, but it doesn't grey the card out for you.

And pushType: .token is what asks APNs for a per-activity token, where passing nil instead gives you a purely local activity that no server can update.

Notice findActivity. Activities are looked up fresh by id on every call rather than cached in a property, because activity handles live inside ActivityKit, not in your process. That distinction matters enormously, as the next section shows.

@available(iOS 16.2, *)
private static func findActivity(id: String) throws -> Activity<DeliveryAttributes> {
  // `Activity.activities` is a live, system-owned list. It survives an app
  // relaunch, a JS reload, and a process kill. Caching a handle in a Swift
  // property would not, which is precisely why this lookup runs every time.
  guard let activity = Activity<DeliveryAttributes>.activities.first(where: { $0.id == id }) else {
    // Reached when the user swiped the card away, or the activity aged out.
    throw ActivityNotFoundException(id)
  }
  return activity
}

Four iOS Gotchas That Cost Me an Evening Each

Each of these wasted an evening because the failure looked like a bug in my code when it was really a quirk of the platform. They share a shape, so I've written each one the same way: the symptom you see, why it happens, and what to do about it.

Gotcha 1: The Compact Island Looks Broken

You build the compact Dynamic Island, run the app, and it never appears.

This happens because the compact presentation is hidden while your own app is in the foreground. This is by design, but nothing tells you so, and I spent twenty minutes certain my layout was wrong.

To fix this, lock the device, or switch to another app, before you judge whether the island works. There's nothing to fix in the code.

Gotcha 2: An Old Activity Renders Nothing After a Rebuild

You change the widget, rebuild, and an activity that was already running goes blank. No error appears anywhere.

This happens when an activity is tied to the exact build that started it. Once you rebuild the widget extension, the running activity no longer matches the code on the device.

To fix this, after any change to the widget extension, end the stale activity and start a fresh one. Don't expect a warning to remind you.

Gotcha 3: Reinstalling Can Jam the System Daemon

Right after simctl install, your first activity refuses to render. Activity.activities says it's active, yet the screen shows nothing.

This happens because Live Activities are drawn by a background system process called chronod. A reinstall can leave it wedged: in my case it threw widgetDescriptorNotFound and logged internal errors, and no amount of ending and restarting the activity cleared it.

This is a fault in the daemon, not in your app, which is why the usual checks mislead you. Listing the extension with pluginkit -m shows it present and healthy while the daemon behind it is stuck.

To fix this, reboot the simulator with simctl shutdown && boot, then start a fresh activity.

Gotcha 4: Tapping the Card Opens an App That Forgot Everything

This is the subtle one, the most visible to users, and the reason for the next two code samples.

The user taps the live card to open your app. The app launches into an empty screen that insists nothing is being tracked, every control disabled, while the card sits right there on the lock screen still updating.

This happens because tapping the card cold-starts the app, which means your JavaScript begins from scratch. The activity id lived in React state, and that state died with the previous process.

The activity itself is completely fine: Activity.activities still lists it, and an APNs push to it still returns 200. (A dead activity returns 410, which makes a handy liveness probe.) The app simply forgot the id it needs to reconnect.

To fix this, stop treating your in-memory id as the source of truth, and ask the system what is running on launch. Expose the live activities to JavaScript.

AsyncFunction("getRunningActivities") { () -> [[String: Any]] in
  guard #available(iOS 16.2, *) else { return [] }

  // The system's list, populated even on a brand-new process. That is the point.
  return Activity<DeliveryAttributes>.activities.map { activity in
    self.observePushToken(of: activity)   // resubscribe: see note below
    let state = activity.content.state    // the live state, kept current by push
    return [
      "activityId": activity.id,                // the handle JS lost
      "orderId": activity.attributes.orderId,   // the static half
      "status": state.status,
      "progress": state.progress,
      "courierName": state.courierName,
      "riderReassigned": state.riderReassigned,
    ]
  }
}

That observePushToken call is the line everyone misses. The for await loop watching this activity's push token died with the previous process, so without resubscribing here the card recovers. But the server never learns the token again after a rotation, and pushes quietly stop landing.

Then rehydrate on mount, and again on every foreground, because a push that lands while you're backgrounded updates the widget without running your JavaScript at all. React Native's AppState gives you the hook.

useEffect(() => {
  const sync = () => {
    void DroptrackLive.getRunningActivities().then((running) => {
      const activity = running[0];
      if (!activity) return;   // nothing running: leave the empty state alone

      setActivityId(activity.activityId);   // this line re-enables the whole UI
      setRider({ name: activity.courierName, justReassigned: activity.riderReassigned });

      // The card carries a status string, not a step index. Guard the -1.
      const index = STEPS.findIndex((s) => s.status === activity.status);
      if (index >= 0) setStepIndex(index);
    });
  };

  sync();   // case 1: cold start (e.g. the user tapped the card and we launched)
  const sub = AppState.addEventListener("change", (s) => {
    if (s === "active") sync();   // case 2: resume from background
  });
  return () => sub.remove();
}, []);

The whole tracking interface is gated on activityId, so restoring it is what turns the app back on. Miss that one line and the app looks dead while the card is live on the lock screen.

The two call sites cover the two ways state goes stale. sync() on mount handles a cold start, and the AppState listener handles a resume, because the mount effect won't re-run and a push may have advanced the card while you were backgrounded without executing any JavaScript. The empty dependency array means this wiring is set up once, for the app's lifetime.

That last gotcha generalises into the sentence I wish I'd read first: Live Activities are owned by the system, not by your process. The API hands you an activity id and it's easy to assume the id is yours to keep. It's not. The activity outlives the variable, and the moment a user is most likely to open your app, by tapping the live card, is precisely the moment your in-memory copy of that id doesn't exist.

How to Drive iOS From a Server With APNs

Here's the payoff: updating the card while the app is fully force-quit. The API surface is almost insultingly small. You change one argument. Apple documents the flow in Starting and updating Live Activities with ActivityKit push notifications.

let activity = try Activity.request(
  attributes: attributes,
  content: ActivityContent(state: state.toContentState(), staleDate: nil),
  pushType: .token   // this was `nil`. That is the entire feature.
)

Task {
  for await tokenData in activity.pushTokenUpdates {
    let token = tokenData.map { String(format: "%02x", $0) }.joined()   // raw Data -> hex
    NSLog("[DropTrack] push token for %@: %@", activity.id, token)       // NSLog, so devicectl sees it
    self.sendEvent("onPushTokenReceived", ["activityId": activity.id, "token": token])
  }
}

pushTokenUpdates is an AsyncSequence, not a one-shot getter, which is why this is a for await loop and not a single read. Reading activity.pushToken right after request() reliably returns nil, because the token hasn't arrived from APNs yet, and it can also rotate mid-flight.

The token arrives as raw Data, so it's hexed before use. It's logged with NSLog rather than print because a standalone Release build has no Metro to receive console.log, and NSLog is what devicectl --console surfaces. And the token is per-activity, so it's keyed by activity id when handed to JS rather than stored globally.

Everything after that is plumbing, and two pieces of it fail without a single error message.

pushType: .token does nothing without the aps-environment entitlement. Activity.request still succeeds. Local updates still work. The token stream simply never yields. Nothing logs. Add the entitlement in app.json:

"ios": {
  "entitlements": {
    "aps-environment": "development",
    "com.apple.security.application-groups": ["group.com.fasarticle.droptrack"]
  }
}

Two notes on those values, since app.json can't carry comments. aps-environment set to development means your tokens are only valid against api.sandbox.push.apple.com. A shipping build needs production, and mixing the two produces an afternoon of BadDeviceToken. The application group is the shared container between the app and the widget extension, and both targets must carry the identical group id or shared reads silently return nothing.

Then verify that the entitlement survived signing, because an entitlement in your config isn't the same as an entitlement in your binary:

# Reads the entitlements actually baked into the signed .app.
# If aps-environment is absent here, the token stream will never yield,
# no matter what app.json says.
codesign -d --entitlements - --xml Build/Products/Release-iphoneos/DropTrack.app

The push token is per-activity, not per-device. It arrives asynchronously after request() returns, and the system can rotate it mid-flight. Consume the pushTokenUpdates async sequence. A single read of activity.pushToken immediately after request() is reliably nil. Every startDelivery mints a brand-new token. I verified that by starting two activities and comparing the hex.

How to Write an APNs Client From Scratch

You don't need a library. Two Node.js built-ins and about sixty lines will do it.

Sending one push comes down to three steps. First, sign a token that proves the request is really from you. Second, open a connection to Apple and attach a precise set of headers. Third, send the state you want the card to show. The rest of this section walks each step, then covers the two ways it fails silently.

One thing to get out of the way first: APNs speaks HTTP/2 only, so fetch() can't reach it. You need Node's node:http2 module, which is why this is written by hand rather than as a fetch call.

Step 1: Sign a Token That Proves Who You Are

APNs won't accept a push until you prove you own the app. You do that with an ES256 JSON Web Token, signed by the .p8 key you download from Apple, following Establishing a token-based connection to APNs. A JWT is just three base64url chunks joined by dots: a header, a claims object, and a signature over the first two.

import { createPrivateKey, sign } from "node:crypto";

const b64url = (buf) => Buffer.from(buf).toString("base64url");   // JWT uses base64url, not base64

export function mintJWT({ keyPath, keyId, teamId }) {
  const header = b64url(JSON.stringify({ alg: "ES256", kid: keyId }));   // kid: the 10-char key id
  const claims = b64url(JSON.stringify({ iss: teamId, iat: Math.floor(Date.now() / 1000) }));
  const signingInput = `${header}.${claims}`;   // a JWT signs header AND claims joined

  const signature = sign("sha256", Buffer.from(signingInput), {
    key: createPrivateKey(readFileSync(keyPath, "utf8")),
    dsaEncoding: "ieee-p1363",   // THE line. The default (DER) fails silently. See below.
  });

  return `${signingInput}.${b64url(signature)}`;
}

That one dsaEncoding line is the whole reason to write this by hand rather than trust a snippet off the internet.

Node signs in DER format by default, which wraps the signature's two halves in an envelope, but the JWT standard (RFC 7518) wants those two halves raw and joined. Use the wrong one and APNs answers 403 InvalidProviderToken, which reads like your key is bad and sends you re-downloading the .p8 for an hour, when the key was fine all along.

Two smaller details. kid is the ten-character key id (it is in the .p8 filename), and it tells APNs which of your registered keys should check the signature. And the iat timestamp can't be more than an hour old, per Apple, which also asks you to refresh it no more than once every 20 minutes, so cache the token instead of minting a fresh one for every push.

Step 2: Open the Connection and Send the Push

With the token in hand, open an HTTP/2 session to the APNs host and make one POST. The headers have to be exact, and the one people get wrong is the topic: it's your bundle id with .push-type.liveactivity appended, not the bundle id on its own.

// Pseudo-headers (":method", ":path") are HTTP/2's way of encoding the request
// line. `client` here is an http2 session opened against the APNs host.
const req = client.request({
  ":method": "POST",
  // The device token in the path is the PER-ACTIVITY token, not a device token
  // from UNUserNotificationCenter. Those are different values entirely.
  ":path": `/3/device/${token}`,
  authorization: `bearer ${jwt}`,   // lowercase "bearer" is what APNs expects

  // Live Activity pushes get a SUFFIXED topic. Send the bare bundle id and
  // APNs rejects the request outright.
  "apns-topic": `${bundleId}.push-type.liveactivity`,
  "apns-push-type": "liveactivity", // must match the topic suffix
  "apns-priority": "10",            // 10 = deliver immediately, 5 = opportunistic
  "apns-expiration": "0",           // 0 = do not retry a failed push
});

req.end(JSON.stringify({
  aps: {
    // Ordering guard, in SECONDS. APNs discards a push whose timestamp is older
    // than the last one it applied, so out-of-order retries cannot rewind the card.
    timestamp: Math.floor(Date.now() / 1000),
    event: "update",              // "update" mutates the card, "end" finishes it
    // Decoded straight into the widget's Codable ContentState. Field names and
    // types must match that struct EXACTLY. See the eta trap below.
    "content-state": contentState,
  },
}));

The body is small on purpose. timestamp is an ordering guard in seconds: APNs drops any push older than the last one it applied, so a delayed retry can't rewind the card. event is "update" to change the card or "end" to finish the activity, and there's no "start" here because push-to-start is a separate token that needs iOS 17.2. Everything else lives in content-state, which the widget decodes directly, and that's where the second silent failure hides, below.

How to Test Your Auth Without a Phone

This one trick saved me the most time, so do it before you involve a device at all. Send a push to the sandbox using a deliberately fake device token, and read the response code APNs gives back.

• 400 BadDeviceToken is the good outcome. It means your key, key id, team id, and JWT encoding are all correct, and APNs got far enough to look up the token and simply not find it. Your auth works.

• 403 InvalidProviderToken means the token itself is wrong, so the problem is your key or your signing, not the device.

That single request separates "my auth is broken" from "my token is broken" with no phone in the room. On this project it returned 400 on the first try, which told me the auth was solid and I should look elsewhere for the real bug. That was exactly the reassurance I needed.

The eta Trap: a 200 That Renders Nothing

This is the most instructive bug in the project, and it hit the moment a second code path reused a shared helper.

The same delivery data takes two different routes to the widget, and the routes expect two different shapes. The native module path carries etaEpochMillis (Unix milliseconds), and Swift converts it into a Date on the way through. The push path skips Swift entirely: the JSON content-state is decoded directly by the widget's Codable struct, which expects a field literally named eta, holding seconds since 2001 (Apple's reference date), and knows nothing about etaEpochMillis.

So if you reuse the native-bridge object as a push payload, APNs returns 200, iOS quietly throws the update away because it won't decode, and nothing is logged anywhere. The fix is to translate at the boundary, converting to the widget's shape only when building a push.

const APPLE_EPOCH_OFFSET = 978_307_200;   // seconds between 1970 and 2001

// The shape the WIDGET decodes, not the shape the native bridge takes.
function toContentState({ etaEpochMillis, ...rest }) {
  return {
    ...rest,
    eta: Math.floor(etaEpochMillis / 1000) - APPLE_EPOCH_OFFSET,   // ms->s, then rebase to 2001
  };
}

Two details make this work. Foundation.Date's reference point is 2001-01-01, not the Unix epoch, and Swift's Codable encodes a Date as seconds since that date, which is why the offset is subtracted. And destructuring etaEpochMillis out of rest is what drops the wrong key: leave it in and the widget's Codable init sees an unexpected field next to a missing eta, fails to decode, and the update vanishes after a 200.

The lesson generalises past the eta field. A 200 from APNs means only that Apple accepted your bytes, not that the card changed. Any content-state that fails to decode is discarded with no error on any surface, so confirm on the lock screen every time rather than trusting the status code.

Two last environment traps to note. Development-signed builds must talk to api.sandbox.push.apple.com, because the production host returns 400 BadDeviceToken for a sandbox token, which looks exactly like a malformed token and sends you debugging the wrong layer. And if you push frequently, add NSSupportsLiveActivitiesFrequentUpdates to your Info.plist, or the system budgets and drops your rapid pushes.

How to Test on Real Hardware

The simulator will lie to you about push, so at some point you need a real phone. Four things can trip you up there that the documentation never mentions. Here is each one with the fix.

Build in Release, not Debug

A Debug build expects to download its JavaScript from Metro over your local network. The build script bakes your Mac's network address into the app, so the moment the phone is on a different network, or simply not tethered to your Mac, it shows a red screen reading No script URL provided. There's no adb reverse equivalent on iOS to paper over this.

Build with --configuration Release instead, which embeds the JavaScript bundle inside the app. That's the more honest test anyway, because a Release build is the only way to fully force-quit the app and prove the push, not a live Metro connection, is doing the work.

Read Logs with devicectl, Not console.log

Once you drop Metro, console.log has nowhere to go. To read something like a push token off the device, you need the app's real standard output, and NSLog in the Swift code plus devicectl on the Mac is the reliable way to get it.

# --console            stream the app's stdout/stderr back to this terminal
# --terminate-existing kill a running copy first, so we catch launch-time logs
# --device             the COREDEVICE id (see the identifier trap below)
xcrun devicectl device process launch --console --terminate-existing \
  --device <coredevice-id> com.fasarticle.droptrack
# → [DropTrack] push token for 3095ACA0-...: 80875cb137590013a4c9...
#   ^ the hex string the dispatch server scrapes and pushes to

Know Which of the Two Device Identifiers You Need

The same phone has two identifiers, and the tools disagree about which they want. expo run:ios --device wants the hardware UDID, listed by xcrun xctrace list devices. The devicectl command above wants the CoreDevice identifier, listed by xcrun devicectl list devices.

Pass one where the other belongs and you get No device UDID or name matching, which reads as though the phone is unplugged. It's not, so check that you copied the right kind of id before you check the cable.

Handle Cold-start Deep Links, Not Just Live Ones

If your test driver opens the app with a deep link, note that devicectl ... --payload-url cold-starts the app, so the link arrives through Linking.getInitialURL() rather than the url event that the simulator's simctl openurl fires. A driver that listens only for the url event will appear to do nothing on a device. Handle both entry points.

With all four handled and the app confirmed fully quit, I drove three pushes through it (a status change, a rider reassignment, and an "arriving now"). Each one rendered on the lock screen and in the Dynamic Island.

One bonus comes free. Sign the Mac into the same Apple ID, and Continuity mirrors the same Live Activity onto the macOS menu bar, segmented bar, and all. One APNs push, three surfaces.

Why Android Has No ActivityKit

Android has no equivalent of ActivityKit, so there's no system-owned card and no framework keeping it up to date. What you have instead is an ordinary notification that you keep re-posting.

The trick is the notification id. Re-post under the same id and Android replaces the existing notification in place, which reads as an update. Post under a new id and you get a second notification instead. So the three lifecycle verbs map onto plain notification calls:

• start is notify() with a fresh id.

• update is notify() again under that same id.

• end is a final notify() with ongoing = false, followed by a delayed cancel().

That is the entire model. The catch is that everything iOS did for you (keeping the card current, recovering it after a restart, and updating it from a push) is now code you have to write.

The Trap That Shapes Everything: Android 16 is Two Releases in One

One versioning quirk shapes the whole Android side, so it's worth thirty seconds up front. "Android 16" ships as two releases that share a single API number:

Both report 36 because Build.VERSION.SDK_INT, the value your code reads to check the OS version, is a plain integer with no room for a .1. Two different releases, one number.

That collision is the entire source of the friction, and it leaves you three things to handle. None is hard once you know it is coming.

1. Compile through the backport, not the platform classes

The promotion methods (setRequestPromotedOngoing, setShortCriticalText, and the POST_PROMOTED_NOTIFICATIONS permission) live only in the 36.1 SDK, and React Native 0.86 compiles against base 36. Call them on the platform classes directly and the build fails with "no such method" before the app ever runs. One dependency fixes that:

dependencies {
  // NotificationCompat backports the 36.1 promotion APIs so they compile
  // against base SDK 36. Without this, ProgressStyle, setRequestPromotedOngoing
  // and setShortCriticalText are simply not on the classpath.
  implementation 'androidx.core:core-ktx:1.17.0'
}

Call the NotificationCompat versions rather than the platform ones. They compile against 36, take effect on a real 36.1 device, and are ignored on older releases, so one build is safe everywhere.

2. Read SDK_INT_FULL only when you truly need the minor version

A normal SDK_INT >= 36 check can't tell base 36 from 36.1, since both say 36. When you genuinely need to know which release you are on, Build.VERSION.SDK_INT_FULL carries the minor version, with named values in Build.VERSION_CODES_FULL. Because of rule 1 you rarely need it for the promotion request itself. You reach for it to decide what to show the user, or to guard the call in rule 3.

3. Wrap the capability check so it can't crash you

NotificationManager.canPostPromotedNotifications() reports whether the device will actually honour a promotion. Its reference lists it as added in API 36, so in theory it belongs to base Android 16, while the POST_PROMOTED_NOTIFICATIONS permission it depends on only arrived in 36.1. On the pre-QPR build I tested, though, the call was absent at runtime and threw. A capability probe should never be the thing that crashes your app, so wrap it and default to false:

Function("canPostPromotedNotifications") {
  // Function, not AsyncFunction: this is a cheap synchronous read, and the UI
  // wants it during the first render to decide what to disable.
  val manager = notificationManager ?: return@Function false

  // Cheapest gate first: below API 36 there is nothing to promote to.
  if (Build.VERSION.SDK_INT < 36) return@Function false

  // Docs list this as added in API 36, but on the pre-QPR build I tested it was
  // absent at runtime and threw. runCatching stops a capability probe from
  // crashing the app, defaulting to false when the call is unavailable.
  return@Function runCatching { manager.canPostPromotedNotifications() }.getOrDefault(false)
}

How to Build the Kotlin Side

Here's the notification builder. Notice how many of these lines are promotion requirements rather than cosmetics.

// Whole percent, clamped: a server that sends 1.4 must not become 140.
val progressPercent = (progress.coerceIn(0.0, 1.0) * 100).toInt()

val builder = NotificationCompat.Builder(ctx, CHANNEL_ID)
  .setSmallIcon(R.drawable.ic_delivery)
  .setContentTitle(status)                     // promotion REQUIRES a title
  .setContentText(courierLine(courierName, riderReassigned, stopsRemaining))
  .setSubText("Order $orderId")
  .setOngoing(ongoing)                         // promotion REQUIRES ongoing
  .setOnlyAlertOnce(true)                      // buzz once, then update silently
  .setColor(BRAND_ORANGE)                      // NOT setColorized: that disqualifies it
  .setShortCriticalText("$progressPercent%")   // text inside the status-bar chip
  .setRequestPromotedOngoing(ongoing)          // the promotion request itself

// `when` is the ETA in the header. It must be in the future (see note below).
if (etaEpochMillis > System.currentTimeMillis()) {
  builder.setWhen(etaEpochMillis.toLong()).setShowWhen(true)
}

if (Build.VERSION.SDK_INT >= 36) {
  val style = NotificationCompat.ProgressStyle()
    .setStyledByProgress(true)                 // colour follows the value
    .setProgress(progressPercent)
    .setProgressTrackerIcon(IconCompat.createWithResource(ctx, R.drawable.ic_delivery))
    .setProgressSegments(listOf(               // segments: spans of the bar
      NotificationCompat.ProgressStyle.Segment(100).setColor(BRAND_ORANGE)
    ))
    .setProgressPoints(listOf(                 // points: milestone dots on top
      NotificationCompat.ProgressStyle.Point(35).setColor(Color.WHITE)
    ))
  builder.setStyle(style)
} else {
  builder.setProgress(100, progressPercent, false)  // pre-16 fallback bar
}

val notification = builder.build()
if (Build.VERSION.SDK_INT >= 36) {
  Log.d(TAG, "hasPromotableCharacteristics=${notification.hasPromotableCharacteristics()}")
}
manager.notify(notificationIdFor(activityId), notification)   // stable id = update in place

Several of those lines carry non-obvious weight:

• setOnlyAlertOnce(true) stops each of the seven re-posts per delivery from buzzing the phone. Only the first notify() alerts, and the rest land silently.

• setColor versus setColorized: setColor tints the notification and is fine, but setColorized(true) would disqualify it from promotion. They're not interchangeable.

• setWhen must be a future timestamp, or the update can be skipped entirely. One UI renders it as an absolute clock time, Pixel as a relative countdown.

• ProgressStyle segments versus points: Segments are spans of the bar (one Segment(100) fills the whole thing, several draw the divided look). Points are milestone dots painted on top at a given percent.

• The else branch: Below API 36 the compat layer has no ProgressStyle at all, so it falls back to the classic determinate bar.

Two runtime checks are your only debugging signal, and they answer different questions:

• hasPromotableCharacteristics(), logged after build(), tells you whether you satisfied every promotion precondition. It says nothing about the device.

• canPostPromotedNotifications() tells you whether the device will honour the request. The two genuinely disagree on Samsung, which is why you need both.

And notificationIdFor() derives a stable int from the activity id, so a re-post under the same id updates the card in place. A different id would post a second notification, the classic "why do I have seven delivery cards" bug.

Promotion eligibility is all-or-nothing, and silent. It flips true only when every condition holds: notification permission, setRequestPromotedOngoing(true), ongoing, a content title, an allowed style, importance above MIN, and not colorized. Miss one and you get an ordinary notification with no explanation. Log hasPromotableCharacteristics() after every build(), and surface canPostPromotedNotifications() in your development interface. Those two booleans are the only debugging signal the platform gives you.

Note also that custom RemoteViews aren't allowed for promoted notifications. You get the ProgressStyle template, or you get no promotion. That's the biggest design constraint compared with iOS, where you write arbitrary SwiftUI.

When it does promote on a real API 36.1 build, you get the chip and the elevated lock-screen slot.

The same APK behaves three different ways:

How to Drive Android From a Server With FCM

This is the deepest difference between the two platforms.

On iOS, APNs updates the widget through the system, and your app code never runs. On Android, there's no system-managed remote update. A data-only FCM message wakes a FirebaseMessagingService, and your code re-posts the notification. The app is the updater, even from the background.

// Registered in the manifest, so Android can instantiate it WITHOUT your
// Activity, your React context, or your module ever existing.
class DroptrackFcmService : FirebaseMessagingService() {

  // Called on install, and again whenever FCM rotates the token. Never assume
  // the token you saw at startup is still valid.
  override fun onNewToken(token: String) {
    Log.i(DeliveryNotifier.TAG, "[DropTrack] fcm token: $token")
  }

  override fun onMessageReceived(message: RemoteMessage) {
    // FCM `data` is always Map<String, String>. Every number and boolean was
    // stringified on the way out and has to be parsed back here.
    val d = message.data

    // No activityId means we cannot address a notification. Bail rather than
    // guess: posting under the wrong id creates a duplicate card.
    val activityId = d["activityId"] ?: return
    val event = d["event"] ?: "update"

    // This service is a SEPARATE entry point. It cannot see the module's
    // in-memory state, so every field must come from the payload, and every
    // parse must be defensive, because a crash here kills the update.
    DeliveryNotifier.ensureChannel(this)   // the process may be brand new
    DeliveryNotifier.post(
      ctx = this,
      activityId = activityId,
      // Every `?:` below is load-bearing. toDoubleOrNull returns null rather
      // than throwing on malformed input, so a bad payload degrades the card
      // instead of killing the service.
      orderId = d["orderId"] ?: "",
      status = d["status"] ?: "",
      progress = d["progress"]?.toDoubleOrNull() ?: 0.0,
      etaEpochMillis = d["etaEpochMillis"]?.toDoubleOrNull() ?: 0.0,
      stopsRemaining = d["stopsRemaining"]?.toIntOrNull() ?: 0,
      courierName = d["courierName"] ?: "",
      riderReassigned = d["riderReassigned"]?.toBoolean() ?: false,
      // "end" clears `ongoing`, which lets the user finally swipe the card away.
      ongoing = event != "end",
    )
  }
}

That "separate entry point" comment is the crux, so it's worth slowing down on. Android can start this service on its own to deliver a push, at a moment when the rest of your app isn't running. There's no React, no module instance, and none of the objects the app was holding in memory. So the push handler can't look up "what delivery is in progress" from app state, because there's no app state to look at. Everything it needs has to come from the push payload itself.

That forces a specific design. The code that builds a notification can't live inside the app and read app state. It has to be standalone code that takes plain values and nothing else.

So I pulled all of it into a shared DeliveryNotifier object, and both paths call it: the in-app path when JavaScript drives an update, and the push path when the service does. Because they run the same builder from the same inputs, they produce an identical notification, and that shared builder is the single most important structural change on the Android side.

The Four Rules of Android Push

Four things have to be right, or the push half quietly fails. In short: send the right kind of message, authenticate the harder way, read the error codes correctly, and wire the plugin through prebuild. Each one in full below.

Rule 1: send a data-only message, never one with a notification block

This is the rule that catches everyone. A message with a notification block, while the app is backgrounded or killed, is handled by the system tray, and your onMessageReceived code never runs, so the card never updates. Only a data-only message (no notification block) reaches your code in the background.

Firebase documents this in Receive messages in an Android app. Send data-only, and set android.priority to high so the app wakes promptly.

Rule 2: authenticate with a service-account token, not a static key

FCM v1 auth is heavier than APNs, with no one-shot .p8. You mint an RS256 JWT from a service account, exchange it for a short-lived OAuth access token, and send that access token as a bearer credential to projects.messages.send. The consolation is that FCM v1 is plain HTTPS, so fetch() works.

// `sa` is the parsed service-account JSON from Firebase. This JWT is not the
// credential you send to FCM; it is the one you trade for a short-lived token.
export function buildAuthJWT(sa) {
  const now = Math.floor(Date.now() / 1000);
  const header = b64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));  // RSA key, so no ieee-p1363 trap
  const claims = b64url(JSON.stringify({
    iss: sa.client_email,
    scope: "https://www.googleapis.com/auth/firebase.messaging",  // exact scope, or every send 403s
    aud: sa.token_uri,        // the JWT is FOR Google's token endpoint
    iat: now,
    exp: now + 3600,          // one hour, Google's maximum
  }));
  const signingInput = `${header}.${claims}`;
  const sig = createSign("RSA-SHA256").update(signingInput).sign(sa.private_key);
  return `${signingInput}.${b64url(sig)}`;
}

export async function sendDataMessage({ token, data, sa }) {
  const accessToken = await getAccessToken(sa);   // trades the JWT for a token; cache the result
  const res = await fetch(
    `https://fcm.googleapis.com/v1/projects/${sa.project_id}/messages:send`,
    {
      method: "POST",
      headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
      body: JSON.stringify({
        message: {
          token,                        // per-DEVICE token (APNs is per-activity)
          data,                         // note: NO `notification` key (see below)
          android: { priority: "high" },
        },
      }),
    }
  );
  const body = await res.json().catch(() => ({}));   // never throw on a bad error body
  return { status: res.status, reason: body?.error?.status ?? null };
}

The design turns on two absences and one indirection. The indirection is the token exchange. Unlike APNs, where the JWT is the credential, here you POST the JWT to Google's token endpoint, get back a short-lived access token, and send that, so cache it rather than re-minting per message.

The first absence is any notification key in the body, which is deliberate and covered next. The second is high priority over normal, because normal may be held until the device leaves Doze, by which time the delivery has finished.

On the response, 404 UNREGISTERED means drop the token while 400 INVALID_ARGUMENT means it was never a token. The caller needs to tell those apart, so the reason string is returned rather than swallowed.

FCM data values are a map of string to string, so everything is stringified on the way out and parsed on the way in. Unlike iOS, there's no silent shape mismatch, because you wrote the parser. But your parser must never throw.

Rule 3: treat 400 and 404 as different failures

FCM splits two cases that APNs collapses. A malformed token returns 400 INVALID_ARGUMENT, while a well-formed but unregistered token returns 404 UNREGISTERED (the full list is in the FCM ErrorCode reference).

APNs reports both as BadDeviceToken. This matters for the fake-token auth probe from the iOS section: on FCM a fake token gives INVALID_ARGUMENT, not UNREGISTERED. Either one still proves your auth works, since a bad service account fails earlier with 401 or 403. I wrote my probe expecting UNREGISTERED, and correcting the test is how I learned the distinction.

Rule 4: wire the google-services plugin through prebuild

The google-services plugin is what reads your Firebase config into the build. Because Continuous Native Generation regenerates the android folder on every prebuild, a config plugin has to re-place google-services.json and re-add the Gradle wiring each time, or the setting is lost on the next prebuild.

// plugins/withAndroidFcm.js
function withGoogleServicesJson(config) {
  // withDangerousMod runs arbitrary filesystem work during prebuild. It is
  // "dangerous" because nothing validates the result. It is also the only way
  // to place a file the Gradle plugin expects to already exist.
  return withDangerousMod(config, ["android", (cfg) => {
    // Kept at the repo root, gitignored, and copied in on every prebuild.
    const src = path.join(cfg.modRequest.projectRoot, "google-services.json");
    // Must land in android/app/, where the google-services plugin looks for it.
    const dest = path.join(cfg.modRequest.platformProjectRoot, "app", "google-services.json");

    // Fail loudly at prebuild. Without this the build succeeds, the app starts,
    // and FCM initialisation quietly no-ops at runtime.
    if (!fs.existsSync(src)) {
      throw new Error("[withAndroidFcm] google-services.json not found at project root");
    }

    fs.copyFileSync(src, dest);
    return cfg;
  }]);
}
// plus withProjectBuildGradle for the classpath,
// and withAppBuildGradle to apply the plugin.

Have it throw when the file is missing. Failing fast at prebuild beats a mystery at runtime.

The Honest Caveat

A data message can be dropped under Doze or after a force-kill. An iOS Live Activity is system-owned and updates regardless. High priority helps. This is a platform limitation to document rather than engineer around. Test with the app backgrounded, not swiped away, and be honest with your product team about the difference.

Three UX Gaps the Naïve Implementation Leaves

Because your code owns the Android side, you inherit three responsibilities that iOS handles quietly for you. I shipped all three only after hitting each one in testing.

Tapping the Notification Does Nothing

NotificationCompat posts happily, but with no setContentIntent(PendingIntent) there is no tap target, so Android just expands and collapses the notification. Nothing in the documentation shouts this at you.

private fun launchIntent(ctx: Context, activityId: String): PendingIntent? {
  // Ask the package manager for our own launcher intent, rather than naming
  // MainActivity. Under Expo's Continuous Native Generation that class name is
  // generated, so hardcoding it breaks on the next prebuild.
  val intent = ctx.packageManager.getLaunchIntentForPackage(ctx.packageName)
    // SINGLE_TOP: reuse the existing task instead of stacking a second copy.
    // CLEAR_TOP: drop anything above it, so the user lands on the tracking screen.
    ?.apply { flags = Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP }
    ?: return null

  return PendingIntent.getActivity(
    ctx,
    // The request code. Keyed per activity so two concurrent deliveries get
    // two distinct PendingIntents rather than silently sharing one.
    notificationIdFor(activityId),
    intent,
    // FLAG_IMMUTABLE is mandatory on Android 12+; omit it and this throws.
    // FLAG_UPDATE_CURRENT refreshes the extras of the existing PendingIntent
    // rather than handing back a stale one from an earlier delivery.
    PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
  )
}

FLAG_IMMUTABLE is required on Android 12 and later. Verify the result with adb shell dumpsys notification, which should show contentIntent=PendingIntent{... startActivity}.

A Push Updates the Notification But Not Your Interface

The service is a separate entry point from your JavaScript state, so a push arriving while the app is open leaves the app showing a stale step. The fix is a static bridge, set when a module instance exists and cleared when it does not.

companion object {
  // Static, because the FCM service cannot reach a module INSTANCE. @Volatile
  // because the service runs on a different thread than the one that sets this.
  // Nullable because, most of the time, there is no live module to emit into.
  @Volatile private var pushEmitter: ((Map<String, String>) -> Unit)? = null

  // Safe to call from anywhere. The `?.` is the entire "is the app alive?" check.
  fun emitPush(data: Map<String, String>) { pushEmitter?.invoke(data) }
}

override fun definition() = ModuleDefinition {
  // Declares the events JS may subscribe to. Emitting an undeclared name throws.
  Events("onFcmTokenReceived", "onDeliveryPush")

  // Register the bridge when a module instance exists...
  OnCreate  { pushEmitter = { data -> sendEvent("onDeliveryPush", data) } }
  // ...and tear it down when it does not. Skip this and you leak a closure
  // holding a dead React context, then crash on the next push.
  OnDestroy { pushEmitter = null }
  // ...
}

The service calls DroptrackLiveModule.emitPush(d) after notify(). It does nothing when the app is dead, in which case the notification still updates and there's simply nothing to sync. This is the Android analogue of the iOS foreground resync.

A Cold-started App Comes Up Empty

iOS recovers from Activity.activities. Android has no such store, so a killed app reopened by tapping its own notification shows "Not tracking". Persist the delivery to SharedPreferences on every notify(), then read it back.

// Same JS name as the iOS implementation, so App.tsx never branches on platform.
AsyncFunction("getRunningActivities") {
  val ctx = context ?: return@AsyncFunction emptyList<Map<String, Any?>>()

  // Our stand-in for iOS's Activity.activities: the record written on notify().
  val active = DeliveryNotifier.activeDelivery(ctx)
    ?: return@AsyncFunction emptyList<Map<String, Any?>>()
  val activityId = active["activityId"] as String

  // Phantom guard: trust the system's notification list over our own record.
  if (!DeliveryNotifier.isActive(ctx, activityId)) {
    DeliveryNotifier.clear(ctx)
    return@AsyncFunction emptyList<Map<String, Any?>>()
  }

  // Repopulate the per-process map, or a later update/end throws after cold start.
  deliveries[activityId] = DeliveryInfoRecord().apply { orderId = active["orderId"] as String }
  return@AsyncFunction listOf(active)
}

Two subtleties here I only found by breaking them. Guard the rehydration with getActiveNotifications(). Without that check, a stale record produces an uncancellable phantom delivery whose Cancel button throws ActivityNotFoundException. And make endDelivery forgiving. If the activity isn't in the in-memory map because you cold-started, still cancel the notification and clear the state rather than throwing. Tearing something down should never fail because you've forgotten about it.

Because the resync effect in App.tsx is cross-platform, implementing Android's getRunningActivities() lights up the existing cold-start path with no JavaScript changes. That's the payoff of keeping one API across two backends.

How to Script the Simulators and Devices

Two small tools saved more time than any feature.

The iOS simulator has no scriptable tap. There's no uiautomator equivalent, and synthetic clicks need macOS accessibility grants. So I added a development-only deep-link driver, fifteen lines, stripped from release builds.

useEffect(() => {
  // Dead code in release builds: the bundler strips the whole effect body.
  if (!__DEV__) return;

  // "droptrack://drive/next" -> "next" -> call actions.next().
  // actionsRef, not actions: the listener is registered once, so a plain
  // closure would capture the first render's handlers forever.
  const run = (url: string) => actionsRef.current[url.split("/").pop() ?? ""]?.();

  // Case 1: app already running. simctl openurl fires this event.
  const sub = Linking.addEventListener("url", ({ url }) => run(url));

  // Case 2: devicectl --payload-url COLD-STARTS the app: the URL arrives as the
  // initial URL and never fires the 'url' event. Handle both or device
  // automation silently does nothing while simulator automation works.
  void Linking.getInitialURL().then((url) => url && run(url));

  return () => sub.remove();
}, []);

# Drives the running app one step forward, with no tap and no accessibility grant.
xcrun simctl openurl booted "com.fasarticle.droptrack://drive/next"

For the push half I built a small web dispatcher. A browser cannot reach APNs or FCM, because of HTTP/2, missing cross-origin headers, and the fact that signing keys must never leave the server. So it talks to a zero-dependency local Node.js signing server that scrapes push tokens off the device console, streams them to the browser with server-sent events, and sends to whichever platform you select.

iPhone  --NSLog--> devicectl --console --+
Android --Log.i--> adb logcat -----------+
                                         | scrape
browser <--SSE /events-- dispatch-server (127.0.0.1:8787)
   \--POST /push--------> apns.mjs / fcm.mjs --> APNs / FCM --> device

Pick a step, pick a courier, and press one button. It turns a two-minute test into a ten-second one, and it made the Samsung investigation below possible at all.

How iOS and Android Compare

The Samsung Reality Check

Version numbers lie, and Samsung is where they lie loudest. I tested by hand across three real Galaxy devices using Samsung Remote Test Lab, whose Remote Debug Bridge turns out to be a full local adb tunnel to a phone in Korea. The entire emulator automation playbook (granting permissions, tapping, taking screenshots, and reading dumpsys) works unchanged against remote hardware.

Here's what the same unmodified APK did on each:

Two findings come out of that table.

1. On the base-36 device, the two capability checks disagree

The S25 Ultra runs base 36, which has no promotion pipeline, so nothing promotes. But hasPromotableCharacteristics() returns true there (Samsung backported some framework pieces) while canPostPromotedNotifications() returns false. A base-36 Pixel emulator returns false for both. So you can't infer one check from the other. Detect both at runtime, and trust canPostPromotedNotifications() for whether promotion will actually happen.

2. On the 36.1 devices, promotion works but only partly

Both the S26 Ultra and the A37 genuinely grant FLAG_PROMOTED_ONGOING to the unmodified APK, which you can confirm in dumpsys. You get top-of-shade pinning and the status-bar icon. You do not get the chip pill, the lock-screen card, or a Now Bar entry, even though the promotion succeeded.

That "only partly" was the mystery, until I found where the missing surfaces went. In Settings, under Lock screen and Always On Display, there's a page called Live notifications (searchable as "live notification", notably not as "Now bar"). It promises exactly the surfaces I was missing: the lock screen, the status bar, and the top of the notification panel, illustrated with the Now Bar pill. And directly below that promise sits a fixed, six-app allowlist: Audio broadcast, Emergency sharing, Google Finance, Maps, Media player, and Sports from Google.

DropTrack isn't on that list. Yet its promoted delivery was live on that very device at that very second, and the page's own "Not seeing Live notifications?" checklist (three notification permissions) was fully satisfied. The feature was working. Samsung simply doesn't offer its best surfaces to apps outside the six.

So the screenshot-backed conclusion for these units is this: One UI 8.5 accepts Google's promotion contract and ships the minor surfaces to any app, but reserves the headline ones for a hardcoded list. This reflects those specific devices at the time of testing, and Samsung may change it.

It leaves the three platforms in three different places. Apple offers a public API on every device. Google offers a public API on its own hardware. Samsung offers the framework to everyone but keeps the best stage by invitation.

The Demo Repository

Everything in this handbook is one working project, DropTrack, released under the MIT licence. It's not a snippet dump. It's a single React Native app whose one delivery-tracking feature reaches down through five layers. The point of reading it is to see how those layers connect rather than how any one of them looks in isolation.

Here's what lives in the repo, layer by layer:

A few things make it worth cloning rather than skimming:

• It genuinely runs on all three surfaces: The same DeliveryState object drives a SwiftUI Live Activity, an Android promoted notification, and a web console, so you can watch one API produce three very different results.

• The push clients have no dependencies: scripts/apns.mjs and scripts/fcm.mjs use only Node built-ins, so you can read the entire APNs and FCM path end to end without unpacking a library. Both have small test files next to them.

• Every gotcha in this article is written up in GOTCHAS.md: The long checklist that used to live in this section now lives there, next to the code it refers to, alongside DEVLOG.md (how the build unfolded) and ARTICLE_NOTES.md.

• It's safe to fork: The Firebase service account, the google-services.json, and the APNs .p8 key are all gitignored, so nothing sensitive is in the history. The README.md lists exactly which of those you supply to run the push phase yourself.

Clone it, run the app on a simulator, open the web console, and push an update to your own device. That loop is the fastest way to make everything above concrete.

What to Know Before You Start

The product feature is identical, and the platform contracts are opposites. iOS gives you a system-owned widget and updates it for you. Android gives you a notification and makes you the update engine, down to re-posting it from a background service on every message. Design your module's seam accordingly. The same three-function API can hide wildly different machinery, and that is exactly what a good native module is for.

The silent failures are the tax. Almost every hard bug in this project, from the mismatched widget struct, to the missing entitlement, the wrong epoch, the un-promoted notification, and the notification-instead-of-data message, fails with zero errors. So instrument aggressively. Log promotable characteristics. Verify entitlements survived signing. Probe push auth with fake tokens before you involve a device. Always confirm on the real surface rather than trusting a 200.

Version numbers lie, so detect features instead. Android 16 is two releases. Samsung's Android 16 is a third. canPostPromotedNotifications() and hasPromotableCharacteristics() can disagree on the same build. Check both at runtime, and never infer one from the other.

The system owns the activity, not your process. On iOS the activity outlives your variable, your React state, and your process. On Android the notification outlives your process too, but nothing recovers it for you. Both platforms punish you for assuming the id in your useState is the source of truth.

Conclusion

You now have a complete picture of both platforms. You built one TypeScript API over two native backends, a SwiftUI widget with four presentations, a Kotlin notification that satisfies Android's promotion contract, and two push clients written from scratch with no libraries. You also know the failure modes that produce no error message, which is most of them.

Three things are worth exploring next:

1. Push-to-start, on iOS 17.2 and later. You can start a Live Activity from a push, with no app launch at all. The token is per-app rather than per-activity, which rewrites the token plumbing described above.

2. Broadcast channels, on iOS 18. One push updates an activity for many users, which suits live scores. Every push in this handbook targets a single token.

3. An Android foreground service. It narrows the Doze and force-kill delivery gap. It won't close it, but it makes long-running deliveries more durable than a bare data message.

The interesting part was never Activity.request(). It was everything the two platforms decline to tell you when you get it wrong.

Sources and Further Reading

Apple, ActivityKit and APNs:

• ActivityKit and ActivityAttributes

• Displaying live data with Live Activities

• Starting and updating Live Activities with ActivityKit push notifications

• Live Activities, Human Interface Guidelines

• The aps-environment entitlement

• Sending notification requests to APNs, Establishing a token-based connection to APNs, and Handling notification responses from APNs

• Date, and the 2001 reference date

• WidgetKit

Android and Firebase:

• Progress-centric notifications in Android 16 and Android 16 overview

• Notification.ProgressStyle and NotificationCompat.ProgressStyle

• NotificationCompat.Builder, where setRequestPromotedOngoing and setShortCriticalText are backported

• Build.VERSION.SDK_INT_FULL and Build.VERSION_CODES_FULL, the 36 versus 36.1 distinction

• NotificationManager.canPostPromotedNotifications(), Notification.hasPromotableCharacteristics(), and getActiveNotifications()

• PendingIntent.FLAG_IMMUTABLE and SharedPreferences

• androidx.core release notes

• Doze and App Standby

• Firebase Cloud Messaging, Receive messages in an Android app, FirebaseMessagingService, projects.messages.send, and the FCM ErrorCode reference

• Using OAuth 2.0 for server to server applications and the google-services Gradle plugin

Apps that document their own Live Activity, cited in "Where You Have Already Seen This Feature":

• Chowdeck, ESPN, MLB, FotMob, CARROT Weather, and Structured, all via their App Store listings

• Flighty's Live Activities help page

• Apple Sports, following games in real time

• MacRumors on Uber Eats, May 2023 and DoorDash, December 2023

• MacStories, the iOS 16.1 Live Activities roundup

React Native, Expo, and tooling:

• Expo Modules API overview and the module API reference

• Expo config plugins and Continuous Native Generation

• @bacons/apple-targets, which generates the widget extension

• expo-live-activity, the packaged alternative

• Notifee, archived, and its last release @notifee/react-native@9.1.8

• React Native AppState and Linking

• Node.js crypto and http2

• RFC 7519, JSON Web Token and RFC 7518, JSON Web Algorithms, which define the ES256 and RS256 signature formats

• Samsung Remote Test Lab