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.
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.
(The Quick Start chapter of the documentation outlines passive usage of the JSAPI interface for basic integrations.)
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.
_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.
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.
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.
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.
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.
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 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.