Backplane 2.0

The following steps describe the Backplane Protocol 2.0 Flow (see Figure 1), and how to integrate your website with each step:

  1. Obtain Bus Name and Credentials from Dashboard
  2. Add backplane.js
  3. Initialize the Backplane Object
  4. Configure Backplane Channel for Engage or Capture

Figure 1: Backplane Flow

1. Obtain Bus Name and Credentials from Dashboard

In the Capture Dashboard, this value is listed as backplane_bus. Copy this value to a text file, or write it down. You will need this later.  For Engage credentials, please contact your Janrain support representative.

The Bus Owner credential is used by the website operator or Bus Owner to authenticate with the Backplane Server before authorizing OAuth clients (widgets) to post to their bus.

The OAuth token is used by widgets to post messages on a bus. (Widgets that do not use OAuth2 can still use the Backplane 1.2 authorization procedure.)

2. Add Backplane JavaScript

Place this code in the <head> section of the webpage hosting the widgets. This script adds the library to your web page that the Backplane Server uses. Any Backplane-enabled widgets on this web page, regardless of who made them, will have access to the Backplane bus.

<script type="text/javascript"
   src="http://d134l0cdryxgwa.cloudfront.net/backplane2.js" ></script>
3. Initialize the Backplane Object

Add the code below to the <body> section of the web page, replacing the busName value with the one obtained at Step 1.

<script type="text/javascript">
 function setup_bp() {
    /*
     * Initialize Backplane:
     * This creates a channel and adds a cookie for the channel.
     * It also sets the function to call when this is complete.
     */
    Backplane(bp_ready);
    Backplane.init({
        serverBaseURL: "http://backplane1.janrainbackplane.com/v2",
        busName: "janraindemo.com"
    });
}

function bp_ready() {
    /*
     * This function is called when Backplane.init is complete.
     */
    if (Backplane.getChannelID() != undefined) {
        demo_bp();
        return false;
    }
}

setup_bp();
</script>

This script requests a channel on the server and initializes the Backplane object and associated cookies. The process is asynchronous and does not affect web page load times.

4. Configure Backplane Channel for Engage or Capture

In order for the Capture or Engage widget to publish messages, it retrieves a Backplane channel from the Backplane Server.

Because Backplane 2.0 is OAuth2 compliant, access to the Backplane Server should be through an OAuth2 access token. (You can still use the “manual” access of Backplane 1.2 if your widget is not OAuth2 compliant.) This access token is issued by the Backplane Server and is essentially a “valet key” that allows the user to access resources “owned” by a particular bus owner (in this case, your Janrain application).

To initialize the Engage widget, add the following code to the <body> of the web page:

function doBackplaneStuff() {
 janrain.engage.signin.setBackplaneChannel(Backplane.getChannelID());
 bpListen();
}

To initialize the Capture widget, add the following code to the <body> of the web page:

function doBackplaneStuff() {
 document.getElementById('capture-signin').href +
 '&bp_channel='+encodeURIComponent(Backplane.getChannelID());
 bpListen();
 }

When a visitor authenticates with a Backplane-enabled service like Capture or Engage, that service will publish an event to the specified Backplane channel.

Settings

Some Janrain widgets have JavaScript settings that allow you to control much of the widget’s behavior and appearance. These are specific to each widget, so while there are specific Backplane Protocol settings, these are defined by the Janrain widget you have installed.

For settings details see:

Help Us Improve!

Give us your feedback