メインコンテンツまでスキップ
バージョン: 4.6.1

コードベース統合

アプリケーションコードからNetFUNNEL関数を呼び出してボタン/APIレベルでトラフィックを制御します。

統合方法

これは利用可能な2つの統合方法の1つです。URLトリガー統合と比較し、使用例に最も適したアプローチを選択するには、統合方法概要を参照してください。

動作方法​

ユーザー体験:

  1. ユーザーがボタンをクリックまたは作業をトリガー
  2. モーダル待合室が現在の画面に開く
  3. 進入が許可されるとモーダルが閉じ、サービスが継続される

最適な用途:

  • ボタンクリック保護 (ログイン、決済、注文)
  • API呼び出しスロットリング
  • 特定の作業に対する精密な制御
  • 一貫した同時性を持つマルチステップフロー

前提条件​

サンプルアプリケーション例

このガイドはコードベース統合パターンを実演するためにサンプルアプリケーションを使用します。実際のアプリケーションコードはここに示された例とは異なります。統合概念を理解し、パターンを特定のコードベース、関数名、ビジネスロジックに合わせて調整することに集中してください。

💡 練習テンプレート: NetFUNNEL統合の練習のために準備された**Webアプリケーション(バニラJavaScript MPA)**テンプレートを含むサンプルプロジェクトを確認してください。

ステップ1: テスト環境の準備​

ブラウザ設定:

  • Firefox(推奨)またはChrome/Edge/Safariを使用
  • クリーンなテストのためにFirefoxプライベートモード推奨

DevTools構成:

  • DevToolsを開く: F12 (Windows)または⌘⌥I (macOS)
  • ネットワークタブ設定:
    • ✅ ログ保持またはログ維持
    • ✅ キャッシュ無効化

DevTools network settings

ステップ2: エージェントインストール確認​

HTTP 200で次のファイルがロードされることを確認して、NetFUNNELエージェントが正しくロードされていることを確認してください:

  1. netfunnel-javascript-agent.js
  2. nf-setting.json

Agent files loading successfully

インストールが必要

これらのファイルがHTTP 200ステータスでロードされない場合、NetFUNNELエージェントが正しくインストールされていません。続行する前にインストールおよび初期化ガイドに戻って設定プロセスを完了してください。

ステップ3: セグメント作成​

2つの制御タイプをサポート

コードベース統合は基本コントロールと区間コントロールの両方をサポートします。このガイドは基本コントロールを使用します。

3.1 新しいセグメント作成​

  1. NetFUNNELコンソール → プロジェクト → セグメントに移動
  2. **+**ボタンをクリックして新しいセグメントを作成

Create segment button

3.2 制御タイプ選択​

基本コントロールを選択し、次へをクリック

Select Basic Control

3.3 セグメント構成​

セグメント名: 説明的な名前を入力 (例: "ログインボタン"、"決済プロセス"、"API呼び出し保護")

Enter segment name

進入状態:

  • ✅ セグメントの有効化を有効化
  • 進入状態: 待機 (ユーザーを待合室に送る)

Entry status settings

待合室適用:

  • テストのためにデフォルト設定を使用
  • ライブメッセージは空のまま

Waiting room settings

進入許容数:

  • テストのために0に設定 (誰も許可されない、待合室が常に表示される)

Limited inflow setting

3.4 セグメント作成​

作成をクリックしてセグメントを確定

Segment created

ステップ4: キー発行統合ポイントの識別 (nfStart)​

サンプルアプリケーション

次の例は実演目的でサンプルアプリケーションを使用します。実際のアプリケーションコードはここに示されたものとは自然に異なります。統合パターンを特定のコード構造、ボタンID、関数名、ビジネスロジックに合わせて調整してください。

💡 練習プロジェクトが必要ですか? NetFUNNEL統合の練習のために準備された**Webアプリケーション(バニラJavaScript MPA)**テンプレートを含むサンプルプロジェクトを確認してください。

サンプルアプリケーションの理解:

NetFUNNEL保護を適用する必要がある場所を理解するために、サンプルアプリケーションを見てみましょう:

4.1 HTMLでターゲットボタンの識別​

<button id="btn-basic-control-function" class="btn btn-primary btn-main">
  Basic Control (Code-based Integration)
</button>
<button id="btn-sectional-control-function" class="btn btn-success btn-main">
  Section Control (Code-based Integration)
</button>
<button id="btn-basic-control-dynamic" class="btn btn-warning btn-main">
  Basic Control (URL Triggered Integration)
</button>

このサンプルに対する仮定:

  • "Basic Control (Code-based Integration)"ボタン(btn-basic-control-function)はリソース集約的な作業を表します
  • これは次のいずれかです: ユーザーログイン、決済処理、ファイルアップロード、データエクスポート
  • 多くのユーザーがこのボタンを同時にクリックするとサーバーに過負荷が発生する可能性があります
  • 他のボタンは重要度が低く、保護は不要です

