Involver Developer Network : bazaarvoice
This page last changed on Oct 24, 2011 by jed.wheeler@involver.com.

Overview

Involver and Bazaarvoice have partnered to bring the power of Bazaarvoice's Ratings and Reviews offering to the audience of Facebook. Powered by SML, the Bazaarvoice SML application lets developers customize each Ratings and Reviews application to provide the best experience to end users possible.

Tab and Canvas Pages

The Bazaarvoice application consists of three distinct pages, each driven by a separate SML template.

Tab (Fan Page) View

The Tab view (bazaarvoice_520px) drives the initial experience shown on a Facebook fan page. This is the standard entry point for an end user, and can be configured to show a combination of product, author and review modules.

  • All data displayed on the Tab view is global - reviews, products or other data will be displayed from all active categories and products.
  • All links to another part of the application will bring the end user to a Canvas page - either Category or Product, depending on link clicked.
  • Unlike other views, no special context variables are exposed. All context variables available are supplied through the bazaarvoice object.

Category Canvas Page

The Category Canvas page (bazaarvoice_760px_category) expands the tab view into the full 760px width of a canvas page, allowing for additional navigation UI. The Category canvas page restricts all modules to the current active category. If no category is selected, modules will display the same data as on the tab view.

Product Canvas Page

The Product Canvas page is the UI for a single product. This is the only page that allows for user submission of data by submitting a review form. All data displayed on the page is associated with a single product.

Configuration

At bare minimum, a BazaarvoiceFeature requires the following information:

  • The main (520px) SML template
  • Category page canvas SML template
  • Product page canvas SML template
  • Shared CSS block
  • Bazaarvoice API credentials (API key and encoding key)

The current SML templates are stored in a shared Github repository for joint use by Involver and Bazaarvoice. Use the most up to date SML template as included in the bazaarvoice-templates repository. If you do not have access, please make a request for your Github account to be added to the list of approved users.

Once the main 520px layout has been saved to the SML feature, a BazaarvoiceFeature will be generated. The feature exposes the rest of the configuration necessary to run the Bazaarvoice application.

Featured Products

Two methods are allowed for providing products: Automatic and manual configuration.

  • Automatic configuration takes the first 100 products from the API and uses them as featured products.
  • Manual allows for an arbitrary number of product IDs to be provided.

A list of categories will be backfilled based on the featured products provided.

API Settings

The Bazaarvoice API requires a secret key for data retrieval and an encoding key for review form interactions.

We allow any application to use production or staging data at any time. Please exercise caution when configuring test and production pages to ensure the page is configured appropriately.

URLs

URL settings allow the privacy policy and Terms of Service URLs to be set for a particular client.

All image URLs are deprecated in favor of editable_image. The images in use are:

image name function
520Banner Banner on the 520px Tab view
760Banner Banner on the 760px canvas views (product and category)
starOn Graphic for a single active star icon (used to display rating values)
starOff Graphic for a single inactive star icon (used to display rating values)
buyNow Button displayed on the Product page that links to the customer's product URL.
buttonDown Graphic used at the end of the Category dropdown menu

Module Configuration

Each module displayed on a page can be toggled on or off.

Due to width issues, we recommend that exactly TWO of the following modules be enabled at any given time:

  • Top Contributors
  • Top Rated Products
  • Most Popular Products

Form Field Configuration

"Always Shown Fields" is a list of field names that should show above the fold.

"Review Field Labels" is used to override labels returned from the Form API. This is required for fields without labels to show in a form view.

Styles and Templates

For the Bazaarvoice application to function properly, three templates must be provided via the feature settings page. As mentioned above, these templates are stored in the shared Github repository. When provisioning a new application, be sure to use the most recent version of all templates.

setting description filename
Styles for all templates Shared CSS Block bazaarvoice_css
Category Page SML SML template for Category Canvas page bazaarvoice_760px_category
Product Page SML SML template for Product Canvas page bazaarvoice_760px_product

Caching Considerations

Bazaarvoice API data is automatically updated each hour. In addition, data is updated whenever a change is made to feature configuration. The Settings page for a Bazaarvoice application shows time elapsed since the last API data sync.

Attributes

name type required description
name string no A unique name the SML will use to look up which Bazaarvoice instance to use. For a typical page, only one Bazaarvoice instance will be used.

Context Variables

name type description
GENERAL SETTINGS
secret_key string Bazaarvoice API key. Not used in templates by default.
feature_all_products boolean Toggle to feature all products for a page.
URL ACCESSORS
privacy_policy_url string Configurable URL for the client's privacy policy. Used as part of review submission form display.
tos_url string Configurable URL for the client's Terms of Service. Used as part of review submission form display.
banner_url_520px string URL for 520px wide banner image for tab view. Deprecated in favor of editable_image.
banner_url_760px string URL for 760px wide banner image for canvas views. Deprectaed in favor of editable_image.
star_on_url string URL for active state of review value display. Deprecated in favor of editable_image.
star_off_url string URL for inactive state of review value display. Deprecated in favor of editable_image.
buy_now_button_url string URL for 'Buy Now' button on product page. Deprecated in favor of editable_image.
PAGE URLS
iframe_url string Base URL of the application.
recent_review_url string API URL to retrieve recent reviews. In the global context, this URL will pull recent reviews for all categories.
CACHED API DATA ACCESSORS
top_level_categories Array of category objects List of top level categories (categories without ancestors). Used to paint 'Choose Category' dropdown.
categories Array of category objects List of categories for the application. This list includes all categories (ancestors and children).
recent_reviews Array of review objects List of recent reviews for the overall application.
featured_products Array of product objects List of products based on the 'Featured Products' setting.
top_rated_products Array of product objects List of top rated products as returned by the Bazaarvoice API.
most_popular_products Array of product objects List of most popular products as returned by the Bazaarvoice API.
top_contributors Array of author objects List of top contributing authors as returned by the Bazaarvoice API.
review_limit integer Exposes limit for recent review for use in fetching database
CONFIGURABLE MODULE ACCESSORS
show_featured_products boolean Toggle for featured products module
show_recent_reviews boolean Toggle for recent reviews module
show_top_contributors boolean Toggle for top contributors module
show_top_rated_products boolean Toggle for top products module
show_most_popular_products boolean Toggle for popular products module

Associated Objects

Category

The category object bundles all data for a given category. On a Category Canvas page, the current category drives most of the data on the page.

Product

A product object represents a product from the user's catalog, along with any associated metadata. This is the record of note on a Product canvas page.

Author

The author object represents a user who has left a review. If the user left a review via the Facebook Ratings and Reviews app, more Facebook-specific information will be available in the model.

Review

The review object represents a review of a product, either pending or complete.

Form

The form object encapsulates information from the Bazaarvoice Form API for review form display. This is primarily used by the form SML partial on the Product page.

Limitations

The block does not use a default template. Unless used with a parent SML feature, SML templates must be provided in every case.

FAQ

There are currently no FAQ questions for this item.

Related Topics
Document generated by Confluence on Feb 12, 2013 09:09