For Developers‎ > ‎How-Tos‎ > ‎

Chrome Frame: Developer Guide

Google Chrome Frame is no longer supported and retired as of February 25, 2014. For guidance on what you need to know as a developer or IT administrator, please read our developer FAQs for Chrome Frame.



About This Document

This document is for web developers who want their pages to work with Google Chrome Frame (aka, GCF). In most cases, making your pages work with GCF is trivial: you just add a single tag to the page. This simple process is described in the next section. The rest of the document is devoted to advanced issues and options.

In short, if your page works in the Google Chrome browser, it'll work in GCF.   For more information check out FAQ. 

Developer Guide

Making Your Pages Work With Google Chrome Frame

Making your pages work with GCF is easy. Just add this tag to the top of the page:

<meta http-equiv="X-UA-Compatible" content="chrome=1">

That's it! Users running Internet Explorer with GCF installed will automatically have pages that include this tag rendered by GCF.

For many sites, adding a tag to every page may be cumbersome, so GCF also supports detection through an HTTP header with the same name and value:
X-UA-Compatible: chrome=1

You may recognize the X-UA-Compatible flag as the same mechanism introduced with IE 8 for controlling the rendering engine that IE uses for a particular page. In cases where GCF is not installed, the values can be combined to control IE's rendering behavior:
<meta http-equiv="X-UA-Compatible" content="IE=Edge,chrome=1">

Note that the value for the "IE" parameter must be provided first. Also, please note that no matter where in the order you list the value "chrome=1", GCF will render the page if it is installed. That is to say, the switch to render the page in GCF always takes the highest priority.

To deploy this header site-wide for a site served with Apache, ensure that mod_headers and mod_setenvif are enabled and add the following to your httpd.conf (or appropriate configuration file):
<IfModule mod_setenvif.c>
  <IfModule mod_headers.c>
    BrowserMatch chromeframe gcf
    Header append X-UA-Compatible "chrome=1" env=gcf
  </IfModule>
</IfModule>

For IIS 7.0 and greater, you can set the header in a web.config file with similar syntax:
<configuration>
  <system.webServer>
     <httpProtocol>
        <customHeaders>
           <add name="X-UA-Compatible" value="chrome=1" />
        </customHeaders>
     </httpProtocol>
  </system.webServer>
</configuration>

GCF supports both the meta tag and HTTP header methods of triggering rendering interchangeably, allowing you to choose whichever approach is best for your site. Note also that GCF is best effort, meaning that if you specify the meta tag or header and GCF isn't installed, the page will be rendered in MSIE as normal.

Conditional Google Chrome Frame Activation


Depending on your site's needs, you might only want to use Google Chrome Frame for users with certain versions of IE. The following X-UA-Compatible header values (whether in a meta tag, or in the HTTP headers) provide you with this control:
chrome=1   - Always active
chrome=IE7 - Active for IE major version 7 or lower
chrome=IE8 - Active for IE major version 8 or lower

The following complete example indicates usage of Google Chrome Frame for IE6 users, and otherwise passes the "Edge" parameter to later versions of IE:
<meta http-equiv="X-UA-Compatible" content="IE=Edge,chrome=IE6">

The differences between Chrome and Chrome Frame

There are a few subtle differences between the two. Read up on the details at Differences between Chrome and Chrome Frame.

Detecting Google Chrome Frame and Prompting to Install

GCF reports that it is available by extending the host's User-Agent header with the string chromeframe.  For more information see Chrome Frame User Agent.

You can use server-side detection to look for this token and determine whether GCF can be used for a page. If GCF is present, you can insert the required meta tag; if not, you can redirect users to a page that explains how to install GCF.As an alternative to server-side sniffing, you can use the CFInstall.js script to detect GCF and prompt users to install the plug-in without restarting their browsers. Using the script is straightforward:

<html>
<body>
<script type="text/javascript"
src="http://ajax.googleapis.com/ajax/libs/chrome-frame/1/CFInstall.min.js"></script>

<style>
/*
CSS rules to use for styling the overlay:
.chromeFrameOverlayContent
.chromeFrameOverlayContent iframe
.chromeFrameOverlayCloseBar
.chromeFrameOverlayUnderlay
*/
</style>

<script> // You may want to place these lines inside an onload handler
CFInstall.check({
mode: "overlay",
destination: "http://www.waikiki.com"
});
</script>
</body>
</html>

