Extension support

Page contents

• Overview
• Prepare the Project
  • Main Target
  • Extension Target
• Enable Extension Support
• Perform authentication
• Error codes

Overview

With iOS extensions, you can extend functionality for your end-users beyond your app.

This feature will them to authenticate outside of your app, and make content available to them whilst interacting with other apps or parts of the system.

Prepare the Project

Before extension support can be activated, you need to make some changes to the project.

Main Target

1. Open the project file, select the main target project, then click the Signing & Capabilities tab.
2. Click +, then add App Groups and Keychain Sharing.
3. In the Keychain Sharing section, add a new Keychain group. This must be exactly the same as the BundleID, for example com.company.app.
4. In the App Groups section, add a new App Group. This must be exactly the same as the BundleID, but preceded by the word 'group'. For example, group.com.company.app.

Extension Target

1. Open the project file, select the extension target project, then click the Signing & Capabilities tab.
2. It is important that the BundleID from the extension target follows the Apple structure, and does not contain more than one period after the main application's BundleID. For example, com.company.app.extensionName.
3. Click +, then add App Groups and Keychain Sharing.
4. In the Keychain Sharing section, add a new Keychain group. This must be exactly the same as the main target BundleID, for example com.company.app
5. In the App Groups section, add a new App Group. This must be exactly the same as the main target BundleID, but preceded by the word 'group'. For example, group.com.company.app.

You have to add the same Frameworks as Main App to Extension Target. See required frameworks on our SDK Getting started page for further information.

Enable Extension Support

To activate the extension support, you only need to set the extensionSupport field of the configuration with value true:

EncapController.shared.config.extensionSupport = true

For new registrations, the data will be stored in the Shared Group and Shared Keychain when extension support is enabled.

For existing registrations the data will be migrated on the next successful authentication.

If the registration has biometrics activated, then the migration will only occur when the biometric authentication method is used to authenticate.

Important

After enabling extensionSupport there is no way to rollback and disable it. To disable it, the end-user must be deactivated and forced to do a new registration.

Note

Keychain Sharing and App Groups are only accessible by apps made by members of the same Apple development team.

You can use isActivatedWithExtensionSupport to check whether the registration is activated with extension support. To do this:

EncapController.shared.isActivatedWithExtensionSupport()

Perform authentication

To authenticate, you should use the same authentication method as in the main app. For more information, see our authentication methods page.

If isActivatedLocallyWithError is returning false from an extension, this means that either:

• The end-user has not activated with extensionSupport enabled.
• The end-user has not migrated yet.

When extensionSupport is enabled, the app can check isActivatedLocallyWithError and isActivatedWithExtensionSupport to identify situations where a migration is required before using this feature.

Error codes

The table below illustrates errors related to extension support:

Error Code	Error name	Description
160	clientErrorAppAttestNotSupportedInExtension	App Attestation is not supported from extension in REQUIRED mode. An authentication is required to be able to use this operation.
161	clientErrorOperationNotAllowedInExtension	The current operation is not allowed from an extension.
175	clientErrorStorageNeedSharedGroup	Storage is unavailable; failed to read or write data. This happens when extension support is enabled but the App Group is not available.