4.2 このボタンのイベントリスナーを見つける​

document.addEventListener('DOMContentLoaded', () => {
  console.log('Main page loaded');
  
  // ナビゲーションボタン設定
  setupNavButton('btn-basic-control-function', './pages/basic-control-function/index.html');
  setupNavButton('btn-sectional-control-function', './pages/sectional-control-function/section1/index.html');
  setupNavButton('btn-basic-control-dynamic', './pages/basic-control-dynamic/index.html');
});

4.3 イベントリスナー関数内で発生することを確認​

export const setupNavButton = (buttonId, targetUrl) => {
  const button = document.getElementById(buttonId);
  if (button) {
    console.log(`Setting up button ${buttonId} to navigate to ${targetUrl}`);
    button.addEventListener('click', () => {
      navigateWithDelay(targetUrl);  // ← サーバー負荷が発生するポイント
    });
  } else {
    console.error(`Button with ID ${buttonId} not found`);
  }
};

4.4 統合ポイントの識別​

  1. ターゲットボタン: btn-basic-control-function (リソース集約的なボタン)
  2. イベントリスナー: setupNavButton()関数がクリックハンドラーを設定します
  3. 統合位置: navigateWithDelay(targetUrl)が呼び出される直前
  4. ここで行う理由: サーバー処理が開始される直前の正確な瞬間です
  5. 保護戦略: サーバー呼び出し前にNetFUNNELキューを追加

全体フロー分析:

  1. ページロード: DOMContentLoadedイベント発生
  2. ボタン設定: 各ボタンに対してsetupNavButton()呼び出し
  3. イベントバインディング: 各ボタンにクリックイベントリスナーを追加
  4. ユーザー作業: ユーザーが"Basic Control (Code-based Integration)"をクリック
  5. 現在の動作: navigateWithDelay(targetUrl)が即座に実行される
  6. サーバー負荷: これがリソース集約的な作業をトリガーします

ロジック:

  • NetFUNNELなし: ボタンクリック → 即座にサーバーリクエスト → 潜在的な過負荷
  • NetFUNNEL使用: ボタンクリック → キュー確認 → 制御されたサーバーリクエスト → 成功

ステップ5: キー発行関数の実装 (nfStart)​

コードに合わせて調整

以下の例は、サンプルアプリケーションのsetupNavButton関数にNetFUNNELを統合する方法を示しています。このパターンを実際のコード構造に合わせて調整してください - 保護が必要な他の関数名、イベントハンドラー、ビジネスロジックがある可能性があります。

5.1 キーの取得​

まず、コンソールからプロジェクトキーとセグメントキーを見つけてください:

  1. NetFUNNELコンソール → プロジェクト → セグメントに移動
  2. セグメントをクリック
  3. プロジェクトキーとセグメントキーをコピー

Project and segment keys

5.2 nfStart関数の理解​

nfStart関数は次のような基本構造を持ちます:

nfStart({
  projectKey: "your_project_key",    // コンソールから
  segmentKey: "your_segment_key"     // コンソールから
}, function(response) {
  // 応答処理
  if (response.status === 'Success') {
    // ロジック進行
  }
});
APIリファレンス

nfStartパラメータ、コールバック処理、応答形式の詳細については、APIリファレンスを参照してください。

5.3 現在のコードから開始​

現在の実装:

export const setupNavButton = (buttonId, targetUrl) => {
  const button = document.getElementById(buttonId);
  if (button) {
    console.log(`Setting up button ${buttonId} to navigate to ${targetUrl}`);
    button.addEventListener('click', () => {
      navigateWithDelay(targetUrl);  // ← これが私たちのビジネスロジックです
    });
  } else {
    console.error(`Button with ID ${buttonId} not found`);
  }
};

核心概念:

  • ビジネスロジック: navigateWithDelay(targetUrl)はリソース集約的な作業を表します
  • 統合ポイント: このビジネスロジックをNetFUNNEL保護でラップする必要があります
  • ラッピング戦略: ビジネスロジックが実行される前にアクセスを制御するためにnfStart()を使用

ここでラップする理由:

  • これはサーバー負荷が開始される直前の正確な瞬間です
  • ここでラップすると、全体のダウンストリーム作業が保護されます
  • ビジネスロジックは変更されません - キューレイヤーのみが追加されます

5.4 基本的なNetFUNNEL保護の追加 (成功のみ)​

ビジネスロジックのラッピング:

