1 <h2 id="manifest">Manifest</h2> 2 <p> 3 All <code>chrome.webNavigation</code> methods and events require you to declare 4 the "webNavigation" permission in the <a href="manifest.html">extension 5 manifest</a>. 6 For example: 7 </p> 8 9 <pre>{ 10 "name": "My extension", 11 ... 12 <b>"permissions": [ 13 "webNavigation" 14 ]</b>, 15 ... 16 }</pre> 17 18 19 <h2 id="examples">Examples</h2> 20 21 <p> 22 You can find simple examples of using the tabs module in the 23 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/webNavigation/">examples/api/webNavigation</a> 24 directory. 25 For other examples and for help in viewing the source code, see 26 <a href="samples.html">Samples</a>. 27 </p> 28 29 <h2 id="event_order">Event order</h2> 30 <p> 31 For a navigation that is successfully completed, events are fired in the 32 following order: 33 <pre> 34 onBeforeNavigate -> onCommitted -> onDOMContentLoaded -> onCompleted 35 </pre> 36 </p> 37 <p> 38 Any error that occurs during the process results in an 39 <code>onErrorOccurred</code> event. For a specific navigation, there are no 40 further events fired after <code>onErrorOccurred</code>. 41 </p> 42 <p> 43 If a navigating frame contains subframes, its <code>onCommitted</code> is fired 44 before any of its children's <code>onBeforeNavigate</code>; while 45 <code>onCompleted</code> is fired after all of its children's 46 <code>onCompleted</code>. 47 </p> 48 <p> 49 If the reference fragment of a frame is changed, a 50 <code>onReferenceFragmentUpdated</code> event is fired. This event can fire any 51 time after <code>onDOMContentLoaded</code>, even after 52 <code>onCompleted</code>. 53 </p> 54 <p> 55 If the history API is used to modify the state of a frame (e.g. using 56 <code>history.pushState()</code>, a <code>onHistoryStateUpdated</code> event is 57 fired. This event can fire any time after <code>onDOMContentLoaded</code>. 58 </p> 59 <p> 60 If a navigation was triggered via <a 61 href="https://support.google.com/chrome/bin/answer.py?answer=177873">Chrome 62 Instant</a> or <a 63 href="https://support.google.com/chrome/bin/answer.py?answer=1385029">Instant 64 Pages</a>, a completely loaded page is swapped into the current tab. In that 65 case, an <code>onTabReplaced</code> event is fired. 66 </p> 67 68 <h2 id="relation_to_webRequest">Relation to webRequest events</h2> 69 <p> 70 There is no defined ordering between events of the <a 71 href="webRequest.html">webRequest API</a> and the events of the 72 webNavigation API. It is possible that webRequest events are still received for 73 frames that already started a new navigation, or that a navigation only 74 proceeds after the network resources are already fully loaded. 75 </p> 76 <p> 77 In general, the webNavigation events are closely related to the navigation 78 state that is displayed in the UI, while the webRequest events correspond to 79 the state of the network stack which is generally opaque to the user. 80 </p> 81 82 <h2 id="tab_ids">A note about tab IDs</h2> 83 <p> 84 Not all navigating tabs correspond to actual tabs in Chrome's UI, e.g., a tab 85 that is being pre-rendered. Such tabs are not accessible via the 86 <a href="tabs.html">tabs API</a> nor can you request information about them via 87 <code>webNavigation.getFrame</code> or <code>webNavigation.getAllFrames</code>. 88 Once such a tab is swapped in, an <code>onTabReplaced</code> event is fired and 89 they become accessible via these APIs. 90 </p> 91 92 <h2 id="timestamps">A note about timestamps</h2> 93 <p> 94 It's important to note that some technical oddities in the OS's handling 95 of distinct Chrome processes can cause the clock to be skewed between the 96 browser itself and extension processes. That means that WebNavigation's events' 97 <code>timeStamp</code> property is only guaranteed to be <i>internally</i> 98 consistent. Comparing one event to another event will give you the correct 99 offset between them, but comparing them to the current time inside the 100 extension (via <code>(new Date()).getTime()</code>, for instance) might give 101 unexpected results. 102 </p> 103 104 <h2 id="frame_ids">A note about frame and process IDs</h2> 105 <p> 106 Due to the multi-process nature of Chrome, a tab might use different processes 107 to render the source and destination of a web page. Therefore, if a navigation 108 takes place in a new process, you might receive events both from the new and 109 the old page until the new navigation is committed (i.e. the 110 <code>onCommitted</code> event is send for the new main frame). Because frame 111 IDs are only unique for a given process, the webNavigation events include a 112 process ID, so you can still determine which frame a navigation came from. 113 </p> 114 <p> 115 Also note that during a provisional load the process might be switched several 116 times. This happens when the load is redirected to a different site. In this 117 case, you will receive repeated <code>onBeforeNavigate</code> and 118 <code>onErrorOccurred</code> events, until you receive the final 119 <code>onCommitted</code> event. 120 </p> 121 122 <h2 id="transition_types">Transition types and qualifiers</h2> 123 <p> 124 The webNavigation API's <code>onCommitted</code> event has a 125 <code>transitionType</code> and a <code>transitionQualifiers</code> property. 126 The <em>transition type</em> is the same as used in the <a 127 href="history.html#transition_types">history API</a> describing how the browser 128 navigated to this particular URL. In addition, several <em>transition 129 qualifiers</em> can be returned that further define the navigation. 130 </p> 131 <p> 132 The following transition qualifiers exist: 133 </p> 134 <table> 135 <tr> 136 <th> Transition qualifier </th> <th> Description </th> 137 </tr> 138 <tr> 139 <td>"client_redirect"</td> 140 <td> 141 One or more redirects caused by JavaScript or meta refresh tags on the page 142 happened during the navigation. 143 </td> 144 </tr> 145 <tr> 146 <td>"server_redirect"</td> 147 <td> 148 One or more redirects caused by HTTP headers sent from the server happened 149 during the navigation. 150 </td> 151 </tr> 152 <tr> 153 <td>"forward_back"</td> 154 <td> 155 The user used the Forward or Back button to initiate the navigation. 156 </td> 157 </tr> 158 <tr> 159 <td>"from_address_bar"</td> 160 <td> 161 The user initiated the navigation from the address bar (aka Omnibox). 162 </td> 163 </tr> 164 </table> 165
