[dangfan]

iOS poll() always waits for queryNDEFStatus before returning, including for apps that only exchange raw commands. In an instrumented downstream build with a CanoKey Canary, this query added about 220 ms after detection; skipping it reduced the same settings read from about 1.28 s to 1.06 s. These are small-sample latency measurements, not success-rate measurements.

Add a shared checkNDEF option (default true) to control automatic NDEF discovery on both Android and iOS:

final tag = await FlutterNfcKit.poll(checkNDEF: false);

On Android, this sets the existing FLAG_READER_SKIP_NDEF_CHECK; platform NDEF methods are unavailable for that session. On iOS, it skips queryNDEFStatus and leaves NDEF capability metadata at its defaults, while preserving raw commands and FeliCa PMm collection. Explicit iOS NDEF methods still contact the tag. Web ignores the option.

Retain androidCheckNDEF with @Deprecated for source compatibility. When explicitly supplied, it overrides checkNDEF on Android only; legacy Android-only calls keep their previous behavior. New callers need only checkNDEF. Document these semantics and precedence in the README and API docs.

Also fix reader lifecycle gaps exposed during repeated scans: invalidation currently skips cleanup once a successful poll has consumed its result, and failed connections leave the reader active. Clean up both cases, serialize discovery/setup state on main, and guard delayed discovery, connection, NDEF and FeliCa callbacks against replaced sessions. This retains the stale-invalidation protection introduced in #235.

Validation:

• flutter test: 5 tests covering defaults, shared opt-out, legacy Android-only behavior, override precedence in both directions, and raw commands after polling. Added tests to the existing stable/beta CI workflow.
• dart analyze, Dart format checks and git diff --check: passed.
• cd example && flutter build ios --debug --no-codesign: passed.
• The latency measurements and scan/recovery trials used the instrumented downstream prototype. This upstream extraction has been compiled, but has not had a separate on-device test; Android validation here covers channel flags, not physical NFC hardware.

Summary by CodeRabbit

• New Features
  • Added the checkNDEF option to control automatic NDEF discovery on Android and iOS. It defaults to enabled; when disabled, polling skips the initial NDEF check while raw transceive remains available. The deprecated androidCheckNDEF option remains as an Android-only override.
• Bug Fixes
  • Improved iOS NFC session cleanup and handling of invalidated sessions, failed connections, and delayed callbacks.
• Documentation
  • Clarified NDEF discovery behavior and its effects on metadata and NFC operations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 606e6586-8383-43eb-88e7-529bf874e432

📥 Commits

Reviewing files that changed from the base of the PR and between dbfc9f7 and c0b51a6.

📒 Files selected for processing: 5

• CHANGELOG.md
• README.md
• ios/flutter_nfc_kit/Sources/flutter_nfc_kit/FlutterNfcKitPlugin.swift
• lib/flutter_nfc_kit.dart
• test/poll_test.dart

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 0 remain after this review.

📝 Walkthrough

The poll API adds checkNDEF, enabled by default, and keeps androidCheckNDEF as a deprecated Android-only override. The iOS plugin applies the option during tag polling and updates reader-session lifecycle and callback handling. Documentation and tests cover the API and polling behavior.

Changes: NDEF Polling

Layer / File(s)	Summary
Expose and validate the NDEF-discovery option lib/flutter_nfc_kit.dart, README.md, test/poll_test.dart, .github/workflows/test.yml, CHANGELOG.md	poll accepts and forwards checkNDEF, which defaults to true. The nullable deprecated androidCheckNDEF overrides it on Android. Documentation describes platform behavior, tests cover option precedence and polling calls, and the workflow runs flutter test.
Manage iOS reader-session lifecycle ios/flutter_nfc_kit/Sources/flutter_nfc_kit/FlutterNfcKitPlugin.swift	The plugin creates reader sessions on the main queue. It clears pending results and reader state during finish, invalidation, and poll failure, and checks session identity before processing callbacks or retrying tag detection.
Handle iOS tag polling results ios/flutter_nfc_kit/Sources/flutter_nfc_kit/FlutterNfcKitPlugin.swift	The plugin conditionally queries NDEF status, preserves FeliCa manufacturer metadata retrieval when NDEF discovery is skipped, and returns poll metadata or errors through guarded completion paths.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant FlutterNfcKit
  participant iOSPlugin
  participant ReaderSession
  participant NFCTag
  FlutterNfcKit->>iOSPlugin: poll with checkNDEF
  iOSPlugin->>ReaderSession: create and begin session
  ReaderSession->>iOSPlugin: detect tag and complete connection
  iOSPlugin->>NFCTag: query NDEF status when enabled and supported
  NFCTag->>iOSPlugin: return NDEF metadata
  iOSPlugin->>NFCTag: retrieve FeliCa manufacturer metadata
  NFCTag->>iOSPlugin: return FeliCa metadata
  iOSPlugin->>FlutterNfcKit: deliver poll result or error

Loading

Merge Risk: ⚪ Minimal · up to c0b51

The option’s documented iOS NDEF behavior remains supported by the inspected code. No identified issue prevents merging after normal checks.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 57.14% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 1 files. (4 skipped: 4…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly summarizes the two main changes: unified NDEF discovery control and iOS session cleanup fixes.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 57.14% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 1 files. (4 skipped: 4 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

• Fix all pre-merge checks with AI

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}