NFC Module

Properties   Methods   Events   Config Settings   Errors  

The NFC component is used to read and write to NFC tags.

Syntax

IPWorksNFC.NFC

Remarks

The NFC class supports tag management according to the specifications outlined in RFC 9428, in addition to RFC 4729, which defines a URN Namespace for the NFC Forum.

Project Setup

First, add the IPWorksNFC framework to your Xcode project. Before the class can run successfully, the Entitlements and Info.plist files must be configured appropriately. These files can be changed directly or via Xcode; see the demo project for reference.

To ensure the correct entitlement is applied to the project, in Xcode, first select the project and the appropriate target in the project view. After navigating to 'Signing & Capabilities', you must add the 'Near Field Communication Tag Reading' capability. Alternatively, you can add the following key to the Entitlements file. For example, the file contents may look like:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>com.apple.developer.nfc.readersession.formats</key> <array> <string>TAG</string> </array> </dict> </plist>

Next, ensure that the Info.plist file includes the NFCReaderUsageDescription key. For example, the file contents may look like:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>NFCReaderUsageDescription</key> <string>This app needs NFC access to read contactless NFC tags</string> </dict> </plist>

You will also need to ensure the Info.plist file is referenced and is present in the 'Build Settings', under 'Packaging'.

Initialization

To use the NFC class, you must first import the IPWorks NFC module as needed: import IPWorksNFC Afterwards, you must create an instance of the class and assign a delegate that conforms to NFCDelegate. The delegate receives all NFC events, including when a tag is detected, when records are read, and when logs or errors occur. A common approach is to wrap the NFC class in a manager class that implements NFCDelegate. This keeps the NFC logic separate from the UI and allows you to reference the manager in your main view: class NFCManager: ObservableObject, NFCDelegate { private var nfc: NFC? init() { do { nfc = try NFC() nfc?.delegate = self // other settings } catch { print("Error initializing NFC: \\(error)") } } // Delegated events func onError(errorCode: Int32, description: String) { } func onLog(logLevel: Int32, message: String, logType: String) { } func onRecord(id: Data, payload: Data, recordType: Data, recordTypeFormat: Int32) { } func onTag(forumType: Int32, maxSize: Int32, serialNumber: String, size: Int32, writable: Bool) { } } struct ContentView: View { @StateObject private var nfcManager = NFCManager() var body: some View { // UI code here } } Alternatively, you can have your SwiftUI view itself conform to NFCDelegate: struct ContentView: View, NFCDelegate { private var nfc: NFC? // Delegated events func onError(errorCode: Int32, description: String) { } func onLog(logLevel: Int32, message: String, logType: String) { } func onRecord(id: Data, payload: Data, recordType: Data, recordTypeFormat: Int32) { } func onTag(forumType: Int32, maxSize: Int32, serialNumber: String, size: Int32, writable: Bool) { } init() { do { nfc = try NFC() nfc?.delegate = self // other settings } catch { print("Error initializing NFC: \\(error)") } } var body: some View { // UI code here } }

Reading a Tag

To read the data from a tag, call the Read method and place the tag close to the device. Please note that the Read method is blocking, and should not be called from the UI (to prevent any freezing behavior). For example:

DispatchQueue.global().async { do { try nfc!.read() } catch let e { print("\(e)") } }

After the tag is detected, the component will attempt to parse the tag information and any stored records. As soon as the component has read all of the tag information, the Tag event will fire, containing relevant details about the tag, such as the tag's type and serial number, current and maximum size (i.e., the amount of data the tag is currently storing or can store), and whether the tag can be written to. For example, in the Tag event:

func onTag(forumType: Int32, maxSize: Int32, serialNumber: String, size: Int32, writable: Bool) { print("Tag Detected. Details:") print("Tag Type: \\(forumType)") print("Serial Number: \\(serialNumber)") print("Size: \\(size) / \\(maxSize) Bytes") print("Writable: \\(writable)") }

After the Tag event fires, the Record event will fire for each record that is detected. The Record event will contain relevant details about the record, such as the record TNF (type name format, or record type format), the actual record type (which is interpreted based on the TNF), the payload (actual record content), and the optional record ID (which is typically empty). For example, in the Record event:

func onRecord(id: Data, payload: Data, recordType: Data, recordTypeFormat: Int32) { print("Record Detected.") print("TNF: \\(recordTypeFormat)") // E.g., 0 -> 0x00 (Empty), 1 -> 0x01 (Well-known) print("Record Type: \\(recordType)") // E.g., if TNF is 0x01 (Empty), this could be "T" (text record) print("Record Payload: \\(payload)") }

Note that, in addition to the tag and record details being made available via their corresponding events, the Tag property and Records collection will be populated after the Read method returns successfully. Tag and record details can also be accessed like so:

// Printing tag info private func printTagInfo() { guard let tag = nfc?.tag else { return } print("Tag Type: \\(tag.forumType)") print("Serial Number: \\(tag.serialNumber)") print("Size: \\(tag.size) / \\(tag.maxSize) Bytes") print("Writable: \\(tag.writable)") } // Printing record info private func printRecordInfo() { var recordNum = 1 for record in nfc!.records { print("Record \\(recordNum) Info") print("TNF: \\(record.recordTypeFormat)") print("Record Type: \\(record.recordType)") print("Record Payload: \\(record.Payload)") print("") recordNum += 1 } }

Parsing Records

As mentioned, the Record event provides the raw components of each NDEF record detected on a tag. An NDEF (NFC Data Exchange Format) record is the standard way NFC tags encode and store data. Each record contains four key parts exposed by the Record event.

Typically, the RecordTypeFormat parameter will be checked first. This parameter represents the TNF (Type Name Format) associated with the record. Possible values for this parameter are:

After checking the value of the RecordTypeFormat parameter, the RecordType parameter can then be interpreted. As an example, if the TNF of a record is 0x01 (Well-Known), the RecordType is usually a single character that identifies the type of record. This value would be "T" to indicate a text record, or "U" to indicate a URI/URL record.

In either case, the mentioned parameters can be used to then determine how to interpret the Payload parameter, which is ultimately left up to the developer. For example, given a RecordTypeFormat of 0x01 and a RecordType of "T" (Well-Known Text Record), the following code (when iterating through the collection of records) can be used to extract the relevant data out of the Payload:

if record.recordTypeFormat == RecordTypeFormats.rtfWellKnown && record.recordType == "T" { // Handle Text Record let payload = record.payloadB let status = payload[0] let isUtf16 = (status & 0x80) != 0 let langCodeLen = Int(status & 0x3F) let encoding: String.Encoding = isUtf16 ? .utf16 : .utf8 let languageCodeRange = 1..<1+langCodeLen let languageCodeData = payload.subdata(in: languageCodeRange) let languageCode = String(data: languageCodeData, encoding: .ascii) ?? "" let textRange = (1 + langCodeLen)..<payload.count let textData = payload.subdata(in: textRange) let text = String(data: textData, encoding: encoding) ?? "" print("Text Record (LangCode = \\(languageCode)) - \\(text)") }

The format of a text record is defined and standardized, so the payload can be parsed in a predictable way (status byte, language code, then the actual text). Other record types follow similar conventions. For example:

• For a URI record (TNF = 0x01, RecordType = "U"), the first byte of the payload is the URI prefix code (e.g., 0x01 for "http://www.), followed by the rest of the URI string in UTF-8.
• For a MIME Media record (TNF = 0x02), the record type is a MIME type (e.g., "text/plain"), and the payload contains raw data of that type.

In practice, this means that the RecordTypeFormat (TNF) tells you how to interpret the RecordType, which in turn tells you how to parse the Payload. By combining these, you can effectively parse any NDEF record type.

Writing to a Tag

To write records to a tag, the Records collection should first be populated with any records that are to be written to the tag. To do so, the API exposes three methods:

• AddTextRecord
• AddURLRecord
• AddRecord

The AddTextRecord method can be used to add a well-formed text record to the Records collection. This is typically used to encode human-readable text. This method takes two parameters: the actual text to store on the tag, and the language code that specifies the language of the text (for example, "en" for English).

The AddURLRecord method can be used to add a URI or URL record to the Records collection. This method takes a single parameter, which is the URL string to store on the tag.

For all other types of records, including custom or MIME-based records, the AddRecord method may be used. This method requires specifying the TNF (Type Name Format), the record type, an optional record ID, and the record payload.

As there are many possible types of records, this method is intended to give developers full control over record creation. While AddTextRecord and AddURLRecord cover some common scenarios, AddRecord allows developers to handle any custom, proprietary, or less common NDEF records without introducing additional specialized methods. As an example, you could create a MIME Media record like containing JSON like so:

do { let tnf: Int32 = 0x02 let recordType = "application/json".data(using: .ascii)! let id = Data() // empty // Prepare JSON let jsonObject: [String: Any] = [ "name": "NFC Example", "version": "1.0", "data": "some_json_data" ] let payload = try JSONSerialization.data(withJSONObject: jsonObject, options: []) try nfc?.addRecord(tnf: tnf, type: recordType, payload: payload, id: id) } catch { print("Failed to add JSON MIME record: \(error)") }

Once the desired records are added to the Records collection, the Write method should be called to write the records to the tag. If multiple records are added, they will be written together as a single NDEF message. Please note that the Write method is blocking. To prevent the UI from freezing, the method should be called like so:

DispatchQueue.global().async { do { try nfc!.write() } catch let e { print("\(e)") } }

Note that if you previously read a tag, the Records collection will likely be populated. Unless you are preserving the existing records from the prior read operation, you can clear the records from the collection like so:

nfc!.records.removeAll() After clearing the records, you can add new records to write using the methods described previously.

Property List

---

The following is the full list of the properties of the module with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the module with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the module with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the module with short descriptions. Click on the links for further details.

Available Property (NFC Module)

Indicates whether NFC is currently enabled and supported on the current device.

Syntax

public var available: Bool
 {
  get {...}
}

Default Value

False

Remarks

This property indicates whether NFC is currently enabled and supported on the current device.

If false, the class will not be able to perform any read or write operations. This property may be checked before attempting to call Read or Write. Note that availability is also checked during the calls to Read and Write, and the methods will return an error if NFC is not supported on the current device.

This property is read-only.

Records Property (NFC Module)

A collection of NDEF records.

Syntax

public var records: Array<NDEFRecord>
 {
  get {...}
}

Remarks

This property holds a collection of NDEF records.

In the case of a Read operation, this property will hold a collection of NDEF records that were read on the tag (assuming Read returned successfully). Note that record information is also made available via the Record event. For example, to iterate through all detected records:

// Reading records after a successful read for record in nfc!.records { // Process records }

In the case of a Write operation, this property will hold records to be written to a tag. To add a record to this collection, AddTextRecord, AddURLRecord, and AddRecord can be called. Once populated, Write can be called to write all records in this collection to a tag. For example:

// Adding records for writing nfc?.addTextRecord(text: "Hello, World!", languageCode: "en") nfc?.addURLRecord(url: "mailto:info@nsoftware.com") if nfc?.records.count > 0 { // Dispatch write }

Note that if you previously read a tag, this collection will likely be populated. Unless you are preserving records from the prior read operation, you can clear the records from the collection before a write like so:

nfc!.records.removeAll()

Tag Property (NFC Module)

Information about the last nfctag detected with a Read operation.

Syntax

public var tag: NFCTag
 {
  get {...}
}

Remarks

This property holds information about the last NFCTag detected with a Read operation. See NFCTag for the available fields.

For example, after reading a tag, you can access it's properties like so:

private func printTagInfo() { guard let tag = nfc?.tag else { return } print("Tag Type: \\(tag.forumType)") print("Serial Number: \\(tag.serialNumber)") print("Size: \\(tag.size) / \\(tag.maxSize) Bytes") print("Writable: \\(tag.writable)") }

This property is read-only.

Timeout Property (NFC Module)

Timeout in seconds to wait for a tag during Read and Write operations.

Syntax

public var timeout: Int32
 {
  get {...}
  set {...}
}

Default Value

30

Remarks

Applies to blocking operations; after the timeout elapses, the call returns without a tag.

Abort Method (NFC Module)

Cancels an ongoing Read or Write operation that is waiting for a tag.

Syntax

public func abort() throws -> Void

Remarks

This method cancels an ongoing Read or Write operation that is waiting for a tag. It may be invoked from any context (such as a background thread on Android or a background dispatch queue on iOS) to interrupt a pending operation.

Example:

// Dispatch read on a background queue DispatchQueue.global().async { do { try nfc!.read() // waits for tag } catch let e { print("Read error or aborted: \(e)") } } // Cancel from UI action (e.g., a button) cancelButton.addTarget(self, action: #selector(cancelRead), for: .touchUpInside) @objc func cancelRead() { nfc?.abort() }

AddRecord Method (NFC Module)

Adds a custom NDEFRecord to the Records collection.

Syntax

public func addRecord(recordTypeFormat: Int32, recordType: Data, payload: Data, id: Data) throws -> Void

Remarks

This method adds a custom NDEFRecord to the Records collection with the specified parameters.

The RecordTypeFormat is used to specify the format of the record (this is also known as the Type Name Format, or TNF). Possible values for this parameter are:

The RecordType parameter, normally assigned based on the RecordTypeFormat being specified, defines the type of the record. For example, if the RecordTypeFormat is set to MIME media (0x02), the RecordType might be "text/plain" or "application/json".

The Payload parameter contains the actual data of the record. This may be text, binary data, or any other content defined by the record type. For instance, for a text record this would contain the text string, while for a URI record it would contain the URI bytes.

The Id parameter is an optional identifier for the record. It may be specified to uniquely identify a record within an NDEF message, or left empty if not needed.

For common cases use AddTextRecord or AddURLRecord. Otherwise, use this method to add a custom record, for example:

do { let recordTypeFormat: Int32 = 0x02 let recordType = "application/json".data(using: .ascii)! let id = Data() // empty // Prepare JSON let jsonObject: [String: Any] = [ "name": "NFC Example", "version": "1.0", "data": "some_json_data" ] let payload = try JSONSerialization.data(withJSONObject: jsonObject, options: []) try nfc?.addRecord(recordTypeFormat: recordTypeFormat, recordType: recordType, payload: payload, id: id) } catch { print("Failed to add JSON MIME record: \(error)") }

AddTextRecord Method (NFC Module)

Adds an NDEF Text record to the Records collection.

Syntax

public func addTextRecord(text: String, languageCode: String) throws -> Void

Remarks

This method adds an NDEF Text record to the Records collection with the specified parameters.

The Text parameter specifies the actual text content of the record.

The LanguageCode parameter specifies the language of the text, using a standard IANA language code (for example, "en" for English or "fr" for French).

Note that at least one record must be added before calling Write.

Example:

nfc?.addTextRecord(text: "Hello, World!", languageCode: "en") nfc?.addTextRecord(text: "Visitez notre site web pour plus d'informations", languageCode: "fr")

AddURLRecord Method (NFC Module)

Adds an NDEF URI/URL record to the Records collection.

Syntax

public func addURLRecord(url: String) throws -> Void

Remarks

This method adds an NDEF URI record to the Records collection with the specified parameter.

The URL parameter specifies the URI/URL to store in the record. The URL should conform to a valid URI scheme, for example "https://", "mailto:", etc.

Note that at least one record must be added before calling Write.

Example:

nfc?.addURLRecord(url: "https://www.nsoftware.com") nfc?.addURLRecord(url: "mailto:info@nsoftware.com")

Config Method (NFC Module)

Sets or retrieves a configuration setting.

Syntax

public func config(configurationString: String) throws -> String

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Read Method (NFC Module)

Reads a presented NFC tag.

Syntax

public func read() throws -> Void

Remarks

This method attempts to read a presented NFC tag and blocks until either a tag is detected or the operation times out.

The Timeout property specifies the maximum time, in seconds, to wait for a tag before returning. If no tag is detected within the specified timeout, the method will return without reading.

The method may throw an exception if the operation is cancelled (for example, by calling Abort) or if another error occurs.

After a tag is successfully detected, the Tag and Record events will fire, containing details about the tag and records present on the tag, respectively. Additionally, the Tag property and Records collection will be populated with this same information. Please refer to the relevent event and property descriptions for additional details.

Example:

// Dispatch read on a background queue DispatchQueue.global().async { do { try nfc?.read() // waits for tag or timeout } catch let e { print("Read error or aborted: \(e)") } }

Reset Method (NFC Module)

Resets the component to its initial state by clearing records and tag information.

Syntax

public func reset() throws -> Void

Remarks

Does not affect the Activity reference or foreground dispatch. Use Abort if there is a need to interrupt an ongoing Read or Write operation.

Example:

// After completing an operation nfc.Write(); // Write some records nfc.Reset(); // Clear everything for next operation nfc.AddTextRecord("New message"); nfc.Write(); // Write new records

Write Method (NFC Module)

Writes the record(s) in the Records collection to a detected NFC tag.

Syntax

public func write() throws -> Void

Remarks

This method will attempt to write the record(s) in the Records collection to a detected NFC tag.

The Timeout property specifies the maximum time, in seconds, to wait for a tag before returning. If no tag is detected within the specified timeout, the method will return without writing.

The method may throw an exception if the operation is cancelled (for example, by calling Abort) or if another error occurs.

Before calling this method, at least one record must be added to Records (for example, using AddTextRecord, AddURLRecord, or AddRecord). After a successful write, the tag will contain the records from the Records collection.

Example:

// Dispatch write on a background queue DispatchQueue.global().async { do { // Add one or more records nfc?.addTextRecord(text: "Hello, World!", languageCode: "en") try nfc?.write() // waits for tag and writes } catch let e { print("Write error or aborted: \(e)") } }

Error Event (NFC Module)

Fired when information is available about errors during data delivery.

Syntax

func onError(errorCode: Int32, description: String)

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class .

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Log Event (NFC Module)

Fired once for each log message.

Syntax

func onLog(logLevel: Int32, message: String, logType: String)

Remarks

This event is fired once for each log message generated by the class. The verbosity is controlled by the LogLevel setting.

LogLevel indicates the level of message. Possible values are as follows:

The value 1 (Info) logs basic information, including the URL, HTTP version, and status details.

The value 2 (Verbose) logs additional information about the request and response.

The value 3 (Debug) logs the headers and body for both the request and response, as well as additional debug information (if any).

Message is the log entry.

LogType identifies the type of log entry. Possible values are as follows:

• "Info"
• "RequestHeaders"
• "ResponseHeaders"
• "RequestBody"
• "ResponseBody"
• "ProxyRequest"
• "ProxyResponse"
• "FirewallRequest"
• "FirewallResponse"

Record Event (NFC Module)

Fires once for each NDEF Record discovered during a Read operation.

Syntax

func onRecord(id: Data, payload: Data, recordType: Data, recordTypeFormat: Int32)

Remarks

This event is triggered for each NDEF record detected on the tag. The event provides access to the following parameters:

The Id parameter is the identifier of the record, if one was specified when the record was created. This may be used to uniquely distinguish records within an NDEF message. This parameter is typically empty, as it is optional.

The Payload parameter contains the actual data stored in the record. This may be text, binary data, or any other content, depending on the record type.

The RecordType parameter specifies the type of the record, usually based on the RecordTypeFormat. For example, with a MIME media format (0x02), the RecordType might be "text/plain" or "application/json".

The RecordTypeFormat parameter specifies the Type Name Format (TNF) of the record. Possible values for this parameter are:

This event will fire once for each record present on the tag. For example, if a tag contains multiple text or URI records, the event will be raised separately for each record. In addition to this event, the record data will be present in the Records collection after the Read operation is successful.

Example:

func onRecord(id: Data, payload: Data, recordType: Data, recordTypeFormat: Int32) { print("Record Detected.") print("TNF: \\(recordTypeFormat)") // E.g., 0 -> 0x00 (Empty), 1 -> 0x01 (Well-known) print("Record Type: \\(recordType)") // E.g., if TNF is 0x01 (Empty), this could be "T" (text record) print("Record Payload: \\(payload)") }

Tag Event (NFC Module)

Fires once when a tag is discovered during a Read operation.

Syntax

func onTag(forumType: Int32, maxSize: Int32, serialNumber: String, size: Int32, writable: Bool)

Remarks

This event is triggered when a tag is successfully detected. The event provides access to the following parameters:

The ForumType parameter specifies the type of the tag according to the NFC Forum specification.

The MaxSize parameter indicates the maximum storage size of the tag, in bytes.

The SerialNumber parameter contains the unique serial number of the tag as a string. This may be empty or unavailable on some tags.

The Size parameter specifies the current amount of used storage on the tag, in bytes.

The Writable parameter indicates whether the tag is currently writable (true) or read-only (false).

In addition to this event, the tag information will be available in the Tag property after a successful Read operation.

Example:

func onTag(forumType: Int32, maxSize: Int32, serialNumber: String, size: Int32, writable: Bool) { print("Tag Detected. Details:") print("Tag Type: \\(forumType)") print("Serial Number: \\(serialNumber)") print("Size: \\(size) / \\(maxSize) Bytes") print("Writable: \\(writable)") }

NDEFRecord Type

The NDEFRecord type represents a single NDEF Record.

Remarks

Each record consists of a type identifier, payload data, optional ID, and format information.

• Id
• Payload
• RecordType
• RecordTypeFormat

Fields

NFCTag Type

This type an represents an NFCTag with its properties and capabilities.

Remarks

• ForumType
• MaxSize
• SerialNumber
• Size
• Writable

Fields

Config Settings (NFC Module)

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

NFC Config Settings

Base Config Settings

Trappable Errors (NFC Module)