メインコンテンツまでスキップ
メインコンテンツまでスキップ

ブラウザ JS

The ClickStackブラウザSDKは、フロントエンドアプリケーションを計測して、ClickStackにイベントを送信することを可能にします。これにより、ネットワークリクエストや例外をバックエンドイベントと同じタイムラインで表示できます。

さらに、セッションリプレイデータを自動的にキャプチャし、相関付けるため、ユーザーがアプリケーションを使用している際に見ていた内容を視覚的にステップスルーしてデバッグできます。

このガイドには以下の内容が含まれています：

  • コンソールログ
  • セッションリプレイ
  • XHR/Fetch/Websocketリクエスト
  • 例外

はじめに​


パッケージインポートでインストール（推奨）

以下のコマンドを使用して、ブラウザパッケージをインストールします。

npm install @hyperdx/browser

ClickStackを初期化する

import HyperDX from '@hyperdx/browser';

HyperDX.init({
    url: 'http://localhost:4318',
    apiKey: 'YOUR_INGESTION_API_KEY',
    service: 'my-frontend-app',
    tracePropagationTargets: [/api.myapp.domain/i], // Set to link traces from frontend to backend requests
    consoleCapture: true, // Capture console logs (default false)
    advancedNetworkCapture: true, // Capture full HTTP request/response headers and bodies (default false)
});

オプション​

  • apiKey - あなたのClickStackインジェクションAPIキー。
  • service - HyperDX UIに表示されるイベントのサービス名。
  • tracePropagationTargets - フロントエンドとバックエンドのトレースをリンクするためのHTTPリクエストに対して照合する正規表現パターンのリスト。対応するパターンに一致するすべてのリクエストに追加のtraceparentヘッダーが追加されます。これはバックエンドAPIドメイン（例：api.yoursite.com）に設定する必要があります。
  • consoleCapture - （オプション）すべてのコンソールログをキャプチャする（デフォルトはfalse）。
  • advancedNetworkCapture - （オプション）フルリクエスト/レスポンスのヘッダーおよびボディをキャプチャする（デフォルトはfalse）。
  • url - （オプション）OpenTelemetryコレクタのURL、セルフホストインスタンスの場合のみ必要です。
  • maskAllInputs - （オプション）セッションリプレイで全ての入力フィールドをマスクするかどうか（デフォルトはfalse）。
  • maskAllText - （オプション）セッションリプレイで全てのテキストをマスクするかどうか（デフォルトはfalse）。
  • disableIntercom - （オプション）Intercom統合を無効にするかどうか（デフォルトはfalse）。
  • disableReplay - （オプション）セッションリプレイを無効にするかどうか（デフォルトはfalse）。

追加の設定​

ユーザー情報またはメタデータを添付する​

ユーザー情報を添付することで、HyperDX UIでセッションやイベントを検索/フィルタリングできます。これはクライアントセッションの任意の時点で呼び出すことができます。現在のクライアントセッションと呼び出し後に送信されたすべてのイベントは、ユーザー情報に関連付けられます。

userEmail、userName、およびteamNameは、対応する値でセッションUIをポピュレートしますが、省略することも可能です。他の追加の値も指定可能で、イベントを検索するために使用できます。

HyperDX.setGlobalAttributes({
  userId: user.id,
  userEmail: user.email,
  userName: user.name,
  teamName: user.team.name,
  // Other custom properties...
});

Reactエラー境界エラーの自動キャプチャ​

Reactを使用している場合、attachToReactErrorBoundary関数にエラー境界コンポーネントを渡すことで、Reactエラー境界内で発生するエラーを自動的にキャプチャできます。

// Import your ErrorBoundary (we're using react-error-boundary as an example)
import { ErrorBoundary } from 'react-error-boundary';

// This will hook into the ErrorBoundary component and capture any errors that occur
// within any instance of it.
HyperDX.attachToReactErrorBoundary(ErrorBoundary);

カスタムアクションを送信する​

特定のアプリケーションイベント（例：サインアップ、送信など）を明示的に追跡するために、addAction関数をイベント名とオプションのイベントメタデータで呼び出すことができます。

例：

HyperDX.addAction('Form-Completed', {
  formId: 'signup-form',
  formName: 'Signup Form',
  formType: 'signup',
});

ネットワークキャプチャを動的に有効にする​

ネットワークキャプチャを動的に有効または無効にするには、必要に応じてenableAdvancedNetworkCaptureまたはdisableAdvancedNetworkCapture関数を呼び出すだけです。

HyperDX.enableAdvancedNetworkCapture();

CORSリクエストのためのリソースタイミングを有効にする​

フロントエンドアプリケーションが異なるドメインにAPIリクエストを送信する場合、オプションでリクエストにTiming-Allow-Originヘッダーを送信するように設定できます。これにより、ClickStackはリクエストの細かいリソースタイミング情報（例えば、DNSルックアップ、レスポンスダウンロードなど）をPerformanceResourceTimingを通じてキャプチャできます。

expressとcorsパッケージを使用している場合、以下のスニペットを使用してヘッダーを有効にできます：

var cors = require('cors');
var onHeaders = require('on-headers');

// ... all your stuff

app.use(function (req, res, next) {
  onHeaders(res, function () {
    var allowOrigin = res.getHeader('Access-Control-Allow-Origin');
    if (allowOrigin) {
      res.setHeader('Timing-Allow-Origin', allowOrigin);
    }
  });
  next();
});
app.use(cors());