Merge pull request #22 from bitjson/feature/ios-10-support

feat(ios): Support iOS 10 beta

readme.md

@@ -5,7 +5,7 @@
 # cordova-plugin-qrscanner
 A fast, energy efficient, highly-configurable QR code scanner for Cordova apps – available for the iOS, Android, and browser platforms.
 
-QRScanner's live video preview is rendered behind the Cordova app's native webview, and the native webview's background is made transparent. This allows for an HTML/CSS/JS interface to be built inside the webview to control the scanner.
+QRScanner's native camera preview is rendered behind the Cordova app's webview, and QRScanner provides `show` and `hide` methods to toggle the transparency of the webview's background. This allows for a completely HTML/CSS/JS interface to be built inside the webview to control the scanner.
 
 ## Get Started
 
@@ -17,7 +17,13 @@ On most platforms, simply adding the plugin to the Cordova project will make the
 
 ### Usage
 
-First, get permission to access the user's camera:
+There are two primary steps to integrating `cordova-plugin-qrscanner`.
+
+#### 1. Get Permission Early (Optional)
+
+**This step is optional** – if the best place for your app to ask for camera permissions is at the moment scanning begins, you can safely skip this step.
+
+If there's a better place in your app's onboarding process to ask for permission to use the camera ("permission priming"), this plugin makes it possible to ask prior to scanning using the [`prepare` method](#prepare). The `prepare` method initializes all the infrastructure required for scanning to happen, including (if applicable) asking for camera permissions. This can also be done before attempting to show the video preview, making your app feel faster and more responsive.
 
 ```js
 // For the best user experience, make sure the user is ready to give your app
@@ -32,27 +38,26 @@ function onDone(err, status){
   }
   if (status.authorized) {
     // W00t, you have camera access and the scanner is initialized.
+    // QRscanner.show() should feel very fast.
   } else if (status.denied) {
    // The video preview will remain black, and scanning is disabled. We can
    // try to ask the user to change their mind, but we'll have to send them
    // to their device settings with `QRScanner.openSettings()`.
   } else {
-    // we didn't get permission, but we didn't get denied. (On Android, a denial
-    // isn't permanent unless the user checks the "Don't ask again" box.)
-    // We can ask again at the next relevant opportunity.
+    // we didn't get permission, but we didn't get permanently denied. (On
+    // Android, a denial isn't permanent unless the user checks the "Don't
+    // ask again" box. We can ask again at the next relevant opportunity.
   }
 }
 ```
 
-Later in your app, when you're ready to show the video preview and scan:
+#### 2. Scan
 
-```js
-// Make the webview transparent so the video preview is visible behind it.
-// (Not required for scanning to work on iOS.)
-QRScanner.show();
-// Be sure to make any opaque HTML elements transparent here to avoid
-// covering the video.
+Later in your application, simply call the [`scan` method](#scan) to enable scanning, and the [`show` method](#show) to make the camera preview visible.
+
+If you haven't previously `prepare`d the scanner, the `scan` method will first internally `prepare` the scanner, then begin scanning. If you'd rather ask for camera permissions at the time scanning is attempted, this is the simplest option.
 
+```js
 // Start a scan. Scanning will continue until something is detected or
 // `QRScanner.cancelScan()` is called.
 QRScanner.scan(displayContents);
@@ -65,28 +70,40 @@ function displayContents(err, text){
     alert(text);
   }
 }
+
+// Make the webview transparent so the video preview is visible behind it.
+QRScanner.show();
+// Be sure to make any opaque HTML elements transparent here to avoid
+// covering the video.
 ```
 
+Please see the [full API docs](#api) for details about each method, [error handling](#error-handling), and [platform specific details](#platform-specific-details).
+
 ### iOS Installation
 
 This plugin requires some additional installation steps for the iOS platform.
 
-The iOS component of the plugin is written in Swift 2. To enable it, be sure you're running the lastest version of Xcode, then add the following hook to the iOS platform in your Cordova app's `config.xml`:
+The iOS component of the plugin is written in Swift 2.3. To enable it, be sure you're running the lastest version of Xcode, then add the following hook and setting to the iOS platform in your Cordova app's `config.xml`:
 
 ```xml
 <platform name="ios">
     <hook type="before_build" src="plugins/cordova-plugin-qrscanner/scripts/swift-support.js" />
+    <config-file target="*-Info.plist" parent="NSCameraUsageDescription">
+      <string>The camera is used to read QR codes.</string>
+    </config-file>
 </platform>
 ```
 
-This script requires the `xcode` npm module:
+The script requires the `xcode` npm module:
 
 ```bash
 npm install --save xcode
 ```
 
 Swift will now be enabled during your build, and the `QRScanner` plugin will be available in your app.
 
+Starting with iOS 10, the `NSCameraUsageDescription` string is also required to avoid a runtime exit. This field can be provided in a single language, localized using the `InfoPlist.strings` file, or simply left empty (`<string></string>`).
+
 #### Using multiple Cordova plugins written in Swift
 
 Because Cordova is written in Objective-C, Cordova plugins written in Swift [require a `bridging header` to interact with Cordova](https://developer.apple.com/library/ios/documentation/Swift/Conceptual/BuildingCocoaApps/MixandMatch.html).

scripts/swift-support.js

@@ -15,6 +15,7 @@ var
 	xcode = require('xcode'),
 
 	BUILD_VERSION = '7.0',
+	SWIFT_VERSION_XCODE = '2.3',
 	BUILD_VERSION_XCODE = '"' + BUILD_VERSION + '"',
 	RUNPATH_SEARCH_PATHS = '@executable_path/Frameworks',
 	RUNPATH_SEARCH_PATHS_XCODE = '"' + RUNPATH_SEARCH_PATHS + '"',
@@ -132,6 +133,7 @@ module.exports = function (context) {
 			buildSettings.SWIFT_OBJC_BRIDGING_HEADER = swiftBridgingHeadXcode;
 			buildSettings.IPHONEOS_DEPLOYMENT_TARGET = BUILD_VERSION_XCODE;
 			buildSettings.ENABLE_BITCODE = ENABLE_BITCODE_XCODE;
+			buildSettings.SWIFT_VERSION = SWIFT_VERSION_XCODE;
 		});
 
 		// Writing the file again

tests/project/config.xml

@@ -25,6 +25,9 @@
         <preference name="orientation" value="all" />
         <allow-intent href="itms:*" />
         <allow-intent href="itms-apps:*" />
+        <config-file target="*-Info.plist" parent="NSCameraUsageDescription">
+          <string>The test app uses the camera to read QR codes.</string>
+        </config-file>
     </platform>
     <plugin name="cordova-plugin-qrscanner" spec="../../cordova-plugin-qrscanner" />
     <plugin name="cordova-plugin-qrscanner-tests" spec="../../cordova-plugin-qrscanner/tests" />