Chrome Frame: Developer Guide

Quick links

Other sites

Except as otherwise noted, the content of this page is licensed under a Creative Commons Attribution 2.5 license, and examples are licensed under the BSD License.

The Chromium OS designs and code are preliminary. Expect them to evolve.

For Developers‎ > ‎How-Tos‎ > ‎

Contents
1 About This Document
2 Making Your Pages Work With Google Chrome Frame
3 Detecting Google Chrome Frame and Prompting to Install
3.1 CFInstall.check() Options
3.2 CFInstall Examples
4 Debugging Tools
5 Testing Your Sites
5.1 Chrome Frame as a default renderer
5.2 Chrome Frame as a closed container
5.3 Troubleshooting installation issues

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.

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=8,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.

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. 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

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

Version 7.0 onwards - Current Stable, Beta and Dev channels:

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!]

Before Version 7.0:

You can use the Windows Registry to force a URL to be loaded in GCF. To achieve this, add an entry with a pattern or full URL for the pages/websites that you want to always be rendered in GCF. For example:

HKCU
Software
Google
ChromeFrame OptInURLs *chromium.org* http://example.mywebsite.net/*

Note: forcing websites into GCF with these techniques may lead to unexpected behavior. GCF will fetch URLs using the host browser's network stack, so the web site will send content intended for the host browser. That may not always work well if rendered in GCF. By default, GCF uses Internet Explorer's network stack to fetch url requests. This ensures the user sees only one view of cookies, history, SSL state, and so on. To turn this off, add a DWORD value UseChromeNetworking=0 under HKCU\Software\Google\ChromeFrame.

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.

Please browse Google Chrome Frame user forums on further help in understanding install errors or post a new question there.

Nov	DEC	Jan
	04
2009	2010	2011