Important: The Google+ API for Hangouts is no longer supported. Learn more

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.

Create a Google API Console project for your app

After you've published your Hangout gadget XML file, you must create a Google API Console project, an OAuth 2.0 client ID, and register your JavaScript origins, and enter the URL for your Hangout gadget XML file.

  1. Go to the Google API Console .
  2. From the project drop-down, select an existing project , or create a new one by selecting Create a new project.
  3. Enable the Google+ Hangouts API service:
    1. In the list of Google APIs, search for the Google+ Hangouts API service.
    2. Select Google+ Hangouts API from the results list.
    3. Press the Enable API button. Wait for the API to be enabled.
    This action adds the service to the Enabled APIs tab, which you can access by selecting APIs & Services on the left menu. You can turn off the Google Cloud services if you don't need them. Enable any other APIs that your app requires.
  4. In the sidebar under "APIs & Services", select Credentials, then select the OAuth consent screen tab.
    1. Choose an Email Address, specify a Product Name, and press Save.
  5. Configure the API:
    1. In the left sidebar, select APIs & Services and then select the Enabled APIs tab.
    2. To the right of the Google+ Hangouts API service name, press the gear icon .
    3. In the Application URL field, enter the URL where you publish your Hangout gadget XML file.
    4. Fill out other information requested on that page.
    5. Press Save.

You can then run your app privately, share your private apps with people outside your team, or publish your app for anyone to use.

Running your app privately

Before your app is marked as public in the Google API Console, any member of your project team may run it privately in any Hangout. Your team members are managed in the Google API Console, under project Permissions. To access, go to Google API Console Permissions, then choose your Hangouts project.

To run the app privately:

  1. Open a Hangout.
  2. Move the mouse pointer to the left edge of the Hangout to reveal the menu, choose the three dots (...), then Add apps. The app picker appears.
  3. Choose the Developer tab.
  4. Select the app that you want to run privately from the list of apps you have registered in the Google API 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 Google API 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 with people outside your team

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 who are not members of your project team will not be able to access the app in other Hangouts they join.

  1. You must create an OAuth 2.0 client ID before you can share an app.
  2. Press the Share app button on a private app to 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.

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, selecting "Websites authorized to access the account", searching for the name of the app, and choosing 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:

  <Require feature="views"/>