Warning: This document describes features that are in developer preview. Everything described here is subject to change.

Your use of the history API code is subject to the Google+ Platform Button Policies and Google+ Platform Terms of Service.

Introduction

The client-side flow allows your application to write moments from within your user's web browser with JavaScript.

Starter project

The easiest way to become familiar with this API is to experience working code. Spend a few minutes setting up and running the starter project before you proceed to the explanation below.

If you do not have 5 minutes to run your own copy of the starter project, visit the live demo.

What you need

To run your own copy of the starter project, you need:

• A web server such as Apache HTTP Server
• A whitelisted API client ID from the APIs Console. If you are using a new API project, you may need to click on the 'Create an OAuth 2.0 client ID...' button.

Downloading the starter project

Next, download the client-side flow starter project.

Running it

Now for the fun! Follow these steps:

1. Extract the archive.
2. Replace all instances of YOUR_CLIENT_ID with your whitelisted client ID.
3. The sign-in button initiates JavaScript requests. To allow this add its protocol and hostname, https://plusone.google.com, to the JavaScript origins list in the API Access section of the APIs Console.
4. Your copy of the starter project also initiates JavaScript requests. Add the protocol, domain name and port for your web server to the JavaScript origins list also. For example, if you are running your copy of the starter project from a local web server on port 8080 you would add http://localhost:8080
5. Start the web server, make the extracted directory accessible, and view it in your web browser.
6. Use the controls to sign in and write moments.
7. View written moments on your Google+ history page.

Note: The requirement to add https//plusone.google.com as a JavaScript origin will be removed at or near launch.

How it works

If you followed the steps above, you should now have a working client-side application that uses this API. Here is a breakdown of how the starter project code uses the API.

Rendering the sign-in button

Rendering the sign-in button is easy. First, include one JavaScript file.

<!-- Required to render the Google+ sign-in button -->
<script src="https://apis.google.com/js/plusone.js"></script>

Next, use the g:plus element where you want the button to render on your page.

<!-- Render the sign-in button -->
<g:plus action="connect"
        clientid="YOUR_CLIENT_ID"
        scope="https://www.googleapis.com/auth/plus.moments.write"
        callback="onSignInCallback"></g:plus>

Finally, supply a callback function in the global namespace that hides the sign-in button and optionally executes other code. For example, the callback function can also be used to reveal features that are only available to signed in users.

<script>
  /**
   * This method is called upon completion of the sign in flow. Its primary
   * function is to hide the sign in button.
   *
   * @param authResult an object which contains the access token and other
   *   authentication information.
   */
  function onSignInCallback(authResult) {
    if (authResult.error == null) {
      debugLog('Auth Success', authResult);
      toggleInterface(true);

      // Store the auth result for later use
      storeAuthResult(authResult);
    } else {
      debugLog('There was a problem!', authResult);
    }
  }
  /**
   * Toggle the interface between the signed in and signed out state
   */
  function toggleInterface(animate) {
    if (animate) {
      // Hide the sign in button
      $("#panel-sign-in").toggle("blind", "slow", function() {
        // Display features that require the user to be signed in
        $("#panel-communicate-moments, #panel-sign-out").toggle("blind", "slow");
      });
    } else {
      // do the same quickly
      $("#panel-sign-in, #panel-communicate-moments, #panel-sign-out").toggle();
    }
  }
</script>

Note: For a more general explanation of the rendering of the sign-in button, see the overview page.

Writing moments

Now that your user is signed in with Google, you can write moments. To make API calls you must include the Google JavaScript API client library.

<!-- The JavaScript API Client library: Required to write moments -->
<script src="//apis.google.com/js/client.js"></script>

You can now use the client library to write moments to Google.

/**
 * Write a moment to Google+
 *
 * @param payload an object representation of the moment
 */
function writeMoment(payload) {
  // Set the access token on the JavaScript API Client
  gapi.auth.setToken(getAuthResult());

  var args = {
    'path': '/plus/v1moments/people/me/moments/vault?debug=true',
    'method': 'POST',
    'body': JSON.stringify(payload),
    'callback': function(response) {
      debugLog('Moment write response', response);
    }
  };
  debugLog('Sending moment', payload);
  gapi.client.request(args);
}

writeMoment({
  "type": "http://schemas.google.com/AddActivity",
  "target": {
    "url": "https://developers.google.com/+/plugins/snippet/examples/thing"
  }
});

Note: For a general explanation of writing moments, see the overview page.

Staying authorized

Your OAuth access token will expire after about one hour. You must refresh it in order to make additional API calls.