APIリファレンス

NetFUNNEL JavaScriptエージェント関数、コールバック、応答形式の完全な参照です。

---

目次

• 基本コントロール関数
• 区間コントロール関数
• コールバック関数
• 応答オブジェクトスキーマ
• ステータスコード参照
• ベストプラクティス

---

基本コントロール関数

基本コントロールはサービスの進入速度を制限します。開始関数が呼び出されるとキーが発行され、待合室が表示されます。停止関数が呼び出されるとキーが返却されます。

nfStart

目的: 動作開始時にキーを発行し、待合室を表示します。

関数シグネチャ:

nfStart(keys, callback)

パラメータ:

パラメータ	タイプ	説明	必須
keys	Object	プロジェクトおよびセグメントキーを含むオブジェクト	はい
keys.projectKey	String	コンソールの基本コントロールプロジェクトキー	はい
keys.segmentKey	String	コンソールの基本コントロールセグメントキー	はい
callback	Function	VWRイベントを処理するカスタムコールバック	はい

戻り値: undefined

例:

nfStart({
  projectKey: "service_1",
  segmentKey: "segKey_8612"
}, function(response) {
  // 応答処理 - 詳細についてはコールバック関数セクションを参照
  if (response.status === 'Success') {
    // ロジック進行
    console.log('Entry granted!');
  }
});

コールバック処理: 詳細な応答処理については、コールバック関数セクションを参照してください。

nfStop

目的: 進入が完了した後にキーを返却します。

関数シグネチャ:

nfStop(keys)

パラメータ:

パラメータ	タイプ	説明	必須
keys	Object	プロジェクトおよびセグメントキーを含むオブジェクト	はい
keys.projectKey	String	コンソールの基本コントロールプロジェクトキー	はい
keys.segmentKey	String	コンソールの基本コントロールセグメントキー	はい

戻り値: undefined

例:

nfStop({
  projectKey: "service_1",
  segmentKey: "segKey_8612"
});

自動返却タイムアウト

停止関数を実行しない場合、セグメントタイムアウト設定に従ってキーが自動的に返却されます (デフォルトタイムアウト: 20秒)。

---

区間コントロール関数

区間コントロールは特定のアプリケーション区間の同時ユーザー数を固定値で維持します。開始関数が呼び出されるとキーが発行されます。停止関数が呼び出されるまでユーザーはアクティブな区間にいるものと見なされ、キューの次のユーザーは許可されません。

nfStartSection

目的: 区間コントロールのためにキーを発行し、待合室を表示します。

関数シグネチャ:

nfStartSection(keys, callback)

パラメータ:

パラメータ	タイプ	説明	必須
keys	Object	プロジェクトおよびセグメントキーを含むオブジェクト	はい
keys.projectKey	String	コンソールの区間コントロールプロジェクトキー	はい
keys.segmentKey	String	コンソールの区間コントロールセグメントキー	はい
callback	Function	VWRイベントを処理するカスタムコールバック	はい

戻り値: undefined

例:

nfStartSection({
  projectKey: "service_1",
  segmentKey: "section_segKey_1234"
}, function(response) {
  // 応答処理 - 詳細についてはコールバック関数セクションを参照
  if (response.status === 'Success') {
    // ユーザーが区間に進入
    console.log('Section entry granted!');
  }
});

コールバック処理: 詳細な応答処理については、コールバック関数セクションを参照してください。

nfStopSection

目的: ユーザーがアクティブな区間を終了するときにキーを返却します。

関数シグネチャ:

nfStopSection(keys)

パラメータ:

パラメータ	タイプ	説明	必須
keys	Object	プロジェクトおよびセグメントキーを含むオブジェクト	はい
keys.projectKey	String	コンソールの区間コントロールプロジェクトキー	はい
keys.segmentKey	String	コンソールの区間コントロールセグメントキー	はい

戻り値: undefined

例:

nfStopSection({
  projectKey: "service_1",
  segmentKey: "section_segKey_1234"
});

区間コントロール動作

停止関数を実行しない場合、ユーザーがアクティブな区間に継続して留まっているものと見なされ、次のユーザーの許可が遅延する可能性があります。

---

コールバック関数

基本/区間コントロール開始関数(nfStartおよびnfStartSection)のコールバック関数(2番目のパラメータ)でNetFUNNELサーバーの応答を受信できます。応答結果に基づいてさまざまな処理ロジックを実行できます。

