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

There are a few general and platform-specific dependencies required to integrate BlockID SDK into an iOS application. Developers should take note of the following requirements:

General

An understanding of how to develop applications for iOS
At least one compatible iOS mobile device

Technical

Xcode 13.4.1 or higher
- Deployment target of iOS 13.0 or higher
- Swift 5.5 or higher
Cocoapods 1.10.0 or higher
- Ruby 2.0.0 or higher
Device support
- iPhone 6s or later
- iPod Touch (7th generation) or later

Get Started Immediately

tip

Please request access to our mobile SDK and demo applications by sending us an email at developers@1kosmos.com

Developers can request access to the iOS BlockID Mobile SDK and Demo Application to access the code to get a feel for how the BlockID SDK might be used.

Integration Overview

This section explains the step by step guide on how to set up and integrate the BlockID SDK in an iOS application.

tip

The examples provided below demonstrate the integration steps of the BlockID SDK into a new iOS project

The same steps can also be used for integration into an existing application

Screenshots in this section are generated using Xcode 13.0.

Step 1: Create a New Application

Open Xcode
Select File -> New -> Project
Choose Single View Application template
Press Next

We are using BlockID Demo for our Product Name
Leave all the other settings as default

Press Next and select a location to save your project

Press Create, and the project will be opened as shown below

Step 2: Setup CocoaPods

2.1 Install CocoaPods

Installing the BlockID iOS SDK via CocoaPodsautomates the majority of the installation process for you. Before beginning this process, please ensure that you are using Ruby 2.0.0 or greater.

Open a terminal and issue the following command to install CocoaPods

sudo gem install cocoapods

2.2 Construct the Podfile

Now that you have installed the CocoaPods, the next step is to create an empty file in your Xcode project directory named Podfile

Using the terminal, cd to your BlockID Demo root directory
Run the following command to create a Podfile

touch Podfile

Confirm that the Podfile was created by navigating to the BlockID Demo root

Step 3: Add BlockID SDK

3.1 CocoaPods Integration (Recommended)

note

Installation of BlockID iOS SDK using Cocoapods is supported from version 1.6.00 only

3.1.1 Add BlockID SDK Library

tip

Dummy credentials are shown in the Podfile below. Please replace these with your actual github credentials

Add the following lines to your Podfile:

Podfile
# Set iOS version as per project requirement
# As BlockID SDK support is from iOS 13.0, this example sets the platform OS as 13.0
 platform :ios, '13.0'

target 'BlockID Demo' do
  # Comment the next line if you don't want to use dynamic frameworks
  use_frameworks!

  pod 'BlockID', :git => 'https://{gituser}:{gittoken}@github.com/1KBlockID/ios-blockidsdk.git', :tag => '1.9.40'
  pod 'Web3', :git => 'https://{gituser}:{gittoken}@github.com/Boilertalk/Web3.swift.git', :tag => '0.4.2'
  pod 'WebAuthnKit', :git => 'https://{gituser}:{gittoken}@github.com/1KBlockID/WebAuthnKit-iOS.git', :tag => '2.0.2'
  pod 'EllipticCurveKeyPair', :git => 'https://{gituser}:{gittoken}@github.com/1KBlockID/EllipticCurveKeyPair.git', :tag => '2.0.2
end
end

post_install do |installer|
 installer.pods_project.targets.each do |target|
  target.build_configurations.each do |config|

   # set build active architecture to to YES
    config.build_settings['ONLY_ACTIVE_ARCH'] = 'YES'
  
   # set build library for distribution to true
    config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'

   # enable simulator support
    config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64 i386"

    # set iOS Deployment Target to 13.0
    config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '13.0'
  end
 end
end

note

The BlockID iOS SDK is not published in the public Cocoapod Spec repository. For now, the above installation mechanism must be used

3.1.2 Install BlockID SDK

To install the BlockID SDK as a pod, navigate to the root directory of your BlockID Demo project within your terminal and run the following command:

pod install

note

All BlockID SDK dependencies will be installed at this time

3.2 Manual Integration

BlockID iOS SDK versions 1.9.40 and lower must be installed and integrated manually.

3.2.1 Download BlockID SDK

If currently open, close the BlockID Demo project in Xcode
Using the terminal, clone the latest version of the BlockID SDK using git

git clone https://github.com/1KBlockID/ios-blockidsdk.git

Copy the entire BlockID.xcframework folder to your BlockID Demo root directory

After Pod installation, a new file, BlockID Demo.xcworkspace, will be created. Double-click BlockID Demo.xcworkspace to open the file.
Xcode will open. Select BlockID Demo under Targets and select General -> Frameworks, Libraries and Embedded Content

Click + to add BlockID.xcframework
Once the framework is added, select Embed & Sign for BlockID.framework

The BlockID SDK uses CryptoTokenKit.framework. The framework must be linked as Optional in the application target Build Phase

3.2.2 Add Required Packages

BlockID SDK has dependencies on the following packages:

#	Name	URL	Version Rules
1	Starscream	https://github.com/daltoniam/Starscream	3.1.1 (Exact version)
2	BIDWalletConnect	https://github.com/1KBlockID/WalletConnectSwiftV2	BIDWalletConnect

To add the packages to your application use the following steps:

Open application project settings and navigate to Package Dependencies
Click + sign and add the packages listed above

3.2.3 Add Required Pods

The BlockID SDK has additional dependencies that must be installed. Open the Podfile (created during Step 2.2) and add the following:

Podfile
# Set iOS version as per project requirement
# As BlockID SDK support is from iOS 13.0, this example sets the platform OS as 13.0
platform :ios, '13.0'