export const setupNavButton = (buttonId, targetUrl) => {
  const button = document.getElementById(buttonId);
  if (button) {
    console.log(`Setting up button ${buttonId} to navigate to ${targetUrl}`);
    button.addEventListener('click', () => {
      if (buttonId === 'btn-basic-control-function') {
        // この関数はすべてのボタンを処理しますが、この特定のボタンのみをラップします
        nfStart({
          projectKey: 'service_1',
          segmentKey: 'segKey_8612'
        }, function (response) {
          if (response.status === 'Success') {
            navigateWithDelay(targetUrl);  // 元のビジネスロジック
          }
        });
      } else {
        navigateWithDelay(targetUrl);  // 保護不要
      }
    });
  } else {
    console.error(`Button with ID ${buttonId} not found`);
  }
};

変更点:

  • ラップ済み: navigateWithDelay(targetUrl)がnfStartコールバック内にあります
  • 条件付き: 特定のボタンのみがNetFUNNEL保護を受けます
  • 成功のみ: NetFUNNELが進入を許可する場合のみビジネスロジックが実行されます

5.5 関数の可用性確認の追加​

エラーを防ぐためにtypeof確認を追加:

export const setupNavButton = (buttonId, targetUrl) => {
  const button = document.getElementById(buttonId);
  if (button) {
    console.log(`Setting up button ${buttonId} to navigate to ${targetUrl}`);
    button.addEventListener('click', () => {
      if (buttonId === 'btn-basic-control-function') {
        // この関数はすべてのボタンを処理しますが、この特定のボタンのみをラップします
        if (typeof window.nfStart === 'function') {
          nfStart({
            projectKey: 'service_1',
            segmentKey: 'segKey_8612'
          }, function (response) {
            if (response.status === 'Success') {
              navigateWithDelay(targetUrl);
            }
          });
        } else {
          // NetFUNNELがロードされていない場合のフォールバック
          console.log(`Navigating to ${targetUrl} without NetFunnel`);
          navigateWithDelay(targetUrl);
        }
      } else {
        // 他のボタンはNetFUNNELなしで進行
        navigateWithDelay(targetUrl);
      }
    });
  } else {
    console.error(`Button with ID ${buttonId} not found`);
  }
};

この確認が必須な理由:

  • クラッシュ防止: この確認なしでNetFUNNELがロードされていない状態でnfStart()を呼び出すとReferenceErrorが発生します
  • 優雅な劣化: NetFUNNELがロードに失敗した場合(ネットワーク問題、CDN問題)、アプリが継続して動作します
  • 開発の柔軟性: NetFUNNELスクリプトがロードされていない状態でもテストできます

5.6 NetFUNNEL統合のモジュール化​

コードがネストされた条件で複雑になっています。モジュール化しましょう:

// NetFUNNEL構成
const NETFUNNEL_CONFIG = {
  projectKey: 'service_1',
  segmentKey: 'segKey_8612'
};

// NetFUNNEL成功応答のみ処理
function handleNetFunnelResponse(response, businessLogic) {
  switch (response.status) {
    case 'Success':
      console.log('NetFUNNEL: Entry granted');
      businessLogic(); // 渡されたビジネスロジックを実行
      break;
  }
}

// nfStart保護でビジネスロジックをラップ
function wrapWithNfStart(businessLogic) {
  if (typeof window.nfStart === 'function') {
    console.log(`Executing with NetFunnel`);
    nfStart(NETFUNNEL_CONFIG, (response) => {
      handleNetFunnelResponse(response, businessLogic);
    });
  } else {
    console.log(`Executing without NetFunnel`);
    businessLogic();
  }
}

// クリーンでモジュール化されたsetupNavButton
export const setupNavButton = (buttonId, targetUrl) => {
  const button = document.getElementById(buttonId);
  if (button) {
    console.log(`Setting up button ${buttonId} to navigate to ${targetUrl}`);
    button.addEventListener('click', () => {
      if (buttonId === 'btn-basic-control-function') {
        // この関数はすべてのボタンを処理しますが、この特定のボタンのみをラップします
        wrapWithNfStart(() => navigateWithDelay(targetUrl));
      } else {
        navigateWithDelay(targetUrl); // 保護不要
      }
    });
  } else {
    console.error(`Button with ID ${buttonId} not found`);
  }
};

このモジュール化アプローチの利点:

  • 関心の分離: NetFUNNELロジックがボタン設定から分離されます
  • 再利用可能: wrapWithNfStart()を他の保護された作業に使用できます
  • 保守可能: 1箇所でNetFUNNEL動作を簡単に変更できます
  • 可読性: メイン関数がクリーンで理解しやすくなります

5.7 完全なコールバック処理の追加​

すべてのNetFUNNEL応答状態に対する包括的な処理を追加します:

このステップは、すべての可能なNetFUNNEL応答状態に対処するためにコールバック処理を向上させます。各応答タイプは、最適なユーザー体験とサービス安定性を確保するために異なる処理戦略が必要です。

