See use cases #3 & #5 for a description of this requirement.
Boomerang's bandwidth plugin (BOOMR.plugins.BW) measures the user's network throughput and network latency
and adds this to the beacon. You will either need to build boomerang with this plugin or include it as part of your HTML
page. Both methods will be described below.
Also note that, bandwidth detection through javascsript is not accurate. If the user's network is lossy or is shared with other users, or network traffic is bursty, real bandwidth can vary over time. The measurement we take is based over a short period of time, and this may not be representative of the best or worst cases. We try to cover for that by measuring not just the bandwidth, but also the error value in that measurement.
To include boomerang and the bandwidth plugin on your page, use the following code in your HTML (assuming the bw.js
file is in a directory called plugins/ under the current directory):
<script src="boomerang.js" type="text/javascript"></script> <script src="plugins/bw.js" type="text/javascript"></script>
To build a version of boomerang with the bandwidth plugin included, run the following command on your command line inside the boomerang directory:
make PLUGINS=plugins/bw.js
This will create a file called boomerang-0.9.XXXXXXXX.js (where XXXXXXXX is a numeric timestamp) in the current directory and you
will include that file in your HTML:
<script src="boomerang-0.9.XXXXXXXX.js" type="text/javascript"></script>
Note that the default for the make command is to build boomerang with the rt.js and bw.js plugins,
so simply running make is sufficient, although that will get you the extra rt.js plugin that you may not want.
The bandwidth images are located in the images/ folder of your local boomerang git repository. You need to copy all of these images to a location on your HTTP server. Some people choose to put these images on their CDN, but be aware that this could result in increased CDN charges. You will need to configure your CDN to ignore the query string when caching these images.
Add boomerang to your page using one of the two methods outlined above, and then call the init() method. This will start the bandwidth
test once the page loads. If you want the beacon results to include the results of the bandwidth test, setting block_beacon to true
will force boomerang to wait for the test to complete before sending the beacon. If you do not turn on the block_beacon feature, you will
only receive bandwidth results if they were cached in a cookie by a previous test run.
<!-- Include boomerang as outlined above -->
<script type="text/javascript">
BOOMR.init({
beacon_url: "http://yoursite.com/path/to/beacon.php",
BW: {
base_url: "http://base_url/to/bandwidth/images/",
block_beacon: true
}
});
</script>
The default value of the BW.base_url parameter is images/, so if your bandwidth detection
images are placed in a subdirectory of the current directory called images, then you do not need
to set the BW.base_url parameter. It is a good practice though, as you might have pages in multiple
directories.
Now while this is the minimum code required to measure bandwidth and latency and have it beaconed back, it isn't
the best option for your user. The test will run every time the user visits a page on your site even though
their bandwidth probably hasn't changed (apart from regular fluctuations). It's far better to store the bandwidth
in a cookie for a fixed period of time, and read it out of the cookie if it exists. Now it is possible that the
user moves between several networks, eg: a laptop used at home, at work and at a coffee shop. The bandwidth and
latency at these locations may be different, and it's necessary to measure them separately. We detect a change
in network through the user's IP address, so in order to store the user's bandwidth in a cookie, you will need
to tell boomerang what the user's IP address is. You do this through the user_ip parameter.
<!-- Include boomerang as outlined above -->
<script type="text/javascript">
BOOMR.init({
beacon_url: "http://yoursite.com/path/to/beacon.php",
user_ip: "<user's ip>",
BW: {
base_url: "http://base_url/to/bandwidth/images/"
}
});
</script>
As far as I know, there's no way in javascript to figure out the user's IP address. You'll have to do this server side and write the value into your code.
If your user has an IPv4 address, then we also strip out the last part of the IP and use that rather than the entire IP address. This helps if users use DHCP on the same ISP where their IP address changes frequently, but they stay within the same subnet. If the user has an IPv6 address, we use the entire address.
You may want to customise the name of the cookie where the bandwidth will be stored. By default this is
set to BA, but you can change it using the BW.cookie parameter.
<!-- Include boomerang as outlined above -->
<script type="text/javascript">
BOOMR.init({
beacon_url: "http://yoursite.com/path/to/beacon.php",
user_ip: "<user's ip>",
BW: {
base_url: "http://base_url/to/bandwidth/images/",
cookie: "BW"
}
});
</script>
This cookie is set to expire in 7 days. You can change its lifetime using the BW.cookie_exp parameter.
The value is in seconds. During that time, you can also read the value of the cookie on the server side. Its
format is as follows:
BA=ba=nnnnnnn&be=nnn.nn&l=nnnn&le=nn.nn&ip=iiiiii&t=sssssss;
The parameters are defined as:
user_ip parameter to the init() methodThese parameters are also sent in the beacon (See HOWTO #0), but having them in the cookie means that you can customise your users experience based on the bandwidth before you serve a request.
Finally, there may be cases when you want to completely disable the bandwidth test. Perhaps you know that your user is on a slow network, or pays by the byte (the bandwidth test uses a lot of bandwidth), or is on a mobile device that cannot handle the load. In such cases you have two options.
BW.enabled parameter to false:
<!-- Include boomerang as outlined above -->
<script type="text/javascript">
BOOMR.init({
BW: { enabled: false }
});
</script>
The latest code and docs is available on github.com/SOASTA/boomerang