Application Real-Time Monitoring Service:Web および HTML5 向け RUM SDK 構成リファレンス

CDN による初期化

Alibaba Cloud コンテンツデリバリーネットワーク (CDN) を通じて SDK をロードする場合、グローバル名前空間 RumSDK.default からアクセスします。

const ArmsRum = window.RumSDK.default;

// SDK がロードされた後に初期化します。
// SDK スクリプトタグの前に window.__rum を定義した場合は、このステップをスキップします。
ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
});

// ランタイムで構成を更新
ArmsRum.setConfig('env', 'pre');

npm による初期化

import ArmsRum from '@arms/rum-browser';

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
});

例

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  user: {
    name: 'your user.name',
    tags: 'your user.tags',
  },
});

例

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  reportConfig: {
    flushTime: 0,       // 即時報告
    maxEventCount: 50,  // バッチあたり最大 50 イベント
  },
});

ストレージの詳細

storage パラメーターは、SDK が以下のデータを永続化する場所を決定します。

• _arms_uid -- ユニークユーザー ID (user.id)

• _arms_session -- セッションメタデータ。フォーマット：${sessionId}-${sampled}-${startTime}-${lastTime}

  • sessionId -- ユニークセッション識別子

  • sampled -- このセッションがサンプリングによって選択されたかどうか

  • startTime -- セッション開始タイムスタンプ

  • lastTime -- 最終アクティビティタイムスタンプ

例

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  sessionConfig: {
    sampleRate: 0.5,          // セッションの 50% をサンプリング
    maxDuration: 86400000,    // 最大 24 時間
    overtime: 3600000,        // 1 時間の非アクティブタイムアウト
    storage: 'cookie',        // localStorage の代わりに cookie を使用
  },
});

収集範囲と代替案

追跡する必要のある要素がデフォルトの収集範囲外にある場合は、次のいずれかのアプローチを使用します。

• DOM 構造の調整 (推奨)：監視したい要素を button または a タグでラップします。SDK は祖先マッチングを通じて自動的に収集します。

• trackUserInteractions の使用：trackUserInteractions: true を設定すると、SDK は非インタラクティブなタグを含むすべての要素のクリックイベントを収集します。このアプローチはヒートマップ分析に適しています。

• sendCustom API の使用：ArmsRum.sendCustom() を呼び出して、デフォルトの収集範囲外のクリックイベントを手動で報告します。パラメーターの詳細については、sendCustom をご参照ください。

例

ユーザーインタラクションの追跡を無効にする：

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  collectors: {
    action: false,
  },
});

入力引数

戻り値の型 (IApiBaseAttr)

返されたフィールドは SDK のデフォルトをオーバーライドします。省略されたフィールドはデフォルト値のままです。

例

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  evaluateApi: async (options, response, error) => {
    let respText = '';
    if (response && response.text) {
      respText = await response.text();
    }

    return {
      name: 'my-custom-api',
      success: error ? 0 : 1,
      snapshots: JSON.stringify({
        params: 'page=1&size=10',
        response: respText.substring(0, 2000),
        reqHeaders: '',
        resHeaders: '',
      }),
      properties: {
        prop_msg: 'custom msg',
        prop_num: 1,
      },
    };
  },
});

MatchOption 型

type MatchOption = string | RegExp | ((value: string) => boolean);

• String -- 指定された値で始まる URL またはメッセージに一致します。例：'https://api.aliyun.com' は 'https://api.aliyun.com/v1/resource' に一致します。

• RegExp -- URL またはメッセージを正規表現と照合します。

• Function -- URL またはメッセージを入力として受け取ります。イベントを除外するには true を返します。

MatchOption 値の配列を渡すと、条件は順番に評価されます。いずれかの条件が一致した場合、イベントは除外されます。

例

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  filters: {
    exception: [
      'Test error',                           // 'Test error' で始まるメッセージ
      /^Script error\.?$/,                    // この正規表現に一致するメッセージ
      (msg) => msg.includes('example-error'), // カスタムマッチ関数
    ],
    resource: [
      'https://example.com/',   // 'https://example.com/' で始まる URL
      /localhost/i,             // 'localhost' を含む URL
      (url) => url.includes('example-resource'),
    ],
  },
});

DetectionRule

トリガーイベント

検出メソッド

CustomTesterResult 型：

type CustomTesterResult = {
  hasContent: boolean;               // true = コンテンツが存在する; false = ホワイトスクリーンが検出された
  message?: string;                  // エラーメッセージ
  snapshot?: Record<string, any>;    // 診断データ
}

ConfigOptions

SCREENSHOT および SAMPLE 検出メソッドに固有のオプション。

SCREENSHOT オプション：

SAMPLE オプション：

共有オプション：

SCREENSHOT と SAMPLE の両方が debug オプション (Boolean、デフォルト：false) をサポートします。有効にすると、検出の詳細がブラウザーの開発者ツールコンソールに出力されます。

例

