eBay Flex/Flash SDK
Flex Developer Guide
Version 607

Welcome to the eBay Flex/Flash SDK

    What Can the SDK Do for You?

    Anatomy of an ActionScript Component

Viewing SDK Samples

    Structure of a Sample

Getting Started

    What Do I Need to Know?

    Overview of the eBay API Structure

Using Flex Builder with the Flex/Flash SDK

    Concepts and General Examples

    Working With Shopping API Class Types

    Creating an Application or Widget

Deploying Your Scripts

User-Contributed Notes

Welcome to the eBay Flex/Flash SDK

The eBay Flex/Flash SDK allows you to create an interactive ActionScript 3 component that can access data on the eBay Servers. The SDK is distributed as an .swc file located in the /Lib directory of the SDK (after you have unzipped the downloadable archive .zip file).

In this guide, we will describe some general concepts for the Flex/Flash SDK, followed by information about how to use the SDK with Flex components to create a Flex application or widget.

See the Readme file for more information about specific files. See the ActionScript 3 Library Reference for descriptions of all of the SDK classes and utilities.

What Can the SDK Do for You?

The Flex/Flash SDK provides classes with methods that allow you to connect to the eBay Shopping Web Services easily and with a minimum amount of code writing. Since the SDK is object-oriented, you can re-use components from the SDK in different widgets and applications.

The SDK contains a Shopping object, that is a proxy between your application and the eBay Shopping Web Service. In addition, it has Success Callback, Failure Callback, and event handler stubs for objects that collect response and error data and bind the data to UI components, so that you can delegate low level operations, like communication and data conversion, to the SDK.

Feel free to use code from our examples and modify it to fit your applications. Note that if you are using a Shopping API call that is not in one or our samples, you will need to plan for different parameters and return data, and you will need to customize the event handlers.

The diagrams below show how you can use some of the SDK classes and methods in your application.

After you create an instance of the Shopping service class, you can invoke its methods to send requests to the Shopping Service and receive data back. The data comes back in the form of a JSON response, which is unmarshaled into Shopping return types. You can use this data as input for a table or other UI component.

The examples in this guide show you how you can use Adobe's Flex Builder 2 or 3 to create re-usable applications or widgets. Flex Builder 2 or 3 is an eclipse-based IDE that allows you to write code using a component model, so you can encapsulate your code and/or use it within other projects. However, if you know how to use the Flex SDK with another code-building tool or without an IDE, you can use these other methods as well.

Anatomy of an ActionScript Component

This section describes the basic sections that an ActionScript application or widget must contain to work successfully. As long as your script contains these elements (with the correct syntax), you can substitute other SDK calls for the ones in these examples, and you can display the results in numerous ways.

The following diagram shows the basic sections of your ActionScript code:

In the Creating an Application or Widget section of this manual, we will show you a simple ActionScript sample, to help you become familiar with the basics of eBay ActionScript widget development.

Back to Top

Viewing SDK Samples

To run a sample, paste this path into a Windows Explorer window (after you have installed the SDK):

C:\...\Samples\Flex\bin

Double-click on any .html file that is contained in the \bin directory. The sample will run because it has already been compiled using an AppId supplied by eBay.

Note: This may not work until you have Flex Builder 2 or 3 installed. See Deploying Your Scripts for more information about setting parameters.

To look at the code of a sample:

1. Download Adobe Flex Builder 2 or 3, if you don't already have it.
2. Copy the entire directory structure of the Flex/Flash SDK to your local computer.
3. File --> New --> Flex Project.
4. Select Basic radio button in 'New Flex Project' window. Click Next.
5. Enter a project name.
6. Uncheck Use default location and Browse to one of the folders in the Samples/Flex directory (such as Samples/Flex/EndingSoon). Click Next.
7. Use the Navigator pane (in the upper left corner) to drag the .mxml file for the sample (such as GetUserProfile.mxml) into your project.
8. Go to the Library path tab. Click the Add SWC button. Browse to the /Lib folder (in the unzipped SDK folder). and choose 'WDKASLib.swc'. Click the Open button. Click OK in the 'Add SWC' window.
9. Click Finish. You will see 'Loading Project' text.
10. Highlight your project name in the Navigator pane and choose the Run --> Run command.

Structure of a Sample

All of our Flex SDK Samples have a similar structure:

• Initialization function - create and initialize variables
• Success Callback function - what to do with data from a successful call
• Failure Callback function - what to do with data from a failed call
• API call function - executes the Shopping API call
• MXML UI display - how to display the data from a successful call
• ActionScript component - main class for the sample (contains class variables and import statements)

Look at the code in the Samples/Flex/FindItems directory to see how each function is created. The FindItems sample is one of the simplest samples in this SDK, and contains code comments that explain each section.

The initialization (init) function contains the variables for the FindItems API call.

private function init():void {
	appId = "eBayAPID-73f4-45f2-b9a3-c8f6388b38d8"
	queryKeywords = "ipod"

You can replace the appID, "eBayAPID-73f4-45f2-b9a3-c8f6388b38d8" in the sample with your own AppID, and you can replace the search keyword in the sample with a different keyword, if you want to customize the sample.

The Success and Failure Callback functions contain event handlers specific to the call being used, the container for response data, and the variables used to bind the data to the UI elements.

The API call function creates a request object, creates a Callback object that includes the success or failure handlers as input parameters, and then executes the FindItems call against eBay's Shopping Web Service.

The MXML file displays the eBay items that are returned by the FindItems call. For the FindItems sample, the UI display function uses the MXML DataGrid component.

It is easy to locate each of these sections in the FindItems sample code because the code has comments above each section that describe the behavior of the function. It is a good practice to review the sample code before you continue on to the next section.

Back to Top

Getting Started

This section gives you an overview of what you need to start creating your own ActionScript 3 widgets or applications, and provides links to other useful and related resources.

What Do I Need to Know?

In order to create ActionScript 3 widgets, you need an ActionScript 3 editor, such as Adobe's Flex Builder 2 or 3, an .html page, and an internet browser.

However, if you want to deploy your widgets after you create them, you will need to have access to a working .html page. This means that you will need to have a website where you can host the widget, or you will need to have someone else host your widget where you can access it through a URL.

Note that knowledge of ActionScript 3 is required to implement the function that will display your data. Some knowledge of error handling is recommended, but you can create error handling code that is similar to what is presented in the samples and tutorials.

The following table describes the resources that we have provided to help you learn about creating ActionScript 3 widgets. Click the links within the table to become familiar with any of the resources listed in the table.

Overview of the eBay API structure

eBay is continually expanding and specializing the API libraries so that developers can build applications with the exact calls they need. Currently, there are two main libraries: the Trading API (original API that uses tokens for calls) and the Shopping API (tokenless calls).

The Flex/Flash SDK gives you the ability to create scripts that retrieve data from the eBay Servers. The ActionScript objects that you will use correspond to the calls in the eBay Shopping API. This means that you can make any of the supported calls without having to include a token. However, you still have to get an Application ID (AppID) and include it in your calls to the eBay API server.

Back to Top

Using Flex Builder with the Flex/Flash SDK

As mentioned earlier, Flex Builder (version 2 or 3) is an eclipse-based IDE that allows you to write code using a component model. Like most IDEs, Flex Builder allows you to drag and drop UI components onto a widget using the design mode, and then add the event code for these components using the edit mode. This process simplifies development and allows you to create re-usable code components.

With the Flex/Flash SDK, the classes that make calls to the eBay Shopping Web Service, and classes that include the event code are already provided for you as ActionScript 3 components. To use these components, you just have to implement the classes in the SDK, build some UI components with Flex Builder, and bind the two pieces together.

The following diagram shows the specifics of this development process:

Use the following steps to create an ActionScript 3 component with Adobe Flex Builder:

1. Download Adobe Flex Builder 2 or 3, if you don't already have it.
2. Copy the entire directory structure of the Flex/Flash SDK to your local computer.
3. File --> New --> Flex Project.
4. Select Basic radio button in 'New Flex Project' window. Click Next.
5. Enter a project name.
6. Choose your project folder. Click Finish. You will see 'Loading Project' text.
7. Highlight your project name within the Navigator window, right-click, and choose 'Properties' from the drop-down menu.
8. Go to Library path tab. Click Add SWC button. Browse to /lib folder (in unzipped SDK folder) and choose 'WDKASLib.swc'. Click the Open button. Click OK in the 'Add SWC' window.
9. Create an application that uses the methods provided in the Shopping class.
10. Implement a UI function to display the returned data. This function needs to register an event handler to perform an action using the data (returned as a value object) and render it on the Flex .mxml page.
11. Highlight your project name in the Navigator pane and right-click to choose 'Run Application'.
12. Make your widget available on a web server or .html page.

Back to Top

Concepts and General Examples

The service class and all related classes are under the single package com.ebay.shoppingservice. The common, single package name matches current Flex 3 WSDL generation where a single package holds both autogenerated types as well as the service class. The service class name is Shopping. This object holds command parameters used across method invocations such as appid, siteId, and affiliate information. The Shopping class requires a ShoppingConfig object in order to initialize.

The Shopping class requires a ShoppingConfig object in the constructor and its instantiation is generalized for the ActionScript bindings:

	var config: ShoppingConfig = new ShoppingConfig({appId: ‘yourappid’, siteId: 0});
	var shopping: Shopping = new Shopping(config);
	

The following is the definition for the ShoppingConfig object:

    public class ShoppingConfig {
	  public var siteId: String;
	  public var appId: String;
	  public var trackingId: String;
	  public var trackingPartnerCode: String;
	  public var affiliateUserId: String;
	  public function ShoppingConfig(props: Object) {
	    this.siteId = props.siteId;
	    this.appId = props.appId;
	    this.trackingId = props.trackingId;
	    this.trackingPartnerCode = props.trackingPartnerCode;
	    this.affiliateUserId = props.affiliateUserId;
	  }
	}
    

The Shopping service methods match the same-named WSDL operations with the exception that they begin with a lowercase character to adhere to ActionScript common naming conventions. Each method takes an input object that corresponds to the <wsdl:input message='methodName'/> WSDL tag. For example, invoking a method that matches the WSDL operation of 'findItems' looks like the following:

	var config : ShoppingConfig = new ShoppingConfig({appId: 'yourappid', siteId: 0});
	var shopping: Shopping = new Shopping(config:ShoppingConfig);
	var request : FindItemsRequestType = new FindItemsRequestType({QueryKeywords: "ipod"});
	var callback: ShoppingCallback = new ShoppingCallback(onSuccess, onFailure);
	shopping.findItems(request, callback);
	

Note: all input is normalized to match what is exposed in the WSDL, and also matches the Flex 3 autogeneration of method inputs.

The datatypes for ActionScript follow a common naming convention and class usage. Unlike the WSDL element and enumeration names, which define most of the complexType and simpleType members, the ActionScript names have been changed to begin with a lowercase character to conform with the naming convention. However, they accept either upper or lower case for assignment. For example, the datatype AbstractRequestType contains 2 member attributes: messageID and any. Its definition is as follows:

	/**
	    @name AbstractRequestType
	    @fileOverview   Base type definition of the request payload, which can carry
	 any type of payload content plus optional versioning information and detail lev
	el requirements. All concrete request types are derived from the abstract reques
	t type. The naming convention we use for the concrete type names is the name of
	the service (the verb or call name) followed by "RequestType": VerbNameRequestType
	*/

	[Bindable]
	public class AbstractRequestType {
	  /**
	   @type String
	    If you pass a value in MessageID in a request, we'll return the same value i
	n CorrelationID in the response. If you're making a lot of calls, you can use this for
	tracking that a response is returned for every request and to match particular responses
	to particular requests. (In this case, specify a different value
	 for each request.) You can specify any value that is useful to you.
	  */
	  public var messageID: String;
	  public var any: Object;
	  public function AbstractRequestType(props: Object) {
	    this.messageID = props.MessageID || props.messageID;
	    this.any = props.any;
	  }
	}
	}
	

