The Truveo Video Search XML API supports two classes of methods, video methods and user methods. The video methods provide basic functionality for submitting queries to the Truveo video search engine and retrieving search results. The user methods provide functionality for letting individual users customize their own search experience. Since the video methods offer no personalization functionality, they can be used without performing any user authentication. In order to take advantage of the functionality provided by the user methods however, each user must have a valid AOL or AIM screen name and be signed in to his or her AOL or AIM account. The Truveo video search API provides the necessary methods for performing this user authentication, and this document provides an overview about how these methods can be used.

Before you can begin developing applications using the Truveo Video Search XML API, you must first create an API account. To view your existing API account or create a new one, please refer to the My API Account page. When your API account is created you will be assigned an Application ID, or appid, which is a key that uniquely identifies your application and authorizes it to access the Truveo Video Search APIs. In addition to the Application ID, you will also be assigned a Shared Secret. This Shared Secret is unique key that is tied to your Application ID, and it is used to verify that your application is permitted to access the XML API user methods. More specifically, this Shared Secret is used to create a unique signature, which must be submitted with each call to the XML API user methods. The procedure for creating this signature is described below.

The user methods of the Truveo video search XML API are available only to users who have signed in to their AOL or AIM accounts. Therefore, if you are building an application that allows users to save and view their favorite videos, recent videos and watchlists, you must first provide a mechanism for each user to sign in to his or her AOL or AIM account. The XML API provides a method for this purpose called truveo.users.login.

The process for allowing users to sign in to your application typically begins with placing a 'Sign In' or 'Log In' button in your web page. In order to access the XML API user methods, this button should invoke the truveo.users.login method by redirecting the user's browser to the following URL: As shown above, this URL must include three parameters: method, appid and callback_url. The method parameter should be set to the name of the login method, which is 'truveo.users.login'. The appid should be set to your assigned Application ID value, and the callback_url should be the URL of the page where you would like your application to be redirected once the user has finished with the sign in process.

When a user clicks the button that invokes the login URL above, this URL will redirect the user's browser to the AOL or AIM account sign in page where the user will be prompted to enter his or her screen name and password. If the user does not yet have an AOL or AIM account, a link will be available for the user to create a new account. If the user wishes to cancel the sign in process, they can select the 'cancel' button. Once the user has completed the sign in process, the user's browser will be redirected to the URL specified by the callback_url parameter that was submitted in the URL above.

There are four specific outcomes of the user login process that should be handled by the application which invoked the truveo.users.login method. These four outcomes are (1) login successful, (2) login cancelled, (3) user already logged in, and (4) login error. For each of these four outcomes, the callback_url sent to the user's browser will be appended with one or two parameters indicating the nature of the outcome. Assuming, for example, that the callback_url submitted to the truveo.users.login method was http://www.mysite.com/index.html, the callback_url returned for each of the four login outcomes will be as described below:

The login is successful when the user submits a valid AOL or AIM screen name and password. In this case, the user's browser will be redirected to the following callback_url: As shown, this callback_url has been appended with the parameter 'auth', which has been assigned a specific value. This auth parameter is uniquely associated with the current user as well as your assigned Application ID value. Additionally, only one auth per application per user can be valid at any one time. Once this auth parameter has been received by your application, it can be used to authenticate the current user with the Truveo Video Search XML API using the truveo.users.getToken method. The auth parameter will remain valid for 60 minutes from the time it was created or until the truveo.users.getToken method is called, whichever is sooner. As described in the XML API reference documentation, the truveo.users.getToken method can be invoked with the following URL: The required parameters for the truveo.user.getToken method include the method name, appid, and auth as well as a unique signature, sig, that is generated using your Shared Secret. The procedure for creating this unique signature is described below. If the authentication token provided is valid, this method will return an XML response containing a user token that can be used by your application to uniquely identify the current user to the Truveo Video Search API methods. For many applications, it is customary to store this user token in a session variable or cookie. For more details on handling user tokens, please consult the section on user tokens below. Please consult the reference documentation for more details on using the truveo.users.getToken method.

If the user aborts the login process by clicking the 'cancel' button during a login attempt, the user's browser will be redirected to the following callback_url: As shown, this callback_url has been appended with the parameter 'loginCancel', which has been assigned a value of 'true'. In order to properly handle this outcome, your application should check for the 'loginCancel' parameter and take the appropriate action if this parameter is received.

This outcome can occur if the following three conditions are met: (1) the user has already successfully competed the login process, (2) the application has already received a user token, and (3) the user token has not expired. If this occurs, any call to the truveo.users.login method will not redirect the user's browser to the AOL and AIM account sign in page. Instead, this method will redirect the user's browser directly to the following callback_url: As shown, this callback_url has been appended with the parameter 'token', which is assigned the value of the currently valid user token. If this parameter is present, then the user is already logged in, and the provided user token value can be used to access the user methods of the XML API.

If, for some reason, an error occurs during the login process, the user's browser will be redirected to the following callback_url: As shown, this callback_url has been appended with the parameters 'errorCode' and 'errorMessage'. The errorCode is assigned the numerical code associated with the error and errorMessage is assigned the corresponding text message that describes the error. In order to properly handle any errors that may occur, your application should check for the 'errorCode' parameter and take the appropriate action if this parameter is received. For a list of the errors that can be returned for each XML API method, please consult the reference documentation.

