クライアントサイドレンダリング

ウェブページ上でTurnstileウィジェットを暗黙的または明示的にレンダリングすることで初期化およびカスタマイズできます。

Turnstileウィジェットを暗黙的にレンダリングする

HTMLはcf-turnstileクラス名を持つ要素をスキャンします：

<div class="cf-turnstile" data-sitekey="yourSitekey" data-callback="javascriptCallback"></div>

チャレンジが解決されると、トークンが成功コールバックに渡されます。このトークンは、私たちのsiteverifyエンドポイントに対して検証する必要があります。トークンは一度だけ検証でき、二度消費することはできません。

チャレンジを構成するには、データ属性とレンダーパラメータを含む構成を参照してください。

フォームを保護する

Turnstileは、ログインフォーム、連絡フォームなどのウェブサイト上のフォームを保護するために頻繁に使用されます。JavaScriptスクリプトタグを挿入した後、<div class="cf-turnstile"></div>をサイトに埋め込むことでフォームを保護できます。

<form action="/login" method="POST">
   <input type="text" placeholder="username"/>
   <input type="password" placeholder="password"/>
   <div class="cf-turnstile" data-sitekey="<YOUR_SITE_KEY>"></div>
   <button type="submit" value="Submit">ログイン</button>
</form>

cf-turnstile-responseという名前の不可視入力が追加され、他のフィールドと共にサーバーに送信されます。

暗黙的レンダリングを無効にする

スクリプトを以下のように置き換えることで、暗黙的レンダリングを無効にできます：

https://challenges.cloudflare.com/turnstile/v0/api.js

次のように：

https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit

render=explicitを使用すると、cf-turnstileクラスを持つHTML要素はチャレンジを表示しません。turnstile.render関数は以下の手順を使用して呼び出す必要があります。両方のオプションを組み合わせるには、?render=explicit&onload=onloadTurnstileCallbackのクエリ文字列を渡します：

https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit&onload=onloadTurnstileCallback

Turnstileウィジェットを明示的にレンダリングする

JavaScriptタグと関連コードを以下に挿入します。.cf-turnstileのクラス名を#example-containerに変更したことを確認してください（上記のようにrender=explicitクエリ文字列オプションを設定しない場合でも、そうでなければレンダリングされます）。スクリプトが埋め込まれると、カスタマイズ可能な複数のコールバックオプションを持つグローバル関数にアクセスできます。以下の関数が正しく機能するためには、ページにID example-containerを持つHTML要素が含まれている必要があります。

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?onload=onloadTurnstileCallback" defer></script>

window.onloadTurnstileCallback = function () {
    turnstile.render('#example-container', {
        sitekey: '<YOUR_SITE_KEY>',
        callback: function(token) {
            console.log(`チャレンジ成功 ${token}`);
        },
    });
};

または：

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit"></script>

// 同期読み込みを使用している場合、DOMが準備でき次第呼び出されます
turnstile.ready(function () {
    turnstile.render('#example-container', {
        sitekey: '<YOUR_SITE_KEY>',
        callback: function(token) {
            console.log(`チャレンジ成功 ${token}`);
        },
    });
});

Turnstileは、グローバルwindowオブジェクト内でturnstile.render()関数を呼び出すことでプログラム的にロードできます。

turnstile.render: function (container: string | HTMLElement, params: RenderParameters)レンダリングは、HTMLウィジェットへの引数を取ります。

呼び出しが成功すると、関数はwidgetId (string)を返します。呼び出しが失敗すると、関数はundefinedを返します。

ウィジェットの状態にアクセスする

render()関数に加えて、Turnstileはturnstile.getResponse(widgetId: string)関数を介してwidgetIdからウィジェットの応答を取得することをサポートしています。widgetIdを省略すると、turnstile.getResponse()は最後に作成されたウィジェットからの応答を返します。

しばらくすると、ウィジェットが期限切れになり、リフレッシュする必要があります（turnstile.reset(widgetId: string)を呼び出すことで）。ウィジェットが期限切れの場合、turnstile.getResponse()は最後の応答を返しますが、その応答は期限切れのため無効になります。

ウィジェットが期限切れかどうかを確認するには、expired-callbackにサブスクライブするか、turnstile.isExpired(widgetId: string)関数を使用します。この関数は、ウィジェットが期限切れの場合にtrueを返します。widgetIdを省略すると、turnstile.isExpired()は最後に作成されたウィジェットが期限切れかどうかを返します。

ウィジェットをリセットする

特定のウィジェットがタイムアウトしたり、期限切れになったり、再読み込みが必要な場合、turnstile.reset(widgetId: string)関数を使用してウィジェットをリセットできます。

ウィジェットを削除する

ウィジェットがもはや必要ない場合、turnstile.remove(widgetId: string)を使用してページから削除できます。これにより、コールバックは呼び出されず、関連するすべてのDOM要素が削除されます。

Turnstileをアンマウントするには、turnstile.render()が返すIDをturnstile.remove()に渡すことができます。

期限切れのトークンをリフレッシュする

トークンが期限切れになる数秒前に、expired-callbackが呼び出されます。

refresh-expiredまたはdata-refresh-expiredパラメータは、Turnstileウィジェットのトークンが期限切れになったときの動作を定義します。

デフォルトでは、このパラメータはautoに設定されており、チャレンジを再実行することでTurnstileに新しいトークンを取得するよう自動的に指示します。チャレンジが再度解決されると、指定されている場合はcallbackが新しいトークンで呼び出されます。

訪問者は、refresh-expiredパラメータをmanualに設定することで、新しいトークンを手動で取得するよう指示することもできます。

さらに、neverを指定すると、トークンの再生成は行われず、Turnstileを使用するアプリケーションが新しいTurnstileトークンを取得する責任を負います。

タイムアウトしたウィジェットをリフレッシュする

管理モードが選択されると、Turnstileは訪問者にインタラクティブなチャレンジを提示することがあります。このインタラクティブなチャレンジが提示されますが、指定された時間内に解決されなかった場合、タイムアウトし、Turnstileのチャレンジプロセスを再起動する必要があります。

refresh-timeoutまたはdata-refresh-timeoutパラメータは、インタラクティブなチャレンジがタイムアウトに遭遇したときの動作を定義します。デフォルトでは、ウィジェットは自動的にリフレッシュされます（auto）。ただし、ウィジェットは、訪問者がタイムアウトしたウィジェットを手動でリフレッシュする必要があるように構成することもできます（manual）、またはウィジェットはアプリケーションによってのみ外部からリフレッシュされることができます（refresh-timeout="never"）。

ウィジェットがインタラクティビティのタイムアウトに遭遇すると、timeout-callbackが呼び出されます。

実行モード

デフォルトでは、Turnstileトークンはウィジェットのレンダリング時に訪問者のために取得されます（不可視モードでも）。ただし、アプリケーションがTurnstileを埋め込みたいが、特定の時点までチャレンジの実行を遅らせたい場合があります。これが実行モードを使用して、チャレンジが実行されるタイミングとトークンが生成されるタイミングを制御する理由です。

2つのオプションがあります：

render()関数を呼び出した後にチャレンジが自動的に実行されます。
render()関数が呼び出された後に、turnstile.execute(container: string | HTMLElement, jsParams?: RenderParameters)関数を別に呼び出すことでチャレンジが実行されます。

これにより、ウィジェットの外観とレンダリングがその実行から切り離されます。

外観モード

ウィジェットが表示されている場合、その外観はappearanceパラメータを介して制御できます。

デフォルトでは、appearanceは表示されるウィジェットタイプに対してalwaysに設定されています。ただし、appearanceがexecuteに設定されている場合、ウィジェットはチャレンジが開始された後にのみ表示されます。これは、execute()がrender()の後に呼び出される場合に役立ちます。appearanceがinteraction-onlyに設定されている場合、ウィジェットはインタラクションが必要な場合にのみ表示されます。

ウィジェットのタイプと状態を確認するには、ウィジェットタイプを参照してください。

ウィジェットサイズ

Turnstileウィジェットは、管理モードまたは非インタラクティブモードを使用する際に、2つの異なる固定サイズまたは柔軟な幅サイズを持つことができます：

Size	Width	Height
Normal	300px	65px
Flexible	100% (min: 300px)	65px
Compact	150px	140px

<div style="display: block; flex-flow: row;">
    <div class="cf-turnstile" data-sitekey="1x00000000000000000000AA" data-size="flexible"></div>
</div>

<div style="display: block; flex-flow: row;">
    <div class="cf-turnstile" data-sitekey="1x00000000000000000000AA" data-size="compact"></div>
</div>

構成

