# WebSDK

# Интеграция WebSDK

Чтобы начать интеграцию WebSDK нужно:

Сгенерировать временный токен доступа accessToken, как это описано в разделе Начало работы.
Установить NPM-пакет или CDN-версию скрипта и запустить инициализацию с токеном доступа, как это описано ниже.
Если вы повторно используете токены доступа, убедитесь, что настроили обработчик истечения срока действия токена.

# Настройка интеграции

Установите пакет NPM:

      npm
    
      yarn
    
Copy
npm i @cyberity/websdk --save   
yarn add @cyberity/websdk  

Импортируйте модуль cyberitySdk:

  import cyberitySdk from '@cyberity/websdk';

Создайте контейнер для WebSDK на своей странице.

  <!-- iframe будет вставлен как дочерний элемент -->
  <div id="cyberity-websdk-container"></div>

Инициализируйте WebSDK:

/**
 * @param accessToken - access token, который вы сгенерировали на бэкенде
 * @param applicantEmail - email пользователя (необязательно)
 * @param applicantPhone - телефон пользователя, если есть (необязательно)
 */
function launchWebSdk(accessToken, applicantEmail, applicantPhone) {
  let sdkInstance = cyberitySdk.init(
    accessToken,
    // коллбэк для обновления токена, должен возвращать Promise
    // access token истёк
    // получите новый и передайте его в коллбэк для повторного запуска WebSDK
    () => this.getNewAccessToken()
  )
    .withConf({
      lang: 'ru', //язык текста и комментариев WebSDK (в формате ISO 639-1)
      email: applicantEmail,
      phone: applicantPhone,
    })
    .on('idCheck.stepCompleted', (payload) => {
      console.log('stepCompleted', payload)
    })
    .on('idCheck.onError', (error) => {
      console.log('onError', error)
    })
    .build();

  //запустите WebSDK, указав элемент-контейнер
  sdkInstance.launch('#websdk-container');
}

function getNewAccessToken() {
  return Promise.resolve(newAccessToken) // получите новый токен с вашего бэкенда
}

Убедитесь, что при инициализации SDK был предоставлен именно accessToken, а не токен другого типа.

# Конфигурация WebSDK

Здесь вы найдете информацию о параметрах конфигурации, типах сообщений WebSDK и их полезной нагрузке.

Поля элемента withConf

Название	Тип	Обязательно	Описание
`lang`	String	Нет	Язык текстов и комментариев WebSDK в формате ISO 639-1 (по умолчанию — `en`).
`country`	String	Нет	Трехбуквенный код страны Альфа-3 (например `RUS`) для предварительного заполнения на экране загрузки документа.
`email`	String	Нет	Электронная почта пользователя.
`phone`	String	Нет	Номер телефона пользователя.
`i18n`	JSON	Нет	Ваши уникальные переводы SDK, которые будут динамически изменяться при инициализации. Формат и тексты по умолчанию вы можете найти в разделе «Переводы SDK».
`uiConf`	Object	Нет	Ваши уникальные настройки SDK.
`documentDefinitions`	Object	Нет	Определения на экране `doCapture`.

Поля элемента uiConf

Название	Тип	Обязательно	Описание
`customCss`	String	Нет	URL-адрес вашего внешнего CSS-файла, чтобы SDK использовал его при инициализации.
`customCssStr`	String	Нет	Строка с изменениями в CSS.
`scrollIntoView`	Boolean	Нет	Отключает/включает автоматическую прокрутку SDK при переключении экрана (по умолчанию — `true`).

Структура элемента documentDefinitions

documentDefinitions представляет собой объект типа «ключ — значение» {idDocSetType: documentDefinition}, где ключами являются idDocSetType, а значениями - documentDefinition.

# Пример

documentDefinitions: {
  IDENTITY: {idDocType: 'PASSPORT', country: 'GBR'}
}

Поля элемента documentDefinition

Название	Тип	Обязательно	Описание
`country`	String	Да	Трехбуквенный код страны Альфа-3 (например `RUS`).
`idDocType`	String	Да	Тип документа.

Доступные значения idDocSetType

Название	Описание
`IDENTITY`	Шаг проверки удостоверения личности.
`IDENTITY2`	Шаг проверки 2-го удостоверения личности.
`IDENTITY3`	Шаг проверки 3-го удостоверения личности.
`IDENTITY4`	Шаг проверки 4-го удостоверения личности.

