Web/JavaScript エージェント
概要
NetFUNNEL JavaScript エージェントは、Web ブラウザで NetFUNNEL サーバーと通信する NetFUNNEL 専用クライアントです。
エージェントのインストール
初期化
NetFUNNEL JavaScript エージェントは、ページロード時に初期化コードを通じてサービスに適用されます。 サービスロジックより先に実行する必要があるため、head タグの上位に配置することを推奨します。
コード
NetFUNNEL JavaScript エージェントを使用するページの HTML に初期化コードを追加してください。
<html>
<head>
...
<script
src="{{AGENT_URL}}"
data-nf-client-id="{{CLIENT_ID}}"
></script>
...
</head>
</html>
エージェントの適用
NetFUNNEL JavaScript エージェントで待合室制御ポイントを設定する方法には、URL トリガー適用 (UTI) とコードベース適用 (CBI) の 2 種類があります。
URL トリガー適用
NetFUNNEL コンソールのセグメント設定でトリガールールを通じて適用します。 ユーザーがアクセスしたページの URL がトリガールールと一致すると待合室を適用します。 NetFUNNEL コンソールで設定するため、アプリケーションの再デプロイが不要で、待合室適用ポイントをリアルタイムに変更できます。
コードベース適用
サービス中のアプリケーションコードで、NetFUNNEL が提供する関数を呼び出します。 待合室適用ポイントを変更するたびに再デプロイが必要ですが、トラフィックが発生する前に待合室を表示するため、 トラフィックを事前に効果的に制御できます。
NetFUNNEL JavaScript エージェントをインストールしたお客様は 2 つの適用方式を使用できますが、 設定の簡素化と管理のしやすさのため、いずれか1つのみの利用を推奨します。
URL トリガー適用
待合室制御ポイントは、NetFUNNEL コンソールのセグメントトリガールールで設定できます。 ユーザーがアクセスしたページの URL とトリガールールを比較し、一致する場合に待合室が適用されます。
動作フロー
待機前：ページロード → エージェント初期化 → トリガールールマッチ 待機中：NetFUNNEL サーバーリクエスト → NetFUNNEL キー発行 → 待合室ページへ移動 待機後：サービスページ進入 → NetFUNNEL キー返却
設定オプション
- Logical Operator：2 つ以上のトリガールールを作成する際、相互の関係を and または or 演算子で決定します。
- Validator：トリガールールが適用される対象の最上位範囲を定義します。現在は URL のみ提供しています。
- Component：Validator で定義された範囲内で、より詳細にルールを適用する対象を指定します。URL 全体やパス (Path) などとなり、特定のページやリソースにルールを適用する際に使用します。
- Negate：設定した条件の逆の場合に適用したいときに使用します。例えば、特定条件が「真」でないときにルールを適用したい場合にこのオプションを有効にします。
- Match：ルールが適用される条件のタイプを定義します。'Equals'、'Exists'などのオプションで、特定の値と一致する場合や特定条件が存在する場合などを基準にルールを適用できます。
- Value：ルール適用時に比較対象となる具体的な値を指定します。この値は'Match'条件とともに使用され、ルールがどの場合に有効になるかを決定します。
- Aa：Value を比較する際に大文字小文字を区別するかを決定します。
Match オプション
- Exists：URL に該当する Component が存在するか確認します（Component が Path の場合のみ使用可能です）。
- Equals：Component の値と Value が完全に一致するかを確認します。
- Contains：Component の値に指定した Value が含まれているかを確認します。
- StartsWith：Component の値が指定した Value で始まるかを確認します。
- EndsWith：Component の値が指定した Value で終わるかを確認します。
トリガールールのテスト
待合室を適用したい URL がトリガールールに合致するか、事前に確認するためにテストできます。
コードベース適用
コードベース適用には開始関数と終了関数があります。 開始関数を呼び出して NetFUNNEL サーバーからキーを発行し、待機を完了して進入 (目的のページへ遷移) したら終了関数を呼び出してキーを返却します。 キーを返却することで、次の待機ユーザーが進入できるようになります。
動作フロー
- 待機前：ページロード → エージェント初期化 → 開始関数実行
- 待機中：NetFUNNEL サーバーリクエスト → NetFUNNEL キー発行 → 待合室表示
- 待機後：Success ロジック実行 → 終了関数実行
基本制御
開始関数
- 関数名：
nfStart - 説明：待機を適用したい箇所で関数を呼び出し、キーを発行して待合室を表示します。
- 適用位置：ページ進入やイベント開始部分に適用します。
| パラメータ | タイプ | 説明 | 必須 |
|---|---|---|---|
| projectKey | String | NetFUNNELコンソールの基本制御プロジェクトキー | O |
| segmentKey | String | NetFUNNELコンソールの基本制御セグメントキー | O |
| callback | Function | 待合室イベント処理のためのユーザー定義コールバック関数 | O |
nfStart({
projectKey: "{{PROJECT_KEY}}",
segmentKey: "{{SEGMENT_KEY}}"
}, function(response) {
// TODO: response に応じて状況に合ったコールバック関数を実装します。
nfCallback(response);
});
終了関数
- 関数名：
nfStop - 説明：進入完了後、キー返却のために使用します。
- 適用位置：開始関数終了後、または進入したユーザーの活動が完了する箇所に適用します。
終了関数を実行しない場合、セグメントのタイムアウト設定に従い自動で返却処理されます。
| パラメータ | タイプ | 説明 | 必須 |
|---|---|---|---|
| projectKey | String | NetFUNNEL コンソールの基本制御プロジェクトキー | O |
| segmentKey | String | NetFUNNEL コンソールの基本制御セグメントキー | O |
nfStop({
projectKey: "{{PROJECT_KEY}}",
segmentKey: "{{SEGMENT_KEY}}"
});
区間制御
区間制御とは、アプリケーションの特定区間で同時接続者数を一定に保つように制御する機能です。 開始関数呼び出し時にキーを発行し、終了関数を呼び出すまでユーザーが活動区間にいるとみなし、 次の待機ユーザーを進入させません。 終了関数を呼び出すとキーを返却し、次の待機ユーザーが進入します。
開始関数
- 関数名：
nfStartSection - 説明：待機を適用したい箇所で関数を呼び出し、キーを発行して待合室を表示します。
- 適用位置：ページ進入やイベント開始部分に適用します。
| パラメータ | タイプ | 説明 | 必須 |
|---|---|---|---|
| projectKey | String | NetFUNNELコンソールの区間制御プロジェクトキー | O |
| segmentKey | String | NetFUNNELコンソールの区間制御セグメントキー | O |
| callback | Function | 待合室イベント処理のためのユーザー定義コールバック関数 | O |
nfStartSection({
projectKey: "{{PROJECT_KEY}}",
segmentKey: "{{SEGMENT_KEY}}"
}, function(response) {
// TODO: responseに応じて状況に合ったコールバック関数を実装します。
nfCallback(response);
});
終了関数
- 関数名：
nfStopSection - 説明：進入完了後、キー返却のために使用します。
- 適用位置：進入したユーザーの活動区間が終了する箇所に適用します。
終了関数を実行しない場合、ユーザーが活動区間に残っているとみなされ、次の待機ユーザーの進入が遅れることがあります。
| パラメータ | タイプ | 説明 | 必須 |
|---|---|---|---|
| projectKey | String | NetFUNNELコンソールの区間制御プロジェクトキー | O |
| segmentKey | String | NetFUNNELコンソールの区間制御セグメントキー | O |
nfStopSection({
projectKey: "{{PROJECT_KEY}}",
segmentKey: "{{SEGMENT_KEY}}"
});
コールバック関数
基本制御と区間制御の開始関数の第2パラメータであるコールバック関数で、NetFUNNEL サーバーからの応答を受け取れます。 応答結果に応じて、さまざまな処理ロジックを実行できます。
状態値 'Success'、'Error'、'NetworkError'については必須で処理する必要があります。 それ以外の状態値は処理しなくてもサービスに影響はありません。
Success
| statusCode | message | 説明 |
|---|---|---|
| 200 | Success | 待合室を正常に通過してサービスに進入 |
| 300 | Bypass | サブスクリプション/ライセンス期限切れ プロジェクト/セグメント無効化 data-nf-error-bypass=true設定 |
| 303 | Express | 進入成功時の動作 |
Error
| statusCode | message | 説明 |
|---|---|---|
| 500 | Server Error | 存在しないプロジェクト/セグメントキー使用 待機中セグメント削除 サーバーエラーによる応答欠落 |
NetworkError
| statusCode | message | 説明 |
|---|---|---|
| 1001 | Network Not Connected | ネットワーク接続遮断 |
| 1002 | Network Timeout | ネットワーク遅延 無効な待合室 html アドレス NetFUNNEL サーバーダウン |
Block
| statusCode | message | 説明 |
|---|---|---|
| 301 | Block | セグメントブロック |
IpBlock
| statusCode | message | 説明 |
|---|---|---|
| 302 | Macro Block | ブラックリスト BotManager Basic 有効化 |
Close
| statusCode | message | 説明 |
|---|---|---|
| 499 | Canceled Waiting Room | 基本待合室のキャンセルボタンクリック |
| 498 | Closed Blocking Room | ブロックルームの閉じるボタンクリック |
| 497 | Closed Macro Blocking Room | マクロブロックルームの閉じるボタンクリック |
| 496 | Closed PreWaiting Room | 事前待合室の閉じるボタンクリック |
| 495 | Closed PostWaiting Room | 事後待合室の閉じるボタンクリック |
function nfCallback(response) {
const { status, statusCode, message } = response;
switch(status) {
case 'Success':
// 進入またはバイパス応答を受けた場合、NetFUNNEL 適用前の既存サービスロジックを実行します。
// ex - ページ遷移、関数実行、API リクエスト
break;
case 'Error':
// システムエラーが発生した場合、円滑なサービス利用のため Success と同様に既存サービスロジックを実行します。
// ex - ページ遷移、関数実行、API リクエスト
break;
case 'NetworkError':
// ネットワークエラーが発生した場合、既存サービスロジックを実行するか、通知後に再度待合室に進入するようにします。
// ex - ページ遷移、関数実行、API リクエスト、alert("ネットワークリクエストに失敗したため再試行します。");
break;
case 'Block':
// 進入状態がブロックの場合、ブロックを通知するか、何も処理しなくても構いません。
// ex - alert("進入がブロックされたページです。");
break;
case 'IpBlock':
// 反復リクエストによりブロックされた場合、ブロックを通知するか、何も処理しなくても構いません。
// ex - alert("反復したリクエストでブロックされました。");
break;
case 'Close':
// 待合室の閉じるまたはキャンセルボタンをクリックした場合、待機キャンセルを通知するか、何も処理しなくても構いません。
// ex - alert("待機をキャンセルしました。");
break;
default:
console.log(`[NF] status: ${status}, code: ${statusCode}, message: ${message}`);
}
}
付加機能
NetFUNNEL JavaScript エージェントではさまざまな付加機能を提供しています。付加機能を有効にするには、初期化コードに設定値を追加する必要があります。 適用方式によって利用できる付加機能が異なるため、以下の表を参照してください。
- UTI：URL トリガー適用 (URL Triggered Integration)
- CBI：コードベース適用 (Code Based Integration)
初期化コードの設定値
| data属性名 | 適用方式 | 説明 | デフォルト値 |
|---|---|---|---|
| data-nf-network-timeout | UTI, CBI | ネットワーク応答最大待機時間 | 3000 |
| data-nf-retry-count | UTI, CBI | ネットワーク再試行回数 | 0 |
| data-nf-custom-cookie-domain | UTI, CBI | クッキー保存時のドメイン設定 | 空欄 |
| data-nf-use-network-recovery-mode | UTI, CBI | ネットワークエラー時の待合室維持と回復 | false |
| data-nf-storage-type | UTI, CBI | ブラウザストレージ選択 | both |
| data-nf-return-key | UTI | キー返却処理 | true |
| data-nf-error-bypass | CBI | Error、NetworkError の代わりに Success 状態値を返却 | false |
| data-nf-use-netfunnel-template | CBI | 自社カスタム待合室使用 | true |
| data-nf-health-check-url | CBI | ネットワークヘルスチェックアドレス | 空欄 |