The document containing the script must include a body tag. In browsers other than Internet Explorer, the call to check() is a no-op. Note that you can't make a local copy of the JavaScript library and use it with a file:// URL - that won't work.In Internet Explorer, check() determines if Chrome Frame is installed. If not, the user is prompted to install it.


You can choose how you want the user to be prompted. By default, check() injects an iframe at the top of the page. This iframe will navigate to a "Please install Google Chrome Frame" page hosted by Google. The overlay mode specified in the example ensures that this UI is displayed over other page content in a modal way and gives the user controls to disable the prompt for the site (noted for the future in a cookie).

Once the user prompt is displayed, CFInstall examines the environment periodically to determine if the plug-in has finished installing. If it has, the browser is redirected to the destination URL. If no destination is provided, the current page is simply refreshed when GCF is detected. If the page was served with either the meta tag or HTTP header, the refreshed page will then render in GCF and the subsequent call to check() will not trigger the prompt.

CFInstall.check() Options

The CFInstall.check method has many more options. You can specify:
  • mode: optional
    How the user should be prompted when GCF is missing. Defaults to a value of inline that puts an iframe in the document that points to the value of url. If a value for node is specified this will control where the iframe is placed, else it will appear as the first child of the doucment's body element. If mode is set to overlay (recommended), an in-page dialog is displayed that floats over page content. If mode is popup, then url is opened in a new (popup) window. It's recommended that you only use a value of popup when calling check() from a user action, for instance the onclick handler of a button element else popup blocking software may defeat the check.
  • url: optional
    Defaults to "http://google.com/chromeframe". Set this to change the URL that the prompt (either inline or in a popup) will navigate to. You might use this if you're using GCF on an intranet or closed environment and you want to prompt users to install from an alternate location.
  • destination: optional
    The URL to navigate to once CFInstall detects that GCF has been installed.
  • node: optional
    The ID or reference to an element that will contain the iframe prompt. If no node is provided, the prompt iframe will be inserted at the top of the document.
  • onmissing: optional
    Function to be called when GCF is missing.
  • preventPrompt: optional
    Boolean, defaults to false, which allows you to disable the default prompting mechanism. Use in conjunction with onmissing to implement your own prompt.
  • oninstall: optional
    Function that will be called when GCF is first detected after an install prompt is displayed.
  • preventInstallDetection: optional
    Boolean, defaults to false. Set this to true to prevent CFInstall from checking whether GCF has been installed. Use this to prevent redirection.
  • cssText: optional
    Style properties to apply to the prompt iframe when mode is inline.
  • className: optional
    CSS classes to apply to the prompt iframe when mode is inline.

CFInstall Examples

Using the node parameter with an inline prompt to place the prompt iframe in the page and using CSS to style the iframe, reloads the current page when install finishes:
<html>
<body>
<!--[if IE]>
<script type="text/javascript"
src="http://ajax.googleapis.com/ajax/libs/chrome-frame/1/CFInstall.min.js"></script>
<style> .chromeFrameInstallDefaultStyle { width: 100%; /* default is 800px */ border: 5px solid blue; } </style>
<div id="prompt">
<!-- if IE without GCF, prompt goes here -->
</div>  
<script> // The conditional ensures that this code will only execute in IE, // Therefore we can use the IE-specific attachEvent without worry window.attachEvent("onload", function() {
 
CFInstall.check({
mode: "inline", // the default node: "prompt"
  }); });
</script> <![endif]-->
</body>
</html>

Note the use of the IE-specific conditional comment syntax. This syntax prevents the code inside it from being visible to non-IE browsers. This avoids fetching the CFInstall script and running the checks on browsers that don't need them, speeding up your pages. Notably, if this page is served with the GCF meta tag or header and the page renders using GCF, the conditional comments will also be ignored, meaning that it's safe to wrap CFInstall-specific code in conditional comments.  

Easier method to enable Chrome Frame for specific versions of Internet Explorer is explained in the FAQ: 

Screenshot of prompt

Here is how the prompt looks in mode:"overlay":

Debugging Tools

You can use the Web Inspector in GCF just as you would in the Google Chrome browser. To use it, right-click and choose "Inspect Element". Logging is available via the console.log method, and you can set breakpoints and inspect network activity.

Testing Your Sites

