| OLD | NEW |
|---|
| (Empty) | |
| 1 <h1>Other Deployment Options</h1> |
| 2 |
| 3 |
| 4 <p> |
| 5 Usually, users install their own extensions. |
| 6 But sometimes you might want an extension |
| 7 to be installed automatically. |
| 8 Here are two typical cases: |
| 9 </p> |
| 10 |
| 11 <ul> |
| 12 <li> |
| 13 An extension is associated with some other software, |
| 14 and the extension should be installed |
| 15 whenever the user installs that other software. |
| 16 The extension could also be uninstalled |
| 17 when the user removes that other software. |
| 18 </li> |
| 19 <li> |
| 20 A network admin wants to install the same extensions |
| 21 throughout the company. |
| 22 </li> |
| 23 </ul> |
| 24 |
| 25 <p> |
| 26 An extension that's installed automatically is known as an |
| 27 <em>external extension</em>. |
| 28 Google Chrome supports two ways of |
| 29 installing external extensions: |
| 30 </p> |
| 31 |
| 32 <ul> |
| 33 <li> Using a preferences JSON file </li> |
| 34 <li> Using the Windows registry (Windows only) </li> |
| 35 </ul> |
| 36 |
| 37 <p> |
| 38 Both ways support installing an extension from a <code>.crx</code> extension |
| 39 file on the user's computer. The preferences JSON file also supports installing |
| 40 an extension hosted at an |
| 41 <a href="autoupdate.html#H2-1">update URL</a>. |
| 42 See <a href="hosting.html">hosting</a> for details on hosting an extension. |
| 43 </p> |
| 44 |
| 45 <h2 id="prereqs">Before you begin</h2> |
| 46 |
| 47 <p> |
| 48 First, package a |
| 49 <a href="packaging.html"><code>.crx</code> file</a> |
| 50 and make sure that it installs successfully. |
| 51 </p> |
| 52 <p> |
| 53 If you wish to install from an |
| 54 <a href="autoupdate.html#H2-1">update URL</a>, ensure that the extension |
| 55 is properly <a href="hosting.html">hosted</a>. |
| 56 </p> |
| 57 |
| 58 <p> |
| 59 Then, before you edit the preferences file or the registry, |
| 60 make a note of the following: |
| 61 </p> |
| 62 |
| 63 <ul> |
| 64 <li> The intended <b>location</b> of the extension's <code>.crx</code> file, |
| 65 or the update URL from which it is served </li> |
| 66 <li> The extension's <b>version</b> |
| 67 (from the manifest file or the <b>chrome://extensions</b> page) </li> |
| 68 <li> The extension's <b>ID</b> |
| 69 (from the <b>chrome://extensions</b> page |
| 70 when you've loaded the packed extension) </li> |
| 71 </ul> |
| 72 |
| 73 <p> |
| 74 The following examples assume the version is <code>1.0</code> |
| 75 and the ID is <code>aaaaaaaaaabbbbbbbbbbcccccccccc</code>. |
| 76 </p> |
| 77 |
| 78 <h2 id="preferences">Using a preferences file</h2> |
| 79 |
| 80 <p class="note"> |
| 81 <b>Windows note:</b> |
| 82 Until <a href="http://crbug.com/41902">bug 41902</a> is fixed, |
| 83 you might want to use the <a href="#registry">Windows registry</a> |
| 84 instead of the preferences file. |
| 85 </p> |
| 86 |
| 87 <p class="note"> |
| 88 <b>Note:</b> |
| 89 Previous versions of Google Chrome used an |
| 90 <code>external_extensions.json</code> file to specify which extensions to |
| 91 install. This file has been deprecated in favor of individual <code>.json</code> |
| 92 files, one per extension. |
| 93 </p> |
| 94 |
| 95 <ol> |
| 96 <li>If you are installing from a file, make the <code>.crx</code> extension |
| 97 file available to the machine you want to install the extension on. |
| 98 (Copy it to a local directory or to a network share for example, |
| 99 <code>\\server\share\extension.crx</code> |
| 100 or <code>/home/share/extension.crx</code>.) |
| 101 </li> |
| 102 |
| 103 <li>Create a file with the following name in one of the folders listed below: |
| 104 <code>aaaaaaaaaabbbbbbbbbbcccccccccc.json</code> where the file name (without
the extension) |
| 105 corresponds to your extension's ID. |
| 106 The location depends on the operating system. |
| 107 <dl> |
| 108 <dt> Windows: </dt> |
| 109 <dd> <code><em>chrome_root</em>\Application\<em>chrome_version</em>\Extensio
ns\</code> |
| 110 <br /> |
| 111 Example: <code>c:\Users\Me\AppData\Local\Google\Chrome\Application\6.0.422.0
\Extensions\</code> |
| 112 </dd> |
| 113 <dt> Mac OS X:</dt> |
| 114 <dd>For a specific user: <code>~USERNAME/Library/Application Support/Google/
Chrome/External Extensions/</code><br> |
| 115 For all users: <code>/Library/Application Support/Google/Chrome/External
Extensions/</code> |
| 116 <p>The external extension file for all users is read only if every directory
in the path is owned by the user <code>root</code>, has the group <code>admin</
code> or <code>wheel</code>, and is not world writable. The path must also be f
ree of symbolic links. These restrictions prevent an unprivileged user from cau
sing extensions to be installed for all users. See <a href="#troubleshooting">t
roubleshooting</a> for details.</p> |
| 117 <p class="note"> |
| 118 <b>Note:</b> The above path for all users was added in Chrome 16. Prior ver
sions used a different path:<br/> |
| 119 <code>/Applications/Google Chrome.app/Contents/Extensions/</code> |
| 120 This path was deprecated in version 17. Support was removed in version 20.
Use one of the paths above instead.</p> |
| 121 </dd> |
| 122 |
| 123 <dt> Linux: </dt> |
| 124 <dd> <code>/opt/google/chrome/extensions/</code> <br> |
| 125 </dd> |
| 126 <dd> <code>/usr/share/google-chrome/extensions/</code> <br> |
| 127 <b>Note:</b> Use <code>chmod</code> if necessary |
| 128 to make sure that the <code>aaaaaaaaaabbbbbbbbbbcccccccccc.json</code> files |
| 129 are world-readable. |
| 130 </dd> |
| 131 </dl> |
| 132 </li> |
| 133 |
| 134 <li>If you are installing from a file, specify the extension's location and vers
ion with fields |
| 135 named "external_crx" and "external_version" in the file created above. |
| 136 <p> |
| 137 Example: |
| 138 <pre> |
| 139 { |
| 140 "external_crx": "/home/share/extension.crx", |
| 141 "external_version": "1.0" |
| 142 } |
| 143 </pre> |
| 144 </p> |
| 145 <p class="note"> |
| 146 <b>Note:</b> |
| 147 You need to escape |
| 148 each <code>\</code> character in the location. |
| 149 For example, |
| 150 <code>\\server\share\extension.crx</code> would be |
| 151 <code>"\\\\server\\share\\extension.crx"</code>. |
| 152 </p> |
| 153 <p> |
| 154 <p> |
| 155 If you are installing from an update URL, specify the extension's update URL |
| 156 with field name "external_update_url". |
| 157 </p> |
| 158 Example: |
| 159 <pre>{ |
| 160 "external_update_url": "http://myhost.com/mytestextension/updates.xml" |
| 161 }</pre> |
| 162 <p> |
| 163 If you would like to install extension only for some browser locales, |
| 164 you can list supported locales in field name "supported_locale". Locale may |
| 165 specify parent locale like "en", in this case the extension will be |
| 166 installed for all English locales like "en-US", "en-GB", etc. |
| 167 If another browser locale is selected that is not supported by the extension, |
| 168 the external extensions will be uninstalled. If "supported_locales" list |
| 169 is missing, the extension will be installed for any locale. |
| 170 </p> |
| 171 Example: |
| 172 <pre>{ |
| 173 "external_update_url": "http://myhost.com/mytestextension/updates.xml", |
| 174 "supported_locales": [ "en", "fr", "de" ] |
| 175 }</pre> |
| 176 </li> |
| 177 <li>Save the JSON file. </li> |
| 178 <li>Launch Google Chrome and go to <b>chrome://extensions</b>; |
| 179 you should see the extension listed. </li> |
| 180 </ol> |
| 181 |
| 182 <h3 id="troubleshooting">Troubleshooting Mac OS permissions problems</h3> |
| 183 |
| 184 <p>On Mac OS, the external extensions files for all users are only read if file
system permissions prevent unprivileged users from changing it. If you do not s
ee external extensions installed when Chrome is launched, there may be a permiss
ions problem with the external extensions preferences files. To see if this is
the problem, follow these steps:</p> |
| 185 |
| 186 <ol> |
| 187 <li> Launch the Console program. You can find it under /Applications/Utilitie
s/Console. </li> |
| 188 <li> If the leftmost icon in the Console says "Show Log List", click that icon
. A second column appears at the left. </li> |
| 189 <li> Click "Console Messages" in the left pane. </li> |
| 190 <li> Search for the string <b>Can not read external extensions</b>. If there
is a problem reading the external extensions files, you will see an error messag
e. Look for another error message directly above it, which should explain the i
ssue. For example, if you see the following error: |
| 191 "Path /Library/Application Support/Google/Chrome is owned by the wrong grou
p", you need to use <code>chgrp</code> or the Finder's Get Info dialog to change
the directory's group owner to the Administrator group.</li> |
| 192 <li> After fixing the issue, relaunch Chrome. Test that the external extensio
n is now installed. It is possible that one permissions error keeps Chrome from
detecting a second error. If the external extension was not installed, repeat
these steps until you do not see an error in the Console application. |
| 193 </ol> |
| 194 |
| 195 <h2 id="registry">Using the Windows registry</h2> |
| 196 |
| 197 <ol> |
| 198 <li>Make the <code>.crx</code> extension file available |
| 199 to the machine you want to install the extension on. |
| 200 (Copy it to a local directory or to a network share — |
| 201 for example, <code>\\server\share\extension.crx</code>.) |
| 202 </li> |
| 203 <li>Find or create the following key in the |
| 204 registry: |
| 205 <ul> |
| 206 <li> 32-bit Windows: <code>HKEY_LOCAL_MACHINE\Software\Google\Chrome\Extension
s</code> </li> |
| 207 <li> 64-bit Windows: <code>HKEY_LOCAL_MACHINE\Software\Wow6432Node\Google\Chro
me\Extensions</code> </li> |
| 208 </ul> |
| 209 </li> |
| 210 |
| 211 <li>Create a new key (folder) |
| 212 under the <b>Extensions</b> key with the |
| 213 same name as the ID of your extension |
| 214 (for example, <code>aaaaaaaaaabbbbbbbbbbcccccccccc</code>). |
| 215 </li> |
| 216 <li>Create two string values (<code>REG_SZ</code>) named "path" and "version", |
| 217 and set them to the extension's location and version. |
| 218 For example: |
| 219 <ul> |
| 220 <li>path: <code>\\server\share\extension.crx</code> </li> |
| 221 <li>version: <code>1.0</code> </li> |
| 222 </ul> |
| 223 </li> |
| 224 <li>Launch the browser and go to |
| 225 <b>chrome://extensions</b>; you should |
| 226 see the extension listed. </li> |
| 227 </ol> |
| 228 |
| 229 <h2 id="updating">Updating and uninstalling</h2> |
| 230 |
| 231 <p>Google Chrome scans the metadata entries |
| 232 in the preferences and registry |
| 233 each time the browser starts, and makes |
| 234 any necessary changes to the installed |
| 235 external extensions. </p> |
| 236 |
| 237 <p>To update your extension to a new version, |
| 238 update the file, and then update the version |
| 239 in the preferences or registry. </p> |
| 240 |
| 241 <p>To uninstall your extension |
| 242 (for example, if your software is uninstalled), |
| 243 remove your preference file (aaaaaaaaaabbbbbbbbbbcccccccccc.json) |
| 244 or the metadata from the registry. </p> |
| 245 |
| 246 <h2 id="faq">FAQ</h2> |
| 247 |
| 248 <p> |
| 249 This section answers common questions about external extensions. |
| 250 </p> |
| 251 |
| 252 <br> |
| 253 |
| 254 <p><b>Can I specify a URL as a path to the external extension?</b> </p> |
| 255 <p>Yes, if you use a <a href="#preferences">preferences JSON</a> file. The |
| 256 extension must be hosted as explained in <a href="hosting.html">hosting</a>. |
| 257 Use the "external_update_url" property to point to an |
| 258 <a href="autoupdate.html#H2-2">update manifest</a> that has the URL for your |
| 259 extension.</p> |
| 260 |
| 261 <br> |
| 262 |
| 263 <p><b>What are some common mistakes when installing with the preferences |
| 264 file?</b></p> |
| 265 <ul> |
| 266 <li> |
| 267 Not specifying the same id/version |
| 268 as the one listed in the <code>.crx</code> </li> |
| 269 <li> |
| 270 The .json file (<code>aaaaaaaaaabbbbbbbbbbcccccccccc.json</code>) is in |
| 271 the wrong location or the ID specified does not match the extension ID. |
| 272 <li> |
| 273 Syntax error in JSON file |
| 274 (forgetting to separate entries with comma or |
| 275 leaving a trailing comma somewhere) </li> |
| 276 <li> |
| 277 JSON file entry points to the wrong path |
| 278 to the <code>.crx</code> (or path specified but no filename) </li> |
| 279 <li> |
| 280 Backslashes in UNC path not escaped |
| 281 (for example, <code>"\\server\share\file"</code> is wrong; |
| 282 it should be <code>"\\\\server\\share\\extension"</code>) </li> |
| 283 <li> |
| 284 Permissions problems on a network share </li> |
| 285 </ul> |
| 286 |
| 287 <br> |
| 288 |
| 289 <p><b>What are some common mistakes when installing with the registry?</b> </p> |
| 290 <ul> |
| 291 <li>Not specifying the same id/version |
| 292 as the one listed in the <code>.crx</code> </li> |
| 293 <li>Key created in the wrong location in the registry </li> |
| 294 <li>Registry entry points to the wrong path to the <code>.crx</code> file |
| 295 (or path specified but no filename) </li> |
| 296 <li>Permissions problems on a network share </li> |
| 297 </ul> |
| 298 |
| 299 <br> |
| 300 |
| 301 <p><b>What if the user uninstalls the extension?</b> </p> |
| 302 <p>If the user uninstalls the extension through the UI, it will no |
| 303 longer be installed or updated on each startup. In other words, the |
| 304 external extension is blacklisted. </p> |
| 305 |
| 306 <br> |
| 307 |
| 308 <p><b>How do I get off the blacklist?</b> </p> |
| 309 <p>If the user uninstalls your extension, you should respect that |
| 310 decision. However, if you (the developer) accidentally uninstalled |
| 311 your extension through the UI, |
| 312 you can remove the blacklist tag |
| 313 by installing the extension normally |
| 314 through the UI, and then uninstalling it. </p> |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 10832042:
Extensions Docs Server: Doc conversion script (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src