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