Core Nfc

by dpearson26998d90fd121a26No license1.1K starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated 2 months ago

Read and write NFC tags using CoreNFC. Use when scanning NDEF tags, reading ISO7816/ISO15693/FeliCa/MIFARE tags, writing NDEF messages, handling NFC session lifecycle, configuring NFC entitlements, or implementing background tag reading in iOS apps.

Instructions onlySoftware Development

AI-generated overview

Guides iOS developers in reading and writing NFC tags with Apple's CoreNFC framework.

What it does: This skill provides reference guidance and code patterns for using CoreNFC on iPhone, covering NDEF reader sessions, tag reader sessions for ISO 7816, ISO 15693, FeliCa and MIFARE tags, NDEF message construction and payload types, entitlements and Info.plist setup, background tag reading, common mistakes, and a review checklist. It produces instructional content and Swift code examples rather than executable output, and points to an extended patterns reference file.
When to use it: Use it when implementing or reviewing NFC tag scanning, reading, or writing in an iOS app, or when configuring NFC capabilities, entitlements, and background tag reading. It also suits troubleshooting session lifecycle and invalidation issues.
Requirements: No scripts; instructions and reference documents only. Working with the described APIs requires Xcode, an iPhone 7 or later for NFC reading, and the Near Field Communication Tag Reading capability with the corresponding entitlement and Info.plist usage description.

CoreNFC

Read and write NFC tags on iPhone using the CoreNFC framework. Covers NDEF reader sessions, tag reader sessions, NDEF message construction, entitlements, and background tag reading.

Setup
NDEF Reader Session
Tag Reader Session
Writing NDEF Messages
NDEF Payload Types
Background Tag Reading
Common Mistakes
Review Checklist
References

Setup

Project Configuration

Add the Near Field Communication Tag Reading capability in Xcode
Add NFCReaderUsageDescription to Info.plist with a user-facing reason string
Add the com.apple.developer.nfc.readersession.formats entitlement with the current TAG value; do not add legacy NDEF
For ISO 7816 tags, add supported application identifiers to com.apple.developer.nfc.readersession.iso7816.select-identifiers in Info.plist
For FeliCa tags, add supported system codes to com.apple.developer.nfc.readersession.felica.systemcodes; do not use wildcard system codes

Device Requirements

NFC reading requires iPhone 7 or later. Always check for reader session availability before creating NFC UI or sessions. Use the concrete reader session type you are about to create.

swift