См. список шагов верификации.

Поля элемента withOptions

Название	Тип	Обязательно	Описание
`addViewportTag`	Boolean	Нет	Добавляет мета-тег iFrame `viewport` для адаптации SDK под мобильные устройства (по умолчанию — `true`).
`adaptIframeHeight`	Boolean	Нет	Позволяет нашему SDK адаптировать свою высоту в зависимости от размера страницы/экрана (по умолчанию — `true`).

# Пример WebSDK

Ниже приведен полностью рабочий пример. Просто замените $ACCESS_TOKEN на соответствующее значение.

      html
    
      main.js
    
Copy
<!DOCTYPE html>
<html lang = "en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title> Verification </title>
</head>
<body>
    <div id="websdk-container"></div>
    <script type="module" src="main.js"></script>
</body>
import cyberitySdk from '@cyberity/websdk';

function launchWebSdk(accessToken, applicantEmail, applicantPhone) {
  let cbrWebSdkInstance = cyberitySdk.init(
          accessToken,
          () => this.getNewAccessToken()
      )
      .withConf({
          lang: 'en',
          email: applicantEmail,
          phone: applicantPhone,
          i18n: {"document":{"subTitles":{"IDENTITY": "Upload a document that proves your identity"}}},
          onMessage: (type, payload) => {
              console.log('WebSDK onMessage', type, payload)
          },
          uiConf: {
              customCssStr: ":root {\n  --black: #000000;\n   --grey: #F5F5F5;\n  --grey-darker: #B2B2B2;\n  --border-color: #DBDBDB;\n}\n\np {\n  color: var(--black);\n  font-size: 16px;\n  line-height: 24px;\n}\n\nsection {\n  margin: 40px auto;\n}\n\ninput {\n  color: var(--black);\n  font-weight: 600;\n  outline: none;\n}\n\nsection.content {\n  background-color: var(--grey);\n  color: var(--black);\n  padding: 40px 40px 16px;\n  box-shadow: none;\n  border-radius: 6px;\n}\n\nbutton.submit,\nbutton.back {\n  text-transform: capitalize;\n  border-radius: 6px;\n  height: 48px;\n  padding: 0 30px;\n  font-size: 16px;\n  background-image: none !important;\n  transform: none !important;\n  box-shadow: none !important;\n  transition: all 0.2s linear;\n}\n\nbutton.submit {\n  min-width: 132px;\n  background: none;\n  background-color: var(--black);\n}\n\n.round-icon {\n  background-color: var(--black) !important;\n  background-image: none !important;\n}"
          },
          onError: (error) => {
              console.error('WebSDK onError', error)
          },
      })
      .withOptions({ addViewportTag: false, adaptIframeHeight: true})
      .on('idCheck.stepCompleted', (payload) => {
          console.log('stepCompleted', payload)
      })
      .on('idCheck.onError', (error) => {
          console.log('onError', error)
      })
      .onMessage((type, payload) => {
          console.log('onMessage', type, payload)
      })
      .build();
  cbrWebSdkInstance.launch('#cyberity-websdk-container')
}

function getNewAccessToken() {
  return Promise.resolve($NEW_ACCESS_TOKEN)
}

launchWebSdk($ACCESS_TOKEN)

# Сообщения WebSDK

Обработчик on позволяет получать сообщения от WebSDK о различных важных событиях, таких как изменения статуса анкеты пользователя, действиях пользователя (actions) и т. д. Все сообщения имеют префикс idCheck.

Вы можете увидеть все эти сообщения в консоли разработчика браузера (DevTools), если запустите WebSDK из нашего Дешборда.

