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

Konfigurace widgetů

Vzhled, chování i funkce widgetu Turnstile nastavíte pomocí data atributů nebo parametrů renderování v JavaScriptu.

Widgety Turnstile lze implementovat pomocí implicitního nebo explicitního vykreslování.

	<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>

V režimech Managed a Non-Interactive může mít widget Turnstile dvě různé pevné velikosti nebo pružnou šířku.

• normal: Výchozí velikost vyhovuje většině rozvržení na počítači i mobilu. Použijte ji, pokud máte na webu nebo ve formuláři dostatek místa na šířku.
• flexible: Automaticky se přizpůsobí šířce kontejneru a zachová minimální použitelnost. Hodí se pro responzivní návrhy, které musí fungovat na všech velikostech obrazovky.
• compact: Vhodné pro mobilní rozhraní, postranní panely nebo místa s omezenou šířkou. Kompaktní widget je vyšší než běžný, aby vyrovnal menší šířku.

	<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'
	});

Přizpůsobte vzhled widgetu designu svého webu.

• auto (výchozí): Automaticky se přizpůsobí motivu nastavenému v systému návštěvníka. Pro většinu implementací doporučujeme auto, protože respektuje předvolby návštěvníka a nabízí nejlepší přístupnost.
• light: Světlý motiv se světlými barvami a jasným kontrastem. Nejlépe funguje na světlém pozadí a díky vysokému kontrastu je text dobře čitelný.
• dark: Tmavý motiv optimalizovaný pro tmavá rozhraní. Hodí se pro tmavá rozhraní, herní weby nebo aplikace s tmavým barevným schématem.

	<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'
	});

Pomocí režimu appearance určete, kdy se widget návštěvníkům zobrazí.

• always (výchozí): Widget je viditelný od načtení stránky. Pro většinu implementací je to nejlepší volba, protože návštěvník widget uvidí okamžitě a dostane jasnou vizuální informaci, že bezpečnostní ověření běží.
• execute: Widget se zobrazí až po zahájení výzvy. To se hodí, když potřebujete řídit okamžik jeho zobrazení, například až návštěvník začne vyplňovat formulář nebo stiskne tlačítko pro odeslání.
• interaction-only: Widget se zobrazí jen tehdy, když je potřeba interakce návštěvníka, což je pro návštěvníky nejméně rušivé. Většina z nich widget nikdy neuvidí, podezřelí boti ale narazí na interaktivní výzvu.

	<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'
	});

Určete, kdy se výzva spustí a kdy se vygeneruje token.

• render (výchozí): Ověření proběhne automaticky po zavolání render() a poskytuje ochranu okamžitě po načtení widgetu. Výzva probíhá na pozadí už během načítání stránky, takže token je připravený ve chvíli, kdy návštěvník odesílá data.

• execute: Výzva se spustí až po zavolání turnstile.execute() zvlášť a dává vám přesnou kontrolu nad tím, kdy ověření proběhne. Tato možnost se hodí pro vícekrokové formuláře, podmíněné ověřování nebo pro případy, kdy chcete výzvu odložit až na okamžik, kdy se návštěvník skutečně pokusí odeslat data. Ověření pak běží jen tehdy, když je potřeba, což zlepšuje rychlost načtení stránky i komfort návštěvníka.

  Časté scénáře

  • Vícekrokové formuláře: ověření spouštějte až v posledním kroku.
  • Podmíněná ochrana: ověřujte pouze návštěvníky, kteří splňují určitá kritéria.
  • Optimalizace výkonu: odložte ověření, zkrátíte tím dobu prvního načtení stránky.
  • Ověření spuštěné uživatelem: návštěvník zahájí ověření ručně.

	<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');

Nastavte jazyk rozhraní widgetu.

• auto (výchozí): Použije jazyk nastavený v prohlížeči návštěvníka.
• Kódy konkrétních jazyků: dvoupísmenné kódy podle ISO 639-1, například es, fr, de.
• Jazyk a region: kombinované kódy pro regionální varianty, například 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'
	});