target 'BlockID Demo' do
  # Comment the next line if you don't want to use dynamic frameworks
  use_frameworks!

  # Pods for BlockIDTestApp
  pod 'TrustWalletCore', '~> 2.5.6'
  pod 'Alamofire','~> 4.9.1'
  pod 'CryptoSwift', '~> 1.3.8'
  pod 'BigInt', '~> 4.0'
  pod 'SwiftyTesseract', '~> 3.1.3'
  pod 'OpenSSL-Universal', '~> 1.1.180'
  pod 'Toast-Swift', '~> 5.0.1'
  pod 'Web3', :git => 'https://{gituser}:{gittoken}@github.com/Boilertalk/Web3.swift.git', :tag => '0.4.2'
  pod 'WebAuthnKit', :git => 'https://{gituser}:{gittoken}@github.com/1KBlockID/WebAuthnKit-iOS.git', :tag => '2.0.2'
  pod 'EllipticCurveKeyPair', :git => 'https://{gituser}:{gittoken}@github.com/1KBlockID/EllipticCurveKeyPair.git', :tag => '2.0.2
  pod 'DocumentSelfieScanner', :git => 'https://github.com/1KBlockID/ios-supporting-sdks.git', :tag => '4.3.0'
  pod 'YubiKit', '~> 4.2.0'
end

post_install do |installer|
 installer.pods_project.targets.each do |target|
  target.build_configurations.each do |config|

    # set build active architecture to YES
    config.build_settings['ONLY_ACTIVE_ARCH'] = 'YES'

    # set build library for distribution to YES
    config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'

    config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64 i386"
  end
 end
end

3.2.4 Install Pods

To install all the dependent pods, cd to the directory of your Xcode app project within your terminal and run the following command:open:

pod install

Step 4: Enable Bitcode

For iOS apps, bitcode is enabled by default but is optional. The BlockID SDK supports enabling bitcode option in the application.

Step 5: Enable Permissions

Add the following permissions to your 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 6: 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 the + icon. Search for Near Field Communication and add it to the project capabilities

Step 7: Application Deployment

Deploying an iOS application, integrated with BlockID SDK (.xcframework), does not require any additional steps outside of the typical process

Step 8: Run the Application

The setup of the application to include the BlockID SDK is now complete. The project can now be compiled to check for any errors.

tip

Encryption of data takes longer while the app runs in Debug mode. It is recommended (but not mandatory) to change the application scheme to Release before running the application

Initial SDK Setup

caution

In order to use the features of the BlockID SDK, you must add your License Key, Wallet, and Tenant details. This information will be provided with SDK access.

Please contact us at developers@1kosmos.com for access to the SDK

The credentials listed on your Developer Dashboard will not work with the BlockID Mobile SDK

caution

The information must be set using the following sequence only and MUST NOT be changed

Step 1: Set License Key

The license key must be called each time the application is launched. Internally, the SDK checks if:

The given license key is valid
The application is authorized to use the given license key

To set the license key, add the following code in your application:

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

Step 2: Initialize Wallet

Before registering tenant, a temporary application wallet must be created. An application can only have one wallet, hence 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 can be represented as the value or an object on which API calls can be registered.

There are two types of tenants:

Root Tenant: stores details about enrolled user biometric informatiom and digital assets
Client Tenant: stores user's enrolled persona

note

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 only allow a tenant to be registered 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:"<tenant tag>", community: "<community name>", dns: "<tenant DNS>")

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 will be used while enrolling documents, or when getting 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 avaible 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

Because the attack surface of an API is wider than that of a standlone application. the BlockID SDK has implemented a locking mechanism to prevent any kind of unauthorized access.

For security purposes, the points below must be implemented in the application:

SDK should be locked when the application moves into background state
SDK should be locked when application shows login screen to Users
SDK lock status should be checked before calling any enrollment APIs

tip

Refer to the API Reference Guide to get more details on the methods used in this section

Prerequisites​

General​

Technical​

Get Started Immediately​

Integration Overview​

Step 1: Create a New Application​

Step 2: Setup CocoaPods​

2.1 Install CocoaPods​

2.2 Construct the Podfile​

Step 3: Add BlockID SDK​

3.1 CocoaPods Integration (Recommended)​

3.1.1 Add BlockID SDK Library​

3.1.2 Install BlockID SDK​

3.2 Manual Integration​

3.2.1 Download BlockID SDK​

3.2.2 Add Required Packages​

3.2.3 Add Required Pods​

3.2.4 Install Pods​

Step 4: Enable Bitcode​

Step 5: Enable Permissions​

Step 6: Add Near Field Communication Tag​

Step 7: Application Deployment​

Step 8: Run the Application​

Initial SDK Setup​

Step 1: Set License Key​

Step 2: Initialize Wallet​

Step 3: Register Tenant​

3.1 About Tenant​

3.2 Register Tenant​

Step 4: Commit Wallet​

SDK Security​

Prerequisites

General

Technical

Get Started Immediately

Integration Overview

Step 1: Create a New Application

Step 2: Setup CocoaPods

2.1 Install CocoaPods

2.2 Construct the Podfile

Step 3: Add BlockID SDK

3.1 CocoaPods Integration (Recommended)

3.1.1 Add BlockID SDK Library

3.1.2 Install BlockID SDK

3.2 Manual Integration

3.2.1 Download BlockID SDK

3.2.2 Add Required Packages

3.2.3 Add Required Pods

3.2.4 Install Pods

Step 4: Enable Bitcode

Step 5: Enable Permissions

Step 6: Add Near Field Communication Tag

Step 7: Application Deployment

Step 8: Run the Application

Initial SDK Setup

Step 1: Set License Key

Step 2: Initialize Wallet

Step 3: Register Tenant

3.1 About Tenant

3.2 Register Tenant

Step 4: Commit Wallet

SDK Security