Web NFC API Integration

Web NFC API Integration on Website

Web NFC API allows reading and writing NFC tags directly from the browser on Android devices. Applications: inventory (scan tag on equipment — card opens in system), event registration, bracelet info reading in hotels, smart marketing signs.

Support

Chrome for Android 89+. Desktop Chrome, Firefox, Safari — not supported. HTTPS only. User gesture only on first run.

const isSupported = 'NDEFReader' in window

If not supported — fallback to QR codes or manual entry.

Reading NFC Tags

class NFCReader {
  private reader: NDEFReader | null = null
  private isReading = false

  async startReading(
    onRecord: (record: NFCRecord) => void,
    onError?: (error: Error) => void
  ): Promise<void> {
    if (!('NDEFReader' in window)) {
      throw new Error('Web NFC not supported in this browser')
    }

    this.reader = new NDEFReader()
    this.isReading = true

    try {
      await this.reader.scan()
    } catch (err) {
      if ((err as Error).name === 'NotAllowedError') {
        throw new Error('NFC permission not granted')
      }
      throw err
    }

    this.reader.addEventListener('reading', (event: NDEFReadingEvent) => {
      console.log(`NFC UID: ${event.serialNumber}`)

      for (const record of event.message.records) {
        onRecord(record)
      }
    })

    this.reader.addEventListener('readingerror', (event) => {
      onError?.(new Error('NFC read error'))
    })
  }

  stop() {
    this.isReading = false
    this.reader = null
  }
}

Decoding NDEF Records

NFC tag contains NDEF (NFC Data Exchange Format) messages with one or more records:

interface ParsedNFCRecord {
  type: string
  data: string | Record<string, unknown>
}

function parseNFCRecord(record: NDEFRecord): ParsedNFCRecord {
  switch (record.recordType) {
    case 'text': {
      const decoder = new TextDecoder(record.encoding ?? 'utf-8')
      return {
        type: 'text',
        data: decoder.decode(record.data),
      }
    }

    case 'url': {
      const decoder = new TextDecoder()
      return {
        type: 'url',
        data: decoder.decode(record.data),
      }
    }

    case 'mime': {
      if (record.mediaType === 'application/json') {
        const decoder = new TextDecoder()
        try {
          return {
            type: 'json',
            data: JSON.parse(decoder.decode(record.data)),
          }
        } catch {
          return { type: 'text', data: decoder.decode(record.data) }
        }
      }
      return {
        type: record.mediaType ?? 'binary',
        data: '[binary data]',
      }
    }

    case 'smart-poster': {
      return { type: 'smart-poster', data: 'Smart Poster record' }
    }

    default:
      return { type: record.recordType, data: '[unknown]' }
  }
}

Writing to NFC Tag

class NFCWriter {
  async write(data: NFCWriteData): Promise<void> {
    const writer = new NDEFReader()

    const message: NDEFMessageInit = {
      records: this.buildRecords(data),
    }

    await writer.write(message)
    console.log('Written to tag')
  }

  private buildRecords(data: NFCWriteData): NDEFRecordInit[] {
    const records: NDEFRecordInit[] = []

    if (data.url) {
      records.push({ recordType: 'url', data: data.url })
    }

    if (data.text) {
      records.push({
        recordType: 'text',
        data: data.text,
        lang: 'en',
      })
    }

    if (data.json) {
      records.push({
        recordType: 'mime',
        mediaType: 'application/json',
        data: new TextEncoder().encode(JSON.stringify(data.json)),
      })
    }

    return records
  }

  async writeWithPassword(message: NDEFMessageInit, password: string): Promise<void> {
    const writer = new NDEFReader()
    await writer.write(message, {
      overwrite: true,
    })
  }
}

interface NFCWriteData {
  url?: string
  text?: string
  json?: unknown
}

Asset Inventory

Real scenario: each asset tagged with NFC card with JSON, employee scans — card opens:

function AssetInventory() {
  const [scanned, setScanned] = useState<AssetData | null>(null)
  const [isScanning, setIsScanning] = useState(false)
  const readerRef = useRef<NFCReader | null>(null)

  async function startScan() {
    if (!('NDEFReader' in window)) {
      alert('Web NFC unavailable. Use Chrome on Android.')
      return
    }

    setIsScanning(true)
    readerRef.current = new NFCReader()

    await readerRef.current.startReading(
      (record) => {
        const parsed = parseNFCRecord(record)
        if (parsed.type === 'json' && isAssetData(parsed.data)) {
          setScanned(parsed.data as AssetData)
          setIsScanning(false)
          readerRef.current?.stop()
        }
      },
      (error) => {
        console.error('NFC error:', error)
        setIsScanning(false)
      }
    )
  }

  function stopScan() {
    readerRef.current?.stop()
    setIsScanning(false)
  }

  return (
    <div>
      {!('NDEFReader' in window) && (
        <div className="bg-yellow-50 border border-yellow-200 rounded p-3 text-sm">
          Web NFC requires Chrome on Android
        </div>
      )}

      <button
        onClick={isScanning ? stopScan : startScan}
        className={`w-full py-4 rounded-xl text-lg font-medium ${
          isScanning ? 'bg-red-500 text-white' : 'bg-blue-600 text-white'
        }`}
      >
        {isScanning ? '⏹ Stop scanning' : '📡 Scan NFC tag'}
      </button>

      {isScanning && (
        <div className="text-center py-8 text-gray-500">
          Bring tag near the back of phone...
        </div>
      )}

      {scanned && (
        <AssetCard asset={scanned} onClose={() => setScanned(null)} />
      )}
    </div>
  )
}

Writing Tags During Inventory

async function tagAsset(assetId: string, assetData: AssetData) {
  const writer = new NFCWriter()
  await writer.write({
    json: {
      id: assetId,
      name: assetData.name,
      location: assetData.location,
      category: assetData.category,
      lastCheck: new Date().toISOString(),
    },
  })
}

What We Do

Implement NFC tag scanning with NDEF record decoding, JSON data writing to tags, error handling and unsupported fallbacks. Build mobile-friendly UI (large buttons, clear instructions "bring phone to tag"). Test with real NFC tags (NTAG213/215/216 — most common).

Timeline: reading and displaying tag data — 1 day. Full inventory system (read + write + API sync) — 3–4 days.