← Cloudflare Turnstile / turnstile / get-started / client-side-rendering

Конфигурации виджетов

Настройте внешний вид, поведение и возможности виджета Turnstile через data-атрибуты или параметры рендеринга в JavaScript.

Виджеты Turnstile можно подключать через неявную или явную отрисовку.

	<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-theme="light"></div>

	<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit" defer></script>
	<div id="my-widget"></div>
	
	<script>
	window.onload = function() {
		turnstile.render('#my-widget', {
			sitekey: '<YOUR-SITE-KEY>',
			theme: 'light',
			callback: function(token) {
				console.log('Success:', token);
			}
		});
	};
	</script>

В режимах Managed и Non-Interactive виджет Turnstile может иметь два фиксированных размера или гибкую ширину.

• normal: размер по умолчанию подходит для большинства десктопных и мобильных макетов. Выбирайте его, если на сайте или в форме достаточно горизонтального пространства.
• flexible: автоматически подстраивается под ширину контейнера и сохраняет минимально необходимое удобство использования. Подходит для адаптивной вёрстки, которая должна работать на экранах любого размера.
• compact: подходит для мобильных интерфейсов, боковых панелей и любых мест, где мало горизонтального пространства. Компактный виджет выше обычного, чтобы компенсировать меньшую ширину.

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-size="flexible"></div>

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-size="compact"></div>

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>'
	});

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		size: 'flexible'
	});

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		size: 'compact'
	});

Настройте внешний вид виджета под дизайн вашего сайта.

• auto (по умолчанию): автоматически подстраивается под тему, выбранную в системе посетителя. Для большинства реализаций рекомендуется именно этот режим: он учитывает предпочтения посетителя и обеспечивает наилучшую доступность.
• light: светлая тема со светлыми цветами и чётким контрастом. Она лучше всего смотрится на светлом фоне и обеспечивает высокий контраст для удобного чтения.
• dark: тёмная тема, рассчитанная на тёмные интерфейсы. Она хорошо подходит для тёмных интерфейсов, игровых сайтов и приложений с тёмной цветовой схемой.

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-theme="light"></div>

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-theme="dark"></div>

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>'
	});

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		theme: 'light'
	});

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		theme: 'dark'
	});

Режим отображения определяет, когда виджет становится видимым для посетителей.

• always (по умолчанию): виджет виден с момента загрузки страницы. Для большинства реализаций это лучший вариант: посетитель сразу видит виджет и понимает, что проверка безопасности выполняется.
• execute: виджет появляется только после начала проверки. Это удобно, когда нужно управлять моментом его появления: например, показывать виджет, только когда посетитель начал заполнять форму или нажал кнопку отправки.
• interaction-only: виджет появляется только тогда, когда нужно действие посетителя, поэтому страница остаётся максимально чистой. Большинство посетителей никогда не увидят виджет, а подозрительные боты столкнутся с интерактивной проверкой.

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-appearance="execute"></div>

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-appearance="interaction-only"></div>

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>'
	});

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		appearance: 'execute'
	});

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		appearance: 'interaction-only'
	});

Определите, когда запускается проверка и создаётся токен.

• render (по умолчанию): проверка выполняется автоматически после вызова render() и защищает страницу сразу после загрузки виджета. Проверка выполняется в фоновом режиме, пока страница загружается, поэтому к моменту отправки данных токен уже готов.

• execute: проверка запускается после вызова turnstile.execute() отдельно и даёт точный контроль над моментом проверки. Такой вариант удобен для многошаговых форм, условной проверки и тех случаев, когда проверку нужно отложить до момента, когда посетитель действительно отправляет данные. Проверка запускается только при необходимости, поэтому страница загружается быстрее, а посетителю работать удобнее.

  Типичные сценарии

  • Многошаговые формы: запускайте проверку только на последнем шаге.
  • Условная защита: проверяются только посетители, которые попадают под заданные условия.
  • Оптимизация производительности: отложите проверку, чтобы сократить время первой загрузки страницы.
  • Проверка по действию пользователя: посетитель запускает проверку вручную.

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-execution="execute"></div>

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>'
	});

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		execution: 'execute'
	});

	turnstile.execute('#widget-container');

Задайте язык интерфейса виджета.

• auto (по умолчанию): используется язык, заданный в браузере посетителя.
• Коды конкретных языков: двухбуквенные коды ISO 639-1, например es, fr, de.
• Язык и регион: составные коды для региональных вариантов, например en-US, es-MX, pt-BR.

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-language="es"></div>

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-language="en-US"></div>

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>'
	});

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		language: 'es'
	});

Обрабатывайте события виджета с помощью функций обратного вызова.