必須状態処理

次の3つの状態を必ず処理する必要があります:

• Success: 進入許可またはバイパスモード
• Error: システムエラー発生
• NetworkError: ネットワーク接続問題

サンプルコールバック実装

function nfCallback(response) {
  const { status, statusCode, message } = response;
  
  switch (status) {
    case 'Success':
      // 進入またはバイパス受信 — 元のサービスロジックを実行
      console.log('User can proceed!');
      // 例: ページに移動、関数実行、API呼び出し
      break;
      
    case 'Error':
      // システムエラー発生 — スムーズなUXのために元のロジックを実行
      console.log(`System error: ${message}`);
      // 例: ページに移動、関数実行、API呼び出し
      break;
      
    case 'NetworkError':
      // ネットワークエラー発生 — 再帰呼び出しで再試行
      console.log(`Network error: ${message}`);
      // NetFUNNEL開始関数を再試行するための再帰呼び出し
      nfStart(keys, nfCallback); // または nfStartSection(keys, nfCallback)
      break;
      
    case 'Block':
      // 進入状態がBlock — ユーザーに通知
      console.log('Access blocked');
      // 例: alert("This page is blocked for entry.");
      break;
      
    case 'IpBlock':
      // 繰り返しリクエストによるブロック
      console.log('IP blocked');
      // 例: alert("You have been blocked due to repeated requests.");
      break;
      
    case 'Close':
      // ユーザーが待合室で閉じる/キャンセルをクリック
      console.log('Waiting canceled by user');
      // 例: alert("Waiting has been canceled.");
      break;
      
    default:
      console.log(`[NF] status: ${status}, code: ${statusCode}, message: ${message}`);
  }
}

---

応答オブジェクトスキーマ

コールバックに渡されるresponseオブジェクトは次のフィールドを含みます:

フィールド	タイプ	例 / 説明
status	String	Success / Error / NetworkError / Block / IpBlock / Close
statusCode	Number	200, 201, 300, 303, 500, 1001, 1002, 301, 302, 49xなど
message	String	Success, Bypass, Express, Server Error, Network Timeoutなど
key	String	発行された進入キー (ID)

例の応答オブジェクト:

// Success応答
{
  status: "Success",
  statusCode: 200,
  message: "Success",
  key: "key_12345"
}

// Bypass応答
{
  status: "Success", 
  statusCode: 300,
  message: "Bypass",
  key: "key_12345"
}

// ネットワークエラー応答
{
  status: "NetworkError",
  statusCode: 1002,
  message: "Network Timeout",
  key: "key_12345"
}

---

ステータスコード参照

可能なすべてのステータスコードとその意味の完全な参照です。

状態	StatusCode	Message	説明
Success	200	Success	キューを正常に通過してサービスに進入
	300	Bypass	サブスクリプション/ライセンス期限切れ、プロジェクト/セグメント無効化、data-nf-error-bypass=true
	303	Express	Express進入成功
Error	500	Server Error	存在しないキー使用、待機中セグメント削除、サーバーエラー
NetworkError	1001	Network Not Connected	ネットワーク接続ブロック
	1002	Network Timeout	ネットワーク遅延、不正な待合室HTML、サーバーダウン
Block	301	Block	セグメントがブロック状態
IpBlock	302	Macro Block	ブラックリスト、BotManager Basic有効化
Close	499	Canceled Waiting Room	デフォルト待合室でキャンセル/閉じるボタンをクリック
	498	Closed Blocking Room	ブロッキングルームを閉じる
	497	Closed Macro Blocking Room	マクロブロッキングルームを閉じる
	496	Closed PreWaiting Room	事前待合室を閉じる
	495	Closed PostWaiting Room	事後待合室を閉じる

---

ベストプラクティス

関数の可用性確認

NetFUNNEL関数を呼び出す前に常に使用可能か確認してください:

if (typeof window.nfStart === 'function') {
  nfStart(keys, callback);
} else {
  // 代替ロジック
  console.log('NetFUNNEL not available, proceeding without protection');
  performOriginalLogic();
}

キー一致

開始および停止関数は同一のキーを使用する必要があります:

const keys = { 
  projectKey: 'service_1', 
  segmentKey: 'segKey_8612' 
};

// 開始
nfStart(keys, callback);

// 停止 (同一のキーを使用する必要がある)
nfStop(keys);

