phonegap-nfc - npm Package Compare versions

Comparing version 1.0.4 to 1.1.0

CHANGES.txt

@@ -0,1 +1,12 @@
+= 1.1.0 =
+Implement nfc.write for iOS
+New iOS specific APIs
+ * scanNdef
+ * scanTag
+ * cancelScan    
+Deprecated old iOS APIs
+ * beginSession
+ * invalidate
+Remove usage of UIWebView and WKWebView. Send event data to Javascript via the channel callback.
+
 = 1.0.4 =
@@ -2,0 +13,0 @@ Added TAG string for iOS entitlement compatibility #376 Thanks ActionZachson

package.json

 {
   "name": "phonegap-nfc",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "Near Field Communication (NFC) Plugin. Read and write NDEF messages to NFC tags and share NDEF messages with peers.",
@@ -5,0 +5,0 @@ "cordova": {

README.md

@@ -66,9 +66,9 @@ PhoneGap NFC Plugin
 
-Reading NFC NDEF tags is supported on iPhone 7 and iPhone 7 Plus running iOS 11. To enable your app to detect NFC tags, the plugin adds the Near Field Communication Tag Reading capability in your Xcode project. You must build your application with XCode 9. See the [Apple Documentation](http://help.apple.com/xcode/mac/current/#/dev88ff319e7) for more info.
+Reading NFC NDEF tags is supported on iPhone 7 (and newer) since iOS 11. iOS 13 added support for writing NDEF messages to NFC tags. iOS 13 also adds the ability to get the UID from some NFC tags. On iOS, the user must start a NFC session to scan for a tag. This is different from Android which can constantly scan for NFC tags. The [nfc.scanNdef](#nfcscanndef) and [nfc.scanTag](#nfcscantag) functions start a NFC scanning session. The NFC tag is returned to the caller via a Promise. If your existing code uses the deprecated [nfc.beginSession](#nfcbeginsession), update it to use `nfc.scanNdef`.
 
-Use [nfc.addNdefListener](#nfcaddndeflistener) to read NDEF NFC tags with iOS. Unfortunately, iOS also requires you to begin a session before scanning NFC tag. The JavaScript API contains two new iOS specific functions [nfc.beginSession](#nfcbeginsession) and [nfc.invalidateSession](#nfcinvalidatesession).
+The `scanNdef` function uses [NFCNDEFReaderSession](https://developer.apple.com/documentation/corenfc/nfcndefreadersession) to detect NFC Data Exchange Format (NDEF) tags. `scanTag` uses the newer [NFCTagReaderSession](https://developer.apple.com/documentation/corenfc/nfctagreadersession) available in iOS 13 to detect ISO15693, FeliCa, and MIFARE tags. The `scanTag` function will include the tag UID and tag type for *some* NFC tags along with the NDEF messages. `scanTag` can also read some RFID tags without NDEF messsages. `scanTag` will not scan some NDEF tags including Topaz and Mifare Classic. 
 
-You must call [nfc.beginSession](#nfcbeginsession) before every scan. 
+You must call [nfc.scanNdef](#nfcscanndef) and [nfc.scanTag](#nfcscantag) before every scan. 
 
-The initial iOS version plugin does not support scanning multiple tags (invalidateAfterFirstRead:FALSE) or setting the alertMessage. If you have use cases or suggestions on the best way to support multi-read or alert messages, open a ticket for discussion.
+Writing NFC tags on iOS uses the same [nfc.write](#nfcwrite) function as other platforms. Although it's the same function, the behavior is different on iOS. Calling `nfc.write` on an iOS device will start a new scanning session and write data to the scanned tag.
 
@@ -94,4 +94,7 @@ # NFC
 - [nfc.showSettings](#nfcshowsettings)
-- [nfc.beginSession](#nfcbeginsession)
-- [nfc.invalidateSession](#nfcinvalidatesession)
+- [~~nfc.beginSession~~](#nfcbeginsession)
+- [~~nfc.invalidateSession~~](#nfcinvalidatesession)
+- [nfc.scanNdef](#nfcscanndef)
+- [nfc.scanTag](#nfcscanTag)
+- [nfc.cancelScan](#nfccancelscan)
 
@@ -308,2 +311,3 @@ ## ReaderMode
 On **Windows** this method *may* be called from within the NDEF Event Handler.
+On **iOS** this method should be called outside the NDEF Event Handler, it will starts a new scanning session. 
 
@@ -315,2 +319,3 @@ On **Windows Phone 8.1** this method should be called outside the NDEF Event Handler, otherwise Windows tries to read the tag contents as you are writing to the tag.
 - Android
+- iOS
 - Windows
@@ -552,2 +557,4 @@ - BlackBerry 7
 
+**`beginSession` is deprecated. Use `scanNdef` or `scanTag`**
+
 iOS requires you to begin a session before scanning a NFC tag.
@@ -559,4 +566,6 @@
 
-Function `beginSession` starts the [NFCNDEFReaderSession](https://developer.apple.com/documentation/corenfc/nfcndefreadersession) allowing iOS to scan NFC tags.
+**`beginSession` is deprecated. Use `scanNdef` or `scanTag`**
 
+Function `beginSession` starts the [NFCNDEFReaderSession](https://developer.apple.com/documentation/corenfc/nfcndefreadersession) allowing iOS to scan NFC tags. Use [nfc.addNdefListener](#nfcaddndeflistener) to receive the results of the scan.
+
 ### Parameters
@@ -577,2 +586,4 @@
 
+**`invalidateSession` is deprecated. Use `cancelScan``.**
+
 Invalidate the NFC session.
@@ -599,2 +610,109 @@
 
+## nfc.scanNdef
+
+Calling `scanNdef` will being an iOS NFC scanning session. The tag or an error will be returned in a promise.
+
+    nfc.scanNdef();
+
+### Description
+
+Function `scanNdef` starts the [NFCNDEFReaderSession](https://developer.apple.com/documentation/corenfc/nfcndefreadersession)  allowing iOS to scan NFC tags.
+
+### Returns
+
+ - Promise
+
+### Quick Example
+
+    // Promise
+    nfc.scanNdef().then(
+        tag => console.log(JSON.stringify(tag)),
+        err => console.log(err)
+    );
+
+    // Async Await
+    try {
+        let tag = await nfc.scanNdef();
+        console.log(JSON.stringify(tag));
+    } catch (err) {
+        console.log(err);
+    }
+    
+
+### Supported Platforms
+
+- iOS
+
+## nfc.scanTag
+
+Calling `scanTag` will being an iOS NFC scanning session. The tag or an error will be returned in a promise.
+
+    nfc.scanTag();
+
+### Description
+
+Function `scanNdef` starts the [NFCTagReaderSession](https://developer.apple.com/documentation/corenfc/nfctagreadersession) allowing iOS to scan NFC tags.
+
+The Tag reader will attempt to get the UID from the NFC Tag. If can also read the UID from some non-NDEF tags.
+
+### Returns
+
+ - Promise
+
+### Quick Example
+
+    // Promise
+    nfc.scanTag().then(
+        tag => {
+            console.log(JSON.stringify(tag))
+            if (tag.id) {
+                console.log(nfc.bytesToHexString(tag.id));
+            }            
+        },
+        err => console.log(err)
+    );
+
+    // Async Await
+    try {
+        let tag = await nfc.scanTag();
+        console.log(JSON.stringify(tag));
+        if (tag.id) {
+            console.log(nfc.bytesToHexString(tag.id));
+        }
+    } catch (err) {
+        console.log(err);
+    }
+    
+
+### Supported Platforms
+
+- iOS
+
+
+## nfc.cancelScan
+
+Invalidate the NFC session started by `scanNdef` or `scanTag`.
+
+    nfc.cancelScan();
+    
+### Description
+
+Function `cancelScan` stops the [NFCReaderSession](https://developer.apple.com/documentation/corenfc/nfcreadersession) returning control to your app.
+
+### Returns
+
+ - Promise
+
+### Quick Example
+
+    nfc.cancelScan().then(
+        success => { console.log('Cancelled NFC session')}, 
+        err => { console.log(`Error cancelling session ${err}`)}
+    );
+
+### Supported Platforms
+
+- iOS
+
+
 # Reader Mode Functions
@@ -739,3 +857,3 @@
 
-Function `connect` enables I/O operations to the tag from this TagTechnology object. `nfc.connect` should be called after receiving a nfcEvent from the `addTagDiscoveredListener`. Only one TagTechnology object can be connected to a Tag at a time.
+Function `connect` enables I/O operations to the tag from this TagTechnology object. `nfc.connect` should be called after receiving a nfcEvent from the `addTagDiscoveredListener` or the `readerMode` callback. Only one TagTechnology object can be connected to a Tag at a time.
 
@@ -751,3 +869,3 @@ See Android's [TagTechnology.connect()](https://developer.android.com/reference/android/nfc/tech/TagTechnology.html#connect()) for more info.
 
- - Promise when the connection is successful
+ - Promise when the connection is successful, optionally with a maxTransceiveLength attribute in case the tag technology supports it
 
@@ -1159,3 +1277,3 @@ ### Quick Example
 
-Copyright (c) 2011-2017 Chariot Solutions
+Copyright (c) 2011-2020 Chariot Solutions
 
@@ -1162,0 +1280,0 @@ Permission is hereby granted, free of charge, to any person obtaining a copy

www/phonegap-nfc.js

@@ -414,2 +414,11 @@ /*jshint  bitwise: false, camelcase: false, quotmark: false, unused: vars, esversion: 6, browser: true*/
     
+    multiCallbackTest: function(success, failure) {
+        cordova.exec(success, failure, "NfcPlugin", "multiCallbackTest", []);
+    },
+
+    // multiCallbackTest: function(success, failure) {
+    //     //cordova.exec(success, failure, "NfcPlugin", "multiCallbackTest", []);
+    //     setInterval(failure, 10000, 'Test from JavaScript!');
+    // },
+    
     addTagDiscoveredListener: function (callback, win, fail) {
@@ -435,4 +444,9 @@ document.addEventListener("tag", callback, false);
 
-    write: function (ndefMessage, win, fail) {
-        cordova.exec(win, fail, "NfcPlugin", "writeTag", [ndefMessage]);
+    write: function (ndefMessage, win, fail, options) {      
+        
+        if (cordova.platformId === "ios") {
+          cordova.exec(win, fail, "NfcPlugin", "writeTag", [ndefMessage, options]);        
+        } else {
+          cordova.exec(win, fail, "NfcPlugin", "writeTag", [ndefMessage]);
+        }
     },
@@ -491,8 +505,30 @@
 
-    // iOS only
+    // iOS only - scan for NFC NDEF tag using NFCNDEFReaderSession
+    scanNdef: function () {
+        return new Promise(function(resolve, reject) {
+            cordova.exec(resolve, reject, "NfcPlugin", "scanNdef", []);
+        });
+    },
+
+    // iOS only - scan for NFC Tag using NFCTagReaderSession
+    scanTag: function (options) {
+        return new Promise(function(resolve, reject) {
+            cordova.exec(resolve, reject, "NfcPlugin", "scanTag", []);
+        });
+    },
+    
+    // iOS only - cancel NFC scan session
+    cancelScan: function () {
+        return new Promise(function(resolve, reject) {
+            cordova.exec(resolve, reject, "NfcPlugin", "cancelScan", []);
+        });
+    },
+
+    // iOS only - deprecated use scanNdef or scanTag
     beginSession: function (win, fail) {
+        // cordova.exec(win, fail, "NfcPlugin", "beginSession", []);
         cordova.exec(win, fail, "NfcPlugin", "beginSession", []);
     },
 
-    // iOS only
+    // iOS only - deprecated use cancelScan
     invalidateSession: function (win, fail) {
@@ -502,2 +538,3 @@ cordova.exec(win, fail, "NfcPlugin", "invalidateSession", []);
 
+    // connect to begin transceive
     connect: function(tech, timeout) {
@@ -509,2 +546,3 @@ return new Promise(function(resolve, reject) {
 
+    // close transceive connection
     close: function() {
@@ -517,3 +555,3 @@ return new Promise(function(resolve, reject) {
     // data - ArrayBuffer or string of hex data for transcieve
-    // the results of transcieve are returned in the promise success as an ArrayBuffer
+    // the results of transceive are returned in the promise success as an ArrayBuffer
     transceive: function(data) {
@@ -520,0 +558,0 @@ return new Promise(function(resolve, reject) {

No alert changes

Improved metrics

Total package byte prevSize

436589

increased by5.13%

Lines of code

2614

increased by1.75%

Number of lines in readme file

1286

increased by10.1%

No dependency changes