トラブルシューティング & FAQ
NetFUNNEL JavaScriptエージェント統合に関する一般的な問題、解決方法、よくある質問です。
目次
インストール問題
エージェントスクリプトがロードされない
症状:
- Networkタブに
netfunnel-javascript-agent.jsがない - エージェントファイルに対するHTTP 404またはその他のエラー
解決方法:
- スクリプトURL確認:
srcURLが正しく、アクセス可能か確認 - ネットワーク接続: サーバーがNetFUNNELサーバーに接続できるか確認
- 広告ブロッカー: スクリプトをブロックできる広告ブロッカーを無効化
- スクリプト配置: スクリプトを
<head>タグの最上部に移動
<!-- 正しい配置 -->
<head>
<script src="https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js" data-nf-client-id="your-client-id"></script>
<!-- その他のスクリプト -->
</head>
設定ファイルがロードされない
症状:
- Networkタブに
nf-setting.jsonがない - 設定ファイルに対するHTTPエラー
解決方法:
data-nf-client-id確認: クライアントIDが正しいか確認- コンソールアクセス: NetFUNNELコンソールに適切なアクセス権限があるか確認
- セグメントの有効化: コンソールでセグメントが有効化されているか確認
バイパスモード (待合室なし)
症状:
- ユーザーが待合室なしでページに直接アクセス
- NetFUNNELトラフィック制御なし
解決方法:
- 必須属性:
data-nf-client-idがあるか確認 - セグメントの有効化: コンソールでセグメントが有効化されているか確認
- 進入許容数: 進入許容数が無制限に設定されていないか確認
- トリガールール: トリガールールがURLと正しく一致しているか確認
関数呼び出しエラー
"nfStart is not a function" エラー
症状:
ReferenceError: nfStart is not defined- 呼び出し時に関数が定義されていない
解決方法:
- 関数可用性確認: 呼び出す前に常に関数が存在するか確認
if (typeof window.nfStart === 'function') {
nfStart(keys, callback);
} else {
// 代替ロジック
console.log('NetFUNNEL not available');
}
- スクリプトロード順序: NetFUNNELスクリプトがコードより先にロードされているか確認
- ロード待機:
window.loadイベント後に関数呼び出し
window.addEventListener('load', function() {
// ここでNetFUNNEL関数を安全に呼び出せる
});
コールバックが実行されない
症状:
nfStartが呼び出されたがコールバックが実行されない- 応答を受け取れない
解決方法:
- ネットワーク確認: NetFUNNELサーバーに対するネットワークリクエスト確認
- コンソールログ: デバッグのために
data-nf-print-log="true"を有効化 - セグメント状態: セグメントがBlock状態でないか確認
- 進入許容数: 進入許容数が進入を許可しているか確認
ネットワークおよび接続問題
ネットワークタイムアウトエラー
症状:
- ステータスコード1002と共に
NetworkError - リクエストがタイムアウトした
解決方法:
- タイムアウト増加:
data-nf-network-timeoutをより高い値に設定 (最大10000ms) - 再試行構成:
data-nf-retry-countを増加 - ネットワーク回復:
data-nf-use-network-recovery-mode="true"を有効化
<script
src="https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js"
data-nf-client-id="your-client-id"
data-nf-network-timeout="5000"
data-nf-retry-count="2"
data-nf-use-network-recovery-mode="true"
></script>
ネットワーク接続なしエラー
症状:
- ステータスコード1001と共に
NetworkError - インターネット接続なし
解決方法:
- 接続確認: インターネット接続確認
- ファイアウォール: NetFUNNELドメインがブロックされていないか確認
- プロキシ設定: 必要に応じてプロキシ構成
- エラー処理: 適切なNetworkError処理を実装
function nfCallback(response) {
if (response.status === 'NetworkError') {
// ユーザーフレンドリーなメッセージを表示
alert('ネットワーク接続問題が発生しました。インターネット接続を確認してください。');
// オプションで再試行または続行
}
}
待合室問題
待合室が表示されない
症状:
- 待合室が表示されない
- ユーザーが直接進行する
解決方法:
- 進入許容数: テストのために0に設定
- セグメントの有効化: セグメントが有効化されているか確認
- トリガールール: URL一致ルール確認
- テンプレート設定:
data-nf-use-netfunnel-template="true"確認
待合室が停止する (終わらない)
症状:
- 待合室が表示されるが進入を許可しない
- 無限待機
解決方法:
- 進入許容数: 進入許容数値を増加
- セグメント状態: セグメントがBlock状態でないか確認
- ネットワーク問題: ネットワーク接続確認
- サーバー状態: NetFUNNELサーバー状態確認
モーダルが表示されない (コードベース)
症状:
- コードベース統合でモーダルが表示されない
- 代わりにページがリダイレクトされる
解決方法:
- 統合方法: URLトリガーではなくコードベースを使用しているか確認
- 関数呼び出し:
nfStartが正しく呼び出されているか確認 - コールバック処理: コールバックが実装されているか確認
- テンプレート設定:
data-nf-use-netfunnel-template="true"確認
キー管理問題
キーが返却されない
症状:
- 次のユーザーが無限に待機する
- 待機列が進行しない
解決方法:
- 常にnfStop呼び出し:
nfStop/nfStopSectionが呼び出されているか確認 - エラー処理: エラーシナリオでもキー返却
- タイムアウト設定: セグメントタイムアウト設定確認
- 関数一致: 開始/停止に同じキーを使用
// 常にキー返却
try {
performAction();
nfStop(keys); // 成功ケース
} catch (error) {
nfStop(keys); // エラーケース - それでもキー返却
}
キー不一致エラー
症状:
- 不正なキーに対するサーバーエラー
- キーが見つからないエラー
解決方法:
- キー一貫性: 開始/停止関数に同じキーを使用
- キースコープ: 異なる動作間でキーを再利用しない
- タイミング: 開始が完了する前に停止呼び出しをしない
// 正しい: 開始および停止に同じキーを使用
const keys = { projectKey: 'service_1', segmentKey: 'segKey_123' };
nfStart(keys, callback);
nfStop(keys);
構成問題
不正なプロジェクト/セグメントキー
症状:
- 関数が呼び出されたが効果がない
- 不正なセグメント動作
解決方法:
- コンソール確認: NetFUNNELコンソールでキーを再度確認
- 正確にコピー: コンソールに表示された通りにキーを正確にコピー
- 環境: 正しい環境を使用しているか確認 (本番 vs ステージング)
Data属性が動作しない
症状:
- 構成オプションが適用されない
- 予期しない動作
解決方法:
- 属性形式: 正しい形式を使用 (例:
data-nf-timeout="5000") - 値範囲: 値が許可された範囲内にあるか確認
- 方法互換性: 属性が統合方法に適用されるか確認
ブラウザおよび環境問題
広告ブロッカー干渉
症状:
- スクリプトがブロックされる
- ネットワークリクエストがブロックされる
解決方法:
- ドメイン許可リスト: NetFUNNELドメインを広告ブロッカー許可リストに追加
- ユーザー指示: ユーザーに指示を提供
- 代替処理: 優雅なパフォーマンス低下を実装
ブラウザ互換性
症状:
- 特定のブラウザで関数が動作しない
- JavaScriptエラー
解決方法:
- ブラウザサポート: ブラウザ互換性確認
- ポリフィル: 古いブラウザに必要なポリフィルを追加
- 機能検出: 関数呼び出し前に機能検出を使用
開発 vs 本番
症状:
- 開発環境では動作するが本番では動作しない
- 環境間で異なる動作
解決方法:
- 環境URL: 各環境に対する正しいURLを使用
- コンソール構成: 開発/本番用の別セグメント設定
- キャッシング: ブラウザキャッシュおよびCDNキャッシュをクリア
FAQ
スクリプトを共通JSファイルに入れることができますか?
A: はい、スクリプトを動的に挿入できます:
<script src="./netfunnel.js" defer></script>
// netfunnel.js
var scriptNF = document.createElement("script");
scriptNF.setAttribute("data-nf-client-id", "your-client-id");
scriptNF.src = "https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js";
document.head.appendChild(scriptNF);
NetworkErrorをどのように処理すべきですか?
A: ユーザーに通知し、nfStartを再試行するか、元のロジックを続行してください:
function handleNetworkError(response) {
if (confirm('ネットワークエラーが発生しました。再度試行しますか?')) {
nfStart(keys, callback); // 再試行
} else {
performOriginalLogic(); // とにかく続行
}
}
キーを返却することを忘れたらどうなりますか?
A: キーはサーバータイムアウトによって自動的に返却される可能性がありますが、これによりボトルネックが発生する可能性があります。常に明示的に返却してください:
// 良い: 常にキー返却
nfStart(keys, function(response) {
if (response.status === 'Success') {
performAction()
.then(() => nfStop(keys))
.catch(() => nfStop(keys)); // エラー発生時にも
}
});
URLトリガーとコードベース方法を両方使用できますか?
A: はい、単一サービス内で方法を混在させることができます:
- URLトリガーをページ進入速度制御に使用
- コードベースをビジネス同時ユーザー数制御に使用
ただし、運用の複雑さを減らすために、1つの方法を優先的に使用することが推奨されます。
NetFUNNEL統合をどのようにデバッグしますか?
A: ロギングを有効化し、コンソールを確認してください:
<script
src="https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js"
data-nf-client-id="your-client-id"
data-nf-print-log="true"
></script>
その後、DevToolsコンソールでNetFUNNELログメッセージを確認してください。
基本コントロールと区間コントロールの違いは何ですか?
A:
- 基本コントロール: 進入速度を制限します (ユーザーがどれだけ速く進入できるか)
- 区間コントロール: 固定された同時ユーザー数を維持します (同時にアクティブにできるユーザー数)
簡単な進入制限には基本コントロールを使用し、特定の同時実行レベルを維持するには区間コントロールを使用してください。
ヘルプを得る
まだ問題が発生する場合:
- コンソールログ確認:
data-nf-print-log="true"を有効化し、ブラウザコンソールを確認 - 構成確認: NetFUNNELコンソールのすべての設定を再度確認
- 簡単な設定でテスト: 基本構成で開始し、段階的に複雑さを追加
- サポートチームに問い合わせ: 具体的なエラー詳細と共にNetFUNNELサポートチームに問い合わせ
関連ドキュメント
- クイックスタート: 迅速に開始する
- インストールおよび初期化: 基本設定ガイド
- URLトリガー方法: URLベースのトラフィック制御
- コードベース方法: 関数ベースのトラフィック制御
- APIリファレンス: 完全な関数仕様
- 初期化オプションリファレンス: 利用可能なすべてのオプション