完全なコールバック処理が必須な理由:

  • ユーザー体験: 異なる応答タイプは適切なユーザーフィードバックが必要です
  • サービス安定性: エラー状態がユーザーのワークフローを中断してはなりません
  • デバッグ: 包括的なロギングが問題を迅速に識別するのに役立ちます
  • ビジネス継続性: NetFUNNELに問題が発生してもサービスが継続する必要があります
// すべてのビジネスロジックに対するNetFUNNEL応答処理
function handleNetFunnelResponse(response, businessLogic, retryCount = 0) {
  const MAX_RETRIES = 1; // 1回のみ再試行
  
  switch (response.status) {
    case 'Success':
      // 進入またはバイパス受信 - 元のサービスロジックを実行
      // 正常フロー: ユーザーがキューを通過して進行できる
      console.log('NetFUNNEL: Entry granted');
      businessLogic(); // 渡されたビジネスロジックを実行
      break;
      
    case 'Error':
      // システムエラー発生 - スムーズなUXのために元のロジックを実行
      // NetFUNNELサーバーエラー (500) - サービス可用性を維持するために継続進行
      console.log(`NetFUNNEL system error: ${response.message}`);
      businessLogic(); // サービス可用性を維持するために継続進行
      break;
      
    case 'NetworkError':
      // ネットワークエラー発生 - 再試行回数に応じて再試行または進行
      // 一時的なネットワーク問題 (1001, 1002) - 1回再試行後に進行
      if (retryCount < MAX_RETRIES) {
        console.log(`NetFUNNEL network error: ${response.message}. Retrying... (${retryCount + 1}/${MAX_RETRIES})`);
        setTimeout(() => {
          wrapWithNfStart(businessLogic, retryCount + 1);
        }, 2000); // 再試行前に2秒待機
      } else {
        console.log('NetFUNNEL: Max retries reached, proceeding without protection');
        businessLogic(); // 最大再試行後も継続進行
      }
      break;
      
    case 'Block':
      // 進入状態がブロック - ユーザーに通知
      // セグメントがブロック状態 (301) - ユーザーに通知し進行しない
      console.log('NetFUNNEL: Entry blocked');
      alert("このページは現在進入がブロックされています。");
      break;
      
    case 'IpBlock':
      // 繰り返しリクエストによりブロック - ユーザーに通知
      // BotManagerまたはブラックリストによりIPブロック (302) - ユーザーに通知し進行しない
      console.log('NetFUNNEL: IP blocked');
      alert("繰り返しリクエストによりブロックされました。");
      break;
      
    case 'Close':
      // ユーザーが待合室で閉じる/キャンセルをクリック
      // ユーザーが手動で待機をキャンセル (499) - ユーザーに通知し進行しない
      console.log('NetFUNNEL: Waiting canceled by user');
      alert("待機がキャンセルされました。");
      break;
  }
}

// 完全なコールバック処理が含まれたwrapWithNfStartの更新
function wrapWithNfStart(businessLogic, retryCount = 0) {
  if (typeof window.nfStart === 'function') {
    console.log(`Executing with NetFunnel`);
    nfStart(NETFUNNEL_CONFIG, (response) => {
      handleNetFunnelResponse(response, businessLogic, retryCount);
    });
  } else {
    console.log(`Executing without NetFunnel`);
    businessLogic();
  }
}

応答処理戦略:

応答タイプステータスコード作業ビジネスロジックユーザー通知
Success200, 300, 303実行✅ はいオプション
Error500実行✅ はいオプション
NetworkError1001, 1002再試行 → 実行✅ はい (再試行後)オプション
Block301停止❌ いいえオプション
IpBlock302停止❌ いいえオプション
Close499停止❌ いいえオプション

変更点:

  • 完全なコールバック処理: すべてのNetFUNNEL応答状態(Success, Error, NetworkError, Block, IpBlock, Close)を処理します
  • スマート再試行ロジック: NetworkErrorは2秒遅延後に自動的に1回再試行してから進行します
  • ユーザー通知: UX要件に応じてすべての応答タイプにオプション通知を追加できます
  • 優雅な劣化: エラー状態はサービス可用性を維持するためにビジネスロジックを継続進行します
  • 包括的なロギング: すべての応答タイプとデバッグのための詳細なコンソールメッセージ
完全なAPIリファレンス

すべてのコールバック応答タイプ、ステータスコード、応答オブジェクト構造、高度なコールバックパターンの詳細については、APIリファレンスを参照してください。

5.8 主要な実装ポイント​

  1. typeof確認: NetFUNNEL関数を呼び出す前に常にロードされているか確認
  2. プロジェクト/セグメントキー: NetFUNNELコンソールの正確なキーを使用
  3. コールバック分岐: Success, Error, NetworkError状態を適切に処理
  4. フォールバックロジック: NetFUNNELを使用できない場合でもサービスが継続することを保証

