The Long Answer

Trust Insights, or how your app can tell when someone is being talked through a scam

Mon, 02 Nov 2026 00:00:00 +0000

The scam that gets past every check a bank app has is the one where the victim does the work. The right person, on their own phone, signed in with Face ID, sends the money themselves, because someone on the phone has told them it is the only way to keep it safe. From the app's side, nothing is wrong. The password is right, the device is known, the person is who they say they are.

These scams are not getting rarer. They are aimed at older and less technical people, and AI has made them cheaper to run: a scammer can now work in a language they do not speak, sound fluent in it, and copy the voice of the victim's grandchild.

iOS 27 gives apps a way to ask about this. With Trust Insights, your app asks the system, before the money moves, whether it looks like someone is coaching the person through what they are doing. It gets back a risk level, and decides what to do with it.

It only helps if the apps use it. A scammer who meets a warning in one bank's app will move the victim to the bank whose app does not ask. As I write this, not one of the bank or brokerage apps on my phone uses it. So here is how, with a sample project that does all of it in one file.

What it tells you

You ask for an insight, and the one there is today is IsLikelyBeingCoachedInsight. Its value is unknown, medium or high.

unknown means the system found no sign of coaching. That is not the same as finding the transfer safe; a scam the model did not catch also comes back unknown. medium and high are reasons to slow down, and Apple's documentation adds that coaching is not always malicious. A daughter walking her father through his first transfer is coaching too.

Apple's WWDC26 session, Meet Trust Insights, says what goes into it. The signals taken from the device are not shared with Apple or with third parties, and the content of Photos, Messages and Mail is never used. The result can also take in Apple Account signals and velocity checks. What your app receives is the risk level, not the reasons for it.

The person stays in charge. They give your app permission, and they can take it away in Settings. The session says a cooldown may apply after they turn it off, to protect people who were coached into turning it off.

Not only banks

The session names the scams Apple had in mind. Tech support scams, where a fake alert leads to remote access and the victim hands over control. Authority impersonation: callers posing as the bank, a government agency or the police. Family emergencies: an urgent plea for money from a relative, more and more often in a voice made with AI. In all three, someone talks the victim through the steps by phone, chat or messages.

None of that is specific to banks. The operation categories cover any exchange of money, assets or content, in-game purchases included; changes to account and security details; costly services such as AI inference; and sending messages, submitting forms or signing documents. The session lists the moments worth asking about: large payments such as peer-to-peer transfers, actions that cannot be undone such as deleting an account or exporting personal data, permissions such as remote access or a new device, and sharing credentials or personal documents. The app that sells gift cards can ask before the purchase, and the remote support app can ask before it hands over the screen.

It only helps where an app asks. A scammer who edits the bank's web page on the victim's computer to show a refund that never happened is out of its reach, and so is a victim who drives to an ATM. The moment the victim sends the "overpaid" money back from a phone app, or buys gift cards in one, is a moment that app can ask about. What the system looks at, Apple describes only as interaction patterns, timing, context and basic sensor data.

It all happens in the app

Trust Insights is an iOS framework, and that puts some developers off: the same bank has an Android app, and a fraud team that wants one pipeline. None of that has to change. The session describes the integration as entirely client-side. The iOS app asks before the transfer and decides what to do with the answer. Your server, your Android app and your fraud rules carry on as they are, and if the fraud team wants the result, the app records it with the transfer like any other check it runs.

The app, step by step

The sample is a one-screen UIKit app for a fictional bank. Everything that touches the API is in TrustInsightsCheck.swift, in five steps, in the order you meet them. The code below is taken from it.

1. Describe the operation

An evaluation request is a context: what kind of operation this is, and which insights you want. A transfer is .payment; the other categories are .account, .resourceUse, .communication and .other.

static func context() -> CoachingContext {
    InsightEvaluator.InsightContext(
        operationCategory: .payment,
        requestedEvaluations: IsLikelyBeingCoachedInsight.request(schema: .version1),
    )
}

InsightContext takes a parameter pack, which makes its type long. The sample gives the types short names, CoachingContext and CoachingEvaluation, so the rest of the code stays readable.

2. Ask for permission at a calm moment

The app needs the person's permission, and when you ask matters more than how. Ask from a deliberate action, such as a settings row, after saying what it does. Never ask in the middle of a transfer: if a scammer is on the phone, they will tell the person to tap Not Now.

static func requestAuthorization(for context: CoachingContext) async -> Bool {
    let status = try? await InsightEvaluator().requestAuthorization(for: context)
    return status == .authorized
}

authorizationStatus(for:) has five answers. .authorized means go ahead. .notDetermined and .deniedRequestable mean you may ask, from that calm moment. .denied and .unavailable mean you may not; the person can still turn it on in Settings > Privacy & Security > Impersonation Risk Detection.

3. Start the evaluation early

The result is the return value of requestEvaluation(context:). There is no delegate, notification or extension. The session warns that it can take a couple of seconds and needs internet access, so do not wait for the Confirm button to start it. The sample starts it as soon as the transfer screen appears, and the seconds pass while the person reads the screen:

private func startEvaluation() {
    let context = TrustInsightsCheck.context()
    pending = Task { await TrustInsightsCheck.evaluate(context) }
}

evaluate checks the authorization status, calls requestEvaluation, and turns every failure into nil, which means "no evaluation, use your existing checks". A failure must never block a transfer that your app would otherwise allow. These are the errors, and what the sample does with each:

EvaluationError	What it means	What to do
`contextInvalid`	The request is malformed	A bug; fix it
`denied`	Permission was withdrawn	Carry on without it
`notAvailable`	Trust Insights is not available	Carry on without it
`rateLimitExceeded`	Too many requests	Check that every evaluation is reported (step 4)
`serverError`, `localError`	A transient failure	Try again on the next transfer, not in a loop
`payloadSecurityError`	The payload could not be secured	Carry on without it, and log it

A production app should also stop waiting after a deadline of its own and go ahead on its usual checks. If you do that, the evaluation that turns up after the deadline still has to be reported, as .notUsedError.

4. Decide, and report what you decided

Every evaluation has to be reported with reportConsumption, exactly once. The session is plain about it: the call is mandatory, and an app that skips it may be rate-limited. The report says what the app did with the result, and it is how Apple learns how the insight is being used.

The sample puts the report on every branch, where you can see it:

static func decide(_ evaluation: CoachingEvaluation?) -> Friction {
    // No evaluation: no permission, no network, or an error. The app's own checks decide, as before.
    guard let evaluation else { return .none }

    switch evaluation.insight.outcome {
    case .success(.unknown):
        // No evidence of coaching. That is not evidence of safety, so friction stays as it was.
        evaluation.reportConsumption(.usedUnchangedFriction, insightsUsed: [evaluation.insight])
        return .none
    case .success(.medium):
        evaluation.reportConsumption(.usedIncreasedFriction, insightsUsed: [evaluation.insight])
        return .warn
    case .success(.high):
        evaluation.reportConsumption(.usedIncreasedFriction, insightsUsed: [evaluation.insight])
        return .hold
    case .success:
        // A level newer than this sample. Do not guess what it means.
        evaluation.reportConsumption(.notUsedError)
        return .none
    case .failure(let error):
        // The evaluation came back, but the insight inside it failed. It still has to be reported.
        log.notice("Insight failed: \(String(describing: error), privacy: .public)")
        evaluation.reportConsumption(.notUsedError)
        return .none
    }
}

Two branches are easy to miss. The .failure case is an evaluation that came back with a failed insight inside it, and it still counts as an evaluation. And a transfer the person cancels before confirming still had an evaluation, which the sample reports as .notUsedNotNeeded.

What the warning says matters as much as when it appears. The sample's medium warning asks whether someone is telling the person what to do, and says the bank will never ask them to move money to keep it safe. Its high response pauses the transfer and promises a call back on the number the bank already has. The Swift Dev's design guide goes much further into this than I do here, and it is worth reading before you write your own copy.

5. Only add friction, and keep a record

A decision made in the app can be changed by anyone who can change the app. For a warning, that does not matter. A changed app that fakes unknown gets the transfer the bank would have allowed before Trust Insights. So the sample only ever adds friction: unknown leaves the transfer as it was, and nothing skips a check.

Apple's documentation shows the other direction too: its example uses a result with no sign of coaching to skip one of the app's checks, and .usedReducedFriction exists for that. That needs a result your server can trust. The evaluation carries a signedPayload for server-side validation, but as of November 2026 what a server needs to check it is not public. The sample does not use it, and neither does this article.

Last, the sample logs the result and the friction with the transfer. A real app keeps them in its own records, because the next section is about what the fraud team does with them.

What you cannot test, and whose job that is

I ran the sample on a device, and the whole flow works: permission, the evaluation, the report. What I could not do is make it see a scam. Apple does not say what it treats as coaching, so there is no way to set up the conditions for a medium or a high on purpose. The session says values and errors can be overridden with launch arguments in the scheme, and refers to the documentation for the list. The documentation does not have the list yet. Until it does, the branches for medium and high can only be tested by reading them.

That leaves the judgement with the banks, which is where it belongs anyway. How much weight a medium gets is a decision for your fraud team, made from your own numbers: what happened to the transfers that got each value, and how many of the unknowns turned out to be fraud. Where the results do not match what your fraud team sees, tell Apple through Feedback Assistant. The model gets better when the banks using it say where it is wrong.

Start

If you work on a bank, brokerage, payments or crypto app, put this on the screen where money leaves the account. If you work on any other app where money, an account or remote access changes hands, put it there. It is all app code, it fits in one file, and the sample is there to copy from. Every app that adopts it leaves scammers one less place to send their victims.

Sources

Trust Insights, Apple's documentation
InsightEvaluation and signedPayload
IsLikelyBeingCoachedInsight
Meet Trust Insights, WWDC26
TrustInsightsSample, the sample project
iOS 27: Trust Insights Framework, Anton Gubarenko
Trust Insights: Detect Coerced Actions In Sensitive iOS Flows, The Swift Dev

App Attest, or how you can trust an app that cannot keep a secret

Tue, 27 Oct 2026 00:00:00 +0000

If your app talks to a service with an API key that is compiled into the app, that key is not a secret. Anyone who has the app has the binary, and anyone who has the binary can read what is in it. Reading compiled code has never been easier than it is today, and the AI assistants that now help with it have made it faster still. OWASP lists keys and other sensitive data hardcoded in the app package as a weakness in its own right, and obfuscation does not change that.

So the secrets go on your server, and your server makes the calls that need them. That moves the problem to the server, which now has to decide who is asking. Your app is one caller. A script that copied your app's requests is another, and so is a modified copy of your app. Apple puts the core of the problem plainly in its App Attest documentation: you can't rely on your app's logic to perform security checks on itself, because a compromised app can falsify the results.

That is the job App Attest does. It lets your server check, with a key that the app itself can never read, that a request comes from your app, signed by your team, running on genuine Apple hardware. It is less work than most people expect.

What App Attest tells your server

Apple's WWDC26 session Secure your apps with App Attest is the best explanation Apple has of all this, and it is twenty minutes well spent. In short, an attestation tells your server that:

the key belongs to an app with your Team ID and bundle identifier, so a copy re-signed by someone else shows up as someone else;
the key was generated in the Secure Enclave of a real Apple device;
how the app was launched (App Store, TestFlight, development signing and so on) and which bundle version is running (on iOS 27 and later);
where App Attest is now available, that the Mac had System Integrity Protection and full security mode turned on (on macOS 27 and later).

After that, the app signs individual requests with the same key, and your server checks each signature.

