Open House On Demand, Part 1: A Video Open House Powered by OpenAuth, Video Uploads, Truveo, and the AOL Video Player

By John Fronckowiak
January 18, 2008

Well, real estate is always good, as far as I'm concerned. - Donald Trump

About Open House On Demand

The goal of the Open House On Demand project is to provide an online virtual open house, supported by AOL technologies. Open House On Demand provides real estate brokers with a mechanism to upload videos of properties for sale to the AOL Video web site and to specify attributes of those properties such as property type, number of bedrooms, or year built. In addition, potential buyers will be able to search the property videos and view a virtual open house in a web browser. This article is presented in two parts. In part one, which you are now reading, I will discuss implementing the video upload for property brokers. In part two, I will discuss how potential buyers can search and view the videos.

Open House On Demand interweaves a number of important AOL and web technologies:

AOL Open Authentication API (OpenAuth) - Allows users to authenticate using either their AOL, ICQ, or OpenID logins.
AOL Video Upload API - Allows video uploads from your web site directly to AOL Video.
AOL Truveo API - Allows searching of the videos available at AOL Video and on other video web sites. I discuss the Truveo API in the articles "TruveoCast: Building a Mac OS X Dashboard Widget to Share Your Truveo Video Favorites" and "Elephant's Pajamas: Building a Truveo Video Joke-of-the-Day Mac OS X Dashboard Widget."
AOL Video Player - Allows embedded playback of videos available at AOL Video.
JavaScript - Supports client-side web scripting.
Prototype JavaScript Framework - Provides developers with many useful JavaScript functions that speed the web development process. I discuss the framework in my blog post "Prototype Power" and in the article "AIM Fight! Building a Mac OS X Dashboard Widget to Measure Your Connectedness."
PHP - Supports server-side web scripting.

Building the Broker Video Upload

Although I use numerous AOL technologies in Open House On Demand, I've kept the design simple at this point so that it will be easy to understand. In this article, I focus on the broker video upload process, which requires using the AOL OpenAuth and AOL Video Upload APIs. To upload videos to AOL Video using the Video Upload API, users must authenticate by using their AOL, ICQ, or OpenID logins to identify the authenticated user as the owner of the video on the AOL Video site.

After users are authenticated, they can upload their videos. The authentication process returns an authentication token, which serves as proof that the user has been authenticated and is used in the call to upload the video.

Both the AOL OpenAuth API and the Video Upload API require developers to register their applications. As part of the registration process, which I review in detail in the following section, each developer will obtain a unique developer ID.

Obtaining a Developer ID

To use the OpenAuth and Video Upload APIs, you first have to obtain an AOL Developer ID (devId). The devId uniquely identifies developers and the specific applications that implement AOL technologies. Fortunately, obtaining a devId is simple. First, you must have an AOL, ICQ, or OpenID account. If you don't already have one, you can obtain an AOL screen name at https://reg.my.screenname.aol.com/_cqr/registration/initRegistration.psp?sitedomain=dev.aol.com&authLev=1
&siteState=OrigUrl%3Dhttp%253A%252F%252Fdev.aol.com%252Fkeys&lang=en&locale=us&uitype=
flex&createSn=1&mcAuth=%2FBcAG0eKl4QAAK81A%2BpMj0eKl8AInP5TVAshGecAAA%3D%3D.

To obtain a devId for your application, go to http://dev.aol.com/keys. You will be asked to log in, as shown in Figure 1.

Figure 1. AOL Developer Network authentication

After you've logged in, you can manage your devIds, as shown in Figure 2. To create a new devId, click Create new devId.

Figure 2. Manage your devIds

Before you can create a new devId, you must agree to the AOL terms of service for using the AOL APIs, as shown in Figure 3. Read the terms closely, and then click the Agree button at the bottom of the page.

Figure 3. The AOL Open Services terms of service

You can now create your devId. You must provide your name, e-mail address, application name, destination URL, and application description, as shown in Figure 4. The destination URL is crucial--you need to provide the URL of the web site that will host your application. This information will come into play when you use the Video Upload API, and I will discuss this point in more detail shortly. Note that I've provided a localhost URL so that I can use the API for testing and development on my local computer. When I deploy the application for production, I must update the destination URL with the new location. After you've typed the required information, click Create.

Figure 4. Provide information about your application