The following code snippet gives you an example of enumerated values for the Sort Order simple type:

package com.ebay.shoppingservice {

[Bindable]
public class SortOrderCodeType {
  public var value: String;
  public function SortOrderCodeType(object: String) {
    this.value = object;
  }
  public function toString(): String {
    return this.value;
  }
  public function getValue(): String {
    return this.value;
  }
  public static const Ascending: SortOrderCodeType = new SortOrderCodeType("Ascending");
  public static const Descending: SortOrderCodeType = new SortOrderCodeType("Descending");
  public static const CustomCode: SortOrderCodeType = new SortOrderCodeType("CustomCode");
};

}
	

Working With Shopping API Class Types

When you request data from the eBay API Servers, the servers respond with a JSON document. Then the handler function for each call parses the response and creates an Action Script 3 Value Object (also known as a data object).

Each of the value objects is described in the eBay ActionScript 3 Library Reference (see the table in the previous section for a link to the eBay ActionScript 3 Library Reference). Review the data objects to see the data that you can retrieve with your Shopping calls. Review the Shopping object (also shown in the eBay ActionScript 3 Library Reference) to become familiar with the calls you can use within your ActionScript application.

If you are unfamiliar with the eBay Shopping Web Services API, please read the following section, as well as The Shopping Web Services Getting Started Guide

