iOS integration guide

Requirements
Objective C or Swift 4.0 or higher
Xcode 11 or higher
iOS 11 or higher for integration
iOS 11.2 or higher for using the scanning view controllers
iOS 13 or higher for name and expiration extraction
Demo
We have a repo on github that includes examples of using CardScan with both Cocoapods and Swift Package Manager. Please see that repo for more details.
iPad Support
CardScan defaults to a formSheet for the iPad, which handles all screen orientations and autorotation correctly. However, if you'd like to use CardScan in full screen mode instead, make sure to select the Requires full screen option in your Info.plist file via XCode, or else non-portrait orientations won't work.
Installation
CardScan is available through CocoaPods and Swift Package Manager. With version 2.0 we dropped support for Carthage. If you require Carthage support we suggest moving to Swift Package Manager or reach out and we'll try to work with you.
In our deployments we use XCFrameworks to encapsulate our code and resources. XCFrameworks have the advantage of faster compilation times and simplified bundle management, but if you need source we make it available in our CardScan repo.
CocoaPods
Swift Package Manager
Add the following line to your Podfile:
1
pod 'CardScan'
Copied!
Or if you're using Stripe:
1
pod 'CardScan'
2
pod 'CardScan/Stripe'
Copied!
Next, install the new pod. From a terminal, run:
1
pod install
Copied!
When using Cocoapods, you use the .xcworkspace instead of the .xcodeproj. Again from the terminal, run:
1
open YourProject.xcworkspace
Copied!
Note: The Podfile can specify the iOS platform target to be lower than 11.2. However, as stated in the requirements CardScan will only run on iOS 11.2 or higher.
To use Swift Package Manager, in Xcode add the https://github.com/getbouncer/cardscan-ios.git repo and choose the latest version up to the next major version. For example, if CardScan is on version 2.0.2 then you'd select 2.0.2 - Next Major
Set up permissions
CardScan uses the camera, so you'll need to add an description of camera usage to your Info.plist file:
XCode iOS camera permission
The string you add here will be what CardScan displays to your users when CardScan first prompts them for permission to use the camera.
iOS camera prompt
Alternatively, you can add this permission directly to your Info.plist file:
1
<key>NSCameraUsageDescriptionkey>
2
<string>We need access to your camera to scan your cardstring>
Copied!
Configure CardScan
CardScan can be configured and run through Swift or Objective-C. CardScan requires an API key, which can be generated for your app through the Bouncer API console.
The CardScan SDK will send anonymous stats to Bouncer's servers. This code snippet shows what we send.
Swift
Objective C
Configure the library when your application launches by adding CardScan to your AppDelegate.swift file. If you are planning to use a navigation controller or support rotation, also be sure to add supportedOrientationMaskOrDefault.
1
import UIKit
2
import CardScan
3
​
4
@UIApplicationMain
5
class AppDelegate: UIResponder, UIApplicationDelegate {
6
​
7
    func application(
8
        _ application: UIApplication,
9
        didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?
10
    ) -> Bool {
11
        ScanViewController.configure(apiKey: "<your_api_key_here>") 
12
        // do any other necessary launch configuration
13
        return true
14
    }
15
​
16
    func application(
17
        _ application: UIApplication,
18
        supportedInterfaceOrientationsFor window: UIWindow?
19
    ) -> UIInterfaceOrientationMask {
20
        // if you are planning to embed scanViewController into a navigation
21
        // controller, put this line to handle rotations
22
        return ScanBaseViewController.supportedOrientationMaskOrDefault()
23
    }
24
}
Copied!
Configure the library when your application launches by adding CardScan to your AppDelegate.m file.
1
#import "AppDelegate.h"
2
@import CardScan;
3
​
4
@implementation AppDelegate
5
​
6
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
7
    // if you need to get an API key you can get one from here:
8
    // https://api.getbouncer.com/console
9
    [ScanViewController configureWithApiKey:@"<your_api_key_here>"];
10
    return YES;
