Using OAuth 2.0 and the Google API Client Library for Javascript with Trigger.io Forge

Introduction

Google’s beta release of their API Client Library for Javascript promises to make life easier for developers who want to integrate their apps with Google services (Calendar, Contacts, Analytics, etc.)

While Google provide some documentation for using their library with web applications accessed via a standard browser there are some gotchas involved when trying to make us of it in a Hybrid app environment.

Specifically:

  • Athentication & Authorization flow differs slightly as Hybrid apps do not support the creation of popup windows.
  • Google make use of a small shim library which bootstraps the rest of the library source code from their remote servers. This library has a bug which causes it to fail silently when included from a page which has been served by a protocol other than http:, https: or file:. Unfortunately, Trigger.io app assets are served via the content: protocol on Android!

In this technote I’m going to show you how to use the GoogleJS Client Library and walk through solutions to both of these issues.

Application Configuration

To follow this tech note and use the Google Javascript client library, you’ll first need to configure your application as follows:

Step 1: Platform Version

Make sure your app is running on platform version v2.2.15 (or higher)

Step 2: Modules

Add the following three modules to your app:

  • tabs – We’re going to use a forge tab to open the OAuth authorization dialog and obtain the user’s auth token for your app.
  • httpd – This is a new, experimental, module which serves your app content via the http: protocol rather than file: (iOS) or content: (Android).
  • parameters – We’re going to use the parameters module to store your Google API keys.

Step 3: Trusted URL’s

In your app config, go to core => general => trusted_urls and add the following entry:

This will whitelist any requests made to the httpd module and ensure they are opened by your app’s webview rather than the device browser.

Obtain Google API keys

Before you can use the Google Javascript client library you’ll need to register your app and create a set of API keys.

You can find full instructions here but the process boils down to the following steps:

  1. Visit the Google API’s Console
  2. Create a project for your application.
  3. Navigate to: API's & auth => APIs
  4. Select the API’s you want to use and enable them.
  5. Navigate to: API's & auth => Credentials
  6. Create a new OAuth “Client ID” with the following settings:
    • Application type: Web application
    • Authorized Javascript origins: http://localhost
    • Authorized redirect URIs: http://localhost/oauth2callback
  7. Create a new Public API access “Key” with the following settings:
    • Key type: Browser key
    • HTTP referrers: Leave empty

Once you’ve created the keys, you can add them to your app by adding the following entries to the parameters module:

Loading the Google client library

To load the Javascript client library, include the following script tag in your app’s src/index.html file:

You’ll notice that the script takes a single argument: onload=OnLoadCallback

This specifies the name of a Javascript function in your code that will be called once the library has finished loading and is ready for use.

To implement the callback, add the following global function definition to your code:

Depending on how your app is structured you can use this callback in a number of ways, including:

  • Setting your Public API access key.
  • Letting the rest of your app know that the library has loaded and ready for use.
  • Logging in the user for API’s which require OAuth login credentials.
  • Checking that cached OAuth login credentials are still valid.
  • Loading the Google API libraries your app will use.

Performing Public API requests

For Public API requests the only authorization you’ll require is to set your API key in the library onload callback.

To keep downloads to a minimium Google have implemented an incremental loading mechanism for the client libraries.

To use a particular library you will first have to load it by making a call to gapi.client.load(API_NAME, API_VERSION, CALLBACK).

Once the library is loaded you will be able to access it directly using the format: gapi.client.API_NAME.FUNCTION

For example, the following code can be used to return public information for a Google+ user:

Note that you only ever have to load a libary once via gapi.client.load.

For more information you can refer to the Google documentation.

OAuth 2.0 Authentication & Authorization

To access any private data belonging to the user your application will need to work with Google’s OAuth 2.0 mechanism.

While Google provide a simple convenience method in the form of gapi.auth.authorize() it is not suitable for use in a Hybrid application as it will attempt to open a browser popup window to handle user login.

Fortunately it’s easy enough to write our own OAuth function using the tabs module:

Note that this method is not only limited to Google but can also be used for any other OAuth service!

Our OAuthorize funtion takes an options object as an argument with the following fields:

  • url – the remote OAuth end point. In this case we’ll be using Google’s.
  • client_id – the OAuth Google Client ID you signed up for earlier.
  • redirect_uri – the URL to redirect the OAuth popup to after the user has authenticated. Here we will use the value we used earlier when we created our Google Client ID.
  • scope – the scope of the authorization we’re requesting. For now we’ll just limit this to the user’s basic information on Google Plus.

To authenticate our App with Google and obtain an authorization token we can use to configure the Google client library we’d use the function like this:

Now we can make Google API calls that will return user information:

…and that’s a wrap!

For more information on Google’s OAuth mechanism please refer to the Google documentation.

Conclusion

I hope you’ve enjoyed this quick walkthrough on using Google’s Javascript Client Library with Trigger.io Forge. As always, we’re looking forward to your questions or comments at support@trigger.io!