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

Campaign Data

Once loading is complete, campaign data will be available in javascript via the _pbxx object. (This data is also available to server-side scripts via a special data url. See Direct Data Access URL below.) Note that typical campaigns that use the Promoboxx JSAPI do not require direct access to campaign data. Techniques in the section are useful for debugging and for developing advanced, server-side interactions with Campaign data.

When accessing loaded data in javascript, add code to a function pushed with the "run" command. This will delay execution of your script until campaign data has loaded. See the Commands chapter for syntax.

The pbxx-data-[...] wildcard class token provides an easy way to write data into the page without using javascript.

To view the structure of data available from the JSAPI, just load the sample campaign into a modern browser and type _pbxx + Enter into the javascript console. This will allow you to inspect the properties of the object.



Structure of JSAPI Data

_pbxx
  ├───addListener *     (Function) // Method that attaches passed functions to handlers for _pbxx object events
  ├───brand             (Object)   // Loaded brand-specific data.
  │   │
  │   ├───addr1             (String)   // Line 1 of the brand address.
  │   ├───addr2             (String)   // Line 2 of the brand address.
  │   ├───address           (String)   // Formatted full address for the brand.
  │   ├───campaign_alias    (String)   // Brand-specific term for referring to campaigns.
  │   ├───city              (String)   // City for the brand address.
  │   ├───facebook_id       (String)   // This retailer's Facebook Id
  │   ├───facebook_url      (String)   // Url of this retailer's facebook page
  │   ├───id                (Number)   // Numerical id of this brand.
  │   ├───logo_url          (String)   // Url of the brand logo.
  │   ├───name              (String)   // Name of the brand.
  │   ├───phone             (String)   // Primary brand phone number.
  │   ├───retailer_alias    (String)   // Brand-specific term for referring to retailers.
  │   ├───state             (String)   // State or province for the brand address.
  │   ├───telephone         (String)   // Formatted primary brand phone number.
  │   ├───twitter_id        (String)   // Brands's Twitter handle.
  │   ├───website           (String)   // Brand website.
  │   └───zip               (String)   // Zip code for the brand address.
  │
  ├───campaign          (Object)   // Loaded campaign-specific data.
  │   │
  │   ├───brand_id          (Number)   // Numerical id for this brand that owns this campaign.
  │   ├───customization     (Object)   // Retailer-entered customizations for this campaign, if available.
  │   ├───end_date          (String)   // End date of this campaign. Format: "yyyy-mm-ddThh:mm:ssZ"
  │   ├───fb_app_id         (String)   // Facebook app id for hosting or tracking this campaign
  │   ├───id                (Number)   // Numerical id of this campaign.
  │   ├───logo_url          (String)   // Url of the campaign logo.
  │   ├───name              (String)   // Name of the campaign.
  │   ├───phase             (String)   // Current phase of the campaign.
  │   ├───share_url         (String)   // Proper generic url for sharing this campaign.
  │   ├───start_date        (String)   // End date of this campaign. Format: "yyyy-mm-ddThh:mm:ssZ"
  │   └───state             (String)   // Active state of the campaign ( "active" || null )
  │
  ├───content *         (Object)   // Parsed raw data returned from load command. For debugging.
  ├───dump *            (Function) // Debugging method that dumps unexecuted commands in the buffer to console.
  ├───error *           (Boolean)  // True if the server responded to load command with an error.
  ├───exclude *         (Array)    // Set of ids of retailers to exclude from retailer lookups.
  ├───facebook *        (Object)   // Repository for Facebook keys and ids related to the campaign.
  ├───getOptions *      (Function) // Register for pre-load options and switches.
  ├───googleMaps *      (Array)    // Set of loaded google maps.
  ├───googleMapsLoaded *(Function/Boolean) // Method for google maps API to announce that its loaded. (===true afterward).
  ├───load *            (Function) // Command for loading campaign data. Accepts campaign key string.
  ├───loaded *          (Boolean)  // Load state of campaign data.
  ├───location *         (Object)   // Profile of the loaded location. Copied element from _pbxx.retailer.location.
  │   │
  │   └─ (data structure identical to _pbxx.retailer.locations)
  │
  ├───log *             (Array)    // Debug log for browsers with no console.
  ├───mappable_set      (Boolean)  // Loaded data includes locations with geolocaton data.
  ├───mode              (String)   // State of loaded page: "location" || "retailer" || "brand"
  ├───name *            (String)   // Full name of Promoboxx JSAPI version.
  ├───onReady *         (Function) // Register for functions that should run when campaign data is loaded.
  ├───push              (Function) // Schedules or executes commands, depending on load state of _pbxx. Accepts an array.
  ├───refreshMaps *     (Function) // Method that re-renders all google maps. Use when hidden maps are made visible.
  ├───retailer          (Object)   // Profile of loaded retailer when available.
  │   │
  │   ├───email             (String)   // This retailer's email address
  │   ├───facebook_id       (String)   // This retailer's Facebook Id
  │   ├───facebook_url      (String)   // Url of this retailer's facebook page.
  │   ├───id                (Number)   // Numerical id of this retailer.
  │   ├───location          (Object)   // Profile of selected location.
  │   │   │
  │   │   └─ (data structure identical to _pbxx.retailer.locations[n] below)
  │   │
  │   ├───locations         (Array)    // Set of locations this retailer manages.
  │   │   └─[n]
  │   │      ├───addr1             (String)   // Address line 1 for this location.
  │   │      ├───addr2             (String)   // Address line 2 for this location.
  │   │      ├───address           (String)   // Formatted full address for this location.
  │   │      ├───city              (String)   // City for this location.
  │   │      ├───id                (Number)   // Numerical id of the location.
  │   │      ├───latitude          (String)   // Decimal representation of latitude value for this location.
  │   │      ├───longitude         (String)   // Decimal representation of longitude value for this location.
  │   │      ├───phone             (String)   // Location phone number.
  │   │      ├───query             (String)   // Query string portion of this location's campaign link url.
  │   │      ├───state             (String)   // State or province for this location.
  │   │      ├───telephone         (String)   // Formatted location phone number.
  │   │      ├───website           (String)   // Url of location website.
  │   │      └───zip               (String)   // Zip code for this location.
  │   │
  │   ├───logo_url          (String)   // Url of the retailer logo.
  │   ├───name              (String)   // Name of the retailer.
  │   ├───phone             (String)   // Primary retailer phone number.
  │   ├───telephone         (String)   // Formatted primary retailer phone number.
  │   ├───twitter_id        (String)   // Retailer's Twitter handle, as entered by retailer
  │   └───website           (String)   // Retailer website.
  │
  ├───retailers         (Array)    // Set of retailers currently loaded and displayed in lookup elements.
  │   └─[n]
  │      ├───accepted          (Boolean)  // True if retailer has accepted this campaign.
  │      ├───id                (Number)   // Numerical id of this retailer.
  │      ├───locations         (Array)    // Set of locations this retailer manages.
  │      │   └─[n]
  │      │      ├───addr1          (String)   // Address line 1 for this location.
  │      │      ├───addr1          (String)   // Address line 2 for this location.
  │      │      ├───address        (String)   // Formatted full address for this location
  │      │      ├───city           (String)   // City for this location.
  │      │      ├───geodata        (Boolean)  // True if geographic location data is available for this location.
  │      │      ├───id             (Number)   // Numerical id of the location.
  │      │      ├───latitude       (String)   // Decimal representation of latitude value for this locationg.
  │      │      ├───link           (String)   // Url of campaign page for this retailer & location.
  │      │      ├───longitude      (String)   // Decimal representation of longitude value for this location.
  │      │      ├───marker         (Object)   // Reference to the associated Google Map marker on the lookup map.
  │      │      ├───query          (String)   // Query string portion of this location's campaign link url.
  │      │      ├───state          (String)   // State or province for this location.
  │      │      └───zip            (String)   // Zip code for this location.
  │      │
  │      ├───name              (String)   // Retailer name.
  │      ├───phone             (String)   // Primary retailer phone number.
  │      ├───telephone         (String)   // Formatted primary retailer phone number.
  │      └───website           (String)   // Retailer website url.
  │
  ├───setOptions *      (Function) // Method for setting pre-load switches. Accepts Object.
  ├───setVars *         (Function) // Method for setting content strings and objects. Accepts Object.
  ├───share_url         (String)   // The proper url for sharing the loaded version of the campaign.
  ├───vars *            (Array)    // Repository for all stored content variables.
  └───version *         (String)   // Numerical portion of Promoboxx JSAPI version.

