Instant Hangouts

Disclaimer: due to Hangouts API changes, this app is no longer supported.

Instant Hangouts lets you easily add Google+ Hangouts to any web page:

<script src='instanthangouts.0.1.0.js' async></script>
<div class='instanthangouts'></div>

which gives you:

The Google+ Hangout Button API is rich but requires a bit of fiddling to get details right. Instant Hangouts is a thin wrapper that handles a bunch of the details for you:

By default we display a Hangout name and information about the participants, rather than just a button to start a new Hangout.
The Google API is loaded asynchronously to keep your pages fast
Configuration is very simple: just add attributes to your <div>.

How it works

You serve instanthangouts.0.1.0.js. Then, you put the following HTML into your page where you want the Hangout to appear:

<script src='instanthangouts.0.1.0.js' async></script>
<div class='instanthangouts'></div>

If you want more than one Hangout on your page, add additional <div>s. You only need our script once:

<script src='instanthangouts.0.1.0.js' async></script>
<div class='instanthangouts'></div>
<div class='instanthangouts'></div>

Our script inserts a <script> tag that loads the Google+ Hangout Button API. We take care of loading the script asynchronously if possible so your pages don't wait until they've downloaded the Google API to render.

Our Javascript looks at your page and finds all elements that have class='instanthangouts' on them. We read the attributes of those tags to figure out what arguments to pass to the Google API. See below for the arguments you can put on these elements to configure your Hangouts.

Next, we insert a new <div> inside each element with class='instanthangouts'. We then call the Google API and pass in the arguments we read from the element, rendering the Hangout. This means you can have as many Hangout controls on a page as you want.

Modes

We support two modes: widget and button.

Widget

Widget mode looks like this:

It is used by default, and can be explicitly selected by setting render to hangout in your HTML:

<div class='instanthangouts' render='hangout'></div>

In widget mode, you automatically get room support. Users who join the same room end up in the same Hangout. Rooms are unique to the 3- tuple (publisher_id, room_id, topic) (see Options below). By default we set all of these for you to values that will cause all Hangouts on a given page to have the same room, which is usually what users want.

Button

Button mode looks like this:

It can be selected with the following HTML:

<div class='instanthangouts' render='createhangout'></div>

This is the default mode in the Google+ Hangout API. It has no room support, but allows some options (like creating a Hangout on Air) that the widget does not support. See Options for full details.

You can mix buttons and widgets on the same page.

Options

We support the full Google+ Hangout Button API, with the exception of adding Hangout apps to your page. If you're using a Hangout app, you probably want full control rather than going through an adapter like Instant Hangouts.

All options are set as HTML attributes on your <div class='instanthangouts'> tags. All values are strings.

The full list of options is:

hangout_type: sets the type of the Hangout that will be created in button mode. Ignored in widget mode. See the official docs for possible values.
lang: sets the language. Default is en (English). lang is a global, so only the value on the first <div class='instanthangouts'> is honored.
parsetags: sets how render targets in the DOM are parsed. Default is explicit, meaning no automatic processing is done and all renders must be called via the API. The other option is onload. This does DOM traversal and discovery and is consequently slower. parsetags is global, so only the value on the first <div class='instanthangouts'></div> is honored.
publisher_id: one of the three values that create a distinct room. By default all Hangouts created with Instant Hangouts use the Instant Hangouts publisher_id. You can use your own if you want to be double sure that your organization's rooms won't overlap with another organization's (though by default we use the URL when constructing rooms, which in most cases will be unique to your organization).
render: sets the mode. hangout sets widget mode and createhangout sets button mode. Default is hangout. No effect in button mode.
room_id: one of the three values used to create a distinct room. By default the room_id is room_ plus the URL of the containing page. No effect in button mode.
topic: one of the three values used to create a distinct room. Also, this value is presented to users in the Hangouts UI telling them what the Hangout is about. Default is Instant Hangout. No effect in button mode.
widget_size: width in pixels if mode is button. No effect if mode is widget. Default is 136.
width: width in pixes if mode is widget. No effect if mode is button. Default is 300.

Here is a full example for the HTML you need in widget mode to set all custom options:

<script src='instanthangouts-0.1.0.js' async></script>
<div
    class='instanthangouts'
    lang='fr'
    parsetags='onload'
    publisher_id='112744459749475398119'
    render='hangout'
    room_id='my_room'
    topic='My Topic'
    width='200'></div>

And here is an example of all supported custom fields in button mode:

<script src='instanthangouts-0.1.0.js' async></script>
<div
    class='instanthangouts'
    lang='es'
    parsetags='explicit'
    render='createhangout'
    widget_size='75'></div>

Development

This section covers development of Instant Hangouts. You don't need to read it unless you want to contribute to the project.

We use npm for package management and Node.js for a development server. You should install Node, which comes with npm, in whatever way is best on your system.

Pull down the repo and install dependencies into ./node_modules with

$ git clone https://github.com/google/instant-hangouts.git
$ cd instant-hangouts
$ npm install

You can start up a development server with

$ node scripts/server.js

which runs on http://localhost:8080. If possible, use your hostname rather than localhost during development because the URL is used when constructing rooms. If you use a hostname, you can bring up the test server on multiple machines and log in with multiple accounts to do a real end-to-end test of the Hangout functionality.

We use Grunt to produce two files:

instanthangouts-<version>.uncompiled.js
instanthangouts-<version>.js

<version> is set in package.json. The first file is the source concatenated and wrapped in a closure. The second is a minified version that users embed in their pages. The former is useful to developers because line numbers etc. are preserved in your debugger. When pushing a new version, be sure to update version in package.json and update the script tag in index.html so you generate new versions of these files. You will also want to update the script tags in this document.

When developing, run

$ grunt

to watch your local files and recreate the computed files automatically every time there is a change. This assumes you have installed grunt-cli globally, which is fairly common. If you want to use the local version managed by Instant Hangouts, instead run

$ ./node_modules/grunt-cli/bin/grunt

We use Karma for our test runner. To start:

$ karma start

This will bring up a Chrome window and attach Karma to it. Your test code will be run in that Chrome window. Karma has its own file watcher and reruns tests when either the source, tests, or index.html changes. We use Jasmine for our test framework.