Selling Manager Applications
|
With Selling Manager Applications, you can embed an application directly in the eBay.com interface. Your application can appear alongside Selling Manager and Selling Manager Pro, eBay's most popular tools for managing selling activities. For an overview of the program, see the Selling Manager Applications product page.
With Selling Manager Applications, you can:
Please see Getting Your Application into Production and sample code.
Getting an Application Running in the Sandbox
Getting Your Application into Production
Options for Content and Layout
Authentication and Processing Requests from eBay
Decrypting to Obtain User Information
Preparing Your Deployment Descriptor
Making Calls from HTML Gadgets
Submitting Your Application Directory Entry
These are the requirements for having your Selling Manager application approved and listed in the applications directory, where sellers can subscribe to it.
eBay Selling Manager Applications supports the open-standard Gadgets specification. We recommend that Selling Manager Application developers familiarize themselves thoroughly with the specification.
Application code can be fully hosted off eBay (URL content type), or hosted on eBay and contained inline (HTML content type) in a deployment descriptor.
eBay has implemented a gadget server and a gadget container that support the core and selected features of the Gadgets specification (see Supported Gadget Libraries below), and an additional API for calling eBay APIs (see Using eBay's callAPI Library).
This framework enables third-party developers to write web applications that eBay users access through My eBay. Selling Manager applications must conform to the Gadget specifications, meet the participation requirements, and have deployment descriptors that specify the application's metadata. eBay's gadget container uses this metadata to render the applications in IFrames in the Selling Manager interface.
The Selling Manager Applications framework is designed to support web applications that customers can use without installing anything on their desktops. Some existing Selling Manager applications make plugins available to their users, but client-side applications are not likely to be good candidates for Selling Manager applications. If your web application includes client-side downloads, they will need to be approved during the Business Readiness Review.
To see how to quickly run an application in the sandbox environment, see Getting an Application Running in the Sandbox.
Selling Manager Applications is only available on the U.S. site.
Please review the latest information about SM Apps at the SM Apps forum and at the Developer Tools announcements.
The Gadgets spec defines two content types for gadgets: HTML and URL.
Selling Manager applications can be either type, but it is expected that most will be URL-type. Developing a URL-type application can be as simple as taking an existing hosted application and writing a deployment descriptor for it, assuming that it meets the Selling Manager program requirements. URL-type applications have a wider array of possibilities for their user interfaces and programming logic, and are not limited to HTML and JavaScript or Flash.
See Gadget Content Types for more information about content types in Selling Manager Applications.
Your Selling Manager application will appear as a canvas view, with full page width and flexible height, in a seller's Applications tab in My eBay. A canvas view is required for all applications.
Your application can optionally also have one or two Summary views, fixed-size smaller views that appear in the seller's Summary page. Summary views can be a single-column view (default) or a two-column view (wide).
See Views for more details.
For users to subscribe to your application, you must implement the OpeneBayParticipantInterface (OEPI) service so that eBay can send subscription-related requests to your application.
To deploy your Selling Manager application, you must create a deployment descriptor, which is an XML file that contains application metadata and deployment preferences. For HTML-type gadgets, the deployment descriptor also contains the inline HTML and JavaScript that comprise your gadget.
See Preparing Your Deployment Descriptor.
Selling Manager applications can use the many calls in the eBay Trading API, eBay Shopping API, and other eBay APIs. There are more than 125 calls in the eBay Trading API.
The Trading API also includes 26 calls specifically designed to work with Selling Manager and Selling Manager Pro. For an overview of these Selling Manager calls, see the Trading API WebHelp.
There is a wide range of possibilities for Selling Manager applications. Based on our research, we think email management, customer management, shipping and fulfillment, bulk editing of listings, UPI process management, picture management, profitability analysis, and inventory management are all pretty good bets. But that doesn't preclude other application types. Your application might create a social networking application or provide special filtering. We know that we have not anticipated all the directions developers might go with this opportunity, and we expect to be pleasantly surprised by innovative implementations.
This section describes how to quickly initiate a basic application in the sandbox environment. Please also see Preparing Your Deployment Descriptor.
You need generic sandbox keys in order to get keys for a Selling Manager application. You can obtain generic sandbox keys on the My Account page.
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: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.sellingmanager.msg.application.applicationName
can be up to 25 characters.<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 in the Permission tag can view and subscribe).
You need sandbox keys specific to your Selling Manager application. 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).
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.
You can use the Embedded Applications tab of the My Account page to download your existing deployment descriptor, update it, and otherwise manage your Selling Manager application. 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.
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).
subscription feature,
within the Implements tag:
<Implements> <Feature name="subscription"/> </Implements>
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 a Selling Manager application.
Please see all the sections below for the steps for moving your application into production and enabling users to subscribe to your application.
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:
<Permission public="false"> <User id="YourUserName"/> </Permission>
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.
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 Selling Manager application. 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.
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.
YourAppID value in
this link.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.
Implements tag,
include the subscription feature:
<Implements> <Feature name="subscription"/> </Implements>
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.
To get revenue, you must set up at least one subscription plan. See Offering Subscription Plans.
When your application state is "Approved," for production use, your application's "public" or "private" setting determines who can subscribe:
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.
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.
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.
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 gadgets are hosted on eBay servers.
The graphic below shows an HTML-type gadget using makeRequest or callAPI.
Selling Manager URL gadgets reference an application that you host on a server outside of eBay.
The graphic below shows a URL-type gadget making requests to eBay APIs and other web services.
Selling Manager Application 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, 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 Third Party Developer UI Standards for Selling Manager Applications.
Selling Manager application 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 Request).
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.
eBay strongly encourages the use of HTTPS for Selling Manager applications, and reserves the right to require HTTPS if the application handles personally-identifiable information.
We recommend that your application:
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:
header('P3P:CP="IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT"');
HttpContext.Current.Response.AddHeader("p3p","CP=\"IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT\"");
response = render_to_response('mytemplate.html')
response["P3P"] = 'CP="IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT"'
response.addHeader("P3P","CP=\"IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT\"")
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 Selling Manager applications.
Note: You can manage subscriptions manually, using the Embedded Applications tab.
To enable subscription, you use the OpeneBayParticipantInterface to write a subscription listener. A subscription listener receives subscription-related calls from eBay.
For example, eBay sends the updateSubscriber call when a change occurs in the state of a user's subscription to your application. This updateSubscriber call contains the old and new states of the user's subscription. Examples of states in the call request are:
For more information about the calls in the OpeneBayParticipantInterface for
subscriptions, such as addSubscriber and updateSubscriber, see the
OEPI Call Reference.
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 by default, eBay sends addSubscriber and removeSubscriber calls to your application.
Remove the subscription value if your application has not implemented a subscription listener, and eBay will not send your application (or expect your application to respond to) subscription calls.
To enable users to subscribe or unsubscribe to your application, you must implement the OpeneBayParticipantInterface (OEPI) service. When you do so, you are in effect writing a "subscription listener" that receives calls such as addSubscriber. This subscription listener is an application that receives subscription requests, e.g. addSubscriber requests, from eBay. eBay makes an addSubscriber call to your OEPI service if a user goes to My eBay and subscribes to your application.
See the OpeneBayParticipantInterface Call Reference, which includes samples. Also see the following Java sample: Selling Manager Applications event listener.
Your application's response can include the errorMessages
node, for your use. It is ignored by eBay.
In your deployment descriptor,
find the Link field
whose rel attribute is EndPoint.Management.
Set its href to the URL of your OEPI listener.
eBay sends subscription calls to the URL that you specify.
eBay recommends HTTPS.
When eBay sends subscription calls to the URL that you specified,
eBay includes a cmd parameter in the URL. Your application should check the value
of this cmd parameter in the URL, because the value is the name of the call. For
example, eBay might use the following URL and parameter:
https://SampleCompany.com/Listener/IntegrationManagement?cmd=addSubscriber
The subscription calls from
eBay include signature and tokenValue.
To ensure that the request is from eBay, use
tokenValue as the verification string for
signature. For more information, see Verifying a Request Signature.
Although tokenValue is
used for signature verification, the encrypted
contents of tokenValue, such as the token expiration date, is not
relevant for signature verification.
However, to subscribe or unsubscribe a user,
you must decrypt tokenValue, because the user name is
encrypted as part of
tokenValue.
See Decrypting to Obtain User Information.
When a user clicks Subscribe in My eBay, eBay sets
the subscription state to Pending and sends an addSubscriber request to your application.
After you process the request, your application sends
an addSubscriber response containing a status value
(Approved, Rejected, etc.).
When a user unsubscribes from your application, eBay calls removeSubscriber to request that you remove the subscriber from your subscription database. eBay also revokes the user's token.
When a subscribed user launches your Selling Manager application, an HTTP POST request 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.
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 |
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 Parameter |
Description |
|---|---|
sg |
(Deprecated; replaced by sig in late June 2009). Digital signature. |
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. |
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.
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).
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) |
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-----
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.
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 Selling Manager Application -SHA-1 Digest Verification code samples.
See also: Digital Signature Authentication and User Token Decryption.
To create a secure token, eBay forms a single string of name/value pairs, each 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 usernameat - the user's auth token (the auth token in the Trading API)ted - the auth token's expiration datees - the EIAS token for the userTo 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 decryptor, see the StandardDecrypter.java file, available as part of the Sample Listener download.
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.
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.
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.sellingmanager.msg.application.applicationName. The name can be up to 25 characters.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 Selling Manager Application Deployment Descriptor.
For reference, see the sample deployment descriptor and the sample applications, which include deployment descriptors.
This section describes how to use the Gadgets specification features that eBay has adapted for Selling Manager Applications, and how to use the eBay callAPI to make secure calls to eBay APIs from your gadget.
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"
Selling Manager Applications supports the following Gadgets specification libraries.
corePrefs (readprefs only)iojsonutilrpcviews (requestNavigateTo is not currently supported, but in a future release will support navigation from a summary view to a canvas view)flashdynamic-heightminimessagetabsThese libraries are documented here: Gadgets libraries.
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.)
callAPI LibraryeBay'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. Permitted values are gadgets.ebay.ApiService.SHOPPING, gadgets.ebay.ApiService.TRADING, and gadgets.ebay.ApiService.MERCHANDISING | 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. |
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.
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);
makeRequestHTML-type gadgets use makeRequest to make remote calls to available web services.
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: Selling Manager Applications 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.
Selling Manager Applications implements a response code for time-out in the makeRequest call. Selling Manager Applications 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 also use makeRequestto call eBay APIs, but we recommend using the callAPI feature.
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 Selling Manager applications 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.
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">
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.
For users to subscribe to your application in production, you must set up one or more subscription plans.
In production, when users view information about your application, they see the subscription plans that you offer. After a user selects a plan, the user completes the subscription process. The user is asked to agree to eBay's Terms of Use, agree to the Developer's Terms and Privacy Policy, and, unless the plan is free, provide payment information. After a user is subscribed, the user can use the application in My eBay on the Application tab.
You receive 80 percent of the revenue from your application, through the following process:
When you're ready to test your plans, enter them in production, in a "hidden" mode (so other users cannot see them), and test them.
You can offer a single free plan, a single billable plan, or a combination of plans (free and/or billable).
Please see the Managed Billing Platform (MBP) Guide for the following:
To receive revenue, you must set up at least one billable plan for your application. The Managed Billing Platform Guide includes subscription options, plan requirements, and invoicing.
Note: A free plan is automatically created for you when you submit your sandbox deployment descriptor. If you decide to move a free application to production, you must create a subscription plan using the steps below.
When you are ready to verify that a billing plan is working as expected, submit the plan for your production application. It will be in a "hidden" mode (so other users cannot see it), so you can begin testing it in production.
For an application in production, you can create subscription (billing) plans with the Billing Plan spreadsheet. Before submitting a billing plan, please do the following:
You can offer multiple plans for one application. For example, one application could allow users to choose one of the following plans:
At a minimum, you must offer a 7-day free trial a subscription plan. In the case of a billable (non-free) plan, if a user unsubscribes from the free trail in less than 7 days, and then resubscribes, the user is no longer in a free trial and is charged.
The subscription plan lifecycle is used to track when the plan is submitted, configured (in the Managed Billing Platform), and available to users.
Each month, each user gets a billing statement of expected charges.
There are two billing cycles each month. Before subscribing to any Selling Manager application, each user already has been assigned to one of the following two cycles:
For all users (BC0 and BC15 users), the following occurs: about 15 days after a statement is received, the user's PayPal account is debited for charges listed in the statement, and the money is credited to the third-party developer's PayPal account.
There is a variable amount of time between when a user comes out of a free trial and when the first billing statement is created. For example, if a user comes out of a free trial on August 3, but they are on BC0, their first statement isn't received until about September 1st. If they are on BC15, their first statement is received on about August 15th.
If a payment failure occurs, the user is requested, through email and My Messages, to correct their payment information. If the user takes no action, then 3 days after the payment failure, the user is suspended (see the Past-Due Accounts section, below this section). If the user still takes no action, then 4 days later, the user's subscription is cancelled.
For more information related to billing cycles, see the Managed Billing Platform Guide. For information about retrieving billing statement information, see Retrieve Billing Statement Information.
If a user of your application has a past-due balance for 18 days, the user's subscription is suspended. An example of a suspended user is below. It is expected that a user with a past-due balance is aware of the past-due balance (see the Billing Statements section, above this section).
A past-due balance usually results from a payment failure. A user is notified by email when a payment failure occurs, and has 3 days to correct the payment failure. Specifically, if the suspended user makes a one-time payment, and the account balance is no longer past-due, then within a few minutes, the user's subscription is made active.
However, if a suspended user takes no action (for 3 days after the suspension), then the user's subscription may be cancelled. You are notified of these events by an updateSubscriber call made to your application. If a subscription is cancelled, then to use your application, the user must resubscribe. If a user's subscription is cancelled, it is recommended that you maintain the user's data for a short period of time to allow the user to resubscribe without losing their settings.
If a user's subscription is suspended, then in My eBay, on the user's Applications tab, the Start button for your application is disabled. The user can click the Make a Payment link, as in the following example, resulting in an updateSubscriber call to your application:
If a user notifies you that on the Applications tab, the Start button is disabled, as in the above example, you can assist them by instructing them as follows:
This section discusses using the requests in the Open eBay Application Integration service to perform billing operations. Note that these calls require an Open eBay Identity Provider token passed in the header of the call. See the OEIDP Call Reference for information on obtaining this token.
You can charge your subscribers for usage and also for setup fees, one-time fees, and even recurring fees, by reporting these transactions to the Managed Billing Platform. For recurring fees, this is an alternative to having the Managed Billing Platform manage charges on your behalf. See the Managed Billing Platform Guide for more information.
To engage in usage-based billing, set up a usage-based billing plan, use the Open eBay Identity Provider (OEIDP) to get a token to authenticate your usage-related calls, and then use the Open eBay Application Integration Service (OEAIS) to submit usage statements. Main steps are as follows.
Decide on the usage charges that you will include in your plan. See the Managed Billing Platform Guide for details.
See Offering Subscription Plans, and when you create your plan, affirm that you plan to bill for usage and select your desired usage categories.
Use the login call in the OEIDP service to obtain an EIDP token. See the OEIDP Call Reference for information on using this service.
Use the addUsage call to report usage and the amount of the charge to the Managed Billing Platform. Include the EIDP token in the header of the request. See the OEAIS Call Reference for information about using the addUsage call.
Usage records will appear on the subscriber's billing statement and the associated usage charges will be included in the billing statement total amount due, where applicable.
Two calls, getBillingRecords and getBillingStatements, let you get summary and detailed billing statement information about a user's subscription account. The billing information retrieved by these calls matches what is displayed on the billing statements that subscribers view in their My eBay page. These calls are intended to help you support your subscribers, and are to be used if, for example, a user contacts you with questions about a charge or a statement.
getBillingStatements retrieves a list of billing statements for each of your subscribers. For example, if a user calls you and inquires about charges on a particular billing statement, you can invoke this call to return a list of billing statements. The call returns a summary list of billing statements, including information for each billing statement such as the statement ID, statement date, statement total, new charges total, credits total, payments total, and balance due. Once you identify the statement in question, you can run getBillingRecords to get the line item details of the statement.
getBillingRecords retrieves line-item details of a statement. For example, if your plan includes a base monthly cost and additional usage, getBillingRecords returns the line items that correspond to these charges. Specifically, you will see a "subscription" fee line item and "usage fee" line item, including the date, description, details of the charge, charge amount, and other information for a given line item.
You might incorporate these operations into whatever tool your company uses to manage end-user inquiries. Once you bring up a user's account, you could have an action in your customer service tool that invokes the operations, reads the XML output, and renders the output in a window in your customer service tool.
The addCredit request enables you to submit a credit request to the system to adjust a user's billing statement balance, or to adjust particular line item charges on a billing statement. You retrieve the information needed for an addCredit request via the getBillingStatements and getBillingRecords calls. Note that requested credits are not applied to a subscriber's statement immediately. eBay processes addCredit requests within about a week.
The getCredits request retrieves information about the disposition of a particular credit request. You can use it to find out if there was a problem with the processing of the credit. It returns the state of the credit request.
The setBillingStartDate request lets you start a user's subscription before the end of the mandatory free trial period, at the subscriber's request. The call can only be made during the free trial period, and only once per subscription. It is designed to meet the needs of applications that offer restricted access during the free trial period. If a user in a free trial period wants to switch to full access, use this call to set the user's start date so you can submit an addUsage request or begin the full-access subscription and charges. The billing start date needs to be in the present or the past before the subscriber can be charged for usage or can begin to be subjected to subscription charges.
You may want to have setBillingStartDate triggered by a button in the user interface, which can be clicked by a free-trial user who intends to upgrade to a full-access subscription.
The Application Directory showcases your description of your Selling Manager application and your application's logo in a directory of available applications that sellers will be browsing. For information about how the directory is used by eBay members, see the information for end-users.
The flow for submitting your application for the Selling Applications Directory is accessible through the Embedded Applications tab on the My Account page. Click the "directory entries" link for your application.
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 currently has an application name longer than 25 characters, you will need to modify your deployment descriptor and upload it again. See Preparing Your Deployment Descriptor.
The short description is also pulled from the application's deployment descriptor, so you might want to update that as well.
The submission flow lets you input tour 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:
© 2008–2009 eBay Inc. All rights reserved.
This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.