src/chrome/common/extensions/docs/templates/intros/webNavigation.html

   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 -&gt; onCommitted -&gt; onDOMContentLoaded -&gt; 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>