docs/static/external_extensions.html

<div id="pageData-name" class="pageData">Other Deployment Options</div>
<div id="pageData-showTOC" class="pageData">true</div>

<p>
Usually, users install their own extensions.
But sometimes you might want an extension
to be installed automatically.
Here are two typical cases:
</p>

<ul>
  <li>
    An extension is associated with some other software,
    and the extension should be installed
    whenever the user installs that other software.
    The extension could also be uninstalled
    when the user removes that other software.
  </li>
  <li>
    A network admin wants to install the same extensions
    throughout the company.
  </li>
</ul>

<p>
An extension that's installed automatically is known as an
<em>external extension</em>.
Google Chrome supports two ways of
installing external extensions:
</p>

<ul>
  <li> Using a preferences JSON file </li>
  <li> Using the Windows registry (Windows only) </li>
</ul>

<p>
Both ways support installing an extension from a <code>.crx</code> extension
file on the user's computer.  The preferences JSON file also supports installing
an extension hosted at an
<a href="autoupdate.html#H2-1">update URL</a>.
See <a href="hosting.html">hosting</a> for details on hosting an extension.
</p>

<h2 id="prereqs">Before you begin</h2>

<p>
First, package a
<a href="packaging.html"><code>.crx</code> file</a>
and make sure that it installs successfully.
</p>
<p>
If you wish to install from an
 <a href="autoupdate.html#H2-1">update URL</a>, ensure that the extension
is properly <a href="hosting.html">hosted</a>.
</p>

<p>
Then, before you edit the preferences file or the registry,
make a note of the following:
</p>

