> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-sdk/ios/getting-started-with-the-sdk.md).

# Installation Guide

{% hint style="warning" %}

## This guide covers version 7.0.0 and above. For versions below 7.0.0, please see the [legacy documentation](/caf-sdk/ios/getting-started-with-the-sdk-5.md).

{% endhint %}

### Requirements

Before integrating, ensure your environment meets the minimum **Xcode**, **Swift**, and **iOS** versions for the CafSDK release you use. Check [**GitHub Releases**](https://github.com/combateafraude/caf-ios-sdk).

You need:

* **CafSDK** and **CafFaceLiveness** linked to your target
* Optional **provider** packages (for example **iProov**, **FaceTec 2D**, **Fortface**) as agreed with CAF for your product — match your **`Package.swift`** or **CocoaPods** subspecs to the providers your backend expects.

{% hint style="warning" %}
We support CocoaPods; however, please note that it will be deprecated by the end of 2026. We strongly recommend using Swift Package Manager instead.

<https://blog.cocoapods.org/CocoaPods-Specs-Repo/>
{% endhint %}

| Requirement           | Version |
| --------------------- | ------- |
| iOS deployment target | 15.0+   |
| Xcode                 | 26      |

***

### Permissions

Add **camera** usage text so the system can show the permission prompt when Face Liveness uses the camera.

**Info.plist**

```xml
<key>NSCameraUsageDescription</key>
<string>We need access to the camera for face verification.</string>
```

Standard iOS apps can use the network without an extra manifest entry; configure **App Transport Security** only if your environment requires exceptions (see Apple documentation).

***

### Adding dependencies

In **`Package.swift`**, add the package (adjust the version range to match your release):

{% tabs %}
{% tab title="Swift Package Manager" %}
{% code title="Package.swift" overflow="wrap" expandable="true" %}

```kt
dependencies: [
    .package(url: "https://github.com/combateafraude/caf-ios-sdk.git", from: "7.0.0")
]

.target(
    name: "YourApp",
    dependencies: [
        .product(name: "CafSDK", package: "caf-ios-sdk"),
        .product(name: "CafFaceLiveness", package: "caf-ios-sdk"),
        // Optional providers, e.g. IproovProvider, FaceTec2DProvider, FortfaceProvider
    ]
)
```

{% endcode %}
{% endtab %}

{% tab title="Cocoapods" %}
{% code title="Podfile" overflow="wrap" expandable="true" %}

```ruby
platform :ios, '15.0'

pod 'CafSDKiOS'
# Example subspecs: CafSDKiOS/CafFaceLiveness, CafSDKiOS/IproovProvider, …
```

{% endcode %}
{% endtab %}
{% endtabs %}

***

### Configuring the session

Initialize **Certta** when you have a valid **mobile token** (JWT) and **user ID** — for example after login. Call **`Certta.shared.configure(configuration:)`** from your app code (typically from the same place you establish the user session, not necessarily `application(_:didFinishLaunchingWithOptions:)` unless that fits your flow).

```swift
Certta.shared.configure(
    configuration: CerttaConfiguration(
        mobileToken: "your-jwt",
        userID: "user-id",
        environment: .prod,
        securityEnabled: true
    )
)
```

* If **mobile token** or **user ID** is empty, the session is not updated and a warning is logged; call **`configure`** again with both values set.
* **`environment`**: must match the CAF environment your backend uses (for example **`.prod`**, **`.dev`** **`.beta`**).
* **`securityEnabled`**: when **`true`**, jailbreak / instrumentation checks may block flows (see CAF product guidance).

#### CerttaConfiguration parameters

| Parameter             | Type             | Description                                                                    |
| --------------------- | ---------------- | ------------------------------------------------------------------------------ |
| **`mobileToken`**     | `String`         | CAF **mobile JWT** from your backend.                                          |
| **`userID`**          | `String`         | End-user identifier.                                                           |
| **`environment`**     | `CafEnvironment` | CAF backend environment (for example **`.prod`**).                             |
| **`securityEnabled`** | `Bool`           | When **`true`**, enables security checks where applicable. Default **`true`**. |

#### Mobile token (JWT)

Your backend should obtain and pass the mobile token according to **CAF platform rules**. Use your **CAF integration / backend documentation** for how to generate and refresh the JWT; do not embed secrets in the client.

***

### Runtime configuration updates

**`userID`** and **`mobileToken`** can be updated after the initial **`configure`** without repeating the full struct. Call these from your coordinator, view controller, or wherever you handle login, logout, or token refresh:

```swift
Certta.shared.updateUserId("new-user-id")
Certta.shared.updateMobileToken("new-jwt-token")
```

Use these when the user logs in again or when your backend issues a **refreshed JWT**, so the Certta SDK stays aligned with the active session.

#### End session

```swift
Certta.shared.clearSession()
```

Call on logout. Flows will not run until **`configure`** succeeds again with valid credentials.

***

### Colors and theming

The Face Liveness UI can use a custom palette when **`useFaceLivenessUi`** is **`true`** in **`LivenessConfiguration`**. Provide colors as **hexadecimal strings** (for example **`#RRGGBB`**).

1. After a successful **`configure`**, set session colors: **`Certta.shared.setColorConfiguration(_:)`**.
2. Set **`useFaceLivenessUi: true`** so those colors apply to the built-in Certta Face Liveness interface.

**Dark / light mode:** build **`CafColorConfiguration`** using **`UITraitCollection.current.userInterfaceStyle`** if you need different palettes.

```swift
Certta.shared.setColorConfiguration(
    CafColorConfiguration(
        primaryColor: "#FF0000",
        secondaryColor: "#00FF00",
        contentColor: "#000000",
        backgroundColor: "#FFFFFF",
        mediumColor: "#D1D1D1",
        dialogBackgroundColor: "#FFFFFF",
        dialogBorderColor: "#0C395E"
    )
)
```

#### CafColorConfiguration parameters

| Parameter                   | Description                  |
| --------------------------- | ---------------------------- |
| **`primaryColor`**          | Primary accent (hex string). |
| **`secondaryColor`**        | Secondary accent.            |
| **`contentColor`**          | Foreground / content.        |
| **`backgroundColor`**       | Main background.             |
| **`mediumColor`**           | Muted / medium emphasis.     |
| **`dialogBackgroundColor`** | Dialog background.           |
| **`dialogBorderColor`**     | Dialog border.               |

All parameters are optional in the initializer; set the ones your theme needs.

***

### Signed response (success)

The string in **`didFinish(signedResponse:)`** is the signed result from the module. Your backend or CAF integration documentation defines how to validate, decode, and store it. **Do not** log the full token in production builds.

***

### Next steps:

{% content-ref url="/pages/oS2QjeJjZkiAKZZ3NiPQ" %}
[Face Liveness](/caf-sdk/ios/getting-started-with-the-sdk-1.md)
{% endcontent-ref %}

{% content-ref url="/pages/Z2W6VWF6vgcbBljXGfnN" %}
[Document Detector](/caf-sdk/ios/getting-started-with-the-sdk-2.md)
{% endcontent-ref %}

### Release notes

See [**GitHub Releases**](https://github.com/combateafraude/caf-ios-sdk) for versions, breaking changes, and minimum Xcode / iOS.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.caf.io/caf-sdk/ios/getting-started-with-the-sdk.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.