DocumentationForumBlogApps

Open Graph protocol

Core Concepts › Open Graph protocol

The Open Graph Protocol enables you to integrate your Web pages into the social graph. It is currently designed for Web pages representing profiles of real-world things — things like movies, sports teams, celebrities, and restaurants. Including Open Graph tags on your Web page, makes your page equivalent to a Facebook Page. This means when a user clicks a Like button on your page, a connection is made between your page and the user. Your page will appear in the "Likes and Interests" section of the user's profile, and you have the ability to publish updates to the user. Your page will show up in the same places that Facebook pages show up around the site (e.g. search), and you can target ads to people who like your content. The structured data you provide via the Open Graph Protocol defines how your page will be represented on Facebook.

Open Graph protocol

Getting Started

To turn your web pages into graph objects, you'll need to add Open Graph protocol <meta> tags and the Like button to your webpages.

The tags allow you to specify structured information about your web pages. The more information you provide, the more opportunities your web pages can be surfaced within Facebook today and in the future. Here's an example for a movie page:

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:og="http://ogp.me/ns#"
      xmlns:fb="http://www.facebook.com/2008/fbml">
  <head>
    <title>The Rock (1996)</title>
    <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="fb:admins" content="USER_ID"/>
    <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."/>
    ...
  </head>
  ...
</html>

The Open Graph protocol defines four required properties:

  • og:title - The title of your object as it should appear within the graph, e.g., "The Rock".
  • og:type - The type of your object, e.g., "movie". See the complete list of supported types.
  • og:image - An image URL which should represent your object within the graph. The image must be at least 50px by 50px and have a maximum aspect ratio of 3:1. We support PNG, JPEG and GIF formats. You may include multiple og:image tags to associate multiple images with your page.
  • og:url - The canonical URL of your object that will be used as its permanent ID in the graph, e.g., http://www.imdb.com/title/tt0117500/.

In addition, we've extended the basic meta data to add two required fields to connect your webpage with Facebook:

  • og:site_name - A human-readable name for your site, e.g., "IMDb".
  • fb:admins or fb:app_id - A comma-separated list of either Facebook user IDs or a Facebook Platform application ID that administers this page. It is valid to include both fb:admins and fb:app_id on your page.

It's also recommended that you include the following property as well as these multi-part properties.

  • og:description - A one to two sentence description of your page.

If a user likes your URL using a Like button, a News Feed story similar to the one below will be published to Facebook. The og:title links to og:url and the og:site_name is rendered pointing to your site's domain automatically.

On a user's profile, og:type defines which category your link will appear within; og:image is the image thumbnail.

Open Graph profile

For some objects, it makes sense to specify additional meta data, such as location for a restaurant. You can add as many og:-prefixed properties as you would like to provide additional context about your web pages. Learn more about the other property fields.

Adding a Like button

Once you configure the meta tags on your web page, you can now add a Like button associated to this page. The Like button can be simply added with an <iframe>, or you can use the JavaScript SDK for the <fb:like> XFBML tag:

<fb:like href="http://developers.facebook.com/" width="450" height="80"/>

Go here to learn about additional Like button options. Here's a sample Like button for an Open Graph-enabled page:

You can also add any of a number of social plugins to your site with a line of HTML.

Check your work

There are many tools to ensure you put the <meta> tags correctly on your page.

  • The official Facebook URL Linter which uses the same code that we use for the Like button and other Open Graph Protocol consumption. Therefore, it gives you the closest possible match as to how we will treat your page when we crawl it in production.
  • opengraphprotocol.org has many community tools for consuming its protocol.

Page Administration

To administer your page, you need to associate it with either your Facebook account or your Facebook Platform application. It is valid to associate your page with both user accounts and a Facebook Platform Application.

To associate the page with your Facebook account, add the additional property fb:admins to your page with a comma-separated list of the user IDs or usernames of the Facebook accounts who own the page, e.g.:

<meta property="fb:admins" content="USER_ID1,USER_ID2"/>

Each listed user must click Like on the URL to be approved as an admin. This is to prevent users being made admins without their consent.

