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

Use of the Promoboxx API is available only to brands currently under contract with Promoboxx. Please contact our sales department for more information on products available through the Promoboxx platform. See the Promoboxx Terms of Service for more information on appropriate uses of this interface.

Overview

Promoboxx is a digital brand-to-retailer marketing platform that enables national brands to distribute online marketing content through local retailers. This API can be used to localize national brand online marketing content (websites, microsites, and Facebook applications) with retailer-specific data. In order for localization to work, the content must be distributed through the Promoboxx platform, though it may be hosted anywhere on the web.

When content is shared from within the Promoboxx platform, the shared urls will include retailer-specific parameters that enable this api to generate customized page content. These parameters are handled automatically by the api and should not be manually processed as their format may change over time.

This overview will briefly explain the features, syntax, and approach of the Promoboxx Javascript API (JSAPI). To skip this discussion and get started with the platform through examples, see the Quick Start section of the documentation.

Approach

The Promoboxx Javascript API is designed to to be used as a passive, unobtrusive javascript interface. It is free of dependencies on other libraries and does not require specific ordering of commands or script loading. A web designer may "paste it and forget it" using the basic loader script and the content token classes.

(The Quick Start chapter of the documentation outlines passive usage of the JSAPI interface for basic integrations.)

Alternatively, the Javascript API may be used actively to produce complex integrations of retailer data. These advanced integrations are created by accessing the _pbxx javascript object and its properties, methods, and events. (Note that using the interface actively may require consideration of the loading sequence of the Promoboxx library with other page resources.)

The following section (platform features) provides an overview of the Promoboxx Javascript API. More detailed information on these features may be found in the remaining chapters of the documentation.

Features

Content injection tokens

Retailer-specific content can easily be integrated into any html page by adding html element placeholders with special css classes. Campaign content will be automatically injected into the selected elements once loading is complete. All content injection class "tokens" are namespaced with the pbxx- prefix. Available tokens and usage is detailed in the chapter Content Tokens.

Push command syntax

The _pbxx object accepts commands using an "array push" syntax. Commands and associated arguments are pushed into the _pbxx command stack using the standard syntax for javascript arrays. This approach allows commands to be entered into a buffer before the Promoboxx scripts have loaded, alleivating the designer of library loading considerations. (Users of the Google Analytics API will recognize this approach.) Example: _pbxx.push(['track','view']);

Campaign data access via a javascript object

Once the _pbxx object has loaded, campaign and retailer data is available through its properties and methods. The structure of the data and usage guidelines are detailed in the chapter Campaign Data. Note that accessing the _pbxx object in this way requires consideration of the load state of affected page elements and the Promoboxx library script.

Load state and context classes

As the Promoboxx scripts and data are loading, the current state is indicated by css classes applied to the <body> element and to any elements with content class tokens. For instance, the <body> element will recieve the class pbxx-loading as soon as the Promoboxx script begins. Once the script completes, the loading class will be replaced with the class pbxx-loaded. See the chapter State and Context for more information on using load state and context classes.

Tracking of user actions

The 'track' command makes granular tracking of page views and user actions easy. Tracked events are automatically classified by retailer and location for display and download in your Promoboxx Control Panel. Syntax and usage is detailed in the Commands chapter. Promoboxx tracking can be used in conjunction with Google Analytics tracking and will not interfere with the performance or statistics of that library.

Automatic loading of Facebook and Google Maps libraries.

The Promoboxx JSAPI makes use of Google Maps (for retailer lookups and address display) as well as the Facebook JavaScript SDK (for sharing and injection of Facebook Social Plugins, i.e. the Like Button). For convienience, these libraries are loaded automatically as needed. The library scripts may also be included explicity in the page code. In this case, the Promoboxx JSAPI will use the already included library. It's recommended that required libraries be included in this way if they are used elsewhere on the page to ensure that library features are available when needed.

Debugging mode.

The Promoboxx JSAPI offers a set of debug modes for diagnosing issues with platform integration. Turning on one of the debuging modes causes verbose output to be written to the browser's console. Console output will include messages indicating loading errors, server responses, and event triggers. See the Commands chapter for more information on debugging modes.

Usage

The Promoboxx JavaScript API has been designed to make it easy to integrate dynamic retailer data into any conventional online marketing content. Retailer-specific contact information, maps, logos and more are available through the API and will be dynamically generated on each content request based on the context of the request. The API also enables custom tracking of user actions that are automatically classified by retailer. The recommended workflow for integrating Promoboxx data into an html project varies depending on the type of integration.

For simple integrations, simply paste in the code from the Quick Start chapter of the docs alongside other scripts in the page and replace the campaign id with the appropriate key from the campaign information page in your Promoboxx Control Panel. Localized content can then be included by adding one or more HTML elements with Promoboxx-specific CSS classes (referred to as “tokens”), to act as placeholders for local retailer information.

For advanced integrations, you'll need to be more aware of details and behavior of the interface. For instance, if you are generating page content dynamically using native javascript or a library like jQuery, you need to make sure the generated elements exist before calling the JSAPI's load command. In this case, call the load command from a load handler function like jQuery's document.ready. The Promoboxx script will delay parsing of the html document until the load command is called and campaign data is retrieved. Any javascript-generated elements with Promoboxx content class tokens will be included in parsing as long as they exist in the DOM when load is called. Inversely, any scripts that access loaded Promoboxx data will need to be queued with the JSAPI's run command to ensure they will be executed only once data has been retrieved.