Get started (iOS SDK)

Prerequisites

To use our iOS SDK for Swift, you need:

1. Apple Developer tools
2. An active UI key from the Embedder Portal
3. Weavr iOS SDK for Swift

Latest version

3.8.1

Compatibility

• Minimum iOS: 15.1
• Swift toolchain: 5.9 or later
• Xcode: 16 minimum, 26 or later recommended
• The device must support push notifications and biometric authentication

See all versions →

Install Xcode

Install Apple's Xcode IDE from the Mac App Store. See Xcode resources on Apple's developer portal for more information.

Verify your Swift version:

$ swift --version
swift-driver version: 1.87.1 Apple Swift version 5.9 (swiftlang-5.9.0.128.108 clang-1500.0.40.1) Target: x86_64-apple-macosx14.0

Install

You can install our iOS SDK via Swift Package Manager (recommended) or CocoaPods.

Swift Package Manager

To install our Secure Components iOS SDK using Swift Package Manager (SPM):

1. Open your Xcode project.

2. Navigate to File > Add Packages...

3. In the search bar, enter the following URL:

   https://github.com/weavr-io/secure-components-ios.git

4. Select the version you wish to use. We adhere to Semantic versioning and so recommend using the Up to next major version dependency rule.
5. Click Add Package to integrate the SDK into your project, and select the target where you want to add the SDK.

CocoaPods

CocoaPods is a dependency management service for Objective-C and Swift Projects. For more information about installation and usage, visit the CocoaPods guides. To integrate Weavr iOS SDK into your Xcode project, specify in your Podfile.

Podfile

source 'https://cdn.cocoapods.org/'
source 'https://github.com/sumsub/Specs.git'

use_frameworks! : linkage => :dynamic          # Required by Approov

pod 'ApproovURLSession', '~> 3.3.3'            # Approov for secure mobile API protection
pod 'WeavrComponents', '~> 3.0'                # Weavr SDK for biometric authentication and UI components - check the latest version on GitHub
pod 'IdensicMobileSDK', '~> 1.41.0'            # Sumsub SDK for identity verification
pod 'Firebase/Analytics'                       # Firebase analytics
pod 'Firebase/Core'                            # Core Firebase functionality
pod 'Firebase/Messaging'                       # Firebase Cloud Messaging for push notifications
pod 'FirebaseAppCheck'                         # Firebase App Check for device integrity verification

The minimum supported iOS deployment target is iOS 15.1 - ensure your Podfile includes platform :ios, '15.1' or higher.

If you have any issues with pod:

1. Check and update your pod version.
2. Add the following pod hook in your podfile:

Podfile

post_install do |installer|
  installer.pods_project.targets.each do |target|
     target.build_configurations.each do |config|
        config.build_settings['ONLY_ACTIVE_ARCH'] = 'NO'
     end
  end
end

Permissions

You must add the following usage descriptions in your Info.plist:

• NSPhotoLibraryUsageDescription - Required so the user can select a picture of themselves or their identification documents (e.g. passport) from their photo library.
• NSCameraUsageDescription - Required so the user can take a picture of themselves or their identification documents (e.g. passport).
• NSMicrophoneUsageDescription - Required during the KYCKYC (Know Your Customer). Know Your Customer - the identity verification process for consumer customers. This process allows you to securely verify your user's identity. Weavr asks users to submit the information and documentation they need for approval by financial providers. flow.
• NSLocationWhenInUseUsageDescription - To validate the location the user is in while performing the KYCKYC (Know Your Customer). Know Your Customer - the identity verification process for consumer customers. This process allows you to securely verify your user's identity. Weavr asks users to submit the information and documentation they need for approval by financial providers. flow.
• NSFaceIDUsageDescription - Required so the user can log in with biometrics.

Set App Check token

To securely link Firebase App Check protection with our SDK components, you must retrieve and store the App Check token before sensitive operations like login or biometric enrollment.

The UXComponents.setAppCheckToken(_:) method securely injects the App Check token into the SDK.

UXComponents.setAppCheckToken(token)

The method returns a Bool:

• true: the token was stored successfully in the SDK.
• false: the App Check token was not accepted - ensure the token is valid and properly formatted.

Initialize the SDK

Initialize the SDK in your AppDelegate.application(_:didFinishLaunchingWithOptions:) so it's ready before any view uses it.

Import the library wherever you use the components:

import WeavrComponents

Then initialize:

let result = await UXComponents.initialize(environment: .Sandbox, uiKey: "YOUR_UI_KEY")
switch result {
case .initialized(let isBiometricsEnabled, let authenticationType, let userNeedsRelogin, let traceability):
    print("SDK initialised!")
    if userNeedsRelogin {
        // Log the user out and require a fresh login.
    }
case .serverError(let code, let message, let traceability):
    // Handle a server-side error. Can retry the initialisation.
case .networkFailure(let cause, let traceability):
    // Handle a network error. Can retry the initialisation.
case .setupError(let cause, let error, let traceability):
    // Handle a local setup error, e.g. a keychain failure. Share `traceability` with
    // our support team if it keeps happening.
case .failure(let cause, let traceability):
    // Handle any other error.
}

initialize(environment:uiKey:) returns an InitializationResult. Every case carries a traceability value that helps our support team debug issues, and authenticationType tells you whether the project is configured for .passcode or .password authentication.

Next steps

With the SDK installed and initialized, you can integrate components:

• Verify users - sign users in securely
• Biometrics - biometric login and step-up authentication
• Card components - display PANPAN (Primary Account Number). Primary Account Number - the long card number (typically 16 digits) printed or embossed on a payment card and used to identify the card on the payment network. Weavr never returns the raw PAN to your client; `GET /managed_cards/{id}` returns the PAN in tokenized form as `cardNumber`, and the value is only detokenized inside a Secure UI card-number component (a sandboxed iframe on the web, a secure native view on mobile)., CVVCVV (Card Verification Value). Card Verification Value - the 3-digit security code printed on a payment card, used to authenticate card-not-present transactions. Weavr returns CVV in tokenized form on `GET /managed_cards/{id}` (with a stepped-up token); the value is only detokenized inside the SDK's secure CVV display component., and PINPIN (Personal Identification Number). Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component.
• KYC components - identity verification flows
• Push provisioning - add cards to Apple Wallet