iOS SDK - Technical Guide

Overview

This document helps developers to set up and integrate Cardknox Payments SDK into 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. Obtain and place the downloaded .framework file to the root of your project (for example, alongside the xcodeproj file):

   
2. 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.

   
3. + 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....

4. Add files... opens Choose frameworks and libraries to add dialog. On dialog find the root folder of the project and select CardknoxPaymentsSDK.framework file.

   
5. 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.

   
6. 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.

   

SkiaSharp dependency

The goal is to reference the libSkiaSharp.framework. It can be found in the CardknoxPaymentsSDK.framework/Frameworks folder. Repeat the same steps for libSkiaSharp.framework integration.

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}"

Globalization File

1. The SDK contains a file icudt.dat. This file is used by the dotnet runtime to configure globalization. Our SDK is using the en-US culture to format currency symbols, amount delimiters, etc.. This means the SDK is “culture sensitive” or “culture variant”.

2. dotnet runtime will look for the icudt.dat file in the “main bundle” which is the Swift app where the SDK is a guest. Therefor our goal is to copy the icudt.dat into the final application archive in XCode, whenever the app builds.

3. Define a new Run Script phase for your application Target in XCode

4. Input the following code:

CardknoxPaymentsSDK headers import

This section shows how to use the CardknoxPaymentsSDK in Swift code. 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 from Template... 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 iOS.Swift.SampleApp/iOS.Swift.SampleApp-Bridging-Header.h path specified. The assumption here is that the header file is in the Target folder, alongside the Info.plist file.