ステップ6: キー返却統合ポイントの識別 (nfStop)​

サンプルアプリケーション

次の例は実演目的でサンプルアプリケーションを使用します。実際のアプリケーションコードはここに示されたものとは自然に異なります。統合パターンを特定のコード構造、ビジネスロジック完了ポイント、キー返却要件に合わせて調整してください。

💡 練習プロジェクトが必要ですか? NetFUNNEL統合の練習のために準備された**Webアプリケーション(バニラJavaScript MPA)**テンプレートを含むサンプルプロジェクトを確認してください。

サンプルアプリケーションの理解:

NetFUNNELキーを返却するためにnfStopを呼び出す必要がある場所を理解するために、サンプルアプリケーションを見てみましょう。

6.1 ビジネスロジック完了ポイントの識別​

nfStart成功後の現在のフロー:

// ステップ5で - nfStartが成功するとき
case 'Success':
  console.log('NetFUNNEL: Entry granted');
  businessLogic(); // これはnavigateWithDelay(targetUrl)を実行します
  break;

次に発生すること:

  1. ユーザーがターゲットページに進入 (例: ./pages/basic-control-function/index.html)
  2. ページが完全にロードされる - すべてのリソース、スクリプト、コンテンツが準備される
  3. ユーザーのセッションがアクティブになる - 保護された機能を使用できるようになります
  4. キーを返却する必要がある - キューの次のユーザーが進入できるように

nfStop実装に関する重要な注意事項: nfStopはnfStartが最初に呼び出される必要なく独立して呼び出すことができます。nfStartが呼び出されなかった場合、NetFUNNELは必要に応じてキー解放を自動的に処理するか、キーがなければ何も行いません。これにより、nfStopは条件付き確認なしですべてのシナリオで安全に呼び出すことができ、実装がシンプルになります。

6.2 キー返却のための統合ポイントの識別​

統合ポイントオプション:

統合ポイント使用タイミング利点
ページロードシンプルなナビゲーションフロー実装が簡単で、ほとんどの場合に動作
ビジネスロジック完了複雑な作業 (API呼び出し、処理)精密な制御、実際の作業後にキー返却

6.3 適切な統合ポイントの選択​

サンプルアプリケーションの場合:

現在のビジネスロジック: navigateWithDelay(targetUrl)

  • 行うこと: サーバー処理をシミュレートし、ターゲットページにナビゲート
  • 完了時点: ターゲットページが正常にロードされたとき
  • 最適な統合ポイント: ターゲットページのページロードイベント

統合戦略:

  1. ターゲットページロード: ターゲットページがロードされたときにキー返却
  2. シンプルで安定: ナビゲーションベースのフローに動作
  3. ユーザー体験: ユーザーが実際にサービスを使用できるときにキーが返却される

6.4 統合ポイントロジックの確認​

全体フロー分析:

  1. ユーザーがボタンをクリック → nfStart()呼び出し
  2. 待合室が表示される → ユーザーがキューで待機
  3. 進入が許可される → Successコールバック発生
  4. ビジネスロジック実行 → navigateWithDelay(targetUrl)実行
  5. ターゲットページロード → ユーザーがサービスを使用できるようになる
  6. キー返却が必要 → キュースロットを解放するためにnfStop()呼び出し

この統合ポイントが合理的な理由:

  • ユーザー体験: ユーザーが実際にサービスを使用できるときにキーが返却される
  • キュー管理: 現在のユーザーが準備できたら次のユーザーが即座に進入できる
  • リソース効率: 不要なキューブロックを防止
  • 実装のシンプルさ: 実装と保守が容易

核心的な洞察: nfStop統合ポイントは、ユーザーの意図したビジネス作業が実際に完了し、キューに入ったサービスの利点を得られる場所である必要があります。

ステップ7: キー返却関数の実装 (nfStop)​

アプリケーションに合わせて調整

以下の例は、キーを返却するさまざまなアプローチを示しています。アプリケーションアーキテクチャに最も適したアプローチを選択してください - ページナビゲーション、API呼び出し、またはその他のビジネスロジック完了後にキーを返却する必要があるかどうか。

7.1 nfStop関数の理解​

nfStop関数は次のような基本構造を持ちます:

nfStop({
  projectKey: "your_project_key",    // nfStartキーと正確に一致する必要がある
  segmentKey: "your_segment_key"     // nfStartキーと正確に一致する必要がある
});

核心要件:

  • 正確なキー一致: nfStart()で使用したキーと同一である必要があります
  • タイミング: nfStart()直後ではなく、ビジネスロジック完了後に呼び出す

7.2 基本的なキー返却の追加 (ページロード)​

ページロードイベントのラッピング:

