# How to Integrate Server-Based Liveness into Your Mobile Application
This guide outlines the steps for integrating the Oz Liveness Mobile SDK into a customer mobile application for capturing facial videos and subsequently analyzing them on the server.
The SDK implements a ready-to-use face capture user interface that is essential for seamless customer experience and accurate liveness results. The SDK methods for liveness analysis communicate with Oz API under the hood.
Before you begin, make sure you have Oz API credentials. When using SaaS API, you get them [from us](mailto:info@ozforensics.com):
|
Login:
Password: …
API:
Web Console:
|
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
For the on-premise Oz API, you need to create a user yourself or ask your team that manages the API. See the [guide on user creation via Web Console](https://doc.ozforensics.com/oz-knowledge/guides/user-guide/oz-webui/webui-users#adding-a-user). Consider the proper user role (`CLIENT` in most cases or `CLIENT ADMIN`, if you are going to make SDK work with the pre-created folders from other API users). In the end, you need to obtain a similar set of credentials as you would get for the SaaS scenario.
We also recommend that you use our logging service called telemetry, as it helps a lot in investigating attacks' details. For Oz API users, the service is enabled by default. For on-premise installations, we'll provide you with credentials.
Oz Liveness Mobile SDK requires a license. License is bound to the bundle\_id of your application, e.g., `com.yourcompany.yourapp`. Issue the 1-month trial license [on our website](https://ozforensics.com/developers/try_mobile_sdk) or [email us](mailto:info@ozforensics.com) for a long-term license.
### Android
{% stepper %}
{% step %}
### Add SDK to your project
In the build.gradle of your project, add:
```kotlin
allprojects {
repositories {
maven { url "https://ozforensics.jfrog.io/artifactory/main" }
}
}
```
In the build.gradle of the module, add:
```kotlin
dependencies {
implementation 'com.ozforensics.liveness:full:'
// You can find the version needed in the Android changelog
}
```
{% endstep %}
{% step %}
### Initialize SDK
Rename the license file to **forensics.license** and place it into the project's res/raw folder.
{% code title="Kotlin" %}
```kotlin
OzLivenessSDK.init(
context,
listOf(LicenseSource.LicenseAssetId(R.raw.forensics))
)
```
{% endcode %}
{% endstep %}
{% step %}
### Connect SDK to Oz API
Use API credentials (login, password, and API URL) that you’ve got from us.
{% code title="Kotlin" %}
```kotlin
OzLivenessSDK.setApiConnection(
OzConnection.fromCredentials(host, username, password),
statusListener(
{ token -> /* token */ },
{ ex -> /* error */ }
)
)
```
{% endcode %}
In production, instead of hard-coding login and password in the application, it is recommended to get access token on your backend with API [auth](https://apidoc.ozforensics.com/#tag/Authorization/paths/~1api~1authorize~1auth/post) method then pass it to your application:
{% code title="Kotlin" %}
```kotlin
OzLivenessSDK.setApiConnection(OzConnection.fromServiceToken(host, token))
```
{% endcode %}
{% endstep %}
{% step %}
### Add face recording
To start recording, use `startActivityForResult`:
{% code title="Kotlin" %}
```kotlin
val sessionToken: String = getSessionToken()
val captureRequest = CaptureRequest(
listOf(
AnalysisProfile(
Analysis.Type.QUALITY,
listOf(MediaRequest.ActionMedia(OzAction.Blank)),
)
)
)
val intent = OzLivenessSDK.createMediaCaptureScreen(captureRequest, sessionToken)
startActivityForResult(intent, REQUEST_LIVENESS_CONTAINER)
```
{% endcode %}
To obtain the captured video, use `onActivityResult`:
{% code title="Kotlin" %}
```kotlin
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (requestCode == REQUEST_LIVENESS_CONTAINER) {
when (resultCode) {
OzLivenessResultCode.SUCCESS -> runAnalysis(OzLivenessSDK.getContainerFromIntent(data))
OzLivenessResultCode.USER_CLOSED_LIVENESS -> { /* user closed the screen */ }
else -> {
val errorMessage = OzLivenessSDK.getErrorFromIntent(data)
/* show error */
}
}
}
}
```
{% endcode %}
{% endstep %}
{% step %}
### Run analyses
To run the analyses, execute the code below.
{% code title="Kotlin" %}
```kotlin
private fun runAnalysis(container: DataContainer?) {
if (container == null) return
AnalysisRequest.Builder()
.addContainer(container)
.build()
.run(
{ result ->
val isSuccess = result.analysisResults.all { it.resolution == Resolution.SUCCESS }
},
{ /* show error */ },
{ /* update status */ },
)
}
```
{% endcode %}
{% endstep %}
{% endstepper %}
### iOS
{% stepper %}
{% step %}
### Add our SDK to your project
[**CocoaPods**](https://cocoapods.org/)
To integrate OZLivenessSDK into an Xcode project, add to Podfile:
```swift
pod 'OZLivenessSDK', :git => 'https://gitlab.com/oz-forensics/oz-liveness-ios', :tag => '' // You can find the version needed in iOS changelog
```
**SPM**
Add the following package dependencies via SPM: (if you need a guide on adding the package dependencies, please refer to the [Apple documentation](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app)). **OzLivenessSDK** is mandatory. Skip the **OzLivenessSDKOnDevice** file.
{% endstep %}
{% step %}
### Initialize SDK
Rename the license file to **forensics.license** and put it into the project.
```swift
OZSDK(licenseSources: [.licenseFileName("forensics.license")]) { licenseData, error in
if let error = error {
print(error.errorDescription)
}
}
```
{% endstep %}
{% step %}
### Connect SDK to Oz API
Use API credentials (login, password, and API URL) that you’ve got from us.
```swift
OZSDK.setApiConnection(Connection.fromCredentials(host: “https://sandbox.ohio.ozforensics.com”, login: login, password: p)) { (token, error) in
// Your code to handle error or token
}
```
In production, instead of hard-coding the login and password in the application, it is recommended to get an access token on your back end using the API [auth](https://apidoc.ozforensics.com/#tag/Authorization/paths/~1api~1authorize~1auth/post) method, then pass it to your application:
```swift
OZSDK.setApiConnection(Connection.fromServiceToken(host: "https://sandbox.ohio.ozforensics.com", token: token)) { (token, error) in
}
```
{% endstep %}
{% step %}
### Add face recording
Create a controller that will capture videos as follows:
```swift
getSessionToken() { sessionToken in
DispatchQueue.main.async {
do {
let action:OZVerificationMovement = .selfie
let mediaRequest = MediaRequest.action(action)
let profile = AnalysisProfile(mediaList: [mediaRequest],
type: .quality,
params: [:] )
let request = CaptureRequest(analysisProfileList: [profile], cameraPosition: .front)
let ozLivenessVC = try OZSDK.createMediaCaptureScreen(self, request, sessionToken: sessionToken)
self.present(ozLivenessVC, animated: true)
} catch let error {
print(error.localizedDescription)
}
}
}
```
The delegate object must implement the `OZLivenessDelegate` protocol:
```swift
extension ViewController: LivenessDelegate {
func onResult(container: DataContainer) {
}
func onError(status: OZVerificationStatus?) {
}
}
```
{% endstep %}
{% step %}
### Run analyses
Use `AnalysisRequestBuilder` to initiate the Liveness analysis. The communication with Oz API is under the hood of the run method.
```swift
func onResult(container: DataContainer) {
let analysisRequest = AnalysisRequestBuilder()
analysisRequest.addContainer(container)
analysisRequest.run(
statusHandler: { status in
},
errorHandler: { error in
}
) { result in
}
}
```
{% endstep %}
{% endstepper %}
With these steps, you are done with basic integration of Mobile SDKs. You will be able to access recorded media and analysis results in Web Console via browser or programmatically via API.
In developer guides, you can also find instructions for customizing the SDK look-and-feel and access the full list of our Mobile SDK methods. Check out the table below:
| Android [sample app](https://gitlab.com/oz-forensics/oz-liveness-android) source codes | iOS [sample app](https://gitlab.com/oz-forensics/public/oz-liveness-ios-sample/-/tree/main) source codes |
| ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Android OzLiveness SDK [Developer Guide](https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/sdk/oz-mobile-sdk/android) | iOS OzLiveness SDK [Developer Guide](https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/sdk/oz-mobile-sdk/ios) |
| [Demo app](https://play.google.com/store/apps/details?id=com.ozforensics.liveness.demo\&hl=en) in PlayMarket | [Demo app](https://testflight.apple.com/join/mBbPQqnM) in TestFlight |
