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

Hangouts API Release Notes - v1.1 and earlier

Note - See the release notes for the latest version of Hangouts API.

For release notes for other Google+ APIs, see Google+ Platform Release Notes.

Hangouts API v1.1

This release introduces the ability for your app to respond to face movements in real time. It also provides a new static image overlay positioned relative to the video feed, new high-rate, low-latency messages, Hangouts on Air support, the ability to enter any OAuth scope, and a few other miscellaneous features.

Face movements

Your app can now respond to facial movements in real time at various points on a face. When participants tilt their head side-to-side, look right and left, or look up and down, your app can react accordingly. This lets your app use a face as a controller, controlling gameplay, for instance. See the sample Face Movement App.

  • onFaceTrackingDataChanged event triggers when the face movement data changes; its event class FaceTrackingData provides the current, real-time positions of points on the face.
  • FaceTrackingFeature now has these new enums that identify points of facial features that can be followed: LEFT_EYEBROW_LEFT, LEFT_EYEBROW_RIGHT, MOUTH_LEFT, MOUTH_CENTER, MOUTH_RIGHT, NOSE_ROOT, RIGHT_EYEBROW_LEFT, and RIGHT_EYEBROW_RIGHT.

Overlay

An Overlay is similar to a FaceTrackingOverlay, but is positioned relative to the video feed rather than to the face. It is visible to all participants and is useful for decorations such as titles, captions, borders, or animations that don't follow face movements.

  • Overlay is an object that controls an image that overlays the video feed, positioned relative to the video feed's center. Create with createOverlay or showOverlay.
  • Overlay methods: getImageResource, getPosition, getRotation, getScale, isVisible, setPosition, setRotation, setScale and setVisible.
  • ScaleReference lets you scale an Overlay relative to the video feed's HEIGHT or WIDTH.

Messages

Messages are useful for sending high-rate data quickly from one participant instance of your app to to other participants' instances of your app. Messages are faster than updating shared state with submitDelta, but are delivered on a best-effort basis where some data can be dropped, so it should only be used for ephemeral data — use shared state to keep your app states in sync. Messages are useful for keeping things such as display of mouse movements quick and responsive in high-activity apps. See the sample Send Message App.

Hangouts on Air

Miscellaneous

  • person objects are now available for all participants in a hangout, not just for app participants. This includes the person fields (id, displayName, image and image.url).
  • isPublic - whether the public has been invited to the hangout. The event onPublicChanged triggers when the public status changes; its event class is PublicChangedEvent.
  • getStartData - gets the data passed in by the gd URL parameter. This data was previously available only with gadgets.views.getParams.

More OAuth 2.0 scopes

Hangouts API v1.0

Promoted the Hangouts API from developer preview to general release, enabling developers to launch their hangout apps for sharing by the entire Google+ community.

Face movements

  • FaceTrackingOverlay.isVisible(): Multiple overlays can now be visible at a time in a single video feed. The restriction that only one overlay can be visible at a time has been relaxed.

Media effects

  • Any app that relies on multiple overlays or other media effects requires version 2.8.5 or later of the Google Talk plugin, which is being updated using the standard upgrade mechanism. You can view the plugin version number at about:plugins in Chrome or Firefox.

Audio

  • Sound(): Many sounds can now be played at a time. The restriction that only one sound can be played at a time has been relaxed.

Hangouts API v0.2

Versions 0.1 and 0.2 are Developer Preview releases.

This release introduces the ability to show a video canvas within an app. It introduces some general convenience functions, removes some displayed participant functions in favor of VideoFeed, and removes the participant highlight functions in favor of setAvatar. It also updates the Developer Preview hangout user interface to the latest look and feel.

Note: Existing apps that point to the v0.1 API will continue to work until we disable that version of the API on February 22, 2012. If you use methods that have been removed from v0.2, you will need to update your code when migrating to that version.

Video classes and functions

Video classes: (in gapi.hangout.layout)

Video functions: (in gapi.hangout.layout)

General convenience functions

Added function to get the Hangout URL:

Changed the behavior of:

  • getHangoutId returns an ID for the hangout. This ID can no longer be used to create the hangout URL — for that, use getHangoutUrl.

Displayed participant functions

Removed the following functions and an event for displaying a participant in the main video area. Instead, we recommend you use a VideoFeed object.

  • gapi.hangout.setDisplayedParticipant function
  • gapi.hangout.getDisplayedParticipant function
  • gapi.hangout.clearDisplayedParticipant function
  • gapi.hangout.onDisplayedParticipantChanged event

Participant highlight functions

Removed the following functions for highlighting a participant. Instead, we recommend you use gapi.hangout.av.setAvatar as replacement functionality. Look through the sample code for an implementation of this use case.

  • gapi.hangout.layout.setParticipantHighlight
  • gapi.hangout.layout.getParticipantHighlight
  • gapi.hangout.layout.clearParticipantHighlight

Hangouts API v0.1 (Dec. 14, 2011)

This release retains the same 0.1 version number as the Nov. 2 release because it is backwards compatible with it. It adds the ability to play sound effects, attach image overlays to faces, add convenience methods for data operations, and logging to the JavaScript console.

Audio and Video Effects APIs

Added ability to play sound effects: gapi.hangout.av.effects.createAudioResource
Added face movement video feed overlay: gapi.hangout.av.effects.createImageResource

Data API convenience methods

Added convenience methods for common data operations:

Data API Rate Limits Increased

Significantly increased the data API rate, with higher short-term bursts allowed.

Improved Developer support