* Properties available only in javascript (not present in direct access data)

Direct Data Access URL

Advanced users may want to inject or manipulate Promoboxx JSAPI data on the server as the page is being assembled. This is possible by querying a data access endpoint. Data will be returned as json in the same structure as data available through the _pbxx javascript object (excluding any method functions). The following endpoint can be used to request campaign data in json format:

http://engine.promoboxx.com/jsapi/0.6.5/data/?campaign_key=XXXXXXXXXXXX&query_string=query_string_from_server_variables

It's best to pass the query string directly to the endpoint as campaign urls are assembled and stored by the Promoboxx server when retailers share their campaigns. The format of these urls may change over time.

Here is an example of loading data from the direct access endpoint in php using the file_get_contents function. This example demonstrates the simplest method to pull remote data in php but it is advisable to use the curl command curl instead if available, for maximum performance and flexibility.

<?php
    // Data access base url
    $endpoint = 'http://engine.promoboxx.com/jsapi/<?=$currentJsapiVersion?>/data/';
    // Parameters:
    $parameters = 'campaign_key=xxxxxxxxxxxx'
                  . '&query_string='.$_SERVER['QUERY_STRING'];
    // Request all retailers for brand view (optional and not recommended).
    //   Note: preload_all_retailers should only be used for brands with small retailer sets (<100)
    //   loading large datasets will significantly increase server response times.
    //$parameters .= '&preload_all_retailers=true';

    // Retrieve data:
    $json = file_get_contents( $endpoint.'?'.$parameters );
    // Load into a php object:
    $pbxx = json_decode($pbxx);

    // campaign data is now available from $pbxx via php object syntax:
?>
<p><?= $pbxx->retailer->name ?></p>

See Structure of JSAPI Data above for data available from the data access endpoint.


Data Access Examples (Advanced Techniques)

Example: Map Marker Manipulation

Below is an annotated example using _pbxx javascript object to access campaign data and change displayed content on the page. This code – likely executed by a click or hover event of a page element – changes the icon for a location marker on the lookup map of a campaign loaded in brand mode. Note that at the point of execution, the campaign would be finished loading and in brand mode, with a set of retailer locations displayed on the lookup map.

// First find the reference to the relevant marker in the _pbxx object.
// (using an index variable set elsewhere in the script).
var activeMarker = _pbxx.retailer.locations[index].marker;

// Now use standard Google Maps marker manipulation syntax to change the icon
activeMarker.setOptions({
  icon:{
    scaledSize:new google.maps.Size(20,30),
    url:'img/flashy.png'
  }
});

// Or use the simplified syntax, with no image scaling
activeMarker.setIcon('img/flashy.png');

// See the Google Maps documentation for more detailed instructions on manipulating markers