Google+ Platform

Starting Google+ Hangouts with the Hangout button

The Hangout button lets you to launch a Google+ Hangout directly from your site. When you use the button, you can set up the Hangout in a variety of configurations. For example, you can specify Hangout apps that launch along with the Hangout and setup the Hangout as a regular Hangout or a Hangout On Air.

You can customize the Hangout button to meet the needs of your website by modifying the button size, loading the button when the page loads, or selectively showing the button using JavaScript.

Use of the Hangout button is subject to the Buttons Policy.

Getting Started

In general, to render the Hangout button, you include the necessary JavaScript resources for rendering the button and then specify where you want the button in your site's HTML.

There are various ways to render the button demonstrated in this section:

  • Tag markup
  • HTML5 markup
  • JavaScript

Lets start with the simplest case, rendering the button with tag markup.

Render with tag markup

To render using tag markup, include the platform.js script and place the <g:hangout> tag where you want the Hangout button to render.The following example shows a simple example for rendering a button using tag markup.

<script type="text/javascript" src="https://apis.google.com/js/platform.js"></script>
<g:hangout render="createhangout"></g:hangout>

The script must be sourced as https and can be included at any point on the page.

Render with HTML5 markup

As an alternative to tag markup, you can specify the Hangout button using standard HTML5 markup. To use HTML5 markup, include platform.js and set the class used in your HTML element to g-hangout.

The following example shows a simple case for rendering the Hangout button using HTML5 markup.

<script type="text/javascript" src="https://apis.google.com/js/platform.js"></script>
<div class="g-hangout" data-render="createhangout"></div>

Render with JavaScript

By rendering the Hangout button with JavaScript, you can target any element in your page and programmatically render the Hangout button.

To render the Hangout button with JavaScript, first include the JavaScript file:

<script type="text/javascript" src="https://apis.google.com/js/platform.js"></script>

After you include the JavaScript file, you need to specify an HTML container to render as the Hangout button, for example:

<div id="placeholder-div"></div>

Finally, render the button by using gapi.hangout.render():

<script>
gapi.hangout.render('placeholder-div', { 'render': 'createhangout' });
</script>

The first parameter passed to the gapi.hangout.render method accepts the target HTML container used to host the Hangout button. The second parameter is an object that contains the parameters that indicate the app to start, the mode, and other information. For more information, see the Hangout button attributes.

Loading the script asynchronously

For improved page load time, you should load the JavaScript asynchronously. This approach allows the browser to load your page and the JavaScript file in parallel. For the best performance, place the following JavaScript before your </body> tag:

<script type="text/javascript">
  (function() {
    var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
    po.src = 'https://apis.google.com/js/plusone.js?onload=onLoadCallback';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
  })();
</script>

You can use the onload callback when using the asynchronous loading to start the execution of your code after all of the dependencies have loaded.

When you load the JavaScript asynchronously, you must specify script tag parameters differently. Use the following syntax instead:

<script type="text/javascript">
window.___gcfg = {
  lang: 'zh-CN',
  parsetags: 'onload'
};
(function() {
    var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
    po.src = 'https://apis.google.com/js/plusone.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
  })();
</script>

Adding a Hangout app

If you are launching an app along with the Hangout, you must provide the app ID of your Hangout app or extension. Go to the APIs Console, select the Hangouts project you want the button to start, then copy the app ID from the current URL at the top of the browser, like this — it's the number that follows "project:", and will be at least 12 digits long. For example, if the URL is //code.google.com/apis/console/b/0/#project:123456789012, then the app ID is 123456789012.

After you have your app ID, configure the button to launch your app by specifying the application in the JavaScript array of apps

The following code shows you how to render the Hangout button with a Hangout app using HTML5 markup.

<script type="text/javascript" src="https://apis.google.com/js/platform.js"></script>
<div class="g-hangout" data-render="createhangout"
    data-initial_apps="[{ app_id : '184219133185', start_data : 'dQw4w9WgXcQ', 'app_type' : 'ROOM_APP' }]">
</div>

The Examples section has more examples showing you how to load Hangout apps when the user clicks the button.

Hangout button attributes

The Hangout button contains attributes for configuring the button, the apps associated with the button, and attributes that are returned from a callback triggered when the user clicks the button.

Script tag parameters

These parameters are defined within the <script /> element. The parameters control the language and button loading mechanism that are used across the entire web page.

