> For the complete documentation index, see [llms.txt](https://docs.1kosmos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.1kosmos.com/mobile-sdk/native/ios/integration-guide.md). # Integration Guide This document provides a step-by-step guide to installing, integrating, and initializing the BlockID SDK in any iOS application. ### **Prerequisites** Below are a few general and platform-specific dependencies required to integrate the BlockID SDK into an iOS application. #### General * An understanding of how to develop applications for iOS * At least one compatible iOS mobile device #### Technical * Xcode Version 26.0.1 (17A400) or higher * Deployment target of iOS 16.0 or later * Swift 5.9 or higher * BlockID SDK Integrated via Swift Package Manager starting from V1.30.40 * Device support: * iPhone SE (1st, 2nd, and 3rd generations) * iPhone 6s or later * iPod Touch (7th generation) or later * iPhone Simulator (arm64 or x86\_64) — supported from BlockID SDK V1.30.50+ ### **Integration Overview** This section provides a step-by-step guide on how to set up and integrate the BlockID SDK into an iOS application. The examples below show how to integrate the BlockID SDK into a new iOS project. You can use the same steps to integrate it into an existing application. > **Note:** The screenshots in this section were generated using Xcode 16.0. #### Step 1: Create a New Application 1. Open **Xcode** 2. Select **File -> New -> Project** 3. Choose the **Single View App** template 4. Tap **Next** 5. Set the Product Name to **BlockID Demo**. Leave all other settings at their default values. 6. Tap **Next** and choose a location to save your project. 7. Click **Create**. The project will open automatically, as shown below. #### Step 2: Add BlockID SDK via Swift Package Manager Starting with Release v1.30.40, the BlockID iOS SDK is distributed via Swift Package Manager (SPM). CocoaPods is no longer supported. SPM is built into Xcode, so no separate tool installation (CocoaPods, Ruby) is required. **2.1. Add the package in Xcode** 1. Open your app project in Xcode 2. Go to File → Add Package Dependencies 3. In the search bar, paste the repository URL: 4. Set the Dependency Rule to Exact Version and enter 1.30.60 5. Click Add Package 6. Select the BlockID library, assign it to your app target, and click Add Package 7. After clicking Add Package, Xcode will fetch and resolve all package dependencies 8. You should see the resolved versions in the project navigator under Package Dependencies | Package Resolved | Version | | ---------------- | -------- | | ios-blockidsdk | 1.30.60 | | Alamofire | 5.11.2 | | CryptoSwift | 1.10.0 | | BigInt | 5.7.0 | | OpenSSL | 3.3.3001 | | wallet-core | 4.6.13 | > **Note:** If packages fail to resolve, go to File → Packages → Reset Package Caches, then File → Packages → Resolve Package Versions. > **Note:** All transitive dependencies (Alamofire, CryptoSwift, BigInt, OpenSSL, WalletCore) are resolved automatically by SPM. No manual dependency setup is needed. **2.2. Add the package via Package.swift (SPM-based projects only)** 1. If your app is itself an SPM package, add the dependency to your Package.swift: ``` dependencies: [ .package(url: "https://github.com/1KBlockID/ios-blockidsdk.git", exact: "1.30.60") ] ``` 2. Then add BlockID to your target: ``` .target( name: "YourApp", dependencies: [ .product(name: "BlockID", package: "ios-blockidsdk") ] ) ``` **2.3. Verify the framework is linked** 1. Confirm BlockID appears under Target → General → Frameworks, Libraries, and Embedded Content. 2. Confirm BlockID appears under Target → Build Phases → Link Binary With Libraries. **Step 3: Build and Run** 1. Clean the build folder (Cmd + Shift + K) 2. Build and run on a device ### Migration Guide: CocoaPods to Swift Package Manager If you are already using BlockID SDK via CocoaPods and want to migrate to SPM (required from version 1.30.40 onwards), follow these steps: #### Step 1: Remove BlockID Pod 1. Open your Podfile 2. Remove the BlockID pod line: ``` # REMOVE this line: pod 'BlockID', :git => 'https://github.com/1KBlockID/ios-blockidsdk.git', :tag => '1.30.30' ``` **Scenario A: Your app has OTHER pods** 1. Only remove the BlockID line from Podfile. Keep all other pods. Run: ``` pod install ``` 2. Continue using your .xcworkspace as before. Proceed to Step 2. **Scenario B: BlockID was your ONLY pod** 1. You can fully remove CocoaPods from the project: ``` pod deintegrate pod cache clean --all rm Podfile Podfile.lock rm -rf Pods/ rm -rf YourApp.xcworkspace ``` 2. After this, open the .xcodeproj directly (the .xcworkspace no longer exists). #### Step 2: Add BlockID via SPM 1. Open your project in Xcode 2. Go to File → Add Package Dependencies. 3. In the search bar, paste the repository URL: 4. Set the Dependency Rule to Exact Version and enter 1.30.60 5. Click Add Package 6. Select the BlockID library, assign it to your app target, and click Add Package 7. In the Project Navigator, expand Package Dependencies 8. Confirm you see | Package Resolved | Version | | ---------------- | -------- | | ios-blockidsdk | 1.30.60 | | Alamofire | 5.11.2 | | CryptoSwift | 1.10.0 | | BigInt | 5.7.0 | | OpenSSL | 3.3.3001 | | wallet-core | 4.6.13 | 9. If any package shows an error, run File → Packages → Resolve Package Versions #### Step 3: Verify Target Configuration 1. Confirm BlockID appears under Target → General → Frameworks, Libraries, and Embedded Content. 2. Confirm BlockID appears under Target → Build Phases → Link Binary With Libraries. #### Step 4: Remove Duplicate Framework Entries from OTHER\_LDFLAGS 1. After migration, you may have duplicate framework references in Build Settings. Remove the following entries from OTHER\_LDFLAGS (if present): ``` "-framework", "Alamofire" "-framework", "BigInt" "-framework", "CryptoSwift" "-framework", "OpenSSL" "-framework", "SwiftProtobuf" "-framework", "WalletCore" ``` 2. Go to Target → Build Settings → Other Linker Flags and delete these entries. SPM handles framework linking automatically. #### Step 5: Update Deployment Target The SDK now requires iOS 16.0 minimum. Update your project: * Target → General → Minimum Deployments → set to 16.0 * If you had platform : ios, '15.0' in your Podfile, the new minimum is 16.0 #### Step 6: Clean Build and Run 1. Clean build folder: Cmd + Shift + K 2. Build and run on device ### Troubleshooting Q. If you face issues downloading the package: ``` rm -rf "YourProject.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/configuration" rm "YourProject.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved" ``` Then in Xcode: File → Packages → Reset Package Caches ### Summary of Changes from CocoaPods to SPM Starting with V1.30.40 | Item | Old Value | New Value | | ---------------------------- | ------------------------------------- | ------------------------------------------- | | Dependency manager | CocoaPods 1.16.2+ | Swift Package Manager (built into Xcode) | | iOS deployment target | 15.0 | 16.0 | | Swift version | 5.0 | 5.9 or higher | | SDK version | 1.30.30 | 1.30.40+ | | Integration method | `pod 'BlockID'` in Podfile | Xcode → Add Package Dependencies | | Dependencies handling | `pod install` installs dependent pods | SPM resolves all dependencies automatically | | Ruby requirement | Ruby 2.0.0+ (for CocoaPods) | Not needed — remove this requirement | | `post_install` Podfile block | Required for build settings | Not needed — remove entirely | #### Step 3: Enable Permissions Add the permissions below in the application. Change the value for each key to match your project requirements. ``` // for NFC reading capability during passport scan NFCReaderUsageDescription Allow permission in order to scan your passport // custom message to show during NFC reading NFCUserMessageDuringRFIDScan Hold your iPhone near an NFC enabled passport. // set camera usage description NSCameraUsageDescription Enable camera access to enable Live id and document scanning // set FaceID usage description NSFaceIDUsageDescription Face ID is needed to log in // set location usage description NSLocationAlwaysAndWhenInUseUsageDescription Your current location will be required. // set location usage description NSLocationWhenInUseUsageDescription Your current location will be required. // set photo library usage description NSPhotoLibraryUsageDescription Enable photo libarary to save screenshots // set NFC reading identifier; the value must be same as given here com.apple.developer.nfc.readersession.iso7816.select-identifiers A0000002471001 ``` #### Step 4: Add Near Field Communication Tag Add Near Field Communication tag to the project capability. This is required if the app uses the Passport scan feature. Add the option from the application's Target → Signing & Capabilities and then click on the ‘+’ icon. Search for the option and select the option to add it to the project capabilities. #### Step 5: Application Deployment Deploying an iOS application integrated with the BlockID SDK (.xcframework) does not require any additional steps beyond the typical process. #### Step 6: Run Application The setup of the new application (existing application) to include the BlockID SDK is now complete. The project cannot be compiled to check for errors. > **Note:** The encryption of data takes time while the app runs in Debug mode. It is recommended (not mandatory) to change the application scheme to Release mode and then run the application. ### **Initial SDK Setup** The BlockID SDK has now been added to your application. To access its features, you need to provide the License Key, Wallet, and Tenant details. > **Note:** To access the SDK, reach out to your 1Kosmos representative. > **Caution:** The information must be set in the following sequence only and MUST NOT be changed. #### Step 1: Set License Key > **Tip:** The license key must be set each time the application is launched. Whenever the license key is set, the SDK internally checks whether: * the given license key is valid * the application is authorized to use the provided license key Add the following code to your application to set the license key: ```jsx BlockIDSDK.sharedInstance.setLicenseKey(key: "") ``` #### Step 2: Initialize Wallet Before registering a tenant, create a temporary application wallet. An application can have only one wallet, so create the temporary wallet only **once**. Add the following code to initialize a temporary wallet: ```shell BlockIDSDK.sharedInstance.initiateTempWallet() { (status, error) in //your code here } ``` #### Step 3: Register Tenant **3.1 About Tenant** The tenant represents the value or object on which API calls can be registered. There are two types of tenants: * **Root Tenant**: Stores details about enrolled users' biometric information and digital assets. * **Client Tenant**: Stores the user's enrolled persona. A root tenant can also store a user's persona, but a client tenant cannot be used to store biometric data or digital assets. The application should register a tenant only once. If an existing tenant is set, the application will load it after validating the license key. The SDK will allow a tenant to be registered only after the license key is set. The tenant object is represented using the BIDTenant class and can be created using the following code: ```shell let defaultTenant = BIDTenant.makeTenant(tag:"your_tenant_tag", community: "your_community", dns: "your_dns_url") ``` **3.2 Register Tenant** After the object `BIDTenant`is created, the tenant registration API must be called: ```shell BlockIDSDK.sharedInstance.registerTenant(tenant: BIDTenant) { (status, error, tenant) in // your code here } ``` The tenant details are used during document enrollment and when retrieving a public key. When this function executes, it creates an Ethereum wallet and makes a Distributed Identifier (DID) and 12 recovery mnemonic phrases available to the user. #### Step 4: Commit Wallet After successful tenant registration, call the commit wallet method. The method must be called **only once**: ```shell BlockIDSDK.sharedInstance.commitApplicationWallet() ``` The commit wallet method is the final step for setting up BlockID SDK in an iOS application. ### SDK Security As the attack surface of an API is broader than that of a standalone application, the BlockID SDK implements a locking mechanism to prevent unauthorized access. For security purposes, the following points must be implemented in the application: * Lock the SDK * When the application moves to the background. * When the application displays the login screen. * The SDK’s lock status should be checked before calling any enrollment APIs. > **Tip:** For more information on methods used in this section, see the API Reference Guide. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.1kosmos.com/mobile-sdk/native/ios/integration-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.