> For the complete documentation index, see [llms.txt](https://doc.ozforensics.com/oz-knowledge-ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.ozforensics.com/oz-knowledge-ru/obshaya-informaciya/kratkie-rukovodstva-po-integracii/kak-integrirovat-oz-liveness-v-vashe-veb-prilozhenie.md).

# Как интегрировать Oz Liveness в ваше веб-приложение

{% hint style="warning" icon="display" %}
Внимание: это машинный перевод.
{% endhint %}

Oz Liveness Web SDK предоставляет готовый пользовательский интерфейс захвата лица, необходимый для бесшовного клиентского опыта и точных результатов анализа Liveness. SDK обнаруживает как презентационные атаки, так и инъекционные атаки.

Это руководство поможет вам выполнить первую проверку Liveness с помощью Web SDK и Oz API. Здесь рассматривается модель [SaaS](/oz-knowledge-ru/obshaya-informaciya/opisanie-sistemy-oz-forensics/modeli-ispolzovaniya-saas-lokalnaya-ustanovka-i-analiz-na-ustroistve.md).

Описанный поток сочетает два подхода.

* **Режим съемки** – Web SDK снимает видео для Liveness в браузере или приложении, а бэкенд клиента передает его в Oz API. Результаты съемки не отправляются из SDK напрямую в Oz API: бэкенд клиента выступает посредником.
* **OzCapsula** – проприетарный зашифрованный бинарный контейнер. SDK упаковывает в него снятые медиаданные; расшифровать и обработать его может только Oz API. На стороне клиента это непрозрачный blob — его нельзя декодировать или просмотреть, можно только передать в исходном виде.

Каждый шаг помечен:

* **\[Oz SDK]** — вызов нашего SDK API.
* **\[Ваш код]** — вызов вашего бэкенда или вашего кода.

`{{host}}` в примерах ниже — базовый URL вашего развертывания Oz API, который предоставляется вам при настройке.

## Требования

| Компонент | Минимальная версия |
| --------- | ------------------ |
| Oz API    | **6.6.1**          |
| Web SDK   | **1.9.10**         |

Для работы необходим выделенный Web Adapter. Если он еще не настроен для вашей компании, разверните раздел ниже.

<details>

<summary>Как получить Web Adapter</summary>

Сообщите нам доменные имена страниц, с которых вы планируете вызывать Web SDK, и email для доступа администратора, например:

| <p>Доменные имена, с которых будет вызываться Web SDK:</p><ol><li>[www.yourbrand.com](http://www.yourbrand.com)</li><li>[www.yourbrand2.com](http://www.yourbrand2.com)</li></ol><p>Email для доступа администратора:</p><ul><li><j.doe@yourcompany.com></li></ul> |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

В ответ вы получите URL и учетные данные для дальнейшей интеграции и использования. При работе с SaaS API они предоставляются [нами](mailto:info@ozforensics.com):

| <p>Логин: <j.doe@yourcompany.com></p><p>Пароль: …</p><p>API: https\://\<link>.com/</p><p>Web Console: https\://\<link>.com</p><p>Web Adapter: [https://web-sdk.\&#x3C;link>.com/your\_company\_name/](https://web-sdk.\&#x3C;link>.com/your_company_name/)</p> |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

</details>

## Инструкции

{% stepper %}
{% step %}

### (Oz SDK) Встройте плагин

Oz предоставляет URL плагина (обслуживается адаптером на стороне Oz). Добавьте его на страницу:

```html
<script src="https://path-to-websdk/plugin_liveness.php"></script>
```

{% endstep %}

{% step %}

### (ваш код) Получите `session_token` из вашего бэкенда

OzCapsula использует session token. Токен обязателен для OzCapsula.

Ваш бэкенд запрашивает session token у Oz API. Запрашивайте его перед каждой сессией съемки — как можно ближе к моменту, когда пользователь начинает съемку.

**Эндпойнт:**

```
GET {{host}}/api/authorize/session_token
```

**Запрос:**

```shell
curl --location -g '{{host}}/api/authorize/session_token' \
--header 'X-Forensic-Access-Token: {{access_token}}' ## опционально, зависит от настроек установки
```

Механизм авторизации при вызовах Oz API (`access_token`) зависит от настроек вашей установки: при использовании Instant API вы можете интегрировать его в рамках собственной схемы авторизации. Если в вашем случае требуется токен доступа, см. раздел [Аутентификация](https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/api/oz-api/use-cases/authentication). Никогда не передавайте токен доступа в браузер. Также обратите внимание, что [токен доступа и session token — это разные токены, выдаваемые для разных целей](/oz-knowledge-ru/other/faq.md#v-chem-raznica-mezhdu-access_token-i-session_token).

**Ответ:**

```json
{
  "session_token": "<session_token>"
}
```

Токен краткосрочный (время жизни по умолчанию: 900 секунд для API Full, 120 секунд для Instant API). Запрашивайте один токен на сессию съемки и сразу же передавайте его в SDK — не кэшируйте и не используйте повторно в разных сессиях.
{% endstep %}

{% step %}

### (Oz SDK) Запустите плагин с `session_token`

```js
OzLiveness.open({
  lang: 'en',
  action: ['video_selfie_blank'],  // пассивная Liveness
  session_token: session_token,    // session_token из шага 2
  on_capture_complete: function (action, ozCapsula) {
    // ozCapsula = контейнер OzCapsula (Blob) — шаг 4
    sendToYourBackend(ozCapsula);
  },
  on_error: function (err) { /* обработка ошибки */ }
});
```

{% endstep %}

{% step %}

### (Oz SDK) Получите контейнер OzCapsula

По завершении съемки SDK вызывает коллбэк `on_capture_complete`. Контейнер передается вторым аргументом — `Blob` с MIME-типом `application/octet-stream`.

{% hint style="warning" %}
Контейнер — это **непрозрачный зашифрованный blob**. Вы **не можете** декодировать его, просматривать его содержимое или извлекать из него отдельные изображения, кадры или метаданные на стороне клиента. Контейнер необходимо передать на бэкенд в исходном виде. Если вам нужен доступ к снятым изображениям (например, к [лучшему кадру](broken://pages/d847aafa79b0d9a38ec8fba1f915a1956865c344)), получайте их из ответа Oz API на стороне сервера.
{% endhint %}

Отправьте контейнер на бэкенд с Content-Type `application/octet-stream`.
{% endstep %}

{% step %}

### (ваш код) Отправьте контейнер в Oz API

Ваш бэкенд передает контейнер в одном синхронном `POST`-запросе.

**Эндпойнт (Instant API):**

```shellscript
POST {{host}}/api/instant/folders/
```

**Эндпойнт (Full API):**

```shellscript
POST {{host}}/api/folders/
```

**Заголовки:**

* `Content-Type: application/octet-stream` (обязательно).
* `X-Forensic-Access-Token: {{access_token}}` (опционально, зависит от настроек установки).

**Тело запроса:** необработанные байты контейнера — без JSON-обертки, без multipart, без base64.

**Запрос (Instant API):**

```shell
curl -X POST '{{host}}/api/instant/folders/' \
  --header 'X-Forensic-Access-Token: {{access_token}}' ## опционально, зависит от настроек установки
  -H 'Content-Type: application/octet-stream' \
  --data-binary '@/path/to/container.dat'
```

**Запрос (Full API):**

```shell
curl -X POST '{{host}}/api/folders/' \
  --header 'X-Forensic-Access-Token: {{access_token}}' ## опционально, зависит от настроек установки
  -H 'Content-Type: application/octet-stream' \
  --data-binary '@/path/to/container.dat'
```

**При успехе:** HTTP `201` с JSON-объектом папки, описывающим результат. Перейдите к шагу 6.

**При ошибке на уровне контейнера:** HTTP `400` — см. раздел [Исключения](https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/api/oz-api/ozcapsula-data-container#exceptions).

Это руководство охватывает анализ Liveness. Чтобы выполнить анализ сопоставления лиц в рамках OzCapsula-потока, см. [Выполнение анализа сопоставления лиц в OzCapsula-потоке](https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/api/oz-api/ozcapsula-data-container/how-to-perform-a-face-matching-analysis-within-ozcapsula-flow).
{% endstep %}

{% step %}

### (ваш код) Обработайте ответ

Ваш бэкенд получает ответ — JSON-объект папки с описанием результата.

Принимайте решение о допуске или отклонении только на основе этих двух полей верхнего уровня:

```json
$.resolution_status   // "FINISHED" — анализы завершены; "FAILED" — ошибка при обработке анализа
$.system_resolution   // "SUCCESS", "DECLINED" или "FAILED"
```

Интерпретация значений `system_resolution`:

* `SUCCESS` — все проверки пройдены; пользователь допускается.
* `DECLINED` — одна или несколько проверок не пройдены; пользователь отклоняется.
* `FAILED` — системная ошибка не позволила завершить хотя бы один анализ; не следует трактовать как допуск или отклонение.

Для получения результатов по каждому анализу отдельно (например, чтобы узнать, прошла ли Liveness, но не прошло сопоставление лиц) читайте `$.analyses[*].resolution_status` со значениями, описанными выше.
{% endstep %}
{% endstepper %}

## Чеклист

* [ ] Web SDK **1.9.10+**, Oz API **6.6.1+**.
* [ ] Шаг 1 встраивает плагин по URL, предоставленному Oz.
* [ ] Шаг 2 получает свежий `session_token` из вашего бэкенда перед каждой съемкой.
* [ ] Шаг 3 передает этот `session_token` в `OzLiveness.open(...)`.
* [ ] Шаг 4 принимает контейнер вторым аргументом `on_capture_complete`; попыток декодировать или просмотреть его в браузере нет.
* [ ] Шаг 5 отправляет контейнер запросом `POST {{host}}/api/instant/folders/` (Instant API) или `POST {{host}}/api/folders/` (Full API) в виде необработанных байтов с `Content-Type: application/octet-stream`.
* [ ] Решение о допуске или отклонении принимается только на основе `resolution_status` и `system_resolution`.
* [ ] `session_token` никогда не кэшируется, не используется повторно и не передается между сессиями или пользователями.

***

На этом базовая интеграция Web SDK в ваше веб-приложение завершена. Захваченные медиаданные и результаты анализов доступны в Web Console через браузер или программно через API (инструкции: получение MP4-видео, получение результатов анализов).

В [руководстве разработчика Web Plugin](/oz-knowledge-ru/rukovodstva/rukovodstvo-razrabotchika/sdk/websdk/web-plugin.md) описаны типичные следующие шаги:

* Настройка внешнего вида плагина
* Добавление пользовательского языкового пакета
* Настройка поведения плагина
* Параметры и коллбэки плагина
* Рекомендации по безопасности

Пример для Oz Liveness Web SDK доступен [здесь](https://gitlab.com/oz-forensics/oz-liveness-sample-web/-/blob/master/OzLivenessWebSDKSample.html). Чтобы запустить его, замените `<web-adapter-url>` на URL Web Adapter, полученный от нас.

Для Angular и React замените `https://web-sdk.<link>.com` в файле index.html.

* [Пример для Angular](https://gitlab.com/oz-forensics/oz-liveness-sample-web-angular)
* [Пример для React](https://gitlab.com/oz-forensics/oz-liveness-sample-web-react/-/tree/main)
* [Пример для Vue](https://gitlab.com/oz-forensics/oz-liveness-sample-web-vue)
* [Пример для Svelte](https://gitlab.com/oz-forensics/oz-liveness-sample-web-svelte)


---

# 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://doc.ozforensics.com/oz-knowledge-ru/obshaya-informaciya/kratkie-rukovodstva-po-integracii/kak-integrirovat-oz-liveness-v-vashe-veb-prilozhenie.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.