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