Introduction

This document describes the integration of Gracenote music metadata with the Facebook Open Graph (OG) Music API.

Note

To access music metadata, Gracenote supports a number of platforms and programming languages. This document assumes Gracenote metadata was pre-fetched using the Music Web API, Mobile Client SDK, or the Gracenote SDK. Refer to the documentation for these products on how to do this in your application.

Process

As with other OG apps, you need to follow standard Facebook process:

  1. Create Self-Hosted Objects containing Gracenote Metadata.
  2. Create a Facebook App
  3. Load Your App to Publish a Story.
  4. Submit Your App for Review and Approval.

For this document, we focus on Step 1. This is where we add Gracenote metadata to objects so they can be shared on Facebook. For information about the general OG app process, see: https://developers.facebook.com/docs/opengraph/getting-started/

Important

URLs returned by Gracenote are temporary, and may become invalid over a short time. Do not cache them for later use.

Step 1. Create Self-Hosted Objects

In Facebook terms, self-hosted objects are web pages that you maintain and host on a separate server. These pages contain OG meta tags and corresponding data and links to images or other pages. To learn about the general process of creating self-hosted objects, see https://developers.facebook.com/docs/opengraph/using-objects/
Many of the OG music meta tags map to Gracenote music metadata. For example, og.title for music.album maps to Gracenote album title, and og.image maps to album cover art. For a detailed mapping of Gracenote music metadata to OG music tags, see Metadata Mapping. For general information about the OG Music meta tags, see https://developers.facebook.com/docs/opengraph/music/ .
Below are some examples of objects mapping Albums, Songs (Tracks), and Profiles (Artists)

Albums

The following snippet shows the meta tag declaration for an OG object of type music.album. This page links to other OG objects of types music.song and music.profile. In this example, we only link to one song object of the album, but multiple songs are supported to support full track lists and playlists.

…
<html>
<head>
…
<title>Album Information</title>
<meta property="og:title" content="OK Computer"/>
<meta property="og:type" content="music.album"/>
<meta property="og:image" content="gn_url_to_album_cover_art"/>
<meta property="og:site_name" content="Gracenote"/>
<meta property="fb:app_id" content="a_fb_app_id"/>
<meta property="og:description" content=" gn_url_to_album_review"/>
<meta property="music:release_date" content="1991">
<meta property="music:musician" content="url_to_web_hosted_profile_page">
<meta property="music:song" content=" url_to_web_hosted_song_page">
<meta property="music:song:disc" content="1">
</head>
…

Song (Tracks)

The following snippet shows the meta tag declaration for an OG object of type music.song. This page links to other OG objects of types music.album and music.profile.

…
<html>
<head>
…
<title>Song Information</title>
<meta property="og:title" content="Climbing Up The Walls"/>
<meta property="og:type" content="music.song"/>
<meta property="og:image" content="gn_url_to_album_cover_art"/>
<meta property="og:site_name" content="Gracenote"/>
<meta property="fb:app_id" content="a_fb_app_id"/>
<meta property="music:musician" content="url_to_web_hosted_profile_page">
<meta property="music:album" content="url_to_web_hosted_album_page">
<meta property="music:album:track" content="3">
</head>

...

Profile (Artist)

The following snippet shows the meta tag declaration for an OG object of type music.profile. This page links to other OG objects of types music.album and music.profile.

…
<html>
<head>
…
<title>Artist Profile</title>
<meta property="og:title" content="Radio Head"/>
<meta property="og:type" content="profile"/>
<meta property="og:url" content="gn_url_to_artist_biography"/>
<meta property="og:image" content="gn_url_to_artist_image"/>
<meta property="og:site_name" content="Gracenote"/>
<meta property="fb:app_id" content="a_fb_app_id"/>
</head>
…

Step 2. Create a Facebook App

Create a Facebook App that points to one or more of the self-hosted objects you created in Step 1.

Note

You should work with Sandbox mode enabled until you have completed your app and submitted it for approval by Facebook. To learn more, see https://developers.facebook.com/docs/opengraph/getting-started/#create-app .

When developing your app, you should define what kind of actions you want the app to provide. There are several kinds of actions available.og.like, og.follow, and og.posts are most general actions. However, there are some specific to music as well, including music.listen for when someone is listening to an album or song, and music.playlist, which is used when a user is creating a playlist to be shared. Learn more about actions here: https://developers.facebook.com/docs/reference/opengraph/action-type

Step 3. Load Your App to Publish a Story

Load your app to publish it as a "story" to your Facebook page. This creates a relationship graph between you, your app, and your objects. Later, when you publish your app for others to use, each new user of your app is added to your app's relationship graph. For details, see https://developers.facebook.com/docs/opengraph/getting-started/#publish

Step 4. Submit Your App for Review and Approval

Submit your app for review and approval by Facebook. This is a mandatory step before you can publish your app outside of the FB OG sandbox. Once approved, publish the app for others to see and use. For details about the submission process, see https://developers.facebook.com/docs/opengraph/getting-started/#submit .

 

Metadata Mapping

This section shows some of OG types and tags that are supported by Gracenote metadata.

OG Type

OGTag

Gracenote Metadata

music.album

og:title

Album Title

og:image

Album Cover Art

og:description

Album Review

music.song

og:title

Track Title

music:album:track

Track Number

profile

og:title

Artist Name

og:image

Artist Image

og:description

Artist Biography

Mobile App Use Case

A compelling use case for using Open Graph Music is a Gracenote application that dynamically posts to Facebook information about what a user is listening to. Several companies that provide online radio provide this sort of feature.
Such an application would dynamically generate album, song, and artist profile objects based on what users are listening to. Then, either automatically or on-demand, can post this information as an OG story to their Facebook pages. To help support this kind of use case, Facebook also provides an Object API to make it easier to publish this information directly to Facebook. For more information, see https://developers.facebook.com/docs/opengraph/using-object-api/