11
}
12
​
13
@end
Copied!
Using CardScan
To use CardScan, create a ScanViewController, display it, and implement the ScanDelegate protocol to receive results from the scan.
Swift
Objective C
1
import UIKit
2
import CardScan
3
​
4
class ViewController: UIViewController, ScanDelegate {
5
    override func viewWillAppear() {
6
        super.viewWillAppear()
7
​
8
        // It's important that this goes in viewWillAppear because the user may
9
        // deny permission on the ScanViewController, in which case the button
10
        // must be hidden to avoid future presses.
11
        if !ScanViewController.isCompatible() {
12
            // Hide your "scan card" button because this device isn't compatible
13
            // with CardScan
14
        }
15
    }
16
​
17
    @IBAction func scanCardButtonPressed() {
18
        guard let vc = ScanViewController.createViewController(withDelegate: self) else {
19
            print("This device is incompatible with CardScan")
20
            return
21
        }
22
        self.present(vc, animated: true)
23
    }
24
​
25
    func userDidSkip(_ scanViewController: ScanViewController) {
26
        self.dismiss(animated: true)
27
    }
28
​
29
    func userDidCancel(_ scanViewController: ScanViewController) {
30
        self.dismiss(animated: true)
31
    }
32
​
33
    func userDidScanCard(
34
        _ scanViewController: ScanViewController,
35
        creditCard: CreditCard
36
    ) {
37
        let number = creditCard.number
38
        let expiryMonth = creditCard.expiryMonth
39
        let expiryYear = creditCard.expiryYear
40
​
41
        // If you're using Stripe and you include the CardScan/Stripe pod, you
42
        // can get `STPCardParams` directly from CardScan `CreditCard` objects,
43
        // which you can use with Stripe's APIs
44
        let cardParams = creditCard.cardParams()
45
​
46
        // At this point you have the credit card number and optionally the
47
        // expiry. You can either tokenize the number or prompt the user for
48
        // more information (e.g., CVV) before tokenizing.
49
        self.dismiss(animated: true)
50
    }
51
}
Copied!
1
#import "ViewController.h"
2
@import Stripe;
3
​
4
@interface ViewController ()
5
​
6
@end
7
​
8
@implementation ViewController
9
​
10
- (void)viewDidLoad {
11
    [super viewDidLoad];
12
    if (![ScanViewController isCompatible]) {
13
        // Hide the "scan card" button because this device isn't compatible
14
        // with CardScan       
15
    }
16
}
17
​
18
- (IBAction)scanCardPress:(id)sender {
19
    UIViewController *vc = [ScanViewController createViewControllerWithDelegate:self];
20
    [self presentViewController:vc animated:YES completion:nil];
21
}
22
​
23
- (void)userDidSkip:(ScanViewController * _Nonnull)scanViewController {
24
    [self dismissViewControllerAnimated:YES completion:nil];
25
}
26
​
27
- (void)userDidCancel:(ScanViewController * _Nonnull)scanViewController {
28
    [self dismissViewControllerAnimated:YES completion:nil];
29
}
30
​
31
- (void)userDidScanCard:(ScanViewController * _Nonnull)scanViewController creditCard:(CreditCard * _Nonnull)creditCard {
32
    NSString *number = creditCard.number;
33
    NSString *expiryMonth = creditCard.expiryMonth;
34
    NSString *expiryYear = creditCard.expiryYear;
35
​
36
    // If you're using Stripe and you include the CardScan/Stripe pod, you can
37
    // get `STPCardParams` directly from CardScan `CreditCard` objects, which
38
    // you can use with Stripe's APIs
39
    STPCardParams *cardParams = [creditCard cardParams];
40
​
41
    // At this point you have the credit card number and optionally the expiry.
42
    // You can either tokenize the number or prompt the user for more
43
    // information (e.g., CVV) before tokenizing.
44
    [self dismissViewControllerAnimated:YES completion:nil];
45
}
46
​
47
@end
Copied!
Customizing
This library is built to be customized to fit your UI. See the customization documentation.
Supporting more cards
Though CardScan supports several cards, you may need to add support for cards specific to your business, instructions can be found in the card support docs.
Authors
Sam King, Jaime Park, Zain ul Abi Din, Adam Wushensky, and Andy Li
License
This library is available under paid and free licenses. See the LICENSE file for the full license text.
Quick summary
In short, this library will remain free forever for non-commercial applications, but use by commercial applications is limited to 90 days, after which time a licensing agreement is required. We're also adding some legal liability protections.
After this period commercial applications need to convert to a licensing agreement to continue to use this library.
Details of licensing (pricing, etc) are available at
​https://cardscan.io/pricing, or you can contact
us at [email protected].
More detailed summary
What's allowed under the license:
Free use for any app for 90 days (for demos, evaluations, hackathons, etc).
Contributions (contributors must agree to the
​Contributor License Agreement)
Any modifications as needed to work in your app
What's not allowed under the license:
Commercial applications using the license for longer than 90 days without a
license agreement.
Using us now in a commercial app today? No worries! Just email
​[email protected] and we’ll get you set
up.
Redistribution under a different license
Removing attribution
Modifying logos
Indemnification: using this free software is ‘at your own risk’, so you can’t
sue Bouncer Technologies, Inc. for problems caused by this library
Questions? Concerns?
Please email us at [email protected] or ask us on slack.