<ul>
 <li> The intended <b>location</b> of the extension's <code>.crx</code> file,
        or the update URL from which it is served </li>
 <li> The extension's <b>version</b>
   (from the manifest file or the <b>chrome://extensions</b> page) </li>
 <li> The extension's <b>ID</b>
   (from the <b>chrome://extensions</b> page
   when you've loaded the packed extension) </li>
</ul>

<p>
The following examples assume the version is <code>1.0</code>
and the ID is <code>aaaaaaaaaabbbbbbbbbbcccccccccc</code>.
</p>

<h2 id="preferences">Using a preferences file</h2>

<p class="note">
<b>Windows note:</b>
Until <a href="http://crbug.com/41902">bug 41902</a> is fixed,
you might want to use the <a href="#registry">Windows registry</a>
instead of the preferences file.

</p>

<ol>
<li>If you are installing from a file, make the <code>.crx</code> extension
file available to the machine you want to install the extension on.
(Copy it to a local directory or to a network share for example,
<code>\\server\share\extension.crx</code>
or <code>/home/share/extension.crx</code>.)
</li>
<li>Locate the <code>external_extensions.json</code> file
  under the Google Chrome installation directory.
  If the file doesn't exist, create it.
  The location depends on the operating system.
  <dl>
  <dt> Windows: </dt>
    <dd> <code><em>chrome_root</em>\Application\<em>chrome_version</em>\Extensions\</code>
    <br />
    Example: <code>c:\Users\Me\AppData\Local\Google\Chrome\Application\6.0.422.0\Extensions\</code>
    </dd>
  <dt> Mac OS X: </dt>
    <dd> <code>/Applications/Google Chrome.app/Contents/Extensions/</code> </dd>
  <dt> Linux: </dt>
    <dd> <code>/opt/google/chrome/extensions/</code> <br>
    <b>Note:</b> Use <code>chmod</code> if necessary
    to make sure that <code>extensions/external_extensions.json</code>
    is world-readable.
    </dd>
  </dl>
</li>
<li> Add an entry to <code>external_extensions.json</code>
for your extension's ID.  If you are installing from a file, specify the
extension's location and version with fields named "external_crx" and
"external_version".

Example:
<pre>{
  "aaaaaaaaaabbbbbbbbbbcccccccccc": {
    "external_crx": "/home/share/extension.crx",
    "external_version": "1.0"
  }
}</pre>

<p class="note">
<b>Note:</b>
You need to escape
each <code>\</code> character in the location.
For example,
<code>\\server\share\extension.crx</code> would be
<code>"\\\\server\\share\\extension.crx"</code>.
</p>
<p>
If you are installing from an update URL, specify the extension's update URL
with field name "external_update_url".
</p>
Example:
<pre>{
  "aaaaaaaaaabbbbbbbbbbcccccccccc": {
    "external_update_url": "http://myhost.com/mytestextension/updates.xml"
  }
}</pre>
</li>

<li>Save the JSON file. </li>
<li>Launch Google Chrome and go to <b>chrome://extensions</b>;
you should see the extension listed. </li>
</ol>

<h2 id="registry">Using the Windows registry</h2>

<ol>
<li>Make the <code>.crx</code> extension file available
to the machine you want to install the extension on.
(Copy it to a local directory or to a network share &mdash;
for example, <code>\\server\share\extension.crx</code>.)
</li>
<li>Find or create the following key in the
registry:
<ul>
  <li> 32-bit Windows: <code>HKEY_LOCAL_MACHINE\Software\Google\Chrome\Extensions</code> </li>
  <li> 64-bit Windows: <code>HKEY_LOCAL_MACHINE\Software\Wow6432Node\Google\Chrome\Extensions</code> </li>
</ul>
</li>

<li>Create a new key (folder)
under the <b>Extensions</b> key with the
same name as the ID of your extension
(for example, <code>aaaaaaaaaabbbbbbbbbbcccccccccc</code>).
</li>
<li>Create two string values (<code>REG_SZ</code>) named "path" and "version",
  and set them to the extension's location and version.
  For example:
<ul>
  <li>path: <code>\\server\share\extension.crx</code> </li>
  <li>version: <code>1.0</code> </li>
</ul>
</li>
<li>Launch the browser and go to
<b>chrome://extensions</b>; you should
see the extension listed. </li>
</ol>

<h2 id="updating">Updating and uninstalling</h2>

<p>Google Chrome scans the metadata entries
in the preferences and registry
each time the browser starts, and makes
any necessary changes to the installed
external extensions. </p>

<p>To update your extension to a new version,
update the file, and then update the version
in the preferences or registry. </p>

<p>To uninstall your extension
(for example, if your software is uninstalled),
remove the metadata from the preferences file
or registry. </p>

<h2 id="faq">FAQ</h2>

<p>
This section answers common questions about external extensions.
</p>

<br>

<p><b>Can I specify a URL as a path to the external extension?</b> </p>
<p>Yes, if you host the extension as explained in
<a href="hosting.html">hosting</a>.
</p>

<br>

<p><b>What are some common mistakes when installing with the preferences
file?</b></p>
<ul>
  <li>
    Not specifying the same id/version
    as the one listed in the <code>.crx</code> </li>
  <li>
    <code>external_extensions.json</code> is in the wrong location </li>
  <li>
    Syntax error in JSON file
    (forgetting to separate entries with comma or
    leaving a trailing comma somewhere) </li>
  <li>
    Extra curly brackets around the top level dictionary </li>
  <li>
    JSON file entry points to the wrong path
    to the <code>.crx</code> (or path specified but no filename) </li>
  <li>
    Backslashes in UNC path not escaped
    (for example, <code>"\\server\share\file"</code> is wrong;
    it should be <code>"\\\\server\\share\\extension"</code>) </li>
  <li>
    Permissions problems on a network share </li>
</ul>

<br>

<p><b>What are some common mistakes when installing with the registry?</b> </p>
<ul>
  <li>Not specifying the same id/version
    as the one listed in the <code>.crx</code> </li>
  <li>Key created in the wrong location in the registry </li>
  <li>Registry entry points to the wrong path to the <code>.crx</code> file
    (or path specified but no filename) </li>
  <li>Permissions problems on a network share </li>
</ul>

<br>

<p><b>What if the user uninstalls the extension?</b> </p>
<p>If the user uninstalls the extension through the UI, it will no
longer be installed or updated on each startup. In other words, the
external extension is blacklisted. </p>

<br>

<p><b>How do I get off the blacklist?</b> </p>
<p>If the user uninstalls your extension, you should respect that
decision. However, if you (the developer) accidentally uninstalled
your extension through the UI,
you can remove the blacklist tag
by installing the extension normally
through the UI, and then uninstalling it. </p>