Google+ Hangouts API

Writing Hangout Apps

Follow these steps to write a Hangout app or extension. This page uses the term "app" to refer to both.

You write Hangout apps using standard HTML, JavaScript, and CSS. An app can additionally communicate with any server APIs as necessary, but that is beyond this scope of this document.

The starter app is a simple skeleton that you can use as the basis for your own app, or look at any of the other samples on that page. Follow the instructions given in the README.txt files in the downloads.

Three important aspects of writing an app are: Gadget XML, Application state, and Events.

Gadget XML

A Hangout app is represented by an XML file that contains your HTML, JavaScript and CSS code:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Your App Name">
    <Require feature="rpc"/>
    <Require feature="views"/>
  </ModulePrefs>
  <Content type="html">
    <![CDATA[
      <script src="//plus.google.com/hangouts/_/api/v1/hangout.js"></script>
      <!-- Your application code -->
    ]]>
  </Content>
</Module>

NOTE: To access API features that are available only in the Developer channel, use the URL in this script in place of the above URL:
<script src="//plus.google.com/hangouts/_/api/dev/hangout.js"></script>

Your XML file should follow the example above, substituting your application name and code. Make sure to include the "rpc" feature in the ModulePrefs section as shown above. Include the "views" feature if you would like to pass data to your app.

Your application code should consist of standard HTML, JavaScript, and CSS. When loaded in a Hangout, the contents of the Content element will be loaded inside of an iframe inside the Hangout. By including the hangout.js file, your application will have access to the Hangouts JavaScript API. You can load some or all of your application's JavaScript and CSS from external files using standard script and link HTML elements.

Your application's XML file must be published at a publicly accessible URL so that it can be fetched by Google's servers. Any external JavaScript and CSS files do not necessarily need to be hosted at public URLs, but they do need to be accessible by the browsers of the Hangout participants.

Application state

During a Hangout session, a single state object is shared across every application instance in the Hangout. The shared state can contain whatever data your application needs, such as the leader of a game and their score:

{
  'leader': participantId,
  'highScore': '112358132134'
}

For a game of chess, you might store the board state as an object:

{
  'chessBoard': JSON.stringify(yourChessBoardObject),
  'currentMove': participantId
}

Application state is accessed and managed using functions in the gapi.hangout.data namespace.

Events

The Hangouts API includes many events which can be used by an application to trigger certain actions. Register a callback function to be called when a certain event occurs using one of the on*.add functions. Events include: the API is ready, the app is visible, participants have joined, the mic is muted, the volume has changed, the shared state has changed, a notice has displayed, and others. Remove a registered event callback using the matching on*.remove function.

For example, the following code demonstrates registering callback functions for two different events: when the state changes and when participants join or leave the Hangout.

var onStateChange = function(eventObj) {
  for (var i = 0; i < eventObj.addedKeys.length; ++i) {
    foo(eventObj.addedKeys[i].key,
        eventObj.addedKeys[i].value,
        eventObj.addedKeys[i].timestamp);
  }
  for (var j = 0; j < eventObj.removedKeys.length; ++j) {
    bar(eventObj.removedKeys[j]);
  }
  state_ = eventObj.state;
  metadata_ = eventObj.metadata;
};
gapi.hangout.data.onStateChanged.add(onStateChange);

var onParticipantsChange = function(eventObj) {
  participants_ = eventObj.participants;
};

gapi.hangout.onParticipantsChanged.add(onParticipantsChange);

The full list of events is documented throughout the API Reference.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.