Getting an Application Running in the Sandbox

Getting Your Application into Production

Processing the Render URL

Authentication and Processing Requests from eBay

Verifying a Digital Signature

Decrypting to Obtain User Information

Preparing Your Deployment Descriptor

Gadgets Features

Supported Gadgets Libraries

Making Calls from HTML Gadgets

User Preferences

Submitting Your Apps Center Entry

Guidelines for Listing and Inventory Apps

Getting an Application Running in the Sandbox

This section describes how to quickly initiate a basic application in the sandbox environment. Please also see Preparing Your Deployment Descriptor.

Getting Generic Sandbox Keys

You need generic sandbox keys in order to get keys for an Open eBay app. You can obtain generic sandbox keys on the My Account page.

Preparing and Uploading Your Sandbox Deployment Descriptor

Download the sample deployment descriptor and the deployment descriptor schema file. (If you already have done an initial upload of a deployment descriptor, download your existing deployment descriptor from the Embedded Applications tab, instead of using the sample deployment descriptor, and then after making any revisions you need, skip to Initially Subscribing a Sandbox User to Your Application.)
Review the latest information, in the SM Apps forum and Developer Tools announcements, about preparing and uploading your sandbox deployment descriptor. If you want to learn more about deployment descriptors at this stage, see Preparing Your Deployment Descriptor.
Revise the sample deployment descriptor. In the id attribute of the OEApplication tag, specify a unique web location in your company's domain (in the form of myapp.mycompany.com). In any future changes to the deployment descriptor, this unique value cannot be changed because it becomes your AppID in the sandbox keys issued for your application. However, you can use a different value for your production deployment descriptor when you are ready to submit one. Please note:

The value you provide in the id attribute of the OEApplication tag can be a non-functional web location. After you submit a sandbox deployment descriptor, you can change many values you specified, but you cannot change the value originally specified in the id attribute.
The same AppID can be used in both the sandbox and production environments, but you cannot use the same AppID for multiple Open eBay apps. Keysets must not be shared between applications.
The application-display name that you provide for sellingmanager.msg.application.applicationName can be up to 25 characters.
Your keyset for your Open eBay app is always distinct from your keyset for your Trading application.
It is recommended that to subscribe your first test user, you utilize the User Management tool.

Go to the Open eBay Apps overview in the My Account page, Embedded Applications tab. The Embedded Applications tab is a self-service tool that includes functionality for managing users' subscription states while you build your application and subscription (OEPI) listener.
On the Embedded Applications tab, click Create New Sandbox Application.
In the Permission tag of your deployment descriptor, no matter the setting of the Public attribute, you must include all users whom you expect to subscribe. For example:
```
	<Permission public="true">
	  <User id="TESTUSER_yourSandBoxUsername"/>
	</Permission>	  
```
Note that you can set the Public attribute to true or false. If you specify true, all sandbox users can view your application, but subscribing a user nevertheless requires that the user is within the Permission tag. (And if you specify false, users specified in the Permission tag can view and subscribe).
Use an XML tool such as Notepad++ to confirm that your deployment descriptor is valid against the deployment descriptor schema file.
On the My Account page, Embedded Applications tab, upload your deployment descriptor. In the cases of both the sandbox and production, you can upload a maximum of one deployment descriptor. For production applications only: After a production application is approved, you cannot change the deployment descriptor.

Retrieving Your Sandbox Keys

You need sandbox keys specific to your Open eBay app. On the My Account page, find the keyset that contains the AppID you specified in your deployment descriptor (in the id attribute of the OEApplication tag; it ends with .com).

Initially Subscribing a Sandbox User

