README.md

Copyrights licensed under the BSD License. See the accompanying LICENSE.txt file for terms.

boomerang always comes back, except when it hits something.

summary

boomerang is a JavaScript library that measures the page load time experienced by real users, commonly called RUM.

Apart from page load time, boomerang measures a whole bunch of performance characteristics of your user's web browsing experience. All you have to do is stick it into your web pages and call the
init() method.

Yes, the best practices say to include scripts at the bottom. That's different. That's for scripts that block downloading of other resources. Including a script this
way will not block other resources, however it will block onload. Including the script at the top of your page gives it a good chance of loading
before the rest of your page does thereby reducing the probability of it blocking the onload event. If you don't want to block onload either, follow Stoyan's
advice from the Meebo team.

3.2. Adding it via an iframe

The method described in 3.1 will still block onload on most browsers (Internet Explorer not included). To avoid
blocking onload, we could load boomerang in an iframe. Stoyan's documented
the technique on his blog. We've modified it to work across browsers with different configurations, documented on
the lognormal blog.

The id of the script node created by this code MUST be boomr-if-as as boomerang looks for that id to determine if it's running within an iframe or not.

Boomerang will still export the BOOMR object to the parent window if running inside an iframe, so the rest of your code should remain unchanged.

3.3. Identifying when boomerang has loaded

If you load boomerang asynchronously, there's some uncertainty in when boomerang has completed loading. To get around this, you can subscribe to the
onBoomerangLoaded Custom Event on the document object:

Note that this only works on browsers that support the CustomEvent interface, which at this time is Chrome (including Android), Firefox 6+ (including Android),
Opera (including Android, but not Opera Mini), Safari (including iOS), IE 6+ (but see the code above for the special way to listen for the event on IE6, 7 & 8).

Boomerang also fires the onBeforeBoomerangBeacon and onBoomerangBeacon events just before and during beaconing.

docs

Documentation is in the docs/ sub directory, and is written in HTML. Your best bet is to check it out and view it locally, though it works best through a web server (you'll need cookies).
Thanks to github's awesome gh-pages feature, we're able to host the boomerang docs right here on github. Visit http://lognormal.github.com/boomerang/doc/ for a browsable version where all
the examples work.

support

We use github issues for discussions, feature requests and bug reports. Get in touch at https://github.com/lognormal/boomerang/issues
You'll need a github account to participate, but then you'll need one to check out the code as well :)

Thanks for dropping by, and please leave us a message telling us if you use boomerang.

boomerang is supported by the devs at LogNormal, and the awesome community of opensource developers that use
and hack it. That's you. Thank you!