← Cloudflare Turnstile / turnstile / concepts
Виджеты Turnstile
Виджет Turnstile определяет, как Turnstile ведёт себя на вашей веб-странице. У каждого виджета есть режим, название, sitekey, а также секретный ключ. Вы можете создать несколько виджетов с разными настройками.
Turnstile размещается на challenges.cloudflare.com. Ваше приложение будет подключаться к этому источнику. Если на вашем сайте используется Content Security Policy, необходимо разрешить подключения к этому домену.
Компоненты виджета
У каждого виджета своя пара sitekey и secret key, а также собственный набор параметров.
| Компонент | Описание |
|---|---|
| Sitekey | Открытый ключ для вызова виджета Turnstile на вашем сайте. |
| Секретный ключ | Закрытый ключ для проверки токена на стороне сервера. |
| Конфигурации | Режим, имена хостов, настройки внешнего вида и другие параметры. |
Режимы виджета
Для виджетов Turnstile доступны режимы Managed, Non-Interactive, а также Invisible.
| Режим виджета | Описание | Сценарий использования |
|---|---|---|
| Managed (рекомендуется) | Автоматически выбирает между неинтерактивной проверкой и флажком, ориентируясь на уровень риска посетителя. Никаких картинок и текста, которые нужно разгадывать. | Простая настройка с адаптивной защитой. Баланс между защитой и удобством для пользователя. |
| Non-Interactive | Показывает видимый виджет с индикатором загрузки. Проверки выполняются без участия посетителя. | Сводит неудобства для посетителя к минимуму и при этом показывает, что проверка выполняется. |
| Invisible | Выполняет проверки полностью в фоновом режиме, без видимого виджета и индикаторов загрузки. | Максимально чистый внешний вид: видимых элементов проверки нет. |
Режим Managed (рекомендуется)
Режимом Managed полностью управляет Cloudflare. Подходящее действие выбирается автоматически, по сигналам на стороне клиента и уровню риска. На основании данных о посетителе Cloudflare решает, нужна ли интерактивная проверка.
Turnstile попросит посетителя о действии только тогда, когда нужна дополнительная проверка того, что перед нами человек. В этом случае посетителю будет предложено отметить флажок. Никаких изображений или текста разгадывать не придётся.
Режим Managed подойдёт тем, кому нужна простая настройка без тонкой подстройки поведения виджета.
Режим Non-Interactive
Посетитель увидит виджет с индикатором загрузки, пока в его браузере выполняются проверки. В отличие от режима managed, взаимодействие с виджетом от посетителя никогда не потребуется и даже не будет предложено.
Режим Non-Interactive подойдёт тем, для кого важнее всего удобство посетителей и кто не хочет усложнять работу с сайтом взаимодействием с Turnstile.
Режим Invisible
Режим Invisible похож на режим Non-Interactive: посетитель никогда не взаимодействует с виджетом Turnstile. При этом он не видит ни самого виджета, ни каких-либо признаков того, что в браузере идёт скрытая проверка.
Режим Invisible подойдёт тем, для кого важнее всего удобство посетителей и внешний вид сайта.
Кастомизация виджета
Размеры
Виджеты можно использовать в размерах normal, flexible или compact.
См. Конфигурации виджетов, где приведены подробные параметры настройки и примеры кода.
Внешний вид и темы
Виджеты Turnstile поддерживают несколько режимов отображения и тем, чтобы соответствовать оформлению вашего сайта.
См. Конфигурации виджетов, где описаны детали реализации.
Состояния виджета
flowchart LR
accTitle: Normal widget operation states
accDescr: This diagram details a Turnstile widget's normal operation states.
A[<b>Loading</b><br /><small>Widget is processing the challenge.</small> ] --> B[<b>Interaction*</b><br /><small>Visitor needs to check the box. <br />*Managed mode only.</small>]
B --> C[<b>Success</b><br /><small>The Challenge was completed successfully.</small>]
Состояния ошибок
Тип |
Описание |
|---|---|
| Неизвестная ошибка | Это состояние виджета появляется, когда во время проверки возникает неизвестная ошибка. Посетитель может воспользоваться подсказками по устранению неполадок в самом виджете или обновить страницу, чтобы пройти проверку заново. |
| Время ожидания взаимодействия истекло | Посетителю показан флажок, но он долго с ним не взаимодействует. Проверку нужно выдать заново, перезагрузив страницу или виджет. |
| Время проверки истекло | Если верификация прошла, но дальше ничего не произошло, результат проверки перестаёт быть действительным. Например, виджет Turnstile стоит на странице входа и отработал успешно, но посетитель долго не выполнял вход: тогда проверку нужно выдать заново, перезагрузив страницу или виджет. |
| Устаревший или неподдерживаемый браузер | Это состояние виджета увидят посетители с устаревшими или неподдерживаемыми браузерами. См. Поддерживаемые браузеры, где перечислены поддерживаемые браузеры. |