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.)

Commands

Pushing commands to the _pbxx object is the recommended way interacting with the Promoboxx javascript object. Commands may be used to configure the Promoboxx javascript object settings, to initiate jsapi actions, and to specify code to be run when jsapi events occur. Commands may be pushed to the interface at anytime. Commands that are pushed prior to script initializaiton will be stored in a buffer until they can be executed. Most commands take parameters, which may be optional or required.

Commands are run by "pushing" a one-dimensional array to the _pbxx object. The first array item is the command name, and any additional items are interpreted as command parameters.

Command Syntax

The javascript syntax for running a command is:

_pbxx.push(['command', param1, param2, ...]);

Command Reference

There are many commands available from the _pbxx object. The commands can be cassified into three categories:

Note: The term “retailer” refers to the currently selected local retailer, dealer, etc.

Option Switches

The following commands switch options on and off, modifying the API’s general behavior. For the most part, these options should be pushed prior to running the 'load' command. The syntax for switches follows this format:

_pbxx.push(['debug',true]);

Note the second parameter may also be omitted, which will have the same effect as passing "true."

_pbxx.push(['debug']);

Many options may be set at once using the setOptions command.

_pbxx.push(['setOptions',{ debug:true, noTrack:true }]);



Command Description
debug

Display verbose console logs for everything.

Parameters
  1. Switch. Boolean. Defaults to false.
debugForm

Display verbose console logs only for forms.

Parameters
  1. Switch. Boolean. Defaults to false.
debugListeners

Display verbose console logs only for event listeners.

Parameters
  1. Switch. Boolean. Defaults to false.
debugTrack

Display verbose console logs only for tracking.

Parameters
  1. Switch. (Boolean) Defaults to false.
loadFacebook

Load the Facebook SDK and process Facebook-related tokens.

Parameters
  1. Switch. Boolean. Defaults to true.
loadMaps

Map widgets (tokens pbxx-map and pbxx-map-brand) will be rendered using Google Maps.

Parameters
  1. Switch. Boolean. Defaults to true.
loadStyle

Enables injection of the pbxxstyle.css stylesheet.

Parameters
  1. Switch. Boolean. Defaults to true.
parseTokens

Look for and process Promoboxx tokens.

Parameters
  1. Switch. Boolean. Defaults to true.
noTrack

Block all tracking commands from executing. This command will prevent successive page loads from registering reporting stats when the page code is offline or being debugged.

Parameters
  1. Switch. Boolean. Defaults to false.
setOptions

Sets any number of the above options above with one command.

Parameters
  1. Commands. Object.
Example
  _pbxx.push(['setOptions',{
    debug : true,
    noTrack : true
  }]);

Identification and Content Settings

The following commands register data that customizes the campaign. These include unique campaign, retailer, or location identifiers, as well as copy for Facebook and Twitter share text.

Command Description
campaignKey

Register the campaign key, to use when loading campaign data.

fbSignedRequest

Register the Facebook signed request.

Parameters
  1. Signed Request, String.
setVars

Defines common variables used to customize JSAPI output. The command takes an object as its argument and may contain any number of recognized properties. Multiple setVars commands may be pushed and only explicitly specified variables will be affected.

Parameters
  1. Variables, Object. Passed values should generally be strings, though in some cases, other data types may be expected. The following properties are available:
    fb_feed_default_image
    A URL pointing to an image to use as the thumbnail for a Facebook share, e.g. http://www.acme.example/image.png.
    fb_feed_title
    The title of a Facebook share.
    fb_feed_description
    The text content of a Facebook share.
    fb_brand_url
    A URL pointing to a brand’s Facebook page, e.g. http://www.facebook.com/acme.
    twitter_text, twitter_text_retailer, twitter_text_brand
    The text content of the Twitter share, used in the built-in "share on twitter" button. Multiple versions are provided for the various page modes. The appropriate mode-specific version will be tried first, depending on whether the page is loaded in a retailer (location or retailer) or brand mode. If these are missing or invalid, then the generic text string is used. This allows for a fallback in the case that variable insertion creates a string over the 120 character limit for tweets (variable insertion is described below).
    fb_feed_description, fb_feed_description_retailer, fb_feed_description_brand
    The text content of the Facebook share, used in the built-in "post on facebook" button. Multiple versions are provided for the various page modes. The appropriate mode-specific version will be tried first, depending on whether the page is loaded in a retailer (location or retailer) or brand mode. If these are missing or invalid, then the generic text string is used.
    fb_feed_title, fb_feed_title_retailer, fb_feed_title_brand
    The title of the Facebook share, used in the built-in "post on facebook" button. Multiple versions are provided for the various page modes. The appropriate mode-specific version will be tried first, depending on whether the page is loaded in a retailer (location or retailer) or brand mode. If these are missing or invalid, then the generic text string is used.
    google_map_marker
    A custom marker image to use for plotted Google Maps points representing retailer locations.
    google_map_style
    Load a set of styles to override default Google Maps styling. For format and available settings, see the Google Maps documentation for styling maps. These styles may also be applied after load by accessing the loaded maps available via the _pbxx javascript object. Usage is demonstrated in an example below.
    retailer_list_select_button_text
    Custom text to display on the "select location" button for an item in the lookup results list in brand mode.
    retailer_list_map_button_text
    Custom text to display on the "show on map" button for an item in the lookup results list in brand mode.
