eBay Shopping Web Services
Searching eBay with FindItemsAdvanced and GetUserProfile
for Adobe's Flash CS3

Introduction

In this tutorial, you will create a Flash CS3 application that searches the eBay site for a specific seller's feedback and available items, using both the FindItemsAdvanced and GetUserProfile calls.

Once you've completed a basic example with one call, such as the FindItemsAdvanced tutorial, you can expand your skills and your application's complexity. This tutorial shows how simple it is to use two calls together to create a useful application. The application allows a user to input a seller's ID to retrieve the seller's basic information and five of the seller's active listings which are ending soon. To do so, the application uses the GetUserProfile and FindItemsAdvanced Shopping API calls. When you complete this tutorial, you will have an application that looks like the following when it runs (for security reasons, user data is anonymized in the following sample). You must run the sample with your appID and an eBay user ID, and you will see the resulting information within the sample.

If the links you present to users (after making these calls) include affiliate tracking information, as described in this tutorial, you can earn money through the eBay Affiliate Program. For notes about the tutorial and the eBay Affiliate Program, see Notes and Next Steps.

Overview of the Flex/Flash SDK 2.2

Before we begin our step-by-step procedure, let's go over the basics of using the Flex/Flash SDK 2.2. With this SDK, you can design using pre-created classes that correspond to the calls in the eBay Shopping Web Service.

If you look in the /src folder in your Flex/Flash SDK, you will see these call-specific .as files. Since the detail of Shopping Web Service calls has been wrapped in these .as file, you can easily create an application that incorporates any of these calls, without writing them from scratch. Each call will instantiate the types used by that call.

Within the src/com/ebay/shoppingservice directory, you will see all of the type files used by the eBay Shopping Web Service (in the form of .as files).

Please refer to the Flash Developer Guide for general information about how to use the Flex/Flash SDK.

After running this tutorial, if you start creating your own search widgets or applications that bring traffic to the eBay web site, you can earn money through the eBay Affiliate Program. For notes about the tutorial and the eBay Affiliate Program, see Notes and Next Steps.

There are ten main steps for this tutorial:

Step 1: Set up the Flash (.fla) file

Step 2: Modify the ActionScript file

Step 3: Create the Main (Document) Class

Step 4: Create the constructor for the GetUserProfile class

Step 5: Define the FindItemsAdvanced and GetUserProfile calls

Step 6: Define the callback functions

Step 7: Define the data conversion function

Step 8: Preparations for publishing

Step 9: Publish the Flash file

Step 10: Deploying your widget

Notes and next steps

User comments

Complete sample code

This tutorial was designed to explain the GetUserProfile sample files, located within the Samples/Flash directory of your Flex/Flash SDK, and to help you create your own applications based on these samples. Some of the steps in the tutorial may include a sub-set of the code that is actually in the sample. Please compare the tutorial to the samples as you proceed.

Running an SDK sample

The SDK comes with several samples that you can run as soon as you add your appID to the .html file.

After you have downloaded and unzipped the SDK archive, you will have access to several widget samples, located in the \Samples\Flash folder. Open the GetUserProfile folder and then edit the GetUserProfile.html file using a text editor. You are going to add two new variables to the list of variables in the AC_FL_RunContent function.

        AC_FL_RunContent(
			'codebase', 'http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,0,0',
			'width', '820',
			'height', '950',
			'src', 'GetUserProfile',
			'quality', 'high',
			'pluginspage', 'http://www.macromedia.com/go/getflashplayer',
			'align', 'middle',
			'play', 'true',
			'loop', 'true',
			'scale', 'showall',
			'wmode', 'window',
			'devicefont', 'false',
			'id', 'GetUserProfile',
			'bgcolor', '#ffff66',
			'name', 'GetUserProfile',
			'menu', 'true',
			'allowFullScreen', 'false',
			'allowScriptAccess','sameDomain',
			'movie', 'GetUserProfile',
			'salign', ''
			); //end AC code

Add a comma after the last entry in the list of variables in the AC_FL_RunContent function.
Then add new flashVars variables to specify your eBay Application Developer ID, and the userID of the eBay member whose profile and Ending Soon items you would like to retrieve.
Open the modified GetUserProfile.html file in a browser, and you will see the working widget. The widget should look the same as the widget shown at the beginning of this tutorial.