JavaScript Render Parameters	Data Attribute	説明
`sitekey`	`data-sitekey`	すべてのウィジェットにはサイトキーがあります。このサイトキーは、対応するウィジェット設定に関連付けられ、ウィジェットの作成時に生成されます。
`action`	`data-action`	同じサイトキーの下でウィジェットを区別するために使用できる顧客値で、検証時に返されます。これは、`_`および`-`を含む最大32の英数字で構成される必要があります。
`cData`	`data-cdata`	チャレンジの発行中に顧客データを添付するために使用できる顧客ペイロードで、検証時に返されます。これは、`_`および`-`を含む最大255の英数字で構成される必要があります。
`callback`	`data-callback`	チャレンジの成功時に呼び出されるJavaScriptコールバックです。コールバックには検証可能なトークンが渡されます。
`error-callback`	`data-error-callback`	エラーが発生したとき（例：ネットワークエラーまたはチャレンジの失敗）に呼び出されるJavaScriptコールバックです。クライアント側のエラーを参照してください。
`execution`	`data-execution`	ウィジェットのトークンを取得するタイミングを制御し、`render`（デフォルト）または`execute`のいずれかで実行できます。詳細については、実行モードを参照してください。
`expired-callback`	`data-expired-callback`	トークンが期限切れになったときに呼び出されるJavaScriptコールバックで、ウィジェットをリセットしません。
`before-interactive-callback`	`data-before-interactive-callback`	インタラクティブモードに入る前に呼び出されるJavaScriptコールバックです。
`after-interactive-callback`	`data-after-interactive-callback`	チャレンジがインタラクティブモードを離れたときに呼び出されるJavaScriptコールバックです。
`unsupported-callback`	`data-unsupported-callback`	指定されたクライアント/ブラウザがTurnstileによってサポートされていない場合に呼び出されるJavaScriptコールバックです。
`theme`	`data-theme`	ウィジェットのテーマです。次の値を取ることができます：`light`、`dark`、`auto`。デフォルトは`auto`で、ユーザーの好みに従います。テーマを強制的に`light`または`dark`に設定することもできます。
`language`	`data-language`	表示する言語で、`auto`（デフォルト）を使用して訪問者が選択した言語を使用するか、ISO 639-1の2文字の言語コード（例：`en`）または言語と国コード（例：`en-US`）である必要があります。詳細については、サポートされている言語のリストを参照してください。
`tabindex`	`data-tabindex`	アクセシビリティの目的でTurnstileのiframeのタブインデックスです。デフォルト値は`0`です。
`timeout-callback`	`data-timeout-callback`	チャレンジがインタラクティブチャレンジを提示したが、指定された時間内に解決されなかった場合に呼び出されるJavaScriptコールバックです。コールバックはウィジェットをリセットし、訪問者が再度チャレンジを解決できるようにします。
`response-field`	`data-response-field`	応答トークンを持つ入力要素が作成されるかどうかを制御するブール値で、デフォルトは`true`です。
`response-field-name`	`data-response-field-name`	入力要素の名前で、デフォルトは`cf-turnstile-response`です。
`size`	`data-size`	ウィジェットのサイズです。次の値を取ることができます：`normal`、`flexible`、`compact`。
`retry`	`data-retry`	ウィジェットがトークンを取得できなかった場合に自動的に再試行するかどうかを制御します。デフォルトは`auto`で、自動的に再試行します。失敗時に再試行を無効にするには`never`に設定できます。
`retry-interval`	`data-retry-interval`	`retry`が`auto`に設定されている場合、`retry-interval`は再試行の間隔をミリ秒単位で制御します。値は900000未満の正の整数でなければならず、デフォルトは`8000`です。
`refresh-expired`	`data-refresh-expired`	トークンが期限切れになったときに自動的にトークンを更新します。`auto`、`manual`、または`never`を取ることができ、デフォルトは`auto`です。
`refresh-timeout`	`data-refresh-timeout`	インタラクティブチャレンジに入ったときにウィジェットが自動的に更新されるかどうかを制御します。`auto`（インタラクティブタイムアウトに遭遇したときに自動的に更新）、`manual`（訪問者に手動で更新を促す）、または`never`（タイムアウトを表示）を取ることができ、デフォルトは`auto`です。モード管理されたウィジェットにのみ適用されます。
`appearance`	`data-appearance`	ウィジェットが表示されるときの外観を制御します。`always`（デフォルト）、`execute`、または`interaction-only`のいずれかです。詳細については、外観モードを参照してください。
`feedback-enabled`	`data-feedback-enabled`	ウィジェットの失敗時にCloudflareが訪問者のフィードバックを収集できるようにします。`true`（デフォルト）または`false`を取ることができます。

Cloudflare Dashboard Discord Community Learning Center Support Portal

Cookie Settings