Native Integration Guide

This document provides a step-by-step guide on how to install, integrate and initialize the BlockID SDK into any iOS application.

Prerequisites

Below are few general and platform specific dependencies required to integrate 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 demonstrate the integration of the BlockID SDK into a new iOS project. The same steps can also be used for integrating 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: https://github.com/1KBlockID/ios-blockidsdk.git

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: https://github.com/1KBlockID/ios-blockidsdk.git

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 below permissions in the application. The value for each key must be changed as per your project requirement

// for NFC reading capability during passport scan
<key>NFCReaderUsageDescription</key>
<string>Allow permission in order to scan your passport</string>

// custom message to show during NFC reading
<key>NFCUserMessageDuringRFIDScan</key>
<string>Hold your iPhone near an NFC enabled passport.</string>

// set camera usage description
<key>NSCameraUsageDescription</key>
<string>Enable camera access to enable Live id and document scanning</string>

// set FaceID usage description
<key>NSFaceIDUsageDescription</key>
<string>Face ID is needed to log in</string>

// set location usage description
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Your current location will be required.</string>

// set location usage description
<key>NSLocationWhenInUseUsageDescription</key>
<string>Your current location will be required.</string>

// set photo library usage description
<key>NSPhotoLibraryUsageDescription</key>
<string>Enable photo libarary to save screenshots</string>

// set NFC reading identifier; the value must be same as given here
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
  <string>A0000002471001</string>
</array>

Step 4: Add Near Field Communication Tag

Add Near Field Communication tag to the project capability. This is required if application will use Passport scan feature. Add the option from application's Target → Signing & Capabilities and then click on ‘+’ 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 BlockID SDK (.xcframework), does not require any additional steps outside of the typical process.

Step 6: Run Application

The setup of new application (existing application) to include BlockID SDK is now complete. The project cannot be compiled to check if there are any errors or not.

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:

BlockIDSDK.sharedInstance.setLicenseKey(key: "<your_license_key>")

Step 2: Initialize Wallet

Before registering a tenant, a temporary application wallet must be created. An application can only have one wallet, so the temporary wallet must be created ONLY once.

Add the following code to initialize a temporary wallet:

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 user 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 is expected to 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:

let defaultTenant = BIDTenant.makeTenant(tag:"your_tenant_tag", community: "your_community", dns: "your_dns_url")

3.2 Register Tenant

After the object BIDTenantis created the tenant registration API must be called:

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 is executed, an Ethereum wallet is created, and a Distributed Identifier (DID) along with 12 recovery mnemonic phrases will be made available to the user.

Step 4: Commit Wallet

Upon successful tenant registration, the commit wallet method must be called. The method must be called only once:

BlockIDSDK.sharedInstance.commitApplicationWallet()

The commit wallet method is the final step for setting up BlockID SDK into 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:

• The SDK should be locked when the application moves to the background.
• The SDK should be locked when the application displays the login screen to users.
• 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.