Getting started

This guide covers RSS iOS SDK 2.6.0. The examples use an application deployment target of iOS 16.6.

Prerequisites

• An application whose deployment target and Xcode toolchain meet the requirements supplied with the SDK distribution.
• A physical device with Secure Enclave, a device passcode and enrolled Face ID or Touch ID for DSS activation and signing.
• An NSFaceIDUsageDescription entry in the application's Info.plist describing why Face ID is requested.
• The Security Server endpoint, an OIDC integration and an SDK license for the application's Bundle Identifier.

The SDK includes simulator slices for integration work. Use a physical device to validate Secure Enclave operations and the complete biometric signing flow.

Add RSS Mobile SDK to your project

Unzip the RSS 2.6.0 distribution and add swisssign_sdk_ios_rss.xcframework to the application's General → Frameworks, Libraries, and Embedded Content section. This artifact is a dynamic framework; select Embed & Sign for the application target.

The artifact includes ios-arm64 for devices and ios-arm64_x86_64-simulator for simulators. The Swift module to import is swisssign_sdk_ios_rss.

Initialize the SDK

Set the global configuration before creating the Rss instance. Use the complete endpoint supplied for your environment; the SDK does not append an endpoint path to a hostname.

import Foundation
import swisssign_sdk_ios_rss

Rss.configuration.secServerUrl = "https://<hostname>/sense/appserver/Server"
Rss.configuration.license = "your-sdk-license"
let rss = Rss()

Retain rss for the lifetime of the signing flow. Creating it without a Security Server URL is a programming error. Set Rss.configuration.workflowEngineUrl as well only if your deployment provides Workflow Engine functionality.

Check device compliance

This check can run before initializing Rss:

let compliance = Rss.isDeviceCompliant()
switch compliance {
case .deviceCompliant:
    break // The device meets the SDK's biometric prerequisites.
case .errNoHardware:
    break // Explain that the required hardware is unavailable.
case .errPinCodeNotSet:
    break // Ask the user to configure a device passcode.
case .errNoBiometricSet:
    break // Ask the user to configure biometrics or retry when available.
@unknown default:
    break // Treat unrecognized results as non-compliant.
}

Only start DSS activation or signing when the result is .deviceCompliant.

Open a session and obtain services

getSessionService(token:) accepts the JSON-encoded OIDC token response, including id_token with the user's sub claim, rather than just an access token. It returns an optional SessionService; handle a missing service before proceeding.

The following code belongs in an application method. oidcTokenResponse is the JSON string obtained from the application's OIDC flow, and secret is the securely stored enrollment secret described in Session Service.

guard let session = rss.getSessionService(token: oidcTokenResponse) else {
    // Report invalid or incomplete OIDC data to the application's login flow.
    return
}

session.openSession(withSecret: secret) { error in
    if let error = error {
        // Handle the session error before making further SDK calls.
        _ = error
        return
    }
    guard session.isSessionValid(),
          let service = session.getRssService(),
          let dss = service.getDssService() else {
        // The application needs to establish a usable session again.
        return
    }

    dss.getAvailableProfiles { profiles, error in
        if let error = error {
            // Present the retrieval error on the application's UI thread.
            _ = error
            return
        }
        let availableProfiles = profiles ?? []
        // Present the available profiles on the application's UI thread.
        _ = availableProfiles
    }
}

Retain the session and services needed by the flow. Check isSessionValid() before retrieving an RssService from an existing session: getRssService() asserts in debug builds when the session is invalid. Service operations can still fail if the session expires after that check.

To refresh the OIDC token, obtain a new SessionService from the same Rss instance with the refreshed token response, then retrieve new service wrappers for that token. Reopen the session if it is no longer valid.

Register the APNs token

Enable Push Notifications in the application and obtain the token from APNs. When both a valid RSS session and the token are available:

guard session.isSessionValid(),
      let service = session.getRssService(),
      service.isAvailable() else {
    // Defer registration until the session and server configuration allow it.
    return
}
let registered = service.registerRemoteNotificationToken(deviceToken)
if !registered {
    // Keep the APNs token and retry registration later.
}

Here deviceToken is the Data supplied by APNs. Repeat registration after session establishment and whenever APNs supplies a new token. For silent notifications, also enable Background Modes → Remote notifications.

End the flow

Call session.closeSession() when the authenticated flow ends. This logs out the current user without removing the enrollment. If the Rss instance is no longer needed, call rss.releaseInstance() and discard its service wrappers; create a new instance before starting another flow.

Profile activation, pending requests, biometric integrity and error handling are described in Services and Appendix.