import CoreNFC
guard NFCNDEFReaderSession.readingAvailable else {    // Device does not support NFC or feature is restricted    showUnsupportedMessage()    return}

import CoreNFC
guard NFCNDEFReaderSession.readingAvailable else {    // Device does not support NFC or feature is restricted    showUnsupportedMessage()    return}

Key Types

Type	Role
`NFCNDEFReaderSession`	Scans for NDEF-formatted tags
`NFCTagReaderSession`	Scans for ISO7816, ISO15693, FeliCa, MIFARE tags
`NFCNDEFMessage`	Collection of NDEF payload records
`NFCNDEFPayload`	Single record within an NDEF message
`NFCNDEFTag`	Protocol for interacting with an NDEF-capable tag

NDEF Reader Session

Use NFCNDEFReaderSession to read NDEF-formatted data from tags. This is the simplest path for reading standard tag content like URLs, text, and MIME data.

swift

import CoreNFC
final class NDEFReader: NSObject, NFCNDEFReaderSessionDelegate {    private var session: NFCNDEFReaderSession?
    func beginScanning() {        guard NFCNDEFReaderSession.readingAvailable else { return }
        session = NFCNDEFReaderSession(            delegate: self,            queue: nil,            invalidateAfterFirstRead: false        )        session?.alertMessage = "Hold your iPhone near an NFC tag."        session?.begin()    }
    // MARK: - NFCNDEFReaderSessionDelegate
    func readerSessionDidBecomeActive(_ session: NFCNDEFReaderSession) {        // Session is scanning    }
    func readerSession(        _ session: NFCNDEFReaderSession,        didDetectNDEFs messages: [NFCNDEFMessage]    ) {        for message in messages {            for record in message.records {                processRecord(record)            }        }    }
    func readerSession(        _ session: NFCNDEFReaderSession,        didInvalidateWithError error: Error    ) {        let nfcError = error as? NFCReaderError        if nfcError?.code != .readerSessionInvalidationErrorFirstNDEFTagRead,           nfcError?.code != .readerSessionInvalidationErrorUserCanceled {            print("Session invalidated: \(error.localizedDescription)")        }        self.session = nil    }}

import CoreNFC
final class NDEFReader: NSObject, NFCNDEFReaderSessionDelegate {    private var session: NFCNDEFReaderSession?
    func beginScanning() {        guard NFCNDEFReaderSession.readingAvailable else { return }
        session = NFCNDEFReaderSession(            delegate: self,            queue: nil,            invalidateAfterFirstRead: false        )        session?.alertMessage = "Hold your iPhone near an NFC tag."        session?.begin()    }
    // MARK: - NFCNDEFReaderSessionDelegate
    func readerSessionDidBecomeActive(_ session: NFCNDEFReaderSession) {        // Session is scanning    }
    func readerSession(        _ session: NFCNDEFReaderSession,        didDetectNDEFs messages: [NFCNDEFMessage]    ) {        for message in messages {            for record in message.records {                processRecord(record)            }        }    }
    func readerSession(        _ session: NFCNDEFReaderSession,        didInvalidateWithError error: Error    ) {        let nfcError = error as? NFCReaderError        if nfcError?.code != .readerSessionInvalidationErrorFirstNDEFTagRead,           nfcError?.code != .readerSessionInvalidationErrorUserCanceled {            print("Session invalidated: \(error.localizedDescription)")        }        self.session = nil    }}

Reading with Tag Connection

For read-write operations, use the tag-detection delegate method to connect to individual tags:

swift

func readerSession(    _ session: NFCNDEFReaderSession,    didDetect tags: [any NFCNDEFTag]) {    guard let tag = tags.first else {        session.restartPolling()        return    }
    session.connect(to: tag) { error in        if let error {            session.invalidate(errorMessage: "Connection failed: \(error)")            return        }
        tag.queryNDEFStatus { status, capacity, error in            guard error == nil else {                session.invalidate(errorMessage: "Query failed.")                return            }
            switch status {            case .notSupported:                session.invalidate(errorMessage: "Tag is not NDEF compliant.")            case .readOnly:                tag.readNDEF { message, error in                    if let message {                        self.processMessage(message)                    }                    session.invalidate()                }            case .readWrite:                tag.readNDEF { message, error in                    if let message {                        self.processMessage(message)                    }                    session.alertMessage = "Tag read successfully."                    session.invalidate()                }            @unknown default:                session.invalidate()            }        }    }}

func readerSession(    _ session: NFCNDEFReaderSession,    didDetect tags: [any NFCNDEFTag]) {    guard let tag = tags.first else {        session.restartPolling()        return    }
    session.connect(to: tag) { error in        if let error {            session.invalidate(errorMessage: "Connection failed: \(error)")            return        }
        tag.queryNDEFStatus { status, capacity, error in            guard error == nil else {                session.invalidate(errorMessage: "Query failed.")                return            }
            switch status {            case .notSupported:                session.invalidate(errorMessage: "Tag is not NDEF compliant.")            case .readOnly:                tag.readNDEF { message, error in                    if let message {                        self.processMessage(message)                    }                    session.invalidate()                }            case .readWrite:                tag.readNDEF { message, error in                    if let message {                        self.processMessage(message)                    }                    session.alertMessage = "Tag read successfully."                    session.invalidate()                }            @unknown default:                session.invalidate()            }        }    }}

Tag Reader Session

Use NFCTagReaderSession when you need direct access to the native tag protocol (ISO 7816, ISO 15693, FeliCa, or MIFARE).

Do not use this session for payment-related AIDs. Load nfc-patterns.md [blocked] for protocol-specific connection, APDU, command, and response handling.

Writing NDEF Messages

Write NDEF data to a connected tag. Always check readWrite status first.

swift

func writeToTag(    tag: any NFCNDEFTag,    session: NFCNDEFReaderSession,    url: URL) {    tag.queryNDEFStatus { status, capacity, error in        guard status == .readWrite else {            session.invalidate(errorMessage: "Tag is read-only.")            return        }
        guard let payload = NFCNDEFPayload.wellKnownTypeURIPayload(            url: url        ) else {            session.invalidate(errorMessage: "Invalid URL.")            return        }
        let message = NFCNDEFMessage(records: [payload])
        tag.writeNDEF(message) { error in            if let error {                session.invalidate(                    errorMessage: "Write failed: \(error.localizedDescription)"                )            } else {                session.alertMessage = "Tag written successfully."                session.invalidate()            }        }    }}

func writeToTag(    tag: any NFCNDEFTag,    session: NFCNDEFReaderSession,    url: URL) {    tag.queryNDEFStatus { status, capacity, error in        guard status == .readWrite else {            session.invalidate(errorMessage: "Tag is read-only.")            return        }
        guard let payload = NFCNDEFPayload.wellKnownTypeURIPayload(            url: url        ) else {            session.invalidate(errorMessage: "Invalid URL.")            return        }
        let message = NFCNDEFMessage(records: [payload])
        tag.writeNDEF(message) { error in            if let error {                session.invalidate(                    errorMessage: "Write failed: \(error.localizedDescription)"                )            } else {                session.alertMessage = "Tag written successfully."                session.invalidate()            }        }    }}

NDEF Payload Types

Creating Common Payloads

swift

// URL payloadlet urlPayload = NFCNDEFPayload.wellKnownTypeURIPayload(    url: URL(string: "https://example.com")!)
// Text payloadlet textPayload = NFCNDEFPayload.wellKnownTypeTextPayload(    string: "Hello NFC",    locale: Locale(identifier: "en"))
// Custom payloadlet customPayload = NFCNDEFPayload(    format: .nfcExternal,    type: "com.example:mytype".data(using: .utf8)!,    identifier: Data(),    payload: "custom-data".data(using: .utf8)!)

// URL payloadlet urlPayload = NFCNDEFPayload.wellKnownTypeURIPayload(    url: URL(string: "https://example.com")!)
// Text payloadlet textPayload = NFCNDEFPayload.wellKnownTypeTextPayload(    string: "Hello NFC",    locale: Locale(identifier: "en"))
// Custom payloadlet customPayload = NFCNDEFPayload(    format: .nfcExternal,    type: "com.example:mytype".data(using: .utf8)!,    identifier: Data(),    payload: "custom-data".data(using: .utf8)!)

Parsing Payload Content

Load Parsing NDEF Payload Content [blocked] for the complete type-name-format switch and multi-record handling.

Background Tag Reading

On iPhone XS and later, iOS can read NFC tags in the background without opening your app. The NDEF message must contain a URI record (typeNameFormat == .nfcWellKnown, type U). If there are multiple URI records, the system uses the first one.

For app-specific routing, write a universal link to the tag and configure the Associated Domains capability for that domain. Background tag reading also supports specific system URL schemes such as web, email, SMS, telephone, FaceTime, Maps, and HomeKit setup. It does not support custom URL schemes, and the system does not route by bundle ID or arbitrary NDEF content type.

When a user taps a compatible tag, iOS displays a notification that opens your app. Handle the tag data via NSUserActivity:

swift

func scene(    _ scene: UIScene,    continue userActivity: NSUserActivity) {    guard userActivity.activityType ==        NSUserActivityTypeBrowsingWeb else { return }
    let message = userActivity.ndefMessagePayload    guard message.records.first?.typeNameFormat != .empty else { return }
    for record in message.records {        processRecord(record)    }}

func scene(    _ scene: UIScene,    continue userActivity: NSUserActivity) {    guard userActivity.activityType ==        NSUserActivityTypeBrowsingWeb else { return }
    let message = userActivity.ndefMessagePayload    guard message.records.first?.typeNameFormat != .empty else { return }
    for record in message.records {        processRecord(record)    }}

Common Mistakes

DON'T: Use stale or missing NFC entitlements

Without the com.apple.developer.nfc.readersession.formats entitlement, reader sessions cannot access NFC hardware. Use the current TAG value for Core NFC reader sessions; do not copy older examples that add NDEF.

DON'T: Ignore session invalidation errors

The session invalidates for multiple reasons. Distinguishing user cancellation from real errors prevents false error alerts.

swift

// WRONG -- shows error when user cancelsfunc readerSession(    _ session: NFCNDEFReaderSession,    didInvalidateWithError error: Error) {    showAlert("NFC Error: \(error.localizedDescription)")}
// CORRECT -- filter expected invalidation reasonsfunc readerSession(    _ session: NFCNDEFReaderSession,    didInvalidateWithError error: Error) {    let nfcError = error as? NFCReaderError    switch nfcError?.code {    case .readerSessionInvalidationErrorUserCanceled,         .readerSessionInvalidationErrorFirstNDEFTagRead:        break  // Normal termination    default:        showAlert("NFC Error: \(error.localizedDescription)")    }    self.session = nil}

// WRONG -- shows error when user cancelsfunc readerSession(    _ session: NFCNDEFReaderSession,    didInvalidateWithError error: Error) {    showAlert("NFC Error: \(error.localizedDescription)")}
// CORRECT -- filter expected invalidation reasonsfunc readerSession(    _ session: NFCNDEFReaderSession,    didInvalidateWithError error: Error) {    let nfcError = error as? NFCReaderError    switch nfcError?.code {    case .readerSessionInvalidationErrorUserCanceled,         .readerSessionInvalidationErrorFirstNDEFTagRead:        break  // Normal termination    default:        showAlert("NFC Error: \(error.localizedDescription)")    }    self.session = nil}

DON'T: Hold a strong reference to a stale session

Once a session is invalidated, it cannot be restarted. Nil out your reference and create a new session for the next scan.

swift

// WRONG -- reusing invalidated sessionfunc scanAgain() {    session?.begin()  // Does nothing, session is dead}
// CORRECT -- create a new sessionfunc scanAgain() {    session = NFCNDEFReaderSession(        delegate: self, queue: nil, invalidateAfterFirstRead: false    )    session?.begin()}

// WRONG -- reusing invalidated sessionfunc scanAgain() {    session?.begin()  // Does nothing, session is dead}
// CORRECT -- create a new sessionfunc scanAgain() {    session = NFCNDEFReaderSession(        delegate: self, queue: nil, invalidateAfterFirstRead: false    )    session?.begin()}

Review Checklist

References

Extended patterns (ISO 7816 commands, multi-tag scanning, NDEF locking): references/nfc-patterns.md [blocked]
Core NFC framework
NFCNDEFReaderSession
NFCTagReaderSession
NFCNDEFMessage
NFCNDEFPayload
NFCNDEFTag
NFCNDEFReaderSessionDelegate
NFCTagReaderSessionDelegate
Building an NFC Tag-Reader App
Adding Support for Background Tag Reading
Near Field Communication Tag Reader Session Formats Entitlement
ISO7816 application identifiers for NFC Tag Reader Session
ISO18092 system codes for NFC Tag Reader Session

Source and attribution

Source:dpearson2699/swift-ios-skillsinskills/core-nfcat commit8d90fd1

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from dpearson2699/swift-ios-skills

Widgetkit

dpearson2699

Guides implementing, reviewing, and improving WidgetKit widgets and controls for iOS, iPadOS, watchOS, and CarPlay.

Software Development1.1Kupdated 2 months ago

Weatherkit

dpearson2699

Guides iOS developers in fetching WeatherKit forecasts, alerts, and attribution using WeatherService.

Software Development1.1Kupdated 2 months ago

Vision Framework

dpearson2699

Implement computer vision features including text recognition (OCR), face detection, barcode scanning, image segmentation, object tracking, and document scanning in iOS apps. Covers both the modern Swift-native Vision API (iOS 18+) and legacy VNRequest patterns, VisionKit DataScannerViewController for live camera scanning, and CoreMLRequest/VNCoreMLRequest for custom model inference. Use when adding OCR, barcode scanning, face detection, or custom Core ML model inference with Vision.

Awaiting classification1.1Kupdated 2 months ago

Tipkit

dpearson2699

Implement and review Apple TipKit feature-discovery UI for iOS 17+ apps. Use when adding or auditing in-app tips, contextual help, coach marks, Tip, TipView, popoverTip, rules, events, actions, display frequency, testing overrides, reusable tip identifiers, or iOS 18+ TipGroup and CloudKit tip sync; avoid for generic SwiftUI navigation or layout outside tip presentation.

Awaiting classification1.1Kupdated 2 months ago

Tabletopkit

dpearson2699

Guides building multiplayer spatial board games on visionOS with Apple's TabletopKit and RealityKit.

Software Development1.1Kupdated 2 months ago

Swiftui Webkit

dpearson2699

Guides embedding and controlling web content in SwiftUI apps with WebKit for SwiftUI on iOS 26 and later.

Software Development1.1Kupdated 2 months ago

Polling option	Tags
`.iso14443`	ISO 7816-compatible and MIFARE
`.iso15693`	ISO 15693
`.iso18092`	FeliCa

Core Nfc

CoreNFC

Contents

Setup

Project Configuration

Device Requirements

Key Types

NDEF Reader Session

Reading with Tag Connection

Tag Reader Session

Writing NDEF Messages

NDEF Payload Types

Creating Common Payloads

Parsing Payload Content

Background Tag Reading

Common Mistakes

DON'T: Use stale or missing NFC entitlements

DON'T: Ignore session invalidation errors

DON'T: Hold a strong reference to a stale session

Review Checklist

References

Source and attribution

More from dpearson2699/swift-ios-skills

Widgetkit

Weatherkit

Vision Framework

Tipkit

Tabletopkit

Swiftui Webkit

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices