WebApp快捷打包
NFC 近场通信
转到模块插件

敬告:此 DEMO 演示为开放测试页面,仅用于开发者快速测试体验应用功能,请严格遵守开发者协议,了解更多

JS-SDK 引用方式:

♦ 普通网页 script 方式加载:下载最新版 jsBridge-v20240326.zip,请在页面上调用 jsBridge 接口之前引用 jsbridge-mini.js 库;

♦ js module 方式引用:npm install ym-jsbridge 具体请参考 npm package

使用步骤:

1. 检测设备是否支持 NFC 功能并且已启用;

2. 调用 setListener 设置监听器,NFC 标签数据及操作状态都在此监听器中返回;

3. 调用 enableForegroundDispatch 让本 APP 处于前台激活状态时接管 NFC 调度;

4. 将设备靠近 NFC 标签时会自动读取数据并完成指定的操作;

♦ Android 支持写入 NDEF TAG,iOS 仅支持读取 NDEF TAG。

状态检测与设置

isSupported 检测设备是否支持 NFC 功能

//支持 Android & iOS(从 iOS 11, iPhone 7 开始支持)
jsBridge.nfc.isSupported(function(succ, data) {
  alert(data.isSupported ? "支持" : "不支持");
});

isEnabled 检测设备是否已启用 NFC

//支持 Android & iOS
//iOS 始终返回 true,如果已禁用 NFC 功能,执行 enableForegroundDispatch 接口时会提示打开 NFC 功能
jsBridge.nfc.isEnabled(function(succ, data) {
  alert(data.isEnabled ? "已启用" : "已停用");
});

openSettings 转到 NFC 设置

//支持 Android
jsBridge.nfc.openSettings();

事件监听

setListener 设置监听器

• 如需接口调用事件,请设置此监听器;

//支持 Android & iOS
//请设置此监听器监听读写数据和事件
jsBridge.nfc.setListener(function(event, data) {if (event == "NDEF_DISCOVERED")
  show({
    event: event,
    data : data
  });
});

//请拉到页面底部查看回调数据信息
$('html,body').animate({ scrollTop: $('#view').offset().top }, 500);

/**
回调参数说明:
event - 事件代码,字符串类型,可能的值:

  //将设备靠近 NFC 标签时会自动读取数据
  //数据在 data 参数中返回
  NDEF_DISCOVERED            发现了 NDEF TAG 标签
  NDEF_SESSION_INVALIDATED   NDEF 会话已失效(仅支持 iOS,如需再次读取需再次调用 enableForegroundDispatch 接口)
  TECH_DISCOVERED            发现了支持特定技术的 TAG 标签
  TAG_DISCOVERED             发现了 TAG 标签

  //写入 NDEF TAG
  //写入操作的数据是一次性的
  //写入成功、失败或取消后都会清除待写入的数据,如需再次写入需调用 write 接口重新准备写入的数据
  NDEF_PENDING_WRITE     待写入数据(请将设备靠近 NFC 标签)
  NDEF_WRITE_SUCCESS     写入成功
  NDEF_WRITE_FAILED      写入失败
  NDEF_WRITE_CANCELED    取消写入(设备靠近 NFC 标签时不再写入)

  //只读 NDEF TAG
  //只读操作是一次性的
  //只读操作成功、失败或取消后都会清除只读操作,如需再次执行只读操作需调用 makeReadOnlyNdef 接口重新准备只读操作
  NDEF_PENDING_MAKE_READ_ONLY    待执行置为只读的操作(请将设备靠近 NFC 标签)
  NDEF_MAKE_READ_ONLY_SUCCESS    置为只读成功
  NDEF_MAKE_READ_ONLY_FAILED     置为只读失败
  NDEF_MAKE_READ_ONLY_CANCELED   取消执行置为只读的操作(设备靠近 NFC 标签时不再执行置为只读的操作)

  //写入 MifareUltralight TAG Page
  //写入操作的数据是一次性的
  //写入成功、失败或取消后都会清除待写入的数据
  MIFAREULTRALIGHT_PENDING_WRITE_PAGE     待写入分页数据(请将设备靠近 NFC 标签)
  MIFAREULTRALIGHT_WRITE_PAGE_SUCCESS     分页写入成功
  MIFAREULTRALIGHT_WRITE_PAGE_FAILED      分页写入失败
  MIFAREULTRALIGHT_WRITE_PAGE_CANCELED    取消分页写入(设备靠近 NFC 标签时不再写入)
  //收发 MifareUltralight TAG 原始数据
  //收发操作的数据是一次性的
  //收发成功、失败或取消后都会清除待发送的数据
  MIFAREULTRALIGHT_PENDING_TRANSCEIVE     待收发数据(请将设备靠近 NFC 标签)
  MIFAREULTRALIGHT_TRANSCEIVE_SUCCESS     收发成功
  MIFAREULTRALIGHT_TRANSCEIVE_FAILED      收发失败
  MIFAREULTRALIGHT_TRANSCEIVE_CANCELED    取消收发(设备靠近 NFC 标签时不再发送)

data  - 事件数据,JSON 对象
**/

removeListener 移除监听器

//支持 Android & iOS
//移除监听器,不会再收到回调通知
//在需要时可重新调用 setListener
jsBridge.nfc.removeListener();

NFC 调度(NFC 连接会话)

enableForegroundDispatch 启用前台调度(开启连接会话)

• APP当前窗口处于前台激活状态时处理 NFC 事件调度;

• 请先执行 setListener 监听 NFC 事件调度及数据;

//支持 Android & iOS(iOS 目前仅支持读取 NDEF 标签)
//请开启调度以便 APP 在前台激活状态时能处理 NFC 任务调度
//将设备靠近标签后会监听到 NDEF_DISCOVERED 或 TECH_DISCOVERED 或 TAG_DISCOVERED 事件
jsBridge.nfc.enableForegroundDispatch({
  //是否连续读取,布尔类型,(仅iOS需提供)
  continuous  : false,
  //提示文字,字符串类型,(仅iOS需提供)
  alertMessage: "请将手机靠近展品标签获取更多信息!"
}, function(succ, data) {
  if (jsBridge.ios) {
    if (!succ) alert(JSON.stringify(data));
  } else {
    alert(succ ? "已启用,请将手机靠近 NFC 标签。" : JSON.stringify(data));
  }
});

disableForegroundDispatch 停用前台调度(结束连接会话)

//支持 Android & iOS
//APP不再处理 NFC 任务调度
jsBridge.nfc.disableForegroundDispatch(function(succ, data) {
  alert(succ ? "已停用" : JSON.stringify(data));
});

写入 NDEF TAG

writeNdefUri 写入 URI 数据

//支持 Android
//写入 URI 数据
//调用成功后会监听到 NDEF_PENDING_WRITE 事件
//将设备靠近标签后会监听到 NDEF_WRITE_SUCCESS 或 NDEF_WRITE_FAILED 事件
jsBridge.nfc.writeNdefUri({
  //必须,字符串类型,Uri 字符串
  uri: "https://m.baidu.com",
  //可选,布尔类型,写入数据之后是否将标签置为只读状态(置为只读后标签将不再可写),默认 false
  makeReadOnly: false
}, function(succ, data) {
  if (succ) {
    alert("待写入,请将设备靠近 NDEF TAG 标签。");
  } else {
    alert(JSON.stringify(data));
  }
});

writeNdefText 写入 TEXT 文本数据

//支持 Android
//写入 TEXT 文本数据
//调用成功后会监听到 NDEF_PENDING_WRITE 事件
//将设备靠近标签后会监听到 NDEF_WRITE_SUCCESS 或 NDEF_WRITE_FAILED 事件
jsBridge.nfc.writeNdefText({
  //必须,字符串类型,文本内容
  text: "任意文本数据,Any Text。",
  //可选,布尔类型,写入数据之后是否将标签置为只读状态(置为只读后标签将不再可写),默认 false
  makeReadOnly: false
}, function(succ, data) {
  if (succ) {
    alert("待写入,请将设备靠近 NDEF TAG 标签。");
  } else {
    alert(JSON.stringify(data));
  }
});

writeNdefMime 写入 MIME 数据

//支持 Android
//写入 MIME 数据
//调用成功后会监听到 PENDING_WRITE 事件
//将设备靠近标签后会监听到 NDEF_WRITE_SUCCESS 或 NDEF_WRITE_FAILED 事件
jsBridge.nfc.writeNdefMime({
  //必须,字符串类型, MimeType 类型
  mimeType: "text/plain",
  //必须,字符串类型,bytes 数组的16进制格式
  //Chinese Dream! 中国梦!(UTF8 Encoded Bytes Array)
  rawBytes: "4368696E65736520447265616D2120E4B8ADE59BBDE6A2A6EFBC81",
  //可选,布尔类型,写入数据之后是否将标签置为只读状态(置为只读后标签将不再可写),默认 false
  makeReadOnly: false
}, function(succ, data) {
  if (succ) {
    alert("待写入,请将设备靠近 NDEF TAG 标签。");
  } else {
    alert(JSON.stringify(data));
  }
});

writeNdefText 写入 TEXT 文本数据后置为只读标签

//支持 Android
//写入 TEXT 文本数据后置为只读标签
//请谨慎操作,置为只读后标签将不再可写!!!
jsBridge.nfc.writeNdefText({
  text: "任意文本数据,Any Text,ReadOnly !!!",
  ////写入后,将标签置为只读状态
                makeReadOnly: true
}, function(succ, data) {
  if (succ) {
    alert("待写入,请将设备靠近 NDEF TAG 标签。");
  } else {
    alert(JSON.stringify(data));
  }
});

cancelWriteNdef 取消写入 NDEF_PENDING_WRITE

//支持 Android
//取消待执行的写入操作
//调用成功后会监听到 NDEF_WRITE_CANCELED 事件,将设备靠近标签将不再执行写入操作
jsBridge.nfc.cancelWriteNdef(function(succ, data) {
  if (succ) {
    alert("已取消 NDEF_PENDING_WRITE");
  } else {
    alert(JSON.stringify(data));
  }
});

只读 NDEF TAG

makeReadOnlyNdef 将标签置为只读状态

//支持 Android
//将标签置为只读状态
//调用成功后会监听到 NDEF_PENDING_MAKE_READ_ONLY 事件
//将设备靠近标签后会监听到 NDEF_MAKE_READ_ONLY_SUCCESS 或 NDEF_MAKE_READ_ONLY_FAILED 事件
jsBridge.nfc.makeReadOnlyNdef(function(succ, data) {
  if (succ) {
    alert("待置为只读状态,请将设备靠近 NDEF TAG 标签。");
  } else {
    alert(JSON.stringify(data));
  }
});

cancelMakeReadOnlyNdef 取消只读 NDEF_PENDING_MAKE_READ_ONLY

//支持 Android
//取消待执行置为只读的操作
//调用成功后会监听到 NDEF_MAKE_READ_ONLY_CANCELED 事件,将设备靠近标签将不再执行置为只读的操作
jsBridge.nfc.cancelMakeReadOnlyNdef(function(succ, data) {
  if (succ) {
    alert("已取消 NDEF_PENDING_MAKE_READ_ONLY");
  } else {
    alert(JSON.stringify(data));
  }
});

写入 MifareUltralight TAG

writeMifareUltralightPage 写入 MifareUltralight 页

//支持 Android
//写入 MifareUltralight 页
jsBridge.nfc.writeMifareUltralightPage({
  //必须,从0开始的页次
  index: 16,
  //必须,4字节数据的16进制格式
  data : "61626364"
}, function(succ, data) {
  if (succ) {
    alert("待写入,请将设备靠近 MifareUltralight TAG 标签。");
  } else {
    alert(JSON.stringify(data));
  }
});

cancelWriteMifareUltralightPage 取消写入 MifareUltralight 页

//支持 Android
//取消写入 MifareUltralight 页
jsBridge.nfc.cancelWriteMifareUltralightPage(function(succ, data) {
  if (succ) {
    alert("已取消 MIFAREULTRALIGHT_PENDING_WRITE_PAGE");
  } else {
    alert(JSON.stringify(data));
  }
});

transceiveMifareUltralight 收发 MifareUltralight 原始数据

将原始数据发送到 MifareUltralight TAG 并接收响应

//支持 Android
//收发 MifareUltralight 原始数据
jsBridge.nfc.transceiveMifareUltralight({
  //必须,字符串类型,原始 bytes 数组的16进制格式
  //示例:第0F页写入 ABCD 字符
  rawBytes: "A20F41424344"
}, function(succ, data) {
  if (succ) {
    alert("待收发,请将设备靠近 MifareUltralight TAG 标签。");
  } else {
    alert(JSON.stringify(data));
  }
});

cancelTransceiveMifareUltralight 取消收发 MifareUltralight 原始数据

//支持 Android
//取消收发 MifareUltralight 原始数据
jsBridge.nfc.cancelTransceiveMifareUltralight(function(succ, data) {
  if (succ) {
    alert("已取消 MIFAREULTRALIGHT_PENDING_TRANSCEIVE");
  } else {
    alert(JSON.stringify(data));
  }
});

示例数据

读取 NDEF Tag - NDEF_DISCOVERED 事件

//Android 读取 NDEF Tag 示例数据
var android_sample = {
    data: null,
    tag: {
        ID: "04bf87225a6680",
        Technologies: {
            MifareUltralight: {
                MifareClassicType: "TYPE_ULTRALIGHT_C",
                MaxTransceiveLength: 253,
                Timeout: 618
            },
            NfcA: {
                MaxTransceiveLength: 253,
                Timeout: 618,
                SAK: 0,
                ATQA: "4400"
            },
            Ndef: {
                Type: "org.nfcforum.ndef.type2",
                //Ndef 消息
                NdefMessage: {
                    //16进制的原始数据
                    Raw: "d1012354027a68e4bbbbe6848fe69687e69cace695b0e68daeefbc8c416e792054657874e38082",
                    //Ndef 消息记录数组
                    Records: [
                        {
                            ID: "",
                            //16进制记录类型
                            Type: "54",
                            Uri: null,
                            //16进制记录荷载(原始 byte 数据流)
                            Payload: "027a68e4bbbbe6848fe69687e69cace695b0e68daeefbc8c416e792054657874e38082",
                            //如果 Payload 为可读文本,这是里其字符串格式
                            Payload_String: "任意文本数据,Any Text。",
                            Tnf: 1,
                            MimeType: "text/plain"
                        }
                    ],
                    ByteLength: 39
                },
                //Ndef 消息数组
                NdefMessages: [
                    {
                        Raw: "d1012354027a68e4bbbbe6848fe69687e69cace695b0e68daeefbc8c416e792054657874e38082",
                        Records: [
                            {
                                ID: "",
                                Type: "54",
                                Uri: null,
                                Payload: "027a68e4bbbbe6848fe69687e69cace695b0e68daeefbc8c416e792054657874e38082",
                                Payload_String: "任意文本数据,Any Text。",
                                Tnf: 1,
                                MimeType: "text/plain"
                            }
                        ],
                        ByteLength: 39
                    }
                ],
                CachedNdefMessage: {
                    Raw: "d1012354027a68e4bbbbe6848fe69687e69cace695b0e68daeefbc8c416e792054657874e38082",
                    Records: [
                        {
                            ID: "",
                            Type: "54",
                            Uri: null,
                            Payload: "027a68e4bbbbe6848fe69687e69cace695b0e68daeefbc8c416e792054657874e38082",
                            Payload_String: "任意文本数据,Any Text。",
                            Tnf: 1,
                            MimeType: "text/plain"
                        }
                    ],
                    ByteLength: 39
                },
                ReadOnly: true,
                MaxSize: 39,
                CanMakeReadOnly: true
            }
        }
    }
};

//iOS 读取 NDEF Tag 示例数据
var ios_sample = {
    data: null,
    tag: {
        ID: "",
        Technologies: {
            Ndef: {
                Type: "",
                //读取到都第一条 Ndef 消息
                NdefMessage: {
                    //Ndef 消息记录数组
                    Records: [
                        {
                            ID: "",
                            //16进制记录类型
                            Type: "54",
                            Uri: null,
                            //16进制记录荷载(原始 byte 数据流)
                            Payload: "027a68e4bbbbe6848fe69687e69cace695b0e68daeefbc8c416e792054657874e38082",
                            //如果 Payload 为可读文本,这是里其字符串格式
                            Payload_String: "任意文本数据,Any Text。"
                        }
                    ]
                },
                //读取到的所有 Ndef 消息数组
                NdefMessages: [
                    {
                        Records: [
                            {
                                ID: "",
                                Uri: null,
                                Type: "54",
                                Payload: "027a68e4bbbbe6848fe69687e69cace695b0e68daeefbc8c416e792054657874e38082",
                                Payload_String: "任意文本数据,Any Text。"
                            }
                        ]
                    }
                ]
            }
        }
    }
};

监听回调数据: