Open Graph Integration

Introduction

The Open Graph protocol is a protocol developed by Facebook to allow web site owners to communicate key information about their pages to Facebook. Since being published in 2010, Open Graph has subsequently been adopted as a supported metadata standard by Google+.

For example, if the page was about the movie "The Rock", you might include the following Open Graph metadata:

<meta property="og:title" content="The Rock"/>
    <meta property="og:type" content="movie"/>
    <meta property="og:url" content="http://www.imdb.com/title/tt0117500/"/>
    <meta property="og:image" content="http://ia.media-imdb.com/rock.jpg"/>
    <meta property="og:site_name" content="IMDb"/>
    <meta property="og:description"
          content="A group of U.S. Marines, under command of
                   a renegade general, take over Alcatraz and
                   threaten San Francisco Bay with biological
                   weapons."/>

When a visitor clicks on the Like button, Facebook will retrieve this information to control how the like interacts with user's Facebook timeline. In the above example, Facebook will include this like in the Movies section of the user's profile:

Usage in UltraCart

The UltraCart catalog allows you to easily include these tags in your catalog group and item pages. In order to utilize these extra tags, you will need to be using XHTML compliant pages.

The first step is to add two different namespaces to your opening HTML tag, which will look like this when updated.

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:og="http://ogp.me/ns#"
      xmlns:fb="https://www.facebook.com/2008/fbml">

If you fail to put the name spaces on your html tag then the Open Graph will not work.

Next, in your page's header, you would enter the metadata as shown above, but replacing the values with velocity code that reflects the content of the current page. For example, you might include the following on an item page:

<meta property="og:title" content="$item.getDescription()"/>
<meta property="og:type" content="$group.getAttribute("og-type")"/>
<meta property="og:image" content="$item.getDefaultMultimedia("image").getViewUrl()"/>
<meta property="og:site_name" content="My Awesome Store"/>
<meta property="og:description" content="$item.getExtendedDescription()"/>

The meta properties must be within the head tag on your page.

Be careful when using the getExtendedDescription() method, as it frequently contains additional HTML and can be quite long. If you are using the extended description for other parts of your catalog, you may want to create a new item attribute to contain your social media description content. Alternatively, you can use the FormatHelper object to remove all of the HTML from your extended description:

<meta property="og:description" content="$formatHelper.removeHtml($item.getExtendedDescription())"/>

The og:type tag specifies what type of "real world" object is being referenced on the current page. Facebook has compiled a list of valid types on their website.

Single Template

We recommend creating a template named "snip_opengraph" and including it within the head tag of your main templates. Here is an example of a snip_opengraph that will adapt based upon whether it's a group or item page that is rendering.

#if ($item) 
  <meta property="og:title" content="$item.getDescription()"/>
  <meta property="og:type" content="product"/>
  <meta property="og:image" content="$item.getDefaultMultimedia("image").getViewUrl()"/>
  <meta property="og:site_name" content="My Site Name"/>
  <!-- <meta property="fb:admins" content="USER_ID"/> -->
  <meta property="og:description" content="$formatHelper.removeHtml($formatHelper.removeNewLines($item.getExtendedDescriptionNoEscape()))"/>
#else
  <meta property="og:title" content="$group.getTitle()"/>
  <meta property="og:type" content="product"/>
  <meta property="og:image" content="$group.getDefaultMultimedia("image").getViewUrl()"/>
  <meta property="og:site_name" content="My Site Name"/>
  <!-- <meta property="fb:admins" content="USER_ID"/> -->
  <meta property="og:description" content="$formatHelper.removeHtml($formatHelper.removeNewLines($group.getDescription()))"/>
#end

So for an item page we have the following mappings and manipulations taking place

OpenGraph Field	Item Field	Manipulation
og:title	Description	None
og:type	n/a	hard coded as product
og:image	Default image	None
og:site_name	n/a	hard code to your sites name
og:description	extended description	obtain it without any escaping, remove the new lines and remove the HTML tags

and for the group pages we have the following mappings and manipulations taking place

OpenGraph Field	Group Field	Manipulation
og:title	Title	None
og:type	n/a	hard coded as product
og:image	Default image	None
og:site_name	n/a	hard code to your sites name
og:description	Description	obtain it without any escaping, remove the new lines and remove the HTML tags

If you create a template named "snip_opengraph" with the example then you include it in your main template using the code:

#ucTemplate("snip_opengraph")

Facebook Specific Options

In addition to the standard Open Graph tags, Facebook has added several helpful tags of their own that will allow you even more control over the behavior and appearance of your content on Facebook. The first is the application identifier. If you have a page on Facebook for your brand or product, then you will have an application identifier. If you don't yet have an application identifier, you can request one from Facebook's Developer website. Once you have your Application ID, add it to your page using the fb:app_id property:

<meta property="fb:app_id" content="1234567"/>

By including this property on each of your pages, you can aggregate all of the "likes" your site receives into a single location in Facebook. If you wish to allow certain Facebook users to visit your site's administration page, you should also include each user's facebook id using the fb:admins property:

<meta property="fb:admins" "USER_1_ID,USER_2_ID"/>