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:
- Create Self-Hosted Objects containing Gracenote Metadata.
- Create a Facebook App
- Load Your App to Publish a Story.
- 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/