Embedding a player on Facebook: A guide

Last weekend I had a mission: to build a player component for instaud.io that could play audio people linked to, right in Facebook news feeds. I found that there are plenty of excerpts on how to go about this, but most of them are based on outdated links to Facebook developer documentation. It bugged me greatly that Facebook didn’t bother setting up redirects to relevant pages after restructuring their docs.

Anyway, I think this would work best as a step by step guide. I’ll go through the steps I’ve had to learn about; you may want to skip over some if you’re already know what you’re doing in them.

1. Build your player in Flash

I downloaded the Adobe Flash trial for this. You’ll want to create a stage that is not much wider than 500 pixels. I went with 504px. What you’re going to be playing depends entirely on you. My purpose was simply to play audio files (MP3s), so I used Sound and SoundChannel to control that. The audio file to be played was requested with an URLRequest object.

If you want a more thorough introduction on how to set up a simple sound player, this video from 2008 is still a good starting point, even with the latest version of Flash (12, CS6): Build Simple Sound Player: Flash Tutorial AS 3.0

Using parameters

The important part about the ActionScript is using parameters. Parameters will be passed to the eventual SWF through the querystring, that is, the bold part in this URL: https://example.com/my-player.swf?param=value&otherparam=value

In ActionScript (3), you can access these variables the following way:

loaderInfo.parameters.parameterName

To check if a parameter is actually present:

loaderInfo.parameters.hasOwnProperty('parameterName')

This way you can use default values for parameters:

var myParam = loaderInfo.parameters.hasOwnProperty('myParam') ?
    loaderInfo.parameters.myParam :
    'defaultValue';

Since hasOwnProperty returns a boolean value (true or false), this statement assigns either the value of myParam from the querystring, or 'defaultValue' if no such parameter was specified, to the myParam variable. It uses a ternary operator.

2. Export the SWF file and include it in your website’s assets

This is fairly straightforward. You’ll want the swf to live someplace where it’s directly accessible. I let mine live in the document root directory.

3. Add Open Graph meta tags to the page

This is where the Facebook magic happens.

Facebook will read this Open Graph data when your page is being linked to, and extract the Flash file for embedding. These are the ones you will need:

og:video

Full URL to the SWF file, including parameters for this page:

<meta property="og:video"
      value="https://example.com/your-player.swf?param=foo&param2=bar">

og:video:width, og:video:height

Specify the dimensions of your Flash movie:

<meta property="og:video:width" content="504">
<meta property="og:video:height" content="115">

og:video:type

The mime type of the file:

<meta property="og:video:type" content="application/x-shockwave-flash">

The canonical URL is the best URL to reach this piece of content on your website. (In case there are multiple URLs that get you there.)

I’d advise you to go read more on The Open Graph Protocol, as well as having a read through David Walsh’s article on Open Graph meta tags for more magic you can implement with these.

4. Set up SSL

The one catch about embedding stuff on Facebook is https. ~~Many~~All users are browsing Facebook with “secure browsing” on by default. The result is that your Flash component won’t get loaded if it doesn’t live at an https:// URL as well.

If you have an SSL certificate installed for your domain, you can make your Flash embed work for https users as well, by simply adding the following meta tag:

<meta property="og:video:secure_url"
      content="https://example.com/your-player.swf?param=foo&param2=bar">

If you need help setting up SSL, you can consult Linode’s library, they have a lot of useful documentation.

Obtaining a Commercial SSL certificate explains how to do the server-side portion of setting up your certificate and key.
SSL certificates with Nginx explains that too, as well as how to use it with your Nginx configurations.
Apache SSL Guides lists articles for various operating systems, on how to set SSL up with Apache.

Update 2016-07-10: I higly recommend using Lets Encrypt for all your SSL needs going forward. It’s free, and is much, much easier to set up than any commercial ssl authority. It is backed by loads and loads of great companies and organisation and is quickly growing to be the de-facto standard for SSL.

I hope that makes it a bit easier for people who want to get this stuff implemented in the future. I definitely had a hard time googling it all together.