iOS SDK - Technical Guide

Overview

This document helps developers to set up and integrate Cardknox Payments SDK into Objective C and Swift projects. The document contains steps for framework integration, required settings setup and import of SDK headers.

Technical Overview

• The SDK is distributed as a .framework

• .framework contains the CardknoxPaymentsSDK binary and ObjectiveC .h headers describing the SDK API

• The CardknoxPaymentsSDK does not contain bitcode and cannot be integrated with applications that require bitcode

• .framework only supports arm64 64-bit architecture for device builds. Simulator targets are not supported.

• SDK minimum deployment target is 14.0

Framework File Integration

1. Download the zip file with CardknoxPaymentsSDK.framework. Links for downloading framework files can find in iOS SDK - Get Started section.

2. Extract CardknoxPaymentsSDK.framework from downloaded .zip file.

3. Copy the downloaded .framework file to the root of your project (for example, alongside the xcodeproj file):
4. Open the General under the application Target. Find the Frameworks, Libraries, and Embedded Content section. Click on the + icon for adding a framework to the project.
5. + icon opens the dialog screen for adding framework. On dialog click on Add Other dropbox, which opens a menu. On the menu click on Add files...
6. Add files... opens Choose frameworks and libraries to add dialog. On dialog find the root folder of the project and select CardknoxPaymentsSDK.framework file.
7. After adding the framework, the CardknoxPaymentsSDK.framework must be in the Frameworks, Libraries, and Embedded Content section. Pay attention to the value in the Embed column. The value must be Embed & Sign.
8. Also after adding the framework, the CardknoxPaymentsSDK.framework must be in Link Binary With Libraries and Embed Frameworks sections. Link Binary With Libraries and Embed Frameworks sections are in the Build Phases tab, under the application Target.

Required Settings Setup

Disabling Bitcode

The Cardknox SDK doesn’t support bitcode. To disable Bitcode follow these steps:

1. Click on your application target. Choose Build Settings > All

2. Set the Enable Bitcode option to No in the Build Options section

Info.plist merge

1. The CardknoxPaymentsSDK framework contains an Info.plist file which contains various key/value pairs that are required by the framework, for example, it defines a NSBluetoothAlwaysUsageDescription key with a value similar to “Bluetooth is required to find, connect to and transfer data between a card reader and the app"

2. The application that is using the CardknoxPaymentsSDK framework also defines an Info.plist file with its own key/value pairs

3. The goal is to merge the framework Info.plist file with the application Info.plist in order to avoid runtime errors in the CardknoxPaymentsSDK framework code due to missing key/values. XCode doesn't perform any merges automatically.

4. Note that if there are identical keys present in the application Info.plist and in the framework Info.plist files, such as the NSBluetoothAlwaysUsageDescription key; the value defined in the application Info.plist for that key will have priority during the merge; making it easy to override values in the framework Info.plist

5. To merge the two files, define a Run Script step in the XCode application Target's Build Phases section and run the PlistBuddy tool, as following:

   • Add a new Run Script step to Build Phases
   • Make sure that the Run Script step is the last step, below other steps (Compile Sources, Embed Frameworks, etc.). You can reposition steps by dragging up and down:
   • Expand the Run Script step
   • Delete the Type a script... contents of the input box and add the following command

     • /usr/libexec/PlistBuddy -c "merge CardknoxPaymentsSDK.framework/Info.plist" "${TARGET_BUILD_DIR}/${INFOPLIST_PATH}"

CardknoxPaymentsSDK headers import

This section shows how to use the CardknoxPaymentsSDK in Objective C and Swift code. For Objective C it’s sufficient to reference the main SDK header. For Swift, an umbrella header is required to wrap the main SDK header into a Swift compatible format.

Objective C import

For Objective C applications - reference the CardknoxPaymentsSDK main header file in your code with #import "CardknoxPaymentsSDK/CardknoxPaymentsSDK.h"

Swift import

For Swift applications - an umbrella header needs to be created and referenced by your application Target in order to properly embed the framework into your app. To create the umbrella header, follow the steps:

1. Create a new header file in the Target folder via File menu > New... > File.... Choose Header File option. For example, the name might be: iOS.Swift.SampleApp-Bridging-Header.h
2. Clear all text in the header file

3. Add #import "CardknoxPaymentsSDK/CardknoxPaymentsSDK.h" into the header file
4. Navigate to your target’s Build Settings > All

5. Find the Objective-C Bridging Header option in the Swift Compiler - General section and set its value to be the relative path to the header file. For example, an application target named iOS.Swift.SampleApp will have the iOS.Swift.SampleApp/iOS.Swift.SampleApp-Bridging-Header.h path specified. The assumption is that the header file is in the Target folder, side by side the info.plist file.