// ターゲットページに追加 (例: ./pages/basic-control-function/index.html)
window.addEventListener('load', function () {
  nfStop({
    projectKey: 'service_1',
    segmentKey: 'segKey_8612'
  });
});

変更点:

  • ページロード: ターゲットページがロードされたときにキー返却
  • シンプルなアプローチ: 基本的なナビゲーションシナリオに動作
  • 直接呼び出し: NetFUNNELがロードされ使用可能であると仮定

7.3 関数の可用性確認の追加​

エラーを防ぐためにtypeof確認を追加:

// ターゲットページに追加 (例: ./pages/basic-control-function/index.html)
window.addEventListener('load', function () {
  if (typeof window.nfStop === 'function') {
    nfStop({
      projectKey: 'service_1',
      segmentKey: 'segKey_8612'
    });
  } else {
    // NetFUNNELがロードされていない場合のフォールバック
    console.log('NetFUNNEL not available, skipping key return');
  }
});

この確認が必須な理由:

  • クラッシュ防止: この確認なしでNetFUNNELがロードされていない状態でnfStop()を呼び出すとReferenceErrorが発生します
  • 優雅な劣化: NetFUNNELがロードに失敗した場合(ネットワーク問題、CDN問題)、アプリが継続して動作します
  • 開発の柔軟性: NetFUNNELスクリプトがロードされていない状態でもテストできます

7.4 キー返却のベストプラクティス​

ベストプラクティス: キーを即座に返却

ビジネスロジックが完了したらNetFUNNELキーを返却してください。NetFUNNELはタイムアウト後に自動的にキーを返却しますが、手動返却はより良いユーザー体験とキュー効率を提供します。

ルール:

  • ✅ 常に: ビジネスロジックが完了した後(成功または失敗)にキー返却
  • ⚠️ 自動タイムアウト: 手動で返却しない場合、NetFUNNELが自動的にキーを返却します

例: ログインプロセス

function performLogin(loginData) {
  fetch('/api/login', {
    method: 'POST',
    body: JSON.stringify(loginData)
  })
  .then(response => response.json())
  .then(data => {
    // ログイン成功
    console.log('Login completed');
    // 成功したログイン後にキー返却
    if (typeof window.nfStop === 'function') {
      nfStop({
        projectKey: 'service_1',
        segmentKey: 'segKey_8612'
      });
    }
  })
  .catch(error => {
    // ログイン失敗 - しかし、まだキー返却
    console.error('Login failed:', error);
    if (typeof window.nfStop === 'function') {
      nfStop({
        projectKey: 'service_1',
        segmentKey: 'segKey_8612'
      });
    }
  });
}

核心要件:

  • 正確な一致: nfStop()のキーはnfStart()と正確に一致する必要があります
  • タイミング: 即座ではなく、ビジネスロジック完了後に呼び出す
  • 常に: 成功、失敗、エラー時にキー返却
完全なAPIリファレンス

nfStopパラメータ、応答処理、高度なキー返却パターンの詳細については、APIリファレンスを参照してください。

ステップ8: 待合室テスト (進入許容数 = 0)​

アプリケーションでテスト

以下のテストステップはサンプルアプリケーションに基づいています。テストプロセスを実際のアプリケーションに合わせて調整してください - ボタン名、URL、確認ステップを特定の実装に置き換えてください。

8.1 作業のトリガー​

  1. ネットワークログをクリア (クリーンな状態で観察したい場合)

    • DevToolsネットワークタブのゴミ箱アイコンをクリックして以前のログをクリア

  2. 保護されたボタンをクリック (例: "Basic Control (Code-based Integration)")

期待される結果: 現在の画面にモーダル待合室が表示される

Modal waiting room Waiting room modal display

8.2 待合室表示の確認​

次の要素が正しく表示されていることを確認してください:

進入許容数が0に設定され、1人のユーザーのみが接続されている場合の確認:

  • 私の待機順序: 1
  • 予想待機時間: N/A
  • 私の後ろの待機者数: 0

Waiting room details

8.3 ネットワーク活動の確認​

定期的なリクエストの確認:

  • 定期的に繰り返されるts.wseq?opcode=5002リクエストを見つける
  • opcode=5002 = 再進入リクエスト (進入が許可されるか尋ねるリクエスト)

Periodic re-entry requests

応答の確認:

  • ts.wseq?opcode=5002リクエストの1つをクリック
  • 応答本文が201 (待機)を表示していることを確認
  • 201 = 待機、200 = 通過 (進入許可)
  • ここでは進入許容数が0なので、正しい応答は201です

Response body showing 201 (WAIT)

8.4 エージェントファイルローディングの確認​

2つの必須ファイルが正常にロードされていることを確認:

  • HTTPステータス200でnetfunnel-javascript-agent.js
  • HTTPステータス200でnf-setting.json

