The current version of the Promoboxx Javascript API is:

0.6.5

Please use the latest API version on new projects to ensure all known bugs are fixed and all documented features are available. See the Initialization chapter for API link code syntax.

(Note: Live projects should be thoroughly tested when upgrading.)

Quick Start

Including The Promoboxx Script

Getting started with simple integration of Promoboxx data is easy. Just copy and paste the script below into your html and replace the campaign id (xxxxxxxxxxxx) with your campaign id from the Promoboxx Control Panel.

<script>
  var _pbxx = _pbxx || [];
  _pbxx.push(['load','xxxxxxxxxxxx']);
  _pbxx.push(['track','view']);
</script>
<script src="https://www.promoboxx.com/jsapi/0.6.5/pbxx.js"></script>
Special Note For Facebook Tab-Based Campaigns
Note that campaigns that are loaded within Facebook tabs will need to handle the Facebook "signed_request" server variable. Facebook passes this value as a POST variable. The code below shows how to capture this value on a server running PHP and pass it to the Promoboxx script for resolution. The 'fbSignedRequest' command must be called before the 'load' command in order to properly identify the retailer that has installed the tab loading this page.
<script>
  var _pbxx = _pbxx || [];
  _pbxx.push([
      'fbSignedRequest',
      '<?=isset($_POST["signed_request"])?$_POST["signed_request"]:"" ?>'
  ]);
  _pbxx.push(['load','xxxxxxxxxxxx']);
  _pbxx.push(['track','view']);
</script>
<script src="https://www.promoboxx.com/jsapi/0.6.5/pbxx.js"></script>
Note that the _pbxx.push() function usually accepts an array as an argument. Be sure to include the array brackets within the function parentheses to avoid errors.
_pbxx.push(['command', argument1])

Including this code connects your campaign to the Promoboxx server and registers a page view track event. To include retailer-specific content in the page, we need an additional step. The easiest way to include retailer content is to add an html element to the page with a special CSS class called a "content token."

Rendering Content With Class Tokens

<h1>
  Product Release Party at <span class="pbxx-retailer-name"></span>
</h1>

Adding the class pbxx-retailer-name to any element on the html page causes the Promoboxx script to insert into that element the name of the retailer that shared the specific link used to request this campaign page.

More commonly, another token like the pbxx-retailer-block token may be used, which includes a formatted block containing basic contact, social media, and location information about the loaded retailer.

<div class="pbxx-retailer-block"></div>

Avalailable tokens and example usage is provided in the chapter Content Tokens.

Tracking a User Action

The basic script code above includes a track command for recording the most basic user action: a page view. Core Promoboxx content elements also have tracking built in, so adding additional tracking code may not be necessary. On some occasions, though, you may want to track additional user actions on the page. The following code tracks clicks on a html button:

<button onclick="_pbxx.push(['track','click','mySpecialButton',{'myKey':'my value'}])">Click Me!</button>

The code above pushed a 'track' command to the _pbxx object when the button is clicked. This causes the script to record a track event on the Promoboxx server. The arguments that follow the command indicate the type of event as well as optional data to be stored with the event. These should be customized for each tracked action.

The first argument indicates the type of the event. In this case the type is a "click."

The second argument is the category or specific name of the event ("mySpecialButton"). It is usually a description of the object that executed the event.

The third argument — which is optional — is a javascript literal object (a JSON structure) that contains key-value pairs representing data that should be stored with this event. For example, this data may include an indication of information the user has provided or a description of the context of the action.