> For the complete documentation index, see [llms.txt](https://doc.faceplugin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.faceplugin.com/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-ios-sdk.md).

# iOS

Faceplugin Face Recognition iOS SDK. Fully on-premise face matching, 1:N identify, and 2D liveness. Xcode frameworks, setActivation, initSDK, detectImage, VideoWorker.

Fully on-premise **Face Recognition SDK for iOS**. Detect faces, extract templates, match 1:1 or live 1:N, and check passive 2D liveness on the device.

Native class: `FaceRecognitionSDK` (`facerecognitionsdk.framework`). Status codes: **0** Success, **1** Invalid license, **2** Expired, **3** Not activated, **4** Init failed.

### Code <a href="#setup" id="setup"></a>

{% embed url="<https://github.com/Faceplugin-ltd/FaceRecognition-iOS>" %}

### Setup <a href="#setup" id="setup"></a>

1. Unzip the frameworks from [Google Drive](https://drive.google.com/drive/folders/1PKmV-o7gq7s7dDtiNgXPfCi2ZlWaRy5H) next to the Xcode project: `facerecognitionsdk.framework`, `FaceRecognitionEngine.framework`, `onnxruntime.framework`.
2. Add the SDK frameworks to the project in Xcode (**Embed & Sign**).
3. Add `FaceRecognitionSDK-Bridging-Header.h` to Build Settings (`#import <facerecognitionsdk/FaceRecognitionSDK.h>`).
4. Set **your** Signing Team. Demo bundle id: **`com.faceplugin.facerecognitionsdk.app`**. Physical iPhone, iOS 13+. Call **setActivation → initSDK** off the main thread.

### APIs

#### <mark style="color:orange;">setActivation:</mark> This API is used to activate the SDK <a href="#setactivation" id="setactivation"></a>

```objectivec
+(int)setActivation:(NSString*)license;
```

| **Input**        | <ul><li><strong>license</strong> (NSString\*): The license string (<code>license key</code>)</li></ul>                                                           |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Return value** | <p>The SDK activation status code.</p><ul><li>0: Success</li><li>1: Invalid license</li><li>2: Expired</li><li>3: Not activated</li><li>4: Init failed</li></ul> |

#### <mark style="color:orange;">initSDK:</mark> This API is used to initialize the SDK <a href="#initsdk" id="initsdk"></a>

```objectivec
+(int)initSDK;
```

| **Input**        | None                                                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Return value** | <p>The SDK initialization status code.</p><ul><li>0: Success</li><li>1–4: see <code>setActivation</code></li></ul> |

#### <mark style="color:orange;">getMachineCode:</mark> This API is used to retrieve the machine code <a href="#getmachinecode" id="getmachinecode"></a>

```objectivec
+(NSString*)getMachineCode;
```

#### <mark style="color:orange;">getLicenseStatus:</mark> This API is used to read license status <a href="#getlicensestatus" id="getlicensestatus"></a>

```objectivec
+(NSString*)getLicenseStatus;
+(BOOL)allowsRecognition;
+(BOOL)allowsLiveness;
+(NSString*)lastLicenseError;
+(BOOL)isActivated;
```

#### <mark style="color:orange;">detectImage:</mark> This API is used to detect faces and return engine JSON <a href="#detectimage" id="detectimage"></a>

```objectivec
+(NSString*)detectImage:(UIImage*)image crop:(BOOL)crop;
+(NSString*)detectImage:(UIImage*)image crop:(BOOL)crop flags:(FaceRecognitionDetectFlags)flags;
```

| **Input**        | <ul><li><strong>image</strong> (UIImage\*): The input image</li><li><strong>flags</strong>: Estimators to run (<code>FaceRecognitionDetectAll</code>, <code>DetectLiveness</code>, …)</li></ul> |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Return value** | JSON string (Linux-compatible, same idea as HTTP `POST /api/detect`).                                                                                                                           |

#### <mark style="color:orange;">qualityImage:</mark> This API is used to run face image quality checks <a href="#qualityimage" id="qualityimage"></a>

```objectivec
+(NSString*)qualityImage:(UIImage*)image crop:(BOOL)crop;
```

#### <mark style="color:orange;">matchImage1:</mark> This API is used to compare two photos (1:1) <a href="#matchimage" id="matchimage"></a>

```objectivec
+(NSString*)matchImage1:(UIImage*)image1 image2:(UIImage*)image2 crop:(BOOL)crop;
```

#### <mark style="color:orange;">extractFeatureFromImage:</mark> This API is used to extract a face template <a href="#extractfeature" id="extractfeature"></a>

```objectivec
+(NSString*)extractFeatureFromImage:(UIImage*)image;
```

| **Input**        | A face image (typically cropped).                                     |
| ---------------- | --------------------------------------------------------------------- |
| **Return value** | JSON with the template. Store the feature bytes in **your** database. |

#### <mark style="color:orange;">similarityWithFeature1:</mark> This API is used to calculate the similarity between two face templates <a href="#similarity" id="similarity"></a>

```objectivec
+(float)similarityWithFeature1:(NSData*)feature1 feature2:(NSData*)feature2;
```

| **Input**        | Two template blobs from `extractFeatureFromImage`.                                       |
| ---------------- | ---------------------------------------------------------------------------------------- |
| **Return value** | Similarity **0.0–1.0**, or **-1** on error. Demo Identify default threshold is **0.67**. |

#### <mark style="color:orange;">setLandmarkMode:</mark> This API is used to set the landmark model <a href="#setlandmarkmode" id="setlandmarkmode"></a>

```objectivec
+(int)setLandmarkMode:(int)mode; // 14, 68, or 468
+(int)landmarkMode;
```

#### <mark style="color:orange;">VideoWorker:</mark> This API is used for live 1:N identify <a href="#videoworker" id="videoworker"></a>

```objectivec
+(int)startVideoWorkerWithMatchThreshold:(float)threshold;
+(int)startVideoWorkerWithConfig:(FaceRecognitionVideoWorkerConfig*)config;
+(int)syncVideoWorkerDatabaseWithFeatures:(NSArray<NSData*>*)features matchThreshold:(float)threshold;
+(int)addVideoWorkerFrame:(UIImage*)image;
+(int)addVideoWorkerSampleBuffer:(CMSampleBufferRef)sampleBuffer;
+(NSString*)extractFeatureWithSampleBuffer:(CMSampleBufferRef)sampleBuffer;
+(void)setVideoWorkerEventHandler:(void(^)(NSString* json))handler;
+(void)stopVideoWorker;
```

#### <mark style="color:orange;">deinitSDK:</mark> This API is used to unload the engine <a href="#deinitsdk" id="deinitsdk"></a>

```objectivec
+(int)deinitSDK;
```

### Run the demo

1. Place the three frameworks next to the Xcode project (see Setup).
2. Keep demo bundle id **`com.faceplugin.facerecognitionsdk.app`**.
3. Run on a **physical** iPhone (iOS 13+).
4. Wait until the home status bar shows Ready. Then Enroll / Identify / Capture / Attribute unlock.

Call **setActivation → initSDK** off the main thread. The engine is **not** concurrent.

### Screenshots

The gallery is **Android** sample UI from `faceplugin-assets`. iOS demo tiles match these screens; there is no separate iOS photoshoot in these docs.

| Home                                                                                                                                                                                                                                                               | Identify                                                                                                                                                                                                   | Capture                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <img src="https://raw.githubusercontent.com/Faceplugin-ltd/faceplugin-assets/main/screenshots/face-recognition/android/home.png" alt="Faceplugin Face Recognition Android sample UI (shown on the iOS page; no separate iOS screenshot yet)" data-size="original"> | <img src="https://raw.githubusercontent.com/Faceplugin-ltd/faceplugin-assets/main/screenshots/face-recognition/android/identify.png" alt="Faceplugin Face Recognition live identify" data-size="original"> | <img src="https://raw.githubusercontent.com/Faceplugin-ltd/faceplugin-assets/main/screenshots/face-recognition/android/capture.png" alt="Faceplugin Face Recognition oval capture" data-size="original"> |

### License

Licenses are **offline**. The sample key is only for the demo bundle. Request a new license key if you change the demo bundle.

Identify default threshold is **0.67**. Liveness demo default is **0.5**.

### Integrate into your own app

You need the three frameworks and `FaceRecognitionSDK`. You do **not** need the demo view controllers.

Typical call order: `setActivation` → `initSDK` → `detectImage` / `extractFeatureFromImage` → store templates in **your** database → `similarityWithFeature1:feature2:` or VideoWorker for live 1:N.

Public header only: `detectImage`, `extractFeatureFromImage`, `similarityWithFeature1:feature2:`, VideoWorker. There is **no** Objective-C `faceDetection:` returning `FaceBox` on this framework.

[Request a License & Support](/help/request-a-license-and-support.md) · [Contact us](/help/contact-us.md)

### FAQ

**What APIs does this page ship?** Swift equivalents of `setActivation`, `init`, face detection, template extract, similarity, and VideoWorker Identify.

**Are the screenshots iOS?** No. The gallery uses **Android** sample UI. iOS demo tiles match those screens.

**Offline?** Yes, after license key for the demo bundle id (or yours).

### Related documentation

* [Faceplugin Face Recognition Mobile SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk.md) · [Android](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-android-sdk.md) · [Glossary](/help/resources/glossary.md)
* [Face Liveness Detection iOS SDK](/products/face-recognition-sdk/liveness-detection-sdk/mobile-sdk/liveness-detection-ios-sdk.md)
* [ID Document Recognition iOS SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-ios-sdk.md)
* [Request a License](/help/request-a-license-and-support.md) · [Status codes](/help/resources/status-codes.md)
* [Combining products (eKYC)](/getting-started/choose-a-product.md) · [SDK comparison](/help/comparisons.md)


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://doc.faceplugin.com/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-ios-sdk.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.