# 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:
```
# Define source and destination paths
FRAMEWORK_NAME="CardknoxPaymentsSDK"
ICU_FILE_NAME="icudt.dat"
SRC_PATH="${TARGET_BUILD_DIR}/${FRAMEWORKS_FOLDER_PATH}/${FRAMEWORK_NAME}.framework/${ICU_FILE_NAME}"
DST_PATH="${TARGET_BUILD_DIR}/${UNLOCALIZED_RESOURCES_FOLDER_PATH}/${ICU_FILE_NAME}"
echo "Copying ${ICU_FILE_NAME} from ${SRC_PATH} to ${DST_PATH}"
# Check if file exists
if [ -f "$SRC_PATH" ]; then
cp "$SRC_PATH" "$DST_PATH"
echo "✅ Successfully copied ${ICU_FILE_NAME} to main bundle"
else
echo "❌ ICU file not found at: ${SRC_PATH}"
exit 1
fi
```
## 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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.solapayments.com/sdk/ios-sdk/ios-sdk.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.