Other Deployment Options

Contents

1. Before you begin
   1. h3Name
2. Using a preferences file
   1. Troubleshooting Mac OS permissions problems
3. Using the Windows registry
   1. h3Name
4. Updating and uninstalling
   1. h3Name
5. FAQ
   1. h3Name
6. API reference
   1. Properties
      1. propertyName
   2. Methods
      1. methodName
   3. Events
      1. eventName
   4. Types
      1. id

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

• 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.
• A network admin wants to install the same extensions throughout the company.

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

• Using a preferences JSON file
• Using the Windows registry (Windows only)

Both ways support installing an extension from a .crx extension file on the user's computer. The preferences JSON file also supports installing an extension hosted at an update URL. See hosting for details on hosting an extension.

Before you begin

First, package a .crx file and make sure that it installs successfully.

If you wish to install from an update URL, ensure that the extension is properly hosted.

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

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

The following examples assume the version is 1.0 and the ID is aaaaaaaaaabbbbbbbbbbcccccccccc.

Using a preferences file

Windows note: Until bug 41902 is fixed, you might want to use the Windows registry instead of the preferences file.

1. If you are installing from a file, make the .crx 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, \\server\share\extension.crx or /home/share/extension.crx.)
2. Locate the external_extensions.json file. If the file doesn't exist, create it. The location depends on the operating system.

   Windows:

   chrome_root\Application\chrome_version\Extensions\
   Example: c:\Users\Me\AppData\Local\Google\Chrome\Application\6.0.422.0\Extensions\

   Mac OS X:

   /Library/Application Support/Google/Chrome/External Extensions/

   Note: The external extensions file is read only if every directory in the path is owned by the user root, has the group admin, and is not world readable. The path must also be free of symbolic links. These restrictions prevent an unprivileged user from causing extensions to be installed for all users. See troubleshooting for details.

   Note: The above path was added in Chrome 16. Prior versions used a different path, which is now deprecated: /Applications/Google Chrome.app/Contents/Extensions/ .

   Linux:

   /opt/google/chrome/extensions/
   Note: Use chmod if necessary to make sure that extensions/external_extensions.json is world-readable.

3. Add an entry to external_extensions.json 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:

   {
     "aaaaaaaaaabbbbbbbbbbcccccccccc": {
       "external_crx": "/home/share/extension.crx",
       "external_version": "1.0"
     }
   }

   Note: You need to escape each \ character in the location. For example, \\server\share\extension.crx would be "\\\\server\\share\\extension.crx".

   If you are installing from an update URL, specify the extension's update URL with field name "external_update_url".

   Example:

   {
     "aaaaaaaaaabbbbbbbbbbcccccccccc": {
       "external_update_url": "http://myhost.com/mytestextension/updates.xml"
     }
   }

   If you would like to install extension only for some browser locales, you can list supported locales in field name "supported_locale". Locale may specify parent locale like "en", in this case the extension will be installed for all English locales like "en-US", "en-GB", etc. If another browser locale is selected that is not supported by the extension, the external extensions will be uninstalled. If "supported_locales" list is missing, the extension will be installed for any locale.

   Example:

   {
     "aaaaaaaaaabbbbbbbbbbcccccccccc": {
       "external_update_url": "http://myhost.com/mytestextension/updates.xml",
       "supported_locales": [ "en", "fr", "de" ]
     }
   }

4. Save the JSON file.
5. Launch Google Chrome and go to chrome://extensions; you should see the extension listed.

Troubleshooting Mac OS permissions problems

On Mac OS, if you do not see the external extension installed when Chrome is launched, there may be a permissions problem with the external extensions preferences file. To see if this is the problem, follow these steps:

1. Launch the Console program. You can find it under /Applications/Utilities/Console.
2. If the leftmost icon in the Console says "Show Log List", click that icon. A second column appears at the left.
3. Click "Console Messages" in the left pane.
4. Search for the string Can not read external extensions. If there is a problem reading the external extensions file, you will find an error message. Look for another error message directly above it, which should explain the issue. For example, if you see the following error: "Path /Library/Application Support/Google/Chrome is owned by the wrong group", you need to use chgrp or the Finder's Get Info dialog to change the directory's group owner to the Administrator group.
5. After fixing the issue, relaunch Chrome. Test that the external extension 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.

Using the Windows registry

1. Make the .crx 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, \\server\share\extension.crx.)
2. Find or create the following key in the registry:
   • 32-bit Windows: HKEY_LOCAL_MACHINE\Software\Google\Chrome\Extensions
   • 64-bit Windows: HKEY_LOCAL_MACHINE\Software\Wow6432Node\Google\Chrome\Extensions
3. Create a new key (folder) under the Extensions key with the same name as the ID of your extension (for example, aaaaaaaaaabbbbbbbbbbcccccccccc).
4. Create two string values (REG_SZ) named "path" and "version", and set them to the extension's location and version. For example:
   • path: \\server\share\extension.crx
   • version: 1.0
5. Launch the browser and go to chrome://extensions; you should see the extension listed.

Updating and uninstalling

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.

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

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

FAQ

This section answers common questions about external extensions.

Can I specify a URL as a path to the external extension?

Yes, if you use a preferences JSON file. The extension must be hosted as explained in hosting. Use the "external_update_url" property to point to an update manifest that has the URL for your extension.

What are some common mistakes when installing with the preferences file?

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

What are some common mistakes when installing with the registry?

• Not specifying the same id/version as the one listed in the .crx
• Key created in the wrong location in the registry
• Registry entry points to the wrong path to the .crx file (or path specified but no filename)
• Permissions problems on a network share

What if the user uninstalls the extension?

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.

How do I get off the blacklist?

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.