Example: Setting Common Variables
  _pbxx.push(['setVars',{
    fb_feed_default_image :
        "http://www.yoursite.com/image.png" ,
    fb_feed_title :
        "The title of the Facebook share" ,
    fb_feed_description :
        "The main text of the share" ,
    fb_brand_url :
        "http://www.facebook.com/cocacola" ,
    twitter_text :
        "The text to share via Twitter goes here." ,
    google_map_marker :
        "img/marker.png"
  }]);
Using dynamic data in variable strings

Many variables that can be set via the setVars command can accept _pbxx inline data tokens. Simply include the javascript reference to the data item, enclosed in braces. Delimit members with periods, just as you would in a javascript reference and be sure not to include any spaces. Standard array bracket syntax may be used to reference an item in a member array.

_pbxx.push(['setVars',{
  twitter_text :
      "I’m heading to {_pbxx.retailer.name} to get my new shiny Acme widget!"
  }]);
Example: Setting Google Maps Styles

  // Change the color of all water on loaded maps

  _pbxx.push(['setVars',{
         google_maps_style:
            [
              {
                "featureType": "water",
                "elementType": "geometry.fill",
                "stylers": [
                  { "color": "#8EC5D4" }
                ]
              }
            ]
  ]);

Events and Actions

Used to attach a function handler to an event raised by the _pbxx object. The command accepts string event name, a handler function, an optional boolean for specifying high priority.

Command Description
load

Load campaign data from the server, using the included campaign key.

Parameters
  1. campaignKey, String (Optional if previously pushed). Indicates the campaign to retreive data from.
exclude

Exclude one or more retailers from lookup results.

Parameters
  1. retailer or location ids, Array or Number. Indicates one or more retailers (or locations) to exclude from the results of brand view retailer lookups. Pass an array of id numbers or a single id.
  1. by_location, Boolean. Passing true indicates that the listed ids are location ids (not retailer ids). Defaults to true
Example
_pbxx.push(['exclude',[813,702,...],false);
allow

(Opposite of exclude.) Prevent all retailers (or locations) from showing up brand view lookup results exept those included in a list.

Parameters
  1. retailer or location ids, Array or Number. Indicates one or more retailers (or locations) to exclude from the results of brand view retailer lookups. Pass an array of id numbers or a single id.
  1. by_location, Boolean. Passing true indicates that the listed ids are location ids (not retailer ids). Defaults to true
Example
_pbxx.push(['allow',[4076,4103,...],true);
run

Specifies a function to run when the campaign content is loaded.

Parameters
  1. Function, Function. Code to be run once campaign content is loaded. The keyword this may be used in the function to refer to the _pbxx object.
Example
_pbxx.push(['run', function (eventData){
    // function code...
}]);
addListener

Used to attach a function handler to an event raised by the _pbxx object. The command accepts string event name, a handler function, and an optional boolean for specifying high priority. The handler function will recieve an object containing any relevant data. For a list of events raised by the _pbxx object and detailed syntax, see the chapter Events.

Parameters
  1. EventName String. The name of recognzed event raised by the _pbxx object.
  2. Handler Function. A handler function to be run when the event is raised.
  3. highPriority Boolean (Optional). Indicates that the function should be pushed to the top of the handler stack.
Example
_pbxx.push([
  'addListener',
  'eventName',
  function (eventData){
    // function code...
  },
  highPriority = true||false
]);
saveLead

Take input from a lead generation form and store it in the database.

This behavior is handled automatically on forms implemented with the pbxx-form- content class tokens. The saveLead command is provided for flexibility when creating campaigns that don't use the built-in form features.

Parameters
  1. Custom Data (Array). An array of name-value object pairs. The exact format of each object may differ from campaign to campaign, but must not vary within a campaign.
  2. Callback (Function). A function to be run after the lead data has been saved to the database.
Example
_pbxx.push([
  'saveLead',
  /* Parameter 1 */
  [
    {
      'name': 'name',
      'value': 'John Smith'
    },
    {
      'name': 'email',
      'value': 'jsmith@domain.example'
    }
  ],
  /* Parameter 2 */
  function ()
  {
    $( '#lead-form' ).remove();
  }
]);
track

Used for tracking page events, like views and clicks. Most components of the JSAPI have tracking built in, but this command is provided for tracking events from other objects on the page (e.g., an embedded national marketing video). See the Quick Start chapter for more information on tracking syntax.

Parameters
  1. Category — String. Labels the action that the user will have taken to trigger the track event. Possible values: view, click.
  2. Subcategory — String (Optional). Further specifies the type of action taken. For instance, a click.
  3. Custom Data — Object. Name/value pairs to associate with the tracking event.
Example
<button onclick="_pbxx.push(['track','click','mySpecialButton',{'myKey':'my value'}])">Click Me!</button>