eBay ClientAlerts API
|
This document gives you an overview of the Client Alerts JavaScript SDK, answers common questions, and points you to other resources where you can learn more.
Users of the Client Alerts JavaScript SDK should be familiar with the Client Alerts Web Services User Guide, which gives an overview of the Client Alerts Web Services.
Welcome to the Client Alerts JavaScript SDK
Configuring and Initializing the Client Alerts Service
The eBay Client Alerts JavaScript SDK provides a Client Alerts Service, which is a client-side module that interacts with the eBay API servers to fetch alerts for registered applications. The Client Alerts Service runs in the client application domain and uses the eBay Client Alerts APIs. Applications manage the lifecycle of the service via interfaces provided.
The service can be configured by passing in the following parameters.
The Client Alert Service is initialized using the configuration parameters. At initialization time, the service calls the Client Alerts server to verify the configuration parameters. All errors are reported back to the calling application.
The Client Alerts Service provides alerts in two categories: user alerts and public alerts. User alerts are alerts about eBay site events that affect an individual user. The individual user calls the Trading API's SetNotificationPreferences to subscribe to specific events. Public alerts are alerts that eBay publishes to all users.
To retrieve user alerts, the user interacts with the "Session" class in the Client Alerts JavaScript SDK. The Session class does the following on behalf of the user:
To retrieve public alerts, the user interacts with the Channel and Channels classes in the Client Alerts JavaScript SDK. The Channels class does the following for the user:
After the service has been initialized, the application can start and stop the Client Alerts service. The service begins polling at start. The polling interval for alerts is set at configuration, and can be modified during the lifetime of the service. The default polling interval is 30 seconds.
// Start a channel //Set the polling interval in seconds here. var pollingInterval = 30;
Client Alerts SDK activities are logged for the purpose of debugging, monitoring and so on. The log file location will be configurable.
The Client Alerts JavaScript SDK logs three types of events:
Each log entry contains a timestamp and a log message.
Applications register with the Client Alerts server to be notified when alerts are received. The Client Alerts service polls the eBay Client Alerts server and delivers alerts to the application.
In this example, new public alerts are updating the displayed information in a badge widget.
/**
* callback function for processing returned ChannelContent
* @param {com.ebay.clientalertsservice.eventType} data
*/
this.OnCallbackSuccess = function (msg){
var ChannelMessageList = document.getElementById("ChannelMessageList");
// reset the inbox
ChannelMessageList.innerHTML = "";
// populate inbox
if(msg != null && msg != undefined && msg.length > 0)
{
for (var i = 0; i< msg.length; i++)
{
var msgLabel = i + ". " + msg[i].eventType + " " +
new Date().toLocaleTimeString();
var msgValue = me.formatEventMessage(msg[i]);
ChannelMessageList.options[i]= new Option(msgLabel, msgValue, false, false);
}
}
document.getElementById("ChannelMessages").wrap = "soft"; // only worked in IE
document.getElementById("ChannelMessages").value =
"message received: \n" + ChannelMessageList.options[0].value;
// reset current price
if(msg[0].priceChange != null && msg[0].priceChange.currentPrice != null)
{
highlightCurrentPrice( msg[0].priceChange.currentPrice.currencyID
, msg[0].priceChange.currentPrice.value);
}
}
The Client Alerts JavaScript SDK provides a way for applications to be optionally notified of error conditions during the retrieval of alerts.
The SDK notifies users of both client errors and system errors.
Errors caused by the client application, or un-recoverable system errors, will be reported to client if error callback is registered. Examples:
Other errors, caused by the system, for example, network, OS, etc, will be reported to client application. The JavaScript SDK will try to recover until asked to stop by the client.
The Client Alerts APIs return the alerts to the JavaScript SDK in JavaScript Object Notation (JSON) format. The SDK provides interfaces to the client application, and these interfaces return message objects. Parsing the message payload and constructing message objects will be done by the SDK. You will be writing your application to the provided interfaces and will not be expected to parse the message payload.
The Client Alerts SDKs support both the public and private Client Alerts APIs. The developers of third-party applications are responsible for securing the token management functionality. For APIs that return private data, the third-party application obtains the token and passes the token to the SDK.
Managing Client Alert preferences is not supported via the SDKs. All notification delivery preferences are managed through the eBay Trading API call SetNotificationPreferences.
The Client Alerts SDK is compatible with a certain version of the Client Alerts API. The Client Alerts SDK will not be on the same release cycle as the Client Alerts APIs, so the version number of the SDK will not be the same as the version number of the APIs. The application will not be able to configure or modify the version of the Client Alerts Service. The SDKs will be forward compatible with the latest version of the Client Alerts APIs. Any changes to the API signature will be handled gracefully by the SDK.
This section lists major classes in the eBay Client Alerts JavaScript SDK.
You can store the .js type classes (included in the Client Alerts JavaScript SDK download) locally, and reference them directly by including them in the needs statement.
Note that knowledge of JavaScript is required to implement your callback function. Some knowledge of error handling is recommended, but you can use code that is similar to what is presented in the samples and tutorials. Knowledge of JSON is not required, but the link is provided here for your convenience.
The following table describes the resources that we have provided to help you learn about creating Client Alerts JavaScript widgets. Click the links within the table to become familiar with any of the resources listed in the table.
| Resource | Link(s) | Description |
|---|---|---|
| Client Alerts JavaScript SDK .zip File | eBay Client Alerts JavaScript SDK | This is the bundle of Client Alerts JavaScript SDK files. It includes: Documentation, source code, and samples. |
| Client Alerts JavaScript SDK Readme File | README | This document discusses the Client Alerts JavaScript SDK in general, what is included, how to download the SDK, recommended steps to follow, and SDK license information. |
| Client Alerts JavaScript SDK Developer Guide | you are here | (THIS guide.) This is the overview of the Client Alerts JavaScript SDK. It includes a general description of how to create and deploy an eBay Client Alerts JavaScript widget and provides links to related resources. |
| Client Alerts JavaScript Widget Tutorials | Widget Tutorials | To give you hands-on experience with the Client Alerts JavaScript SDK, in case you would like a more in-depth understanding before creating your own widgets. |
| Client Alerts Web Services Call Reference | Client Alerts Web Services Call Reference | To help you understand what the SDK calls are retrieving from the eBay API servers. |
| JavaScript Information | JavaScript | To help you understand the JavaScript document methods and learn how to display your returned data in an interface format. When using the SDK, you will need to implement a JavaScript display function - there is no display interface class in the kit, because each developer will want to create their own implementation, depending on what they're creating. |
| JSON Information | JSON | To increase your understanding of the JSON request and response methods that are used to retrieve data from the eBay Client Alerts API servers. |
You can implement one of the parse methods from the data object classes to handle the data once it is returned.
The Client Alerts JavaScript SDK does not include an interface for displaying your data through a series of UI components. You can display the data returned in any way that you can code the UI elements using JavaScript. The example below, from the ItemBadgeWidget sample shows one way to implement a callback function to process your returned data. In this case, the callback function is called, "filterResults". It retrieves the item ID from findItemsResponse and then uses that item ID to call getItem.
There are two ways that you can deploy your completed JavaScript
widgets:
1. Upload them to a widget-hosting site, and then refer to the
location from your web page.
2. Host the widgets on your own web server.
With either of these methods, you need to point to the location of the widget by adding a source tag to your .html page that contains the URL of the web page that contains your widget.
© 2007-2008 eBay Inc. All rights reserved.
eBay and the eBay logo are
registered trademarks of eBay Inc.
All other brands are the property of their
respective owners.