Android NFC框架业务与兼容 下篇

9 阅读13分钟

1. 先画三张业务地图

所有 NFC 业务,本质只有三种形态:

① 读卡(Reader / Polling)
   手机 = 读头,外部 = 标签/卡片
   典型:巡检打卡、资产盘点、防伪溯源、耗材识别、标签量产写号

② 卡模拟(Card Emulation / Listening)
   手机 = 卡片,外部 = 读头/闸机/POS
   典型:门禁、会员卡、园区一卡通、票务、车钥匙

③ 双向(P2P / 读写器互通)
   手机 ↔ 手机 / 手机 ↔ 设备
   典型:配网传参、产线写号(⚠️ Beam 已在 Android 14 移除)

再叠加一个维度:频段。

业务诉求频段Android 原生能否覆盖方案
工牌/门禁/公交13.56MHz✅原生 NFC
仓储托盘/服装吊牌UHF 900MHz❌外接 UHF 模块(串口/BLE)
老小区门禁、动物耳标LF 125kHz❌外接 LF 读头 / 引导换卡
远距离资产盘点(>10cm)HF 15693⚠️ 部分机型优先 NfcV,做好降级

这一格表是需求评审阶段就该拍死的东西。等到开发完发现"客户要读 UHF 标签",返工成本极高。


2. 逐模块业务构想 × 坑

2.1 API 层:把"能力探测"做成基础设施

业务构想:做一个 NfcCapability,在任何业务开始前先探明"这台机器到底能干什么",输出一张能力矩阵,驱动后续 UI 与降级策略。

data class NfcCapability(
    val hasNfc: Boolean,          // 硬件是否存在
    val enabled: Boolean,         // 用户是否打开
    val hceSupported: Boolean,    // 是否支持卡模拟
    val secureNfc: Boolean,       // 是否支持 Secure NFC(防中继)
    val techs: Set<String>        // 探测到的可用技术
)

探测的坑:android.nfc 没有 getSupportedTechList() 这种 API。唯一可靠的办法是用一张已知的测试卡实际读一次,记录 tag.techList。所以工程上要区分"静态能力"(HCE 是否声明、Secure NFC 是否支持)和"动态能力"(实测技术位)。

另一个坑:API 层现在会随 APEX 更新(Android 16 起 framework-nfc.jar 独立下发)。不要用 SDK_INT 推断 NFC 行为,用 PackageManager.hasSystemFeature(PackageManager.FEATURE_NFC_HOST_CARD_EMULATION) 这类特性开关。

2.2 服务层:把状态机当成业务状态来用

业务构想:NFC 开关是异步的,把"开卡引导"做成一个可恢复的流程。

// 推荐:监听状态广播,而不是假设 enable() 成功
val filter = IntentFilter(NfcAdapter.ACTION_ADAPTER_STATE_CHANGED)
val receiver = object : BroadcastReceiver() {
    override fun onReceive(ctx: Context, intent: Intent) {
        when (intent.getIntExtra(NfcAdapter.EXTRA_ADAPTER_STATE, -1)) {
            NfcAdapter.STATE_ON -> startReading()
            NfcAdapter.STATE_TURNING_ON -> showLoading()
            NfcAdapter.STATE_OFF -> showGuide()
        }
    }
}

坑:ACTION_ADAPTER_STATE_CHANGED 在部分 ROM 上会被节流或延迟;STATE_TURNING_ON 可能停留很久(固件初始化慢)。工程上要给超时兜底(比如 5 秒后仍然 TURNING_ON 就提示"设备 NFC 异常,请重启")。

业务上可以做的一件聪明事:把 applyRouting 的语义映射成业务语言——"屏幕亮且应用在前台"时打开轮询+"屏幕灭"时只保留卡模拟路由。这是省电与体验的最佳平衡点,也解释了为什么"灭屏刷不了门禁"通常是配置问题而不是硬件问题。

2.3 派发层:治理"应用劫持"与"选择器弹窗"

业务构想:多应用抢同一张卡,是政企项目最常见的问题(比如钉钉、企业微信、自家 App 都想处理工牌)。

