バージョン: 4.6.1

インストールおよび初期化

このガイドはURLトリガー統合とコードベース統合方法の両方に適用される必須設定ステップを扱います。

ステップ1: 初期化コードの取得

本番コードが必要

以下のコードは例に過ぎません。NetFUNNELコンソールの専用初期化コードを必ず使用してください。

実際の初期化コードを取得する方法:

NetFUNNELコンソールに移動
上部のエージェントメニューをクリック
クライアント側エージェント → JavaScriptに移動
2. インストール方法セクションからプロジェクト別コードをコピー

Agent initialization script placement

コンソール vs. ドキュメント

NetFUNNELコンソールでは初期化スクリプトにdata-nf-client-idが表示されます。すべての利用可能な属性の完全なリストについては、このドキュメントを参照してください。

例の初期化コード:

<script
    src="https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js"
    data-nf-client-id="your-client-id"
></script>

必須属性

初期化スクリプトには次の必須属性が必要です:

属性	説明	必須
`data-nf-client-id`	クライアント識別子	はい

全属性参照

オプションのネットワーク設定、ストレージオプション、デバッグ機能を含むすべての利用可能な属性の詳細については、初期化オプションリファレンスを参照してください。

ステップ2: すべてのHTMLファイルに適用

方法A: 直接HTML挿入 (推奨)

最大の信頼性とパフォーマンスのために、初期化スクリプトを各HTMLファイルに直接適用します。

重要: 最初にロードする必要がある

NetFUNNELエージェントはページロード時に他のすべてのものより先に実行される必要があります。すべてのHTMLファイルの<head>最上部に配置してください。

これが重要な理由:

トラフィック制御はスクリプトがロードされたページにのみ適用されます
エージェントは他のスクリプトが実行される前にリクエストをインターセプトする必要があります
このステップを逃すと = バイパスモード (待合室保護なし)

重要なタイミング要件:

NetFUNNELスクリプトにdeferまたはasync属性を使用しないでください
スクリプトは同期的に即座に実行される必要があります

エラー処理が必要

重要: ユーザーがトラフィック制御をバイパスすることを防ぐために、常にエラー処理を実装してください。詳細な実装については、エラー処理 - 方法Aセクションを参照してください。

一般的な位置:

メインページ (index.html)
ランディングページ
SPAエントリーポイント
エラーページ (保護したい場合)

複数ページの例:

<!-- main/index.html -->
<head>
  <script
      src="https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js"
      data-nf-client-id="your-client-id"
  ></script>
  <!-- 他のhead要素 -->
</head>

<!-- landing/index.html -->  
<head>
  <script
      src="https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js"
      data-nf-client-id="your-client-id"
  ></script>
  <!-- 他のhead要素 -->
</head>

方法B: 動的スクリプト注入 (代替)

多くのHTMLファイルがあり、NetFUNNEL初期化を集中化したい場合は、共通JavaScriptファイルを介して動的スクリプト注入を使用できます。

重要: 最初にロードする必要がある

動的注入を使用しても、NetFUNNELスクリプトは依然としてページで実行される最初のスクリプトである必要があります。共通JavaScriptファイルが他のすべてのスクリプトより先にロードされるようにしてください。

これが重要な理由:

トラフィック制御はスクリプトがロードされたページにのみ適用されます
エージェントは他のスクリプトが実行される前にリクエストをインターセプトする必要があります
このステップを逃すと = バイパスモード (待合室保護なし)

重要なタイミング要件:

最初の位置を保証するためにinsertBefore(script, head.firstChild)を使用
NetFUNNELスクリプトにdeferまたはasync属性を使用しないでください
スクリプトは同期的に即座に実行される必要があります

エラー処理が必要

重要: ユーザーがトラフィック制御をバイパスすることを防ぐために、常にエラー処理を実装してください。詳細な実装については、エラー処理 - 方法Bセクションを参照してください。

ステップ1: 共通JavaScriptファイルの作成

プロジェクトにnetfunnel-init.js(または類似の名前)ファイルを作成します:

// netfunnel-init.js
(function() {
  // NetFUNNELが既にロードされているか確認
  if (window.NetFUNNEL || document.querySelector('script[data-nf-client-id]')) {
    return;
  }

  // NetFUNNELスクリプト要素の作成および構成
  var scriptNF = document.createElement("script");
  
  // 必須属性の設定
  scriptNF.setAttribute("data-nf-client-id", "your-client-id");
  scriptNF.setAttribute("data-nf-retry-count", "0");
  scriptNF.setAttribute("data-nf-network-timeout", "3000");
  
  // スクリプトソースの設定
  scriptNF.src = "https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js";
  
  // headの開始部分にスクリプトを挿入
  var head = document.head || document.getElementsByTagName('head')[0];
  head.insertBefore(scriptNF, head.firstChild);
})();

