Implementing Backplane Protocol 2.0

The following sections outline the process for making your web application Backplane compliant and becoming Backplane certified.

Backplane is a message bus used to integrate multiple applications on the same web page. Backplane is not an identity provider, but applications can consume identity messages published from Backplane compliant identity services, such as Janrain Engage or Janrain Capture. Backplane is not a state manager; you will be responsible for managing your own application state, or relying on another application for determining state.

What to Expect

From start to finish, these are the major milestones to becoming Backplane Certified:

  1. Request developer resources and a development environment.
  2. Implement Backplane per the Implementation Guide.
  3. Submit your Backplane integration for review.
  4. Work with Janrain to demonstrate functionality.
  5. Become Backplane Certified.

Implementation Prerequisites

The following are required before implementing Backplane:

  • A provisioned client on a Backplane server
  • A grant on a bus for the client
  • Access to an identity app that publishes identity/login messages (Engage or Capture)
  • JavaScript development resource
  • Server-side development resource
  • Server-side persistence layer
  • Session management (for user engagement apps)
  • Familiarity with OAuth 2.0 (http://tools.ietf.org/html/rfc6749)
  • Familiarity with Portable Contacts and/or OpenSocial (http://portablecontacts.net/draft-spec.html)

The following are optional:

  • Familiarity with Backplane 1.x
  • Backplane 2.0 client library (Java, Python, PHP, Ruby)

Client-Side Integration

The Backplane JavaScript library should be included and initialized by the site owner. Each participating application should bind to the Backplane object for subsequent tasks.

Checking Backplane Version

Your application should test Backplane.version to verify that this site is using Backplane 2.x. If the site is using Backplane 1.x, you should use a code path that follows the Backplane 1.x spec; otherwise, do nothing.

On Backplane Ready

Applications can pass in a callback function to be notified when the Backplane library has completed initialization and a valid channel ID has been generated. The following is an example:

Passing Channel ID to Your Server (optional)

For applications that will need to publish Backplane messages, the Backplane channel ID will need to be passed to the server. An example follows:

Subscribing to the Channel

In order to be notified of messages, you will need to register a callback function to be executed when a message is published.

You can test the type of the message to take the appropriate action for different scenarios.

The browser client will have access to the message header only. To take advantage of the user payload, the message ID will need to be passed on to the server where your authorized client can retrieve the full message.

Allow Customization of Login UI

If your application has existing login/registration links, or actions that prompt the user to authenticate, these will need to be customized such that Backplane identity providers can be used instead. In some cases, it is sufficient to remove the authentication component from the page, and allow the site owner to decide where to place its authentication links.

Server-Side Integration

The supporting server to your application will need the following components:

  • OAuth token creation and refreshing behavior
  • A persistence layer to store access tokens
  • A method to allow the client-side JavaScript to pass in a channel ID (if publishing messages)
  • A method to allow the client-side JavaScript to pass in a message ID and retrieve the payload from the Backplane server
  • A connection to your client-side application to update state when user data is retrieved (if necessary)

Much of this behavior can be simplified by using our Java, Python, or PHP clients. See each respective client for examples.

Support

For questions related to Backplane implementation we ask that you turn first to the Backplane Community to see if your questions have already been answered, and also as a way to archive resolution to any new issues you may experience.