Some sites may have hundreds or even thousands of pages with Open Graph protocol meta data. To handle a site with lots of pages, you can link your pages to your Facebook Platform application. This will enable you to publish stream updates to your pages programmatically. To connect your Page to your Facebook application ID, include your application's id in the fb:app_id property on your pages:

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

Editing Meta Tags

You can update the attributes of your page by updating your page's <meta> tags. Note that og:title and og:type are only editable initially - after your page receives 50 likes the title becomes fixed, and after your page receives 10,000 likes the type becomes fixed. These properties are fixed to avoid surprising users who have liked the page already. Changing the title or type tags after these limits are reached does nothing, your page retains the original title and type.

For the changes to be reflected on Facebook, you must force your page to be scraped. The page is scraped when an admin for the page clicks the Like button or when the URL is entered into the Facebook URL Linter. You can programmatically force your page to be scraped by cURL'ing the linter. For example:

curl http://developers.facebook.com/tools/lint/?url={YOUR_URL}&format=json

Publishing

You can publish stream updates to the users who have liked your page just like you can with Facebook Pages. There are two ways to get to the publishing interface:

  • From your Web page, click Admin Page next to the Like button.
  • From Facebook, click Manage Pages under the Account tab, then click Go To Page next to your page name

You can publish stories to your users the same way you write a Facebook post from your own wall: by typing in the Publisher, the field at the top of the screen that says "What's on your mind?" The stories appear in the News Feed of anyone who has clicked the Like button on your webpage.

If you associate your page with a Facebook application using the fb:app_id meta tag, you can publish updates to the users who have liked your pages via the Graph API. First you need to get an access token for your application. This can be obtained with

curl -F grant_type=client_credentials \
 -F client_id=your_app_id \
 -F client_secret=your_app_secret \
 https://graph.facebook.com/oauth/access_token

Using this access token and the URL of your page, you can publish to users via the API with

curl -F 'access_token=...' \
 -F 'message=Hello Likers' \
 -F 'id=http://www.myopengraphpage.com/page1.html' \
 https://graph.facebook.com/feed

Some sample PHP code to help you get started:

<?php

$ogurl = "INSERT_YOUR_OG_URL_HERE";
define(FACEBOOK_APP_ID, "YOUR_APP_ID_HERE");
define(FACEBOOK_SECRET, "YOUR_SECRET_KEY_HERE");

$mymessage = "Hello World!";

$access_token_url = "https://graph.facebook.com/oauth/access_token"; 
$parameters = "grant_type=client_credentials&client_id=" . FACEBOOK_APP_ID .
    "&client_secret=" . FACEBOOK_SECRET;
$access_token = file_get_contents($access_token_url . "?" . $parameters);

$apprequest_url = "https://graph.facebook.com/feed";
$parameters = "?" . $access_token . "&message=" .
    urlencode($mymessage) . "&id=" . $ogurl . "&method=post";
$myurl = $apprequest_url . $parameters;

$result = file_get_contents($myurl);

// output the post id
echo "post_id" . $result;
}
?>

Open Graph Publish

The story will be published with the attribution of your application name.

Recommended Meta Data

Two common pieces of information many profile pages have are location and contact information. Below are examples of how you can provide this information as meta data.

Location

This is useful if your pages is a business profile or about anything else with a real-world location. You can specify location via latitude and longitude, a full address, or both. For example:

<html xmlns:og="http://ogp.me/ns#">
  <head>
    ...
    [REQUIRED TAGS]
    <meta property="og:latitude" content="37.416343"/>
    <meta property="og:longitude" content="-122.153013"/>
    <meta property="og:street-address" content="1601 S California Ave"/>
    <meta property="og:locality" content="Palo Alto"/>
    <meta property="og:region" content="CA"/>
    <meta property="og:postal-code" content="94304"/>
    <meta property="og:country-name" content="USA"/>
    ...
  </head>

Contact Information

Consider including contact information if your page is about an entity that can be contacted. For example:

<html xmlns:og="http://ogp.me/ns#">
  <head>
    ...
    [REQUIRED TAGS]
    <meta property="og:email" content="me@example.com"/>
    <meta property="og:phone_number" content="650-123-4567"/>
    <meta property="og:fax_number" content="+1-415-123-4567"/>
    ...
  </head>

Object types

Facebook currently supports the following object types. They're specified using the og:type property. For example:

<meta property="og:type" content="athlete" />

Note that the Open Graph protocol is currently designed to support real-life objects. If your URL is a piece of content — such as a news article, photo, video, or similar — you should set og:type to article (see below). Pages of type article do not have publishing rights, and will not show up on user's profiles because they are not real world objects.

Activities

  • activity
  • sport

Businesses

  • bar
  • company
  • cafe
  • hotel
  • restaurant

Groups

  • cause
  • sports_league
  • sports_team

Organizations

  • band
  • government
  • non_profit
  • school
  • university

People

  • actor
  • athlete
  • author
  • director
  • musician
  • politician
  • public_figure

Places

  • city
  • country
  • landmark
  • state_province

Products and Entertainment

  • album
  • book
  • drink
  • food
  • game
  • product
  • song
  • movie
  • tv_show

For products which have a UPC code or ISBN number, you can specify them using the og:upc and og:isbn properties. These properties help uniquely identify products.

Websites

  • blog
  • website
  • article

Use article for any URL that represents transient content - such as a news article, blog post, photo, video, etc. Do not use website for this purpose. website and blog are designed to represent an entire site, an og:type tag with types website or blog should usually only appear on the root of a domain.

If your object does not fit into one of the types above, you can specify your own type. This will be represented as type other on Facebook. We will monitor the most commonly used types and graduate them to fully supported og:types. If you are specifying your own type we recommend that you use your own namespace. For example if you are moviesite.com, and you want to mark a URL on your site as a director you would do:

<html xmlns:moviesite="http://www.moviesite.com/ns#" > 
<head>
....
    <meta property="og:type" content="moviesite:director"/>

Attaching Audio and Video Data

If you want to attach a video to your Open Graph page you can simply specify a video url:

  • og:video - e.g., "http://example.com/awesome.swf"

and optionally, you can add additional metadata

  • og:video:width - e.g. "385" (max 398)
  • og:video:height - e.g. "400" (max 460)
  • og:video:type - e.g. "application/x-shockwave-flash"

Facebook supports embedding video in SWF format only. You must include a valid og:image for your video to be displayed in the news feed.

For example:

<html xmlns:og="http://ogp.me/ns#"> 
    <head>
        ...
        [REQUIRED TAGS]
        <meta property="og:video" content="http://example.com/awesome.swf" />
        <meta property="og:video:height" content="640" />
        <meta property="og:video:width" content="385" />
        <meta property="og:video:type" content="application/x-shockwave-flash" />
        ...
    </head>

In a similar fashion to og:video you can add an audio file to your markup:

  • og:audio - e.g., "http://example.com/amazing.mp3"

and optionally

  • og:audio:title - e.g. "Amazing Soft Rock Ballad"
  • og:audio:artist - e.g. "Amazing Band"
  • og:audio:album - e.g. "Amazing Album"
  • og:audio:type - e.g. "application/mp3"

For example:

<html xmlns:og="http://ogp.me/ns#">
    <head>
        ...
        [REQUIRED TAGS]
        <meta property="og:audio" content="http://example.com/amazing.mp3" />
        <meta property="og:audio:title" content="Amazing Song" />
        <meta property="og:audio:artist" content="Amazing Band" />
        <meta property="og:audio:album" content="Amazing Album" />
        <meta property="og:audio:type" content="application/mp3" />
        ...
  </head>

Best practices

  • Make it easy for users to Like things on your site. Place the Like button close to the object they are liking.
  • When publishing, use only the 'voice' of the object. For example, if users are liking an actor in a TV show, that actor should publish stories about themselves, not general information on the show, or the TV network.

Building standards

Facebook Platform uses the Open Graph protocol to enable integrations of your web pages into the social graph. While a new technology, we've tried to build off of existing open standards to create a more semantically aware web.

Updated about 2 months ago
Facebook © 2011
AboutPlatform PoliciesPrivacy Policy