キー返却戦略

ユーザーが正常に進入した場合にのみキーを返却してください:

function performAction() {
  nfStart(keys, function(response) {
    if (response.status === 'Success') {
      doSomething();
    }
  });
}

// ページロード時にキー返却 (ページナビゲーションケース用)
window.addEventListener('load', () => {
  if (typeof window.nfStop === 'function') {
    nfStop(keys);
  }
});

一般的な統合パターン

ボタンクリック保護

document.getElementById('login-button').addEventListener('click', () => {
  if (typeof window.nfStart === 'function') {
    nfStart({
      projectKey: 'service_1',
      segmentKey: 'login_segKey'
    }, function(response) {
      // 詳細な応答処理についてはコールバック関数セクションを参照
      if (response.status === 'Success') {
        performLogin();
      } else {
        handleError(response);
      }
    });
  } else {
    performLogin(); // 代替
  }
});

function performLogin() {
  // ログインロジックをここに記述
  fetch('/api/login', { /* ... */ })
    .then(() => {
      // ログイン成功後にキー返却
      if (typeof window.nfStop === 'function') {
        nfStop({
          projectKey: 'service_1',
          segmentKey: 'login_segKey'
        });
      }
    })
    .catch(() => {
      // エラー発生時にもキー返却
      if (typeof window.nfStop === 'function') {
        nfStop({
          projectKey: 'service_1',
          segmentKey: 'login_segKey'
        });
      }
    });
}

再帰呼び出しを使用したNetworkError処理

NetworkError状態の場合、NetFUNNEL開始関数を再試行するために再帰呼び出しを実装する必要があります。これにより、ネットワーク問題が一時的な場合により良いユーザー体験を保証できます。

// 再帰呼び出しを使用した基本コントロールNetworkError処理
function startWithRetry(keys) {
  nfStart(keys, function(response) {
    switch (response.status) {
      case 'Success':
        // 元のロジック進行
        performAction();
        break;
        
      case 'NetworkError':
        console.log('Network error, retrying...');
        // 再試行のための再帰呼び出し
        startWithRetry(keys);
        break;
        
      case 'Error':
        console.log('System error, proceeding without protection');
        performAction();
        break;
        
      default:
        console.log(`Unexpected status: ${response.status}`);
        performAction();
    }
  });
}

// 再帰呼び出しを使用した区間コントロールNetworkError処理
function startSectionWithRetry(keys) {
  nfStartSection(keys, function(response) {
    switch (response.status) {
      case 'Success':
        // ユーザーが区間に進入
        showCheckoutForm();
        break;
        
      case 'NetworkError':
        console.log('Network error, retrying section entry...');
        // 再試行のための再帰呼び出し
        startSectionWithRetry(keys);
        break;
        
      case 'Error':
        console.log('System error, proceeding without section protection');
        showCheckoutForm();
        break;
        
      default:
        console.log(`Unexpected status: ${response.status}`);
        showCheckoutForm();
    }
  });
}

// 使用例
const keys = {
  projectKey: 'service_1',
  segmentKey: 'segKey_8612'
};

// 再試行ロジックとともに開始
startWithRetry(keys);

function performAction() {
  // ビジネスロジックをここに記述
  console.log('Performing protected action...');
  
  // 動作完了時にキー返却
  nfStop(keys);
}

function showCheckoutForm() {
  // チェックアウトフォームロジックをここに記述
  console.log('Showing checkout form...');
}

マルチステップ区間コントロール

// 区間開始 (例: チェックアウトプロセス)
function startCheckout() {
  nfStartSection({
    projectKey: 'service_1',
    segmentKey: 'checkout_segKey'
  }, function(response) {
    // 詳細な応答処理についてはコールバック関数セクションを参照
    if (response.status === 'Success') {
      showCheckoutForm();
    }
  });
}

// 区間終了 (例: 決済完了後)
function completeCheckout() {
  // チェックアウト完了ロジック
  processPayment()
    .then(() => {
      // 成功した完了後にキー返却
      nfStopSection({
        projectKey: 'service_1',
        segmentKey: 'checkout_segKey'
      });
    });
}

---

関連ドキュメント

• コードベース方法: 例を含む実装ガイド
• 初期化オプションリファレンス: すべてのdata-attributeオプション
• トラブルシューティング: 一般的な問題および解決方法