Skip to main content

Getting started

Prerequisites​

Before you can get started, you must first install the following software:

Minimum iOS version

The minimum supported iOS version for the Encap SDK is iOS 14.

Cross-platform integration​

The Encap SDK (EncapSwiftAPI) is optimised for Swift, utilising Swift features such as:

  • Enums with associated values
  • Result type
  • Value types (structs)

For cross-platform developers such as React Native users, be aware that the Encap SDK is not directly compatible with Objective-C due to these Swift-specific features.

How to handle cross-platform projects​

To use EncapSwiftAPI in cross-platform projects:

  1. Create a Swift wrapper around the SDK.
  2. Expose the necessary functionality to Objective-C through this wrapper.
Our recommendation

To ensure a successful integration, we recommend that you have familiarity with Swift and Objective-C interoperability.

To get assistance, you can contact us by creating a support ticket in the Signicat Dashboard.

Add the SDK to your application​

The Encap SDK is available for download from our repository. The repository is gated, therefore you require login credentials to access it.

  1. Request your Nexus repository login credentials from us by creating a support ticket in the Signicat Dashboard.
  2. Navigate to our repository and enter your Nexus repository login credentials. Browse for the correct version using the following links:
  3. Download EncapSwiftAPI.xcframework.

Configure your project​

For optimal use of the API, you need to set up and configure your IDE and project's configuration .

Risk of registration data loss

The EncapSwiftAPI framework uses Apple's Keychain for persistence. If the application's App ID prefix is changed, then this data will no longer be available to the API.

As a result, if an app changes its App ID prefix, then all upgrading clients must re-activate with Encap.

For new developments the App ID prefix will typically be your TeamID. For older developments, the App ID prefix uses a 10 digit alphanumeric.

You have to link EncapSwiftAPI.xcframework with your application, and add any other required frameworks. To do this:

  1. Drag and drop EncapSwiftAPI.xcframework into your project directory, ensuring that it is added to the target.
  2. Under the TARGETS list, select your application.
  3. Click on the Build Phases tab.
  4. Under Link Binary With Libraries, click the + button to add the system frameworks that are required by the Encap SDK.
Embed and sign the EncapSwiftAPI

If you are using Xcode 15, embed the Encap framework that was dragged in. To ensure this is configured correctly, you can:

  1. Navigate to Frameworks, Libraries, and Embedded Content in Xcode.
  2. In the Embed column, click on the field corresponding to your EncapSwiftAPI framework.
  3. Select Embed & Sign from the dropdown menu.

This step will enable privacy manifests to be picked up by Xcode's tooling.

Frameworks required by the EncapSwiftAPI​

The following system frameworks are required by the EncapSwiftAPI:

  • Security
  • SystemConfiguration
  • CoreLocation
  • LocalAuthentication
  • WebKit
  • UserNotifications
  • libz.tbd

To use the classes and methods in the Encap, you need to import the EncapSwiftAPI:

import EncapSwiftAPI

Create the controller​

The Encap client API is exposed through the EncapController object which handles the state of all operations.

Operations using the EncapController take several operation-specific parameters and a onCompletion block containing the Result.

Once an operation has been dispatched as a request to the controller, its handling is asynchronous to the thread that initiated the operation. This allows the UI thread to invoke operations and not be blocked as they're being handled.

The result is then passed to your application that contains either a .success or .failure case:

  • If the Result contains a .success value, then the operation is successful.
  • If the Result contains a .failure value, then the error result object can be used to determine how your UI should proceed.

You can use your completion block to update the user interface to reflect the result. For example:

  • When the operation completes successfully, you could proceed to the next step; marking the user as logged in.
  • When the operation fails, you could let the user try the operation again; optionally allowing the user to update the provided input.

An EncapController only supports a single operation at a time. It does not support multiple parallel operations simultaneously. You can use the shared method to retrieve an instance of the EncapController.

Example: Use the shared method to retrieve an instance of the EncapController
EncapController.shared.loadConfig { result in
    switch result {
    case .success(let loadConfigResult):
        // Success
    case .failure(let error):
        // Error
    }
}

Multiple active registrations in one application​

From Encap version 3.11, initWithName was added. This means that the EncapController can now be initialised with a unique name in order to support multiple active registrations in one application.

Example: Initialise EncapController with a unique name
let controller = EncapController(name: "registrationA")
Note

If the app only supports one registration, then shared controller can be used.

Configure the controller​

To configure the controller, you can use the EncapConfig class. The SDK sets default values for most of its configuration properties, however, you must set the Encap server's URL and the public key for end-to-end encryption.

You must update the settings before making any calls to the EncapController object. Configurations are not persistent to disk; they are only stored in memory, and therefore need to be set for every new instance of the EncapController.

The following properties can be configured:

Example: How to set configuration properties
let config = EncapConfig(serverURL: "https://demo.encapsecurity.com/pt/", applicationId: "encapApiTest", publicKey: "someKey")
EncapController.shared.config = config
MobileID customers

For MobileID customers, you must configure the following properties in the controller. This applies to both sandbox and production accounts:

  • serverURL: This is always https://api.signicat.com/encore/encap.
  • applicationId: To find this, see Details for your MobileID account in the Signicat Dashboard.
  • publicKey: To find this, see Details for your MobileID account in the Signicat Dashboard.
On this page