You can run any of the other Flash samples in the Flex/Flash SDK by adding your appID to the .html file as shown in this section.

Before You Begin

Read the Flex/Flash SDK overview in the Readme file
Make sure you understand the concepts in the Flex Developer Guide
Complete the FindItemsAdvanced Flex Tutorial
This sample uses GetUserProfile and FindItemsAdvanced shopping API calls, and builds on the Find Items Advanced tutorial.

Before you can begin using the Flex/Flash SDK with Flash CS3, you also need to do the following:

Download Adobe Flash CS3, if you don't already have it.
Download the eBayShopping_SDK_Flex_Flash_2.2.full.zip file.
Copy the WDKASLib.swc file into the components folder of your Flash CS3 installation.
(Example: C:\Program Files\Adobe\Adobe Flash CS3\en\Configuration\Components)

Now you're ready to start building your application.

Step 1 - Set up the Flash (.fla) file

In this first step, we will create a Flash file (file with .fla extension), set up the libraries, and then create a blank ActionScript file to use as the Document Class for your .fla file. You can create a separate directory and save these files to it as you create them, or you can just create the files and Flash will save them in your default document directory ('My Documents' directory if you're using a PC).

Alternately, you can create a project file and add the .fla and .as files to the project, but we have chosen to use a simpler structure for this tutorial.

Open your Flash CS3 Application.
Choose File -->New Flash File (ActionScript 3.0) to create your .fla file.
Drag the ASWDK symbol from the Standard Components list to the Library panel of the Flash project.
Drag the Button, Label, DataGrid, and TextInput components from the User Interface folder of the Components tab to the Library panel of the Flash project. These Flash components will be used in the Document class later in this tutorial.
Choose File -->New ActionScript File to create your .as file.

When you first create the file, it will have a name like, 'Script-1'. We will change this name later to match the class name. In the next section, we will modify this ActionScript file to add the application's code.

Step 2: Modify the ActionScript file

Now we will modify the ActionScript file that will contain your calls, parse the results of those calls, and pass the retreived information to a UI display function. As with most object- oriented languages, you can create the main class and the function definitions for the class in the same file. In this tutorial, we will create the main class first, followed by the definitions for the UI functions, the call functions, the success and failure callback functions, and the data conversion function.

To enter your ActionScript code, choose the tab for the .as file and type in the following ActionScript sections to create a working application.

Let's begin by importing the packages for all of the eBay Flex/Flash SDK classes and the Flash component classes that are used by the sample we're creating in this tutorial:

    package {
    import flash.display.Sprite;
    import flash.events.*;
	import flash.display.LoaderInfo;

	import fl.controls.TextInput;
	import fl.controls.Button;
	import fl.controls.Label;

	import com.ebay.shoppingservice.*;
	import com.ebay.events.*;
	import util.eBayUtil;
	import renderer.*;

Step 3 - Create the Main (Document) class

Now let's create a GetUserProfile class which extends the Sprite component. In the variables section of the class, we create a service variable (Shopping type), and a userID variable (String type).

	public class GetUserProfile extends Sprite
		{
		    private var service:Shopping;
		    private var userID:String;

Then we create all of the other internal varibles used by the class.

            /**
			* error message
			* @type String
			*/
			private var errorMessage:Label = null;

			/**
			* top 5 items of this production
			* @type ArrayCollection
			*/
			private var sellerItems:ItemList = null;
			private var searchLabel:Label = null;
			private var searchInput:TextInput = null;
			private var searchButton: Button = null;
			private var seeAllURL:LinkButton;
			private var profile:Profile = null;
			private var userTitle:Label = null;
			private var top5: Label = null;

			/**
			* if severice call is failed
			* @type Boolean
			*/
		    private var hasError : Boolean = false;

Use the File --> Save As command to change the name of your ActionScript file to match the name of your main class (also known in Flash as the document class).

Step 4 - Create the constructor for the GetUserProfile class

Next, we will define the constructor of the class. In the constructor, we get the UserID, initialize the shopping service, initialize the UI, and then perform the search. All of the code in the constructor will be automatically called when the Document class is instantiated. It is like the 'main' function of a program.

Note: If you do not provide the userID (which can be your userID or the userID of any seller on eBay) in the HTML wrapper, then you need to uncomment the userID in the function below and set it to the userID that you want to use as the default.

	public function GetUserProfile() {

				//Read parameters passed in by the HTML container using flashvars
				var paramObj:Object = LoaderInfo(this.root.loaderInfo).parameters;
				userID = paramObj.userID;
				if (('' == userID) || (undefined == paramObj.userID)) {
					//userID = "";
				}

Then continue adding the service call and the search function:

				// get userId from index.template.html file
				// init shopping service
				service = eBayUtil.initEBayService(paramObj);

				initInterface();

				// do search
				performSearch();

		}

The UI initialization is defined in a private function called, 'initInterface'. In this function, we create some Flash UI components (like Label and Button), and some customized components (like Profile, ItemList (based on DataGrid).

Note: Before you can use these components, please make sure you have dragged the corresponding component icons from the Flash Components pane into the library of your project (as mentioned in Step 1). Please see the Samples\Flash\GetUserProfile\GetUserProfile.as file for the complete code listing used in this example.

					private function initInterface(): void {

						userTitle = new Label();
						userTitle.text = "Items for Sale by Seller";
						eBayUtil.setLabelFormat(userTitle, 14);
						userTitle.x = 10;
						userTitle.width = 800;
			            addChild(userTitle);

						profile = new Profile(this);

						top5 = new Label();
						top5.text = "Top 5 Listings Ending Soon:";
						eBayUtil.setLabelFormat(top5, 14);
						top5.width = 800;
						top5.x = 10;
			            addChild(top5);

						sellerItems = new ItemList();
			            sellerItems.x = 10;
			            sellerItems.width = 800
			            sellerItems.rowCount = 0;
			            addChild(sellerItems);

						searchLabel = new Label();
						searchLabel.x = 330;
						searchLabel.width = 40;
						searchLabel.text = "User ID:";
						addChild(searchLabel);

						searchInput = new TextInput();
						searchInput.x = 375;
						searchInput.width = 80;
						addChild(searchInput);

						searchButton = new Button();
						searchButton.label = "Go";
						searchButton.x = 460;
						searchButton.width = 40;
						searchButton.addEventListener(MouseEvent.CLICK, onSearchClick);

						addChild(searchButton);

						seeAllURL = new LinkButton();
						seeAllURL.label = "See All Items for this Seller";
						seeAllURL.fontSize = 14;
						seeAllURL.x = 10;
						seeAllURL.width = 320;
						seeAllURL.height = searchLabel.height;
			            addChild(seeAllURL);

						adjustHeight();
					}

					.
					.
					.
		}

Step 5 - Define the FindItemsAdvanced and GetUserProfile calls

Now we will implement the definitions for the performSearch function. The following steps are performed within this function:

Create a GetUserProfileRequestType object with a specific userID.
Create a ShoppingCallback object with a success callback function (getUserProfile, in this example), and a failure callback function (getUserProfileFailed) as parameters.
Make a getUserProfile call to the eBay Shopping Web Service with the GetUserProfileRequestType object and ShoppingCallback object (created above) as parameters.
Create a FindItemsAdvancedRequestType object with a specific userID and maxEntries. In our example, we use 5 maxEntries.
Create a ShoppingCallback object with a success callback function (onSomeItemsReturned in this example), and a failure callback function (onSomeItemsReturnedFailed in this example) as parameters.
Make a findItemsAdvanced call to the eBay Shopping Web Service with a findItemsAdvancedRequestType object and ShoppingCallback object as parameters.

The GetUserProfile call is responsible for getting a user's details, and the FindItemsAdvanced call is responsible for getting five of the user's items that are ending soon. In the example below, you can see that you can use minimal code to interact with the eBay Shopping Web Service, because of the SDK.

/**
		 * search seller by user id, call FindItemsAdvanced to get seller's top 5 items
		*/
		private function performSearch():void {
			hasError = false;

			// new GetUserProfileRequestType
			// IncludeSelector is Details,FeedbackHistory, inlcude feedback history and details.
			var fiRequest:GetUserProfileRequestType = new GetUserProfileRequestType({
				userID: userID,
				includeSelector: "Details,FeedbackHistory"});
			// call service function, getUserProfile is callback function on success, and getUserProfileFailed is callback function on failure
			service.getUserProfile(fiRequest, new ShoppingCallback(getUserProfile, getUserProfileFailed));

			// new FindItemsAdvancedRequestType
			// itemSort is EndTime ,sort by endtime.
			// itemType is AllItemTypes, return all types
			// maxEntries is 5, top 5 items
			var request:FindItemsAdvancedRequestType = new FindItemsAdvancedRequestType({
				sellerID: userID,
				itemSort: SimpleItemSortCodeType.EndTime,
				itemType: ItemTypeCodeType.AllItemTypes,
				maxEntries: 5});
			// call service function, onSomeItemsReturned is callback function on success, and onSomeItemsReturnedFailed is callback function on failure
			service.findItemsAdvanced(request,new ShoppingCallback(onSomeItemsReturned, onSomeItemsReturnedFailed));

		}

Step 6 - Define the callback functions

The failure callback function will be called if the service call fails, and the success callback function will be called if the service call succeeds. Below, we show the details of the callback functions used in this sample. The failure callback function displays an error message to the UI. The success callback function displays the user profile and item data (returned by the eBay Shopping Web Service) to the UI. Please see the Samples\Flash\GetUserProfile\GetUserProfile.as file for the complete code listing used in this example.

	/**
			* callback function when FindItemsAdvanced is failed
			* display error message	and clear previous items.
			* @param {mx.rpc.events.FaultEvent}
			*/
			private function onSomeItemsReturnedFailed(fault:FaultEvent):void {
				hasError = true;
				var faultMessage:Fault = fault.fault;
				showErrorMessage(faultMessage.faultDetail);
				sellerItems.dataProvider.removeAll();
				sellerItems.rowCount = 0;
				adjustHeight();
			}

			private function showErrorMessage(message:String) {
				if (errorMessage == null) {
					errorMessage = new Label();
					errorMessage.x = 10;
					errorMessage.width = 800;
					addChild(errorMessage);
				}
				errorMessage.text = errorMessage.text + message;
			}

			/**
			* callback function when FindItemsAdvanced is success
			* display items
			* @param {com.ebay.shoppingservice.FindItemsAdvancedResponseType}
			*/
			private function onSomeItemsReturned(data:FindItemsAdvancedResponseType):void {

				if(data.ack.value != AckCodeType.Success.value) {
				   return;
				}

				if (!hasError && errorMessage != null) {
					this.removeChild(errorMessage);
					errorMessage = null;
				}

				if (0 == data.totalItems) {
					sellerItems.dataProvider.removeAll();
					sellerItems.rowCount = 0;
				} else {
					sellerItems.dataProvider.removeAll();
					var items: Array = convertData4ItemListUI(data);
					sellerItems.dataProvider.addItems(items);
					sellerItems.rowCount = items.length;
				}
				adjustHeight();
			}

			/**
			* callback function when GetUserProfile is failed
			* display error message and clear previous user profile.
			* @param {mx.rpc.events.FaultEvent}
			*/
			private function getUserProfileFailed(fault:FaultEvent):void {
				hasError = true;
				var faultMessage:Fault = fault.fault;
				showErrorMessage(faultMessage.faultDetail);
				userTitle.text = "Items for Sale by Seller";
				seeAllURL.url = null;
				profile.clear(this);
				adjustHeight();
			}

			/**
			* callback function when GetUserProfile is success
			* display user profile
			* @param {com.ebay.shoppingservice.GetUserProfileResponseType}
			*/
			private function getUserProfile(data:GetUserProfileResponseType):void {

				if(data.ack.value != AckCodeType.Success.value) {
				   return ;
				}

				if (!hasError && errorMessage!=null) {
					this.removeChild(errorMessage);
					errorMessage = null;
				}

				if (data.user == null) {
					profile.clear(this);
				} else {
					convertData4ProfileUI(data);
					userTitle.text = "Items for Sale by Seller " + userID;
					seeAllURL.url = getSellerItemsURL(data);
				}
				adjustHeight();
		}

Step 7 - Define the data conversion function

We need to convert the returned data into a format suitable for UI display before we bind it to a UI component. The following function shows the conversion for the user profile data. After the data is converted, we will bind it to the profileUI component (that was created for this tutorial).

		/**
				* set data required by profileUI. these data is from GetUserProfileResponseType
				* @param {com.ebay.shoppingservice.GetUserProfileResponseType}
				*/
				private function convertData4ProfileUI(data:GetUserProfileResponseType): void {
					var user:SimpleUserType = data.user as SimpleUserType;
					var imageURL:String = null;
					if (user.myWorldSmallImage) {
						imageURL = user.myWorldSmallImage;
					}
					var title:Link = createLinkObject("", "Seller: " + user.userID,user.myWorldURL);

					var specs:Array = new Array();
					var i:int = 0;
					var nameValue:Object = null;

					var score:int = user.feedbackScore;
					var scoreValue:Object = null;
					if (data.feedbackHistory) {
						score = data.feedbackHistory.uniqueNegativeFeedbackCount + data.feedbackHistory.uniquePositiveFeedbackCount;
						nameValue = createLinkObject("Feedback Count: ",score + "",user.feedbackDetailsURL);
						specs.push(nameValue);
						nameValue = createLinkObject("Positive Feedback Percentage: ",
							(data.feedbackHistory.uniquePositiveFeedbackCount/score* 100.0).toFixed(2) + '%' + "",null);
						specs.push(nameValue);
					} else {
						nameValue = createLinkObject("Feedback Count: ",score + "",user.feedbackDetailsURL);
						specs.push(nameValue);
					}
					nameValue = new Object();
					nameValue = createLinkObject("Member Since: ",eBayUtil.toDateString(user.registrationDate),null);
					specs.push(nameValue);

					if (user.storeName) {
						nameValue = new Object();
						nameValue = createLinkObject("Store Name: ",user.storeName,user.storeURL);
						specs.push(nameValue);
					}

					profile.reload(imageURL, title, specs, this);

				}

				/**
				* create link object, Key: URL
				* @param {String} key: label
				* @param {String} value: url title
				* @param {String} url: url
				* @return {Link} link object
				*/
				private function createLinkObject(key:String, value:String, url:String) : Link {
					return new Link(key, value, url);
				}

The following function converts the data for the user's ending soon items.

/**
				* Get top 5 items
				* @param {com.ebay.shoppingservice.FindItemsAdvancedResponseType}
				* @return {Array} items
				*/
				private function convertData4ItemListUI(data:FindItemsAdvancedResponseType): Array {
					if (data.searchResult) {
						var itemArray:SimpleItemArrayType = data.searchResult[0].itemArray;
						var count:int = itemArray.item.length > 5? 5: itemArray.item.length;
						var items:Array = new Array(count);
						for (var i:int = 0; i< count; ++i) {
							items[i] = itemArray.item[i];
						}
						return items;
					}
					return new Array();
				}

		    }
}

Step 8 - Preparations for publishing

With the Flash application, the File -->Publish command performs the build function. You can alternately use the Properties panel to Publish, by clicking Settings and then Publish (while your .fla file is selected). Before you Publish, you may need to change the security setting from 'Local playback security' to 'Access network only' so that your application can access the eBay Shopping Service.

Before you publish your application, you must copy the \util and \renderer folders from the Samples\Flash\GetUserProfile directory of your SDK to the folder where your .fla and .as files are located.

Within the \util folder, there is a file named, 'eBayUtil.as'. Modify this file to include your appID (required), siteID (optional), trackingID (optional), trackingPartnerCode (optional), and affiliateUserID (optional).

public static function initEBayService(paramObj:Object):Shopping {
		var apiAppName:String = null;
		var trackingID:String = null;
		var trackingPartnerCode:String = null;
		var affiliateUserID:String = null;
		var siteID:String = null;
		var service:Shopping;
        //Read parameters passed in by the HTML container using flashvars
		apiAppName = paramObj.ebayAppId;
		if (('' == apiAppName) || (undefined == paramObj.ebayAppId)) {
			//replace your 'appId' here
			apiAppName = "yourappid";
		}

Step 9 - Publish the Flash (.fla) file

Now you're ready to publish the application from within Flash CS3. Make sure that the tab for the .fla file is selected, and modify the settings in the Properties tab.

Set the Document class to the name of your ActionScript file (without the file extension). For this tutorial, the Document class should be 'GetUserProfile'.

Use the Properties panel to Publish - by clicking Settings and then Publish (while your .fla file is selected), OR choose the File -->Publish command.

Step 10 - Deploying your widget

When you publish your application, Flash CS3 creates an .swf file, and an .html file, in addition to your .fla and .as files.

If you haven't added parameters (like appID) in the eBayUtil.as file mentioned above, you can still pass these parameters into the .swf file using flashVars.

If your (and your customer's) browser supports JavaScript (which is the normal case), you only need to add flashVars in the 'AC_FL_RunContent' JavaScript function call. [This is the same as the example in Running an SDK Sample above.]


	    AC_FL_RunContent(
			'codebase', 'http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,0,0',
			'width', '820',
			'height', '950',
			'src', 'GetUserProfile',
			'quality', 'high',
			'pluginspage', 'http://www.macromedia.com/go/getflashplayer',
			'align', 'middle',
			'play', 'true',
			'loop', 'true',
			'scale', 'showall',
			'wmode', 'window',
			'devicefont', 'false',
			'id', 'GetUserProfile',
			'bgcolor', '#ffff66',
			'name', 'GetUserProfile',
			'menu', 'true',
			'allowFullScreen', 'false',
			'allowScriptAccess','sameDomain',
			'movie', 'GetUserProfile',
			'salign', '',
			'flashVars','ebayAppId=YourAppId&userID=YourUserId'
			); //end AC code
	...
	</script>

To increase your compatibility with different types of browsers, you can add two additional flashVars: one as a parameter of an element of an object html tag, and another as a property of the embed html tag (within an object tag):

	...
	<script language="JavaScript" type="text/javascript">
	<noscript>
		<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
			id="GetUserProfile" width="100%" height="100%"
			codebase="http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab">
			<param name="movie" value="GetUserProfile.swf" />
			<param name="quality" value="high" />
			<param name="bgcolor" value="#869ca7" />
			<param name="allowScriptAccess" value="sameDomain" />


			<embed src="GetUserProfile.swf" quality="high" bgcolor="#869ca7"
				width="100%" height="100%" name="GetUserProfile" align="middle"
				play="true"
				loop="false"
				quality="high"
				allowScriptAccess="sameDomain"
				type="application/x-shockwave-flash"
				pluginspage="http://www.adobe.com/go/getflashplayer">
			</embed>
		</object>
	</noscript>

You should now be able to double-click the .swf file and run your application in Flash Player 9, or double-click the .html file to run the widget within a browser.

Note: as a best practice, we recommend that you save a copy of your .html file after you have modified it, because if you update your application and use the Publish command again, a new .html file will over-write the one that contains your appID.

Congratulations! You now have a working application that uses eBay Shopping Web Services.

Notes and next steps

This section contains observations about this tutorial and offers some alternate ways to achieve similar or better results. We've also provided some suggestions about where you can go from here.

eBay Affiliate Program

The eBay Affiliate Program allows you to earn money by driving traffic to the eBay site using applications or widgets you create and post on your own web page. You can think of this as a way to enhance your existing business or create a new enterprise. With just a little effort, you can earn a lot of money.

Now that you have a working search application, you can earn money with the eBay Affiliate Program! Join the affiliate program now!

Once you have joined the eBay Affiliate Program, sign up for the Affiliate API Tier of the eBay Developers Program.

About the application

As noted at the beginning of the tutorial, we tried to keep things simple. The eBay community codebase contains many excellent samples that are more complex and many give you good ideas for ways to design your applications.

The sample provided with this tutorial was built and tested on a Windows 2003 Server platform using JS for Win32 and Microsoft IIS 5.0.

About the call

For the tutorial, we took a minimalist approach to input parameters. The GetUserProfile call is very powerful. It supports numerous input parameters, and the query supports AND/OR logic and wildcards. Visit the Flash Developer Center for links to documentation and additional information.

Additional resources

Here's a list of resources for the topics and technologies introduced in this tutorial:

User-Contributed Notes

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

eBay Shopping Web Services Searching eBay with FindItemsAdvanced and GetUserProfile for Adobe's Flash CS3