Create a new sandbox user, who is specific to the US site. If necessary, you can change the site of an existing sandbox user.
If your app uses Selling Manager functionality, subscribe the sandbox user to Selling Manager (My eBay > Account Tab > Subscriptions).
Make sure the Implements tag in your deployment descriptor is empty. (When the Implements tag is empty, no subscription listener is needed for testing your application's user interface).
```
	<Implements>
	</Implements>
```
Add the new sandbox user to the Permission tag in the deployment descriptor, and save the file. On the Embedded Applications tab, upload the the deployment descriptor.
On the Embedded Applications tab, click the subscribe link and subscribe your sandbox user to your application. Wait for about one minute.
On the Embedded Applications tab, under Sandbox Applications, click the link next to Active Subscribers. The User Management tool is displayed, enabling you to retrieve the user and change the user's status to Active. The User Management tool is run when you click the Search button. Users are retrieved based on criteria that you specify in the tool. You can retrieve subscribers by any of the criteria used by the tool (Status, etc.).
On the sandbox user's Applications tab (in My eBay), begin testing the functionality of your application.

Managing Your Sandbox Application

You can use the Embedded Applications tab of the My Account page to download your existing deployment descriptor, update it, and otherwise manage your Open eBay app. You also can use the tab to manage user subscriptions.

After you submit your sandbox deployment descriptor, your application is, by default, in an Approved state for the sandbox.

Testing a Subscription Listener in the Sandbox

Instructions for the production environment are similar to these instructions; see Initializing Testing of a Production Listener, including for information about the User Management tool.

Note: You may want to avoid receiving subscription calls (e.g., addSubscriber calls) from eBay. The Implements tag in the deployment descriptor has a default value of subscription, which means that eBay sends subscription calls to your application. Leave the tag empty if your application has not implemented a subscription listener, and eBay will not send your application any subscription calls.

See the deployment descriptor sample here: sample-DD.xml. Before following the steps below, make sure you have added your sandbox user to the deployment descriptor.

When the Implements tag in the deployment descriptor is empty, no subscription listener is necessary for your testing in the sandbox. (See Enabling Subscription regarding the subscription listener.)

However, if you are creating a subscription listener, you can do the following procedure to begin testing it. During the procedure, do not unsubscribe a user; that would put the user in a cancel-pending state, requiring that you manually change the user's status (using the Embedded Applications tab).

Enable your subscription listener.
In your deployment descriptor, add the subscription feature, within the Implements tag:
```
	<Implements>
	  <Feature name="subscription"/>
	</Implements>
```
Upload the revised deployment descriptor.
From the Embedded Applications tab, click the subscribe link and subscribe your sandbox user to your application.
Wait for about one minute and refresh the browser window that contains the Embedded Applications tab.
If the user is active, your subscription listener has correctly responded to the addSubscriber call from eBay.
If the user is not active, your subscription listener hasn't correctly responded to the addSubscriber call from eBay. You must fix your subscription-listener code (e.g., your addSubscriber-listener code) and do the following test:
- From the Embedded Applications tab, in the User Management tool (accessible through the link next to Active Subscribers), manually change the user's status from pending to active. This resends an addSubscriber call. Note that a message on the Embedded Applications page of "Success, status was changed" doesn't indicate that the user's state necessarily was changed; the message on the page just means that an addSubscriber call was sent.
- Wait for about one minute and refresh the browser window.
- If the user is active, your subscription listener has correctly responded to the addSubscriber call from eBay.
- If the user is not active, fix your code and repeat the test. The test also can be used for other subscription listeners, e.g. a removeSubscriber listener.

Please note that when the subscription feature is in your deployment descriptor, then if a subscription state stays in Pending for more than 5 minutes after a user subscribes, it's likely that eBay was unable to reach your listener with an addSubscriber request, or your listener's response was not as expected. If a user's subscription state is in Pending, you can cause eBay to resend the addSubscriber request by setting the user to Active in the User Management tool (accessible in the Embedded Applications tab, through the link next to Active Subscribers).

Important: If your subscription remains stuck in either a pending state or a cancelled state, you can "force" a change in the subscription state. To do so, upload a deployment descriptor with an empty Implements tag. Then, on the Embedded Applications tab, manually change the subscription state. Also see Attempting to Re-Subscribe to an Open eBay app.

Getting Your Application into Production

Please see all the sections below for the steps for moving your application into production and enabling users to subscribe to your application.

Develop in the Sandbox and Complete a Business Readiness Review

Get your application running in the sandbox. This includes uploading a sandbox deployment descriptor and submitting a subscription plan. See the steps in Getting an Application Running in the Sandbox.
Ensure that your business meets the Participation Requirements. These requirements are part of Open eBay Appss--Participation Requirements.
Complete the Questionnaire for the Business Readiness Review.

You need a Business Readiness Review before eBay allows you to move your application to production. This includes, but is not limited to, a review of your hosting infrastructure, business processes, billing plans, and data security policies. eBay wants to be sure that you have the infrastructure in place to provide our mutual customers with a stable, available, and secure service.
Please purchase one hour of support from Developer Technical Support.
Use the purchased support for a support request. In the support request, submit the completed Questionnaire. Along with the questionnaire, submit a subscription plan.
Please title the support request as follows: "Request for Business Readiness Review."

Await review and approval of your Business Readiness request. A team of reviewers at eBay will review your application and get back to you within three business days, noting any requests for clarification, or changes.

Prepare Your Deployment Descriptor for Upload to Production

Most procedures involving the deployment descriptor are the same for sandbox and production. Thus, for basic information about downloading a sample descriptor, modifying it, and uploading it, please see the sandbox instructions.

Before the initial upload of your deployment descriptor, please do the following:

Specify a production App ID in the deployment descriptor. The App ID cannot be changed. For important information about this value, see Preparing and Uploading Your Sandbox Deployment Descriptor.
Set the Permission tag to false (so only users in the Permission tag can view and subscribe), and specify at least one ID of a user whom you plan to subscribe. If your app uses Selling Manager functionality, the user must already be subscribed to Selling Manager (free). For example:
```
	<Permission public="false">
	  <User id="YourUserName"/>
	</Permission>	  
```
Remove the subscription feature from the Implements tag, so the Implements tag does not contain the following: Feature name="subscription". For example:
```
	<Implements>
	</Implements>	
```
Removing the subscription feature enables you to easily subscribe a user in production, without having to enable a subscription listener. Note that after you have successfully subscribed at least one user in production (see below), and you want to test a subscription listener, you can add the subscription feature back into your deployment descriptor (within the implements tag), and upload the updated deployment descriptor.

Upload a Production Deployment Descriptor

When your Business Readiness Review is complete (see the information about the Questionnaire), eBay notifies you. After eBay notifies you, check the Embedded Applications tab for a new link that enables you to upload a production deployment descriptor. Specifically, on the My Account page, click the Embedded Applications tab. Under Embedded Application Management, click Create New Production Application.

After you confirm that you have followed the steps in the section above (for example, you have specified a production App ID in the descriptor), upload your production deployment descriptor on the Embedded Applications tab.

As a result of the upload, eBay generates production keys unique to your app. The keys are available on the the My Account page. The state of your application is "Stored."

The application is in production, but is only available to the users that you specified in the deployment descriptor (and to eBay administrators). A sample subscription plan is created for you in production, as a stub plan. The stub plan is a non-billable (free) plan.

Subscribe One User

After you have uploaded your production deployment descriptor, you can subscribe a production user to the stub plan that was created for you. The following procedure applies if, using the steps for your deployment descriptor above, you removed the subscription feature and inserted the user in the Permission tag.

From the Embedded Applications tab, click the subscribe link for your production application. Alternatively, use your production App ID instead of the YourAppID value in this link.
On the Sign In To Your Account page, sign in a user (that is, sign in a user who you have already is listed in your deployment descriptor).
On the Choose Your Subscription Plan page, use the Confirm Subscription button to subscribe to the stub plan (created for you when you uploaded your deployment descriptor).
After about one minute, navigate to the user's My eBay page, Applications tab.
Confirm that the Start button is enabled for the user.
If you did not yet remove the subscription feature from your deployment descriptor, and you do not have a subscription listener, then the user's subscription state is pending. In this case, remove the subscription feature and upload the deployment descriptor. Then on the Embedded Applications tab, utilize the User Management tool to change the state to Active (see below for more information).

Initializing Testing of a Production Listener

Instructions for the sandbox environment are similar to these instructions; in addition to reviewing the steps below, review the steps for the sandbox at the following location: Testing a Subscription Listener in the Sandbox.

Deploy your production subscription listener.
In a text editor, open the deployment descriptor that you used in Subscribe One User. Add a new user (who has an Open eBay app) in the Permission tag and, in the Implements tag, include the subscription feature:
```
	<Implements>
	  <Feature name="subscription"/>
	</Implements>
```
Save and upload the revised deployment descriptor.
From the Embedded Applications tab, click the subscribe link for your production application.
Sign in the new user (added to your deployment descriptor in step 2).
Use the Confirm Subscription button to subscribe to the stub plan (created for you when you first uploaded your deployment descriptor). This sends an addSubscriber call to your production subscription listener.
After about one minute, navigate to the user's My eBay page, Applications tab.
If a Start button is enabled for the user, your subscription listener was successful in responding to the addSubscriber call that was just made to your listener by eBay. There is no need to continue to the next step.
If a Start button isn't enabled for the user, the subscription will be in Pending. This probably means that a fix is needed to the subscription listener, so that it returns the correct response to eBay.
After attempting to fix the subscription listener, go to the the Embedded Applications tab. Under Production Applications, click the link next to Active Subscribers. The User Management tool is displayed. This tool works as follows: When you click the Search button, users are retrieved based on criteria you specify.
In the User Management tool, specify a Status of All, leave the other fields blank, and click Search.
Scroll to the bottom of the page. If the user is in the Pending state, click Pending to change the state to Active. A resulting message of Success doesn't necessarily mean the user is now Active. It just means that eBay just sent an addSubscriber request to your application.
Wait for about one minute and refresh the browser window that contains the Embedded Applications tab.
If the user is Active, your subscription listener has properly responded to the addSubscriber call from eBay. If the user is Pending, repeat the test.

Note: You many want to remove the subscription feature from the deployment descriptor, in order to temporarily use only the User Management tool for changes to subscription states. By removing the subscription feature from the deployment descriptor (and uploading it), you can utilize the User Management tool to change a state to Active, without a need for a subscription listener.

Create Subscription Plans

To get revenue, you must set up at least one subscription plan. See Offering Subscription Plans.

Submit Additional Details for Full Production Use

Submit an entry for the Apps Center. Sellers learn about applications in the Apps Center, and can subscribe to them. In the My Account page and the embedded applications tab, submit your entry. Submitting your entry enables you to preview the entry. After your entry is reviewed and approved (part of the Application Review process), your entry is published in the Apps Center, and after publication, you should review the entry.
Initiate an Application Review. Complete the App Check form to initiate the application review. Review of your application is required before your application can be used in production. Your application is checked to ensure that it adheres to the Checklist for Going Live, the Developer UI Standards, and—most important—your application is tested to ensure that it matches what you describe in your marketing literature, Apps Center entry, subscription information, and documentation. During the Application Review, the application state is "In Review."
Await review and approval of your application by eBay. eBay has a small team who review all applications and will get back to an applicant within 5 business days with status or requests for clarification or change. If the application is approved, the application state is "Approved." Otherwise, the state is "Change Requested."

Change Your Application State to Public

When your application state is "Approved," for production use, your application's "public" or "private" setting determines who can subscribe:

"Private" means that only the eBay users specified in the Permission field of the deployment descriptor can subscribe to and run your application.
"Public" means that most eBay sellers can subscribe to and run your application.

Note: To control when user subscription becomes available, you can "mark down" your application. When you are ready to begin subscriptions, you will need to manually move your approved application to the "marked up" state. If you have subscribers and then mark down your application, the button for the application is disabled for subscribers.

Developing Your Application

This section describes the views and content types that determine how your application looks and functions. It also explains how to enable a subscription flow and how to process the render request eBay sends when a user starts your application.

Options for Content and Layout

As you develop your application, consider the complexity and location of your code and how the application will appear to your customers. Then select one of the two content types described below.

Gadget Content Types

Gadgets of HTML content type are lightweight gadgets consisting of HTML and JavaScript or Flash provided inline in the deployment descriptor. A URL-type gadget provides a URL to an application not hosted by eBay but residing on a third-party server, and can offer more complex functionality than an HTML-type gadget.

HTML Content Type

HTML gadgets are hosted on eBay servers.

HTML and inline JavaScript is contained in the deployment descriptor and resides on eBay servers; complex JavaScript libraries as well as images and other external resources can be loaded from your servers.
All HTML and JavaScript specified in the Gadget is run client-side, in the end-user's browser.
eBay persists some data for your application via key-value user preferences.
A specific JavaScript method is available to make direct eBay API calls. The method proxies calls to eBay APIs so that developer credentials and user tokens are not exposed in Gadget code.
The gadget can call out to your server, or any public web service, to access remote data or business logic.

The graphic below shows an HTML-type gadget using makeRequest or callAPI.

URL Content Type

Open eBay App URL gadgets reference an application that you host on a server outside of eBay.

All presentation logic is handled by your application.
Almost all data persistence is done by your application, and not on eBay servers. eBay persists key-value user preferences for your application.
eBay API calls are made directly by your application.

The graphic below shows a URL-type gadget making requests to eBay APIs and other web services.

Views

Open eBay Apps views appear as the contents of IFrames in a user's browser.

Your application will appear as a canvas view, with full-page width and flexible height, corresponding to gadgets.views.ViewType.canvas in the Gadgets specification. A canvas view is required for every application.

Applications can also have one or two Summary views, which are fixed-size smaller views that appear in the seller's Summary page. Summary views are only viewable by users who are subscribed to Selling Manager or Selling Manager Pro.

Summary views, implemented as default and wide, have the following dimensions:

canvas: height is 800 pixels, width is the width of the browser.
default: height is 297 pixels, width is a single column.
wide: height is 97 pixels, width is two columns.

All views of an application are linked to a single ApplicationID, and specified in a single deployment descriptor.

This graphic compares a canvas view and summary views.

For more information about the user interface, see the Developer UI Standards.

Dynamic Resizing

Note: This feature does not currently work properly in Chrome browsers.

Open eBay app content is displayed in an IFrame, and the height and width of the IFrame is controlled by the containing page, not by the developer or by the gadget content.

The Gadget specification provides a method for altering a gadget's height (not width) to simulate the behavior of a <div> on a page. This method is dynamic-height, and its use is recommended. You should require it in the ModulePrefs section of your gadget's deployment descriptor.

For HTML-type gadgets, using dynamic-height is straightforward. For URL-type gadgets, the use of dynamic-height is a bit more complex, requiring that you process the parameter is, which is passed in the render request (see Processing the Render URL).

For URL-type applications to use the dynamic resizing feature, each page in the application must include the decoded is parameter value at the top of the page, preferably in the head element.

Example code for including the is parameter in the page:

<head>
    <%=new String(Base64.decode(session.getAttribute("is").getBytes("UTF-8")), "UTF-8")%>;
</head>

Note that the string is is Base64-encoded, and must be properly decoded. Java standard does not have a Base64 decoder built-in; you must download a third-party library such as org.apache.commons.codec.binary.Base64.

Use gadgets.window.adjustHeight() to resize the frame. Generally, call adjustHeight() from the onload event. (HTML gadget developers see this: gadgets.util.registerOnLoadHandler(callback). URL developers have direct access to the onload handler.) Call the method any time your layout changes result in size changes, such as DHTML manipulations. Take special note of images, as they continue loading in the background. Most HTML development guides (such as http://code.google.com/speed/page-speed/docs/rendering.html#SpecifyImageDimensions) recommend using the height and width parameter for reasons of performance; that same concept is extended to resizing. By declaring the size of the image you will prevent the resizing of the page as the image loads.

If your application maintains a consistent height on all pages, use a specific height to resize to by passing the height in pixels to the adjustHeight method. For example: gadgets.window.adjustHeight(700).

In the June 2009 release, resizing the height can only reduce height; height can not be increased, even if it has previously been reduced.

See Managing Gadget Height in the Gadgets Specification.

HTTP vs. HTTPS

eBay strongly encourages the use of HTTPS for Open eBay apps, and reserves the right to require HTTPS if the application handles personally-identifiable information.

We recommend that your application:

Use an industry standard certificate authority (i.e. Verisign). Self-signed certificates are not allowed.
Use SSL 3.0 / TLS 1.0 or better. SSL 2.0 is not recommended.

Privacy Policy Browser Requirement

For URL type applications, some Internet Explorer versions require that you specify a P3P (Platform for Privacy Preferences) data schema in the hosted application's output headers. If the P3P header is not detected, some browsers will not store the cookies at the default security level settings. This is because of the cross-domain nature of the IFrame source. You can read more about it here.

Examples of including the P3P header in your output headers:

For PHP:

header('P3P:CP="IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT"');

For ASP.NET:

HttpContext.Current.Response.AddHeader("p3p","CP=\"IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT\"");

For Django:

response = render_to_response('mytemplate.html')
response["P3P"] = 'CP="IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT"'

For JSP:

response.addHeader("P3P","CP=\"IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT\"")

Third-Party Cookies

If your application requires cookies, please consider that the cookies your application requires will be third-party cookies for your users. Some users may block third-party cookies, which would cause your site to fail. While there are some simple workarounds for all browsers, users could be reluctant to meet this applications requirement.

Should you decide you want to use cookies, you should properly handle users when the cookies are turned off. When you detect a lack of cookies, you should direct the users to a page that has wording like:

The browser you are using is rejecting cookies for our site.

Here are some steps you might take:


If you are being asked to accept cookies and you are not accepting them, you should try the operation again, and accept the cookies.
If you have set up your browser to either reject all cookies or third-party cookes, and your browser supports white-listing, you may add our address to the white-list. 
You may enable all third-party cookies.

Graceful management of third-party cookies will be verified for all Open eBay apps.

Processing the Render URL

When a subscribed user launches your Open eBay app, an HTTP POST request, or render URL, is sent to the URL specified in the gadget deployment descriptor. For URL-type gadgets, it is expected that your server will process the request and return a proper HTML page, suitable for the view requested.

Note that the application code in most application servers cannot tell the difference between URL and POST body parameters. The language-specific API to get parameters may retrieve both together.

When you receive the render request, you will have access to the following parameters.

URL Parameters

The URL parameters listed here are part of the signature. You should validate the signature to ensure it has not been tampered with.

URL Parameters	Description
`mid`	ignore
`lang`	Enum for language. Example: `en`
`country`	Country. Example: `US`
`globalid`	eBay site. Examples: `EBAY-US`, `EBAY-MOTORS`, and `EBAY-HK`
`view`	Type of view. Examples: `canvas`, `default`, `wide`. See Views.
`parent`	ignore
`rpctoken`	ignore
`env`	eBay environment. Possible values: `sandbox`, `production`
`sp`	Comma-separated list of the parameters that are signed by `sig`. See Verifying a Digital Signature.
`up`	User preferences. Parameters starting with `up_` are gadget user preferences.
`view-params`	JSON string representing the parameters passed in as part of the gadgets.views.requestNavigateTo() method

POST Body Parameters

POST Body Parameter	Description
`is`	Base64-encoded string that needs to be placed into the <head> of the document to enable the dynamic resizing and other JavaScript features. If you want to use dynamic resizing for a URL-type gadget, this value should be persisted in session memory and placed in the <head> of every page returned from the server; see Dynamic Resizing.
`sig`	Digital signature. See Verifying a Digital Signature.
`st`	Secure token. See Decrypting to Obtain User Information.

Authentication and Processing Requests from eBay

Subscription calls from eBay must be verified and decrypted. The same is true for render requests from eBay. This section explains how to verify that requests are from eBay and that requests weren't modified en route to your application. This section also explains how to decrypt part of the request, to obtain user information.

Verifying a Digital Signature

To verify a call's signature, you need a verification string and a public key. The section below explains how to extract and assemble the verification string. The public key is available on the Developer site (see the link below).

Parameters for Signature Verification

eBay forms an RSA signature, base64-encodes it, and sends it, along with a verification string, to your application.

In subscription calls, the signature is in the credentials.token.signature field, in the XML payload. The string for signature verification is in the XML payload, in the credentials.token.tokenValue field.

In a render request, the signature is in the sig parameter in the HTTP POST body. You assemble the string for signature verification for render requests by processing the parameters referenced in the sp parameter. The sp parameter contains a comma-separated list of the parameters that are included in the signature. The parameter values are to be URL-encoded and concatenated with "&". If any URL parameter itself has multiple values, the individual parameters are URL-encoded and concatenated with "|" prior to concatenation with "&". For the precise algorithm, see SignatureExtraction.java in the link in Sample Signature Verification Code.

Context	Where the signature is found	Where the verification string is found
`addSubscriber`, `removeSubscriber` request	`credentials.token.signature`	`credentials.token.tokenValue`
render request and `makeRequest`	`sig` parameter; replaces deprecated (`sg` parameter).	`sp` parameter (references other parameters in the signature, and replaces the deprecated `st` parameter)

Public Key

The public key for the sandbox environment is at http://developer.ebay.com/certificates/sandbox.cert.

The public key for production is at http://developer.ebay.com/certificates/production.cert.

The public key can be changed at any time, so you should write signature-verification code accordingly. For example, if your code cannot verify a signature, your code could grab a fresh copy of the public key, and then retry signature verification.

The public key is provided as multiple lines, and this works for many programming languages. You may find that, for your programming language, you need to first concatenate the lines into one long line before your verification code can process the public key. If you are using the Sun JDK, remove the new-line characters from the certificate, but keep each of the following lines on separate lines from the rest:
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

Sample Signature Verification Code

For sample Java code that shows how to extract, decrypt and verify a signature, see SignatureExtraction.java, StandardDecrypter.java and SignatureVerification.java in the DSR download.

Decrypting to Obtain User Information

The subscription calls, and the render requests, made by eBay to your application include sensitive information about the user, in encrypted form. This encrypted information includes the user name. Whether your application needs additional user information depends on your application (for example, whether it makes Trading API calls that require user authentication).

You need to provide your own decrypter. See Sample Decrypter for a link to a downloadable decrypter written in Java. See also Open eBay App -SHA-1 Digest Verification code samples.

The Secure Token: Information about the User

To create a secure token, eBay forms a single string of name/value pairs separated by ampersands. The value in every name/value pair is URL-encoded. This string is then encrypted.

In the subscription calls, the secure token is found in the credentials.token.tokenValue field of the payload.

In the render request, the secure token is found in the st parameter in the HTTP POST body.

These are the parameters in the decrypted secure token:

un - the user's username
at - the user's auth token (the auth token in the Trading API)
ted - the auth token's expiration date
es - the EIAS token for the user

Sample Decrypter

To decrypt the base64-encoded secure token that you receive from eBay, you need your Cert ID. The Cert ID is one of the three SM Apps keys that you receive after uploading your deployment descriptor. For a sample decrypter, see the StandardDecrypter.java file, available as part of the Sample Listener download.

Decrypter Logic

This section is most useful if you read it with reference to the SampleDecrypter.java file in the Sample Decrypter section.

The decrypter needs a decryption key, an hmacKey and a cipherKey. The decryption key is your application's CertID.

Derive hmacKey and cipherKey from your application's CertID. hmacKey is a hash of a byte array, where the byte array is the combination of the number 1 and the bytes of the CertID. cipherKey is the first 16 bytes of a hash of a byte array, where the byte array is the combination of the number 0 and the bytes of the CertID.

The secure token was base64-encoded before being sent to your application. So, start by base64-decoding the secure token (the value of tokenValue or st).

Next, split the secure token in two--the last 20 bytes from the rest of it. The last 20 bytes is an HMACSHA1 hash for verifying the front portion, the "cipherBytes".

If you have confirmed that cipherBytes is valid, capture its first 16 bytes as the initialization vector. With the initialization vector, the hmacKey and cipherKey, you can decrypt the remainder of cipherBytes.

The result of decryption is the long string of name/value pairs, separated by ampersands. Again, each value is URL-encoded, so you need to decode each before using it.

Preparing Your Deployment Descriptor

To deploy your application, you must create a deployment descriptor, which is an XML file that contains application metadata and deployment preferences. Before creating a production deployment descriptor, you should review Getting Your Application into Production.

If your gadget is of content type HTML, your entire gadget will be contained in its deployment descriptor, as HTML and JavaScript or Flash within CDATA in the Content section.

If your gadget is of content type URL, your deployment descriptor's content tag will specify only the type, the view, and the URL at which your application code resides.

Download the sample deployment descriptor and the deployment descriptor schema file.
Revise the sample deployment descriptor. Refer to the annotations in the sample deployment descriptor. Some things to keep in mind:

In the id attribute of the OEApplication tag, specify a unique web location in your company's domain (in the form of myapp.mycompany.com). In any future changes to the deployment descriptor, this unique value cannot be changed because it becomes your AppID in the keys issued for your application.
The same AppID can be used in for a single application in both the sandbox and production environments, but you cannot use the same AppID for multiple Open eBay apps. Keysets can not be shared between applications.
Supply an application-display name for sellingmanager.msg.application.applicationName. The name can be up to 25 characters.
Use an XML tool such as Notepad++ to confirm that your deployment descriptor is valid against the deployment descriptor schema file.

Your deployment descriptor is now ready for upload. In the My Account page, Embedded Applications tab, click "Create new sandbox application" and proceed through the submission flow. See also: Uploading Open eBay Apps Deployment Descriptor.

Sample Deployment Descriptor

For reference, see the sample deployment descriptor.

Gadgets Features

This section describes how to use the Gadgets specification features that eBay has adapted for Open eBay Apps, and how to use the eBay callAPI to make secure calls to eBay APIs from your gadget.

Supported Gadgets Libraries

Some Gadget APIs are only partly supported, with optional features. Others, including setprefs and settitle, are not supported.

Import JavaScript libraries by requiring them in your HTML-type gadget. For example:

Required feature="core"

Open eBay Apps supports the following Gadgets specification libraries.

core

Prefs (readprefs only)
io
json
util

Feature-specific libraries

rpc
views (requestNavigateTo is not currently supported, but in a future release will support navigation from a summary view to a canvas view)
flash
dynamic-height
minimessage
tabs

These libraries are documented here: Gadgets libraries.

Using HTTP GET and POST Methods with URL-Type Gadgets

For calls that do not require user information, your gadget can use ebay-params to specify that the gadget be rendered via the HTTP GET method. POST is the default method.

Note that user information can't be encrypted in GET requests as it is in POST requests. Because of this limitation, GET should only be used in calls that do not pass confidential information. Such GET requests are signed, but do not contain the st parameter, which contains user information.

Syntax:

<Require feature="ebay-params">
<Param name="VIEW_NAME:url-render-type">RENDERING_METHOD</Param>
</Require>

Example:

<Require feature="ebay-params">
<Param name="default:url-render-type">EBAY_GET</Param>
<Param name="canvas:url-render-type">EBAY_POST</Param>
</Require>

Making Calls from HTML-type Gadgets

HTML-type gadgets use gadgets.ebay.callApi or gadgets.io.makeRequest when they call eBay APIs or make other remote calls.

(URL-type gadgets are free to make calls to eBay APIs or other web services. For URL gadgets, the content is generated on your server, and your server is free to make eBay API or other web server calls. Once the content from a URL gadget has been rendered into the browser the gadgets.io.makeRequest and gadgets.ebay.callApi are NOT available.)

Using eBay's `callAPI` Library

eBay's APIs provide rich functionality for selling applications.

eBay supplies a library, callApi, that enables HTML-type gadgets to call eBay APIs. For other remote calls, use makeRequest.

For calls that require authentication and authorization, the call uses a placeholder, ebay-auth-token, which eBay replaces with the user's token before passing the request to the API. This avoids passing a user's token.

`callApi` parameters

Parameter	Description	Use
`service`	An enum representing the type of eBay API being called. Recognized values are gadgets.ebay.ApiService.SHOPPING, gadgets.ebay.ApiService.TRADING, gadgets.ebay.ApiService.MERCHANDISING, gadgets.ebay.ApiService.FINDING, and gadgets.ebay.ApiService.FEEDBACKDSR.	Required
`operation`	Name of the API being called.	Required
`version`	eBay API version number, required in any eBay API request.	Required
`siteId`	eBay site ID. For example, "0" for US.	Required
`payload`	Request data (XML, JSON, or name-value pairs string).	Required
`callback`	Callback function to be called with the response data from the API request. A response object is passed into the callback function. Response data can be obtained by referencing response.data.	Optional
`requestPayloadType`	An enum representing type of request data (XML, JSON, or name-value pairs): gadgets.ebay.ApiPayloadType.XML, gadgets.ebay.ApiPayloadType.JSON, or gadgets.ebay.ApiPayloadType.NV.	Optional. Defaults to XML type.
`responsePayloadType`	An enum representing type of response data expected (XML, JSON, or name-value pairs): gadgets.ebay.ApiPayloadType.XML, gadgets.ebay.ApiPayloadType.JSON, or gadgets.ebay.ApiPayloadType.NV.	Optional. Defaults to XML type.
`Timeout`	An integer specifying a timeout for the request in milliseconds. The default value is 1.0 second, which is also the maximum value. When the API times out, the response code is 504.	Optional.

Supported Formats for the eBay APIs

Your application can use callAPI to access eBay APIs. The following are the supported input formats for the supported APIs. See the API products pages for details.

Trading API: XML
Shopping API: XML, Name Value, and JSON
Merchandising API: XML, Name Value, JSON
Finding API: XML, Name Value, JSON
FeedbackDSR API: XML

Sample `callApi` Call

gadgets.ebay.callApi(gadgets.ebay.ApiService.TRADING, "getFeedback", "603", "0", requestXml, callback,
    gadgets.ebay.ApiPayloadType.XML, gadgets.ebay.ApiPayloadType.XML);

An example of a gadget calling an eBay API:

var service = gadgets.ebay.ApiService.TRADING;
var operation = "getUser";
var version = "611";
var siteID = "0";

var sb = [];
sb.push("<?xml version=\"1.0\" encoding=\"utf-8\"?>");
sb.push("<GetUser xmlns=\"urn:ebay:apis:eBLBaseComponents\">");
sb.push("<RequesterCredentials><eBayAuthToken>${ebay_auth_token}</eBayAuthToken></RequesterCredentials>");
sb.push("<DetailLevel>ReturnAll</DetailLevel>");
sb.push("</GetUser>");

var payload = sb.join("");
var requestFormat = gadgets.ebay.ApiPayloadType.XML;
var responseFormat = gadgets.ebay.ApiPayloadType.XML;
var callback = function(response) {
  if(response.data) {
    if(response.data.toString().toLowerCase().indexOf("<ack>success</ack>") > -1) {
      // API call successful, now parse the response
    }
    else {
      // API was called, but there is an error in the response
    }
  }
  else {
    // API was not called due to a problem with authentication or the Gadget Server
    // response.errors array has details on the problems encountered during processing
  }
}

// requestFormat and responseFormat are optional (XML is the default format)
gadgets.ebay.callApi(service, operation, version, siteID, payload, callback, requestFormat, responseFormat);

Using `os:HttpRequest`

HTML-type gadgets use os:HttpRequest to make remote calls to available web services. os:HttpRequest is described in the OpenSocial Data Pipelining Specification. os:HttpRequest is recommended over the older makeRequest.

makeRequest is still available, but we recommend using HttpRequest. The advantages of using HttpRequest include:

The syntax is cleaner, and the request appears in the gadget's content section.
You can use the results of prior calls in subsequent calls using expression language, as described here.
HttpRequest integrates with OpenSocial templates, providing additional methods for creating content.

The Open eBay implementation of os:HttpRequest includes the following attributes. This list is a subset of the attributes described in the OpenSocial Data Pipelining Specification.

@key {string}
@href {string}
@params {string}
@method {string}
@format {string}
@refreshInterval {int}
@authz. String, either "none" (default) or "ebay-signed".

You can use HttpRequest to call eBay APIs, but we recommend using the callAPI feature for eBay API calls.

Using `makeRequest`

HTML-type gadgets use makeRequest to make remote calls to available web services. If your gadget uses makeRequest, consider switching to the newer os:HttpRequest.

eBay has implemented makeRequest with only a few slight differences from its OpenSocial implementation. These differences include:

gadgets.io.AuthorizationType.EBAY_SIGNED: For authorization, eBay returns two values in response to the gadgets.io.AuthorizationType.EBAY_SIGNED field. These values are the parameters sig and sp.
gadgets.io.AuthorizationType.OAUTH: Open eBay Apps do not support OAuth, so gadgets.io.AuthorizationType.OAUTH is not supported.

If your HTML gadget is sending makeRequest calls to your own server (if, for example, you are using a complex AJAX page), you can ensure that the makeRequest request your server receives is proper by marking the request EBAY_SIGNED, and verifying the signature when your server receives the request. See Verifying a Digital Signature.

Open eBay Apps implements a response code for time-out in the makeRequest call. Open eBay Apps returns a 504 (Gateway time-out) for timed-out responses. You can use this response to handle makeRequest responses elegantly. For example, if a call to a public web service times out, then the gadget might collapse a particular section, or show an appropriate end-user message.

You can use makeRequest to call eBay APIs, but we recommend using the callAPI feature for eBay API calls.

Content Rewriting

You can use the content rewriting feature to control whether references to external resources are rewritten to be cached and served up eBay servers when they appear in the source of an HTML-content gadget. This OpenSocial Data Pipelining feature lets your HTML-type gadget decrease the load on your servers and use eBay servers to serve style sheets, JavaScript, and images. OpenSocial documentation on content rewriting is available here.

eBay supports the documented features, with the following rules:

Max refresh time: 86400 secs.
Rewriting only applies to the following tags: link, script, ebmed, img and style.
Once a tag has been rewritten and cached, it will remain cached until it expires, even if you change your gadget's XML to lower the refresh time. If you want to change the refresh time, you can change the URL signature of a link, thereby creating a new uncached URL.

User Preferences

The Gadgets specification describes the attributes and enums that a gadget can use to specify user-specific information, which you can read about here: User Preferences. This section describes how to employ user preferences in Open eBay apps that are HTML-type gadgets.

User preferences declared in the gadget section of the deployment descriptor are persisted by eBay. In response to a Start call, eBay adds persisted user preferences to the render request that is passed to the gadget.

If you declare a name and type for a user preference in the gadget section of your deployment descriptor, a user of your application, on first loading your application, will have no value for the user preference. The gadget interface lets a user assign a value.

Examples

User preferences can be used to supply the gadget's query, for example:

up_query="ipod"

Example of a user preference being declared in a gadget:

<UserPref name="myname" display_name="Name" default_value="Rowan"/>

Example of a gadget accessing a declared user preference value in a gadget.

var prefs = new gadgets.Prefs();
html += "<br><FONT SIZE=6>Good " + salutation + ", " + prefs.getString("myname") + "!!!<br><br></FONT>";

Example of a gadget accessing a user preference value via the hangman variable:

<ModulePrefs title="Preferences for __UP_myname__" height="400">

Limitations

The interface that allows users to set or select user preferences in the application is only available in the summary view. Canvas views do not yet offer this interface.

Submitting Your Apps Center Entry

The Apps Center showcases your description of your Open eBay app, and your logo.

Sellers browse the Apps Center for Open eBay apps. Sellers also can rate the applications. For information about how the center is used by eBay members, see the information for end-users.

You submit your application for the Apps Center through the Embedded Applications tab (on the My Account page). Click the "directory entries" link for your application.

Information To Have on Hand

Your company name and information are auto-filled from your developer account.

Your application name is limited to 25 characters and is based on the application name in your deployment descriptor. If your deployment descriptor has an application name longer than 25 characters, you will have to modify your deployment descriptor and upload it again. See Preparing Your Deployment Descriptor.

The short description displayed in the Apps Center listing is also pulled from the application's deployment descriptor.

The submission flow lets you input your company or application logo and screenshots of your application, or a URL from which they can be served, for display in the directory. Logos must be exactly 115px by 80px, and screenshots must be exactly 640px by 480px.

Additional information you'll want to have on hand for the submission:

Your region
The languages your app supports
The category of your app (for example Inventory, or Shipping and Payments)
A description of your app's features (basic HTML is supported for the description)
The browsers your app supports
URLs to external resources that describe or show your app's effectiveness
A description of the type and level of support you provide to users of your app
The type of pricing you will be using (for example, free, or subscription, or usage-based), and pricing details

Guidelines for Listing and Inventory Apps

Users who unsubscribe from an app that revises listings and inventory numbers can reasonably expect their listings to revert to their original pre-subscription state. These guidelines are to minimize the burden of reverting listings.

After a subscription goes into the Cancelled state, you won't be able to revert the listings. You need to catch unsubscribers while they are in the CancelledPending state. You can find subscribers' subscription states, including those in the cancelled pending state, using the getSubscribers call or via updateSubscriber requests via your subscription listener.

Listing Apps

If you have an app that creates or revises item listings, you should (1) make sure potential subscribers know how your app will affect their listings, and (2) give subscribers a way to back out of revisions.

Show potential subscribers how your application revises listings, so they can preview before applying changes to their entire inventory. Do one of the following:

Give users a preview of listings that have been revised by the app
Provide in the app's Getting Started steps very clear instructions for trying out the functionality on one or two listings

There are several approaches to backing out of revisions your app has made to listings.

Be able to mass remove the component from all of a seller's listings, should they request it. We suggest using the Trading API ReviseItem call for this. Be aware of the Restrictions on Changing Item Properties During a Revision. If your app revises an item description, save the listing's original Item.Description so that you will be able to revert your app's revisions.
Enable unsubscribing users to remove the app's component from all or selected listings. Provide instructions within your application or help content on how best to accomplish this.
When a user unsubscribes, you should automatically remove the app's components from the user's listings. Some developers do this by replacing widgets in the listings with single-pixel images. Note that this has to be done when the seller is in cancelled pending state, before the subscription moves to the cancelled state. Another approach is to message the user via email prompting the user to remove the widget or template from their listings.

Inventory Apps

Applications that revise item quantities should:

Clearly explain to new subscribers how the app's automatic updates and update rules will affect existing and new listings.
Provide subscribers a way to stop automatic updates immediately for all or for individual listings.
Automatically stop all updates when an unsubscription takes effect. For non-prorated subscriptions, send a warning in an email to the user that automatic updates will stop when the subscription runs out.

User-Contributed Notes

This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.

Open eBay Apps Users Guide: Developing Open eBay Apps

Table of Contents

Getting an Application Running in the Sandbox

Getting Generic Sandbox Keys

Preparing and Uploading Your Sandbox Deployment Descriptor

Retrieving Your Sandbox Keys

Initially Subscribing a Sandbox User

Managing Your Sandbox Application

Testing a Subscription Listener in the Sandbox

Getting Your Application into Production

Develop in the Sandbox and Complete a Business Readiness Review

Prepare Your Deployment Descriptor for Upload to Production

Upload a Production Deployment Descriptor

Subscribe One User

Initializing Testing of a Production Listener

Create Subscription Plans

Submit Additional Details for Full Production Use

Change Your Application State to Public

Developing Your Application

Options for Content and Layout

Gadget Content Types

HTML Content Type

URL Content Type

Views

Dynamic Resizing

HTTP vs. HTTPS

Privacy Policy Browser Requirement

Third-Party Cookies

Processing the Render URL

URL Parameters

POST Body Parameters

Authentication and Processing Requests from eBay

Verifying a Digital Signature

Parameters for Signature Verification

Public Key

Sample Signature Verification Code

Decrypting to Obtain User Information

The Secure Token: Information about the User

Sample Decrypter

Decrypter Logic

Preparing Your Deployment Descriptor

Sample Deployment Descriptor

Gadgets Features

Supported Gadgets Libraries

Using HTTP GET and POST Methods with URL-Type Gadgets

Making Calls from HTML-type Gadgets

Using eBay's callAPI Library

callApi parameters

Supported Formats for the eBay APIs

Sample callApi Call

Using os:HttpRequest

Using makeRequest

Content Rewriting

User Preferences

Examples

Limitations

Submitting Your Apps Center Entry

Information To Have on Hand

Guidelines for Listing and Inventory Apps

Listing Apps

Inventory Apps

User-Contributed Notes

Open eBay Apps
Users Guide: Developing Open eBay Apps

Using eBay's `callAPI` Library

`callApi` parameters

Sample `callApi` Call

Using `os:HttpRequest`

Using `makeRequest`