Analytics サービス入門にようこそ。このページは、Analytics サービスに ついて学習するための開始点です。以下のトピックについて説明します。
Analytics サービス・アプリケーションは、Dojo Toolkit for JavaScript の dojox.analytics および 関連プラグインの使用を補完するために作成されたものです。 Analytics は、イベント (Dojo、マウスのクリックなど) の追跡 およびログの生成をクライアント・サイドのコードから行う方法を提供します。分析情報がクライアントで管理され、 いくつかの分析サーバーに送信される場合がしばしばあります。これは煩雑になることがあり、 アプリケーションを提供したサーバーの外側にあるドメインとの通信を必要とすることもよくあります。 Analytics サービスは、サーバー・サイドで分析およびロギングの多重化 を扱う方法を提供します。クライアント上に存在する dojox.analytics コード は、アプリケーションを提供したサーバーと同一のサーバーにイベントを送信するので、 クロスドメイン問題が解消されます。
サーバー上の Analytics サービス・アプリケーションには、クライアント dojox.analytics コードから送信された要求を 受け取るサーバー・サイド JAX-RS リソースがあります。 Analytics サービス・アプリケーション内にサーブレット初期設定パラメーターを 設定して、分析イベントをどのように処理するのかを構成できます。デフォルトでは、 すべてのイベントが、単一のログ・ファイルである analytics_default.log に送信されます。
前提となる製品 | バージョン |
---|---|
Java Technology Edition | 5.0 以降 |
Java Platform, Enterprise Edition 5 (Java EE) アプリケーション・サーバー以降 | WebSphere Application Server バージョン 8.5 |
Web ブラウザー | 任意の新しい Web ブラウザー (例: Internet Explorer 7 以降、 Mozilla Firefox 3.x 以降、Google Chrome、Safari、Opera) |
Analytics サービスが有用なのは、クライアント・サイド JavaScript が dojox.analytics を活用している場合のみです。クライアント・サイド JavaScript は、適切な dojo.require ステートメントを組み込むだけで dojox.analytics のツールにアクセスできます。 この依存関係を使用して、イベントを生成するためのいくつかのオプションを使用できます。 以下の例を参照してください。
イベントを生成する機能を有効にします。
dojo.require("dojox.analytics.plugins.dojo");
任意のテキストを持つ dojox.analytics イベントを生成します。
console.rlog("Any quoted string goes here.");
高精度タイム・スタンプをつけて情報をログに記録します。
dojox.analytics.addData("timestamp", [new Date().getTime(), "on-load executed"]);
dojox.analytics によって追跡するイベントを選択する他に、分析サービスの相対 URL または絶対 URL を 識別するための構成が必要です。以下のパラメーターを使用できます。
djConfig パラメーター | 意味および設定できる値 | 必須? |
---|---|---|
analyticsUrl: | 分析サービスの URL。 完全修飾で指定するか、現行リソースへの相対で指定します。 | はい |
sendMethod | 'script' または 'xhrPost' (デフォルト) | 分析サービスが参照元ページと異なるドメインにある場合、sendMethod: 'script' が必須です。 |
sendInterval | どれだけの間イベントを累積した後で分析サービスに送信するのかを ミリ秒で指定します。 | いいえ。デフォルトで 5000 ミリ秒に設定されます。 |
デフォルトの構成では、サーバー JVM からサーバー java.io.tmpdir システム・プロパティーによって定義されるディレクトリー にある単一のログ・ファイル analytics_default.log に、すべてのイベントが送信されます。 この出力ログ・ファイル名およびパスは、web.xml ファイル内のプロパティー設定によってカスタマイズできます。 これを行うには、イベント・ログの記録先にするファイルの絶対パスを、 param-name com.ibm.ws.mobile.appsvcs.analytics.logger.LocalFileLogger の param-value に指定する必要があります。また、サービスが使用する構文バージョンを 指定するために値「1.0」を指定する必要もあります。これは必須であり、 将来のバージョン管理のためだけのものです。
以下の web.xml ファイルの一部は、その使用法を示します。
... <init-param> <param-name>com.ibm.ws.mobile.appsvcs.analytics.logger.LocalFileLogger</param-name> <param-value>1.0,/tmp/events.log</param-value> </init-param> ...
各ログ項目の一部として記録されるその他の情報を指定して、 ログのフォーマットをさらにカスタマイズすることも可能です。これは、web.xml ファイル内のプロパティー設定によって行うことができます。 これを行うには、 param-name com.ibm.ws.mobile.appsvcs.analytics.logger.LocalFileLogger.LogFormat の param-value に、1 つ以上の事前定義キーワードを指定します。
以下の web.xml ファイルの一部は、その使用法を示します。
... <init-param> <param-name>com.ibm.ws.mobile.appsvcs.analytics.logger.LocalFileLogger.LogFormat</param-name> <param-value>CLIENT_IP,CLIENT_SESSION,HTTP_REFERER</param-value> </init-param> ...
以下の事前定義キーワードから選択することができます。
ログ・フォーマット項目 | ログに記録される内容 |
---|---|
CLIENT_SESSION | HttpServletRequest#getRequestedSessionId() を ログに記録します。これは、クライアントによって指定される要求セッション ID です。 |
CLIENT_SESSION_FORCED | HttpServletRequest#getSession(true).getId() をログに記録します。 これは、HTTP セッションが存在しない場合にその作成を強制し、そのセッション ID を ログに記録します。 |
CLIENT_IP | HttpServletRequest#getRemoteAddr() をログに記録します。 これは、クライアントのインターネット・プロトコル (IP) アドレスです。 |
HTTP_REFERER | HttpServletRequest#getHeader() をログに記録します。 これは、要求ヘッダーです。 |
Analytics サービス使用の次のステップは、アプリケーションを開始し、それを 構成することです。開始に必要なのは、.ear ファイルのインストールとデプロイのみ です。
クライアントが dojox.analytics を使用している場合、そのクライアントがイベント を生成すると、HTTP 要求が分析サーバーに送信されます。Analytics サービス は、これらの要求を Representation State Transfer (REST) インターフェースの公開によって処理します。 使用可能な操作については、下の表の説明を参照してください。
Analytics サービスは、 http://<server>:<port>/<context-root>/<url-pattern>/analytics/logger をターゲットにした要求を処理します。 コンテキスト・ルートは、Web アーカイブ・ファイル (.war) が エンタープライズ・アーカイブ・ファイル (.ear) 内にパッケージされている場合、application.xml ファイルによって定義されます。 .war が単独でインストールされている場合は、コンテキスト・ルートはユーザーによってインストール時に 定義されます。uri マッピングは .war ファイル内の WEB-INF/web.xml に定義されます。
提供される appsvcs-analytics.ear 内では、application.xml ファイル は "/appsvcs-analytics" のコンテキスト・ルートを指定し、web.xml ファイル は "/rest/*" の URL パターンを指定しています。
操作の説明 | メソッド | URI | パラメーター |
---|---|---|---|
イベント・リストの報告 | GET | /appsvcs-analytics/rest/analytics/logger | 2 つの必須の照会パラメーター (id および data) と 1 つのオプション・パラメーター (callback) があります。 |
イベント・リストの報告 | POST | /appsvcs-analytics/rest/analytics/logger | POST 要求は同じパラメーターを使用しますが、 それらは URI 照会の一部ではありません。そうではなく、 HTTP 要求の本体に組み込まれます。 下に例があります。 |
次の表に、各パラメーターの説明を示します。
照会パラメーター | 説明 |
---|---|
id | 固有のイベント ID |
data | フォーマット済みの、イベントの JSON 配列 |
callback | 応答に組み込む必要のある、JavaScript メソッドの 名前。応答のフォーマットについては、 下の説明を参照してください。 |
POST 要求と GET 要求への応答に差異はありません。ただし、 オプションの callback パラメーターが要求に含まれている場合は、応答のフォーマットは少し 異なります。フォーマットの概略を以下の例で示します。
説明 | サンプル要求 | サンプル応答 |
---|---|---|
callback が指定されている GET | GET /appsvcs-analytics/rest/analytics/logger?id=1&callback=method &data=[{"plugin":"dojo","data":{"locale":"en-us"}}] | method({"eventsReceived":1,"id":"1"}) |
callback が指定されていない GET | GET /appsvcs-analytics/rest/analytics/logger?id=1 &data=[{"plugin":"dojo","data":{"locale":"en-us"}}] | {"eventsReceived":1,"id":"1"} |
callback が指定されている POST | POST /appsvcs-analytics/rest/analytics/logger, HTTP body: id=1&callback=method &data=[{"plugin":"dojo","data":{"locale":"en-us"}}] | method({"eventsReceived":1,"id":"1"}) |
callback が指定されていない POST | POST /appsvcs-analytics/rest/analytics/logger, HTTP body: id=1 &data=[{"plugin":"dojo","data":{"locale":"en-us"}}] | {"eventsReceived":1,"id":"1"} |
REST サービスに要求が送信されるたびに、 成功または失敗のタイプを示す状況コードを含む HTTP 応答が生成されます。これらの 結果は、一般的な HTTP 状況コードとよく対応しています。
状況コード | 説明 |
---|---|
200 | 要求された操作は成功しました。 |
400 | 要求のパラメーターまたは要求本体に不正な値が含まれていました。 |
405 | REST 要求内にサポートされない URI があります。 |
406 | クライアントは、要求ヘッダーで、必要な JSON フォーマットをサポートしていません。 |
415 | クライアント要求に、サポートされないコンテンツ・タイプが含まれています。 |
500 | 予期しないエラーがサーバーで発生しました。 |
このセクションでは、Analytics サービスをバージョン 8.5 の IBM WebSphere Application Server にインストールする手順を説明します。ここでは、アプリケーションのインストールとアプリケーション・サーバーの管理についての知識があることを前提としています。
製品インストールと共に提供される Analytics サービス・エンタープライズ・アーカイブ (EAR) ファイルがある場所を確認してください。EAR ファイルは、IBM WebSphere Application Server の Web 2.0 および Mobile Toolkit がインストールされたインストール・ツリー内にあります。例えば、このツールキットを以下の場所にインストールしたとします。
プラットフォーム | 場所 |
---|---|
Linux および UNIX の場合: | /opt/WebSphere/Web20Mobile |
Windows: | c:¥WebSphere¥Web20Mobile |
この場合、EAR ファイルは次の場所にあります。
プラットフォーム | 場所 |
---|---|
Linux および UNIX の場合: | /opt/WebSphere/Web20Mobile/installableApps/application_services/analytics/appsvcs-analytics.ear |
Windows: | c:¥WebSphere¥Web20Mobile¥installableApps¥application_services¥analytics¥appsvcs-analytics.ear |
デモ・クライアントのショー・ケース・サンプルをインストールし、アプリケーション・サーバーのインストール済み環境 http://<アプリケーション・ サーバー・ホスト名>:<ポート>/appsvcs-analytics/ を Web ブラウザーで参照してください。
アプリケーション・サーバーのホスト名とポート番号は、アプリケーション・サーバーのインストール済み環境に固有のものです。アプリケーション・サーバー・インストール の Web コンテナーのデフォルト・ポートは 9080 です。アプリケーション・サーバー・インストールと同じワークステーション で Web ブラウザーを実行していて、すべてデフォルト値を使用している場合は、URL: http://localhost:9080/appsvcs-analytics/ を使用してください。