Website Integrations #2: oEmbed
Welcome to part 2 of this impromptu miniseries! In this second part of three, I'll be showing you a little about how I set up and tested a simple oEmbed provider for my blog posts - I've seen lots of oEmbed client information out there, but not much in the way of provider (or server) implementations.
If you haven't read part one about the open graph protocol yet, then you might find it interesting.
oEmbed is a bit different to open graph in that instead of throwing a bunch of meta tags into your <head />, you instead use a special <link /> element that points interested parties in the direction of some nice tasty json. Personally, I find this approach to be more sensible and easier to handle - the kind of thing you'd expect from an open standard.
To start with, I took a read of their specification, as I did with open graph. It doesn't have as many examples as I'd have liked, and I had to keep jumping around, but it's certainly not the worst I've seen.
oEmbed is built on the idea of providers (that's me!) and consumers (the programs and website you use). Providers, erm, provide machine-readable information about urls passed to them, and consumers take this information provided to them and display it to the user in a manner they think is appropriate.
To start with, I created a new PHP file to act as my provider over at https://starbeamrainbowlabs.com/blog/oembed.php and took a look at the different oEmbed types available - oEmbed has a type system of sorts, similar to open graph. I decided on link - while a rich would look cool, it would be almost impossible to test with every client out there, and I can't guarantee how the html would be rendered or what space it would have either.
With that decided, I made a list of the properties that I'd need to include in the json response:
version- The version of oEmbed. Currently1.0as of the time of typing.type- The oEmbed type. I choselinkhere.title- The title of the pageauthor_name- The name of the authorauthor_url- A link to the author's homepage.provider_name- The provider's name.provider_url- A link to the provider's homepage. I chose my blog index, since this script will only serve my blog.cache_age- How long consumers should cache the response for. I put 1 hour (3600 seconds) here, since I usually correct mistakes after posting that I've missed, and I want them to go out fairly quickly.thumbnail_url- A link to a suitable thumbnail picture.thumbnail_width- The width of the thumbnail image, in pixels.thumbnail_height- The width of the thumbnail image, in pixels.
Then I looked at the data I'd be getting from the client. It all comes in the form of GET parameters:
format- Eitherjsonorxml. Personally, I only support json.url- The url to send oEmbed information for.
With all the information close at hand, I spent a happy hour or so writing code, and ended up with a script that outputs something like this:
{
"version": "1.0",
"type": "link",
"title": "Website Integrations #1: Open Graph",
"author_name": "Starbeamrainbowlabs",
"author_url": "https:\/\/starbeamrainbowlabs.com\/",
"provider_name": "Stardust | Starbeamrainbowlabs' Blog",
"provider_url": "https:\/\/starbeamrainbowlabs.com\/blog\/",
"cache_age": 3600,
"thumbnail_url": "https:\/\/starbeamrainbowlabs.com\/images\/logos\/open-graph.png",
"thumbnail_width": 300,
"thumbnail_height": 300
}Though the specification includes requirements for satisfying 2 extra GET parameters, maxwidth and maxheight, I chose to ignore them since writing a dynamic thumbnail rescaling script is both rather complicated and requires a not insignificant amount of processing power every time it is used.
After finishing the oEmbed script, I turned my attention to one final detail: The special <link /> tag required for auto-discovery. A quick bit of PHP in the article page renderer adds something like this to the header:
<link rel="alternate" type="application/json+oembed" href="https://starbeamrainbowlabs.com/blog/oembed.php?format=json&url=https%3A%2F%2Fstarbeamrainbowlabs.com%2Fblog%2Farticle.php%3Farticle%3Dposts%252F229-Website-Integrations-1-Open-Graph.html" />and with that, my oEmbed provider implementation is complete - but it still needs testing! Unfortunately, testing tool for oEmbed are few and far between, but I did manage to find a few:
- oEmbed Tester - A basic testing tool. Appears to work well for the most part - except the preview. Not sure why it says "Preview not available." all the time.
- Iframely URL Debugger - Actually a testing tool for some commercial tool or other, but it still appears to accurately test not only oEmbed, but open graph and twitter cards (more on them in the next post!) too!
After testing and fixing a few bugs, my oEmbed provider was complete! Next time, I'll be taking a look at twitter's take on the subject: Twitter cards.
Found this interesting? Comment below! Share it with a friend!