Added logging to the JavaScript console:

  • When API parameter validation fails.
  • When an event handler throws an exception.

Hangouts API v0.1 (Nov. 2, 2011)

New Location for hangout.js

The location of the hangouts.js file has been changed. The new location is:

https://hangoutsapi.talkgadget.google.com/hangouts/api/hangout.js?v=0.1

The old location at hangoutsapi.appspot.com/static/hangout.js is still being served (until November 16, 2011) to prevent current apps from breaking.

Event Pattern Changed

The event pattern has been changed. An event is now an object containing two functions add and remove. The add method adds a callback to be called when the event fires. The callback receives a single event object argument. The event object contains the details of the event.

Participants who have enabled the app, previously referred to as AppParticipants, are now referred to as EnabledParticipants. For example, addAppParticipantsListener is now onEnabledParticipantsChanged.

Events are named on* (such as onApiReady). The corresponding event objects are named *Event (such as ApiReadyEvent) and are declared in the same namespace as their corresponding event.

The new event names and their corresponding objects are:

Event Name Event Object
gapi.hangout.onApiReady gapi.hangout.ApiReadyEvent
gapi.hangout.onParticipantsDisabled gapi.hangout.ParticipantsDisabledEvent
gapi.hangout.onParticipantsEnabled gapi.hangout.ParticipantsEnabledEvent
gapi.hangout.onAppVisible gapi.hangout.AppVisibleEvent
gapi.hangout.onDisplayedParticipantChanged gapi.hangout.DisplayedParticipantChangedEvent
gapi.hangout.onEnabledParticipantsChanged gapi.hangout.EnabledParticipantsChangedEvent
gapi.hangout.onParticipantsAdded gapi.hangout.ParticipantsAddedEvent
gapi.hangout.onParticipantsChanged gapi.hangout.ParticipantsChangedEvent
gapi.hangout.onParticipantsRemoved gapi.hangout.ParticipantsRemovedEvent
gapi.hangout.av.onCameraMute gapi.hangout.av.CameraMuteEvent
gapi.hangout.av.onHasCamera gapi.hangout.av.HasCameraEvent
gapi.hangout.av.onHasMicrophone gapi.hangout.av.HasMicrophoneEvent
gapi.hangout.av.onHasSpeakers gapi.hangout.av.HasSpeakersEvent
gapi.hangout.av.onMicrophoneMute gapi.hangout.av.MicrophoneMuteEvent
gapi.hangout.av.onVolumesChanged gapi.hangout.av.VolumesChangedEvent
gapi.hangout.data.onStateChanged gapi.hangout.data.StateChangedEvent
gapi.hangout.layout.onChatPaneVisible gapi.hangout.layout.ChatPaneVisibleEvent
gapi.hangout.layout.onHasNotice gapi.hangout.layout.HasNoticeEvent

See the updated API reference for details of the members of the event objects.

For example:

  // Events now are named onXXX. Events have 2 members, 'add' and 'remove'.
  gapi.hangout.onApiReady.add(function(eventObj) {
    if (eventObj.isApiReady) {
      initialize();
    }
  });

  function initialize() {
    // Use onXXX.add to sign up for notification of an event
    gapi.hangout.onParticipantsChanged.add(whenParticipantsChange);
  };

  // Event callbacks now all take a single event object
  function whenParticipantsChange(event) {
    // The details of the event are stored in members of the event object.
    int numberOfParticipants = event.participants.length;

    alert('Participants have changed. Hangout has ' +
        numberOfParticipants + ' participants.');

    // Use onXXX.remove to unsubscribe from an event
    gapi.hangout.onParticipantsChanged.remove(whenParticipantsChange);
  }
  

New APIs

Participant.displayIndex

Participants have a new displayIndex field which is the index into the list of participants displayed in the thumbnail images below the application. The left-most participant has a displayIndex of 0.

Participant Audible

We've added audio counterparts to the participant visible API. The new APIs are:

  • gapi.hangout.av.isParticipantAudible
  • gapi.hangout.av.setParticipantAudible
  • gapi.hangout.av.getParticipantAudioLevel
  • gapi.hangout.av.setParticipantAudioLevel

These APIs give the app control over which participants audio streams are audible.

Resetting the Microphone and Camera Mute

The microphone and camera mute states can be controlled both by the API and by the user. We've added methods to restore the microphone and camera mute states to the values most recently set by the user:

  • gapi.hangout.av.clearMicrophoneMute
  • gapi.hangout.av.clearCameraMute
  • gapi.hangout.clearDisplayedParticipant

Person split from Participant

The identifying information for a person has been split into a distinct person object. The person object has the following fields:

Person
id: the unique Google ID of the person
displayName: a name for the person suitable for display to the user
image.url: an url to an image suitable for display to the user

The participant's hangoutId field has been renamed to just id. All Hangout API's that identify a participant use the participant's id, rather than the confusingly named hangoutId.

Notice API moved to gapi.hangout.layout Namespace

The notice APIs have been moved from the gapi.hangout namespace to the gapi.hangout.layout namespace.

API Renames

Some of the APIs have been renamed for clarity and consistency.

Old name New name Comment
hangoutId id All Hangout API's that identify a participant use the participant's id, rather than the confusingly named hangoutId.
ActiveSpeaker DisplayedParticipant To indicate the participant displayed in the main video area of the hangout.
AppParticipants ParticipantsEnabled and ParticipantsDisabled AddParticipants was used to represent participants with the application enabled and running in the hangout.

Send feedback about...

Google+ Hangouts API
Google+ Hangouts API