# Верификация телефона на своем сайте
Виджет верификации телефона снимает с вас необходимость самостоятельно отправлять код подтверждения на устройства пользователей разными способами (SMS, код в звонке, WhatsApp и другие), сверять отправленный и введенный код, следить за длительностью сессии и заботиться о безопасности отправки сообщений. Вам только понадобится интегрировать наш виджет в вашей HTML-форме и настроить закрытое взаимодействие между вашей серверной частью и сервером i-Digital Direct.
{% hint style="warning" %}
Данная инструкция предполагает встраивание виджета в web-приложение с фронтендом и защищенным бэкендом.
Для встраивания виджета в Tilda изучите инструкцию [Верификация телефона на Tilda](tilda/). Для других конструкторов сайта на данный момент виджет не предоставляется.
{% endhint %}
## Принцип работы
1. Вы настраиваете виджет верификации телефона в [личном кабинете](https://direct.i-dgtl.ru/solutions/widget-phone-confirmation). Подробную инструкцию можете найти в разделе "[Настройка виджета](set_up_widget.md#nastroika-vidzheta)".
2. Вы создаете API-ключ в [личном кабинете](https://direct.i-dgtl.ru/solutions/widget-phone-confirmation) для управления виджетом верификации телефона `{TOKEN_3}`. Подробную инструкцию можете найти в разделе "[Создание API-ключа](set_up_widget.md#sozdanie-api-klyucha)".
3. Вы встраиваете виджет в DOM-элемент своего сайта, например, в форму авторизации.
4. Пользователь выбирает способ, которым ему удобно получить код подтверждения номера из настроенных в личном кабинет.
5. Пользователь проходит капчу.
6. Виджет передает коллбэк вашему сайту с идентификатором для отправки кода подтверждения, который вам нужно передать вашей серверной части.
7. Ваша серверная часть передает запрос серверу i-Digital Direct на отправку кода подтверждения по идентификатору, используя API-ключ.
8. Сервер i-Digital Direct отправляет код подтверждения пользователю выбранным им способом.
9. Виджет отображает пользователю форму ввода кода.
10. При успешном вводе кода виджет передает коллбэк вашему сайту, при получении которого вам нужно проверить успешность подтверждения номера телефона, отправив запрос с вашей серверной части на сервер i-Digital Direct, используя API-ключ.
11. При получении подтверждения ваша система может считать устройство пользователя верифицированным и открыть пользователю доступ.
{% hint style="info" %}
Вы можете посмотреть как работает виджет на нашей форме авторизации, если у вас включена двухфакторная аутентификация: [https://direct.i-dgtl.ru/login](https://direct.i-dgtl.ru/login)
{% endhint %}
## Шаг 1. Создание учетной записи captcha
Создайте учетную запись в одном из поддерживаемых сервисов Captcha (hCaptcha, ReCaptcha, Yandex SmartCaptcha).
Это обязательный шаг для настройки виджета, подробная инструкцию создания captcha вы можете найти в статье "[Использование captcha](captcha-usage.md)".
## Шаг 2. Настройка виджета в личном кабинете
Настройте виджет в личном кабинете и создайте API-ключ для управления виджетом. Подробная инструкция по настройке описана в разделе "[Настройка виджета в личном кабинете](set_up_widget.md)".
## Шаг 3. Интеграция в ваш сайт
Подключите css и js-файлы из cdn I-Digital к странице своего сайта, где необходимо добавить виджет. Для этого добавьте следующее в \ своего сайта:
```html
```
Инициализируйте виджет на странице следующим кодом:
```javascript
window.VerifyWidget.mount('#ELEMENT_ID', {
destination: 'CLIENT_PHONE_NUMBER',
widgetId: 'YOUR_WIDGET_ID',
captchaSiteKey: 'YOUR_CAPTCHA_SITEKEY'
}, sendAuthKeyFunc, onSuccessFunc)
```
#### Описание параметров виджета:
* ELEMENT\_ID – id элемента DOM, в который будет встраиваться виджет
* destination – номер телефона абонента
* widgetId – идентификатор виджета из личного кабинета
* captchaSiteKey – **Sitekey** от hCaptcha или reСaptcha
* sendAuthKeyFunc – функция для передачи идентификатора сообщения вашему серверу
* onSuccessFunc – функция, выполняемая после ввода корректного кода пользователем
#### Пример функции sendAuthKeyFunc:
```javascript
const sendAuthKeyFunc = (key) => {
const payload = {
key
};
return fetch('YOUR_BACKEND_METHOD_URL', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(payload)
});
};
```
### Кастомизация виджета
На данный момент в виджете не предусмотрено каких-либо возможностей кастомизации при помощи параметров, но вы можете изменить стили одним из двух способов:
* переопределить стиль после загрузки нашего css-файла своими стилями;
* не загружать наш css-файл, используя вместо него свой.
Таким образом вы сможете поменять цвета, шрифт, тени, размеры элементов. При этом контентная часть виджета не редактируется (иконки, изображения, тексты, кнопки, логика работы), но вы можете скрыть эти элементы при помощи свойства `display: none`.
## Шаг 4. Интеграция с серверной частью
### Отправка кода
При необходимости отправить код подтверждения, виджет выполнит функцию `sendAuthKeyFunc.` При использовании [примера выше,](widget.md#primer-funkcii-sendauthkeyfunc) функция выполнит POST-запрос по адресу `YOUR_BACKEND_METHOD_URL` с json-контентом, в котором будет передан уникальный идентификатор для отправки кода подтверждения:
```
{
"key": "UNIQUE_VERIFICATION_KEY"
}
```
После получения запроса ваша серверная часть должна выполнить POST-запрос по адресу https://direct.i-dgtl.ru/api/v1/verifier/widget/send из-под API-ключа, передав идентификатор для отправки кода подтверждения от виджета в json-контенте.
## Метод отправки сообщения по идентификатору от виджета
`POST` `https://direct.i-dgtl.ru/api/v1/verifier/widget/send`
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ----------------- |
| Authorization\* | | Basic {TOKEN\_3} |
| Content-Type\* | String | application/json |
#### Request Body
| Name | Type | Description |
| ------------------------------------- | ------ | ---------------------------------------------------- |
| key\* | string | Уникальный идентификатор отправки кода подтверждения |
::::{tab-set}
:::{tab-item} 200: OK Код отправлен абоненту. В ответе возвращается id отправленного сообщения
```
{ messageUuid: 'SENT_MESSAGE_ID' }
```
:::
:::{tab-item} 401: Unauthorized Некорректный API-ключ
:::
:::{tab-item} 403: Forbidden Некорректный API-ключ
:::
::::
{% hint style="info" %}
Таким образом отправка кода подтверждения происходит только при подтверждении от вашей серверной части из-под закрытого API-ключа.
{% endhint %}
После этого код подтверждения будет отправлен пользователю выбранным им способом. На странице авторизации отобразится форма для ввода кода подтверждения.
{% hint style="warning" %}
Убедитесь, что ваша серверная часть отвечает 200 OK статусом на POST-запрос с уникальным идентификатором для отправки кода подтверждения, который отправляется после выполнения функции sendAuthKeyFunc. Иначе виджет не начнет проверку отправки кода подтверждения и не покажет форму для ввода кода.
{% endhint %}
{% hint style="info" %}
Информацию об отправленном пользователю сообщении с кодом подтверждения вы можете получить с помощью GET-запроса "[Получение сообщения по id](../messages/get.md)". messageUuid для отправки запроса ваша серверная часть получит в ответе при успешном [POST-запросе для отправки кода подтверждения](widget.md#otpravka-koda).
{% endhint %}
### Проверка подтверждения
После того, как пользователь прошел верификацию, виджет выполнит функцию `onSuccessFunc`. Передайте в этой функции идентификатор key вашему серверу для проверки.
Обратите внимание, что идентификатор key не передается в функцию `onSuccessFunc,` как в случае с функцией `sendAuthKeyFunc`. Поэтому во время выполнения функции `sendAuthKeyFunc` вы можете сохранить значение key в переменную и после использовать это значение при выполнении функции `onSuccessFunc`. Например:
```javascript
messageKey = ''; // переменная для будущего сохранение значения key
const sendAuthKeyFunc = (key) => {
messageKey = key;
// здесь функция отправки POST-запроса на серверную часть
};
const onSuccessFunc = () => {
const payload = {
key: messageKey,
};
return fetch('YOUR_BACKEND_METHOD_URL', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
};
```
Чтобы проверить валидность верификации по идентификатору, нужно выполнить POST-запрос по адресу https://direct.i-dgtl.ru/api/v1/verifier/widget/check, из-под API-ключа, передав идентификатор для отправки кода подтверждения от виджета в json-контенте, как и на предыдущем шаге.
В ответе будут переданы время верификации, номер абонента и информация о том, проверялась ли данная верификация ранее (таким образом вы сможете точно знать, является ли данная проверка первой). При подтверждении верификации вы можете закрыть виджет и предоставить пользователю доступ.
## Метод проверки верификации от виджета
`POST` `https://direct.i-dgtl.ru/api/v1/verifier/widget/check`
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization\* | String | Basic {TOKEN\_3} |
| Content-Type\* | String | application/json |
#### Request Body
| Name | Type | Description |
| ------------------------------------- | ------ | --------------------------------- |
| key\* | string | Уникальный идентификатор отправки |
::::{tab-set}
:::{tab-item} 200: OK В ответе возвращаются статус верификации, подтвержденный номер, дата водтв
```
{
"status": "CONFIRMED",
"destination": "79999999999",
"confirmedAt": "2023-04-01T15:41:32Z",
"firstSuccessfulCheck": true
}
```
:::
::::
#### Статусы проверки:
* CONFIRMED – номер был верифицирован;
* NOT\_FOUND – идентификатор сообщения не найден;
* UNSENT – сообщение с кодом не было отправлено;
* WRONG\_CODE – код был указан неверно.
.png)