Key Value Default Description
lang language code en-US Sets the language to use for all of the Google+ plugins on the page. For available language code values, see the list of supported language codes and a lang example.
parsetags explicit, onload onload Sets the loading mechanism to use.
onload
All Hangout button on the page are automatically rendered after the page loads. See the asynchronous load example.
explicit
Hangout button are rendered only with explicit calls to gapi.hangout.go or gapi.hangout.render.

When you use the explicit load in conjunction with go and render calls that point to specific containers in your page, you prevent the script from traversing the entire DOM, which can improve button rendering time. See the gapi.hangout.go and gapi.hangout.render examples.

Hangout button parameters

The following parameters are used to initialize the Hangout button. These parameters determine the type of Hangout to create and the apps to launch when the Hangout starts.

Parameter Type Description
render String Specifies how to render the Hangout button. Currently this parameter must have the value ‘createhangout’.
topic String Pre-populates the topic field for Hangouts on Air. Note that users can change the topic of the Hangout after they have joined.
initial_apps Array This array of JavaScript objects specifies the Google+ Hangout apps to launch when a user clicks the Hangout button. Invalid objects and parameters are ignored. The next section, Initial App Parameters, describes the parameters for the members of this array.
hangout_type HangoutType Specifies what type of Hangout should be started. The following values are supported:
normal
(Default) Launch the Hangout app without broadcasting to YouTube or starting a Hangout party.
onair
Launch the Hangout to be broadcast on YouTube as a Hangout On Air.
party
Launch the Hangout app as a Hangout party.
moderated
Launch the Hangout app with Control Room enabled.
widget_size Number Specifies the width of the button. The default value is 136.

Initial app parameters

These parameters specify the applications that are started along with the Google+ Hangout when a user clicks the button. Each application passed in the array of Hangout apps must have these parameters set.

Parameter Type Description
app_id String The identifier for the project, retrieved from the Google APIs console that corresponds to the application this button launches.
start_data String This optional parameter specifies data to be passed to the initial instantiation of the app. Only the first participant to join the application has this value present in the response from gapi.hangout.getStartData. If you want this data to be referenced later, store the data in the shared Hangout state using the gapi.hangout.data methods.
app_type Enum This optional parameter specifies the type of Hangout app created when the user clicks the button. Setting this parameter changes the way that Hangout applications are loaded for the Hangout and its participants. The following values are supported:
LOCAL_APP
Launches the app for only the user who clicks the widget.
ROOM_APP
Launches the app for every participant who joins the Google+ Hangout. The button defaults to this value.

Button sizes

The button can be rendered at various sizes and renders differently when you specify the button is to be rendered as a Hangout On Air. The following table lists example sizes.

Example Type Width Code
A wide Hangout button.
A wide Hangout button.
Hangout 175

<script src="https://apis.google.com/js/platform.js"></script>
<div id="placeholder-rr"></div>
<script>
  gapi.hangout.render('placeholder-rr', {
    'render': 'createhangout',
    'initial_apps': [{'app_id' : '184219133185', 'start_data' : 'dQw4w9WgXcQ', 'app_type' : 'ROOM_APP' }],
    'widget_size': 175
  });
</script>

The default Hangout button.
The default Hangout button.
Hangout 136 (Default)

<script src="https://apis.google.com/js/platform.js"></script>
<div id="placeholder-div1"></div>
<script>
  gapi.hangout.render('placeholder-div1', {
    'render': 'createhangout',
    'initial_apps': [{'app_id' : '184219133185', 'start_data' : 'dQw4w9WgXcQ', 'app_type' : 'ROOM_APP' }]
  });
</script>

A narrow Hangout button.
A narrow Hangout button.
Hangout 72

<script src="https://apis.google.com/js/platform.js"></script>
<div id="placeholder-div2"></div>
<script>
  gapi.hangout.render('placeholder-div2', {
    'render': 'createhangout',
    'initial_apps': [{'app_id' : '184219133185', 'start_data' : 'dQw4w9WgXcQ', 'app_type' : 'ROOM_APP' }],
    'widget_size': 72
  });
</script>

A wide Hangout button with Hangouts on Air enabled.
A wide Hangout button with Hangouts on Air enabled.
Hangout on Air 175

