Release 4.0.0

CardIO.podspec

@@ -1,14 +1,14 @@
 Pod::Spec.new do |spec|
   spec.name             = 'CardIO'
-  spec.version          = '3.10.1'
+  spec.version          = '4.0.0'
   spec.license          = { type: 'MIT', file: 'LICENSE.md' }
   spec.homepage         = 'https://www.card.io'
   spec.authors          = { 'CardIO' => '[email protected]' }
   spec.summary          = 'Credit card scanning for mobile apps'
   spec.social_media_url = 'https://twitter.com/cardio'
   spec.source           = { :git => 'https://github.com/card-io/card.io-iOS-SDK.git', :tag => "#{spec.version}" }
-  spec.platform         = :ios, '6.0'
-  spec.ios.deployment_target = '6.0'
+  spec.platform         = :ios, '6.1'
+  spec.ios.deployment_target = '6.1'
   spec.requires_arc     = true
   spec.source_files     = 'CardIO/*.h'
   spec.preserve_path    = 'CardIO/*.a'

CardIO/CardIO.h

@@ -1,8 +1,8 @@
 //
 //  CardIO.h
-//  Version 3.10.1
+//  Version 4.0.0
 //
-//  Copyright (c) 2011-2014 PayPal. All rights reserved.
+//  See the file "LICENSE.md" for the full license governing this code.
 //
 
 // All-in-one header file for card.io sdk.
@@ -11,3 +11,4 @@
 #import "CardIOViewDelegate.h"
 #import "CardIOPaymentViewController.h"
 #import "CardIOPaymentViewControllerDelegate.h"
+#import "CardIOUtilities.h"

CardIO/CardIOCreditCardInfo.h

@@ -1,8 +1,8 @@
 //
 //  CardIOCreditCardInfo.h
-//  Version 3.10.1
+//  Version 4.0.0
 //
-//  Copyright (c) 2011-2014 PayPal. All rights reserved.
+//  See the file "LICENSE.md" for the full license governing this code.
 //
 
 #import <Foundation/Foundation.h>
@@ -62,6 +62,8 @@ typedef NS_ENUM(NSInteger, CardIOCreditCardType) {
 /// Was the card number scanned (as opposed to entered manually)?
 @property(nonatomic, assign, readwrite) BOOL scanned;
 
+/// The rectified card image; usually 428x270.
+@property(nonatomic, strong, readwrite) UIImage *cardImage;
 
 /// Derived from cardNumber.
 /// @note CardIOCreditInfo objects returned by either of the delegate methods

CardIO/CardIODetectionMode.h

@@ -0,0 +1,18 @@
+//
+//  CardIODetectionMode.h
+//  Version 4.0.0
+//
+//  See the file "LICENSE.md" for the full license governing this code.
+//
+//
+
+#ifndef icc_CardIODetectionMode_h
+#define icc_CardIODetectionMode_h
+
+typedef NS_ENUM(NSInteger, CardIODetectionMode) {
+  CardIODetectionModeCardImageAndNumber = 0,
+  CardIODetectionModeCardImageOnly,
+  CardIODetectionModeAutomatic
+};
+
+#endif

CardIO/CardIOPaymentViewController.h

@@ -1,12 +1,13 @@
 //
 //  CardIOPaymentViewController.h
-//  Version 3.10.1
+//  Version 4.0.0
 //
-//  Copyright (c) 2011-2014 PayPal. All rights reserved.
+//  See the file "LICENSE.md" for the full license governing this code.
 //
 
 #import <UIKit/UIKit.h>
 #import "CardIOPaymentViewControllerDelegate.h"
+#import "CardIODetectionMode.h"
 
 /// CardIOPaymentViewController is one of two main entry points into the card.io SDK.
 /// @see CardIOView
@@ -38,7 +39,7 @@
 /// E.g., specifying "en" on a device set to "English" and "United Kingdom" will result in "en_GB".
 ///
 /// These localizations are currently included:
-/// ar,da,de,en,en_AU,en_GB,en_SE,es,es_MX,fr,he,is,it,ja,ko,ms,nb,nl,pl,pt,pt_BR,ru,sv,th,tr,zh-Hans,zh-Hant,zh-Hant_TW.
+/// ar,da,de,en,en_AU,en_GB,en_SE,es,es_MX,fr,he,it,ja,ko,ms,nb,nl,pl,pt,pt_BR,ru,sv,th,tr,zh-Hans,zh-Hant,zh-Hant_TW.
 @property(nonatomic, copy, readwrite) NSString *languageOrLocale;
 
 /// If YES, the status bar's style will be kept as whatever your app has set it to.
@@ -80,6 +81,40 @@
 /// Mask the card number digits as they are manually entered by the user. Defaults to NO.
 @property(nonatomic, assign, readwrite) BOOL maskManualEntryDigits;
 
+/// Set the scan instruction text. If nil, use the default text. Defaults to nil.
+/// Use newlines as desired to control the wrapping of text onto multiple lines.
+@property(nonatomic, copy, readwrite) NSString *scanInstructions;
+
+/// Hide the PayPal or card.io logo in the scan view. Defaults to NO.
+@property(nonatomic, assign, readwrite) BOOL hideCardIOLogo;
+
+/// A custom view that will be overlaid atop the entire scan view. Defaults to nil.
+/// If you set a scanOverlayView, be sure to:
+///
+///   * Consider rotation. Be sure to test on the iPad with rotation both enabled and disabled.
+///     To make rotation synchronization easier, whenever a scanOverlayView is set, and card.io does an
+///     in-place rotation (rotates its UI elements relative to their containers), card.io will generate
+///     rotation notifications; see CardIOScanningOrientationDidChangeNotification
+///     and associated userInfo key documentation below.
+///     As with UIKit, the initial rotation is always UIInterfaceOrientationPortrait.
+///
+///   * Be sure to pass touches through to the superview as appropriate. Note that the entire camera
+///     preview responds to touches (triggers refocusing). Test the light button and the toolbar buttons.
+///
+///   * Minimize animations, redrawing, or any other CPU/GPU/memory intensive activities
+@property(nonatomic, retain, readwrite) UIView *scanOverlayView;
+
+/// CardIODetectionModeCardImageAndNumber: the scanner must successfully identify the card number.
+/// CardIODetectionModeCardImageOnly: don't scan the card, just detect a credit-card-shaped card.
+/// CardIODetectionModeAutomatic: start as CardIODetectionModeCardImageAndNumber, but fall back to
+///        CardIODetectionModeCardImageOnly if scanning has not succeeded within a reasonable time.
+/// Defaults to CardIODetectionModeCardImageAndNumber.
+///
+/// @note Images returned in CardIODetectionModeCardImageOnly mode may be less focused, to accomodate scanning
+///       cards that are dominantly white (e.g., the backs of drivers licenses), and thus
+///       hard to calculate accurate focus scores for.
+@property(nonatomic, assign, readwrite) CardIODetectionMode detectionMode;
+
 /// Set to NO if you don't need to collect the card expiration. Defaults to YES.
 @property(nonatomic, assign, readwrite) BOOL collectExpiry;
 
@@ -104,36 +139,33 @@
 
 /// Set to YES to prevent card.io from showing its "Enter Manually" button. Defaults to NO.
 ///
-/// @note If +canReadCardWithCamera returns false, then if card.io is presented it will
+/// @note If [CardIOUtilities canReadCardWithCamera] returns false, then if card.io is presented it will
 ///       automatically display its manual entry screen.
 ///       Therefore, if you want to prevent users from *ever* seeing card.io's manual entry screen,
-///       you should first check +canReadCardWithCamera before initing the view controller.
+///       you should first check [CardIOUtilities canReadCardWithCamera] before initing the view controller.
 @property(nonatomic, assign, readwrite) BOOL disableManualEntryButtons;
 
 /// Access to the delegate.
 @property(nonatomic, weak, readwrite) id<CardIOPaymentViewControllerDelegate> paymentDelegate;
 
-/// The preload method prepares card.io to launch faster. Calling preload is optional but suggested.
-/// On an iPhone 5S, for example, preloading makes card.io launch ~400ms faster.
-/// The best time to call preload is when displaying a view from which card.io might be launched;
-/// e.g., inside your view controller's viewWillAppear: method.
-/// preload works in the background; the call to preload returns immediately.
-/// The preload method of CardIOPaymentViewController and of CardIOView do the same work,
-/// so a call to either of them suffices.
-+ (void)preload;
-
-/// Determine whether this device supports camera-based card scanning, considering
-/// factors such as hardware support and OS version.
+/// Name for orientation change notification.
+extern NSString * const CardIOScanningOrientationDidChangeNotification;
+
+/// userInfo key for orientation change notification, to get the current scanning orientation.
 ///
-/// card.io automatically provides manual entry of cards as a fallback,
-/// so it is not typically necessary for your app to check this.
+/// Returned as an NSValue wrapping a UIDeviceOrientation. Sample extraction code:
+/// @code
+///     NSValue *wrappedOrientation = notification.userInfo[CardIOCurrentScanningOrientation];
+///     UIDeviceOrientation scanningOrientation = UIDeviceOrientationPortrait; // set a default value just to be safe
+///     [wrappedOrientation getValue:&scanningOrientation];
+///     // use scanningOrientation...
+/// @endcode
+extern NSString * const CardIOCurrentScanningOrientation;
+
+/// userInfo key for orientation change notification, to get the duration of the card.io rotation animations.
 ///
-/// @return YES iff the user's device supports camera-based card scanning.
-+ (BOOL)canReadCardWithCamera;
-
-/// Please send the output of this method with any technical support requests.
-/// @return Human-readable version of this library.
-+ (NSString *)libraryVersion;
+/// Returned as an NSNumber wrapping an NSTimeInterval (i.e. a double).
+extern NSString * const CardIOScanningOrientationAnimationDuration;
 
 
 #pragma mark - Deprecated properties

CardIO/CardIOPaymentViewControllerDelegate.h

@@ -1,8 +1,8 @@
 //
 //  CardIOPaymentViewControllerDelegate.h
-//  Version 3.10.1
+//  Version 4.0.0
 //
-//  Copyright (c) 2011-2014 PayPal. All rights reserved.
+//  See the file "LICENSE.md" for the full license governing this code.
 //
 
 #import <Foundation/Foundation.h>

CardIO/CardIOUtilities.h

@@ -0,0 +1,37 @@
+//
+//  CardIOUtilities.h
+//  Version 4.0.0
+//
+//  See the file "LICENSE.md" for the full license governing this code.
+//
+
+#import <Foundation/Foundation.h>
+#import <UIKit/UIKit.h>
+
+@interface CardIOUtilities : NSObject
+
+/// Please send the output of this method with any technical support requests.
+/// @return Human-readable version of this library.
++ (NSString *)libraryVersion;
+
+/// Determine whether this device supports camera-based card scanning, considering
+/// factors such as hardware support and OS version.
+///
+/// card.io automatically provides manual entry of cards as a fallback,
+/// so it is not typically necessary for your app to check this.
+///
+/// @return YES iff the user's device supports camera-based card scanning.
++ (BOOL)canReadCardWithCamera;
+
+/// The preload method prepares card.io to launch faster. Calling preload is optional but suggested.
+/// On an iPhone 5S, for example, preloading makes card.io launch ~400ms faster.
+/// The best time to call preload is when displaying a view from which card.io might be launched;
+/// e.g., inside your view controller's viewWillAppear: method.
+/// preload works in the background; the call to preload returns immediately.
++ (void)preload;
+
+/// Returns a doubly Gaussian-blurred screenshot, intended for screenshots when backgrounding.
+/// @return Blurred screenshot.
++ (UIImageView *)blurredScreenImageView;
+
+@end

CardIO/CardIOView.h

@@ -1,36 +1,23 @@
 //
 //  CardIOView.h
-//  Version 3.10.1
+//  Version 4.0.0
 //
-//  Copyright (c) 2011-2014 PayPal. All rights reserved.
+//  See the file "LICENSE.md" for the full license governing this code.
 //
 
 #import <UIKit/UIKit.h>
 #import "CardIOViewDelegate.h"
+#import "CardIODetectionMode.h"
 
 /// CardIOView is one of two main entry points into the card.io SDK.
 /// @see CardIOPaymentViewController
 @interface CardIOView : UIView
 
-/// Determine whether this device supports camera-based card scanning, considering
-/// factors such as hardware support and OS version.
-/// @return YES iff the user's device supports camera-based card scanning.
-+ (BOOL)canReadCardWithCamera;
-
-/// The preload method prepares card.io to launch faster. Calling preload is optional but suggested.
-/// On an iPhone 5S, for example, preloading makes card.io launch ~400ms faster.
-/// The best time to call preload is when displaying a view from which card.io might be launched;
-/// e.g., inside your view controller's viewWillAppear: method.
-/// preload works in the background; the call to preload returns immediately.
-/// The preload method of CardIOPaymentViewController and of CardIOView do the same work,
-/// so a call to either of them suffices.
-+ (void)preload;
-
 
 #pragma mark - Properties you MUST set
 
 /// Typically, your view controller will set itself as this delegate.
-@property(nonatomic, strong, readwrite) id<CardIOViewDelegate> delegate;
+@property(nonatomic, weak, readwrite) id<CardIOViewDelegate> delegate;
 
 
 #pragma mark - Properties you MAY set
@@ -47,7 +34,7 @@
 /// E.g., specifying "en" on a device set to "English" and "United Kingdom" will result in "en_GB".
 ///
 /// These localizations are currently included:
-/// ar,da,de,en,en_AU,en_GB,en_SE,es,es_MX,fr,he,is,it,ja,ko,ms,nb,nl,pl,pt,pt_BR,ru,sv,th,tr,zh-Hans,zh-Hant,zh-Hant_TW.
+/// ar,da,de,en,en_AU,en_GB,en_SE,es,es_MX,fr,he,it,ja,ko,ms,nb,nl,pl,pt,pt_BR,ru,sv,th,tr,zh-Hans,zh-Hant,zh-Hant_TW.
 @property(nonatomic, copy, readwrite) NSString *languageOrLocale;
 
 /// Alter the card guide (bracket) color. Opaque colors recommended.
@@ -64,13 +51,66 @@
 /// Set to NO to follow standard iOS constraints. Defaults to YES. (Does not affect the manual entry screen.)
 @property(nonatomic, assign, readwrite) BOOL allowFreelyRotatingCardGuide;
 
+/// Set the scan instruction text. If nil, use the default text. Defaults to nil.
+/// Use newlines as desired to control the wrapping of text onto multiple lines.
+@property(nonatomic, copy, readwrite) NSString *scanInstructions;
+
+/// Hide the PayPal or card.io logo in the scan view. Defaults to NO.
+@property(nonatomic, assign, readwrite) BOOL hideCardIOLogo;
+
+/// A custom view that will be overlaid atop the entire scan view. Defaults to nil.
+/// If you set a scanOverlayView, be sure to:
+///
+///   * Consider rotation. Be sure to test on the iPad with rotation both enabled and disabled.
+///     To make rotation synchronization easier, whenever a scanOverlayView is set, and card.io does an
+///     in-place rotation (rotates its UI elements relative to their containers), card.io will generate
+///     rotation notifications; see CardIOScanningOrientationDidChangeNotification
+///     and associated userInfo key documentation below.
+///     As with UIKit, the initial rotation is always UIInterfaceOrientationPortrait.
+///
+///   * Be sure to pass touches through to the superview as appropriate. Note that the entire camera
+///     preview responds to touches (triggers refocusing). Test the light button and the toolbar buttons.
+///
+///   * Minimize animations, redrawing, or any other CPU/GPU/memory intensive activities
+@property(nonatomic, retain, readwrite) UIView *scanOverlayView;
+
+/// CardIODetectionModeCardImageAndNumber: the scanner must successfully identify the card number.
+/// CardIODetectionModeCardImageOnly: don't scan the card, just detect a credit-card-shaped card.
+/// CardIODetectionModeAutomatic: start as CardIODetectionModeCardImageAndNumber, but fall back to
+///        CardIODetectionModeCardImageOnly if scanning has not succeeded within a reasonable time.
+/// Defaults to CardIODetectionModeCardImageAndNumber.
+///
+/// @note Images returned in CardIODetectionModeCardImageOnly mode may be less focused, to accomodate scanning
+///       cards that are dominantly white (e.g., the backs of drivers licenses), and thus
+///       hard to calculate accurate focus scores for.
+@property(nonatomic, assign, readwrite) CardIODetectionMode detectionMode;
+
 /// After a successful scan, the CardIOView will briefly display an image of the card with
 /// the computed card number superimposed. This property controls how long (in seconds)
 /// that image will be displayed.
 /// Set this to 0.0 to suppress the display entirely.
 /// Defaults to 1.0.
 @property(nonatomic, assign, readwrite) CGFloat scannedImageDuration;
 
+/// Name for orientation change notification.
+extern NSString * const CardIOScanningOrientationDidChangeNotification;
+
+/// userInfo key for orientation change notification, to get the current scanning orientation.
+///
+/// Returned as an NSValue wrapping a UIDeviceOrientation. Sample extraction code:
+/// @code
+///     NSValue *wrappedOrientation = notification.userInfo[CardIOCurrentScanningOrientation];
+///     UIDeviceOrientation scanningOrientation = UIDeviceOrientationPortrait; // set a default value just to be safe
+///     [wrappedOrientation getValue:&scanningOrientation];
+///     // use scanningOrientation...
+/// @endcode
+extern NSString * const CardIOCurrentScanningOrientation;
+
+/// userInfo key for orientation change notification, to get the duration of the card.io rotation animations.
+///
+/// Returned as an NSNumber wrapping an NSTimeInterval (i.e. a double).
+extern NSString * const CardIOScanningOrientationAnimationDuration;
+
 
 #pragma mark - Property you MAY get
 

CardIO/CardIOViewDelegate.h

@@ -1,8 +1,8 @@
 //
 //  CardIOViewDelegate.h
-//  Version 3.10.1
+//  Version 4.0.0
 //
-//  Copyright (c) 2011-2014 PayPal. All rights reserved.
+//  See the file "LICENSE.md" for the full license governing this code.
 //
 
 #import <Foundation/Foundation.h>

LICENSE.md

@@ -2,7 +2,7 @@ All header files are released under the MIT License:
 
     The MIT License (MIT)
 
-    Copyright (c) 2013-2014 PayPal
+    Copyright (c) 2013-2014 eBay Software Foundation
 
     Permission is hereby granted, free of charge, to any person obtaining a copy
     of this software and associated documentation files (the "Software"), to deal