nfcreader-sdk

NFCReader-SDK 用于开发基于 NFCReader 应用上的功能扩展插件

• NFCReader是一款基于 android 操作系统之上的 NFC 读写工具软件，可在各大应用商店搜索“NFCReader”进行下载（同时也可直接点击进行下载）
• 功能扩展插件本质上是使用 TaroJS 3.x（官方文档链接） 开发的 H5应用（SPA），运行于 NFCReader 应用中的 WebView 中
• SDK将原本复杂的 NFC 读写操作进行了封装，以简单的函数调用展示出来，具备基本前端开发技能的同学均可轻松的开发出属于自己的NFC读写插件，实现特有的业务逻辑
• 插件SDK的使用完全免费，开发完成的插件审核通过后便可发布在 NFCReader 插件市场上，供其他用户有偿/无偿下载使用
• 对于付费插件的收入，开发者可无门槛提现至指定的支付宝或微信账户
• 开发中遇到的任何问题均可在抖音/快手中搜索“NFCReader”，与官方客服进行沟通和解决

---

SDK 安装

项目根目录下执行命令安装插件SDK

npm install --save nfcreader-sdk

SDK初始化

// 在Tarojs项目中的入口文件中进行SDK初始化 app.js
import { System } from 'nfcreader-sdk';

function APP({ children }){

	useLaunch(() =>{

		System.init('你的插件ID');

	});
}

注意：SDK初始化必须在其他接口调用前进行，否则会造成接口异常

插件调试

• Tarojs 项目本地运行（npm run dev:h5）
• 手机运行 NFCReader 软件，我的——插件管理——插件开发调试
• 输入项目本地 IP 地址后开启调试
• 建议安装 vconsole，并在项目启动阶段进行初始化，方便查看调试日志

项目打包

打包前需修改项目配置，config/index.js

一定要将publicPath修改为“./”，否则插件无法正常加载，切记！！！

一定要将publicPath修改为“./”，否则插件无法正常加载，切记！！！

一定要将publicPath修改为“./”，否则插件无法正常加载，切记！！！

const config = {
	//...
	h5: {
		//...
		publicPath: './',
		//...
	},
	//...
}

项目需构建打包为 H5 应用

npm run build:h5

插件审核&发布

• 打包完成的插件，添加到 zip 压缩包
• 手机运行 NFCReader 软件，我的——插件管理——找到对应 ID 的插件项目
• 选择压缩包并上传，等待审核即可
• 审核通过后，开发者可将插件发布至插件市场或分享给其他用户使用

API

M1.readSectorByNFC(keyArray: SectorKey[]) : Promise<ReadDataResponse>

通过 NFC 读取 M1 标签扇区数据

参数为密钥对象数组

interface SectorKey {
	/** 扇区索引编号，取值0-15 */
	sector: number;
	/** 扇区A密钥，6字节hex数值 */
	keyA: string;
	/** 扇区B密钥，6字节hex数值 */
	keyB: string;
	/** 扇区访问控制指令，4字节hex数值 */
	keyC?: string;	
};

返回Promise，当resolve时，对象属性如下

interface ReadDataResponse {
	/** SDK执行标识符，true为执行成功；false为执行失败 */
	status: boolean;
	data: {
		/** 扇区第0块数据，16字节hex数值 */
        b0: string;
        /** 扇区第1块数据，16字节hex数值 */
        b1: string;
        /** 扇区第2块数据，16字节hex数值 */
        b2: string;
        /** 扇区A密钥，6字节hex数值 */
        keyA: string;
        /** 扇区B密钥，6字节hex数值 */
        keyB: string;
        /** 扇区访问控制指令，4字节hex数值 */
        keyC: string;
	} | null;
	/** SDK操作回执消息 */
	msg: string;
}

M1.readSectorByPN532(keyArray: SectorKey[]): Promise<ReadDataResponse>

通过 PN532 芯片读卡器读取 M1 标签扇区数据

参数和返回值类型见 M1.readSectorByNFC

M1.readSectorWithUI(keyArray: SectorKey[], NFCActionCallback: (result: ReadDataResponse) => void, PN532ActionCallback: (result: ReadDataResponse) => void): void

调用宿主 UI 读取 M1 标签扇区数据（用户自行选择使用 NFC或者PN532操作）

参数和回调函数参数类型见 M1.readSectorByNFC

M1.writeBlockByNFC(sectorIndex: number, blockIndex: number, data: string, key: SectorKey): Promise<SDKResponse>

通过 NFC 向 M1 标签写入块数据

参数类型见函数签名及M1.readSectorByNFC

返回值为Promise，当resolve时，对象属性如下

/** SDK响应格式 */
interface SDKResponse {
    /** SDK执行标识符，true为执行成功；false为执行失败 */
    status: boolean;
    /** SDK操作回执消息 */
    msg: string;
}

M1.writeBlockByPN532(sectorIndex: number, blockIndex: number, data: string, key: SectorKey): Promise<SDKResponse>

通过 PN532 芯片读卡器向 M1 标签写入块数据

参数及返回值见 M1.writeBlockByNFC

M1.writeSectorByNFC(dataArray: SectorData[], keyArray: SectorKey[], isWriteB0: boolean): Promise<SDKResponse>

通过 NFC 向 M1 标签写入扇区数据

参数类型见函数签名，写入数据对象属性如下

interface SectorData {
	sector: number;
	data: {
		/** 扇区第0块数据，16字节hex数值 */
        b0: string;
        /** 扇区第1块数据，16字节hex数值 */
        b1: string;
        /** 扇区第2块数据，16字节hex数值 */
        b2: string;
        /** 扇区A密钥，6字节hex数值 */
        keyA: string;
        /** 扇区B密钥，6字节hex数值 */
        keyB: string;
        /** 扇区访问控制指令，4字节hex数值 */
        keyC: string;
	};
}

返回值为Promise，同 M1.writeBlockByNFC

M1.writeSectorByPN532(dataArray: SectorData[], keyArray: SectorKey[], isWriteB0: boolean): Promise<SDKResponse>

通过 PN532 芯片读卡器向 M1 标签写入扇区数据

参数类型及返回值同 M1.writeSectorByNFC

M1.writeSectorWithUI(dataArray: SectorData[], keyArray: SectorKey[], NFCActionCallback: (result: SDKResponse) => void, PN532ActionCallback: (result: SDKResponse) => void):void

调用宿主 UI 向 M1 标签写入扇区数据（用户自行选择使用 NFC 或者 PN532 操作）

参数及回调函数参数见上述其他接口

M1.selectKeyByUI(): Promise<ReadKeyResponse>

调用宿主 UI 选择用户保存的密钥文件数据

返回值为Promise，当 resolve 时，返回的对象属性如下

interface ReadKeyResponse {
	/** SDK执行标识符，true为执行成功；false为执行失败 */
	status: boolean;
	data: {
		/** 扇区索引编号，取值0-15 */
        sector: number;
        /** 扇区A密钥，6字节hex数值 */
        keyA: string;
        /** 扇区B密钥，6字节hex数值 */
        keyB: string;
        /** 扇区访问控制指令，4字节hex数值 */
        keyC?: string;
	};
	/** SDK操作回执消息 */
	msg: string;
}

M1.selectCardByUI(): Promise<ReadDataResponse>

调用宿主 UI 选择用户保存的 M1 标签文件数据

返回值对象属性见上述其他接口

System.init(devID: string): void

初始化 SDK

参数及返回值见函数签名

System.connectPN532(): Promise<ConnectPN532Response>

连接 PN532 芯片读卡器

返回值为 Promise，当 resolve 时，返回对象属性如下：

interface ConnectPN532Response {
	/** SDK执行标识符，true为执行成功；false为执行失败 */
	status: boolean;
	data: {
		/** PN532是否连接标识符 */
		isConnected: boolean;
	};
	/** SDK操作回执消息 */
	msg: string;
}

System.getPN532Status(): Promise<PN532StatusResponse>

获取 PN532 芯片读卡器状态

返回值为 Promise， 当 resolve 时， 返回对象属性如下：

interface PN532StatusResponse {
	/** SDK执行标识符，true为执行成功；false为执行失败 */
	status: boolean;
	data: {
		/** PN532是否连接标识符 */
		isConnected: boolean;
		/** PN532是否插入手机 */
        isDevInsert: boolean;
	};
	/** SDK操作回执消息 */
	msg: string;
}

System.getUserInfo(): Promise<UserinfoResponse>

获取插件使用用户的基础资料

返回值为 Promise， 当 resolve 时，返回对象属性如下：

interface UserinfoResponse {
	/** SDK执行标识符，true为执行成功；false为执行失败 */
	status: boolean;
	data: {
		/** 用户ID */
		id: string;
		/** 用户昵称 */
		nickName: string;
		/** 用户头像 */
		avatar: string;
	};
	/** SDK操作回执消息 */
	msg: string;
}

System.getNFCStatus(): Promise<NFCStatusResponse>

获取手机 NFC 开关状态

返回值为 Promise，当 resolve 时， 返回对象属性如下：

interface NFCStatusResponse {
	/** SDK执行标识符，true为执行成功；false为执行失败 */
	status: boolean;
	data: {
		/** NFC开关是否开发 */
		isOpen: boolean;
	};
	/** SDK操作回执消息 */
	msg: string;
}

System.openNFCSettings(): void

打开手机 NFC 设置界面

System.copyToClipboard(text: string): void

复制文本到手机剪贴板

Ui.showToast(msg: string, during?: ToastDuring): void

调用安卓原生 Toast 进行消息展示

参数见函数签名及下面所示

type ToastDuring = 'short' | 'long';

Ui.createModal(config: ModalConfig, confirmCallback: () => void, cancelCallback?: () => void): Modal

根据配置创建一个模态 Modal

confirmCallback 为确认按钮点击回调，位于 Modal 右下角；cancelCallback 为取消按钮点击回调，位于 Modal 左下角，配置项属性如下

interface ModalConfig {
    /** 标题配置 */
    title: {
    	/** 标题文字，最大长度6 */
    	text: string;
    	/** 标题背景色，rgba(0,0,0,0)/rgb(0,0,0)/#000000/black */
    	bgColor?: string;
    	/** 文字颜色，rgba(0,0,0,0)/rgb(0,0,0)/#000000/black */
    	fontColor?: string;
    };
    content: {
        /** 弹窗内容 */
        text: string;
        /** 文字颜色，rgba(0,0,0,0)/rgb(0,0,0)/#000000/black */
        fontColor?: string;
        /** 文字对齐方式 */
        textAlign?: 'left' | 'center' | 'right';
    };
    subContent?: {
        /** 弹窗子内容 */
        text: string;
        /** 文字颜色，rgba(0,0,0,0)/rgb(0,0,0)/#000000/black */
        fontColor?: string;
        /** 文字对齐方式 */
        textAlign?: 'left' | 'center' | 'right';
    };
    confirmBtn: {
        /** 取消按钮文字，最大长度6 */
        text: string;
        /** 按钮背景色，rgba(0,0,0,0)/rgb(0,0,0)/#000000/black */
        bgColor?: string;
        /** 文字颜色，rgba(0,0,0,0)/rgb(0,0,0)/#000000/black */
        fontColor?: string;
    };
    cancelBtn?: {
        /** 确定按钮文字，最大长度6 */
        text: string;
        /** 按钮背景色，rgba(0,0,0,0)/rgb(0,0,0)/#000000/black */
        bgColor?: string;
        /** 文字颜色，rgba(0,0,0,0)/rgb(0,0,0)/#000000/black */
        fontColor?: string;
    };
};

返回值为 Modal 类型，对象属性如下：

interface Moda {
	/** 显示弹窗 */
	show(): void;
	/** 隐藏弹窗 */
	hide(): void;
}

Event.addRWPercentListener(name: EventName, callback: (event: EventPercent) => void): void

添加 NFC/PN532 数据读写进度监听函数

事件名称属性及回调函数参数对象属性如下：

type EventName = 'nfcReadPercent' | 'nfcWritePercent' | 'pn532ReadPercent' | 'pn532WritePercent';

interface EventPercent {
	/** 操作进度数值 */
	value: number;
}

Event.removeRWPercentListener(name: EventName, callback: (event: EventPercent) => void): void

移除 NFC/PN532 数据读写进度监听函数

参数同 Event.addRWPercentListener

持续关注

后续将逐步开放其他 NFC 协议的读写 SDK，如 NDEF 标签、CPU 标签等，敬请持续关注