There are two things it does not do. It does not identify a user; that is still the job of your sign-in process. And it cannot make a device with a modified operating system honest. Apple says so in its fraud assessment article: an attacker who modifies the operating system might get around it. That is what the fraud metric, further down, is for.

Important: App Attest is not jailbreak detection. A jailbroken device runs a modified operating system, and that operating system may be modified so that attestations and assertions still pass. Apple's documentation calls this a compromised device; the WWDC26 session says a compromised device could still pass attestations. An Apple engineer put it more directly in a forum reply: App Attest gives general guarantees that your app is running unmodified, but "in the cases of a jailbreak / root, the latter may not always hold true". Do not trust a jailbroken device, whatever its attestations say. And do not rely on jailbreak detection in the app instead: Apple DTS advises against it, because such checks depend on low-level details that break as the system changes.

Why a compromised device can't be trusted is easy to see once you look at what a check is. Every check your app makes is code running on the device: if the answer is good, carry on, otherwise refuse. Whoever controls the operating system controls that code too. Flipping one comparison so that a failing check passes, making a system call return the answer your app was hoping for, loading their own code into your app's process: on a device whose operating system is theirs, all of that is routine work. The same goes for the frameworks your app calls, the one that talks to App Attest included. The WWDC26 session walks through that very case on a Mac with System Integrity Protection turned off, where the attacker modifies the App Attest framework itself. On the Mac, the key's access policy still gives it away, which is why the section on the Mac below says to check it. The lesson holds everywhere: checks belong on your server, where nobody but you can edit them, and even your server can only weigh what such a device sends against every other signal it has.

OWASP, which I quoted at the top, does want apps to look for jailbreaks. Its MASVS-RESILIENCE controls and the weakness it calls Root/Jailbreak Detection Not Implemented cover exactly that, and there are commercial products that do it for you. The rest of what OWASP says lands where this article does. These are defence-in-depth measures for apps with something worth protecting, and leaving them out is not a vulnerability in itself. They must never replace other security controls, none of them is fully effective, and the checks that are publicly documented are easy to get around. OWASP's own advice is to back them with device attestation verified on the server, so the server can still act when the checks in the app have been defeated. If your risk calls for them, add them, or buy them, as one more signal for your server. Keep the decision on the server, and expect them to need updating when the system changes.

How it works

There are three steps, and only one of them talks to Apple.

The app generates a key. The private half stays in the Secure Enclave, and the app gets back an identifier, which it keeps.
The app attests the key once. It asks your server for a challenge, and the system contacts Apple, which returns an attestation object. The app passes that to your server, which checks it and stores the public key.
From then on, for each request that matters, the app asks your server for a challenge and signs the request together with it. That is an assertion. It happens on the device and does not involve Apple at all.

The app side

Note: The code in this article was tested when it was written, in October 2026: the app side compiles against the iOS 27 SDK, and the server checks were run against Apple's validation guide. App Attest, Apple's guidance and the SDKs all change. Before you rely on any of it, check it against the current documentation and test it again.

Here is all of it, in one actor. The protocols at the top stand in for your own networking and keychain code.

import CryptoKit
import DeviceCheck
import Foundation

/// The calls your app makes to your own server. Yours to implement.
protocol AttestServer: Sendable {
    func challenge() async throws -> Data
    func register(keyID: String, attestation: Data, challenge: Data) async throws
    func send(_ request: Data, assertion: Data) async throws -> Data
}

/// Where the key identifier lives. Use a keychain item with
/// kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly, so it never syncs.
protocol KeyIDStore: Sendable {
    func load() -> String?
    func save(_ keyID: String)
    func remove()
}

/// App Attest on the app side: one key per user per device, attested once.
actor AppAttest {
    private let service = DCAppAttestService.shared
    private let server: any AttestServer
    private let store: any KeyIDStore

    init(server: any AttestServer, store: any KeyIDStore) {
        self.server = server
        self.store = store
    }

    /// Run when your server says this install should attest, away from any
    /// user flow. Returns false if the device can't attest; the app carries
    /// on, and your server decides what that device may do.
    func attestIfNeeded() async throws -> Bool {
        guard service.isSupported else { return false }
        let keyID: String
        if let saved = store.load() {
            keyID = saved
        } else {
            keyID = try await service.generateKey()
            store.save(keyID)
        }
        let challenge = try await server.challenge()
        let hash = Data(SHA256.hash(data: challenge))
        do {
            let attestation = try await service.attestKey(keyID, clientDataHash: hash)
            try await server.register(keyID: keyID, attestation: attestation,
                                      challenge: challenge)
            return true
        } catch let error as DCError where error.code == .serverUnavailable {
            // Keep the key. Try again later, with back-off, using the same key.
            throw error
        } catch let error as DCError {
            // Any other DeviceCheck error: this key is no good. Forget it, and
            // the next attempt starts with a new one.
            store.remove()
            throw error
        }
    }

    /// Signs one request. The server checks the signature and the counter.
    func send(_ action: [String: String]) async throws -> Data {
        guard let keyID = store.load() else { throw DCError(.invalidKey) }
        var request = action
        request["challenge"] = try await server.challenge().base64EncodedString()
        let clientData = try JSONEncoder().encode(request)
        let hash = Data(SHA256.hash(data: clientData))
        let assertion = try await service.generateAssertion(keyID, clientDataHash: hash)
        return try await server.send(clientData, assertion: assertion)
    }
}

A few rules come with it, and most of them are in Apple's integration guide or the WWDC26 session.

Generate one key per user account per device, or one for the whole app if it has no accounts, and never share a key between users; Apple's guide explains that a shared key makes it hard to spot one compromised device serving many users. Store the identifier in the keychain with a ThisDeviceOnly accessibility class such as kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly, because, as the guide puts it, there is no way to get the identifier back later, and the key is useless on any other device anyway.

Attest once per key, and let your server decide when. Do it away from any user flow, in the background if you can; the WWDC26 session asks for both. It is easy to end up calling attestKey from somewhere like a view controller's viewDidLoad, especially from inside an SDK, and then every launch of every copy of the app goes to Apple's servers. Keep track of whether the key was attested, and don't ask again.

If attestKey fails with serverUnavailable, keep the key and try again later, with the same key, backing off exponentially between attempts. For any other DeviceCheck error, throw the identifier away and start over with a new key next time. Both rules are in the integration guide, and the back-off is from the WWDC26 session.

Check isSupported before anything else, and when it is false, carry on without App Attest and let the server decide what that device is allowed to do. The WWDC26 session also suggests watching for a rise in unsupported responses from one user, since that can be a sign of tampering.

Use assertions where they count: signing in, payments, premium content, anything you would not want a script doing. Apple's guide reserves them for sensitive moments, and the WWDC26 session points out that generating one costs CPU. Add the round trip to your server for the challenge, and putting one on every API call is a bad trade.

The server side

The server does the real work, and it should, because the app cannot be trusted to check itself. Apple's article Validating apps that connect to your server lists every check, and its Attestation Object Validation Guide gives a real attestation object with the expected value at every step. Run your implementation against that guide before you trust it.

For the attestation, the server:

verifies the certificate chain in the attestation statement up to Apple's App Attest root certificate, which Apple publishes on its certificate authority page;
computes the nonce as the SHA-256 of the authenticator data followed by the client data hash, and checks it against the leaf certificate's extension 1.2.840.113635.100.8.2;
checks that the hash of the public key in the leaf certificate is the key identifier the app sent;
checks the authenticator data: the hash of your App ID, a counter of 0, the environment in aaguid, and the key identifier in credentialId;
on iOS 27 and later, reads the launch validation category and bundle version from the authenticator data's extensions;
stores the public key and the receipt, and associates them with the user and the device.

The attestation follows the WebAuthn authenticator data format, which is where the field layout below comes from. The certificate chain and the CBOR decoding need an X.509 and a CBOR library; use a maintained one for your server's language. The rest is plain hashing and byte comparison. Here are the authenticator data checks, and the assertion check, in Swift with CryptoKit. I ran the attestation check against Apple's validation guide, and it produces the guide's expected nonce.

import CryptoKit
import Foundation

/// Reads bytes front to back, one field at a time, so nothing depends on
/// where a field sits. Asking for more bytes than are left returns nil.
struct ByteReader {
    private var bytes: ArraySlice<UInt8>

    init(_ data: Data) {
        bytes = ArraySlice(data)
    }

    mutating func take(_ count: Int) -> Data? {
        guard count >= 0, bytes.count >= count else { return nil }
        defer { bytes = bytes.dropFirst(count) }
        return Data(bytes.prefix(count))
    }

    /// An unsigned big-endian integer of `count` bytes.
    mutating func uint(_ count: Int) -> UInt64? {
        take(count)?.reduce(0) { $0 << 8 | UInt64($1) }
    }
}

/// WebAuthn authenticator data, as App Attest uses it.
struct AuthenticatorData {
    /// Field sizes, as the WebAuthn specification defines them.
    enum Size {
        static let rpIDHash = 32
        static let flags = 1
        static let counter = 4
        static let aaguid = 16
        static let credentialIDLength = 2
    }

    /// Flag bits from the same section of the specification.
    enum Flag {
        static let attestedCredentialData: UInt8 = 0x40
        static let extensionData: UInt8 = 0x80
    }

    let rpIDHash: Data
    let flags: UInt8
    let counter: UInt32
    let aaguid: Data?         // present when the flags say so: attestations
    let credentialID: Data?

    init?(_ data: Data) {
        var reader = ByteReader(data)
        guard let rpIDHash = reader.take(Size.rpIDHash),
              let flags = reader.take(Size.flags)?.first,
              let counter = reader.uint(Size.counter)
        else { return nil }
        self.rpIDHash = rpIDHash
        self.flags = flags
        self.counter = UInt32(counter)
        // Read the attested credential data only if the flags say it is
        // there; never assume it.
        if flags & Flag.attestedCredentialData != 0 {
            guard let aaguid = reader.take(Size.aaguid),
                  let length = reader.uint(Size.credentialIDLength),
                  let credentialID = reader.take(Int(length))
            else { return nil }
            self.aaguid = aaguid
            self.credentialID = credentialID
        } else {
            aaguid = nil
            credentialID = nil
        }
        // What follows is CBOR: the COSE public key, then the extensions.
        // Apple's own sample object carries extensions without setting
        // Flag.extensionData, so don't use that flag to decide whether to
        // look for them. Decode whatever follows the key, with a CBOR library.
    }
}

enum Environment {
    case development, production

    /// The aaguid values this environment accepts.
    var aaguids: Set<Data> {
        switch self {
        case .production:
            return [Data("appattest".utf8) + Data(repeating: 0, count: 7)]
        case .development:
            // Apple's pages give two different development values; accept both
            // here, and log which one your devices actually send.
            return [Data("appattestdevelop".utf8), Data("appattestsandbox".utf8)]
        }
    }
}

/// The attestation checks that don't need an X.509 or CBOR library. The
/// certificate chain, and the nonce in the leaf certificate's extension
/// 1.2.840.113635.100.8.2, need both; use a maintained library for those.
///
/// `clientDataHash` must be exactly the bytes the app passed to
/// `attestKey`. If the app hashed the challenge, hash it here the same way.
func checkAttestation(authData: Data, keyID: String, clientDataHash: Data,
                      appID: String, environment: Environment) -> Data? {
    guard let auth = AuthenticatorData(authData),
          let aaguid = auth.aaguid,
          let credentialID = auth.credentialID,
          let keyIDBytes = Data(base64Encoded: keyID) else { return nil }
    guard auth.rpIDHash == Data(SHA256.hash(data: Data(appID.utf8))),
          auth.counter == 0,
          environment.aaguids.contains(aaguid),
          credentialID == keyIDBytes else { return nil }
    // The value the leaf certificate's nonce extension must equal.
    return Data(SHA256.hash(data: authData + clientDataHash))
}

