doc/howtos/howto-5.html

<!DOCTYPE HTML>
<html>
<head>
<title>Boomerang Howto #5: Request/page tagging</title>
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../boomerang-docs.css">
</head>
<body>
<span style="float:right;"><a href="../">All Docs</a> | <a href="index.html">Index</a></span>
<h1>Boomerang Howto #5: Request/page tagging</h1>
<p>
See <a href="../use-cases.html#uc-5">use case #5</a> for a description of this requirement.
</p>
<p>
There will be several occassions when you need to add more information to the beacon that's sent
back to the server.  For example, you may want to tag the beacon with a <code>page_id</code> or
you may want to do A/B testing and tag the beacon with a parameter specifying which bucket this
beacon is for.  You can achieve all this using the <code>BOOMR.addVar()</code> method.
</p>

<p>
Before you use this method, remember that each plugin adds its own parameters and you shouldn't
overwrite these with your own values.  See <a href="howto-0.html">Howto #0</a> for a list of
parameters set by boomerang's built-in plugins.  Other plugins may add their own parameters,
consult the documentation of the plugin to find out what these are.
</p>

<pre>
BOOMR.addVar("page_id", 123);
</pre>

<p>
The parameter name must be a string.  We recommend only using alphanumeric characters and underscores,
but you can really use anything you like.  Parameter values may only be numbers or strings, ie,
something that you can put into a URL.
</p>

<p>
If you need to set multiple parameters, you can pass in an object instead:
</p>

<pre>
BOOMR.addVar({
		"bucket": "test#1",
		"page_id": 123
	});
</pre>

<p>
Make sure you've included boomerang.js before calling <code>BOOMR.addVar()</code>.
</p>

<h2>The beacon</h2>
<p>
The beacon will include all variables that you add in the URL.  Both keys and values will be
URI encoded.  Your back end application will need to understand the passed in parameters.
</p>

<pre>
http://yoursite.com/path/to/beacon.php?<em>bucket=test%231</em>&amp;<em>page_id=123</em>&amp;t_done=.....
</pre>

<h2>Removing variables</h2>
<p>
You can also remove a parameter that you've added (or that a plugin has added) from the beacon.
To do this, call the <code>BOOMR.removeVar()</code> method.  This method takes in a list of
name, and removes all of them from the parameter list.  Any name that isn't in the parameter
list is ignored.
</p>

<pre>
<span class="comment">// don't send the stooges to the server   </span>
BOOMR.removeVar("larry", "moe", "curly");
</pre>

<h2>Stopping the beacon</h2>
<p>
You can also this as a crude way to prevent the beacon from firing.  Inside your <code>before_beacon</code>
event handler, simply remove all parameters.
</p>

<pre>
BOOMR.subscribe('before_beacon', function(o) {
	var p_names = [], k;

	if( "t_done" in o ) {
		return;
	}

	<span class="comment">// t_done is not set, so don't beacon         </span>
	for(k in o) {
		if(o.hasOwnProperty(k)) {
			p_names.push(k);
		}
	}

	<span class="comment">// removeVar accepts either a list or an array</span>
	BOOMR.removeVar(p_names);
});
</pre>

<p class="perma-link">
The latest code and docs is available on <a href="http://github.com/lognormal/boomerang/">github.com/lognormal/boomerang</a>
</p>

<p id="results">
</p>
<script src="../../boomerang.js" type="text/javascript"></script>
<script src="howtos.js" type="text/javascript"></script>
<script type="text/javascript">
BOOMR.init({
		user_ip: '10.0.0.1',
		BW: {
			base_url: '../../images/',
			cookie: 'HOWTO-BA'
		},
		RT: {
			cookie: 'HOWTO-RT'
		}
	}).
	addVar({
		"author": "bluesmoon",
		"page_id": "howto-5"
	});
</script>
</body>
</html>