治理手段按优先级:

  1. 优先用 enableReaderMode / enableForegroundDispatch:前台应用直接拿走,不参与系统级竞争;
  2. AAR(Android Application Record):在标签里写入自己的包名,保证只有自己能拉起;
  3. ACTION_TECH_DISCOVERED + 精确 tech-list:缩小匹配面,减少选择器;
  4. 避免 ACTION_TAG_DISCOVERED:它是兜底 Action,谁都能注册,已在 Android 17(API 37)废弃,新项目一律不要用。
<!-- tech-list 要精确到你真正需要的最小集合 -->
<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
    <tech-list>
        <tech>android.nfc.tech.NfcA</tech>
        <tech>android.nfc.tech.IsoDep</tech>
    </tech-list>
</resources>

坑:tech-list 的语义是"同时具备",不是"任一具备"。写多了匹配不上,写少了被别人抢。

2.4 技术对象层:标签量产写号与资产盘点

业务构想 A:产线批量写号 一张标签写"型号 + 批次 + 序列号 + HMAC 签名",产线工人连续贴卡,要求 300ms 内出结果。

业务构想 B:资产盘点 用 NfcV(15693)做远距离盘点,一次性走完整货架。

关键代码:带重试的安全写入

fun writeNdef(tag: Tag, message: NdefMessage, retries: Int = 3): Boolean {
    repeat(retries) { attempt ->
        var ndef: Ndef? = null
        try {
            ndef = Ndef.get(tag) ?: return false
            ndef.connect()                       // 注意:必须先 connect
            if (!ndef.isWritable) return false
            if (message.toByteArray().size > ndef.maxSize) return false
            ndef.writeNdefMessage(message)
            return true
        } catch (e: TagLostException) {
            // RF 场被重配或卡移开,退避后重试
            Thread.sleep(50L * (attempt + 1))
        } catch (e: IOException) {
            return false
        } finally {
            runCatching { ndef?.close() }
        }
    }
    return false
}

坑清单:

坑现象处理
maxSize 是"当前可用",不是"总容量"写入超限抛 IOException写前校验,留 8 字节余量
写一半移开卡标签变成"半损坏",既非 NDEF 也非可格式化用 NdefFormatable 兜底格式化
MifareClassic 扇区密钥认证返回 false该机型可能只支持透传,不支持认证,需厂商确认
缓存了 Tag 对象第二次操作必失败每次回调都重新 getTag()

一个省钱的设计:把"写号"和"验签"拆开。写号只写明文 + 签名,验签在服务端做。这样即使标签被复制,没有后端签名校验也无法伪造业务。

2.5 HCE 模块:门禁/会员/票务的正确姿势

业务构想:把"手机当工牌",AID 与后端约定,APDU 只做三件事——SELECT、读卡号、读签名。

class MyApduService : HostApduService() {

    override fun processCommandApdu(apdu: ByteArray, extras: Bundle?): ByteArray {
        // 1) SELECT AID: 00 A4 04 00 Lc AID
        if (apdu.size >= 4 && apdu[1] == 0xA4.toByte() && apdu[2] == 0x04.toByte()) {
            return SELECT_OK_SW          // 90 00
        }
        // 2) 读卡号: 约定私有指令 80 CA 00 00
        if (apdu.size >= 4 && apdu[1] == 0xCA.toByte()) {
            return buildCardNo() + SELECT_OK_SW
        }
        return UNKNOWN_CMD_SW            // 6D 00
    }

    override fun onDeactivated(reason: Int) {
        // reason: LINK_LOST / DESELECTED —— 用来清理会话状态
    }

    companion object {
        private val SELECT_OK_SW = byteArrayOf(0x90.toByte(), 0x00)
        private val UNKNOWN_CMD_SW = byteArrayOf(0x6D, 0x00)
    }
}

必须知道的四条约束:

  1. 响应有超时(通常几百毫秒)。processCommandApdu 里绝对不能做网络/数据库请求,只能读内存。需要联机就把数据提前缓存好。
  2. APDU 有长度上限。超长响应要做分片,靠 00 C0 00 00 Le(GET RESPONSE)续传,状态字用 61 XX 告诉读卡器还有多少字节。
  3. onDeactivated 一定会来,但不保证顺序;不要在这里做重活。
  4. AID 冲突静默失败。两个 App 注册同一 AID,落选者完全收不到回调,日志里也没有明显报错。排查时先 adb shell dumpsys nfc 看路由表。

调试命令(非常有用,建议收藏):

# 查看当前 NFC 状态、AID 路由、HCE 服务
adb shell dumpsys nfc

# 看 NFC 相关日志
adb logcat -s NfcService:N NfcDispatcher:N HostEmulationManager:N NativeNfcManager:N nfc_ncif:N

2.6 底层/外设模块:把 LF/UHF 抽象成统一接口

业务构想:客户既要刷手机(13.56MHz),又要盘 UHF 托盘。最干净的做法不是"两个 App",而是统一标签抽象:

interface TagSource {
    val name: String
    fun start(onTag: (RawTag) -> Unit)
    fun stop()
}

data class RawTag(
    val id: String,            // 统一后的标识
    val band: Band,            // HF_13M56 / UHF_900M / LF_125K
    val payload: ByteArray?,
    val rssi: Int? = null
)

class NfcTagSource(...) : TagSource { /* NfcAdapter + ReaderMode */ }
class UhfTagSource(...) : TagSource { /* 串口/BLE UHF 模块 */ }

上层业务只依赖 TagSource,band 决定后续解析策略(NDEF / EPC Gen2 / EM4100)。这样换硬件不动业务代码,也天然满足了"高中低频统一"的产品诉求。

坑:外接模块的时钟与手机 NFC 会互相干扰。UHF 模块发射时优先暂停 NFC 轮询,否则两边都读不到。这是车载/手持机项目的高频问题。

2.7 安全模块:Secure NFC 与中继攻击

业务构想:门禁/支付类业务要防"中继攻击"(一个人拿着读卡器,另一个人拿着手机在远处)。

手段:NfcAdapter.isSecureNfcSupported() / enableSecureNfc(true)(Android 9+,依赖 NXP 芯片能力)。开启后卡模拟被限制在极近距离,中继基本失效。这是硬件级能力,不支持就是没有,不要试图用软件绕。


3. 版本兼容:一张表 + 一段代码

3.1 行为变更矩阵

版本APINFC 相关变更影响与对策
4.419引入 HCE(HostApduService + AID 路由)HCE 基线,之前的机器只能用 eSE
928isSecureNfcSupported() / enableSecureNfc()先判断支持再加开关
1029后台 Activity 启动限制;普通应用无法 enable()/disable()Intent 派发必须前台;开关只能跳设置页
1231PendingIntent 可变性必须显式声明前台派发的 PendingIntent 记得 FLAG_IMMUTABLE
1333NfcFrameworkInitializer 注册服务API 层开始模块化,不要靠版本号猜行为
1434Android Beam 正式移除P2P 方案全部下线,改 BLE/QR
1636NFC 迁入 Mainline APEX com.android.nfcservices;http/https 的 NDEF URI 改为触发 ACTION_VIEW网址标签的 Intent Filter 要兼容 ACTION_VIEW
1737ACTION_TAG_DISCOVERED 废弃;targetSdk > 36 的 Activity 接收 NFC Intent 需声明 android.permission.DISPATCH_NFC_MESSAGE;网址标签改为"打开链接"通知,需用户点击迁移到 NDEF/TECH;清单补权限;不要假设贴卡即跳转

上表中 16/17 的变更来自 AOSP 与 Android 官方文档的现行行为说明。厂商 ROM 落地节奏不一,必须实测。

3.2 兼容写法:一份清单 + 一段代码

<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.NFC" />
<uses-feature android:name="android.hardware.nfc" android:required="false" />

<activity
    android:name=".TagActivity"
    android:exported="true"
    android:permission="android.permission.DISPATCH_NFC_MESSAGE">
    <!-- 注意:该权限从 Android 17 起成为必需;老版本声明无副作用 -->
    <intent-filter>
        <action android:name="android.nfc.action.NDEF_DISCOVERED" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:scheme="https" android:host="your.domain" />
    </intent-filter>
</activity>
object NfcCompat {

    /** 是否具备基础 NFC 能力(硬件 + 可用) */
    fun isAvailable(ctx: Context): Boolean {
        val am = ctx.getSystemService(Context.NFC_SERVICE) as? NfcManager
        return am?.defaultAdapter != null
    }

    /** 是否支持 HCE(特性开关,比版本号可靠) */
    fun supportsHce(ctx: Context): Boolean =
        ctx.packageManager.hasSystemFeature(
            PackageManager.FEATURE_NFC_HOST_CARD_EMULATION)

    /** 是否支持 Secure NFC(硬件相关) */
    fun supportsSecureNfc(adapter: NfcAdapter): Boolean =
        runCatching { adapter.isSecureNfcSupported }.getOrDefault(false)

    /** 统一的读卡入口:ReaderMode 优先级最高,不参与系统级 Intent 竞争 */
    fun startReading(activity: Activity, onTag: (Tag) -> Unit) {
        val adapter = NfcAdapter.getDefaultAdapter(activity) ?: return
        adapter.enableReaderMode(
            activity,
            { tag -> onTag(tag) },
            NfcAdapter.FLAG_READER_NFC_A or
                NfcAdapter.FLAG_READER_NFC_B or
                NfcAdapter.FLAG_READER_NFC_V or
                NfcAdapter.FLAG_READER_SKIP_NDEF_CHECK,
            null
        )
    }

    /** 必须成对调用,否则会一直占用 NFC 前台 */
    fun stopReading(activity: Activity) {
        NfcAdapter.getDefaultAdapter(activity)?.disableReaderMode(activity)
    }
}

三条硬经验:

  1. FLAG_READER_SKIP_NDEF_CHECK 要按需加。加了快,但拿不到 EXTRA_NDEF_MESSAGES,需要自己读;不加则框架会先做一次 NDEF 探测,慢但省事。
  2. ReaderMode 用 onResume 开、onPause 关。忘了关会导致退出应用后 NFC 仍被占用,甚至耗电异常投诉。
  3. 不要同时用 ReaderMode 和 ForegroundDispatch。两者都会争抢前台优先级,行为不确定。

4. 厂商兼容:差异到底从哪来

4.1 芯片与能力

芯片平台常见机型档位关键差异
NXP PN5xx / SN100 系列主流旗舰、大量国产机MIFARE Classic、Secure NFC 支持最好
高通 NQ 系列部分旗舰eSE/UICC 路由能力强,MIFARE 视授权
三星 / ST 等韩版、部分中端FeliCa(日版)、特定路由策略
国产中低端方案千元机常裁剪 MifareClassic、NfcV,甚至只保留 NDEF

4.2 五个高频差异点

  1. MIFARE Classic:需要 NXP 芯片 + 授权。非 NXP 平台基本没有,techList 里干脆不出现。
  2. NfcV / ISO 15693:部分机型默认关闭轮询位,需要在设置或配置文件里打开。
  3. FeliCa(NfcF):仅日版机型提供,国行普遍缺失。
  4. eSE / UICC 路由:金融、运营商业务依赖,需要系统签名或厂商白名单,普通 App 无法直接访问。
  5. 灭屏卡模拟:由 RF_SET_LISTEN_MODE_ROUTING_CMD 的电源状态位决定,各家策略不同(省电优先 or 体验优先)。

4.3 兼容策略:探测 + 降级 + 声明

① 探测:静态特性(PackageManager.hasSystemFeature)+ 动态实测(贴卡看 techList)
② 降级:技术缺失时切换到备用链路(NfcA 透传 / 二维码 / 手输编号)
③ 声明:把"支持的机型清单"写进合同与隐私政策,而不是写进代码注释

一个实用的降级表:

能力缺失降级方案
无 MifareClassic用 NfcA 读 UID + 服务端映射
无 NfcV改用 14443A 标签重新发卡
无 HCE引导使用实体卡 / 动态二维码
无 Secure NFC缩短读卡距离要求 + 后端风控