/// Checks one assertion against the public key stored at attestation time.
/// Returns the new counter to store, or nil to reject the request.
func checkAssertion(signature: Data, authData: Data, clientData: Data,
                    publicKey: P256.Signing.PublicKey, appID: String,
                    lastCounter: UInt32) -> UInt32? {
    guard let auth = AuthenticatorData(authData),
          auth.rpIDHash == Data(SHA256.hash(data: Data(appID.utf8))),
          auth.counter > lastCounter,
          let ecdsa = try? P256.Signing.ECDSASignature(derRepresentation: signature)
    else { return nil }
    let clientDataHash = Data(SHA256.hash(data: clientData))
    let nonce = Data(SHA256.hash(data: authData + clientDataHash))
    guard publicKey.isValidSignature(ecdsa, for: nonce) else { return nil }
    return auth.counter
}

For an assertion, the server checks the signature over the nonce with the stored public key, the App ID hash, that the challenge in the client data is the one it handed out, and that the counter is higher than the last one it saw for that key. Then it stores the new counter. These are the steps in Apple's validation article. A counter that stays the same or goes backwards means a replay, or, as the WWDC26 session puts it, a copy of the app that does not know where the real one is up to.

Libraries in other languages

If your server is not written in Swift, there are open-source libraries that do all of this, certificate chain and CBOR included. I have not tested any of them. Read the code, check it against Apple's validation guide the same way, and look at how recently it was maintained before you trust it with anything that matters.

Node.js and TypeScript: node-app-attest and appattest-checker-node
Python: pyattest, which also handles Android's Play Integrity
Go: go-app-attest
Kotlin and Java: devicecheck-appattest, WebAuthn4J, which supports App Attest alongside WebAuthn, and Warden Supreme, which covers Android key attestation as well
Rust: appattest-rs
PHP: app-attest

If you would rather not run the verification yourself, Firebase App Check can use App Attest as its provider and do it for you.

The things that trip people up

The nonce is built from exactly what the app passed

The nonce is the SHA-256 of the authenticator data followed by whatever bytes the app gave attestKey as clientDataHash. Apple's steps have the app pass the SHA-256 of the challenge, and the server has to hash it the same way. The sample object in the validation guide was made by passing the challenge itself, so if you test against the guide, append the challenge as it is. Either works, as long as both sides agree.

Extensions without the extension flag

In WebAuthn, a flag in the authenticator data says whether extensions follow. The sample object in Apple's validation guide sets only the attested credential data flag (0x40), yet it carries the iOS 27 extensions, apple_validation_category_01 and apple_bundle_version_01. A server that relies on the extension flag will miss them. Decode whatever follows the public key instead.

Two names for the development environment

The validation article says a key attested in development carries appattestdevelop in aaguid, and the article on preparing to use the service says appattestsandbox. Accept both when your server runs in development, log which one your devices send, and never accept either in production, where the value is appattest followed by seven zero bytes.

Development and production do not mix

Keys and receipts from one environment are useless in the other. During development the app uses the sandbox unless you set the App Attest environment entitlement to production. Once the app is on TestFlight or the App Store it always uses production. Test in the sandbox, because, as Apple's onboarding guidance explains, production keeps a count of keys per device that you cannot reset.

Keys do not survive reinstalling

A key lasts through app updates, but not through a reinstall, a restore from a backup (iCloud included), or a move to a new device. The integration guide and the WWDC26 session both say so. So one user will collect several keys over time, one per device and one per reinstall. Accept new keys for an existing user, and do not throw away the old ones straight away.

Where it runs

The WWDC26 session and the integration guide list Action and SSO extensions as supported, along with watchOS, and macOS from version 27. Check isSupported at run time and believe what it says on the device in front of you. An App Clip attests with the full app's App ID, and should store its key identifier in a container the full app can read, so the full app uses the same key.

The Mac

The reference page for isSupported was written before the Mac support arrived. It says isSupported is false on a Mac, for Mac Catalyst apps and for iPhone and iPad apps running on Apple silicon too. That was true until macOS 27. From macOS 27, the WWDC26 session says App Attest works on the Mac, with a condition: every key the Mac generates is bound to a policy that requires full security mode and System Integrity Protection. Apple has not said whether Mac Catalyst apps and iPhone apps on a Mac are included, so ask isSupported there rather than assume.

A Mac with System Integrity Protection turned off can still produce an attestation, so don't take a successful attestation as proof that the Mac is in full security mode. The proof is the key's access policy, which the leaf certificate carries under OID 1.2.840.113635.100.8.6. The validation article gives the one value to accept, and says to trust a Mac's attested key only for exactly that value. One more Mac difference comes from the same article: the RP ID hash is computed over the app's designated code signing requirement instead of its bundle identifier, as TN3127 describes, so check your server computes the right one for Mac clients.

Turning it on for an app with millions of users

Attestation goes through Apple's servers, and they throttle an app that sends too much at once. Apple's onboarding guidance is to ramp up gradually and uniformly, no more than 10 million users a day per app, and to stay under 100 attestation requests a second across all installations. Ship the code with attestation switched off, and have your server turn it on for a growing share of your users. After the first rollout, only new users, new devices and reinstalls attest, and for most apps that traffic does not cause trouble.

Most is not all. If your app goes viral overnight, or a feature launch sends a few million new users your way in a day, that surge is a rollout too, whether you planned it or not. Because your server decides when each copy of the app attests, as the WWDC26 session asks, it can let the new users in and pace their attestations to stay under the limit.

The surge you are most likely to cause yourself is a server failure. Say your server loses its record of which keys it has seen, through an outage, a botched migration or a restore from an old backup. The tempting fix is to tell every copy of the app to attest again. That is your whole user base calling Apple at once, on keys that were already attested, and it is exactly the traffic the onboarding guidance tells you to avoid. Keep the attestation records as safe as anything else you can't rebuild, and if you ever do need to collect attestations again, ramp up the way you did the first time.

Assertions from several requests at once

The counter goes up with every assertion. If the app signs two requests at the same time and they reach the server in the other order, the server sees the counter go backwards, and rejects a perfectly good request. There are two ways out, both suggested in The Swift Dev's walk-through: serialize the signed requests in the app, so that one assertion is made and sent before the next one starts, or have the app retry a rejected request with a fresh challenge, which gets a new assertion with a higher counter.

Never lock people out because attestation failed

Do not make your app depend on attestation succeeding. Networks fail. Apple's service can be slow or unreachable for a while, as any service on the internet can, which is what the serverUnavailable error is for. Keys get rotated by every reinstall and restore, and some devices cannot attest at all. If your app refuses to work whenever an attestation fails or isn't there, then the day attestation has a bad hour is the day your app stops working for everyone, honest users first. That is an outage you built yourself, and it is no use blaming Apple for it afterwards.

A failed or missing attestation is a reason to look closer, never a reason on its own to lock someone out. Apple's advice in the WWDC26 session is to degrade gracefully: limit what that user can do, watch them more closely, and leave the decision to your risk assessment. Keep everything that doesn't need App Attest working without it.

The fraud metric

A device with a compromised operating system can still produce valid attestations, and an attacker can use one such device to attest on behalf of modified copies of your app running on other devices. The fraud metric is how your server notices.

To get the metric, your server sends the receipt that came with an attestation to Apple's App Attest data server. The request is authenticated with a JWT made the same way as for APNs. Apple's server answers with a new receipt, and that new receipt holds the metric: an approximate count of the keys attested for your app on that device in the last 30 days. Store the new receipt in place of the old one, because the next request uses the latest receipt.

Expect the count to be small. Reinstalls and restores push the count up a little; a device that has attested hundreds of keys is almost certainly attesting for somebody else.

The count goes stale, so your server has to ask again from time to time. Each receipt has two dates in it: the earliest time your server may ask for a new count, and the time after which Apple's server may refuse to. A request made before the first date gets a 304, and a receipt left past the second date may stop working, so schedule the requests between the two.

As with every other signal in this article, treat a high count as a reason to look closer, and decide what to do about a suspicious device the same way you decide about any other fraud signal.

Sources

Secure your apps with App Attest, WWDC26
Mitigate fraud with App Attest and DeviceCheck, WWDC21
Establishing your app's integrity
Validating apps that connect to your server
Attestation Object Validation Guide
Preparing to use the App Attest service
Assessing fraud risk
App Attest environment entitlement
isSupported, attestKey(_:clientDataHash:completionHandler:), generateAssertion(_:clientDataHash:completionHandler:)
TN3127: Inside Code Signing: Requirements
kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
Establishing a token-based connection to APNs
Apple App Attestation Root CA, from Apple PKI
Web Authentication, Level 2: authenticator data, W3C
How to block iOS App to run on a Rooted device?, Apple Developer Forums, an Apple engineer's reply
How to test anti jailbreak, Apple Developer Forums, Apple DTS's reply
MASWE-0004: Sensitive Data Hardcoded in the App Package, OWASP
MASVS-RESILIENCE: Resilience Against Reverse Engineering and Tampering, OWASP
MASWE-0051: Root/Jailbreak Detection Not Implemented, OWASP
Validate Real Apps With App Attest, The Swift Dev
App Attest: How to prevent an iOS app's APIs from being abused, SwiftRocks

Server libraries, untested by me:

node-app-attest, appattest-checker-node (Node.js)
pyattest (Python)
go-app-attest (Go)
devicecheck-appattest, WebAuthn4J, Warden Supreme (Kotlin and Java)
appattest-rs (Rust)
app-attest (PHP)
Firebase App Check with App Attest, a hosted alternative

How an iOS app extension talks to its containing app

Mon, 19 Oct 2026 00:00:00 +0000

Most of the time, it can't. There's no open channel between an extension and its containing app, and the app usually isn't even running while the extension is. What works for nearly every extension, Notification Service and Location Push Service extensions included, is to write what the app needs into the App Group container and have the app read it the next time it runs.

This article covers how to do that properly, the handful of cases where you can do more, and before any of it, whether you need to reach the app at all.

Do you need the app?

The usual reason for wanting to call into the app is that the app already has the code. It parses the payload, updates the database, talks to the server, and nobody wants a second copy of all that in the extension. Sometimes the worry is that the existing code won't fit in the limits of extensions. Extensions get much less memory than apps (Apple's extension guide calls the limits "significantly lower"), and a notification service extension gets no more than 30 seconds.

The first problem doesn't need the app. Put the code in a framework or a Swift package that both targets link, and the extension runs the same code in its own process. [The extension guide] (https://developer.apple.com/library/archive/documentation/General/Conceptual/ExtensibilityPG/ExtensionScenarios.html) recommends exactly that, with "Require Only App-Extension-Safe API" turned on for the framework/package. Anything in the shared code that extensions can't use gets marked, and the compiler keeps the extensions away from it:

import UIKit

/// Shared by the app and its extensions.
enum Thumbnails {
    /// Fine everywhere: plain image work.
    static func make(from data: Data, side: CGFloat) -> UIImage? {
        guard let image = UIImage(data: data) else { return nil }
        let size = CGSize(width: side, height: side)
        return UIGraphicsImageRenderer(size: size).image { _ in
            image.draw(in: CGRect(origin: .zero, size: size))
        }
    }

    /// Uses UIApplication, so it's for the app only.
    @available(iOSApplicationExtension, unavailable)
    @MainActor
    static func makeInBackground(_ work: @escaping @Sendable () -> Void) {
        let task = UIApplication.shared.beginBackgroundTask(withName: "Thumbs")
        work()
        UIApplication.shared.endBackgroundTask(task)
    }
}

Call makeInBackground from an extension and the build stops with "'makeInBackground' is unavailable in application extensions for iOS".

For the second problem, do only what can't wait. A notification service extension has to decrypt the text before it's shown; rebuilding the chat index can happen later. A location push extension wants to update a server, creating a path can be done when the app is visible.

Instead, leave the app a note in the shared container saying what's left, and let the app do it when it next runs, or schedule a BGProcessingTask for it then. The work happens later, with the app's memory and the app's time.

If neither of those covers it and the app really does have to hear from the extension, here are your options (depending on the extension type you have)

The mailbox

The extension writes each message as its own file in the App Group container, then posts a Darwin notification. If the app is running, it hears the notification and reads the files. Running or not, it also reads them at launch and every time it becomes active, so a message written while the app was suspended or not running is still there when it looks.

The notification is only there to make it quicker. If it never arrives, nothing is lost, because the next launch or activation picks the message up anyway. MMWormhole made this pattern popular years ago, and its README makes the same point: the notification reaches the app only if the app is awake.

Both targets share this code:

import Foundation
import notify

/// Observes one Darwin notification name until released.
final class DarwinObserver {
    private var token: Int32 = NOTIFY_TOKEN_INVALID

    /// Calls `handler` on the main queue each time `name` is posted.
    init(_ name: String, handler: @escaping @MainActor () -> Void) {
        notify_register_dispatch(name, &token, .main) { _ in
            MainActor.assumeIsolated { handler() }
        }
    }

    deinit {
        notify_cancel(token)
    }
}

/// One message, as the extension wrote it.
struct Envelope<Body: Codable & Sendable>: Codable, Sendable {
    let sent: Date
    let body: Body
}

/// A directory of message files in the App Group container.
struct Mailbox: Sendable {
    /// The Darwin notification that says a message has arrived.
    static let ping = "group.com.example.app.mailbox"

    private let inbox: URL
    private let staging: URL

    /// The mailbox in `appGroup`, or nil if the group is not entitled.
    init?(appGroup: String) {
        let files = FileManager.default
        guard let root = files.containerURL(
            forSecurityApplicationGroupIdentifier: appGroup)
        else { return nil }
        inbox = root.appending(path: "Mailbox/Inbox")
        staging = root.appending(path: "Mailbox/Staging")
        do {
            try files.createDirectory(
                at: inbox, withIntermediateDirectories: true)
            try files.createDirectory(
                at: staging, withIntermediateDirectories: true)
        } catch {
            return nil
        }
    }

    /// Extension side: writes one message, then rings the doorbell.
    func send<Body: Codable & Sendable>(_ body: Body) throws {
        let envelope = Envelope(sent: .now, body: body)
        let data = try JSONEncoder().encode(envelope)
        let name = UUID().uuidString + ".json"
        // Write the whole file outside the inbox, then move it in. A
        // move within one volume is atomic, so the app never sees half
        // a file.
        let staged = staging.appending(path: name)
        try data.write(to: staged)
        try FileManager.default.moveItem(
            at: staged, to: inbox.appending(path: name))
        notify_post(Mailbox.ping)
    }

    /// App side: hands each waiting message to `handle`, oldest first,
    /// and deletes its file only after `handle` returns. A message whose
    /// handling throws stays in the inbox for the next drain.
    func receive<Body: Codable & Sendable>(
        _ type: Body.Type, handle: (Body) throws -> Void
    ) throws {
        let files = FileManager.default
        let urls = try files.contentsOfDirectory(
            at: inbox, includingPropertiesForKeys: nil)
            .filter { $0.pathExtension == "json" }
        // A file that will not decode stays where it is, for inspection.
        let waiting = urls.compactMap { url -> (URL, Envelope<Body>)? in
            guard let data = try? Data(contentsOf: url),
                  let envelope = try? JSONDecoder().decode(
                      Envelope<Body>.self, from: data)
            else { return nil }
            return (url, envelope)
        }
        for (url, envelope) in waiting.sorted(by: { $0.1.sent < $1.1.sent }) {
            try handle(envelope.body)
            try files.removeItem(at: url)
        }
    }
}

A message is written outside the inbox and moved in, so the app can't read half of one. Its file is deleted after the app has handled it, and not before. Nothing keeps a file open between calls, which matters more than it looks; see the section on the shared container.

Sending, from any extension:

/// What the share extension hands over.
struct SharedLink: Codable, Sendable {
    let url: URL
    let note: String
}

func handOff(_ url: URL, note: String) throws {
    let mailbox = Mailbox(appGroup: "group.com.example.app")
    try mailbox?.send(SharedLink(url: url, note: note))
}

Reading, in the app. It drains the inbox when the doorbell rings, at launch, and whenever the scene becomes active:

import Observation
import SwiftUI

/// The app's side of the mailbox.
@MainActor @Observable
final class Inbox {
    private(set) var links: [SharedLink] = []
    @ObservationIgnored
    private let mailbox = Mailbox(appGroup: "group.com.example.app")
    @ObservationIgnored
    private var observer: DarwinObserver?

    init() {
        observer = DarwinObserver(Mailbox.ping) { [weak self] in
            self?.drain()
        }
        drain()
    }

    /// Moves every waiting message out of the mailbox.
    func drain() {
        guard let mailbox else { return }
        do {
            try mailbox.receive(SharedLink.self) { links.append($0) }
        } catch {
            // Whatever was not handled is still in the inbox; the next
            // drain picks it up.
        }
    }
}

@main
struct ExampleApp: App {
    @Environment(\.scenePhase) private var scenePhase
    @State private var inbox = Inbox()

    var body: some Scene {
        WindowGroup {
            List(inbox.links, id: \.url) { Text($0.note) }
        }
        .onChange(of: scenePhase) { _, phase in
            if phase == .active { inbox.drain() }
        }
    }
}

In a UIKit app, call drain() from sceneDidBecomeActive(_:) instead.

A race condition can make the message arrive twice. If the app is killed after handling one and before deleting its file, the next drain hands it over again, so whatever the app does with a message has to cope with seeing it a second time. The array in the example only stands in for that; a real app saves the message somewhere before the file goes.

Notification service extensions

A notification service extension runs when an alert notification with mutable-content arrives, and it has no more than 30 seconds to process the notification and take any other necessary actions. It can't launch the app or open it. The usual request is to get whatever the push brought into the app's data straight away.

For that, use the mailbox. Write what the app needs, ring the doorbell, and hand the content back:

import UserNotifications

/// What the notification tells the app.
struct ArrivedMessage: Codable, Sendable {
    let id: String
}

final class NotificationService: UNNotificationServiceExtension {
    private var contentHandler: ((UNNotificationContent) -> Void)?
    private var content: UNMutableNotificationContent?

    override func didReceive(
        _ request: UNNotificationRequest,
        withContentHandler contentHandler:
            @escaping (UNNotificationContent) -> Void
    ) {
        self.contentHandler = contentHandler
        let content = request.content.mutableCopy()
            as? UNMutableNotificationContent
        self.content = content

        // A note for the app. It reads it the next time it runs, or now,
        // if it's running and hears the doorbell.
        if let id = request.content.userInfo["id"] as? String {
            try? Mailbox(appGroup: "group.com.example.app")?
                .send(ArrivedMessage(id: id))
        }
        contentHandler(content ?? request.content)
    }

    override func serviceExtensionTimeWillExpire() {
        if let contentHandler, let content {
            contentHandler(content)
        }
    }
}

For data the app needs only when the person taps the notification, there's a simpler route: leave it in the notification's userInfo. A tap that launches the app brings the response in the scene's connection options as notificationResponse, and a tap while the app is running goes to userNotificationCenter(_:didReceive:withCompletionHandler:). Either way, the payload is in response.notification.request.content.userInfo.

What the extension can't do is get the app to run before the person opens it. If that matters, you can try to have your server send a background notification as well; see the section on pushes further down to understand the downsides of that.

Location push service extensions

A location push service extension runs when your server sends a location push. It finds the device's location and sends it to your server, which is the job Apple designed it for. Apple's article on creating one lists the conditions. The app needs Always authorization, and a device gets about 360 location pushes a day, refilled at roughly one every few minutes.

For the app's copy, it's the mailbox again:

import CoreLocation

/// A location for the app to pick up.
struct SharedLocation: Codable, Sendable {
    let latitude: Double
    let longitude: Double
    let time: Date
}

final class LocationPushService: NSObject, CLLocationPushServiceExtension,
                                 CLLocationManagerDelegate {
    private var completion: (() -> Void)?
    private var manager: CLLocationManager?

    func didReceiveLocationPushPayload(
        _ payload: [String: Any], completion: @escaping () -> Void
    ) {
        self.completion = completion
        let manager = CLLocationManager()
        manager.delegate = self
        manager.requestLocation()
        self.manager = manager
    }

    func locationManager(_ manager: CLLocationManager,
                         didUpdateLocations locations: [CLLocation]) {
        if let location = locations.last {
            // Send it to your server first. Then leave a copy for the app.
            try? Mailbox(appGroup: "group.com.example.app")?.send(
                SharedLocation(latitude: location.coordinate.latitude,
                               longitude: location.coordinate.longitude,
                               time: location.timestamp))
        }
        finish()
    }

    func locationManager(_ manager: CLLocationManager,
                         didFailWithError error: any Error) {
        finish()
    }

    func serviceExtensionWillTerminate() {
        finish()
    }

    private func finish() {
        completion?()
        completion = nil
    }
}

The same article tells you not to keep sending pushes for long-running or frequent location work, and to hand that work to the app instead, with Core Location's liveUpdates(_:). That reads like a call the extension makes. It isn't. Nothing gets handed over for you, and the extension has no way to start anything in the app.

What it means is that the app runs the continuous part itself. The WWDC23 session Discover streamlined location updates explains the pieces. An app receiving live updates in a CLBackgroundActivitySession keeps getting them in the background, and if it's terminated, Core Location launches it in the background again when there are updates. On that launch the app has to call liveUpdates(_:) again and recreate its session objects. The catch is that a background activity session can only be started while the app is in the foreground; from the background, the app can only rejoin one it started earlier. Apple's background location guide says the same of CLServiceSession.

So the app starts continuous sharing when the person turns it on, with the app on screen, and keeps it going until they turn it off:

import CoreLocation

/// Continuous sharing, run by the app itself.
@MainActor
final class LocationSharing {
    private var service: CLServiceSession?
    private var background: CLBackgroundActivitySession?
    private var updates: Task<Void, Never>?

    /// Call when the person turns sharing on, with the app on screen,
    /// and again at every launch while sharing is on.
    func start() {
        service = CLServiceSession(authorization: .always)
        background = CLBackgroundActivitySession()
        updates = Task {
            do {
                for try await update in CLLocationUpdate.liveUpdates() {
                    if let location = update.location { report(location) }
                }
            } catch {
                // The updates ended; log it.
            }
        }
    }

    /// Call when the person turns sharing off.
    func stop() {
        updates?.cancel()
        background?.invalidate()
        service?.invalidate()
        updates = nil
        background = nil
        service = nil
    }

    private func report(_ location: CLLocation) {
        // Send it to your server.
    }
}

Keep a flag in the shared container that says sharing is on, and call start() at launch whenever it's set. The extension then handles the occasional request while continuous sharing is off. If the extension learns that continuous sharing should start, it can only leave a note in the mailbox; the app acts on it the next time the person opens it.

Darwin notifications Not to be confused by push notifications

The mailbox's doorbell is a Darwin notification: a name posted to the system's notification server, which tells every process registered for that name. The API is notify.h, and the two calls you need are notify_post and notify_register_dispatch, both used in the mailbox code above. Every process on the device shares the same names, so start yours with your App Group identifier.

What a notification carries

Nothing. A posted notification is an event with no contents at all.

The notification server does keep one 64-bit number per name, which any process can set with notify_set_state and read with notify_get_state. That number isn't attached to any notification; it's a variable that happens to live next to the name. Each set replaces the old value, and a process gets whatever the value is at the moment it asks. In my test below, three notifications posted with the values 1, 2 and 3 all read 3 when they were delivered. A version counter is about the most it's good for. Messages go in the container.

Use notify.h or Core Foundation?

Core Foundation offers the same notifications through CFNotificationCenterGetDarwinNotifyCenter(), which its documentation describes as a front end to notify.h. Its functions are the same ones used for distributed notifications on the Mac, which is why they take an object, a userInfo dictionary and a deliverImmediately flag. For Darwin notifications, CFNotificationCenterPostNotification ignores all three. No version of a Darwin notification carries a dictionary, or reaches a suspended app any sooner.

So the choice is only about convenience. The Core Foundation version needs the main thread's run loop and a C callback with a context pointer. notify.h takes a block, runs it on any queue you like, and gives you the state variable. I use notify.h.

When the app is suspended

Apple's reply to a developer whose background app kept missing these: iOS doesn't resume a suspended app to deliver one. If the app is resumed later, it should get the notification then. If it's terminated while suspended, it never does.

I wanted to know what "should" means in practice, so I tested it in the iOS 27 simulator. The test app logs a line every second while it runs, so the log shows exactly when it's suspended, and logs every Darwin notification it receives.

Posted while suspended	Then	Delivered
3 notifications, 5 s apart	resumed 30 s later	3, within a millisecond of resuming, all reading the last state value
1 notification	resumed about 12 hours later	1, on resuming
100 notifications in 14 s	resumed 5 s later	17, on resuming
1 notification	terminated, then launched	none

A notification posted to a suspended app is held for as long as the process lives. There's no documented time limit. The practical limit is the suspended process itself, which the system can terminate at any moment to free memory. And what's held isn't a queue. The notify(3) man page says notifications posted in quick succession may be coalesced, and that the kernel's queues for them are limited, which is how 100 posts turned into 17. One delivery tells you something was posted since you last looked. It never tells you how many times.

Run tests like this from the Home Screen. Apple's reply makes the point too: under the Xcode debugger the app is never suspended, so notifications that would wait, or be lost, arrive straight away.

CFMessagePort

CFMessagePort gets suggested because it can carry data. Its documentation says CFMessagePortCreateLocal returns NULL on iOS 7 and later, and on the Mac, where it does work, Apple's advice is to use XPC. Leave it alone.

Getting the app to run

The mailbox waits for the app. These don't, but each one works only for some extensions, or only from some parts of the system. Check that yours is one of them before you plan around it.

A background URL session

If the extension has a file to download or upload, it can hand the transfer to a background URLSession and finish. When the transfer is done, the system wakes the containing app to deal with the result, not the extension. Apple's guide describes this, and a post by Apple DTS on networking in short-lived extensions fills in the details.

It goes like this:

The extension creates a background session in the App Group, starts the task, and finishes. The system carries on with the transfer.
When the transfer ends and no process is connected to the session, the system resumes the app, or launches it in the background, and calls application(_:handleEventsForBackgroundURLSession:completionHandler:).
The app creates a session with the same identifier, which reconnects to the transfer, and the session's delegate gets the results.
When the session calls urlSessionDidFinishEvents(forBackgroundURLSession:), the app invalidates the session and calls the completion handler it got in step 2, on the main thread.

The configuration and the delegate go in shared code:

import Foundation

/// The background session both targets use.
enum Transfer {
    static let sessionID = "com.example.app.transfer"
    static let appGroup = "group.com.example.app"

    /// Creates, or reconnects to, the shared background session.
    static func session(delegate: URLSessionDelegate) -> URLSession {
        let configuration = URLSessionConfiguration
            .background(withIdentifier: sessionID)
        // Required in an extension: without it the session is
        // invalidated as soon as it is created.
        configuration.sharedContainerIdentifier = appGroup
        // Wake or launch the app when the transfer needs attention.
        configuration.sessionSendsLaunchEvents = true
        return URLSession(configuration: configuration,
                          delegate: delegate, delegateQueue: nil)
    }
}

/// A downloaded file waiting in the App Group container.
struct DownloadedFile: Codable, Sendable {
    let name: String
}

/// Compiled into both targets: whichever process is connected to the
/// session when a task finishes gets the callback.
final class TransferDelegate: NSObject, URLSessionDownloadDelegate {
    private let finishedEvents: @Sendable () -> Void

    init(finishedEvents: @escaping @Sendable () -> Void = {}) {
        self.finishedEvents = finishedEvents
    }

    func urlSession(_ session: URLSession,
                    downloadTask: URLSessionDownloadTask,
                    didFinishDownloadingTo location: URL) {
        // `location` is temporary: move the file before returning, into
        // the shared container, and tell the app it is there.
        let files = FileManager.default
        guard let root = files.containerURL(
                  forSecurityApplicationGroupIdentifier: Transfer.appGroup),
              let mailbox = Mailbox(appGroup: Transfer.appGroup)
        else { return }
        let name = UUID().uuidString
        do {
            try files.moveItem(at: location,
                               to: root.appending(path: name))
            try mailbox.send(DownloadedFile(name: name))
        } catch {
            // Log it; the download has to be retried.
        }
    }

    func urlSessionDidFinishEvents(forBackgroundURLSession session: URLSession) {
        finishedEvents()
    }
}

The extension starts the download and gets out of the way:

func download(_ url: URL) {
    let session = Transfer.session(delegate: TransferDelegate())
    session.downloadTask(with: url).resume()
    // The extension can be terminated from here on; the system finishes
    // the download and hands the result to the app.
    extensionContext?.completeRequest(returningItems: nil)
}

The app picks it up:

import UIKit

final class AppDelegate: NSObject, UIApplicationDelegate {
    private var session: URLSession?
    private var finishEvents: (() -> Void)?

    func application(
        _ application: UIApplication,
        handleEventsForBackgroundURLSession identifier: String,
        completionHandler: @escaping () -> Void
    ) {
        finishEvents = completionHandler
        // Creating the session with the same identifier reconnects to
        // it. Never create a second one with the same identifier in one
        // process.
        guard session == nil else { return }
        session = Transfer.session(delegate: TransferDelegate { [weak self] in
            Task { @MainActor in self?.eventsDone() }
        })
    }

    private func eventsDone() {
        // Disconnect, so the extension can use the session next time,
        // then tell the system the app has handled everything.
        session?.finishTasksAndInvalidate()
        session = nil
        finishEvents?()
        finishEvents = nil
    }
}

A SwiftUI app attaches this class with @UIApplicationDelegateAdaptor.

Three things trip people up. Only one process can be connected to a background session at a time, and a second one that creates it gets NSURLErrorBackgroundSessionInUseByAnotherProcess; that's why the app invalidates the session when it's done with it. A short transfer may finish while the extension is still around and complete there, a long one completes in the app, and you can't choose, so the delegate lives in both. And with Background App Refresh turned off, for the app or for the whole device, the system doesn't wake the app for the session at all. Apple's reply dates that to iOS 13. The extension can't check the setting, but the app can, and can warn the person that transfers finish only when they open it:

let wakes = UIApplication.shared.backgroundRefreshStatus == .available

App Intents, from widgets and controls

An app intent is a Swift type that describes one thing your app can do: a title, the parameters it needs, and a perform() method that does it. You write it once, and the system can then run it for you from Shortcuts, Siri, Spotlight, the Action button, a control in Control Center, or a button in a widget or a Live Activity, without the person opening the app. The framework is App Intents, which arrived in iOS 16 and has grown in every release since.

import AppIntents

/// Saves a link. The system runs `perform()` when the button is tapped.
struct SaveLinkIntent: AppIntent {
    static let title: LocalizedStringResource = "Save Link"

    // iOS 27: run this in the app's process, never the widget's.
    static var allowedExecutionTargets: IntentExecutionTargets { .main }

    @Parameter(title: "Link")
    var url: URL

    init() {}

    init(url: URL) {
        self.url = url
    }

    func perform() async throws -> some IntentResult {
        try Mailbox(appGroup: "group.com.example.app")?
            .send(SharedLink(url: url, note: "From the widget"))
        return .result()
    }
}

A widget runs it from a button:

Button(intent: SaveLinkIntent(url: url)) {
    Label("Save", systemImage: "bookmark")
}

What matters for this article is which process runs perform(). By default, a widget's intent runs in the widget extension. WidgetKit's documentation lists the cases where it runs in the app instead: intents that conform to LiveActivityIntent, AudioPlaybackIntent, ForegroundContinuableIntent or PushToTalkTransmissionIntent, and intents that set openAppWhenRun. For a LiveActivityIntent, the system launches the app's process without bringing the app to the screen.

The last two releases changed how you say where an intent runs. iOS 26 deprecated openAppWhenRun in favour of supportedModes, which says whether an intent runs in the background, in the foreground, or starts in one and moves to the other. iOS 27 added allowedExecutionTargets, which names the processes that may run it: .main for the app, .appIntentsExtension, .widgetKitExtension, or a combination (IntentExecutionTargets). Left alone, it's any available target. The intent above says .main, so its code always runs in the app. iOS 27 also added LongRunningIntent, for work that needs more than the usual 30 seconds; Apple's App Intents updates page has the rest. Whichever you use, the intent has to be compiled into the app target for the app to run it.

This only helps where the system runs intents. A share extension, a notification service extension or a location push extension can't run an app intent to reach the app.

Opening the app

A widget or Live Activity can open the app when it's tapped, with widgetURL(_:), a Link, or a button that runs an OpenURLIntent (iOS 18), which hands one of your universal links to the app:

if let url = URL(string: "https://example.com/links") {
    Button(intent: OpenURLIntent(url)) {
        Label("Open", systemImage: "arrow.up.forward.app")
    }
}

A share or action extension has no supported way to do it. NSExtensionContext.open(_:completionHandler:) works only where the extension point allows it, which on iOS means Today and iMessage extensions, and an iMessage extension can open only its own app. When a developer asked in 2025, Apple's reply was that there's no supported way to launch an app from an app extension, Today extensions and widgets aside.

There are workarounds going around that reach UIApplication from inside an extension. They aren't part of the documented API, they can break in any release, and App Review guideline 2.5.1 asks apps to use public APIs only for their intended purpose. I won't go into them here.

A push from your own server

Any extension that can reach the network can ask your server to wake the app with a background notification. The request to APNs carries apns-push-type: background and apns-priority: 5, and the payload holds nothing but content-available:

{ "aps": { "content-available": 1 } }

The app treats it as one more reason to check the mailbox:

func application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any]
) async -> UIBackgroundFetchResult {
    // The push is the wake-up; the message is in the mailbox.
    drainMailbox()
    return .newData
}

But don't count on it. Apple's documentation says the system treats these as low priority, doesn't guarantee delivery, throttles them, and suggests no more than two or three an hour. It launches the app if it has to, unless the person force-quit it, and gives it up to 10 seconds.

Network Extension and File Provider

These two extension types are the exceptions: each has a real channel to the app.

Network Extension

The containing app sends Data to its tunnel provider with sendProviderMessage(_:responseHandler:), and the provider answers in handleAppMessage(_:completionHandler:). Only the app can start an exchange. The documentation warns that the app may not be running when the provider is, since the provider can be started from Settings or by Connect On Demand, so don't use this channel to start or stop the tunnel.

When the provider has news for the app, Apple's reply suggests long polling. The app asks for the status, the provider holds on to the completion handler and calls it at the next change, and the app asks again:

// App side.
@MainActor
final class TunnelStatus {
    func watch(_ session: NETunnelProviderSession) {
        do {
            try session.sendProviderMessage(Data("status".utf8)) { reply in
                Task { @MainActor in
                    if let reply { self.show(reply) }
                    self.watch(session)   // ask again: long polling
                }
            }
        } catch {
            // The provider is not running; observe NEVPNStatusDidChange.
        }
    }

    func show(_ data: Data) {}
}

// Provider side.
final class PacketTunnelProvider: NEPacketTunnelProvider {
    private var waiting: (@Sendable (Data?) -> Void)?

    override func handleAppMessage(
        _ messageData: Data,
        completionHandler: (@Sendable (Data?) -> Void)? = nil
    ) {
        // Keep the request open; answer it at the next change.
        waiting = completionHandler
    }

    func statusChanged(to status: Data) {
        // A completion handler can be called only once.
        waiting?(status)
        waiting = nil
    }
}

If connected and disconnected are all you need, observe NEVPNStatusDidChange and skip the messaging.

File Provider

NSFileProviderService gives the app and a File Provider extension an NSXPCConnection, with an @objc protocol both sides compile. The extension offers services through NSFileProviderServiceSource, and the app asks for them by item:

@objc protocol AccountService {
    func signOut(reply: @escaping (Error?) -> Void)
}

func accountService(for item: URL) async throws -> AccountService? {
    let services = try await FileManager.default
        .fileProviderServicesForItem(at: item)
    let name = NSFileProviderServiceName("com.example.account")
    guard let service = services[name] else { return nil }
    let connection = try await service.fileProviderConnection()
    connection.remoteObjectInterface = NSXPCInterface(with: AccountService.self)
    connection.resume()
    return connection.remoteObjectProxy as? AccountService
}

The documentation says a service you get this way works only on the item at that URL. For something that isn't about one item, like signing out, one developer reports that the root container works (NSFileProviderItemIdentifier.rootContainer). Apple hasn't said whether that's intended. You should treat anything that is not documented as a bug that will eventually be fixed.

The shared container

Everything else goes through the App Group container: UserDefaults(suiteName:) for small values, files under containerURL(forSecurityApplicationGroupIdentifier:), a Core Data, SwiftData or SQLite store kept there, and a shared keychain access group for secrets.

UserDefaults(suiteName: "group.com.example.app")?
    .set(Date.now, forKey: "lastShare")

Two processes are now using the same files, and Apple's guide asks you to coordinate with Core Data, SQLite or POSIX locks. File coordination works as well, on one condition: an extension that uses NSFilePresenter has to remove its presenters when it goes into the background.

Locks are also how the shared container gets processes killed. A process suspended while holding a file lock or an SQLite database lock is terminated with the code 0xdead10cc. Apple's crash report documentation gives the fix: ask for time to finish the work and release the lock before suspension. A database open in both the app and an extension, either of which can be suspended at any moment, is where this usually comes from. Wrap each write:

// In the app.
let task = UIApplication.shared.beginBackgroundTask(withName: "Save")
save()
UIApplication.shared.endBackgroundTask(task)

// In an extension, which can't use UIApplication.
ProcessInfo.processInfo.performExpiringActivity(withReason: "Save") { expiring in
    guard !expiring else { return }
    save()
}

The mailbox above stays clear of all this. It never holds a file open, and the only process that deletes messages is the app.

Which mechanism for which job

Mechanism	Works from	Carries data	App suspended	App not running
Mailbox in the shared container	any extension	yes	read when resumed	read at next launch
Darwin notification	any extension	no; a shared 64-bit value beside it	held until resumed, coalesced	lost
Background `URLSession`	extensions that transfer files	the transferred file	app resumed	app launched, unless Background App Refresh is off
Background push from your server	any extension that can reach the network	the push payload	app resumed	app launched, unless force-quit; throttled
App intent run in the app	widgets, Live Activities, controls	the intent's parameters	runs	app process launched
`widgetURL`, `Link`, `OpenURLIntent`	widgets, Live Activities	a URL	app opened	app opened
Provider messages	Network Extension	`Data`, request and reply	the app starts every exchange
File Provider service	File Provider	XPC calls	the app starts every connection

Sources

Apple documentation:

Apple Developer Forums:

Darwin notifications and suspended apps, Apple's reply
CFMessagePort and XPC, Apple's reply
Networking in a short-lived extension, a post by Apple DTS
Background sessions and Background App Refresh, Apple's reply
Opening an app from a share extension, Apple's reply
Messaging between a VPN app and its provider, Apple's reply
A File Provider service without an item, a developer's report

Other:

MMWormhole, archived

What happened to launchOptions

Thu, 15 Oct 2026 00:00:00 +0000

application(_:didFinishLaunchingWithOptions:) still has a launchOptions parameter, and in a scene-based app it is always nil.

Apple’s documentation for the parameter says so in one line: "If the app supports scenes, this is nil."

Code that checks it for the reason the app was launched finds nothing in an app with a scene manifest.

Until now that was a choice. The iOS 27 release notes make it the rule: "Apps built with the latest SDK must adopt the scene-based life cycle or they fail to launch."

All 14 UIApplication.LaunchOptionsKey values are deprecated, twelve of them in iOS 26, and each key's documentation page names what to use instead.

The 14 launch options

Six moved to UIScene.ConnectionOptions, which UIKit passes to scene(_:willConnectTo:options:) when it creates a scene, and eventAttribution now travels with the URL it belongs to.

Five described launches for background work. For those there is nothing in the connection options; the replacement is the object that asked for the event, recreated at every launch.

Two are no longer used.

Launch option	Deprecated	Use instead
`url`	iOS 26	`urlContexts` in the connection options
`sourceApplication`	iOS 26	`sourceApplication` in the connection options
`shortcutItem`	iOS 26	`shortcutItem` in the connection options
`userActivityDictionary`	iOS 26	`userActivities` in the connection options
`userActivityType`	iOS 26	`handoffUserActivityType` in the connection options
`cloudKitShareMetadata`	iOS 26	`cloudKitShareMetadata` in the connection options
`eventAttribution`	iOS 26	`eventAttribution` in the `options` of each URL context
`bluetoothCentrals`	iOS 26	Create the `CBCentralManager` at launch with the same `CBCentralManagerOptionRestoreIdentifierKey`. The state arrives in `centralManager(_:willRestoreState:)`.
`bluetoothPeripherals`	iOS 26	The same for `CBPeripheralManager`, with `CBPeripheralManagerOptionRestoreIdentifierKey` and `peripheralManager(_:willRestoreState:)`.
`location`	iOS 26	Restart `CLLocationUpdate` or `CLMonitor`, or recreate the `CLLocationManager` and its delegate. Location data was never in the launch options; it always went to the delegate.
`remoteNotification`	iOS 26	`application(_:didReceiveRemoteNotification:fetchCompletionHandler:)` for a silent notification. A notification the person tapped arrives as `notificationResponse` in the connection options.
`newsstandDownloads`	iOS 26	Nothing. No longer used.
`annotation`	iOS 16	Nothing. No longer used.
`localNotification`	iOS 10	`userNotificationCenter(_:didReceive:withCompletionHandler:)`

The 14 connection options

UIScene.ConnectionOptions carries the reason UIKit created the scene. Seven of its properties date from iOS 13, when scenes arrived. Six belong to other frameworks whose events can create a scene. The last, sceneAccessoryUserInfo, is new in UIKit in iOS 27.

Connection option	Framework, since	Why the scene was created
`urlContexts`	UIKit, iOS 13	URLs to open, each with its options
`sourceApplication`	UIKit, iOS 13	the bundle ID of the app that made the request
`shortcutItem`	UIKit, iOS 13	a Home Screen quick action
`userActivities`	UIKit, iOS 13	user activities to configure the scene's interface from
`handoffUserActivityType`	UIKit, iOS 13	the type of a pending Handoff activity
`cloudKitShareMetadata`	UIKit, iOS 13	an accepted CloudKit share
`notificationResponse`	UIKit, iOS 13	a person's response to a notification
`nfcEvent`	Core NFC, iOS 17.4	an NFC reader's field, or a gesture to start a contactless transaction
`credentialSessionEvent`	SecureElementCredential, iOS 17.4	a credential session event
`marketplaceDisplayOption`	MarketplaceKit, iOS 17.4	a deep link the system makes into an alternative app marketplace
`gameControllerActivationContext`	Game Controller, iOS 18	a game controller event; carries the previously active app's bundle ID
`appIntent`	App Intents, iOS 26	an app intent that opens the app; `scene(_:willPerform:)` follows
`shouldHandleActiveWorkoutRecovery`	HealthKit UI, iOS 26	a workout session to recover
`sceneAccessoryUserInfo`	UIKit, iOS 27	the user info given when the scene accessory was created

Important: The six framework options are declared by their own frameworks, not by UIKit, and importing UIKit does not bring them in. Import the framework in the file where the scene delegate reads them. If nothing in the module imports it, the property does not exist and the compiler reports "value of type 'UIScene.ConnectionOptions' has no member 'nfcEvent'". With Swift's member import visibility turned on (SE-0444), an import in another file is not enough either: the import has to be in the same file, and the error names the missing module.

import UIKit
import AppIntents               // appIntent
import CoreNFC                  // nfcEvent
import GameController           // gameControllerActivationContext
import HealthKitUI              // shouldHandleActiveWorkoutRecovery
import MarketplaceKit           // marketplaceDisplayOption
import SecureElementCredential  // credentialSessionEvent

Import only the ones whose events your app handles.

Apple's pages for marketplaceDisplayOption, gameControllerActivationContext and shouldHandleActiveWorkoutRecovery have no description; those rows come from the types they return and the SDK headers. The same pages list the last two under UIKit, but they are declared in Game Controller and HealthKit UI.

The connection options describe the launch that created the scene. When the scene already exists, UIKit calls a scene delegate method instead: scene(_:openURLContexts:) for URLs, scene(_:continue:) for user activities, windowScene(_:performActionFor:completionHandler:) for quick actions and windowScene(_:userDidAcceptCloudKitShareWith:) for shares.

A scene delegate that covers the common cases:

func scene(_ scene: UIScene, willConnectTo session: UISceneSession,
           options connectionOptions: UIScene.ConnectionOptions) {
    // was .url
    if let context = connectionOptions.urlContexts.first {
        open(context.url)
    }
    // was .shortcutItem
    if let item = connectionOptions.shortcutItem {
        perform(item)
    }
    // was .userActivityDictionary
    if let activity = connectionOptions.userActivities.first {
        resume(activity)
    }
    // a notification the person tapped
    if let response = connectionOptions.notificationResponse {
        show(response)
    }
}

The launches with no connection option

Since there is no launch reason to test, the app delegate sets up whatever receives background events every time, whatever the reason for the launch:

func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions
        launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
    // launchOptions is nil in a scene-based app. Set up whatever
    // receives background events on every launch.
    UNUserNotificationCenter.current().delegate = notificationHandler
    let key = CBCentralManagerOptionRestoreIdentifierKey
    central = CBCentralManager(delegate: bluetooth, queue: nil,
                               options: [key: "central"])
    return true
}

The notification center's delegate belongs in the app delegate too. Its documentation asks for it to be set in application(_:willFinishLaunchingWithOptions:) or application(_:didFinishLaunchingWithOptions:), so that the notification that launched the app reaches it.

UIApplication.LaunchOptionsKey, with the replacement on each key's page
UIScene.ConnectionOptions
Transitioning to the UIKit scene-based life cycle

Core Location has a maritime activity type, as of iOS 27

Mon, 05 Oct 2026 00:00:00 +0000

iOS 27 added .maritime to CLActivityType, and a matching .maritime to CLLocationUpdate.LiveConfiguration. There was no WWDC session about it and the iOS 27 release notes do not mention it. It appears in the SDK headers and on two documentation pages, so most of the developers who need it have not seen it.

Apple's documentation describes it as positioning for "activities in vessels on water, including while anchored", with sailing, motor-boating and traveling by ship as the examples. Both are available from version 27 on every platform.

Until now the documented choice for a boat was .otherNavigation, whose description still lists boats alongside cycling, scooters, trains and off-road vehicles. An app used on the water should set .maritime on iOS 27 and later, and keep .otherNavigation for earlier systems.

With CLLocationManager:

if #available(iOS 27, macOS 27, watchOS 27, visionOS 27, *) {
    manager.activityType = .maritime
} else {
    manager.activityType = .otherNavigation
}

With live updates:

let configuration: CLLocationUpdate.LiveConfiguration
if #available(iOS 27, macOS 27, watchOS 27, visionOS 27, *) {
    configuration = .maritime
} else {
    configuration = .otherNavigation
}
for try await update in CLLocationUpdate.liveUpdates(configuration) {
    // ...
}

If location on the water has given you trouble, .maritime is the first thing to try. It is a one-line change, and the SDK header CLLocationUpdater.h describes it as "tuned for vehicular maritime use cases". Before you file a bug or write a filter for odd positions on the water, switch to it and look again.

A SensorKit fetch that returns nothing is usually asking for the wrong window

Tue, 22 Sep 2026 00:00:00 +0000

The fetch completes. sensorReader(_:didCompleteFetch:) is called. sensorReader(_:fetching:didFetchResult:) never is, and sensorReader(_:fetching:failedWithError:) never is either. There is no error to look up, because as far as the framework is concerned the request succeeded and matched nothing.

Almost always the request asked for a window that cannot contain data. The window has an edge at each end.

The recent edge: the 24-hour hold

SensorKit keeps newly recorded data to itself for 24 hours before any app can read it, so the user has a chance to delete what they would rather not share. That much is documented on SRFetchRequest, along with the part that surprises people:

Important: A fetch request returns no results at all if its time range overlaps the holding period. The range is not trimmed to the part that has aged past the hold. One hour of overlap and the whole request comes back empty.

So to: Date(), the obvious thing to write and the thing every first implementation writes, can never return a sample. Neither can "the last hour", or "today". The most recent moment worth asking for is 24 hours ago, and asking for anything newer costs the entire result, not the tail of it.

The far edge: before your app was authorized

An app cannot fetch anything from before the moment the user authorized it. That is the floor, it is per app, and nothing moves it.

This is the edge the documentation makes easy to misread. SRSensorReader says an app "has access to 7 days of prior recorded data for an active sensor", which reads like a promise that a device already recording for another app or for the system will hand you a week of history as soon as you are authorized. It will not. The sensor may have been running for months and the samples may be sitting on the device, but your window opens at your own authorization and not one second earlier. A from behind that point does not return a truncated result. It returns nothing.

Design the onboarding for that. An app that asks for a week of history on the day the user consents has nothing to show them, and the emptiness looks identical to a bug.

The same floor is what makes a development cycle painful. Deleting the app and reinstalling resets its authorization, and therefore resets the floor; installing a new build over the old one does not. A workflow built on delete-and-reinstall starts every test run at the bottom of a fresh 24-hour hole, usually with a from that predates the new authorization and a to inside the hold. Both edges are wrong at once, and there is no error either way.

Writing a request that can succeed

Record the moment your app was authorized and persist it. Clamp every from to it, rather than passing a date from the study protocol or a date picker.
Put to at least 24 hours in the past. Treat "now" as unavailable, not as a boundary to approach.
Advance from using the timestamp of the newest sample you have actually received, not the time of your last fetch. The gap between those two is data you will never ask for again.
During development, install over the previous build. Reserve delete-and-reinstall for the times you mean to start the clock again, and expect to wait a day when you do.

Neither edge has a switch. Both are privacy guarantees to the user. The hold gives them time to delete, and the floor means consent applies from the moment it is given, not retroactively. There is no entitlement or debug setting that shortens either one. The testing schedule has to absorb them, and so does anything you promise a study participant on their first day.

The default contactless app is woken by every reader

Tue, 22 Sep 2026 00:00:00 +0000

An app holding com.apple.developer.nfc.hce.default-contactless-app and selected as the default app receives NFCWindowSceneEvents when the phone meets a reader. The events apps expect are the ones for the cards they support. The events they get also include the access reader in the office lobby, the transit gate and the hotel room door.

There is no way to narrow this, and the shape of the event says why. readerDetected reports the presence of a reader. It is a field-level signal, raised before any application identifier has been exchanged, and at that instant nothing on the device knows which AID the reader is about to ask for. The prefixes declared in com.apple.developer.nfc.hce.iso7816.select-identifier-prefixes govern what your CardSession can answer once you are emulating a card. They do not govern whether you are woken.

Also, there can only be one default. The entitlement lets a person choose your app in Settings, and that choice is singular: whatever they pick is the front door for every contactless interaction on the device. So the unsupported cases are not edge cases, they are most cases, and they need designing: come up, make it obvious you are not the right credential, and get out of the way without the user having to dismiss anything.

Which invites a question worth asking before applying for the entitlement. If your app services limited identifiers, being the default means appearing at every reader its user walks past and being useless at nearly all of them. Being the default is a commitment to the whole surface, not a claim on the part of it you care about. An app that does one thing well is often better off letting the user invoke it, and leaving the front door to something general.

There is probably a logging profile for whatever you are stuck on

Tue, 22 Sep 2026 00:00:00 +0000

Your logs show what your code did. They rarely show what the system decided, which is usually the part you need: why the scan discovered nothing, why the silent push never woke the app, why the region event arrived four minutes after the boundary. At the default log level most of that reasoning is never written down, so you are left inferring it from the outside.

Apple publishes a configuration profile for each of those subsystems on the Profiles and Logs page. Installing one raises the log level for that subsystem on the device, and its internal decisions then appear in Console and in any sysdiagnose you capture.

The list runs to well over a hundred entries and is easy to walk past. The ones that matter for the problems this site covers include Bluetooth, with a separate profile for each of iOS, macOS, watchOS, tvOS and visionOS; Location Services for iOS, macOS and watchOS; APNs; CoreNFC and SEC Frameworks; Accessory Setup Kit; Nearby Interaction; HealthKit; Background Networking; CFNetwork; and Network Diagnostics. Further down there are profiles for Battery Life, Memory Exception and HangTracer for slow UI, which are worth knowing about before you need them.

Two things decide whether this is useful or wasted effort.

Install the profile before you reproduce the problem. A sysdiagnose contains the log buffer as it was actually written, so a profile installed afterwards tells you nothing about what already happened. This is the most common reason a carefully collected sysdiagnose turns out to be worthless, and noticing costs you another full reproduction cycle.

Remove the profile when you are finished. They are verbose by design, and there is no reason to keep one running on a device you are no longer investigating.

One practical detail: the page used to live at developer.apple.com/bug-reporting/profiles-and-logs/, which still redirects. Older forum threads and support mail point at that address, so a dead-looking link is usually just the old one.

Why Core Bluetooth state restoration never fires

Mon, 21 Sep 2026 00:00:00 +0000

Is Bluetooth State Restoration broken?

You follow the documentation, you set CBCentralManagerOptionRestoreIdentifierKey, the system terminates your app in the background, the accessory sends something, and the app does not come back. The conclusion most people reach at that point is that state restoration is broken. But it almost never is.

State restoration has strict rules, and if any one of them is not met, the app will not be relaunched. Apple covers them in the Core Bluetooth Programming Guide, in technote TN3115, and in the API reference for the restoration keys and delegate methods. This article puts them together in one place.

How restoration works

An app running in the background is sooner or later going to be terminated by the system, to free up memory for something else. If the app's Core Bluetooth managers opted in to state restoration, the system holds on to their state when that happens: the scans in progress, the pending connections, the connected peripherals and the characteristics the app subscribed to. When a Bluetooth event arrives that the app was waiting for, the system launches the app in the background, hands that state back, and delivers the event. The Core Bluetooth Programming Guide describes the mechanism, and gives an app woken up this way about 10 seconds to deal with the event.

So restoration is a relaunch for a specific Bluetooth event. If the app was not waiting for any event when it was terminated, the system has no reason to bring it back.

What your app has to do

There are four requirements on the app side, and you need all of them.

1. Declare the background mode

Add bluetooth-central to UIBackgroundModes if the app is a central, bluetooth-peripheral if it is a peripheral, or both if it is both:

<key>UIBackgroundModes</key>
<array>
    <string>bluetooth-central</string>
</array>

2. Use the same restoration identifier on every launch

The documentation for the key says the identifier has to be identical across executions of the app, because that is how the system matches the state it saved to the manager you create. If you generate a UUID at launch, or build the string from anything that can change, the system has nothing to match it to.

3. Create the manager at every launch

The programming guide was written before scenes, and its example looks in launchOptions for UIApplicationLaunchOptionsBluetoothCentralsKey to find out which managers to recreate. In a scene-based app launchOptions is always nil, and with the iOS 27 SDK every app is scene-based. The key's documentation describes the current way: persist the identifier yourself, and create the manager with it on every launch, whatever the launch was for. I have a note on launchOptions that covers the rest of the keys that went the same way.

4. Implement centralManager(_:willRestoreState:)

When the system relaunches the app for restoration, this is the first CoreBluetooth delegate method it calls, before centralManagerDidUpdateState(_:). The dictionary it passes holds the peripherals that were connected or had a connection pending, and the services the manager was scanning for. You will want to keep those peripherals and set yourself as their delegate again. If you do not, their events have nowhere to go.

Important: sometimes the system will know to relaunch your app but the parameters passed to willRestoreState may be empty. In that case you will need to restore the state of your app/centrals/peripherals yourself, or start discovery from scratch

Here is a central that covers all four:

import CoreBluetooth

/// Owns the central manager. Created at every launch, whatever the reason
/// for the launch, so a restoration has something to restore into.
final class Bluetooth: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate {
    /// The same string on every launch, or restoration finds nothing.
    static let restoreID = "com.example.app.central"

    private var central: CBCentralManager?
    private var known: [UUID: CBPeripheral] = [:]

    override init() {
        super.init()
        central = CBCentralManager(
            delegate: self, queue: nil,
            options: [CBCentralManagerOptionRestoreIdentifierKey: Bluetooth.restoreID])
    }

    func centralManager(_ central: CBCentralManager,
                        willRestoreState state: [String: Any]) {
        // On a relaunch, this comes first. Take the peripherals back, and
        // be their delegate again, or their events go nowhere.
        let restored = state[CBCentralManagerRestoredStatePeripheralsKey]
            as? [CBPeripheral] ?? []
        for peripheral in restored {
            peripheral.delegate = self
            known[peripheral.identifier] = peripheral
        }
    }

    func centralManagerDidUpdateState(_ central: CBCentralManager) {
        guard central.state == .poweredOn else { return }
        // Pick up where the app left off. A pending connect is what gets
        // the app relaunched next time.
        for peripheral in known.values where peripheral.state == .disconnected {
            central.connect(peripheral)
        }
    }

    func centralManager(_ central: CBCentralManager,
                        didDisconnectPeripheral peripheral: CBPeripheral,
                        error: (any Error)?) {
        // Ask again straight away. The request stays pending while the app
        // is suspended or terminated, and the connection relaunches it.
        central.connect(peripheral)
    }
}

And the app delegate, which creates it on every launch:

import UIKit

final class AppDelegate: NSObject, UIApplicationDelegate {
    private var bluetooth: Bluetooth?

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions
            launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        // Every launch. In a scene-based app launchOptions is nil, so
        // there's no Bluetooth key to check, and nothing to check it for.
        bluetooth = Bluetooth()
        return true
    }
}

When the system relaunches the app

Apple's TN3115 spells out the first condition. The app is relaunched if, and only if, it was waiting for a specific Bluetooth event when it was terminated, and that event then happened. For a central that means scanning, a pending connection, or a characteristic the app subscribed to. For a peripheral it means advertising. An app that was connected to an accessory and doing nothing else is relaunched when the accessory disconnects, or when it sends a notification on a characteristic the app subscribed to.

The second condition is how the app stopped, and what the person has done since. TN3115 has the full list, including what happens after a restart. A simpler way to remember it is to ask who stopped the app. When the system terminates it, or it crashes, it comes back. When the person stops it, or stops Bluetooth, it may not. And if the app was only suspended, it is resumed rather than relaunched, so willRestoreState is not called at all.

The case that catches most people is the force-quit, because swiping the app away in the app switcher is also how most people try to test this. Once the person force-quits the app, the system does not relaunch it for Bluetooth events until they open it again.

Turning Bluetooth off is the other one, and it helps to know that there are two ways to do it. Turning it off in Settings, or with an Airplane Mode that includes Bluetooth, powers the radio off, and no app is relaunched after that, whatever it was waiting for. The Bluetooth button in Control Center does something else: Apple's support article describes it as disconnecting accessories while Bluetooth stays on.

Starting with iOS 26, apps that set up their accessories with AccessorySetupKit are relaunched after a force-quit and after the Control Center button, and other apps are not. Powering the radio off still ends restoration for everyone. If you are building an accessory app and have not looked at AccessorySetupKit yet, you should.

Before you blame restoration

Make sure the app was actually terminated. From the accessory's side, an app that is suspended, or still running but stuck somewhere it does not accept a connection, looks the same as one that was terminated and never came back. Log something in application(_:didFinishLaunchingWithOptions:) and in centralManager(_:willRestoreState:). If neither shows up after the event, the app was never relaunched, and the next thing to check is whether it was ever terminated in the first place.

If your app is the peripheral, keep in mind what happens to advertising in the background. The programming guide says the local name is not advertised, the service UUIDs go into an overflow area that only an iOS device explicitly scanning for them can see, and advertising may slow down when every advertising app is in the background. An accessory that looks for your app's local name will not find it while the app is in the background, whether it was terminated or not.

Testing it

Do not test this from Xcode. Under the debugger the app is not suspended or terminated the way it is in normal use, so you end up testing something that never happens on a customer's phone. Install the build, launch it from the Home Screen, and do not swipe it away, because that is the force-quit case above.

To terminate the app when you want to, give your debug build a button that kills the process. TN3115 says a crashed app is relaunched, and this is as close to a crash as you can get on purpose:

#if DEBUG
/// Debug builds only: end the process the way a crash does, not the way
/// a swipe in the app switcher does.
func terminateForRestorationTest() {
    kill(getpid(), SIGKILL)
}
#endif

Important: it is very easy to make a mistake a ship the kill code in production. So take utmost care that this code branch only exists in your debug builds.

Get a connection pending, press the button, then have the accessory do the thing the app is waiting for. If the app does not come back, install the Bluetooth logging profile before you reproduce it again, and take a sysdiagnose right after. The profile has to be installed before the problem happens, and I have a note on why.

If the person force-quits the app

On iOS 26 and later, AccessorySetupKit is the way to stay relaunchable. Without it, the most an app can do is let the person know. Schedule a local notification a few minutes ahead, and move it further ahead every time the app gets to run. As long as the app keeps running, the notification never fires. If the app is gone, the notification fires and asks the person to open the app again. It is a commonly used workaround.

Sources

Why an NFC reader session has a time limit

Mon, 21 Sep 2026 00:00:00 +0000

A recurring request: keep Core NFC listening. The user walks through a building tapping tags, and the app should pick each one up without a sheet appearing and disappearing every time. Is there a session configuration for that, or a way to restart the session so quickly that nobody notices?

There is not. The time limits are hard, they are documented, and the design that tries to hide them is a worse experience than the design that accepts them. Also, abusing the NFC subsystem on an iPhone will shorten the session time due to thermal stress.

What is fixed

The public CoreNFC headers state the rules plainly.

A reader session has a time limit from the moment init() is called. When it expires, the delegate receives readerSessionInvalidationErrorSessionTimeout.
One reader session can be active in the system at a time. A second init() while one is active fails with readerSessionInvalidationErrorSystemIsBusy.
Calling init() presents a modal system sheet. The sheet is dismissed when the session is invalidated, by your code, by the timeout, or by the user tapping Done, which produces readerSessionInvalidationErrorUserCanceled.
If the app leaves the foreground, the session ends with readerSessionInvalidationErrorSessionTerminatedUnexpectedly.
An invalidated session cannot be reused. restartPolling() on it does nothing. A new session means a new init(), and a new sheet.

None of these has a knob. There is no entitlement that extends the timeout, no configuration that suppresses the sheet, and no background mode for reader sessions.

Why it is built this way

Reader mode is not simply listening. It is transmitting. For as long as a session is active, the phone is driving its antenna to generate the RF field that powers whatever tag comes into range, as the tag has no battery and takes its energy from the phone. The energy that goes into that field is drawn from the battery, and what the field does not deliver to a tag ends up as heat in the antenna and the circuits around it.

That is a fine thing to do for the few seconds it takes to hold a phone against a tag. It is not a fine thing to do for the twenty minutes it takes to walk through a building. So the session is shaped like the interaction it exists for: short, started by the user, visible on screen while it runs, and over quickly. The time ceiling, the single active session, and the sheet are not three separate restrictions. They are one decision, that a reader session is a burst and not a mode.

Important: Restarting a session the instant it ends does not produce a “mode" either. Trying to use it as a trick will only shorten the time for the next session until the stress on the NFC subsystem will prevent the next session from starting altogether. And for a VoiceOver user, this gets worse as a new modal is announced every time. The app is now fighting the system on the user's screen, and the user can see it.

What one session can do

A single session can do more than one read. If the use is a short guided sequence, a couple of tags within a short time, it fits inside one session without any tricks.

Create the NDEF session with invalidateAfterFirstRead: false. It stays open after a successful read, until the timeout, invalidate(), or Done.
After handling a tag, call restartPolling() to discover the next one. Tag objects from before the restart are invalid; drop your references.
Update alertMessage after each read. The sheet's text can change while the session is valid, so it can say "Tag 2 of 5 read. Hold the phone near the next one."

When the session times out, tell the user it is over and let them start the next one. Do not start it for them.

What to build instead

Match the tool to the interaction.

One tag, one tap. Start a session on a deliberate user action, a button or a gesture, read the tag, invalidate with a message, done. This is what Core NFC is for. It is also the predictable shape for VoiceOver: one action, one sheet, one result.

No app involvement at all. Late model iPhones can read NDEF tags in the background without any reader session. Encode a universal link on the tag; when the user holds the phone near it, the system shows a notification, and tapping it delivers the tag's payload to your app. There are conditions, all documented: the phone must be in use and unlocked, no reader session may be active, and the camera and Wallet must not be in use. It still requires the user to tap the notification. That is the system's version of "tap a tag while walking around", and it is as close to a live mode as iOS offers.

Proximity over minutes, hands-free. If the requirement is really "know when the user is near a point of interest" rather than "the user touched this thing", NFC is the wrong radio. It works at a few centimetres and only on request. Beacon region monitoring in Core Location, or a Bluetooth LE scan for a service the beacons advertise, work at room scale and in the background, and are what wayfinding systems use. The tags can stay as the deliberate, precise action layered on top.

Handling the endings

Every session ends in readerSession(_:didInvalidateWithError:). Treat the error as the reason, not as a failure.

Error	What happened	What to do
`readerSessionInvalidationErrorFirstNDEFTagRead`	Read one tag, as configured	Nothing; this is success
`readerSessionInvalidationErrorUserCanceled`	The user tapped Done	Nothing; the user is in charge
`readerSessionInvalidationErrorSessionTimeout`	Sixty seconds elapsed	Tell the user; offer to start again
`readerSessionInvalidationErrorSessionTerminatedUnexpectedly`	The app left the foreground	Start again when the user returns and asks
`readerSessionInvalidationErrorSystemIsBusy`	Another session was active	Wait for it to end; do not retry in a loop

The one thing not on the list is "restart automatically". A session that begins without the user asking for it is the sheet appearing without warning, and that is the whole reason the request comes up in the first place.

The Long Answer

Trust Insights, or how your app can tell when someone is being talked through a scam

What it tells you

Not only banks

It all happens in the app

The app, step by step

1. Describe the operation

2. Ask for permission at a calm moment

3. Start the evaluation early

4. Decide, and report what you decided

5. Only add friction, and keep a record

What you cannot test, and whose job that is

Start

Further reading

Sources

App Attest, or how you can trust an app that cannot keep a secret

What App Attest tells your server

How it works

The app side

The server side

Libraries in other languages

The things that trip people up

The nonce is built from exactly what the app passed

Extensions without the extension flag

Two names for the development environment

Development and production do not mix

Keys do not survive reinstalling

Where it runs

The Mac

Turning it on for an app with millions of users

Assertions from several requests at once

Never lock people out because attestation failed

The fraud metric

Further reading

Sources

How an iOS app extension talks to its containing app

Do you need the app?

The mailbox

Notification service extensions

Location push service extensions

Darwin notifications Not to be confused by push notifications

What a notification carries

Use notify.h or Core Foundation?

When the app is suspended

CFMessagePort

Getting the app to run

A background URL session

App Intents, from widgets and controls

Opening the app

A push from your own server

Network Extension and File Provider

Network Extension

File Provider

The shared container

Which mechanism for which job

Sources

What happened to launchOptions

The 14 launch options

The 14 connection options

The launches with no connection option

Core Location has a maritime activity type, as of iOS 27

A SensorKit fetch that returns nothing is usually asking for the wrong window

The recent edge: the 24-hour hold

The far edge: before your app was authorized

Writing a request that can succeed

The default contactless app is woken by every reader

There is probably a logging profile for whatever you are stuck on

Why Core Bluetooth state restoration never fires

Is Bluetooth State Restoration broken?

How restoration works

What your app has to do

1. Declare the background mode

2. Use the same restoration identifier on every launch

3. Create the manager at every launch

4. Implement centralManager(_:willRestoreState:)

When the system relaunches the app

Before you blame restoration

Testing it

If the person force-quits the app

Sources