The following steps describe the Backplane Protocol 2.0 Flow (see Figure 1), and how to integrate your application or widget with each step:
- Any Backplane enabled widget subscribes with the Client-Side Library for a callback.
- The Library polls the server periodically and when the server returns a new message the Library will pass it along to the widgets via that callback given in the subscribe step.
- The Backplane Server returns the message in a callback to the Backplane Client-Side Library.
- The Client-Side Library, transfers the message header from the callback to your Widget. (Depends on your implementation.)
- Your Widget calls the Widget Server with the message id. Your Widget can ask for all or part of the message, and request a specific format, or even to receive the data wrapped in another data structure.
- The Widget Server requests the payload from the Backplane Server.
- The Backplane Server sends the payload to the Widget Server, which processes the message payload and sends the appropriate subset to the Widget.
In the Janrain Dashboard, you need the values listed as backplane_password and backplane_bus. Copy these values to a text file, or write them down. You will need these later.
For Engage credentials, please contact your Janrain support representative. We require these elements from you in order to provide you with credentials.
- A PGP public key for us to encrypt your credentials.
- A URL that identifies the site. This will eventually be the redirection URI for the OAuth2 code flow.
Note: You do not necessarily need credentials to create a widget or application, but we suggest that you get a free Engage app to test with. If you also want to set up your own capture-enabled site for testing, you need to get credentials from us. For partners developing new widgets, you need the client credentials and your own backplane bus for testing.
1. Subscribe for a Callback
One of the notable differences in Backplane Protocol v2.0 from Backplane Protocol v1.2 is that the message payload (that portion of the message containing personally identifiable content) is removed from the message arriving at the non-credentialled client. The Backplane 2.0 widget listens for a message, and then requests the data to go along with the message from another server. For more information on this change in procedure, refer to Messages.
The following is sample code used to listen to the Backplane channel for ‘identity/login’ messages. Once this message type is received, this code will make a call to its server-side component, using JSONP, to fetch the portion of the payload that is important for their function. See Step 4 for details.
2. Receive Message in a Callback
Place this code in the section of the webpage hosting the widgets. This script adds the Backplane Server library to your webpage. Any Backplane-enabled widgets on this web page, regardless of who made them, will have access to the Backplane bus.
Once included, the library facilitates the client side code interaction with the Backplane server.
3. Transfer the message header from the callback from the client side to your platform server script or process
The header needs to be passed along to the server-side code for processing. This can be accomplished in several different ways, depending on how your website is implemented. It is suggested to use the existing client-to-server, if present.
4. Request Payload from Backplane Server
Once the widget or web app on the site receives the message, it will request more information from its Widget Server through a JSONP call. The Widget Server then requests the payload from the Backplane Server.
The following is an example request in PHP:
5. Process Payload
The Backplane Server delivers the payload to the Widget Server as a JSON file.
The Widget Server must parse and then store data from this file. Not all data needs to be preserved. The storage and format is completely up to the Widget Server. All that matters is that the server can send a JSON payload to a widget.