Your devId will be generated, as shown in Figure 5. You will use this key when accessing the OpenAuth and Video Upload APIs. You can return to the http://dev.aol.com/keys site to retrieve your key, edit information about a key, or even create additional keys for other applications.

Figure 5. Your devId key listing

OpenAuth Usage Rules

As a developer, before you integrate the OpenAuth API into your applications, you must understand and agree to the OpenAuth usage rules. These rules are detailed at http://dev.aol.com/api/openauth. Important highlights of these rules include:

You will use the API only for authentication purposes.
You will not store or duplicate your authentication token.
Your application will not request more than 10,000 tokens per day or 150,000 tokens per month.
If you are going to use the API in a commercial application, you must first contact AOL at http://dev.aol.com/contact.

Implementing Authentication

Authentication is the first thing a user must do when accessing Open House On Demand. Authentication is accomplished by calling the login function, as shown in Listing 1, through the URL http://api.screenname.aol.com/auth/login.

Listing 1 - The Broker Open House Video Upload page

<?php
  // Begin a new session
  session_start();
?>
<html>

<body>

  <div align="center">Broker Open House Video Upload</div>

<?php 
  // The URL of the video upload site - upon successful authentication 
  // this is where the user is redirected
  $_SESSION['succUrl'] = "http://localhost/~john/ohod/upload.php";

  // Replace with your devId
  $_SESSION['devId'] = "**Your DevId**";

  // Build the authentication URL
  $href = 'http://api.screenname.aol.com/auth/login?f=qs';
  $href .= '&devId='. $_SESSION['devId'].'&supportedIdType=SN,ICQ';
  $href .= '&succUrl='.urlencode($_SESSION['succUrl']);
?>

<p> 
  <strong>You must first 
     <a href="<?php 
			  // The constructed href is the Login link
                 echo($href); 
              ?>">Login</a> using your AOL/AIM ID or ICQ Account.</strong>
</p>

</body>
</html>

The login method is supported only as a browser redirect. The application constructs a login URL using this method along with the required parameters. This method depends on secure authentication cookies set in the browser, so it cannot be invoked from the server side. For the Open House On Demand project, the login method is invoked from a link that is constructed as the page is requested. The login method requires the following URL parameters:

f - The format of the authentication response, which can be either JavaScript Object Notation (JSON) or XML or can be returned as query string parameters.
devId - This must be your developer ID that you obtained from http://dev.aol.com/keys.

The following optional parameters are passed to the login method:

supportedIdType - This is a comma-separated list of identity types: SN for AOL and AIM IDs, ICQ, or OID for OpenID users. (The AOL Video Upload API does not currently support OpenID.)
succUrl - After successful authentication, this is the URL to which the user is redirected.

The authentication for Open House On Demand returns the authentication response as URL parameters to the page specified in succUrl. This will contain the AOL authorization token, which is required by the Video Upload API.

When users access the Broker Open House Video Upload page, shown in Figure 6, clicking the Login link will take them to the AOL Authentication page, shown in Figure 7. After typing the correct username and password, they are redirected to the page on which they can upload the open house video and describe the property.

Figure 6. The Broker Open House Video Upload login page

Figure 7. The AOL Authentication page

The Broker Upload Page

After users are authenticated, they are ready to fill in the Broker Open House Video Upload page, shown in Figure 8. In addition to selecting the video file to upload, users can specify other attributes of the property. The address of the property is used as the title that identifies the video. All of the other attributes are stored as tags. These tags will be used later when a query is constructed using the AOL Truveo API. The tags are stored as a comma-separated value list.

Figure 8. The Broker Open House Video Upload page

The AOL Video Upload API

The AOL Video Upload API provides two functions: upload and status. The Video Upload page uses the upload function. When a video is uploaded, it is sent to the AOL Video site for processing. The video files must be converted to a format that can be played by the AOL Video player. This process will take some time. You can use the status function to determine where a particular video is in the conversion process.

Currently, the AOL Video Upload API does not provide a mechanism to delete a video that has been uploaded. Users must go to the AOL Video site to manage their video uploads, where they can edit and delete any videos that they have uploaded earlier.

AOL Video Upload Usage Rules

Just like the OpenAuth API, the Video Upload API requires developers to adhere to specific usage rules, which are detailed at http://dev.aol.com/api/video_upload. Important highlights of these rules include:

You must clearly state that the video will be uploaded to AOL Video.
Users must agree to the AOL Video standards--detailed at http://uncutvideo.aol.com/License.html--before they can upload a video.
The upload API cannot be called more than 50 times in a 24-hour period. If you believe your application will exceed these limits, contact AOL at http://dev.aol.com/contact for a site review.