4.4 配置文件在哪

排障时如果怀疑是 RF 参数问题,先确认这几类文件:

/vendor/etc/libnfc-nci.conf        # 通用 NCI 配置
/vendor/etc/libnfc-nxp.conf        # NXP 专有 RF 参数
/vendor/etc/libnfc-brcm.conf       # 部分平台
/vendor/etc/nfc_nci_<vendor>.conf  # 厂商自定义

这些文件属于 vendor 分区,应用层读不到(SELinux 限制)。所以"读不到某类卡"的最终结论通常是:带上日志找厂商,要求打开对应轮询位。这也是为什么 NFC 项目立项时就要把"厂商支持承诺"写进合同。


5. 排障手册:症状 → 层 → 手段

症状定位层首选手段
开关打不开,一直 TURNING_ONHAL / 固件 / 供电logcat -s nfc_ncif,看 CORE_RESET 是否超时
能开但一张卡都读不到RF_DISCOVER_CMD / 天线换已知好卡交叉验证,对比 dumpsys nfc
只能读某类卡技术位 / 固件看 techList,对照芯片能力表
能读但 App 收不到 Intent派发 / 后台限制 / 权限改前台派发,检查 exported 与 DISPATCH_NFC_MESSAGE
偶发 TagLostExceptionRF 重配 / 场强加退避重试,避免读卡中途切前后台
HCE 无回调AID 路由 / 电源状态dumpsys nfc 看路由表,检查 AID 大写与 category
灭屏刷不了路由电源位要求厂商放开灭屏 host 路由
读卡距离特别近天线 / 手机壳 / 金属换位置、去壳、避开摄像头模组

日志关键词(记下来能省很多时间):

RF_DISCOVER / RF_INTF_ACTIVATED / RF_DEACTIVATE   # 发现链路
CORE_RESET / CORE_INIT                            # 初始化
SET_LISTEN_MODE_ROUTING                           # AID 路由
HostEmulationManager                              # HCE 会话
TagLostException / transceive failed              # 数据交换

6. 上线检查清单

能力与权限

  • uses-feature android.hardware.nfc 设为 required="false",无 NFC 设备可安装
  • 启动时做能力探测,缺失时给出明确文案而非崩溃
  • HCE 用 FEATURE_NFC_HOST_CARD_EMULATION 判断,不用版本号
  • Android 17+ 的 Activity 已声明 android.permission.DISPATCH_NFC_MESSAGE

读卡链路

  • ReaderMode 在 onResume/onPause 成对开关
  • 不缓存 Tag,每次回调重新获取
  • transceive 有退避重试(≥3 次)
  • tech-list 精确到最小集合,不使用 ACTION_TAG_DISCOVERED
  • 网址类标签同时兼容 ACTION_NDEF_DISCOVERED 与 ACTION_VIEW

HCE 链路

  • AID 全大写、偶数长度、已在后端备案
  • processCommandApdu 内无阻塞操作,超时可控
  • 长响应实现 61 XX + GET RESPONSE 分片
  • onDeactivated 正确清理会话状态
  • 与其他应用 AID 冲突时有人工引导

兼容与体验

  • 建立机型验证矩阵(至少覆盖 NXP / 高通 / 三星三类芯片)
  • MIFARE / NfcV 缺失时走降级链路
  • 失败提示可操作("请贴近感应区中央"而非"读取失败")
  • 连续读卡做防抖(同一 UID 500ms 内不重复回调)

7. 结语

NFC 是个"上层简单、下层极深"的领域。Ndef.get(tag).connect() 这一行代码背后,是 NCI 报文、RF 路由、AID 表、电源状态、芯片授权五件事同时成立。

所以做 NFC 业务,真正要建立的能力不是"会调 API",而是三件事:

  1. 分层定位——出问题先判断在哪一层,别在应用层瞎改;
  2. 能力探测——不假设任何机型有什么,先测再说;
  3. 降级设计——任何单点能力都要有 B 方案。

把这三件事做进架构,NFC 就不再是"玄学",而是一个普通的、可测试的传感器。


标签建议:Android、NFC、架构、兼容性、源码分析