Google+ Hangouts API

Running Hangout Apps

After you've written your Hangout app, it's time to actually run it inside of a Hangout. This document walks you through that process.

Publish the app XML

If you haven't done so already, you must publish your Gadget XML file to a publicly accessible URL. Any stable URL will do, such as a repository on Google Project Hosting or an application on Google App Engine.

Note that any external JavaScript or CSS files your Hangout app uses do not necessarily need to be hosted at public URLs. They can be hosted on a private intranet site, for example, as long as the Hangout participants are able to access them from their browser.

Register your app

After you've published your Gadget XML file, you must register your app in the Google APIs Console. Full documentation for using the APIs Console is available at Google APIs Console Help.

Once you have created a project in the APIs Console, activate the "Google+ Hangouts API" from the All Services pane. Once activated, a new Hangouts pane will be available from the sidebar. This page will allow you to enter the URL for your Gadget XML file, as well as to start a new Hangout in the developer sandbox with your app running inside it. Be sure to save our changes.

Running your app in developer sandbox

Start a Hangout in the developer sandbox with your app running in it as follows:

  • Click the Enter a Hangout link at the bottom of the APIs Console.

The developer sandbox is distinguished by the presence of a red "Developer Sandbox: For Testing Purposes Only!" banner along the top.

You can invite people on your project team to view your app in the Hangout. People outside your team will not able able to see your app in the developer sandbox

In the Hangout, you can load another app by either clicking the ... View more apps button in the left-side apps bar, which is also the ... button when the bar is collapsed.

These buttons appear on the Manage Developed Apps bar:

Load app
Opens a dialog box listing all your Hangout applications and extensions you have under development in the APIs Console. Click on an app to unload the currently running app and load a new instance of the selected app without starting a new Hangout. Switching to a different app does not switch it for other participants in the Hangout.
Reload app
Loads and parses the latest version of the Hangout XML file, while preserving the application state. Use this button to pick up new code changes.
Reset app state
Initialized the application state for the currently loaded Hangout app.

When you are ready to make this app public, follow the procedure at Publishing Apps.

Running your app privately

Before your app is marked as public in the APIs console, any member of your project team may run it privately in any Hangout.

To run the app privately:

  1. Open a Hangout.
  2. Choose ... View more apps, then Add App.
  3. Within the app picker, choose the Developer tab. Click the app that you want to run privately from the list of apps you have registered in the APIs console.

The app loads and appears in the active apps list on the left with a special icon ( ) that indicates that it is running as a private app. Only project members of your APIs console team will be able to see the app.

Private apps display a special toolbar at the top, which is labeled Manage Developed Apps. The toolbar contains four buttons, which are useful for debugging your app during development:

Share app
See sharing your private app.
Load app
Reopens the app picker, which allows you to open another public or private app.
Reload app
Loads and parses the latest version of the Hangout XML file, while preserving the application state. Use this button to pick up new code changes.
Reset app state
Re-initializes the application state for the currently loaded Hangout app. This button clears the keys that are stored in the shared state. After resetting the app state, the app behaves as if you started it for the first time.

Sharing your private apps

You can allow the other participants in a Hangout to see and use your private apps for the duration of that Hangout.  Use this option for previewing or beta testing your app with a limited audience.  Participants that are not a member of your project team will not be able to access the app in other Hangouts they join.

Clicking the Share app button on a private app will show the app in the active apps list of all other users. The app's entry will display a special icon ( ) that indicates that the app is a private app. If the user is not a member of your project team, they will need to accept a warning message, but otherwise the app will act as it would normally. You must create an OAuth 2.0 client ID before you can share an app.

When you are ready to make this app fully public, follow the procedure at Publishing Apps.

Permissions and authorization

An app with an OAuth 2.0 client ID will ask participants for permission to run the first time they try to use the app. Once a participant has agreed to these permissions, they won't be asked to agree to it again. A participant can revoke permission to the app by going to the Google Dashboard, clicking "Websites authorized to access the account", searching for the name of the app, and clicking Revoke Access.

To enable the authorization dialog box in development mode, you must create an OAuth 2.0 client ID. All apps available to the public must have an OAuth2 client ID.

Also see I need an OAuth 2.0 access token. How do I get one?

Passing data to the app

You can pass your app an initial set of data by adding the query parameter gd=somevalue. Your app can read this query parameter's value using the following code:

var appData = gadgets.views.getParams()['appData'];

In order to read data passed to your app, make sure you have specifed the "views" feature in the ModulePrefs section of your Gadget XML:

<ModulePrefs>
  <Require feature="views"/>
</ModulePrefs>

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.