Zpracujte události widgetu pomocí callbacků.

• callback: Vyvolá se, když je výzva úspěšně dokončena.
• error-callback: Vyvolá se, když během výzvy dojde k chybě.
• expired-callback: Vyvolá se, když vyprší platnost tokenu (před vypršením časového limitu).
• timeout-callback: Vyvolá se, když u interaktivní výzvy vyprší časový limit.

Callback pro úspěch dostane token, který musíte ověřit na svém serveru přes Siteverify API. Tokeny jsou jednorázové a vyprší po 300 sekundách (pěti minutách).

	<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');
		}
	});

• Vždy implementujte success callback, který token zpracuje a umožní odeslání formuláře nebo další krok.
• Používejte error callbacky, aby se chyby ošetřily elegantně a návštěvník dostal zpětnou vazbu.
• Sledujte vypršené tokeny a obnovujte výzvy dříve, než přestanou platit.
• Ošetřete vypršení časového limitu, aby návštěvník věděl, jak výzvu dokončit.

Nastavte, jak má Turnstile řešit neúspěšné ověřovací výzvy.

• auto (výchozí): Neúspěšná ověření se automaticky opakují. Automatické opakování je pro návštěvníka příjemnější, protože se samo zotaví z dočasných potíží se sítí i z chyb při zpracování.
• never: Vypne automatické opakování. Vyžaduje ruční zásah a dává vám plnou kontrolu nad zpracováním chyb v aplikacích, které potřebují vlastní logiku opakování.
• retry-interval: Řídí prodlevu mezi opakovanými pokusy (výchozí hodnota: 8000ms) a umožňuje vyvážit rychlost obnovy a zátěž serveru.

<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>

Nastavte, jak má Turnstile řešit vypršení platnosti tokenu a časové limity interaktivní výzvy.

• refresh-expired: Řídí chování při vypršení platnosti tokenů (auto, manual, never).
• refresh-timeout: Řídí chování při vypršení časového limitu interaktivních výzev (auto, manual, never).

• auto probíhá pro návštěvníka plynule, spotřebuje ale více prostředků.
• manual dává kontrolu návštěvníkům, ti ale musí sami zasáhnout.
• never vyžaduje, aby veškerou logiku obnovení řešila vaše aplikace.

Pro vypršení platnosti tokenu a pro časové limity interaktivní výzvy můžete zvolit různé strategie podle toho, jaké prostředí chcete návštěvníkům nabídnout.

<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>

Přidejte ke svým výzvám vlastní identifikátory a data.

• action: Vlastní identifikátor pro analytiku a rozlišení widgetů (maximálně 32 znaků).
• cData: Vlastní data, která se vrátí při ověření (maximálně 255 znaků).

• Sledování akcí: v analytice rozlišíte přihlášení, registraci, kontaktní formuláře a další.
• Kontext návštěvníka: předejte ID návštěvníka, informace o relaci nebo další kontextová data.
• A/B testování: sledujte různé konfigurace widgetu nebo varianty stránky.
• Detekce podvodů: doplňuje další kontext pro vyhodnocení rizika.

<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>

Nastavte, jak se Turnstile propojí s HTML formuláři.

Když je tato možnost zapnutá, Turnstile automaticky vytvoří skrytý prvek <input> element s ověřovacím tokenem. Odešle se spolu s ostatními daty formuláře, takže validace na serveru je přímočará.

• response-field: Určuje, zda se má vytvořit skryté pole formuláře s tokenem (default: true)
• response-field-name: Vlastní název skrytého pole formuláře (default: cf-turnstile-response)

• Automatická integrace s formulářem znamená, že se token odešle spolu s formulářem a není potřeba žádný další JavaScript.
• Vlastní názvy polí pomáhají předejít konfliktům se stávajícími poli formuláře.
• Vypnutá pole s odpovědí vám dají plnou kontrolu nad prací s tokenem ve složitějších formulářích.

<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>