Тип сообщения	Полезная нагрузка	Описание
`onReady`	// id of the iframe in the current context {}	Ресурсы WebSDK загружены.
`onError`	{ "code": "invalid-origin" \| "initialization-error" \| "invalid-token" \| "invalid-config" \| "bad-request", "error": "Error message" }	Ошибка верификации. Подробности об ошибке написаны в поле "error".
`onInitialized`	{}	На устройстве пользователя отобразился первый экран.
`onStepInitiated`	{ "idDocSetType": "$idDocSetType", "types": ["$idDocType1", "$idDocType2"] }	Отображен экран, соответствующий `$idDocSetType`.
`onStepCompleted` или `stepCompleted`	{ "step": "$idDocSetType" }	Завершен шаг проверки `$idDocSetType`.
`onApplicantLoaded`	{ "applicantId": "$id" }	Пользователь с идентификатором `$id` загружен.
`onApplicantSubmitted`	{}	Документы отправлены на проверку.
`applicantStatus`	{ "reprocessing": false, "levelName": "$levelName", "createDate": "$createDate", "expireDate": "$expireDate", "reviewStatus": "$reviewStatus", "autoChecked": false }	Статус проверки пользователя изменен.
`onApplicantResubmitted`	{}	Документы отправлены на проверку повторно.
`onUploadError`	{ "code": "$error", "msg": "Error message" }	Загруженный документ отклонен. Доступные значения см. здесь
`onUploadWarning`	{ "code": "$warning", "msg": "Warning message" }	Предупреждение о загруженном документе. В поле `msg` указано предупреждениее, см. здесь.
`onActionSubmitted`	{}	Действие пользователя отправлено на проверку.
`onActionCompleted`	{ "action": "$actionType", "applicantActionId": "$id", "answer": "$answer" }	Проверка действия пользователя `$id` завершена.
`onModuleResultPresented`	{ "answer": "GREEN" }	Пользователю показан результат проверки. (`GREEN`/`YELLOW`/`RED`)

# Вебхуки

Ваш бэкенд получает результаты через вебхуки. Вы можете получать результаты по электронной почте или в Telegram, но для использования в Основном окружении (Production) мы рекомендуем задать ваш собственный эндпоинт для вебхука, который мы будем вызывать по мере необходимости.

URL-адрес, на который вы будете получать результаты, можно задать в разделе «Менеджер вебхуков».

# Получение результатов верификации

Вы всегда можете самостоятельно проверить статус пользователя с помощью данного эндпоинта, однако мы не рекомендуем использовать API-запросы в качестве базового метода получения результатов верификации и настоятельно рекомендуем использовать вебхуки.

На случай, если по какой-то причине вебхук не был получен, мы записываем всё, что пытаемся отправить вам, и можем повторно отправить вебхук в любой момент. Если вебхук не удается отправить, мы делаем это повторно четыре раза: через 5 минут, 1 час, 5 и 18 часов, до тех пор пока запрос не будет успешным. Поэтому проверяйте поле createdAt полезной нагрузки вебхука, чтобы убедиться, что вы получаете актуальный статус пользователя. Рекомендуем вам дожидаться вебхука не более суток, а затем отправить запрос на наш сервер для получения информации о статусе пользователя.

Отслеживать статусы вебхуков и отправлять их вручную можно в соответствующем разделе «Панель разработчика».

Важно:

Обратите внимание, что мы можем отправить несколько финальных вебхуков, поэтому будьте готовы к тому, что статус пользователя будет изменен и на вашей стороне. Типичным примером является ситуация, когда пользователь был одобрен, но позже он был признан мошенником, и поэтому мы блокируем его вторым финальным вебхуком RED.

В Тестовом окружении (Sandbox) проверки не запускаются автоматически и, соответственно, вебхуки также не отправляются автоматически. Поэтому либо попросите нас сделать это вручную, либо запустите вебхук самостоятельно этим API-запросом.
Как только интеграция будет завершена, и вы перейдете в Основное окружение (Production), вебхуки будут отправляться автоматически после завершения процедуры верификации.

# Персонализация WebSDK

Мы предоставляем возможность использовать ваш собственный брендинг в WebSDK и email-уведомлениях: можно настроить логотипы, тексты, CSS и внешние ссылки на ваш домен.

Основные настройки можно найти на вкладках «Брендинг» и «Настройки WebSDK» в Дешборд. Изменить тексты SDK на разных языках можно в разделе «Переводы SDK».

Более подробную информацию вы найдете в подсказках Дешборда.

# Внешние ссылки WebSDK

По умолчанию, если вы настроите отправку писем с нашей стороны, пользователь получит ссылку на наш WebSDK, размещённый на домене api.cyberity.ru. То же самое относится к ссылкам WebSDK «Продолжить на телефоне» и к QR-кодам.

Через «Настройки WebSDK» в Дешборде вы можете задать параметр «Внешняя ссылка WebSDK», который изменит домен ссылки и добавит ключ JWT для проверки подлинности ссылки. Для этого необходимо инициализировать WebSDK на вашей стороне, используя динамическую ссылку с JWT и его подтверждённым значением. Значение JWT содержит externalUserId (идентификатор пользователя) и clientId (ваш идентификатор в нашей системе). Это позволит вам отправлять запросы и использовать правильный accessToken. Токен генерируется с использованием алгоритма HMACSHA256, а секретный ключ используется без кодирования для создания подписи JWT.