<script src="https://apis.google.com/js/platform.js"></script>
<div id="placeholder-div3"></div>
<script>
  gapi.hangout.render('placeholder-div3', {
    'render': 'createhangout',
    'hangout_type': 'onair',
    'initial_apps': [{'app_id' : '184219133185', 'start_data' : 'dQw4w9WgXcQ', 'app_type' : 'ROOM_APP' }],
    'widget_size': 175
  });
</script>

The default Hangout button with Hangouts on Air enabled.
The default Hangout button with Hangouts On Air enabled.
Hangout on Air 136 (Default)

<script src="https://apis.google.com/js/platform.js"></script>
<div id="placeholder-div4"></div>
<script>
  gapi.hangout.render('placeholder-div4', {
    'topic': 'hats',
    'render': 'createhangout',
    'hangout_type': 'onair',
    'initial_apps': [{'app_id' : '184219133185', 'start_data' : 'dQw4w9WgXcQ', 'app_type' : 'ROOM_APP' }],
  });
</script>

A narrow Hangout button with Hangouts on Air enabled.
A narrow Hangout button with Hangouts on Air enabled.
Hangout on Air 72

<script src="https://apis.google.com/js/platform.js"></script>
<div id="placeholder-div5"></div>
<script>
  gapi.hangout.render('placeholder-div5', {
    'topic': 'cats',
    'render': 'createhangout',
    'hangout_type': 'onair',
    'initial_apps': [{'app_id' : '184219133185', 'start_data' : 'dQw4w9WgXcQ', 'app_type' : 'ROOM_APP' }],
    'widget_size': 72
  });
</script>

Supported languages

If you need to change the language used on the button, provide script tag parameters to configure the button. The following JavaScript code will set the language used on the Hangout Button.

<script type="text/javascript">
    window.___gcfg = {
      lang: 'en-US'
    };
</script>

The following table lists values and languages the button supports.

Language Value
Afrikaans af
Amharic am
Arabic ar
Basque eu
Bengali bn
Bulgarian bg
Catalan ca
Chinese (Hong Kong) zh-HK
Chinese (Simplified) zh-CN
Chinese (Traditional) zh-TW
Croatian hr
Czech cs
Danish da
Dutch nl
English (UK) en-GB
English (US) en-US
Estonian et
Filipino fil
Finnish fi
French fr
French (Canadian) fr-CA
Language Value
Galician gl
German de
Greek el
Gujarati gu
Hebrew iw
Hindi hi
Hungarian hu
Icelandic is
Indonesian id
Italian it
Japanese ja
Kannada kn
Korean ko
Latvian lv
Lithuanian lt
Malay ms
Malayalam ml
Marathi mr
Norwegian no
Persian fa
Polish pl
Language Value
Portuguese (Brazil) pt-BR
Portuguese (Portugal) pt-PT
Romanian ro
Russian ru
Serbian sr
Slovak sk
Slovenian sl
Spanish es
Spanish (Latin America) es-419
Swahili sw
Swedish sv
Tamil ta
Telugu te
Thai th
Turkish tr
Ukrainian uk
Urdu ur
Vietnamese vi
Zulu zu

Examples

The following examples show how to create buttons using the various approaches and configurations.

Basic page

<html>
  <head>
    <title>Hangout button demo: Async load</title>
    <link rel="canonical" href="http://www.example.com" />
    <script type="text/javascript" src="https://apis.google.com/js/platform.js">
    </script>
  </head>
  <body>
    <g:hangout render="createhangout"></g:hangout>
  </body>
</html>

Basic page with the language set

<html>
<head>
  <script type="text/javascript">
      window.___gcfg = {
        lang: 'hi'
      };
  </script>
  <title>Hangout button demo: Setting the Hangout button language</title>
  <link rel="canonical" href="http://www.example.com" />
</head>
<body>
    <script type="text/javascript" src="https://apis.google.com/js/platform.js"></script>
    <g:hangout render="createhangout"></g:hangout>
</body>
</html>

Basic page with a Hangout app

<html>
<head>
<script type="text/javascript">
    <title>Hangout button demo: Setting the Hangout button language</title>
    <link rel="canonical" href="http://www.example.com" />
</script>
</head>
<body>
    <script type="text/javascript" src="https://apis.google.com/js/platform.js"></script>
    <g:hangout render="createhangout"
        initial_apps="[{ app_id : '184219133185', start_data : 'dQw4w9WgXcQ', 'app_type': 'ROOM_APP' }]">
    </g:hangout>
</body>
</html>

Basic page using HTML5 markup

