Boomerang 使用方法 #6: boomerang を設定する

boomerang を使用するためには最初に boomerang.js を HTML の中に読み込み、BOOMR.init() メソッドを呼び出します。ページのパフォーマンスを測定するにはこれで十分のはずですが、サイトの管理者として十分役立つとは限りません。これだけではまだサーバーに送ったデータを取得することはできませんし、ユーザーの帯域幅も測定できません。

このドキュメントでは、あなたが使用できる boomerang の設定とビルトインのプラグインのパラメーターの違いについて説明します。もし追加のプラグインを使っている場合はその設定についてはプラグインのドキュメントを参考にしてください。

boomerang の設定

boomerang とそのプラグインを設定するには、init() メソッドに設定オブジェクトを渡します。

BOOMR.init({
		key: value,
		...
	});

boomerang には以下のパラメーターがあります:

beacon_url

[強く推奨] ビーコンの結果を送る URL 。全てのパラメーターはこの URL の QueryString に追加されます。この URL は QueryString 部分を事前に持っておく必要はありません。このパラメーターには初期値はありません。もし設定されていなければビーコンは送信されません。

site_domain

[推奨] 全ての Cookie がセットされるドメイン。boomerang はこれを自動判別しようとしますが、あなたのサイトが foo.com の形式の場合を除き、実際には取得に失敗します。これはドメイン間で共有する帯域幅やパフォーマンスを測定したいときに役立ちます。
もし複数のドメインを持っている場合はうまくいきません。別々に測定しなければなりません。

user_ip

[推奨] この名前にもかかわらず、これはユーザーのコネクションをユニークに区別するために使われる自由な文字列です。これは主にユーザーの帯域幅を再測定するかどうかの判断に使われるか、または Cookie に格納される値に使われます。IPv4 アドレスや IPv6 アドレスまたはそれ以外のユーザーのコネクションを区別できるものを使うことになります。

log

[オプション] 初期値では boomerang は YUI のロガーコンポーネントが見つかればそれを、Firebug が見つかれば代わりにそれを使おうと試みます。どちらもない場合は、初期状態では何もログに残しません。ログメッセージ用の関数のために log パラメーターを設定することで自身のロガーを定義することができます。
この関数については:

function log(oMessage, sLevel, sSource);

どこに:

oMessage: 記録されるオブジェクトまたはメッセージ。記録するオブジェクトを決定するだけです。
sLevel: "error"、"warn"、"info"、"debug" などのログレベル。
sSource: ログメッセージのソース。通常はプラグインの名前がついた "boomerang" の文字列になります。

log に null を設定することでログの記録を無効にできます。

autorun

[オプション] 初期値では boomerang は自動的に実行され window.onload イベントに page_ready ハンドラーが登録されます。もし autorun を false にすると、これは起こらず、BOOMR.page_ready() を自分で呼び出す必要があります。

<plugin_name>

それぞれのプラグインは設定オブジェクトのサブオブジェクトを通して設定を行ないます。キーはプラグインの名前になります。ビルトインのプラグインの設定方法については次の各セクションをご覧ください。

BOOMR.init({
		beacon_url: "http://beacons.yoursite.com/path/to/beacon.php",
		site_domain: "yoursite.com",
		user_ip: "202.54.1.18",
		autorun: false
	});

Roundtrip プラグイン

roundtrip プラグインの全ての設定は RT の名前空間の下に入ります。

cookie: [オプション] ページの読み込み時間を測定するための開始時間を格納する Cookie の名前。初期値は RT になります。
cookie_exp: [オプション] 秒で表した Cookie の有効期間。これは1つのページの読み込みに負荷がかかるためできるだけ長くする必要があります。10秒以上にすればほとんどの場合は問題ありませんが、念のため遅いコネクションのユーザーをカバーするためや、地理的に遠いユーザーのために、数分は維持します。初期値は10分です。
strict_referrer: [オプション] 初期値では boomerang は現在のページの document.referrer に RT Cookie が一致しなければページの往復時間は測定しません。これは RT Cookie がまだ有効な状態で3番目のページを訪れたからということを意味し、ページの読み込み時間は無効となる可能性があります。
このようなこともあるかもしれませんが、こういった場合は有効です — 例えば、SSL のページ間でリファラーが渡されません。この場合は、strict_referrer を false にすればいいでしょう。

BOOMR.init({
		beacon_url: "http://beacons.yoursite.com/path/to/beacon.php",
		site_domain: "yoursite.com",
		user_ip: "202.54.1.18",
		autorun: false,
		RT: {                     
		        cookie: "MyRT",   
		        cookie_exp: 120   
		}                         
	});

Bandwidth プラグイン

bandwidth プラグインの全ての設定は BW の名前空間の下に入ります。

base_url: [推奨] 初期値では、bandwidth プラグインは帯域幅測定用の画像を現在のページのディレクトリーの images/ サブディレクトリーから見つけます。これはあなたのサイト上の全てのページで正しいとは限りません。画像があるディレクトリーのパスを base_url パラメーターで設定ができます。絶対 URL または相対 URL で指定ができます。相対パスの場合、JavaScript ファイルからではなく boomerang が読み込まれたページからの相対パスになることを覚えておいてください。
cookie: [オプション] ユーザーのコネクションの帯域幅と遅延の測定結果を格納する Cookie の名前。初期値は BA です。詳細は使用方法 #3 をご覧ください。Cookie を無視して開始時間を完全に WebTiming API に依存させるには、ここに null のような偽の値か空文字を指定します。
cookie_exp: [オプション] 秒で表した Cookie の有効期限。初期値は7日間です。これはユーザーの帯域幅テストを再度行うまでにどれくらい空けるかを記述します。IP アドレスをもとにその間は変更されません。ネットワークコネクションの帯域幅は通常は定期的に大きくは変わらないため、実際はこの設定を何も変更する必要はありません。
もしあなたがレアルタイムストリーミングのようなことを行っている場合、帯域幅のテストは適切ではなく、Cookie に短い値を設定するのは正しい方法ではありません。
timeout: [オプション] ミリ秒で表した帯域幅のテスト全体のタイムアウト値。初期値は15秒です。帯域幅のテストは長時間実行できるため、時々ネットワークエラーが発生し終了しないかもしれません。タイムアウトは強制的にテストを終了させます。これはハードリミットです。もしタイムアウトになると、テストの続行を停止してこの時点で取得できているデータから帯域幅を計算しようとします。タイムアウトを長くすればさらに多くのデータを取得し精度を向上できますが、長くした分、ユーザーがページを離れる前にテストが終了しないリスクも増えます。
nruns: [オプション] 帯域幅のテストを実行する回数。初期値は5回です。初回のテストは常に残りのテストを続行するためにベストな計算をするための試験的なものです。この回数が増えるとテストの精度も向上していきますが、増やした分、テストがタイムアウトするリスクも増えます。これは実行毎に約2秒から4秒かかるため、この値は timeout の値よりも超えるように考慮しなければなりません。

全てのオプション

全ての設定パラメーターはオプションですが、それらのうちいくつかを設定しないと予期しないまたは不完全な結果が起こる可能性があるため、設定すべきです。しかしながら、正しいディレクトリーに帯域幅テストの画像を置けば、コードを読み込んで init() を呼び出せば実行はできます。

最新のソースコードとドキュメントは github.com/SOASTA/boomerang に公開されています。