# Пример пользовательской ссылки

Ваш URL-адрес: https://your-project.io/kyc
Секретный ключ для подписи ссылки пользователя: 1
externalUserId: userId_8
clientId: your-project

Пример итоговой ссылки:

https://your-project.io/kyc?jwt=eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2MjAwNTI1MjcsImV4cCI6MTYyMDY1NzMyNywic3ViIjoidXNlcklkXzgiLCJhdWQiOiJzdW1zdWIifQ.qCR-4VMfC_zOAN1hCtbjj9DJxmB6c0sEg7XD5Y8ZvvM

Пример полезной нагрузки данных JWT:

{
  "iat": 1620052527, // Время выпуска (в секундах с начала эпохи Unix)
  "exp": 1620657327, // Действителен до (в секундах с начала эпохи Unix)
  "sub": "userId_8", // Внешний ID аппликанта (externalUserId)
  "aud": "your-project" // Ваш идентификатор (clientId) 
}

# Email-уведомления для пользователей

Отправку email-уведомлений пользователям можно настроить, выбрав нужные параметры для «Уведомления по эл. почте» в настройках уровня.

Чтобы использовать брендированные email-уведомления, необходимо в разделе «Брендинг» добавить:

Иконку,
Логотип,
Email-адрес отправителя в поле «Отправлять электронные письма клиентам от».

Все тексты писем можно изменить для каждого языка в разделе «Переводы SDK».

Если вы хотите разрешить нам отправлять письма от имени вашего домена, необходимо настроить записи SPF и DKIM на вашем DNS-сервере.

# SPF

Создайте или отредактируйте запись SPF для ссылки на IDnGO.
В настройках DNS вашего домена добавьте запись типа .TXT.

Мы рекомендуем использовать следующую запись SPF:

v=spf1 include:_spf.cyberity.ru ~all

Если вы уже задали SPF-запись для другой цели, вы можете просто добавить ссылку на IDnGO:

include:_spf.cyberity.ru

Внимание:

Отсутствие настроенной SPF-записи приведет к блокировке наших писем пользователям. В этом случае email-рассылка будет автоматически отключена с нашей стороны.

# DKIM

Отредактируйте настройки DNS вашего домена, чтобы добавить записи CNAME.

Записи CNAME должны иметь следующий вид:

cyberity1._domainkey CNAME cyberity1._domainkey.cyberity.ru.
cyberity2._domainkey CNAME cyberity2._domainkey.cyberity.ru.

Проверить корректность записи можно с помощью следующих инструментов:

# Рекомендации

# Использование WebView

Для инициализации WebSDK в мобильном приложении с помощью WebView убедитесь, что:

WebView может получить доступ к локальному хранилищу устройства и инициализировать камеру (для старых версий iOS доступ к камере возможен только через браузер Safari или WebView с помощью SFSafariViewController);
Воспроизведение HTML5-видео разрешено (мы используем некоторые инструкции в тегах <video>). Если видеоинструкции не воспроизводятся, попробуйте использовать WebChromeClient, чтобы разрешить воспроизведение видео;
Автовоспроизведение в полноэкранном режиме отключено, и allowsInlineMediaPlayback задает значение true для WebView с запущенным SDK.

# Доступ к камере

Если у вас возникли проблемы с доступом к камере для проверки живости (liveness), убедитесь, что:

Заголовок Feature-Policy для вашей веб-страницы/фрейма не имеет никаких ограничений на инициализацию камеры (например, значение camera 'none');
Заголовок Permissions-Policy не ограничивает доступ к камере и микрофону, а если установлен параметр allow, то проверьте значения camera; microphone;
Ваш сайт работает по защищенному HTTPS-соединению.

# Размещение

Для наилучшей конверсии попробуйте инициализировать SDK по центру экрана, чтобы пользователям было проще следовать инструкциям в процессе верификации.

Iframe SDK изменяет размер относительно своего контейнера и содержимого экрана SDK, поэтому сам контейнер не должен иметь статичный размер, а должен подстраиваться под размер экрана. Попробуйте использовать теги <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">.