This repository has been archived by the owner on Apr 15, 2019. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 447
/
RT.html
244 lines (216 loc) · 9.17 KB
/
RT.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
<!DOCTYPE HTML>
<html>
<head>
<title>Roundtrip plugin API</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>Roundtrip plugin API</h1>
<p>
The roundtrip plugin measures page load time, or other timers associated with the page. Its API
is encapsulated within the <code>BOOMR.plugins.RT</code> namespace.
</p>
<h2 id="config">Configuration</h2>
<p>
All roundtrip plugin configuration items are under the <code>RT</code> namespace.
The full configuration object is described in <a href="../howtos/howto-6.html">Howto #6 — Configuring boomerang</a>.
</p>
<dl>
<dt>cookie</dt>
<dd>
<strong>[optional]</strong>
The name of the cookie in which to store the start time for measuring page load time. The default name is <code>RT</code>.
Set this to a falsy value like <code>null</code> or the empty string to ignore cookies and depend completely on the
WebTiming API for the start time.
</dd>
<dt>cookie_exp</dt>
<dd>
<strong>[optional]</strong>
The lifetime in seconds of the roundtrip cookie. This only needs to live for as long as it takes for a single page to load.
Something like 10 seconds or so should be good for most cases, but to be safe, and to cover people with really slow
connections, or users that are geographically far away from you, keep it to a few minutes. The default is set to 10 minutes.
</dd>
<dt>strict_referrer</dt>
<dd>
<strong>[optional]</strong>
By default, boomerang will not measure a page's roundtrip time if the URL in the <code>RT</code> cookie doesn't match
the current page's <code>document.referrer</code>. This is so because it generally means that the user visited a
third page while their <code>RT</code> cookie was still valid, and this could render the page load time invalid.<br>
There may be cases, though, when this is a valid flow — for example, you have an SSL page in between and the
referrer isn't passed through. In this case, you'll want to set <code>strict_referrer</code> to <code>false</code>
</dd>
</dl>
<h2 id="methods">Methods</h2>
<dl class="api">
<dt>init(oConfig)</dt>
<dd>
<p>
Called by the <a href="BOOMR.html#init">BOOMR.init()</a> method to configure the roundtrip
plugin.
</p>
<h3>Parameters</h3>
<dl>
<dt>oConfig</dt>
<dd>The configuration object passed in via <code>BOOMR.init()</code>. See the <a href="#config">Configuration section</a> for details.
</dl>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR.plugins.RT</code> object, so you can chain methods.
</p>
</dd>
<dt>startTimer(sName, [nValue])</dt>
<dd>
<p>
Starts the timer named <code>sName</code>. Timers count in milliseconds. You must call
<code>endTimer()</code> when this timer has complete for the measurement to be recorded
in boomerang's beacon.
</p>
<p>
If passed in, the optional second parameter <code>nValue</code> is the timestamp in milliseconds
to set the timer's start time to. This is useful if you need to record a timer that started
before boomerang was loaded up.
</p>
<h3>Parameters:</h3>
<dl>
<dt>sName</dt>
<dd>The name of the timer to start</dd>
<dt>nValue</dt>
<dd><strong>[optional]</strong>
A javascript timestamp value (milliseconds since the epoch). If set, the timer's start time will be set
explicitly to this value. If not set, the current timestamp is used. You'd use this parameter if you
measured a timestamp before <code>boomerang</code> was loaded and now need to pass that value to the
roundtrip plugin.
</dd>
</dl>
<h3>Example:</h3>
<p>
See <a href="../howtos/howto-4.html">Howto #4</a> for an example that uses startTimer and endTimer.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR.plugins.RT</code> object, so you can chain methods.
</p>
<h3>Note</h3>
<p>
Calling <code>startTimer("t_page")</code> has the side-effect of calling <code>endTimer("t_resp")</code>.
These timers are generally used to measure the time from (as close to) the first byte loaded to <code>onload</code>
(<code>t_page</code>) and from <code>onbeforeunload</code> to the first byte time (<code>t_resp</code>).
You do not need to explicitly call <code>startTimer("t_resp")</code>.
</p>
</dd>
<dt>endTimer(sName, [nValue])</dt>
<dd>
<p>
Stops the timer named <code>sName</code>. It is not necessary for the timer to have been started
before you call <code>endTimer()</code>. If a timer with this name was not started, then the unload
time of the previous page is used instead. This allows you to measure the time across pages.
</p>
<h3>Parameters:</h3>
<dl>
<dt>sName</dt>
<dd>The name of the timer to stop</dd>
<dt>nValue</dt>
<dd><strong>[optional]</strong>
A javascript timestamp value (milliseconds since the epoch). If set, the timer's stop time will be set
explicitly to this value. If not set, the current timestamp is used. You'd use this parameter if you
measured a timestamp before <code>boomerang</code> was loaded and now need to pass that value to the
roundtrip plugin.
</dd>
</dl>
<h3>Example:</h3>
<p>
See <a href="../howtos/howto-4.html">Howto #4</a> for an example that uses startTimer and endTimer.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR.plugins.RT</code> object, so you can chain methods.
</p>
</dd>
<dt>setTimer(sName, nValue)</dt>
<dd>
<p>
Sets the timer named <code>sName</code> to an explicit time measurement. You'd use this method if you
measured time values within your page before <code>boomerang</code> was loaded and now need to pass
those values to the roundtrip plugin for inclusion in the beacon. It is not necessary to call
<code>startTimer()</code> or <code>endTimer()</code> before calling <code>setTimer()</code>. If you
do, the old values will be ignored and the value passed in to this function will be used.
</p>
<h3>Parameters:</h3>
<dl>
<dt>sName</dt>
<dd>The name of the timer to set</dd>
<dt>nValue</dt>
<dd>
The value in milliseconds to set this timer to.
</dd>
</dl>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR.plugins.RT</code> object, so you can chain methods.
</p>
</dd>
<dt>done()</dt>
<dd>
<p>
Typically called automatically when boomerang's <a href="BOOMR.html#page_ready">page_ready</a>
event fires, but it may also be called explicitly to measure the load time of transitions that
do not involve a onload event.
</p>
<p>
This method calculates page load time, and determines whether the values we have are good enough
to be beaconed. It then signals the <code>BOOMR</code> object via its <a href="BOOMR.html#sendBeacon">sendBeacon</a>
method.
</p>
<h3>Example:</h3>
<p>
See <a href="../howtos/howto-2.html">Howto #2</a> for an example of explicitly calling the <code>done()</code> method.
</p>
<h3>Returns</h3>
<p>
a reference to the <code>BOOMR.plugins.RT</code> object, so you can chain methods.
</p>
<h3>See also</h3>
<ul>
<li><a href="../methodology.html#roundtrip">Roundtrip methodology</a> for details on how roundtrip time is measured.</li>
</ul>
</dd>
<dt>is_complete()</dt>
<dd>
<p>
Called by <a href="BOOMR.html#sendBeacon">BOOMR.sendBeacon()</a> to determine if the roundtrip plugin has
finished what it's doing or not.
</p>
<h3>Returns</h3>
<ul>
<li><code>true</code> if the plugin has completed.</li>
<li><code>false</code> if the plugin has not completed.</li>
</ul>
</dd>
</dl>
<h2 id="beacon">Beacon Parameters</h2>
<p>
This plugin adds the following parameters to the beacon:
</p>
<dl>
<dt>t_done</dt> <dd><strong>[optional]</strong> Perceived load time of the page.</dd>
<dt>t_page</dt> <dd><strong>[optional]</strong> Time taken from the head of the page to page_ready.</dd>
<dt>t_resp</dt> <dd><strong>[optional]</strong> Time taken from the user initiating the request to the first byte of the response.</dd>
<dt>t_other</dt> <dd><strong>[optional]</strong> Comma separated list of additional timers set by page developer. Each timer is of the format <code>name|value</code></dd>
<dt>t_load</dt> <dd><strong>[optional]</strong> If the page were prerendered, this is the time to fetch and prerender the page.</dd>
<dt>t_prerender</dt> <dd><strong>[optional]</strong> If the page were prerendered, this is the time from start of prefetch to the actual page display. It may only be useful for debugging.</dd>
<dt>t_postrender</dt> <dd><strong>[optional]</strong> If the page were prerendered, this is the time from prerender finish to actual page display. It may only be useful for debugging.</dd>
<dt>r</dt> <dd>URL of page that set the start time of the beacon.</dd>
<dt>r2</dt> <dd><strong>[optional]</strong> URL of referrer of current page. Only set if different from <code>r</code> and <code>strict_referrer</code> has been explicitly turned off.</dd>
<dt>rt.start</dt> <dd>Specifies where the start time came from. May be one of <code>cookie</code> for the start cookie, <code>navigation</code> for the W3C navigation timing API, <code>csi</code> for older versions of Chrome or <code>gtb</code> for the Google Toolbar.</dd>
</dl>
<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>
</body>
</html>
<!--
Copyright (c) 2011, Yahoo! Inc. All rights reserved.
Copyrights licensed under the BSD License. See the accompanying LICENSE.txt file for terms.
-->