「分析」服務入門

歡迎使用「分析服務入門」。本頁面是瞭解「分析」服務的起始點。包含的主題如下:

概觀

建立「分析」服務應用程式是為了要從 Dojo Toolkit for JavaScript 補充使用 dojox.analytics 及相關的外掛程式。 「分析」提供從用戶端程式碼追蹤事件(Dojo、點擊滑鼠等等)以及產生記載的方式。分析資訊經常是在用戶端上管理,並可能傳送至數部不同的分析伺服器。這可能會非常麻煩,並且經常需要與提供應用程式的伺服器外的網域通訊。 「分析」服務提供一種在伺服器端上處理分析及記載的多工作業方式。用戶端上的現有 dojox.analytics 程式碼將事件傳送至同一部提供應用程式的伺服器,其可消除任何跨網域問題。

在伺服器上,「分析」服務應用程式包括伺服器端 JAX-RS 資源,其接受從用戶端 dojox.analytics 程式碼所傳送的要求。 您可以在「分析」服務應用程式中設定 Servlet 起始設定參數,來配置它處理分析事件的方式。依預設,所有事件皆會傳送至單一日誌檔 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

使用「分析」服務

只有當用戶端 JavaScript 在利用 dojox.analytics 時,「分析」服務才有用。要從 dojox.analytics 存取工具,用戶端 JavaScript 只需要併入適當的 dojo.require 陳述式。在納入該相依關係時,就有數個選項可供用來產生事件。 請參閱下列範例:

啟用產生事件的能力。

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 的配置。您可能也會使用下列參數:

djConfig 參數 意義以及可能的值 必要?
analyticsUrl: 分析服務的 URL,為完整的或相對於現行資源
sendMethod 'script' 或 'xhrPost'(預設值) sendMethod:如果分析服務所在的網域與參照頁面所在的網域不同,則需要 'script'。
sendInterval 在事件傳送至分析服務之前要累計的毫秒數 否,預設為 5000 毫秒

預設配置會將所有事件傳送至單一日誌檔 analytics_default.log,此檔案位於伺服器 JVM 中的伺服器 java.io.tmpdir 系統內容所定義的目錄。 您可以透過 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 中指定一或多個預先定義的關鍵字即可。

下列 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(),即要求標頭

使用「分析」服務的下一步是啟動應用程式及配置它。啟動它只需要安裝並部署 .ear 檔。

「分析」服務的 REST 介面

當用戶端使用 dojox.analytics 時,它產生的事件會導致 HTTP 要求傳送至分析伺服器。「分析」服務藉由展示 Representation State Transfer (REST) 介面來處理這些要求。 請參閱下列表格,其中會說明可用的作業。

「分析」服務將會處理目標設定於 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 有兩個必要的查詢參數(id 和 data),以及一個選用參數 (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 伺服器中發生非預期的錯誤。

安裝「分析」服務

WebSphere Application Server 安裝指示

本節說明在 IBM WebSphere Application Server 8.5 版上安裝「分析」服務的程序。假設您熟悉應用程式伺服器的應用程式安裝和管理作業。

開始之前

請找出產品安裝隨附的「分析」服務企業保存檔 (EAR)。您可以在其中安裝 IBM WebSphere Application Server Web 2.0 and Mobile Toolkit 的安裝樹狀結構中找到 EAR 檔。比方說,如果您在下列位置安裝此工具箱:

平台 位置
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

利用管理主控台來安裝「分析」服務

  1. 登入應用程式伺服器的管理主控台。
  2. 導覽至應用程式 > 新建應用程式。(附註:在 WebSphere Application Server 6.1 版中,請選取安裝新的應用程式
  3. 選取新建企業應用程式。 (附註:在 WebSphere Application Server 6.1 版中,請跳過此步驟)
  4. 瀏覽您的檔案系統,選取先前找到的 appsvcs-graphics.ear 檔。按下一步
  5. 下一步來準備安裝應用程式。 (附註:在 WebSphere Application Server 6.1 版中,請跳過此步驟)
  6. 下一步,接受預設安裝選項。
  7. 下一步,接受將模組對映到伺服器的預設選項。
  8. 下一步,接受模組 meta 資料的預設選項(附註:在 WebSphere Application Server 6.1 版和第 7 版中,請跳過此步驟)
  9. 下一步,接受對映 Web 模組的虛擬主機之預設選項。
  10. 檢閱安裝選項的摘要。
  11. 按一下完成
  12. 按一下儲存到主要配置中
  13. 導覽至應用程式 > 應用程式類型 > WebSphere 企業應用程式。(附註:在 WebSphere Application Server 6.1 版中,請導覽至應用程式 > 企業應用程式
  14. 選取 IBM WebSphere Application Server - 分析服務,然後按一下啟動

存取已安裝的應用程式展示用戶端

安裝展示用戶端的 Showcase 範例,然後將 Web 瀏覽器指向您的應用程式伺服器安裝架構:http://<application server hostname>:<port>/appsvcs-analytics/

應用程式伺服器主機名稱和埠號是您的應用程式伺服器安裝架構專用的。 應用程式伺服器預設安裝架構的 Web 儲存器埠是 9080。如果您在應用程式伺服器安裝架構的相同工作站上執行您的 Web 瀏覽器,且全部採用預設值,請使用下列 URL:http://localhost:9080/appsvcs-analytics/


使用條款 | 意見