JavaScript Technical Reference


Browser Requirements

While all browsers that support Cross-Origin Resource Sharing and Local Storage are compatible with the JavaScript SDK, we have tested and officially support the following browsers:

  • Internet Explorer 8, 9, and 10
  • Safari 5.0.x (Mac OS X only) and above
  • Chrome version 17.0 and above
  • Firefox 3.6 and above

On a non-compatible browser, calls to SDK will be ignored. Mobile browsers are not officially supported at this time.

Cross-Origin Resource Sharing

Browser support for the Cross-Origin Resource Sharing (CORS) specification is required for the SDK to use an AJAX request to reach the Medio Data Collection Service (DCS), which is hosted on another domain than your application.

Due to the way that CORS is implemented in Internet Explorer (IE) 8 & 9, the protocol used to communicate with the DCS service must match the protocol of the host page. When your application is running in IE 8 & 9, the SDK will automatically determine the protocol of the host page and use that protocol to communicate with DCS. In other words, if your application is hosted at http://mydomain.com, the SDK will communicate with the DCS service using the HTTP protocol. If your application is hosted at https://secure.mydomain.com, the SDK will communicate with the DCS service using the HTTPS protocol. If your website supports IE 8 & 9, it is important to consider the security needs of your application and host your pages using HTTPS whenever possible to ensure secure communication with the DCS service. On all other browsers, the SDK communicates with the DCS service using the HTTPS protocol regardless of the host page protocol.

Local Storage

Browser support for HTML5 Local Storage is required as the SDK uses it as the internal event buffer.

Geolocation

Browser support for HTML5 Geolocation is required only required when you set the trackLocation property to true. This feature may require the user’s explicit permission on some browsers. In most cases the user will be prompted by the browser to approve the request for his/her location.


Internal buffer capacity

The SDK uses the browser’s local storage as an internal buffer for events. When the maximum storage capacity is reached, the Medio Client SDK will purge a small number of the oldest events to make room for new events. This will only occur in extreme situations such as when events cannot be flushed to the Medio DCS due to prolonged lack of data connectivity or when a misbehaving application logs too many events without flushing.


Flushing events

The SDK flushes events automatically. Your application may also flush events manually by calling Medio.EventApi.flushEvents.
Flushing of events assumes that the browser is working in online mode and has an Internet connection available. If the application is offline, a flush request is re-scheduled.

The SDK spreads the sending of large amounts of events over several AJAX requests to minimize memory, CPU and network consumption. Once the Medio DCS successfully acknowledges receipt of the events, the Medio Client SDK removes the events from local storage. If the HTTP request fails for any reason, then the events are not removed from the local storage and re-scheduled for a later time. Events that are not sent to the Medio DCS successfully remain queued up (stored persistently in local storage) and will be sent on the next flush either automatically or manually.

The SDK will ignore all other requests to flush if it is already busy with a previous request. New requests to flush will only be accepted after the previous flush has succeeded or failed.

Flushing events and application behavior

The SDK’s automatic flush behavior may not meet every application’s requirements. For example, if you find automatic flushing affecting critical application processing like game play, then you can disable it temporarily during these critical processing points by calling Medio.EventApi.setProperties and setting the autoFlush property to false. Automatic flushing can be re-enabled again by setting the autoFlush property to true once the critical processing section is complete. Note your application can still flush events on demand using the Medio.EventApi.flushEvents method while automatic flushing is disabled or enabled.

In extreme cases, you may disable automatic flushing entirely for the life of your application. In this case, we recommend calling the Medio.EventApi.flushEvents method when you perform some other networking activity (if any). If your application does not have any networking activity, then we recommend calling Medio.EventApi.flushEvents during pauses in user interaction. For example, in the case of a game, you may wish to flush events in a “Game Over” screen or a “Main Menu” screen.

If you choose to flush events on demand instead of or in addition to automatic flushing, your application should not call Medio.EventApi.flushEvents too frequently to avoid compromising battery life. On the other hand, you also don’t want to take the risk of losing data by calling Medio.EventApi.flushEvents too infrequently, as old events are purged to allow for new ones when the internal buffer capacity limit is reached.


Performance and resources

We conducted performance tests on a machine with the following specifications:

  • OS: Mac OS X 10.6.8
  • CPU: 2.53 GHz Intel Core i5
  • RAM: 4 GB 1067 MHz DDR3

For measuring performance, we used the following tools:

  • JavaScript Profiling
  • Custom Benchmark
  • Speed Tracer Plugin (Chrome only)
  • Memory over time (Chrome and Safari)

In all of the tests, we looked at the impact of our SDK on the page’s responsiveness. JavaScript Profiling, our Custom Benchmark, and Chrome’s Speed Tracer all examine UI responsiveness. Measuring memory shows our overall system impact. Our goals are high responsiveness and low memory consumption.

The following graphs are from our Custom Benchmark, which is designed to measure the current page’s responsiveness. We used a simple game, written in HTML 5 Canvas, to generate load on the browser. Next, we added our SDK to the game to see if it causes anything to slow down. We use a mock version of our SDK (same methods, but those methods are empty) as a control variable.
The graphs below show how many times our game loop executes, broken down into 9 second intervals. The target rate (without any latency) is 600 executions for every 9 seconds. Internet Explorer (not shown) had similar results, but was tested using a different computer. Firefox and Safari performed the best. In the graphs below, there is no significant difference between using our SDK and our mock SDK (an empty implementation).

For this test, we logged two (2) events per second and automatically flushed every fifteen (15) seconds. We set all optional fields and included eleven (11) common key-value pairs. All of the tests below lasted 180 seconds.

Chrome 20.0

javascript_sdk_perf_chrome

Firefox 13.0.1

javascript_sdk_perf_firefox

Safari 5.1.7

javascript_sdk_perf_safari

RAM consumption

Memory usage during the test was approximately 10,000 kb. Memory usage also remained consistent over the duration of an 8-hour test: the highest the memory usage was 17,000 kb with 10,000 kb as the average.

CPU utilization

Chrome offers the best glimpse at memory and CPU utilization, on a per tab basis. When running the Mock SDK (an empty implementation) on Chrome 20 with our custom benchmark page, the CPU utilization was approximately 30%. There was an increase of approximately 1-2% when using our SDK. Most of the CPU load came from our game loop.

Local Storage consumption

Events are stored in Local Storage as strings. Because JavaScript uses UTF-16 strings, the size an event in Local Storage is simply the event’s string length multiplied by two.

The smallest an event can be is about 150 characters (300 bytes in storage). An event with a few key value pairs and optional fields is about 200 characters (400 bytes in storage).

In general, to calculate the storage required for an event, take the base event (about 150 characters) and add the string lengths for each field you set. Note that key value pairs add an additional two characters for delimiters. Also note that certain characters (e.g., quotes) are escaped, so allow a small margin for those as well.

If your average event is 512 bytes (256 characters) in size, you can store approximately 2,048 events in the library’s 1MB of local storage.