ブラウザとWebView側の統合手順
ダウンロード
フォーカスモード
フォントサイズ
EdgeOne は、Web サイト向けのクライアント認証 SDK を提供します。SDK はフロントエンド JavaScript の形式で Web ページに統合でき、ブラウザユーザーに対する透過的な検証を実現します。
説明：
ユーザー無感覚（不可視の純バックグラウンド）認証方式をシンプルな Web サービスに迅速に統合する必要がある場合は、SDK 統合と認証呼び出しのセクションを参照してください。
ご利用の認証方式にユーザーが視認できるインタラクティブコンポーネントが含まれる場合は、より良いサイトインタラクション体験を提供するために、インタラクティブ認証の適応利用のセクションもあわせて参照してください。
ご利用のサイトサービスでサードパーティドメインAPIも併用している場合は、サイトがサードパーティサービスに正常にアクセスできるように、CORSサポート：自動認証範囲の設定のセクションをさらに参照してください。
ブラウザ互換性
クライアント認証 SDK は、モバイル端末の WebView を含む、現代の主要ブラウザ環境をサポートします。推奨される最低バージョンは以下の通りです：
Chrome ≥ 90
Firefox ≥ 90
Safari ≥ 11
Edge ≥ 90
モバイル端末 WebView（iOS ≥ 11、Android WebView ≥ 67）
Opera ≥ 76
説明：
旧バージョンのブラウザ（特に Promise、Fetch、Crypto API をサポートしていないブラウザ）では、SDK が正常に動作しない可能性があります。
現在、HTTPSプロトコルに基づくHTMLページ応答によるSDK統合のみをサポートしています。
SDK統合と認証呼び出し
以下のいずれかの方法で、SDKをページに統合できます。ブラウザまたはWebViewコンポーネントがSDKを正常にロードすると、
windowオブジェクトにEOClientSecurityKitグローバルオブジェクトがインスタンス化されます。開発者はこのオブジェクトを通じてSDKインターフェースにアクセスし、さらに設定や制御を行うことができます。JavaScriptインジェクション方式により、ブラウザおよびWebViewの統合を効率的かつ容易に完了できます。EdgeOneプラットフォームによって提供またはプロキシされるHTMLページに適用され、手動介入を最小限に抑えることができます。
適用シーン
WebViewクライアントまたはブラウザは、EdgeOneによって保護されたHTMLページおよびAPIエンドポイントにアクセスする必要があります。（HTMLページはEdgeOneプロキシを通じて配信されます）
統合方式
フロントエンドコードの変更は不要です。EdgeOneクラウドコンソールで注入ルールを設定し、JavaScript注入機能を有効にしてください。
クライアント認証 SDK は、JavaScript コードスニペットにカプセル化され、指定された HTML ページの応答時に、HTML コンテンツへ自動的に注入されます。クライアントが EdgeOne にアクセスしてページコンテンツを読み込むか、または AJAX リクエストを開始する際に、このコードスニペットは認証ルールの要件に従って対応する認証メカニズムを実行し、認証結果を自動的に送信します。無感覚クライアント認証方式と併用する場合、上記の認証プロセスではページリソースに対する特別な調整や適応は不要です。
SDKの動作原理
SDKコードが注入されロードされると、ページ内のXMLHttpRequestおよびfetch API呼び出しを自動的にインターセプトします。SDKはEdgeOneサーバーからのHTTP 428チャレンジを透過的に処理し、認証成功後に認証トークンを後続のリクエストヘッダーに自動的に付加して、クライアント認証を自動化します。
JavaScript注入範囲の設定
JavaScript注入ルールを使用して、JavaScript注入の範囲を設定できます。ルールの優先順位と一致条件を設定することで、EdgeOneが特定のリソースにJavaScriptコードスニペットを注入するか、または注入をスキップするかを指定し、最適なアクセスパフォーマンスと認証効果を同時に満たすことができます。
以下のシーンではJavaScript注入を有効にしないようお願いします。業務異常を引き起こす可能性があります：
HTTPS 以外のページパス。
APIパスまたはモバイル端末がアクセスするパス。
WebSocketサービスのパス。
エッジ関数を有効にしたパス。
アクティブ特徴認識を有効にしたパス。
ルールを設定する際、ドメイン（Host）、URLパス、リクエストメソッドなどの条件を指定できます。例えば、特定のサブドメインにのみ適用するか、または特定のパス（
/checkoutなど）にのみ適用することができます。さらに、必要に応じてCookieやリクエストヘッダーなどをマッチングさせ、柔軟性を高めることもできます。リクエストが設定されたすべての条件に一致した場合にのみ、スクリプト注入が行われます。シナリオ例：サイトの全HTMLページにJavaScript注入を自動デプロイし、ブラウザクライアントを認証する
ECサイト
www.buyexample.com配下のすべてのHTMLページにアクセスするブラウザおよびWebViewクライアントに対して、デフォルトでセキュリティ認証を実行し、インターフェースに認証ポリシーを展開できるようにします。操作手順
1. EdgeOneコンソールにログインし、左側のメニューバーで「サービス概要」に入り、「Webサイト安全な加速」内で設定が必要なサイトをクリックします。
2. 「セキュリティ保護」>「クライアント認証」をクリックします。「認証SDK統合」タブをクリックし、「ブラウザ統合：JavaScriptの注入」オプションで「ルールを追加」をクリックして統合ルール設定画面に入ります。
3. ルール名を入力し、判定条件とJavaScript注入オプションを設定します。例のシナリオを例にとると、マッチング条件オプションでリクエストドメインマッチングを選択し、JavaScript注入オプションで
JavaScriptを注入を選択します。1つのリクエストが複数のルールに一致する場合、優先度が高い（数値が低い）ルールの処理方法が適用されます。
4. 「保存して公開」をクリックすると、ルールがデプロイされて有効になります。
EdgeOneプラットフォームを介してJavaScriptインジェクションを実行できない特定のシナリオに適用されます。例えば、ローカルファイルの読み込みや複数CDNによる配信などです。
適用シーン
ウェブページはローカルストレージ（ファイルシステムやアプリ内部ストレージなど）から読み込まれます。
静的サイトファイルは、EdgeOneの制御を受けない複数のCDNを介して配信されます。
開発者はSDKの読み込みおよび初期化プロセスをより詳細に制御する必要があります。
実現方法
クライアントデバイスがインターネットにアクセスできることを確認してください。以下の
<script>タグを対象HTMLページの<head>セクション（または<body>終了タグの前）に直接挿入してください：注意：
src属性が正しいSDK配布アドレスを指していることを確認してください。<script src="https://cdnstatic.tencentcs.com/edgeone/security/client-attestation/eoclientsecuritykit.min.js"></script>
動作原理
<script>タグの読み込み実行後、eoclientsecuritykit.min.jsが動作し、ページ内でAJAX（XHRおよびFetch API）を通じて発行されたリクエストをインターセプトします。SDKは認証チャレンジを処理し、認証トークンを取得して、後続のリクエストに自動的に付加することで、APIエンドポイントを保護します。対話型認証の適応使用（オプション）
一部のクライアント認証シナリオでは、EdgeOne SDK に特定の実行環境サポートが必要です。例えば：
認証フローでユーザー操作（Captchaなど）が必要な場合
計算集約型タスク（プルーフ・オブ・ワークなど）を実行します。
このようなシナリオでは、SDKがJavaScriptを読み込むために必要な実行環境（WebViewまたはブラウザ）を提供する必要があります。本節では、WebViewの使用方法や認証UIのレンダリングオプションなど、これらのインタラクティブな認証シナリオに適応する方法について詳しく説明します。
WebViewを使用した対話型またはJSベースの認証の実行
認証器がインタラクティブな検証コード（CAPTCHA）をレンダリングする必要がある場合、またはJavaScriptベースの暗号化によるProof-of-Workチャレンジを実行する必要がある場合、SDKはAPIパラメータでWebViewインスタンスを提供することを要求します。これは、開発者がアプリケーションで事前にWebViewインスタンスを割り当て、認証APIを呼び出す際にそれをパラメータとしてSDKに渡す必要があることを意味します。
対話型認証シナリオ
一部の認証器（例えば、埋め込み型またはポップアップ型のインタラクティブ設定を使用する TC-CAPTCHA）は、インタラクティブインターフェースをレンダリングするために WebView インスタンスを必要とします。この WebView インスタンスはアプリケーション内部で Captcha ページを表示するため、正しく表示されるように事前に設定する必要があります。
固定ブロック形式でデバイス画面に表示されます。UIが正しく表示され、ユーザーエクスペリエンスに影響を与えないようにするために、開発者はレンダリングウィンドウのサイズ、重なり順、配置方法を事前に設定する必要があります。なお、埋め込み型認証GUIは画面ビューに応じて拡大縮小されません。
説明：Tencent Captcha（TC-CAPTCHA）埋め込み型モードでは、最適なレンダリング効果とユーザーインタラクション体験を得るために、少なくとも300x230ピクセルのスペースを確保することを推奨します。
認証が呼び出された際に、フローティングウィンドウ形式でデバイス画面に表示されます。埋め込み型認証と同様に、レンダリングウィンドウのサイズ、重なり順、配置方法も事前に設定する必要があります。ポップアップ型認証の特徴は、画面ビューが特定のしきい値より小さい場合、ポップアップ型認証GUIが自動的に拡大縮小され、異なる画面サイズに適応することです。
説明：Tencent Captcha（TC-CAPTCHA）のポップアップ型モードの初期レンダリングブロックサイズは360x360ピクセルです。
JavaScriptベースの認証シナリオ
一部の認証器（例えば、無感覚モードを使用する TC-CAPTCHA）は、JavaScript ランタイム環境として WebView インスタンスを必要とし、主に暗号化による作業証明（PoW）チャレンジの実行に使用されます。このシナリオでは、WebView インスタンスは JavaScript 実行サンドボックスのみを提供し、UI を可視的にレンダリングする必要はありません。したがって、渡される WebView インスタンスは可視である必要はなく、SDK もそれを UI レンダリングに使用しません。
認証に必要なUIのレンダリング
ブラウザまたはWebView環境のH5/Webアプリケーションでは、インタラクティブ認証または可視認証を使用する場合、SDKは認証UIをレンダリングするためにHTML要素を必要とします。SDKは、
<span>、<p>、<div>、<section>など、さまざまな一般的なコンテナ要素をサポートしています。SDKは、以下の優先順位に基づいて認証UIのレンダリング位置を決定します：開発者は、
window.EOClientSecurityKit.setClientAttestationDOMSelectorProvider(elementSelectorFunc) APIを呼び出して要素セレクタ関数を割り当てることができます。SDKが認証UIをレンダリングする必要がある場合、この関数が呼び出されます。elementSelectorFuncは、以下の2つの方法で定義できます：CSSセレクタ文字列を返します： 要素ID（
#valid-dom-id）、クラス名（.valid-dom-class）、またはより複雑な子孫セレクタ（#valid-dom-id .valid-dom-class）などのCSSセレクタ文字列を直接返します。SDKはこのセレクタを使用してページ要素を検索し、UIをレンダリングします。非同期関数コールバックを返します： 実行時にレンダリング要素を動的に作成または決定する必要がある場合は、最終的にCSSセレクタ文字列に解決されるPromiseを返すことができます。これにより、複雑な動的UIシナリオに柔軟性が提供されます。
例：
// 要素レンダリングコールバックのセレクタプロトタイプtype ClientAttestationDOMSelector = () => string | Promise<string>// 例1：要素IDを使用して要素を指定します（同期方式）const tmpProviderSyncId: ClientAttestationDOMSelector = () => {return \\'#valid-dom-id\\'; // 要素IDセレクタを返します};// 例2：非同期関数を使用して要素を指定します（要素を動的に作成）const tmpProviderAsync: ClientAttestationDOMSelector = () => {return new Promise((resolve, reject) => {setTimeout(() => {const id = Math.random().toString(36).substring(2, 15);const iframe = document.createElement(\\'div\\');iframe.id = id;document.body.appendChild(iframe);resolve(`body > #${id}`); // セレクタ文字列として解析します}, 500);});};// コールバック関数を設定します（いずれかの例を選択して設定します）// window.EOClientSecurityKit.setClientAttestationDOMSelectorProvider(tmpProviderSyncId);// window.EOClientSecurityKit.setClientAttestationDOMSelectorProvider(tmpProviderAsync);
注意：
ページ内に指定されたレンダリング要素コールバックのセレクタ（オプション1）が定義されている場合、そのオプションが優先的に使用されます。
setClientAttestationDOMSelectorProviderを通じてセレクタコールバック関数が割り当てられていない場合、SDKはページ内で最初にIDがeo-client-attestationであるHTML要素を検索します。見つかった後、その要素は認証UIのレンダリングに使用されます。この方法は、開発者が認証UIの表示領域を確保するための簡単な規約を提供します。例：
<div id="eo-client-attestation"></div> <!-- レンダリング領域を確保するための要素 -->
開発者はこの
div 要素をHTMLページの適切な位置に配置し、必要に応じてスタイルをカスタマイズして、認証UIがページ全体のデザインスタイルと一致するようにできます。他の2つのレンダリングオプションが存在しない場合、EdgeOne SDKはデフォルト戦略を採用します：HTML
<body> Tagの末尾に認証UIをレンダリングするための新しいHTML要素を動的に作成します。注意：
このデフォルトのレンダリング方法は認証UIの表示を確保できますが、最適なユーザーエクスペリエンスを提供できない可能性があります。要素は動的に作成され、位置は
<body> の末尾に固定されるため、そのスタイルとレイアウトはページデザインと調和しない可能性があり、他の要素によって遮られる可能性もあります。そのため、強く推奨します開発者が認証UIのレンダリング専用の要素を積極的に割り当てて指定し（オプション1またはオプション2を使用）、認証UIの表示位置、サイズ、スタイルを正確に制御することで、より優れたユーザーエクスペリエンスを提供してください。CORS対応：自動認証範囲の構成（オプション）
ページにサードパーティサービスを統合する際、クロスオリジンリソース共有（CORS）ポリシーの競合が発生する可能性があります。EdgeOne SDKは、リクエストインターセプターの作用範囲を制限するための柔軟なメカニズムを提供します。自動認証範囲を適切に構成することで、開発者は複雑なWeb環境におけるSDKの動作を効果的に管理し、サードパーティサービスのCORSポリシーとの競合を回避できます。
SDKインターセプト範囲の制限
window.EOClientSecurityKit.setCustomHostnameScope(customScope) APIを呼び出すことで、どのドメインのリクエストに対して自動認証を有効にするかを正確に指定できます。これにより、SDKが無関係なサードパーティリクエストを遮断することを防ぎ、潜在的なCORSの問題を効果的に回避できます。const hostnameScope = ["*.example.com", // ワイルドカードによるサブドメインマッチングをサポートします。"a.test.com", // 特定ドメインを正確にマッチングします。"[1-9].test.com" // 正規表現によるマッチングをサポートします。];window.EOClientSecurityKit.interceptor.setCustomHostnameScope(hostnameScope);
カスタム範囲のクリア
すべてのカスタムドメイン範囲制限を削除し、SDKのデフォルトのブロック動作を復元するには、以下を呼び出します：
window.EOClientSecurityKit.interceptor.clearCustomHostnameScope();
例：自動認証範囲の構成による、SDK統合時のクロスドメインでのサードパーティサービス呼び出しにおける互換性問題の解決
Webアプリケーションを開発中で、そのメインドメインが
www.your-app.com であるとします。このアプリケーションは、api.your-app.com にEdgeOneによって保護されたAPIリクエストを送信するだけでなく、サードパーティの統計サービスも統合しており、このサービスは analytics.third-party.com にデータ報告リクエストを送信します。EdgeOneクライアント認証SDKは、自動注入方式によってアプリケーションのページに統合されています。
デフォルトでは、EdgeOne SDKはページ内のすべての
XMLHttpRequest および fetch API リクエストをインターセプトしようとし、これらのリクエストのリクエストヘッダーに EO-Attest-Token を自動的に付加する可能性があります。アプリケーションが analytics.third-party.com にデータ報告リクエストを送信する際、そのリクエストにも EO-Attest-Token が付加されており、analytics.third-party.com のサーバーが EO-Attest-Token のようなカスタムリクエストヘッダーを許可するように構成されていない場合、ブラウザはクロスオリジンセキュリティポリシー（CORS）によってそのリクエストをブロックします。
具体的には以下のように現れます：
プリフライトリクエスト（OPTIONS）の失敗：ブラウザは実際のクロスオリジンリクエストを送信する前に、まずOPTIONSプリフライトリクエストを送信します。このリクエストには
Access-Control-Request-Headers フィールドが含まれており、実際のリクエストで送信されるカスタムリクエストヘッダー（EO-Attest-Token を含む）が一覧表示されます。サーバーによる拒否：
analytics.third-party.com のサーバーがそのCORS設定で EO-Attest-Token を明示的に許可していない場合、サーバーはそのプリフライトリクエストを拒否し、プリフライトが失敗します。実際のリクエストがブロックされます：プリフライトリクエストが失敗した後、ブラウザは実際のデータ報告リクエストを送信せず、コンソールにエラーを表示し、CORSポリシーの競合を通知します。
これにより、サードパーティの統計サービスが正常に動作しなくなり、データ収集に影響を及ぼします。
ソリューション
自動認証範囲を設定することで適応します。
上記の問題を解決するには、
window.EOClientSecurityKit.interceptor.setCustomHostnameScope() APIを使用してSDKのインターセプト範囲を正確に制限し、自分のドメイン（api.your-app.com）配下のリクエストにのみ有効にして、サードパーティドメインへのリクエストを無視する必要があります。// SDKの読み込みと初期化後に呼び出します。window.EOClientSecurityKit.interceptor.setCustomHostnameScope([「api.your-app.com」、// お客様のAPIドメインに対してのみ自動認証を有効にします。「www.your-app.com」 // メインサイトでも認証が必要な場合は、追加できます。]);// この時点で、SDKはanalytics.third-party.comへのリクエストにEO-Attest-Tokenを追加しなくなります。// サードパーティ統計サービスのデータ報告リクエストは正常に送信され、CORS制限の対象外となります。
上記の設定により、SDKは
api.your-app.com と www.your-app.com へのリクエストに対してのみインターセプトとトークン付加を行います。アプリケーションが analytics.third-party.com にリクエストを送信する際、SDKはそのリクエストに EO-Attest-Token を追加しなくなります。リクエストにサードパーティサーバーが認識できないカスタムリクエストヘッダーが含まれなくなるため、CORSプリフライトリクエストは成功し、実際のリクエストも正常に送信されます。これにより、サードパーティサービスとEdgeOne SDKは同一ページ内で調和して共存し、互いに干渉しません。
フィードバック