Guidelines for implementing an aggregator

When we implement an aggregator using the Active Site Analytics Mediator SPI, the following guidelines can be helpful.

1. Implement the function that parses the DOM to collect and format all Active Site Analytics-specific data.

2. Subscribe for the DOM notifications. Register the function that you implemented in the previous step with the object SiteAnalyticsMediator.

3. Implement the logic that sends the collected data to the external analytics service.

When performing these steps, apply the following considerations:

1. Implement the function that parses the DOM to collect and format all Active Site Analytics-specific data.

   • The implementation for collecting the data greatly depends on the themes, skins, and all the other components that might produce analytics-specific microformats. So, there is a dependency between the theme and its skins on the one hand and the aggregator.

   • The aggregator implementation can affect the performance, as it increases the page rendering time in the browser. To mitigate this time increase, take care the DOM processing required to collect the data is implemented efficiently. To achieve a good performance, use implementation details of the themes and skins. For example, use HTML identifiers in the theme markup to isolate the nodes containing the Active Site Analytics-specific data into a DOM subtree the aggregator can access efficiently. In any case, avoid traversing the entire DOM.

2. Subscribe for the DOM notifications. Register the function that you implemented in the previous step with the object SiteAnalyticsMediator.

   • It is only during this registration step that you directly invoke the Active Site Analytics Mediator SPI. Register the function with the SiteAnalyticsMediator before the browser sends the onload event.

3. Implement the logic that sends the collected data to the external analytics service.

   • To have the data analyzed, you send them to an external analytics service. This step is separated from step 1, as the aggregator cannot make assumptions as to how often it is notified about DOM changes. In a Web 2.0 portal environment with many Ajax components, multiple notifications per portal page or even per portlet interaction can occur. Therefore, this step requires a deep understanding of the analytics service. Even the contract with the analytics service provider can influence when and how frequently to send the collected data to the analytics service.

   • If it does not matter how frequently data is transmitted to the analytics service, we can combine steps 1 and 3. For example, we can send the data directly to the analytics service after or even during the DOM parsing process. If the transmission frequency is relevant, store the data in a buffer, for example a JSON object or a cookie, during the DOM parsing process in step 1. To trigger sending the buffer contents to the analytics service, we can either use an external event or a specific data change. The trigger can be based on a time interval, for example a JavaScript timeout. We can also use the beforeunload event the browser fires whenever the entire browser page is refreshed, or when a browser window or browser tab is closed.

   • We have several options for how to send the collected data to the external analytics service. A widely spread method is to use a so-called tracking image. In this case, the aggregator adds an HTML image element to the DOM, which is hidden via CSS. The image source URL that points to the external analytics service is used to transport the collected data. After adding the image element to the DOM, the browser initiates an HTTP GET request to load the tracking image. Alternatively, use an asynchronous XmlHttpRequest (XHR) to send the data to the external analytics service. This method is useful to use HTTP POST requests to submit a large amount of data.

The following list gives a summary of the guidelines:

1. Register the handler before the page finishes loading, that is, before the browser sends the onload event.

2. Do not make assumptions about the frequency by which the aggregator gets notified about DOM changes. For a single page, multiple notifications can occur.

3. Use separate steps for collecting and formatting the data, and for submitting the data to the external analytics server.

4. The processing that is done by the aggregator affects the page rendering time in the browser.

5. To ensure a better performance, use theme and skin implementation details. For example, use HTML identifiers for efficient DOM node lookups if available. Avoid traversing the entire DOM.

6. Carefully decide when and how often to send the collected data to the analytics service. This decision might depend on your analytics service provider.

7. Use an asynchronous way to send the collected data to the analytics service, for example a tracking image or an asynchronous XHR.

8. Use a JavaScript framework to implement the aggregator.

For code samples see Aggregator patterns and samples.

Parent Write an aggregator for Active Site Analytics

Related reference:

Aggregator patterns and samples