By Xavier Damman, co-founder of Storify
(Cross-posted from the Google Code blog, where the post is part of Who's at Google I/O, a series of guest blog posts written by developers who are appearing in the Developer Sandbox at Google I/O.)
Storify is part of the Google I/O Sandbox. Please come say hi to find out more about how you can leverage our APIs so your users can remix your content to create stories to share on social networks.
Storify provides a super simple drag and drop user experience to create stories using elements from the web: tweets, YouTube videos, Facebook updates, SlideShare presentations, audioboo files, and so on (see Storify in action here). This post explains how we incorporate videos in Storify using YouTube Data API and Player API. All the code snippets are in JavaScript. In fact, our full stack is in JavaScript: we use NodeJS and MongoDB which we think is an über cool mix.
The source of the source
To create a Storify source, we need to be able to get a feed of results using JSONp (basically JSON with a callback function so that you can do cross domain calls; from the YouTube API perspective this is the JSON-C format). For YouTube, the main search API endpoint looks like this:
request: function(formdata) {
return {
'url' : 'http://gdata.youtube.com/feeds/api/videos',
'params': {
'v' : 2,
'max-results' : 20,
'alt' : 'jsonc',
'q' : formdata.keywords
}
};
}
This function is called when the user clicks Submit in the search tab of the YouTube source in the Storify Editor. The main controller executes the request and sends the JSON result to the results method, which returns an array of normalized results:results: function(json) {
if (json.data && json.data.totalItems && json.data.totalItems == 0) {
throw "No results found";
}
var videos = json.data.items;
var results_array = [];
for (var i = 0; i < videos.length; i++) {
var normalizedResult = {
permalink : 'http://www.youtube.com/watch?v='+videos[i].id,
source : 'youtube',
elementClass : 'video',
metadata : videos[i],
thumbnail : videos[i].thumbnail.sqDefault,
title: videos[i].title,
description : videos[i].description.substr(0,140),
author: {username: videos[i].uploader },
created_at : videos[i].uploaded,
oembed: {html: '<iframe id="youtube-'+videos[i].id+'" type="text/html" width="360" height="294" src="http://www.youtube.com/embed/'+videos[i].id+'?enablejsapi=1&origin=storify.com" frameborder="0">'
}};
results_array.push(normalizedResult);
}
return results_array;
}
Thanks to this normalized representation of a story element – in this case, it’s a video object – we can build an object-oriented story as the user drags and drops any of these elements. This technique has multiple benefits: we maintain attribution to the original content creator, and we can track the content as it spreads across the web (how many times it has been seen and from where).
The story element also provides the oEmbed HTML code. This is used to render the video embed when the video is added to the story. For that purpose we use the YouTube Player API with their new iframe embed.
Story.json
We have a very simple way to get any data out of our platform: just append .json to any storify.com URL and you get the JSON representation of the content of that page.
For example:
- http://storify.com/latest.json?topic=googleio returns the latest stories with the tag
#googleio. - http://storify.com/xdamman.json returns the user object and the user’s latest stories.
- http://storify.com/xdamman/googleio.json returns the story object of the story “GoogleIO” of xdamman. You can use this to easily filter the elements of the story to retrieve only the YouTube videos of a given story and create a fancy HTML5 visualization (see the slideshow or this version). You can see some open source examples at http://github.com/storify/templates.
Add the Storify Editor to your site
The Storify Editor can be called in an iframe. You just need to provide a callback parameter, like this:
http://storify.com/story/new?callback=yoursiteurlcallback. The user will be asked to authenticate with Twitter and then will be able to create a new story. Once the user is done and hits “Publish”, we call you back, passing you the permalink of the new story created:yoursiteurlcallback?permalink=storyPermalink.You can then either fetch the JSON of the story by appending “.json” to the
storyPermalink or you can embed the story by loading <script src=”storyPermalink.js”></script>. This is a great way to provide your community with a way to create stories right from your site.This is only the start. We plan to open a Sources API so that any developer can build a source for any service. Please come see us at our booth at the Google I/O Sandbox if you’re interested in joining our developer community. And check out this article in the New York Times to learn more.
Come see Storify in the Developer Sandbox at Google I/O on May 10-11.
Xavier Damman is the co-founder of Storify. He is also the founder of HackDemocracy, a community of hackers who want to improve our democracies using technology.
