boomerang は全て BOOMR オブジェクトを通してアクセスします。それぞれのプラグインは各 API を持っていますが、それも BOOMR.plugins を通した領域となります。このドキュメントは主に BOOMR オブジェクトについて記述します。
以下のいずれかへのアクセスには BOOMR オブジェクトを参照します。例えば version の文字列を取得するには、BOOMR.version を使います。
boomerang ライブラリーのバージョン。バージョンは メジャー.マイナー.パッチレベル 形式の文字列になります。標準的なバージョンナンバリングが適用されます。
boomerang に追加されている全てのプラグインを格納します。もしあなたが自分でプラグインをつくった場合このオブジェクトに追加するべきです:
BOOMR.plugins.MyPlugin = {
...
};
boomerang の設定については 使用方法 #6 — boomerang を設定する に記載されています。BOOMR オブジェクトに関係があるパラメーターは:
function log(oMessage, sLevel, sSource);どこに:
log に null を設定することでログの記録を無効にできます。
window.onload イベントに page_ready ハンドラーが登録されます。もし autorun を false にすると、これは起こらず、BOOMR.page_ready() を自分で呼び出す必要があります。
boomerang を初期化するために呼び出すのが init メソッドです。boomerang の JavaScript の読み込みが終わったあとにこのメソッドを一度だけ呼び出します。一つの設定オブジェクトをパラメーターとして受け取ります。詳細は 設定項目の説明 をご覧ください。
BOOMR オブジェクトへの参照。メソッドチェーンをサポートします。
page_ready イベントを発行するメソッドです。init() メソッドを呼び出した時に autorun を false にしているときだけこのメソッドを呼び出します。あなたのページではユーザーが ready を使う場合にはこのメソッドを呼び出す必要があります。これはページの読み込み時間の測定時の終了時間になります。
このメソッドの使い方の例は 使用方法 #1b をご覧ください。
BOOMR オブジェクトへの参照。メソッドチェーンをサポートします。
subscribe メソッドは boomerang の イベント にイベントハンドラーを追加します。4つのパラメーターを受け付けます。
function(oEventData, oCallbackData);
this への参照は oCallbackScope を参照します。
before_beacon はビーコンが発生する前に何かしたい場合に便利ですが、page_ready と page_unload イベントはほとんどのプラグインで役立ちます。さらに詳しい内容は イベント のセクションをご覧ください。
BOOMR オブジェクトへの参照。メソッドチェーンをサポートします。
ビーコンに一つ以上のパラメーターを追加します。このメソッドはビーコンにパラメーターを追加したいプラグインによって使用されますが、ページの開発者が現在のリクエストにタグをつけるために使う場合もあるかもしれません。
addVar() を使用した例は 使用方法 #5 をご覧ください。
このメソッドは key/value のペアを含んだ一つのオブジェクト、または一つ目が変数名、二つ目が値といったような二つのパラメーターと一緒に呼び出されます。全ての名前は URL のクエリーストリングに使用できる文字列である必要があります。英数字とアンダースコアを推奨しますが、あなたが使いたい文字列でも構いません。値は文字列または数値である必要があります。こちらも名前と同じ制限があります。
BOOMR オブジェクトへの参照。メソッドチェーンをサポートします。
ビーコン URL から一つ以上の変数を削除します。これはセットしたパラメーターの値をリセットするプラグインで有効に使えます。また、before_beacon ハンドラーでも送信したビーコンを止めるために使用できます。使用方法は 使用方法 #5 をご覧ください。
このメソッドは変数名のリストまたは変数名のリストを含んだ一つの配列のいずれかを受け取ります。
BOOMR オブジェクトへの参照。メソッドチェーンをサポートします。
ビーコンを送信するために boomerang へリクエストを送ります。boomerang はこのリクエストを無視する場合があります。このメソッドが呼び出されると、boomerang は全てのプラグインをチェックします。もし不完全なプラグインがあれば（プラグインの is_complete() をチェック）、このメソッドは false を返し何もしません。全てのプラグインに問題なければ、ビーコンに送信された全ての変数と一緒に before_beacon イベントを発生させます。
全ての before_beacon ハンドラーが終了したあとに、beacon_url がセットされているか、ビーコンを送信するためにパラメーターが存在するかをチェックし共に問題がなければビーコンが送信されます。
BOOMR オブジェクトへの参照。メソッドチェーンをサポートします。
設定されたロガーへ sLevel のレベルと一緒に sMessage を記録します。このメソッドは単に設定されたロガーに全てのロギング情報を渡します。設定の詳しい方法は 使用方法 #6 をご覧ください。
大抵の場合ログレベルを設定するよりも次のメソッドを使用したほうが便利です。
なし
設定されたロガーへ debug レベルで sMessage を記録します。sSource がセットされていると "boomerang." の文字列に結合され、ログメッセージのソースとしてセットされます。このパラメーターはプラグイン名や行番号、関数名などを出力するために使用できます。
BOOMR オブジェクトへの参照。メソッドチェーンをサポートします。
設定されたロガーへ info レベルで sMessage を記録します。sSource がセットされていると "boomerang." の文字列に結合され、ログメッセージのソースとしてセットされます。このパラメーターはプラグイン名や行番号、関数名などを出力するために使用できます。
BOOMR オブジェクトへの参照。メソッドチェーンをサポートします。
設定されたロガーへ warn レベルで sMessage を記録します。sSource がセットされていると "boomerang." の文字列に結合され、ログメッセージのソースとしてセットされます。このパラメーターはプラグイン名や行番号、関数名などを出力するために使用できます。
BOOMR オブジェクトへの参照。メソッドチェーンをサポートします。
設定されたロガーへ error レベルで sMessage を記録します。sSource がセットされていると "boomerang." の文字列に結合され、ログメッセージのソースとしてセットされます。このパラメーターはプラグイン名や行番号、関数名などを出力するために使用できます。
BOOMR オブジェクトへの参照。メソッドチェーンをサポートします。
ユーザーがページを利用できるようになった時に発生します。デフォルトでは window.onload が発生した時に発生しますが、autorun を false にしている場合は BOOMR.init() が呼び出されたときに BOOMR.page_ready() によって明示的に発生させる必要があります。
追加されるイベントデータはコールバック関数に渡されます。いくつかのデータは subscribe() メソッドに渡されます。
ブラウザーがページを閉じる直前に発生します。window.onbeforeunload が発生した時に発生します（Opera では onunload）。
追加されるイベントデータはコールバック関数に渡されます。いくつかのデータは subscribe() メソッドに渡されます。
ビーコンがサーバーへ送信される直前に発生します。ビーコンのパラメーターは BOOMR.removeVar() を呼び出すことによってビーコンを止めるられます。
コールバック関数は二つのパラメーターと一緒に呼び出されます。最初のパラメーターはビーコンに追加される全てのパラメーターを含んだオブジェクトになります。二つ目のパラメーターは subscribe() メソッドに渡されたコールバックデータのオブジェクトになります。もしコールバック関数が boomerang から全てのパラメーターを削除した場合、ビーコンは送信されません。
独自のプラグインがない場合、boomerang はビーコンを通して次のパラメーターを送ります:
プラグインによってはそれぞれのプラグインの API ドキュメントに記述されている独自のパラメーターを追加するかもしれません。
最新のソースコードとドキュメントは github.com/SOASTA/boomerang に公開されています。