• callback: срабатывает при успешном прохождении проверки.
• error-callback: срабатывает при ошибке во время проверки.
• expired-callback: срабатывает, когда истекает срок действия токена (до истечения времени ожидания).
• timeout-callback: срабатывает, когда истекает время ожидания интерактивной проверки.

Callback успешного завершения получает токен, который нужно проверить на вашем сервере через Siteverify API. Токен одноразовый и истекает через 300 секунд (пять минут).

	<div class="cf-turnstile"
		data-sitekey="<YOUR-SITE-KEY>"
		data-callback="onSuccess"
		data-error-callback="onError"
		data-expired-callback="onExpired"
		data-timeout-callback="onTimeout"></div>
	<script>
	function onSuccess(token) {
	console.log('Challenge Success:', token);
	}
	function onError(errorCode) {
	console.log('Challenge Error:', errorCode);
	}
	function onExpired() {
	console.log('Token expired');
	}
	function onTimeout() {
	console.log('Challenge timed out');
	}
	</script>

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		callback: function(token) {
			console.log('Challenge Success:', token);
		},
		'error-callback': function(errorCode) {
			console.log('Challenge Error:', errorCode);
		},
		'expired-callback': function() {
			console.log('Token expired');
		},
		'timeout-callback': function() {
			console.log('Challenge timed out');
		}
	});

• Всегда реализуйте обратный вызов success: он получает токен и запускает отправку формы или следующие шаги.
• Используйте error-callback, чтобы корректно обрабатывать ошибки и сообщать о них посетителю.
• Следите за истечением срока действия токенов и обновляйте проверку до того, как токен перестанет быть действительным.
• Обрабатывайте тайм-ауты, чтобы помочь посетителям пройти проверку.

Настройте, как Turnstile обрабатывает неуспешные проверки.

• auto (по умолчанию): неудачные проверки повторяются автоматически. Автоматический повтор удобнее для посетителя, потому что временные сбои сети и ошибки обработки устраняются без его участия.
• never: отключает автоматические повторные попытки. Потребуется вмешательство вручную, зато вы полностью контролируете обработку ошибок в приложениях со своей логикой повторов.
• retry-interval: задаёт интервал между повторными попытками (по умолчанию: 8000ms) и позволяет выбрать баланс между быстрым восстановлением и нагрузкой на сервер.

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-retry="never"></div>

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-retry-interval="0000"></div>

Настройте, как Turnstile обрабатывает истечение срока действия токена и тайм-ауты интерактивной проверки.

• refresh-expired: управляет поведением при истечении срока действия токена (auto, manual, never).
• refresh-timeout: управляет поведением при истечении времени интерактивной проверки (auto, manual, never).

• auto не требует действий от посетителя, но расходует больше ресурсов.
• manual даёт посетителям контроль, но требует от них действий.
• never требует, чтобы вся логика обновления была реализована в вашем приложении.

В зависимости от требований к работе посетителей для истечения срока действия токена и для тайм-аутов интерактивной проверки можно задать разные стратегии.

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-refresh-expired="manual"></div>

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-refresh-timeout="auto"></div>

Добавляйте к проверкам собственные идентификаторы и данные.

• action: собственный идентификатор для аналитики и различения виджетов (не более 32 символов).
• cData: произвольные данные, которые возвращаются при проверке токена (не более 255 символов).

• Отслеживание действий: различайте в аналитике формы входа, регистрации, обратной связи и другие.
• Контекст посетителя: передавайте идентификаторы посетителей, данные сессии или другие контекстные сведения.
• A/B-тестирование: отслеживайте разные конфигурации виджета или варианты страницы.
• Выявление мошенничества: добавьте дополнительный контекст для оценки рисков.

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-action="login"></div>

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-cdata="user-cdata"></div>

Настройка интеграции Turnstile с формами HTML.

Если этот параметр включён, Turnstile автоматически создаёт скрытый <input> с токеном проверки. Он отправляется вместе с остальными данными формы, поэтому проверка на сервере не требует дополнительных усилий.

• response-field: определяет, создавать ли скрытое поле формы с токеном (default: true)
• response-field-name: собственное имя скрытого поля формы (default: cf-turnstile-response)

• Автоматическая интеграция с формой означает, что токен уходит вместе с отправкой формы и дополнительный JavaScript не нужен.
• Собственные имена полей помогают избежать конфликтов с уже существующими полями формы.
• Отключённые поля ответа дают полный контроль над обработкой токена в сложных сценариях с формами.

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-response-field-name="turnstile-token"></div>

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-response-field="false"></div>

<div style="max-width: 500px;">
  <div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-size="flexible" data-theme="auto"></div>
</div>

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-size="compact" data-theme="light" data-language="en">
</div>