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">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">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/answer/177873">Chrome
  64 Instant</a> or <a
  65 href="https://support.google.com/chrome/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">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">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 Frames within a tab can be identified by a frame ID. The frame ID of the main
 109 frame is always 0, the ID of child frames is a positive number. Once a document
 110 is constructed in a frame, its frame ID remains constant during the lifetime of
 111 the document.
 112 </p>
 113 <p>
 114 Due to the multi-process nature of Chrome, a tab might use different processes
 115 to render the source and destination of a web page. Therefore, if a navigation
 116 takes place in a new process, you might receive events both from the new and
 117 the old page until the new navigation is committed (i.e. the
 118 <code>onCommitted</code> event is send for the new main frame). Because frame
 119 IDs are only unique for a given process, the webNavigation events include a
 120 process ID, so you can still determine which frame a navigation came from.
 121 </p>
 122 <p>
 123 Also note that during a provisional load the process might be switched several
 124 times. This happens when the load is redirected to a different site. In this
 125 case, you will receive repeated <code>onBeforeNavigate</code> and
 126 <code>onErrorOccurred</code> events, until you receive the final
 127 <code>onCommitted</code> event.
 128 </p>
 129
 130 <h2 id="transition_types">Transition types and qualifiers</h2>
 131 <p>
 132 The webNavigation API's <code>onCommitted</code> event has a
 133 <code>transitionType</code> and a <code>transitionQualifiers</code> property.
 134 The <em>transition type</em> is the same as used in the <a
 135 href="history#transition_types">history API</a> describing how the browser
 136 navigated to this particular URL. In addition, several <em>transition
 137 qualifiers</em> can be returned that further define the navigation.
 138 </p>
 139 <p>
 140 The following transition qualifiers exist:
 141 </p>
 142 <table>
 143 <tr>
 144   <th> Transition qualifier </th> <th> Description </th>
 145 </tr>
 146 <tr>
 147   <td>"client_redirect"</td>
 148   <td>
 149     One or more redirects caused by JavaScript or meta refresh tags on the page
 150     happened during the navigation.
 151   </td>
 152 </tr>
 153 <tr>
 154   <td>"server_redirect"</td>
 155   <td>
 156     One or more redirects caused by HTTP headers sent from the server happened
 157     during the navigation.
 158   </td>
 159 </tr>
 160 <tr>
 161   <td>"forward_back"</td>
 162   <td>
 163     The user used the Forward or Back button to initiate the navigation.
 164   </td>
 165 </tr>
 166 <tr>
 167   <td>"from_address_bar"</td>
 168   <td>
 169     The user initiated the navigation from the address bar (aka Omnibox).
 170   </td>
 171 </tr>
 172 </table>