eBay Flex/Flash SDK
Flash Developer Guide
Version 607

Welcome to the eBay Flex/Flash SDK

    What Can the ActionScript Libraries 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 Flash Creative Suite 3 with the Flex/Flash SDK

    Concepts and General Examples

    Working With Shopping API Class Types

Building the 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 unzipped SDK.

You can use the libraries in the .swc file to create an .swf file that you can play on a Flash 9 player. The libraries only include ActionScript files that allow you to create an ActionScript application or widget using Adobe's Flash for Creative Suite 3. It does not include drag and drop movie components.

Note: Adobe's Creative Suite 3 includes Photoshop for CS3, Dreamweaver for CS3, and Flash for CS3. We used Flash CS3 Professional to create the Flash samples.

What Can the ActionScript Libraries Do for You?

The ActionScript libraries include classes with methods that allow you 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 would 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 which send requests to the Shopping Service and receive data back. The data comes back in the form of a JSON response, which includes data saved as Shopping Web Service return data types. Then you can use the returned data as input for a table or other UI display component.

The examples in this guide (and in the tutorials) show you how you can use Adobe's Flash CS3 to create re-usable applications or widgets. CS3 is a multi-application IDE that allows you to write code using a component model, so you can encapsulate your code and/or use it within other projects.

Anatomy of an ActionScript Component

This section describes the basic pieces 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 this manual, we will begin with an ActionScript sample, called EndingSoon as a guide, to help you become familiar with the basics of eBay ActionScript widget development.

Back to Top

Viewing SDK Samples

To run a sample, navigate to a sample directory of your Flash SDK (after you have installed the Flex/Flash SDK), for example:

C:/.../Samples/Flash/FindItems

Double-click on the .html file that is contained in the sample 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 Flash Player 9 installed and have modified your .html file to include configuration parameters (like appId and siteId). See Deploying Your Scripts for more information.

To look at the code of a sample:

1. Install Adobe's Flash CS3 and open it on your desktop.
2. From the File menu, select Open.
3. In the Open Dialog, navigate to the directory that contains the sample.
4. Make sure the .fla file is selected, and click Open
5. Within Flash CS3, click the 'edit class definition' button (button with pencil icon on the properties panel) to open the Document Class of the sample.

Structure of a Sample

All of our Flash 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
• UI display function(s) - how to display the data from a successful call
• Document class - main class for the sample (contains class variables and import statements)
• Flash (.fla) file - compiled Flash file that displays results

Look at the code in the Samples/Flash/FindItems directory to see how each function is created. The FindItems sample is one of the simplest samples in this SDK.

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 the input parameters, and then executes the FindItems call against eBay's Shopping Web Service.

The UI display function displays the eBay items that are returned by the FindItems call. For the FindItems sample, the UI display function is wrapped in a customized Flash component called ItemGrid.

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, and provides resources and links to other parts of eBay's ActionScript documentation.

What Do I Need to Know?

In order to create ActionScript 3 widgets, you need an ActionScript 3 editor, such as Adobe's Flash for CS3, 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 Flash for Creative Suite 3 with the Flex/Flash SDK

As mentioned earlier, Flash for Creative Suite 3 is an IDE that allows you to write code using a component model. Like most IDEs, Creative Suite 3 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.

Note that the ActionScript 3 components provided with the SDK are not movie modules, but are code snippets. Therefore, you have to create your application as a script, not as a movie.

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 Flash for Creative Suite 3, and bind the two pieces together.

Use the following steps to create an ActionScript 3 component with Flash for CS3:

1. Download Adobe Flash CS3, if you don't already have it.
2. Download the eBayShopping_SDK_Flex_Flash_607.full.zip file, if you don't already have it.
3. Copy the WDKASLib.swc file into the components folder of your Flash CS3 installation.
   ex, C:\Program Files\Adobe\Adobe Flash CS3\en\Configuration\Components
4. Create a new Flash file.
5. Drag the ASWDK symbol from the Standard Components list to the Library panel of the Flash project.
6. Create a new ActionScript file.
7. Make the ActionScript file as the Document Class of the Flash file
8. Implement application logic (call Shopping class functions) and UI function (display returned data) in the ActionScript file.
9. Test the Flash application in Flash CS3.
10. Publish the Flash application
11. Make your widget available on a web server or .html page.

Note: You may alternatively use the eBay ActionScript Library source for development, In that case, ignore step 3 and change step 5 to: Add eBay ActionScript Library source folder (in /Src of the unzipped SDK) to the classpath of the Flash project (PublishSettings -->Flash --> ActionScript 3.0 Settings).

Back to Top

Concepts and General Examples

This section gives you general information about the classes and types within the SDK libraries.

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, 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. As an 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);
	

The datetypes for ActionScript following the same 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 for naming conventions. 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

Building the Application or Widget

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

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.

This section will describe more about step 8 in the ActionScript 3 creation process discussed at the beginning of Using Flash for Creative Suite 3 with the Flex/Flash SDK. Make sure you have performed steps 1-7 before you begin writing your ActionScript 3 code:

1. Create a document class for your Flash file. Enter the file name (without the .as suffix) of the ActionScript file into the Document class input box. Click the pencil icon beside the input box to open the ActionScript file.

   

Import Flash components:

{
	import flash.display.Sprite;
	import flash.events.*;
	import flash.net.navigateToURL;
	import flash.net.URLRequest;

	import fl.controls.TextInput;
	import fl.controls.LabelButton;
	import fl.controls.Label;
	import fl.controls.TextArea;
	import fl.containers.UILoader;
	import flash.text.TextFieldAutoSize;

Import WDKASLib Components:

	import com.ebay.shoppingservice.*;
	import com.ebay.events.*;

Import Customized ButtonLink Component:

	import renderer.*;

Create a class that extends the Sprite component of Flash:

	public class EndingSoon extends Sprite {

2. In the properties section of the class, create a service variable and a searchTerm variable:

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

3. Create a constructor. In the constructor, we input appId and query keyword parameters, and we create a Shopping object. At the end of the constructor, we perform the search. The parameters are retrieved from the HTML page first. If parameters are not set in the HTML page, the default value will be used. To run the samples, you should provide parameters in the HTML page or set the default value in the source file.

	public function EndingSoon() {
		var apiAppName:String = null;

Make sure the constructor will retrieve the appID:

	// Read parameters passed in by the HTML container using flashvars
	var paramObj:Object = LoaderInfo(this.root.loaderInfo).parameters;
	apiAppName = Application.application.parameters.ebayAppId;
	if (('' == apiAppName) || (undefined == Application.application.parameters.ebayAppId)) {
	    //replace your 'appId' here
		apiAppName =  "<Your AppID>";
	}

Make sure the constructor 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 an input parameter:

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

Perform the search:

	performSearch();
	}

4. Create the method definitions. In 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 with fiRequest and a ShoppingCallback object as parameters.

The constructor of ShoppingCallback takes two parameters, one is success callback function, the other is failure callback function, success callback function will be called if the service calling succeeds, failure callback function will be called if the service calling 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 error message label.

	  private function findItemsHandlerFailed(fault:FaultEvent):void {
		    var error: Fault = fault.fault;
		    var errorMessage:Label = new Label();
		    errorMessage.x = 10;
		    errorMessage.y = this.width - errorMessage.height - 25;
		    errorMessage.width = 180;
		    errorMessage.text = error.faultString;
	            addChild(errorMessage);
	 }

In the success callback function, we first check if there are some match, if no, we just return, if yes, 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 one.

	/**
	 * Update some global variables with search results
	 * Look for the first item with a gallery image
	 */
      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)
						return;
				}
			}

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

5. In the displayItem function, we use some Flash UI components like TextArea, UILoader and Label, and one customized LinkButton component to show items on the UI. LinkButton is our customized component, it’s source is in: renderer/LinkButton.as.

private function displayItem(item:SimpleItemType): void {

Use the TextArea UI component to show the item's title:

           var title:TextArea = new TextArea();
				title.x = 10;
				title.y = 10;
				title.width = 180;
				title.height = 40;
				title.text = item.title;
				addChild(title);

Use the UILoader component to show the item's image:

           var gallaryURL: UILoader = new UILoader();
				gallaryURL.x = 10;
				gallaryURL.y = 60;
				gallaryURL.width = 100;
				gallaryURL.height = 100;
				gallaryURL.source = item.galleryURL;
				gallaryURL.load();
				addChild(gallaryURL);

Use the Label component to show the item's price:

           var price: Label = new Label();
				price.y = 70;
				price.x = 140;
				price.width = 30;
				price.autoSize = TextFieldAutoSize.RIGHT;
				price.text = "$" + item.convertedCurrentPrice.value.toFixed(2);
				addChild(price);

Use a modified version of the LinkButton component to display a "See it on eBay" link:

           var link : LinkButton = new LinkButton();
				link.y = 65 + gallaryURL.height;
				link.x = 100;
				link.width = 100;
				link.height = 20;
				link.label = "See it on eBay";
				link.url = item.viewItemURLForNaturalSearch;
				addChild(link);
			}
	}
}

Note: make sure you import all components (Flash UI components, ASWDK) used in the ActionScript source to the Library of the Flash project.



6. Publish your file. To publish your file, choose File -->PublishSettings-->Publish. After your file has been published, you will see three new files in the directory that contained your original .fla file. One of the files is called, "AC_RunActiveContent.js". The other two have the same name as your original .fla file, except one has a .html extension and the other has a .swf extension. The .js and .html files are wrapper files (auto-generated by Flash CS3) for publishing your .swf file on the web.

You can now double-click the .swf file to run it in your Flash 9 Player.

Deploying Your Scripts

Every time you select the Publish command within CS3, an .swf file is created. This file is a compiled version of your project code and the Flex/Flash SDK (WDKASLib.swc) code. One .js file and one .html file are also created for your convenience when publishing the .swf file on the web.

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.

If you are ready to make your widget available to users, you would 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. In the code snippet below, we use the default html wrapper (auto-generated by Flash CS3, 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 as 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: Flash 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.