1 <h2 id="manifest">Manifest</h2> 2 <p>You must declare the "contentSettings" permission 3 in your extension's manifest to use the API. 4 For example:</p> 5 <pre>{ 6 "name": "My extension", 7 ... 8 <b>"permissions": [ 9 "contentSettings" 10 ]</b>, 11 ... 12 }</pre> 13 14 15 <h2 id="patterns">Content setting patterns</h2> 16 <p> 17 You can use patterns to specify the websites that each content setting affects. 18 For example, <code>http://*.youtube.com/*</code> specifies youtube.com and all 19 of its subdomains. The syntax for content setting patterns is the same as for 20 <a href="match_patterns.html">match patterns</a>, with a few differences: 21 <ul><li>For <code>http</code>, 22 <code>https</code>, and <code>ftp</code> URLs, the path must be a wildcard 23 (<code>/*</code>). For <code>file</code> URLs, the path must be completely 24 specified and <strong>must not</strong> contain wildcards.</li> 25 <li>In contrast to match patterns, content setting patterns can specify a port 26 number. If a port number is specified, the pattern only matches websites with 27 that port. If no port number is specified, the pattern matches all ports. 28 </li> 29 </ul> 30 </p> 31 32 <h3 id="pattern-precedence">Pattern precedence</h3> 33 <p> 34 When more than one content setting rule applies for a given site, the rule with 35 the more specific pattern takes precedence. 36 </p> 37 <p>For example, the following patterns are ordered by precedence:</p> 38 <ol> 39 <li><code>http://www.example.com/*</code></li> 40 <li><code>http://*.example.com/*</code> (matching 41 example.com and all subdomains)</li> 42 <li><code><all_urls></code> (matching every URL)</li> 43 </ol> 44 <p> 45 Three kinds of wildcards affect how specific a pattern is: 46 </p> 47 <ul> 48 <li>Wildcards in the port (for example 49 <code>http://www.example.com:*/*</code>)</li> 50 <li>Wildcards in the scheme (for example 51 <code>*://www.example.com:123/*</code>)</li> 52 <li>Wildcards in the hostname (for example 53 <code>http://*.example.com:123/*</code>)</li> 54 </ul> 55 <p> 56 If a pattern is more specific than another pattern in one part but less specific 57 in another part, the different parts are checked in the following order: 58 hostname, scheme, port. For example, the following patterns are ordered by 59 precedence:</p> 60 <ol> 61 <li><code>http://www.example.com:*/*</code><br> 62 Specifies the hostname and scheme.</li> 63 <li><code>*:/www.example.com:123/*</code><br> 64 Not as high, because although it specifies the hostname, it doesn't specify 65 the scheme.</li> 66 <li><code>http://*.example.com:123/*</code><br> 67 Lower because although it specifies the port and scheme, it has a wildcard 68 in the hostname.</li> 69 </ol> 70 71 <h2 id="primary-secondary">Primary and secondary patterns</h2> 72 <p> 73 The URL taken into account when deciding which content setting to apply depends 74 on the content type. For example, for 75 $ref:contentSettings.notifications settings are 76 based on the URL shown in the omnibox. This URL is called the "primary" URL.</p> 77 <p> 78 Some content types can take additional URLs into account. For example, 79 whether a site is allowed to set a 80 $ref:contentSettings.cookies is decided based on the URL 81 of the HTTP request (which is the primary URL in this case) as well as the URL 82 shown in the omnibox (which is called the "secondary" URL). 83 </p> 84 <p> 85 If multiple rules have primary and secondary patterns, the rule with the more 86 specific primary pattern takes precedence. If there multiple rules have the same 87 primary pattern, the rule with the more specific secondary pattern takes 88 precedence. For example, the following list of primary/secondary pattern pairs 89 is ordered by precedence:</p> 90 <table> 91 <tr><th>Precedence</th><th>Primary pattern</th><th>Secondary pattern</th> 92 <tr> 93 <td>1</td> 94 <td><code>http://www.moose.com/*</code>, </td> 95 <td><code>http://www.wombat.com/*</code></td> 96 </tr><tr> 97 <td>2</td> 98 <td><code>http://www.moose.com/*</code>, </td> 99 <td><code><all_urls></code></td> 100 </tr><tr> 101 <td>3</td> 102 <td><code><all_urls></code>, </td> 103 <td><code>http://www.wombat.com/*</code></td> 104 </tr><tr> 105 <td>4</td> 106 <td><code><all_urls></code>, </td> 107 <td><code><all_urls></code></td> 108 </tr> 109 </table> 110 111 <h2 id="resource-identifiers">Resource identifiers</h2> 112 <p> 113 Resource identifiers allow you to specify content settings for specific 114 subtypes of a content type. Currently, the only content type that supports 115 resource identifiers is $ref:contentSettings.plugins, 116 where a resource identifier identifies a specific plug-in. When applying content 117 settings, first the settings for the specific plug-in are checked. If there are 118 no settings found for the specific plug-in, the general content settings for 119 plug-ins are checked. 120 </p> 121 <p> 122 For example, if a content setting rule has the resource identifier 123 <code>adobe-flash-player</code> and the pattern <code><all_urls></code>, 124 it takes precedence over a rule without a resource identifier and the pattern 125 <code>http://www.example.com/*</code>, even if that pattern is more specific. 126 </p> 127 <p> 128 You can get a list of resource identifiers for a content type by calling the 129 $ref:contentSettings.ContentSetting.getResourceIdentifiers method. The returned list 130 can change with the set of installed plug-ins on the user's machine, but Chrome 131 tries to keep the identifiers stable across plug-in updates. 132 </p> 133 134 <h2 id="examples">Examples</h2> 135 136 <p> 137 You can find samples of this API on the 138 <a href="samples.html#contentSettings">sample page</a>. 139 </p> 140