<html>
  <head>
    <title>Hangout button demo: Async load</title>
    <link rel="canonical" href="http://www.example.com" />
    <script type="text/javascript" src="https://apis.google.com/js/platform.js">
    </script>
  </head>
  <body>
    <div class="g-hangout" data-render="createhangout"></div>
  </body>
</html>

Asynchronous load and JavaScript render with a language code

<html>
<head>
    <title>Hangout button demo: Async load</title>
    <link rel="canonical" href="http://www.example.com" />
</head>
<body>
  <div id="placeholder-div"></div>
  <script type="text/javascript">
    window.___gcfg = {
      lang: 'zh-CN'
    };
    (function() {
      var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
      po.src = 'https://apis.google.com/js/platform.js?onload=renderButtons';
      var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
    })();

    function renderButtons(){
      gapi.hangout.render('placeholder-div', {
          'render': 'createhangout',
        });
    }
  </script>
</body>
</html>

Asynchronous load with language code and a Hangout app

<html>
<body>
  <div id="placeholder-div"></div>
</body>
<script>
window.___gcfg = {
  lang: 'fr'
};

(function() {
  var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
  po.src = 'https://apis.google.com/js/platform.js?onload=renderButton';
  var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
})();

function renderButton(){
  gapi.hangout.render('placeholder-div', {
      'render': 'createhangout',
      'initial_apps': [
        { app_id : '184219133185', start_data : 'dQw4w9WgXcQ', 'app_type' : 'ROOM_APP' }
      ]
    });
}
</script>
</html>

Troubleshooting

This section includes resolutions to issues encountered when using the Hangout button.

Button does not render

If you open the console and see the error: Failed to load resource: the server responded with a status of 500 (Internal Server Error)

Ensure that you are specifying how to render the button. For example, the following code will cause this error:

  <script type="text/javascript" src="https://apis.google.com/js/platform.js"></script>
  <g:hangout></g:hangout>

The following example shows how to update this code to correctly render the Hangout button:

  <script type="text/javascript" src="https://apis.google.com/js/platform.js"></script>
  <g:hangout render="createhangout"></g:hangout>

Button renders in the wrong language

You must specify the lang script tag parameter before loading platform.js. The following example will not work because the language is set after loading platform.js:

  <html>
  <head>
  <script type="text/javascript" src="https://apis.google.com/js/platform.js"></script>
  <script type="text/javascript">
      window.___gcfg = {
        lang: 'fr'
      };
  </script>
  </head>
  <body>
      <g:hangout render="createhangout"></g:hangout>
  </body>
  </html>

The following example will correctly set the language:

  <html>
  <head>
  <script type="text/javascript">
      window.___gcfg = {
        lang: 'fr'
      };
  </script>
  <script type="text/javascript" src="https://apis.google.com/js/platform.js"></script>
  </head>
  <body>
      <g:hangout render="createhangout"></g:hangout>
  </body>
  </html>

Google+ Hangout app is not loading

First, make sure that you are specifying a valid app ID, which you can find as described in the Initial app parameters section.

Next, you need to make sure that the JavaScript array of apps is valid, and is in fact an array as opposed to just a JavaScript object. In the following example where there is an issue, a JavaScript object is passed instead of an array which will prevent the app from including the Google+ Hangout app:

  <html>
    <head>
    <script type="text/javascript">
        <title>Hangout button demo: Setting the Hangout button language</title>
        <link rel="canonical" href="http://www.example.com" />
    </script>
    </head>
    <body>
        <script type="text/javascript" src="https://apis.google.com/js/platform.js"></script>
        <g:hangout render="createhangout"
            initial_apps="{ app_id : '184219133185', start_data : 'dQw4w9WgXcQ', 'app_type' : 'LOCAL_APP' }">
        </g:hangout>
    </body>
  </html>

The following example correctly specifies the array of Hangout apps:

  <html>
    <head>
    <script type="text/javascript">
        <title>Hangout button demo: Setting the Hangout button language</title>
        <link rel="canonical" href="http://www.example.com" />
    </script>
    </head>
    <body>
        <script type="text/javascript" src="https://apis.google.com/js/platform.js"></script>
        <g:hangout render="createhangout"
            initial_apps="[{ app_id : '184219133185', start_data : 'dQw4w9WgXcQ', 'app_type' : 'ROOM_APP' }]">
        </g:hangout>
    </body>
  </html>

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.