To make your pages work with GCF, you should use the method of inserting a meta tag, as described earlier. There are other ways of invoking GCF. These techniques are useful for testing but are turned off by default. GCF provides a fast testing and prototyping shortcut that's especially useful when you can't modify the page you want to test. To use this method, just navigate to the URL prepended with "gcf:". Note that this prefix is in addition to any other URL scheme. For example, to see Gmail in GCF, go to Internet Explorer and navigate to:
gcf:http://gmail.com

You must use both the gcf: and http: prefixes. To enable this testing-only feature, open regedit.exe and add a DWORD value 
AllowUnsafeURLs=1 under HKCU\Software\Google\ChromeFrame.  By default only gcf:about:blank and gcf:about:version are allowed.

In addition to the above, you can use the Windows Registry to force a URL to be loaded in GCF or make all URLs load in GCF by default. 


Chrome Frame as a default renderer


You can use the Windows Registry or better yet Group Policy to force a URL to be loaded in GCF or make all URLs load in GCF by default.  GCF supports two lists for this purpose and a flag to switch between which one is active.  The flag is named IsDefaultRenderer, a REG_DWORD type value, and can be set to either 0 or 1:

HKCU
Software
Google
ChromeFrame IsDefaultRenderer [0=All documents are by default rendered by the host browser (default). 1=All documents are rendered by GCF]

When GCF is the default renderer, Internet Explorer will send Chrome's User Agent string (except in cases where a URL is configured to load in IE, see below). This will make it appear like the request is coming from Chrome and it's not necessary for a site to include a meta tag. Depending on the setting of this value, GCF supports a list of exceptions.  If IsDefaultRenderer is set to 0, this list (RenderInGcfUrls) contains patterns of URLs that should be rendered in GCF.  Note that the URLs are registry values (and not sub-keys):
HKCU
Software
Google
ChromeFrame RenderInGcfUrls
*google.com* [string value name is the pattern to match, assigned value is not used]
*yahoo.com/mail* [use simple pattern, no regexp matching]
* ['*' means load everything!]

If IsDefaultRenderer is set to 1, the other list (this time RenderInHostUrls) contains patterns of URLs that should be rendered in the host browser and not GCF.  Again, note that the URLs are registry values (and not sub-keys):

HKCU
Software
Google
ChromeFrame RenderInHostUrls
*google.com* [string value name is the pattern to match, assigned value is not used]
*yahoo.com/mail* [use simple pattern, no regexp matching]
* ['*' means load everything!]


Chrome Frame as a closed container

GCF sends all top level navigation to Internet Explorer. This is to allow content to load other links in the host browser. This feature can be turned off by adding a DWORD value HandleTopLevelRequests=0 under HKCU\Software\Google\ChromeFrame.  In this case all the subsequent top level navigations will remain inside Chrome Frame whether they have a meta tag or not.

Troubleshooting installation issues

If Google Chrome Frame installation is failing, it's possible to collect an install log using MSI installer available to download at http://www.google.com/chromeframe/eula.html?msi=true. After downloading this:

  1. Uninstall Chrome Frame if it is there in 'Add Remove Programs'.
  2. Re-install using the MSI, by running this command from a command prompt:  "msiexec.exe /i GoogleChromeframeStandaloneEnterprise.msi /l*v install.log" . The /l*v parameter will cause a detailed installer log to be generated. Inspect the generated install.log file for install failures.
  3. After installing, you should have a file called chrome_frame_installer.log in your temp directory (you can get to it by doing Start -> Run and then typing %TEMP% in the box that appears).  If install.log does not have any significant errors, look for failures in chrome_frame_installer.log.

Further Troubleshooting

If Chrome Frame is installed successfully but does not work, please use this link for further diagnosis: http://www.chromium.org/developers/diagnostics/gcf_troubleshooting


Further Reading

Check out this article on html5rocks.com for more information on Google Chrome Frame: http://www.html5rocks.com/en/tutorials/google-chrome-frame/



Asking for help


Variety of developer and end user issues are addressed on Google Chrome Frame user forum.  This forum is actively answered by Chrome Frame engineers. If you don't find the information you are looking for, post a new question there.

Log a bug using Google Chrome Frame bug tracker. Before you file any bug, please search existing bugs. It’s likely that a solution is waiting for you.  If you find that the bug is already there, feel free to star it so you can find it later and indicate to us that another person is interested in its resolution.

Using early access channels of GCF

You can install early access channels for testing: beta channel or dev channel.

Chrome Frame for Administrators


Chrome Frame supports a number of features useful to systems administrators seeking to deploy and manage Chrome Frame. See the Chrome Frame Administrators Guide for more details.