Developer Pages

# Getting started

Page contents

# 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 12.

# 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 at support@signicat.com.

  2. Navigate to our repository and enter your Nexus repository login credentials. Browse for the correct version using the following links:

  3. Download EncapAPI.xcframework.

# Configure your project

Next, you have to set up and configure your IDE and project’s configuration for optimal use of the API.

Risk of registration data loss

The EncapAPI 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 EncapAPI.xcframework with your application, and add any other required frameworks. To do this:

  1. Drag and drop EncapAPI.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.

Do not embed the EncapAPI

The EncapAPI is a static framework, and should not be embedded. 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 EncapAPI framework.
  3. Select Do not embed from the dropdown menu.

# Frameworks required by the EncapAPI

The following system frameworks are required by the EncapAPI:

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

To use the classes and methods in the Encap SDK, you have to import the SDK in the same way that you would any Objective-C framework:

#import <EncapAPI/EncapAPI.h>

# Swift support

Learn more about our EncapSwiftAPI

For more information, you can read our Encap SDK developer documentation on migrating to our EncapSwiftAPI.

To use EncapAPI from Swift, make the following configurations:

  1. Add a new Objective-C file. When asked to add a bridge, answer Yes.
  2. A new file called <project_name>-Bridging-Header.h has now been created.
  3. In the bridging file, add the import for Encap as shown in the code snippet below:
#import "EncapAPI/EncapAPI.h"

# Configure Library Search Path for Objective-C apps

Objective-C only

This step is only required for apps that are written in Objective-C.

For EncapAPI versions 3.15 and above, parts of the internal code are written in Swift. This means that the EncapAPI has dependencies towards Swift standard libraries. Xcode automatically handles this when the project contains Swift code.

However, for Objective-C projects that do not contain any Swift code, the Library Search Path must be configured with the following:

$(SDKROOT)/usr/lib/swift
$(TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME)
$(TOOLCHAIN_DIR)/usr/lib/swift-5.0/$(PLATFORM_NAME)

Note

You can also resolve this by adding an empty Swift file to the project, and ensuring that the target membership is set to the app.

# Create the controller

The EncapAPI is exposed through the EncapController object which handles the state of all operations.

Operations using the EncapController take several operation-specific parameters and a success or error block. Once an operation has been dispatched as a request to the EncapAPI, 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 by invoking either the onSuccess or onError block.

  • If the onSuccess block is invoked, then the operation is successful.
  • If the onError block is invoked, 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 sharedController method to retrieve an instance of the EncapController.

Example: Use the sharedController method to retrieve an instance of the EncapController

# 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 sharedController can be used.

# Configure the controller

To configure the EncapAPI, you can use the EncapConfig class. The EncapAPI 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:

Properties Description
serverURL The URL of the Encap server.
applicationId The identifier for your application configuration. This contains specific settings for your app.
connectionTimeOut The amount of time in seconds before the connection the the Encap server times out.

The default value is 20 seconds.
publicKey The public key used for end-to-end encrypted communication. This is Base64 DER encoded (opens new window).

To find out how to generate a valid Elliptic curve key pair, see our E2EE set up guide in our Encap server administration manual.

Supports sect233k1 curve.
publicKeyHashes See our certificate pinning feature documentation for more details.
locationAccuracy The accuracy of the location.

The default is value is kCLLocationAccuracyHundredMeters.
allowDebugData See our client debug data feature documentation for more details.

Example: How to set configuration properties

Last updated: 11/04/2024 07:47 UTC

← Core operations →