スクリーンショットベースの検出：

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  whiteScreen: {
    detectionRules: [{
      target: '#root',
      test_when: ['LOAD', 'ERROR', 'ROUTE_CHANGE', 'LEAVE'],
      delay: 5000,
      tester: 'SCREENSHOT',
      configOptions: {
        colorRange: ['rgb(255, 255, 255)', 'rgb(0, 0, 0)'],
        threshold: 0.9,
        pixels: 10,
        horizontalOffset: 210,
        verticalOffset: 50,
      },
    }],
  },
});

サンプリングベースの検出：

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  whiteScreen: {
    detectionRules: [{
      target: '#root',
      test_when: ['LOAD', 'ERROR', 'ROUTE_CHANGE', 'LEAVE'],
      delay: 5000,
      tester: 'SAMPLE',
      configOptions: {
        sampleMethod: 2,
        checkPoints: 10,
        threshold: 0.9,
        whiteBoxElements: ['.el-skeleton'],
      },
    }],
  },
});

カスタム検出関数：

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  whiteScreen: {
    detectionRules: [{
      target: '#root',
      test_when: ['LOAD', 'ERROR', 'ROUTE_CHANGE', 'LEAVE'],
      delay: 5000,
      tester: async (element) => {
        return {
          hasContent: false,
          message: 'Custom error message',
          snapshot: {
            checkPoints: 100,
            rate: 0.99,
            checkdata: '......',
          },
        };
      },
    }],
  },
});

マージ動作

• グローバルプロパティ (init() で設定) とイベントレベルのプロパティ (evaluateApi、sendCustom、sendException、または sendResource を通じて設定) は、ストレージ時にマージされます。

• イベントレベルのプロパティが優先されます。同じキーが両方に存在する場合、イベントレベルの値が優先されます。

• マージ後、最大 20 個のキーと値のペアが保持されます。超過したペアはキーでソートされ、削除されます。

例

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  properties: {
    prop_string: 'xx',
    prop_number: 2,
    // 50 文字を超えるキーは切り捨てられます
    more_than_50_key_limit_012345678901234567890123456789: 'yy',
    // 2,000 文字を超える文字列値は切り捨てられます
    more_than_2000_value_limit: new Array(2003).join('1'),
    // 無効な型 -- これらのペアは削除されます
    prop_null: null,
    prop_undefined: undefined,
    prop_bool: true,
  },
});

ステップ 1：ARMS コンソールでの構成

1. アプリケーションリスト に移動し、ご利用のアプリケーションを開きます。

2. アプリケーション設定 > SDK 設定 に移動します。

3. 目的の構成値を設定します。

4. 動的構成の更新を確認 をクリックして、設定をリモートの Object Storage Service (OSS) サーバーにプッシュします。

ステップ 2：SDK での有効化

アプリケーションがホストされている region を含む remoteConfig フィールドを初期化コードに追加します。

CDN：

window.__rum = {
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  remoteConfig: {
    region: "cn-hangzhou"  // 例：シンガポールは "ap-southeast-1"
  }
};

<script async src="https://xxid-sdk.rum.aliyuncs.com/v2/browser-sdk.js"></script>

npm：

import ArmsRum from '@arms/rum-browser';

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  remoteConfig: {
    region: "cn-hangzhou"  // 例：シンガポールは "ap-southeast-1"
  }
});

キャッシュ動作

リモート構成を取得した後、SDK は設定をローカルにキャッシュします。その後の初期化では、SDK はキャッシュされた構成を優先します。

動的構成には、固定バージョンで CDN を介してインポートする場合、SDK バージョン 0.0.37

例

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  geo: {
    country: 'your custom country info',
    city: 'your custom city info',
  },
});

getConfig

現在の SDK 構成を取得します。

const config = ArmsRum.getConfig();

setConfig

ランタイムで SDK 構成を更新します。単一のキーと値のペア、または完全な構成オブジェクトを渡します。

// 単一の値を設定
ArmsRum.setConfig('env', 'pre');

// 複数の値を設定
const config = ArmsRum.getConfig();
ArmsRum.setConfig({
  ...config,
  version: '1.0.0',
  env: 'pre',
});

sendCustom

カスタムイベントを報告します。type および name フィールドは必須です。

ArmsRum.sendCustom({
  type: 'CustomEventType1',
  name: 'customEventName2',
  group: 'customEventGroup3',
  value: 111.11,
  properties: {
    prop_msg: 'custom msg',
    prop_num: 1,
  },
});

sendException

カスタム例外を報告します。name および message フィールドは必須です。

ArmsRum.sendException({
  name: 'customErrorName',
  message: 'custom error message',
  file: 'custom exception filename',
  stack: 'custom exception error.stack',
  line: 1,
  column: 2,
  properties: {
    prop_msg: 'custom msg',
    prop_num: 1,
  },
});

sendResource

カスタムリソースイベントを報告します。name、type、および duration フィールドは必須です。

ArmsRum.sendResource({
  name: 'getListByPage',
  message: 'success',
  duration: 800,
  url: 'https://www.aliyun.com/data/getListByPage',
  properties: {
    prop_msg: 'custom msg',
    prop_num: 1,
  },
});