The Video Upload Form

The form that uploads the video to the Broker Open House Video Upload page is shown in Listing 2. Before the page is submitted, the JavaScript validate_upload() function is called, as shown in Listing 3. I have specifically used the $ and blank functions from the JavaScript Prototype Framework in the validate_upload function.

Listing 2. The Video Upload form

<form action="" method="post" enctype="multipart/form-data" 
   name="videoUpload" id="videoUpload" onsubmit="validate_upload();">
  <label>
  Open House Video File:
  <input name="videoFile" type="file" id="videoFile" size="64" />
  <br />
  Notify By Email When Processing Is Complete:
  <select name="notifyByEmail" id="notifyByEmail">
    <option value="yes">Yes</option>
    <option value="no">No</option>
  </select>
  <br />
  <input type="hidden" name="cat" id="cat" value="1024" />
  <input type="hidden" name="title" id="title" />
  <input type="hidden" name="tag" id="tag" />
<br />
  </label>
    <input name="submit" type="submit" id="submit" value="Submit" />
    <input type="reset" name="cancel" id="cancel" value="Cancel" />
</form>

Listing 3. The validate_upload function

function validate_upload() {
    if($('terms').checked) {
	  if($('videoFile').value.blank()) {
		  // You must specify a file!
	  	  alert('You must specify a video file to upload!');
	  } else {
		  if($('address').value.blank()) {
			 // The address can't be blank - since it used for the 
			 // video title
			 alert('You must provide a property address!');
		   } else {
			 $('title').value = $('address').value;
			 $('tag').value = "proptype=" + $('proptype').value +
						   ",price=" + $('price').value +
						   ",sqfeet=" + $('sqfeet').value +
						   ",numbedrooms=" + $('numbedrooms').value +
						   ",numbaths=" + $('numbaths').value +
						   ",yearbuilt=" + $('yearbuilt').value +
						   ",stories=" + $('stories').value +
						   ",garage=" + $('garage').value +
						   ",pool=" + $('pool').value +
						   ",fireplace=" + $('fireplace').value +
						   ",handicap=" + $('handicap').value +
						   ",lotfeatures=" + $('lotfeatures').value +
						   ",acreage=" + $('acreage').value;
		   }

		   // construct the appropriate action URL
		   <?php echo "$('videoUpload').action = 'http://uncutvideo.aol.com/api/asset/
			upload?devId=".urlencode($_SESSION['devId'])."&f=xml&a=".urlencode
($aolAuthToken)
			."&referer=".urlencode($_SESSION['succUrl'])."';\n" ?>

		   // all fields are present!
		   return true;
	   }
	} else {
		// You must agree to the standards
		alert('You must agree to the AOL Video Standards before uploading!');
	}
	return false;
  }

videoFile - The video file (which cannot be larger than 100 MB) to be uploaded.
notifyByEmail - An optional flag that will send an e-mail after the upload file has been converted and is available on the AOL Video site.
cat - A required field, which is hidden, that indicates the category of the video.
title - The required title of the video.
tag - An optional list of comma-separated values that are associated with the video.

The upload function requires that the cat and title fields be passed as part of the multi-part form data. Also required are the URL parameters: the devId, the authentication token, and the referrer URL. The referrer URL must match the URL that you indicated when you created the devId. This URL is assigned when the data describing the property has been validated by the validate_upload function.

The validate_upload function ensures that a video file has been specified, and that the address is not blank--it is assigned to the video title. If anything is missing, an alert message is displayed, and the form is not sent. The function builds the video tag list based on the property description, and assigns this to the hidden tag form field. The action for the videoUpload form is assigned in the function. This action is dynamically built using the devId, authentication token, and the referrer URL on the server side when the page is requested.

What's Next - Part 2

I deliberately kept the design of the application simple at this point so it would be easier to understand how the AOL OpenAuth and AOL Video Upload APIs work. In part two of this article, I will polish the upload functionality I've presented here and introduce the ability to search the videos that have been uploaded. The AOL Truveo API will power the video search. The Open House On Demand project will implement advanced searching features, specifically using the tags created during the upload process. Finally, I will introduce embedded playback using the AOL Video player. You can also read more about the application of AOL technologies on my blog at http://dev.aol.com/blog/25105.

Topic Centers

Submit Post