Back to Top

Creating an Application or Widget

This section will describe more about steps 9 and 10 in the ActionScript 3 creation process discussed at the beginning of Using Flex Builder with the Flex/Flash SDK. Make sure you have preformed steps 1-8 before you begin writing your ActionScript 3 code.

To create an ActionScript 3 widget or application with this SDK, you will need a developer application id (AppID), If you do not already have an eBay Application ID, you can get one here.

Now you're ready to start building your application. As mentioned above, this example (from the EndingSoon.mxml sample in your Flex/Flash SDK) will show you how to use ActionScript components to create a Flash application or widget.

When you begin, the Navigator window for the EndingSoon project should look like this:

1. Open the main application file for your project (such as EndingSoon.mxml) in the Source view. You will see that the first thing you need to do is import the packages for all of the eBay Flex/Flash SDK classes that you want to use in your widget. The following code contains the import statements used in the EndingSoon example.

   	<mx:Script>
   		<![CDATA[
   			import com.ebay.shoppingservice.*;
   			import com.ebay.events.FaultEvent;
   			import com.ebay.events.Fault;
   

2. Now create a service variable and a searchTerm variable:

                           private var service:Shopping;
   			private var searchTerm:String;
   

   Then create a displayItem variable and an errorMessage variable. You can bind these two variables to UI elements directly.

   			/**
   			 * Search results
   			 */
   			[Bindable]
   			private var displayItem:SimpleItemType = null;
   			[Bindable]
   			private var errorMessage:String;
   

3. Create an onApplicationComplete function. This function will be called when your Flex application starts. In this function, we input appId and query keyword parameters, and we create a Shopping object. At the end of the function, we perform the search. The parameters are retrieved from the HTML wrapper first. If the parameters are not set in your HTML page, default values will be used. To run the sample, you should provide parameters in the HTML wrapper or set the default values in the source file.

   			private function onApplicationComplete():void {
   				var apiAppName:String = null;
   

   Make sure the function will retrieve the appId:

   			// Read parameters passed in by the HTML container using flashvars
   			apiAppName = Application.application.parameters.ebayAppId;
   			if (('' == apiAppName) || (undefined == Application.application.parameters.ebayAppId)) {
   				//replace your 'appId' here
   				apiAppName = "";
   			}
   

   Make sure the function will retrieve the query keyword (in this example, we assign the search term, "ipod" if the query keyword is undefined):

   			// if QueryKeywords was omitted from the web page, hard-code the search for "ipod"
   			searchTerm = Application.application.parameters.QueryKeywords;
   			if (('' == searchTerm) || (undefined == Application.application.parameters.QueryKeywords)) {
   				searchTerm = "ipod";
   			}
   

   Create a Shopping object using your appId as input parameter:

   			// create a ShoppingService object (so you can call SDK functions
   			// like findItems(), getSingleItem()...
   			service = new Shopping({
   				appId: apiAppName
   			});
   

   Perform the search:

   			// now that the listeners are all set, search for the items
   			performSearch();
   		}
   

   Remember to set the function name which will be called when your Flex application starts (at the beginning of your .mxml file).

   <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute"
   	width="250" height="220"
   	applicationComplete="onApplicationComplete()">
   

4. Create the method definitions. In the performSearch function, we first create a FindItemsRequestType object (fiRequest) with query keyword, item sort type, and sort order type as parameters. Then we call the findItems method of the service object and pass in fiRequest and a ShoppingCallback object as parameters.

   The constructor of ShoppingCallback takes two parameters – one is the success callback function and the other is the failure callback function. The success callback function will be called if the service call succeeds; the failure callback function will be called if the service call fails.

			/**
			 * Invoke eBay ShoppingService call to search for items
			 */
			private function performSearch():void {
				// IMPORTANT: Key values of the anonymous object should be spelled correctly
				// e.g. QueryKeywords and not queryKeywords
				var fiRequest:FindItemsRequestType = new FindItemsRequestType({
					QueryKeywords: searchTerm,
					ItemSort: SimpleItemSortCodeType.EndTime,
					SortOrder: SortOrderCodeType.Ascending
				});
				service.findItems(fiRequest, new ShoppingCallback(findItemsHandler, findItemsHandlerFailed));
			}

In the failure callback function, we set the error message label.

			/**
			 * Update some global variables with search results
			 * Look for the first item with a gallery image
			 */
			private function findItemsHandlerFailed(fault:FaultEvent):void {
				var error: Fault = fault.fault;
				errorMessage = error.faultString;
			}

In the success callback function, we first check if there are matches found for the search parameters. If not, we just return the function. If matches are found, we then find the first item that has a gallery image and display it. If none of the items has a gallery image, we just display the first item.

			private function findItemsHandler(searchResult:FindItemsResponseType):void {
				// if there were no matches, bail
				if (0 == searchResult.totalItems) {
					// No search results
					return;
				}

				// otherwise, return the first item found that has a gallery image
				for (var i:int = 0; i < searchResult.item.length; i++) {
					var item:SimpleItemType = searchResult.item[i] as SimpleItemType;
					if (null != item.galleryURL) {
						displayItem = item;
						linkButton.visible = true;
						return;
					}
				}

				// none of the items has a gallery image? okay, just return the first one
				displayItem = searchResult.item[0] as SimpleItemType;
			}

5. Implement the user interface. According to your requirements, you can use any Flex UI components to implement your UI functions. In our EndingSoon sample, we use TextArea components to show the item's title, an Image component to show the item's image, Label components to show the item's price and any error messages, and the LinkButton component to show the 'See it on eBay' link:

   	<mx:TextArea  text="{displayItem.title}"  top="10" left="10" right="10" height="40"/>
   	<mx:Image source="{displayItem.galleryURL}"  top="60" left="10" width="100" height="100"/>
   	<mx:Label text="${displayItem.convertedCurrentPrice.value}" styleName="Price" right="10" top="60"/>
   	<mx:Label text="{errorMessage}" bottom="25" left="10" />
   	<mx:LinkButton id="linkButton" label="See it on eBay" click="navigateToEbay()" bottom="10" right="10" visible="false"/>
   

   The mx code in the example above can be created using the 'drag and drop' components in the Design tab of the Flex Builder IDE.

   

   You can use the Design editor to bind objects to controls and create many different types of displays. And once you have created a display that you like, you can use it within other ActionScript 3 applications and widgets.

Deploying Your Scripts

Every time you select the Build command (or Build Automatically) within Flex Builder 2, an .swf file is created. This file is a compiled version of your project code and the Flex/Flash SDK (WDKASLib.swc) code.

Widgets

There are two ways that you can deploy your completed ActionScript widgets:
1. Upload them to a widget-hosting site, and then refer to the location from your web page.
2. Host the widgets on your own web server.

With either of these methods, you need to point to the location of the widget by adding a source tag to your .html page that contains the location of your widget.

When you are ready to make your widget available to users, add some flashVars parameters to the .html page (which points to your .swf file). These parameters include your Application ID and any other eBay parameters for your calls. Below, we use the default .html wrapper (auto-generated by Flex Builder, such as EndingSoon.html) as an example.

To ensure browser compatibility, you can add the flashVars parameters in three places:

1. The first is as a parameter of a javascript function call. This example uses the javascript function, AC_FL_RunContent:

   
   <script language="javascript">
             ...
         AC_FL_RunContent(
               ...
   	'flashVars', 'ebayAppId=YourAppId&QueryKeywords=ipod',
   	    ...
         )
             ...
   </script>
   

2. The second and third flashVars parameters are a parameter element of an object .html tag, and a property of the embed .html tag (within an object tag):

   
   <noscript>
           <object ... >
               ...
   	  <param name="flashVars" value="ebayAppId=YourAppId&QueryKeywords=ipod" />
   	    ...
   	  <embed ... flashVars="ebayAppId=YourAppId&QueryKeywords=ipod" ... />
   	    ...
   	</object>
   
   </noscript>
   

Applications

To deploy your project as a Flash Player application, put your compiled .swf file on a shared network drive or on the web where users with Flash Players can access it.

Back to Top

User-Contributed Notes

In order to leave a comment in this section, you must view the Developer Guide via the eBay web site: Flex Developer Guide - online version.

© 2008–2009 eBay Inc. All rights reserved.
eBay and the eBay logo are registered trademarks of eBay Inc.
All other brands are the property of their respective owners.