ステップ2: HTMLファイルに共通スクリプトを含める

<html>
  <head>
    <!-- NetFUNNEL初期化が最初である必要がある -->
    <script src="./netfunnel-init.js"></script>
    <!-- 他のスクリプト -->
    <script src="./app.js"></script>
    <script src="./analytics.js"></script>
  </head>
  <body>...</body>
</html>

検証: 使用された方法に関係なく、常に次を確認してください:

NetFUNNELスクリプトが最初にロードされる (ネットワークタブで確認)
netfunnel-javascript-agent.jsとnf-setting.jsonの両方がHTTP 200を返す
初期化中にJavaScriptエラーが発生しない

ステップ3: インストール確認

NetFUNNELエージェントを実装した後、次を確認して正しく動作していることを確認してください:

必須ファイルのローディング

次のファイルがHTTP 200でロードされることを確認:

netfunnel-javascript-agent.js - メインエージェントファイル
nf-setting.json - 構成ファイル

ブラウザDevToolsの確認

ステップ1: ブラウザDevToolsを開く

F12を押すか右クリック → "検証"
ネットワークタブに移動

ステップ2: ネットワークタブの構成

"ログ保持"または"ログ維持"を有効化 (ページナビゲーション後もログを維持)
"キャッシュ無効化"を有効化 (新しいリクエストを保証)
既存のネットワークログをクリア

ステップ3: ページの再ロード

ページをリフレッシュ (Ctrl+F5またはCmd+Shift+R)
ネットワークタブで次のファイルを確認:

ファイル	期待されるステータス	目的
`netfunnel-javascript-agent.js`	200 OK	メインNetFUNNELエージェントスクリプト
`nf-setting.json`	200 OK	エージェント構成設定

エラー処理

エラー処理は、セキュリティを維持し、ユーザーがトラフィック制御をバイパスすることを防ぐために重要です。NetFUNNELエージェントがロードに失敗した場合、ユーザーはバイパスを許可するのではなく、エラーページにリダイレクトされる必要があります。

エラー処理が重要な理由:

セキュリティ: ユーザーがNetFUNNELスクリプトをブロックしてトラフィック制御をバイパスすることを防ぐ
ユーザー体験: エージェントロード失敗時に明確なフィードバックを提供
コンプライアンス: トラフィック制御ポリシーが一貫して適用されることを保証

方法A: 直接HTML挿入 NetFUNNELスクリプトタグにonerror属性を直接追加します:

<script
    src="https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js"
    data-nf-client-id="your-client-id"
    onerror="(function () { window.location.href='/your-custom-error-page.html' })()"
></script>

方法B: 動的スクリプト注入 スクリプト作成にエラー処理を追加:

// netfunnel-init.js
(function() {
  if (window.NetFUNNEL || document.querySelector('script[data-nf-client-id]')) {
    return;
  }

  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";
  
  // エラー処理
  scriptNF.onerror = function() {
    console.error('NetFUNNELエージェントロード失敗');
    // 次のオプションのいずれかを選択:
    window.location.href = "/your-custom-error-page.html";  // カスタムエラーページ
    // window.location.href = "/";  // ホームページにリダイレクト
    // document.body.innerHTML = '<div>サービスを一時的に使用できません</div>';  // メッセージ表示
  };

  scriptNF.onload = function() {
    console.log('NetFUNNELエージェントが正常にロードされました');
  };
  
  document.head.insertBefore(scriptNF, document.head.firstChild);
})();

エラー処理オプション

すべての方法は次のエラー処理戦略をサポートします:

カスタムエラーページ: window.location.href='/your-custom-error-page.html'
メインページリダイレクト: window.location.href='/' (ホームページにリダイレクト)
サービス使用不可ページ: window.location.href='/service-unavailable.html'
カスタムメッセージ: document.body.innerHTML='<div>サービスを一時的に使用できません</div>'

アプリケーションのエラー処理戦略に最も適したオプションを選択してください。

トラブルシューティング

スクリプトがロードされない:

src URLが正しいことを確認
NetFUNNELサーバーへのネットワーク接続を確認
広告ブロッカーが干渉していないことを確認

バイパスモード (待合室なし):

data-nf-client-idがあることを確認
コンソールでセグメントが有効化されていることを確認
進入許容数が無制限に設定されていないことを確認

スクリプト配置の問題:

スクリプトを<head>の最上部に移動
deferまたはasync属性を削除
NetFUNNELより先に実行される他のスクリプトがないことを確認

ステップ1: 初期化コードの取得​

必須属性​

ステップ2: すべてのHTMLファイルに適用​

方法A: 直接HTML挿入 (推奨)​

方法B: 動的スクリプト注入 (代替)​

ステップ3: インストール確認​

必須ファイルのローディング​

ブラウザDevToolsの確認​

エラー処理​

エラー処理オプション​

トラブルシューティング​