Welcome to the Getting Started with the Analytics service. This page is the starting point for learning about the Analytics service. The following topics are covered:
The Analytics service application was created to complement the use of dojox.analytics and related plug-ins from the Dojo Toolkit for JavaScript. Analytics provides a way to track events (Dojo, mouse clicks, and so on) and generate logging from the client-side code. The analytics information is often managed on the client and sent to potentially several different analytics servers. This can be cumbersome and often requires communication with domains outside of the server that provided the application. The Analytics service provides a way to handle the multiplexing of analytics and logging on the server side. The existing dojox.analytics code on the client sends the events to the same server that provided the application, which eliminates any cross domain issues.
On the server, the Analytics service application includes a server-side JAX-RS resource that accepts the requests sent from the clients dojox.analytics code. Servlet initialization parameters can be set in the Analytics service application to configure how it handles the analytics events. By default, all events are sent to a single log file, analytics_default.log.
Product prerequisite | Version |
---|---|
Java Technology Edition | 5.0 and later |
Java Platform, Enterprise Edition 5 (Java EE) application server and later | WebSphere Application Server Version 8.5 |
Web browser | Any modern web browser, such as Internet Explorer 7 and later, Mozilla Firefox 3.x and later, Google Chrome, Safari, Opera |
The Analytics service is only useful if the client side JavaScript is leveraging dojox.analytics. To access the tools from dojox.analytics, the client side JavaScript need only include the proper dojo.require statement. With that dependency pulled in, several options are available to generate events. See the following examples:
Enable the ability to generate events.
dojo.require("dojox.analytics.plugins.dojo");
Generate a dojox.analytics event with arbitrary text.
console.rlog("Any quoted string goes here.");
Log something with a high precision time stamp.
dojox.analytics.addData("timestamp", [new Date().getTime(), "on-load executed"]);
Beyond selecting which events will be tracked by dojox.analytics, configuration to identify the relative or absolute URL of the analytics service is required. You might also use the following parameters:
djConfig parameter | meaning and possible values | Required? |
---|---|---|
analyticsUrl: | URL of the analytics service, either fully qualified or relative to the current resource | Yes |
sendMethod | 'script' or 'xhrPost' (default) | sendMethod: 'script' is required if analytics service is on a different domain than the referring page. |
sendInterval | Number of milliseconds to accumulate events before sending to the analytics service | No, defaults to 5000 milliseconds |
The default configuration sends all events to a single log file, analytics_default.log, located in the directory defined by the server java.io.tmpdir system property from the server JVM. This output log file name and path can be customized via property settings in the web.xml file. To do so, you will need to specify the full path of the file where you would like events to be logged to, in the param-value for the param-name com.ibm.ws.mobile.appsvcs.analytics.logger.LocalFileLogger. You will also need to specify a value of '1.0' to identify the syntax version to be used by the service. This is required, and is simply to allow for versioning in the future.
The following portion of web.xml file demonstrates its use:
... <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> ...
You can also further customize the format of the log by specifying what other information is recorded as part of each log entry. This can be done via property settings in the web.xml file. To do so, simply specify one or more of the predefined keywords in the param-value for the param-name com.ibm.ws.mobile.appsvcs.analytics.logger.LocalFileLogger.LogFormat.
The following portion of web.xml file demonstrates its use:
... <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> ...
You can choose from any of the following predefined keywords:
log format entry | what is logged |
---|---|
CLIENT_SESSION | logs HttpServletRequest#getRequestedSessionId(), the request's session ID specified by the client |
CLIENT_SESSION_FORCED | logs HttpServletRequest#getSession(true).getId(), forcing the creation of a HTTP session if it doesn't exist, and logging it's session id |
CLIENT_IP | logs HttpServletRequest#getRemoteAddr(), the Internet Protocol (IP) address of the client |
HTTP_REFERER | logs HttpServletRequest#getHeader(), the request header |
The next step in using the Analytics Service is to start the application and configure it. Starting it only requires installing and deploying the .ear file.
When a client is using dojox.analytics, the events that it generates result in HTTP requests being sent to an analytics server. The Analytics service processes these requests by exposing a Representation State Transfer (REST) interface. See the following table, which describes the available operations.
The Analytics service will handle requests targeted at http://<server>:<port>/<context-root>/<url-pattern>/analytics/logger. The context root is defined by the application.xml file if your web archive file (.war) is packaged in an enterprise archive (.ear) file. If the .war is installed by itself, the context root is defined at install time by the user. The uri mapping is defined in the WEB-INF/web.xml in the .war file.
In the provided appsvcs-analytics.ear, the application.xml file specifies a context root of "/appsvcs-analytics" and the web.xml file specifies a URL pattern of "/rest/*".
Operation Description | Method | URI | Parameters |
---|---|---|---|
Report a list of events | GET | /appsvcs-analytics/rest/analytics/logger | There are two required query parameters (id and data) and one that is optional (callback). |
Report a list of events | POST | /appsvcs-analytics/rest/analytics/logger | The POST request uses the same parameters, but they are not part of the URI query. Rather, they are in the body of the HTTP request. Examples are provided below. |
The following table provides a description for each of the parameters.
Query Parameter | Description |
---|---|
id | Unique event identifier |
data | JSON formatted array of events |
callback | The name of the JavaScript method that should be included in the response. See the following information about the format of the response. |
Responses to the POST and GET requests are no different. However, the format of the response is slightly different if the optional callback parameter is included in the request. The following examples below outline the format.
Description | Sample Request | Sample Response |
---|---|---|
GET with callback | GET /appsvcs-analytics/rest/analytics/logger?id=1&callback=method &data=[{"plugin":"dojo","data":{"locale":"en-us"}}] | method({"eventsReceived":1,"id":"1"}) |
GET without callback | GET /appsvcs-analytics/rest/analytics/logger?id=1 &data=[{"plugin":"dojo","data":{"locale":"en-us"}}] | {"eventsReceived":1,"id":"1"} |
POST with callback | POST /appsvcs-analytics/rest/analytics/logger, HTTP body: id=1&callback=method &data=[{"plugin":"dojo","data":{"locale":"en-us"}}] | method({"eventsReceived":1,"id":"1"}) |
POST without callback | POST /appsvcs-analytics/rest/analytics/logger, HTTP body: id=1 &data=[{"plugin":"dojo","data":{"locale":"en-us"}}] | {"eventsReceived":1,"id":"1"} |
Each requests sent to the REST service results in an HTTP response, which includes a status code to indicate the type of success or failure. These results map well with common HTTP status codes.
Status Code | Description |
---|---|
200 | The requested operation succeeded. |
400 | The request included incorrect values in the parameters or request body. |
405 | An unsupported URI is in the REST request. |
406 | The client does not support the required JSON format, per the request headers. |
415 | The client request includes an unsupported content type. |
500 | An unexpected error occurred in the server. |
This section describes the procedure for installing the Analytics service on Version 8.5 of the IBM WebSphere Application Server. It is assumed that you are familiar with application installation and administration for the application server.
Locate the Analytics service enterprise archive (EAR) file that is provided with your product installation. You can find the EAR file in your installation tree where you installed the IBM WebSphere Application Server Web 2.0 and Mobile Toolkit. For example, if you installed the toolkit in the following location:
Platform | Location |
---|---|
Linux and UNIX: | /opt/WebSphere/Web20Mobile |
Windows: | c:\WebSphere\Web20Mobile |
Then you can find the EAR file at:
Platform | Location |
---|---|
Linux and UNIX: | /opt/WebSphere/Web20Mobile/installableApps/application_services/analytics/appsvcs-analytics.ear |
Windows: | c:\WebSphere\Web20Mobile\installableApps\application_services\analytics\appsvcs-analytics.ear |
Install showcase sample for the democlient and Point your web browser to your application server installation: http://<application server hostname>:<port>/appsvcs-analytics/
The application server host name and port number are specific to your application server installation. An application server default installation web container port is 9080. If you are running your web browser on the same workstation as your application server installation and have taken all the default values, then use the following URL: http://localhost:9080/appsvcs-analytics/.