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トリガー適用とコードベース適用の2種類があります。
URLトリガー適用
ネットパーネルコンソールのセグメント設定でトリガールールを通じて適用します。 ユーザーがアクセスしたページのURLがトリガールールと一致すると待機列を適用します。 ネットパーネルコンソールで設定するため、アプリケーションの再デプロイが不要で、待機列適用ポイントをリアルタイムに変更できます。
コードベース適用
サービス中のアプリケーションコードで、ネットパーネルが提供する関数を呼び出します。 待機列適用ポイントを変更するたびに再デプロイが必要ですが、トラフィックが発生する前に待機室を表示するため、 トラフィックを事前に効果的に制御できます。
NetFUNNEL JavaScriptエージェントをインストールしたお客様は2つの適用方式を使用できますが、 設定の簡素化と管理のしやすさのため、いずれか1つのみの利用を推奨します。
URLトリガー適用
待機列制御ポイントは、NetFUNNELコンソールのセグメントトリガールールで設定できます。 ユーザーがアクセスしたページのURLとトリガールールを比較し、一致する場合に待機列が適用されます。
動作フロー
待機前: ページロード → エージェント初期化 → トリガールールマッチ 待機中: ネットパーネルサーバーリクエスト → ネットパーネルキー発行 → 待機室ページへ移動 待機後: サービスページ進入 → ネットパーネルキー返却
設定オプション
- 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がトリガールールに合致するか、事前に確認するためにテストできます。
コードベース適用
コードベース適用には開始関数と終了関数があります。 開始関数を呼び出してネットパーネルサーバーからキーを発行し、待機を完了して進入したら終了関数を呼び出してキーを返却します。 キーを返却することで、次の待機者が進入できるようになります。
動作フロー
- 待機前: ページロード → エージェント初期化 → 開始関数実行
- 待機中: ネットパーネルサーバーリクエスト → ネットパーネルキー発行 → 待機室表示
- 待機後: 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パラメータであるコールバック関数で、ネットパーネルサーバーからの応答を受け取れます。 応答結果に応じて、さまざまな処理ロジックを実行できます。
状態値 '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アドレス ネットパーネルサーバーダウン |
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':
// 進入またはバイパス応答を受けた場合、ネットパーネル適用前の既存サービスロジックを実行します。
// 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 | ネットワークヘルスチェックアドレス | 空欄 |