ウィジェットの設定

data 属性または JavaScript の render パラメーターで、Turnstile ウィジェットの外観、動作、機能を設定します。

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 ウィジェットは 2 種類の固定サイズ、または幅可変サイズにできます。

• normal: デフォルトサイズです。ほとんどのデスクトップとモバイルのレイアウトに適します。サイトやフォームに十分な横幅がある場合に使います。
• flexible: 最低限の使いやすさを保ちつつ、コンテナ幅に自動で合わせます。あらゆる画面サイズで動くレスポンシブデザインに使います。
• compact: モバイル UI、サイドバー、横幅が限られる場所に適します。幅が狭い分、通常より高くなります。

	<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（デフォルト）: 訪問者のシステムテーマ設定に自動で合わせます。訪問者の設定を尊重し、アクセシビリティも高いため、ほとんどの実装では auto を推奨します。
• light: 明るい色と明確なコントラストのライトテーマです。明るい背景で読みやすく、コントラストが高くなります。
• dark: 暗い UI 向けに最適化したダークテーマです。暗いインターフェイス、ゲームサイト、ダークカラースキームのアプリに適します。

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

ウィジェット UI の言語を設定します。

• auto（デフォルト）: 訪問者のブラウザー言語設定を使います。
• 特定の言語コード: es、fr、de などの ISO 639-1 の 2 文字コードです。
• 言語と地域: 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: インタラクティブなチャレンジがタイムアウトしたときに呼び出されます。

成功コールバックはトークンを受け取ります。このトークンは Siteverify API でサーバー側検証する必要があります。トークンは 1 回限りで、300 秒（5 分）後に期限切れになります。

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

• 成功コールバックは必ず実装し、トークンを処理してフォーム送信や次の手順へ進みます。
• エラーコールバックで、失敗時の案内と訪問者へのフィードバックを行います。
• 期限切れトークンを監視し、無効になる前にチャレンジを更新します。
• タイムアウトを処理し、チャレンジ解決まで訪問者を案内します。

失敗したチャレンジへの 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 文字）。

• アクション追跡: ログイン、サインアップ、お問い合わせフォームなどを分析上で区別します。
• 訪問者コンテキスト: 訪問者 ID、セッション情報、その他の文脈データを渡します。
• 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>