Alpha Only: This service is subject to change
This service is a work in progress. It is currently subject to change or removal without notice.

Spark Bar Integration

Integrating the SparkBar into your project is a matter of passing the appropriate credential to some client-side JavaScript. This is a two step process.

Step 1: Add the client-side code

Add the following code to your page (see jQuery note below). This code loads some JavaScript and CSS asynchronously.

<script>
    // include the SparkBar
    window.SparkBarAsyncInit = function() {
        SparkBar.init({
            token: 'YOUR__TOKEN__GOES__HERE',
            display: 'full'
        });

        // include additional items here that will run after the SparkBar is initiated
    };
</script>

// load the App Bar JavaScript
<script type="text/javascript" src="http://sparkplatform.com/appbar/assets/v1/sparkbar.js"></script>
jQuery Note
The SparkBar uses jQuery. If your site also uses jQuery, you can use a lightweight version of the SparkBar that avoids reloading jQuery, which avoids namespace conflicts and code duplication. Simply load this alternative version of the JavaScript after jQuery is loaded:

<script type="text/javascript" src="http://sparkplatform.com/appbar/assets/v1/sparkbar_no_jquery.js"></script>

This code will load a JS file that will in turn load all the rest of the code necessary to steal space and present the SparkBar.

The SparkBar init function takes an options object, which currently supports:

  1. token: this is required in order for the SparkBar to know who your user is. This is required, and the token that needs to be passed is generated in the second step below.
  2. display: this determines which display the SparkBar is oriented in. This string currently accepts either "full" or "mini".
  3. onresize: this accepts a function that will be called whenever the SparkBar is resized (made smaller or larger, for example). This is useful if your interface needs to change when that occurs.

The full SparkBar will take 29px from the top of your page by creating additional margin space. This prevents the site owner from having to carve out space, as it will be done automatically.

The mini SparkBar is absolutely positioned over the top of the page to the right. This SparkBar will not make room on the page, so it's up to the site owner to clear a path.

Mobile Tip
To prevent the SparkBar from getting bigger and smaller with orientation changes on a mobile device, we'd recommend the meta tag below. This will keep your zooming in/out in line for your whole site.
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1" />

Step 2: Retrieve a SparkBar token

In order to know who your user is, we need to pass a token along. This token is generated by the SparkBar app itself based on your OAuth session. This way, you're not passing your OAuth credentials in plain view. This token is also only good for the SparkBar, which itself is restricted to only see certain pieces of data (and no writes of any kind).

To receive a SparkBar token, you must POST your OAuth access_token to the SparkBar app on the server side. The URL endpoint is:

https://sparkplatform.com/appbar/authorize

This service expects an access_token parameter, which it will validate against the API. If it's successful, you'll receive:

{ "success": true, "token": YOUR__SPARKBAR__TOKEN__IS__HERE }

If the success attribute has the value true, the value of the token attribute is what you'll need to pass to the SparkBar.init method (detailed in Step 1). If this works, you should see a successfully loaded SparkBar.

However, if the success attribute is false, consult the error attribute for more details about the error. Below is an example response when an invalid or expired access token is POSTed to the appbar service:

{"success": false, "error": "Failed to authenticate to the API"}