Agent files loading successfully

ステップ9: 進入テスト (進入許容数 = 1)​

9.1 セグメント設定の更新​

  1. NetFUNNELコンソールに戻る
  2. セグメントの編集ボタンをクリックして編集画面を開く

Edit segment button

  1. 進入許容数を0から1に変更
  2. 下部の確認をクリック

Update limited inflow Confirm changes

即座に効果

確認をクリックすると即座に待合室が消え、ターゲットページに即座に進入します。この瞬間を観察するには、待合室が現在表示されている別の画面を開いておいてください。

9.2 進入確認​

期待される結果: 待合室が即座に消え、元のロジックが実行される

Service entry successful

9.3 キー返却確認​

成功したキー返却の確認:

  • HTTP 200でts.wseq?opcode=5004リクエスト
  • opcode=5004 = キー返却リクエスト
  • キューの次のユーザーが待機を終了し、サービスに進入できるように必要

Key return request

要約​

必須事項 (必ず実行)​

設定:

  • NetFUNNELエージェントをインストールし、ファイルがHTTP 200でロードされることを確認
  • コンソールで基本コントロールでセグメント作成
  • コンソールからプロジェクトキーとセグメントキーを取得
  • テストのために進入許容数を0に、本番のために1以上に設定

統合:

  • NetFUNNEL関数を呼び出す前にtypeof確認を追加
  • クリックハンドラーでnfStart()でビジネスロジックをラップ
  • ビジネスロジックを実行するためにSuccess応答を処理
  • ビジネスロジック完了後にnfStop()を呼び出す
  • nfStart()とnfStop()の両方で同じキーを使用

エラー処理:

  • Errorはビジネスロジックを継続進行して処理
  • NetworkErrorは1回再試行してからビジネスロジックを継続進行して処理
  • BlockとIpBlockはユーザー通知を表示して処理
  • Closeは何も行わない(ユーザーがキャンセル)
  • NetFUNNELを使用できない場合のフォールバックロジックを提供

テスト:

  • 進入許容数 = 0のときに待合室が表示されることをテスト
  • 進入許容数 = 1のときに進入が動作することをテスト
  • 完了後にキー返却が発生することを確認

オプション (あれば良い)​

エラー処理の向上:

  • NetworkError応答に対する再試行ロジックの追加
  • 再試行に対する指数バックオフの実装
  • アラートの代わりにユーザーフレンドリーなエラーメッセージの追加

コード構成:

  • centralized構成オブジェクトの作成
  • 再利用可能なラッパー関数の構築
  • モジュール式統合パターンの実装

ベストプラクティス​

関数の可用性確認​

if (typeof window.nfStart === 'function') {
  // NetFUNNEL使用可能
  nfStart(config, callback);
} else {
  // フォールバックロジック
  console.log('NetFUNNEL not available, proceeding without protection');
  executeBusinessLogic();
}

これが重要な理由:

  • NetFUNNELスクリプトロード失敗時のクラッシュ防止
  • NetFUNNELを使用できない場合でもアプリが動作することを許可
  • 開発およびテストに必須

集中化された構成​

// キーを1箇所に保存
const NETFUNNEL_CONFIG = {
  projectKey: 'service_1',
  segmentKey: 'segKey_8612'
};

// すべての場所で同じ構成を使用
nfStart(NETFUNNEL_CONFIG, callback);
nfStop(NETFUNNEL_CONFIG);

利点:

  • アプリ全体でキーを簡単に更新
  • コピー&ペーストエラーの削減
  • 構成に対する単一ソース

完全なエラー処理​

function handleNetFunnelResponse(response, businessLogic, retryCount = 0) {
  const MAX_RETRIES = 1;
  
  switch (response.status) {
    case 'Success':
      businessLogic(); // ロジック進行
      break;
    case 'Error':
      // システムエラー - サービスを継続実行するために継続進行
      console.error('NetFUNNEL system error:', response.message);
      businessLogic();
      break;
    case 'NetworkError':
      // ネットワーク問題 - 1回再試行してから進行
      if (retryCount < MAX_RETRIES) {
        console.log(`NetFUNNEL network error: ${response.message}. Retrying... (${retryCount + 1}/${MAX_RETRIES})`);
        setTimeout(() => {
          nfStart(NETFUNNEL_CONFIG, (response) => {
            handleNetFunnelResponse(response, businessLogic, retryCount + 1);
          });
        }, 2000); // 再試行前に2秒待機
      } else {
        console.log('NetFUNNEL: Max retries reached, proceeding without protection');
        businessLogic(); // 最大再試行後も継続進行
      }
      break;
    case 'Block':
      alert("サービスを一時的に使用できません。後でもう一度お試しください。");
      break;
    case 'IpBlock':
      alert("アクセスが拒否されました。この問題が続く場合はサポートチームにお問い合わせください。");
      break;
    case 'Close':
      // ユーザーがキャンセル - 作業不要
      break;
  }
}

