Google+ JavaScript API

The following methods and classes are useful when working with the Google+ plugins, Google+ Sign-In button and the HTTP APIs. The full Google JavaScript Client Library reference contains additional methods and classes.

Loading the JavaScript API

For most of the plugins, your site only needs to include the Google+ JavaScript API (platform.js). The Google+ JavaScript API can be loaded with the following script tag:

<script src="https://apis.google.com/js/platform.js" async defer>
</script>

Deferred execution with onLoad and script tag parameters

Use the onload callback to execute widget code after all dependencies have loaded.

To specify script tag parameters, use the following syntax:

<script >
  window.___gcfg = {
    lang: 'zh-CN',
    parsetags: 'onload'
  };
</script>
<script src="https://apis.google.com/js/platform.js" async defer></script>

Specifying an onload callback

You can define an onload callback that will execute when the script has successfully loaded. This callback can be helpful to ensure that your scripts run at the appropriate time.

<script src="https://apis.google.com/js/platform.js?onload=onLoadCallback" async defer>
</script>

When you load the script synchronously, your onload callback function must be defined prior to loading the script above.

Specifying the publisher ID

When you use the mobile web recommendations, you must pass your Google+ Page ID to the JavaScript API by using the publisherid query parameter:

<script src="https://apis.google.com/js/platform.js?publisherid={{PAGE_ID}}" async defer>
</script>

You would replace {{PAGE_ID}} with the numeric ID that can be found in the URL to your Google+ Page. For example:

https://apis.google.com/js/platform.js?publisherid=110967630299632321627

If your Google+ Page uses a custom URL, you can find the Google+ Page ID by inspecting one of the Google+ Page's posts. You can copy the link from the time stamp on the post to extract the numeric ID:

Configuration options

You can specify options for how to handle the loading of plugins and the language to use for the plugins. These options must be defined within a <script /> element prior to loading the JavaScript API or be defined within the same <script /> element that loads the JavaScript API, for example:

<script>
  // Defines the configuration options, these must be set before you load
  // the platform.js file.
  window.___gcfg = {
    lang: 'en-US',
    parsetags: 'explicit'    //    DS?: can the onload param be removed from the line below and added here?
                             //         E.g., 'explicit','onload'
  }
</script>
<script src="https://apis.google.com/js/platform.js?onload=onLoadCallback" async defer></script>

lang - type: string

Sets the language to use for all of the plugins on the page. See the full list of supported languages.

parsetags - type: string

Sets the loading mechanism to use.

• onload: All plugins on the page are automatically rendered after the page loads.
• explicit: Plugins are rendered only with explicit calls to their respective go or render methods. When you use the explicit load in conjunction with go and render calls that point to specific containers in your page, you prevent the script from traversing the entire DOM, which can improve button rendering time.

Other Google JavaScript APIs also use this object to define configuration options, such asGoogle Analytics's social analytics.

Methods

These methods listed below are a subset of the Google JavaScript Client Library that are useful when working with Google+ features.

Authentication and authorization

See the Google Sign-In JavaScript client reference.

---

gapi.client.load(name, version, callback)

Loads the client library interface to a particular API. The new API interface will be in the form gapi.client.api.collection.method. For example, the Moderator API would create methods like gapi.client.moderator.series.list.

Arguments:

name - type: string

The name of the API to load.

version - type: string

The version of the API to load.

callback - type: function

Optional function that is called once the API interface is loaded.

---

gapi.client.request(args)

Creates a HTTP request for making RESTful requests.

Arguments:

args - type: object

An object encapsulating the various arguments for this method. The path is required, the rest are optional. The values are described in detail below.

path - type: string

The URL to handle the request.

method - type: string

The HTTP request method to use. Default is GET.

params - type: Object

URL params in key-value pair form.

headers - type: Object

Additional HTTP request headers.

body - type: string

The HTTP request body (applies to PUT or POST).

callback - type: Function

If supplied, the request is executed immediately and no gapi.client.HttpRequest object is returned.

Returns: type: gapi.client.HttpRequest|undefined. If no callback is supplied, a request object is returned. The request can then be executed via gapi.client.HttpRequest.execute(callback).

---

gapi.client.setApiKey(apiKey)

Sets the API key for the app, which can be found in the Google API Console. Some APIs require this key to be set in order to work.

Arguments:

apiKey: type: string

The API key to set.

Classes

OAuth 2.0 Token Object

The OAuth 2.0 token object represents the OAuth 2.0 token and any associated data. The properties of this object include:

access_token - type: string

The OAuth 2.0 token. Only present in successful responses.

error - type: string

Details about the error. Only present in error responses.

expires_in - type: string

The duration, in seconds, the token is valid for. Only present in successful responses.

state - type: string

The Google API scopes related to this token.

---

gapi.client.HttpRequest

An object encapsulating an HTTP request. This object is not instantiated directly, rather it is returned by gapi.client.request. It defines one method:

gapi.client.HttpRequest.execute(callback)

Executes the request and runs the supplied callback on response.

Arguments:

callback(jsonResp, rawResp) - type: Function

The callback function which will execute when the request succeeds or fails. jsonResp contains the response parsed as JSON. If the response is not JSON, this field will be false. rawResp is the HTTP response. It is JSON, and can be parsed to an object which includes body, headers, status, and statusText fields.

---

The full Google JavaScript Client Library reference contains additional methods and classes.

---