Any application that allows users to sign in using their AOL or AIM accounts should also provide a mechanism for letting users sign out. This is typically done by providing a 'Sign Out' or 'Logout' button in your web application. When the user clicks this button, your application should sign the user out of his or her AOL or AIM account. This can be done by invoking the truveo.users.logout method using the following URL: As described in the documentation for this method, this URL must include three parameters: method, appid and logout_callback_url. The method parameter should be set to the name of the login method, which is 'truveo.users.logout'. The appid should be set to your assigned Application ID value, and the logout_callback_url should be the URL of the page where you would like your application to be redirected once the user has finished with the sign out process. The logout_callback_url should be in the same domain as the client application. When the user's browser is directed to that URL, the application should take the necessary steps to change the state of the logged in user, such as removing cookies containing tokens, ending sessions, and indicating to users that they are no longer logged in.

A valid user token is required in order to call any of the XML API methods that allow users to access their personal information. A user token can only be retrieved after a user has successfully logged in to their AOL or AIM account. Each user token is uniquely associated with each user as well as your assigned Application ID. User tokens may only be used with the Application ID to which they are assigned, and only one token per application per user is valid at any one time.

Once a user token has been assigned, it will remain valid for a maximum of 30 days or until the user logs out of your application using the truveo.users.logout method. When a user token expires or becomes invalid, any subsequent API method calls using that token will return an 'invalid token' error. Therefore, your application should check periodically to determine if each user token is still valid using the truveo.users.checkToken method. It is good practice to perform this check at least once per browser session. If the truveo.users.checkToken method indicates that a user token is invalid, your application can obtain a valid token by redirecting the user through the login process.

For every method of the XML API that allows users to access their personal information, a parameter called 'sig' is required. This parameter must contain a unique signature that is generated using the Shared Secret assigned to your API account. The following example illustates the procedure for creating this signature.

Let us say that you would like to make a call to the truveo.users.getFavoriteVideos method of the XML API and that your API account has been assigned a Shared Secret and appid value of 'MY_SECRET' and "MY_APPID", respectively. Let us also say that the user of your application has already completed the sign in process and retrieved a valid user token with the value USER_TOKEN. In order to invoke the truveo.users.getFavoriteVideos method, you can construct its URL as follows: As you can see, the final argument to this URL is the sig parameter. The value of this sig parameter must be constructed using the Shared Secret along with the other parameters that you intend to submit in the XML URL. To create this sig parameter, first sort all of the parameters in your XML URL alphabetically by parameter name, excluding the sig parameter. This will yield the following parameter list: Now create a string by concatenating the Shared Secret value with all of the parameter name-value pairs in alphabetical order, as listed above. This will yield the following string: Note that, while the string displayed above contains a carriage return, the string used to generate the signature should not contain any carriage returns or line breaks. To create the signature, simply take the MD5 hash of this string, which will yield the value '4136897c45139ae0f10972b54b98648c'. This signature can then be used as the value for the sig parameter which is submitted as part of the XML URL for the truveo.users.getFavoriteVideos method: This procedure for generating unique signatures can be applied to every method of the XML API that requires a sig parameter.

This simple example will illustrate how you can use the functionality of the Truveo Video Search XML API to allow a user to retrieve a list of his or her favorite videos. For the purposes of this example, assume that you are building an application that will be located at the URL http://www.mysite.com. Also assume that you have created a Video Search API Account and have been assigned an appid with a value of MY_APPID and a Shared Secret with a value of MY_SECRET.

The first step to let a user access his or her favorite videos is to offer the user the option to sign in to his or her AOL or AIM account. This sign in process begins when the user clicks the 'Sign In' link on your web site. This link will then call the truveo.users.login method of the XML API with the following URL: At this point, the user's browser will be redirected to the AOL or AIM account login page, and the user will be prompted to enter his or her screen name and password and hit return. Once the user's screen name and password have been authenticated, the user's browser will then be redirected to the URL http://www.mysite.com/callback.php?auth=MY_AUTH. This URL consists of the callback_url, originally submitted in truveo.users.login method above, followed by an auth parameter set to a value of MY_AUTH. The auth parameter indicates that the user login was successful, and the value of this parameter can now be used to obtain a user token.

The callback.php file should execute a server-side script that retrieves the value of the auth parameter from the callback URL and then calls the truveo.users.getToken method to obtain a user token. The truveo.users.getToken method can be invoked with the following URL: Note that, following the procedure outlined above for creating a signature, the value of sig for this method was created by taking the MD5 hash of the following string: MY_SECRETappidMY_APPIDauthMY_AUTHmethodtruveo.users.getToken. If called correctly, this REST-style call will return an XML message containing a valid user token. For the purposes of this example, assume that the value of this user token is USER_TOKEN.

Once the user token has been received by the callback.php script, this script can then establish a user session and store the user token in a session cookie. With the user session established, the callback.php script can then retrieve a list of the user's favorite videos by invoking the truveo.users.getFavoriteVideos method with the following URL: This XML API call will return an XML-formatted response that will contain a list of the user's favorite videos. This list can then be used to generate the appropriate page that can be displayed in the user's browser.