核心原則: サービス可用性を維持するために、システムエラー時に常にビジネスロジックを継続進行します。

常にキー返却​

// 成功した作業後にキー返却
fetch('/api/process-payment')
  .then(response => response.json())
  .then(data => {
    console.log('Payment processed');
    // 成功した決済後にキー返却
    if (typeof window.nfStop === 'function') {
      nfStop(NETFUNNEL_CONFIG);
    }
  })
  .catch(error => {
    console.error('Payment failed:', error);
    // エラー発生時にもキー返却
    if (typeof window.nfStop === 'function') {
      nfStop(NETFUNNEL_CONFIG);
    }
  });

キーを返却するタイミング:

  • 成功したAPI呼び出し後
  • ページナビゲーション完了後
  • フォーム送信完了後
  • 作業が失敗した場合でも

キー一致​

// 開始と停止は同じキーを使用する必要がある
const keys = { projectKey: 'service_1', segmentKey: 'segKey_8612' };
nfStart(keys, callback);
nfStop(keys); // 正確に一致する必要がある

一般的な問題とトラブルシューティング​

待合室が表示されない​

症状: ボタンクリックが正常に動作するが待合室が表示されない

デバッグステップ:

  1. ブラウザコンソールでJavaScriptエラーを確認
  2. NetFUNNELエージェントファイルがHTTP 200でロードされていることを確認:
    • netfunnel-javascript-agent.js
    • nf-setting.json
  3. セグメントが有効化されていることを確認(無効化されていない)
  4. テストのために進入許容数が0に設定されていることを確認

コールバックが発生しない​

症状: nfStartが呼び出されたが応答を受け取らない

デバッグステップ:

  1. NetFUNNELサーバーへの失敗したリクエストについてネットワークタブを確認
  2. プロジェクト/セグメントキーがコンソールと正確に一致していることを確認(大文字小文字を区別)
  3. セグメントが有効化されていることを確認(無効化されていない)
  4. 待合室を強制的に表示するために進入許容数 = 0で試す

ユーザーがキューに閉じ込められる​

症状: 最初のユーザーは進入するが、2番目のユーザーは決して通過しない

デバッグステップ:

  1. ビジネスロジック完了後にnfStop()が呼び出されていることを確認
  2. nfStop()のキーがnfStart()と正確に一致していることを確認
  3. nfStop()実行を妨げるJavaScriptエラーを見つける
  4. ネットワークタブでts.wseq?opcode=5004 (キー返却)リクエストを確認

待合室が表示されるが進入を許可しない​

症状: 待合室が表示されるが、ユーザーが決して通過しない、進入許容数 = 1でも

デバッグステップ:

  1. コンソールでセグメント状態を確認 - "ブロック"モードではないことを確認
  2. 進入許容数が1以上に設定されていることを確認
  3. ネットワークタブでts.wseq?opcode=5002リクエストを確認
  4. リクエスト詳細でエラー応答を見つける

QAチェックリスト​

実装前確認​

  • プロジェクトキー / セグメントキーがコンソールと正確に一致する (コンソールで再確認)
  • エージェントファイル(netfunnel-javascript-agent.jsおよびnf-setting.json)がHTTP 200でロードされる
  • エージェントロード前に関数を呼び出すことを防ぐために**typeof確認**が実装される

待合室テスト (進入許容数 = 0)​

  • 進入許容数 = 0のときに待合室モーダルが正しく表示される
  • 待合室が正しい詳細を表示する:
    • 私の待機順序: 1
    • 予想待機時間: N/A
    • 私の後ろの待機者数: 0
  • 待機中に**ts.wseq?opcode=5002**リクエストが定期的に繰り返される
  • **ts.wseq?opcode=5002応答本文が201 (待機)**を表示する

進入テスト (進入許容数 = 1)​

  • 進入許容数を1に変更するとSuccessコールバックが発生する
  • Successコールバックが元のビジネスロジックを実行する
  • 進入時に待合室が即座に消える

キー返却確認​

  • 完了ポイントでキー返却が正しく動作する
  • ts.wseq?opcode=5004リクエストがHTTP 200で発生する
  • キー返却がnfStart呼び出しあたり正確に1回発生する
  • キー返却がビジネスロジック完了後に発生する

エラー処理​

  • すべての必須状態に対してコールバック分岐が実装される:
    • Success - 元のロジック実行
    • Error - システムエラーを適切に処理
    • NetworkError - ネットワーク問題を適切に処理
  • NetFUNNEL関数を使用できない場合のフォールバックロジックが動作する
  • キー一致 - nfStartとnfStopでprojectKey/segmentKeyが同一