Rumable SDK のソースと設定¶
このページでは、Rumable が SDK を注入・ロード・初期化する方法について説明します。手動設定が不要な方法はワンクリック接続を参照してください。手動設定の場合は4 種類の接続方式の完全な例に進んでください。初回インストールはインストールと接続を、バージョン更新とロールバックは運用の説明を参照してください。
注入方法とタイミング¶
Rumable は、Web サーバーが返す標準の <head> の後に外部スクリプトを追加します。業務ソースファイルは変更しません。ソースとロード方法は互いに独立しています。
| ソースと方法 | ダウンロード場所 | 実行順序 |
|---|---|---|
| 同一ドメイン + 非同期（デフォルト） | インストールパッケージに同梱された SDK をウェブサイトの同一ドメインでホスト | 初期化スクリプトを非同期でロードし、次に SDK を動的に非同期ダウンロードし、完了後に初期化 |
| 同一ドメイン + 同期 | インストールパッケージに同梱された SDK をウェブサイトの同一ドメインでホスト | 最初に SDK を実行し、次に初期化スクリプトを実行し、その後ページの解析を継続 |
| CDN + 非同期 | SDK は公式または自社 CDN から取得し、初期化スクリプトは同一ドメイン | 初期化スクリプトが CDN SDK を非同期ダウンロードし、完了後に初期化 |
| CDN + 同期 | SDK は公式または自社 CDN から取得し、初期化スクリプトは同一ドメイン | 最初に CDN SDK を実行し、次に初期化スクリプトを実行し、その後ページの解析を継続 |
同一ドメインのリソースはウェブサイトの __rumable__/<サイトID>/ 配下にあり、ファイル名にはコンテンツダイジェストが含まれます。同一ドメインを選択しても SDK のダウンロード場所が変わるだけで、データは設定された転送先に送信されます。
非同期スクリプトのダウンロードは HTML の解析をブロックしませんが、初期化前のエラー、リクエスト、インタラクションは収集できない場合があります。同期方式では、async や defer のない 2 つの通常の外部スクリプトを使用するため、後続の業務スクリプトの前に初期化を完了できます。ネットワークが遅い場合や CDN 障害時には、後続のページ解析とファーストビューが遅延します。
同期では、SDK のロード失敗や初期化前のすべてのイベントを確実にキャプチャできるわけではありません。SDK のロードに失敗しても、自動的に同一ドメインのコピーに切り替わることはありません。同期モードでも、ブラウザがリクエストの完了または失敗を判定するまで待つ必要があります。どちらの方法でも CSP は自動的に緩和されません。
source と loading の意味¶
source は SDK のダウンロード元を示し、loading は SDK のロード方法を示します。この 2 つは独立して選択できます。
| 設定項目 | 入力値 | 説明 |
|---|---|---|
source |
"bundled" |
インストールパッケージに同梱された SDK を使用し、ウェブサイトの同一ドメインで提供 |
source |
"cdn" |
url で指定した CDN アドレスから SDK をダウンロード |
loading |
"async" |
非同期：ページの解析を継続し、SDK のロード完了後に収集を開始 |
loading |
"sync" |
同期：先に SDK をロードして初期化し、その後ページの解析を継続 |
url |
完全な HTTPS スクリプトアドレス | CDN を使用する場合のみ入力 |
integrity |
false / true |
ブラウザの SRI 完全性チェックを有効にするかどうか。デフォルトは false。CDN で有効にする前に、以下の CORS とダイジェスト要件を満たす必要があります |
loading を指定しない場合は非同期が使用されます。明示的に loading = "async" と入力することもできます。以下の例では、直接比較できるようにロード方法を明記しています。[sites.sdk] は TOML 内でこれらのオプションを配置する設定セクション名であり、追加で入力する必要のあるパラメータではありません。
設定ページで選択してワンクリック接続¶
最初にワンクリック接続フローを使用することをお勧めします。ページでアプリケーションパラメータを入力し、SDK 方式を選択してから、生成されたコマンドをコピーしてサーバーで実行します。以下の TOML を手動で記述する必要はありません。設定ページの「SDK ソースとロード方法の選択」には 2 つのドロップダウンボックスがあります。
| 実現したい効果 | 「SDK ソース」の選択 | 「ロード方法」の選択 | CDN アドレス |
|---|---|---|---|
| ウェブサイト同一ドメイン + 非同期 | ウェブサイト同一ドメイン（デフォルト） | 非同期（デフォルト） | 入力不要 |
| ウェブサイト同一ドメイン + 同期 | ウェブサイト同一ドメイン（デフォルト） | 同期 | 入力不要 |
| CDN + 非同期 | CDN | 非同期（デフォルト） | SDK の HTTPS アドレスを入力 |
| CDN + 同期 | CDN | 同期 | SDK の HTTPS アドレスを入力 |
例えば、公式 CDN で同期ロードする場合は、「CDN」と「同期」を選択し、CDN アドレスに https://static.guance.com/browser-sdk/v3/dataflux-rum.js を入力します。右側のダイジェストを確認したら、リリースバージョンを読み取り、TOML をダウンロードし、ページで生成されたコマンドに従って実行します。
ワンクリック接続は上記の 4 つの組み合わせをサポートしており、ウェブサイトの自動検出時に CDN と同期ロードを選択することもできます。
すでに CLI がインストールされているサイト¶
初回接続では、latest 設定ページで生成されたコマンドを直接使用します。既存サイトで SDK のソースやロード方法を変更する場合は、元の設定、サイト ID、状態ディレクトリを保持し、設定の更新とアップグレードに従って再適用してください。TOML のダウンロードや設定ページの更新をしても、サーバー上の CLI と SDK は自動的に更新されません。
4 種類の接続方式の完全な例¶
以下の 4 つのコードブロックはすべて Linux / Nginx の完全な設定ファイルです。毎回 1 つだけ選択し、/etc/rumable/website.toml として保存してください。4 つの例を同じファイルに結合しないでください。既存サイトの場合は、元の TOML をバックアップし、元の [sites.sdk] セクションのみを変更し、元のサイト ID、パス、サンプリングなどの設定を保持してください。
初回接続時は、以下の値を置き換えてください。
| サンプル値 | 置き換える内容 |
|---|---|
website |
今回接続するサイト ID。以降の更新でも変更しない |
https://www.example.com/ |
ウェブサイトのアドレス。パスは / で終わる |
/usr/sbin/nginx |
実際の Nginx 実行ファイルのパス |
YOUR_APPLICATION_ID |
Web アプリケーションのアプリケーション ID |
https://openway.example.com |
コンソールが提供する OpenWay アドレス。プロトコル、ホスト、任意のポートのみを入力 |
YOUR_CLIENT_TOKEN |
対応するブラウザアクセストークン |
service、env、version は業務に応じて入力します。ここでの version は業務アプリケーションのバージョンであり、SDK のバージョンではありません。この例では、すべてのセッションサンプリングを有効にし、リプレイをオフにしています。検収が完了したら調整してください。
例 1：ウェブサイト同一ドメイン + 非同期¶
デフォルトの方法です。SDK はウェブサイトの同一ドメインで提供され、ページはそのロード完了を待ちません。
schemaVersion = 1
[[sites]]
id = "website"
publicURL = "https://www.example.com/"
includePaths = ["/"]
excludePaths = ["/downloads/"]
probePaths = ["/"]
[sites.nginx]
binary = "/usr/sbin/nginx"
attachmentReviewed = false
[sites.rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
service = "website"
env = "production"
version = "1.0.0"
sessionSampleRate = 100
sessionReplayEnabled = false
defaultPrivacyLevel = "mask"
[sites.sdk]
source = "bundled" # ウェブサイト同一ドメイン
loading = "async" # 非同期ロード。SDK のダウンロード完了を待たない
例 2：ウェブサイト同一ドメイン + 同期¶
SDK はウェブサイトの同一ドメインで提供され、先に初期化してからページの解析を続行します。
schemaVersion = 1
[[sites]]
id = "website"
publicURL = "https://www.example.com/"
includePaths = ["/"]
excludePaths = ["/downloads/"]
probePaths = ["/"]
[sites.nginx]
binary = "/usr/sbin/nginx"
attachmentReviewed = false
[sites.rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
service = "website"
env = "production"
version = "1.0.0"
sessionSampleRate = 100
sessionReplayEnabled = false
defaultPrivacyLevel = "mask"
[sites.sdk]
source = "bundled" # ウェブサイト同一ドメイン
loading = "sync" # SDK のロードと初期化を待ってからページの解析を続行
例 3：CDN + 非同期¶
ブラウザは指定した CDN の SDK を非同期でダウンロードし、初期化スクリプトは引き続きウェブサイトの同一ドメインで提供されます。
schemaVersion = 1
[[sites]]
id = "website"
publicURL = "https://www.example.com/"
includePaths = ["/"]
excludePaths = ["/downloads/"]
probePaths = ["/"]
[sites.nginx]
binary = "/usr/sbin/nginx"
attachmentReviewed = false
[sites.rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
service = "website"
env = "production"
version = "1.0.0"
sessionSampleRate = 100
sessionReplayEnabled = false
defaultPrivacyLevel = "mask"
[sites.sdk]
source = "cdn" # CDN からダウンロード
url = "https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
integrity = false
loading = "async" # 非同期ロード。SDK のダウンロード完了を待たない
例 4：CDN + 同期¶
先に CDN SDK をロードして初期化を完了し、その後ページの解析を続行します。
schemaVersion = 1
[[sites]]
id = "website"
publicURL = "https://www.example.com/"
includePaths = ["/"]
excludePaths = ["/downloads/"]
probePaths = ["/"]
[sites.nginx]
binary = "/usr/sbin/nginx"
attachmentReviewed = false
[sites.rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
service = "website"
env = "production"
version = "1.0.0"
sessionSampleRate = 100
sessionReplayEnabled = false
defaultPrivacyLevel = "mask"
[sites.sdk]
source = "cdn" # CDN からダウンロード
url = "https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
integrity = false
loading = "sync" # SDK のロードと初期化を待ってからページの解析を続行
IIS と DataKit でのこれらの例の使用方法¶
IIS でも同じ [sites.sdk] 設定を使用します。選択した例の [sites.nginx] セクション全体を以下のセクションに置き換え、その他のフィールドは保持します。
site は実際の IIS サイト名に変更します。allowCompressionChanges=true は、このアプリケーションの IIS 静的・動的圧縮を無効にすることを許可することを意味します。無効にした場合は元の設定を復元します。サブアプリケーション /shop は publicURL=https://www.example.com/shop/ に対応し、注入と検収パスにも /shop/ プレフィックスを使用する必要があります。
DataKit を使用してデータを転送する場合は、[sites.rum] から site と clientToken を削除し、datakitOrigin = "https://datakit.example.com" に変更して、実際のアドレスに置き換えてください。2 つの転送方法は排他的であり、/v1/write/rum を追加しないでください。
保存後に適用する方法¶
Nginx への初回接続時は、一致するバージョンの実際の CLI パスで以下を実行します。
ここでの rumable はインストール済みの CLI を表します。PATH に追加されていない場合は、その絶対パスに置き換えてください。変更対象の Nginx フックを確認してから適用し、ブラウザでの実行と実際のデータの取り込みを確認してください。すでに接続されているサイトは元の状態ディレクトリを保持し、設定を変更した後に enable を再実行します。
Windows での初回接続と両プラットフォームでの検収はインストールの説明を、すでに接続されているサイトの設定変更は運用の説明を参照してください。
CDN アドレス、ダイジェストと SRI¶
- URL は完全な HTTPS スクリプトアドレスである必要があり、アカウントパスワード、クエリパラメータ、フラグメントは含めません。
- 自社 CDN は、選択したインストールパッケージと完全に同じ SDK バイトを提供する必要があります。有効化とプローブでは、コンテンツダイジェスト、JavaScript MIME、通常および gzip レスポンスをチェックします。
- ブラウザの CSP で実際の CDN アドレスを許可する必要があります。CDN を選択しても初期化スクリプトがウェブサイトの同一ドメインから移動することはありません。
- クロスオリジン SRI では、CDN がサイトの Origin または
*を許可するAccess-Control-Allow-Originを返す必要があります。現在の公式 v3 アドレスはデフォルトで SRI を有効にしていません。有効にする前に、実際のレスポンスヘッダーとインストールチェックを確認してください。 - 公式 v3 は可変アドレスであり、プローブ時にダイジェストが一致しても将来のコンテンツは固定されません。バージョンを固定する必要がある場合は、同一ドメインモードを使用するか、不変の自社 CDN ファイルを維持してください。
- bundled を使用する場合は、
urlを入力したりintegrityを有効にしないでください。検証で拒否されます。
自動検出設定¶
自動検出は、ツールがサーバー上の既存のウェブサイトをスキャンし、接続対象を選択できるようにする機能です。ウェブサイトアドレスや Nginx/IIS ターゲットを手動で入力する手間が省けます。server、[rum]、[sdk] を使用し、[[sites]] を含む完全な設定とは異なる形式です。
以下はすべて完全な自動検出設定です。毎回 1 つだけ選択し、/etc/rumable/discovery.toml として保存してください。アプリケーション ID、OpenWay アドレス、トークンを置き換えてください。これらは setup --discover にのみ渡すことができ、enable に直接渡すことはできません。
同一ドメイン非同期。デフォルトの動作を使用し、SDK 設定セクションは記述しません。
schemaVersion = 1
server = "nginx"
[rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
sessionReplayEnabled = false
CDN 同期。SDK アドレスとロード方法を指定します。
schemaVersion = 1
server = "nginx"
[rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
sessionReplayEnabled = false
[sdk]
source = "cdn"
url = "https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
loading = "sync"
integrity = false
Windows では server を "iis" に変更し、実際の権限に応じて [rum] の前にトップレベルの allowCompressionChanges = true を設定します。SDK パラメータの意味は完全な設定と同じですが、設定セクション名は [sdk] であり、[sites.sdk] と記述することはできません。
Nginx では実際にインストールされている CLI で実行します。ターミナルでサイトを選択すると、接続識別子が表示されます。
Windows では管理者ターミナルで実際の exe、設定ファイル、状態ディレクトリを使用して setup --discover を実行します。その後も元のサイト ID、ターゲット、状態ディレクトリを引き続き使用します。別の任意の ID で同じデプロイメントを引き継がないでください。
パス、サンプリングとリプレイ¶
includePaths と excludePaths は大文字小文字を区別するプレフィックスで一致し、除外が優先されます。probePaths は注入範囲内にあり、検収可能な HTML を直接返す必要があります。パスはサーバーがそのページを書き換えるかどうかを決定しますが、SDK の Fetch/XHR リクエストを除外することとは異なり、SPA でルートが切り替わっても注入が再判定されることはありません。
リプレイはデフォルトでオフです。完全な設定の既存の [sites.rum] で以下のフィールドを調整してください。このテーブルを重複して追加しないでください。
sessionSampleRate = 100
sessionReplayEnabled = true
sessionReplaySampleRate = 20
sessionReplayOnErrorSampleRate = 0
defaultPrivacyLevel = "mask"
リプレイは RUM セッションサンプリングに依存します。サンプリングレートを変更した後は、新しいセッションで検収してください。リプレイ、リクエスト圧縮、リモート設定には Worker が必要な場合があります。デフォルトの Blob Worker では CSP が blob: を許可する必要があり、外部 Worker はユーザーの同一ドメインでホストされ、バージョンが一致している必要があります。
詳細なサンプリングの意味についてはサンプリング設定を参照してください。setUser、手動の startView、カスタムイベント、関数コールバックは引き続き業務コードが必要です。Rumable の静的設定ではこれらの呼び出しを自動的に代替できません。「アプリケーションバージョン」は業務ラベルであり、「SDK リモート設定」は収集パラメータを調整します。どちらも SDK ファイルをアップグレードしません。
設定ページまたは CLI が選択した方式をサポートしていないと表示される場合¶
latest 設定ページを開き、リリースバージョンを再読み込みしてインストールコマンドを生成してください。インストール済みの CLI が loading や [sdk] を認識しないと表示する場合は、アップグレード手順に従って CLI を更新し、元のサイト設定を適用してください。アップグレード時は元のサイト ID、ターゲット、状態ディレクトリを保持します。