1
Introduction

The OP (Oracle9iAS Personalization) REAPI (Recommendation Engine Application Programming Interface) enables a Web application written in Java to collect and preprocess data used to build OP models and to request recommendations. The recommendations are returned in real time.

OP also includes the Recommendation Engine Batch API, which returns bulk recommendations.

REAPI was designed to be extensible, to minimize the number of API functions, to be uniform, and to keep the number of arguments to a minimum.

Appendix A contains examples of how to perform common tasks using REAPI.

Appendix B contains a complete example of REAPI use.

OP includes a demo program that helps you learn how the API methods work. OP also contains javadoc associated with the jar files.

Note: REAPI and REAPI Demo are installed on the system where Oracle9iAS is installed.

REAPI Prerequisites

Before you can use REAPI methods, OP must be installed and the appropriate tables must be created and populated. If you plan to use existing data, the data must be converted to use the appropriate schema. If you plan to use Hot Picks, you must specify Hot Picks groups, as well as Hot Picks. If you are using one or more taxonomies, they must be properly specified.

If you plan to request recommendations, you must build and deploy an OP package before you request any recommendations. Use the OP Administrative UI to do this.

For detailed information about how to install OP, see the Oracle9iAS Personalization Administrator's Guide. For information about how to create and deploy packages, see Getting Started with Oracle9iAS Personalization and the online help for the Administrative UI.

Definitions and Concepts

This section describes the collections of methods that make up the REAPI and concepts and terms used in the description of the API.

End Users (Customers and Visitors)

End users (users of a Web site that uses OP for personalization services) are divided into two groups: customers and visitors. A customer is a registered user, who can be identified by a unique customer ID assigned by the Web application. A visitor is an unregistered user; a visitor is usually assigned a visitor ID by the Web application. A visitor can become a customer by completing registration. End users are specified using the IdentificationData class.

Sessions

The Web application that calls REAPI can be either

• sessionful, that is, it creates a session for each user visit to the Web site

• sessionless (stateless), that is, it does not create such a session

OP is always sessionful; it creates a session even if the Web application does not.

During the OP session, the Web application can collect data and/or request recommendations.

Sessionful Web Applications

If the Web application is sessionful, it can explicitly create an OP session using one of the following methods:

• createCustomerSession to create a session for a customer (registered user)

• createVisitorSession to create a session for a visitors (a user who isn't registered)

The Web application then uses the createSessionful() method of the class IdentificationData to create identification data used during the session.

Sessionless Web Applications

If the Web application is sessionless, the recommendation engine (RE) automatically creates an OP session for the first REAPI method (either data collection or recommendation request) issued for a given customerId.

The Web application then uses the createSessionless() method of the class IdentificationData to create identification data used during the session.

Collecting Data

OP supports collecting several kinds of data: demographic data, purchasing, rating, and navigation data. The Web application decides what kind of data to collect.

Note: Ratings in OP are in "ascending order of goodness", that is, the higher the rating, the more the user prefers the item. Low rated items are items that the user does not prefer. OP algorithms use these assumptions, so it is important that ratings are in ascending order of goodness.

Data for both visitors and customers can be either persisted (stored in the database) or not. Data is collected in an RE and is persisted in the MTR. A configuration parameter specifies whether or not to persist data. For more information about what data is persisted and when, see the discussion of data synchronization in the Oracle9iAS Personalization Administrator's Guide.

Data collection makes it possible to generate recommendations based on activity during the current session as well as historical data.

Making Recommendations

For both visitors and customers, recommendations are based on two kinds of data:

• Historical data, which is stored in the database and retrieved at the beginning of the current session

• Data collected during the current session

Hot Picks

On some e-commerce sites, vendors promote certain products called "hot picks"; the hot picks might, for example, be this week's specials. The hot pick items are grouped into Hot Pick Groups. The hot pick items and groups are specified by the OP administrator in the Mining Table Repository (MTR); each hot picks group is identified by a (long) integer.

Using REAPI

Before you can use OP, the following must be true:

• A recommendation engine farm containing at least one recommendation engine must exist.

• A package must have been successfully deployed in the recommendation engine farm.

Getting Started with Oracle9iAS Personalization and the online help for the OP Administrative UI explain how to perform these steps.

Some REAPI methods collect data in the Recommendation Engine (RE), which resides in Oracle9i database; others retrieve recommendations.

You can then either collect data or get recommendations. You cannot get recommendations until there is an existing deployed package, which is created using the OP Administrative UI. You cannot create a package until there is some data available; this data can either be collected using the REAPI or converted from existing data collected by your Web application and stored in an Oracle database.

When you design an OP application, you must decide if there should be more than one RE and, if there are several REs, how to use them. For a discussion of the design considerations, see "Recommendation Engine Usage" in Appendix A.

Recommendations may want to take income level (salary) into consideration; for example, you may want to recommend items that the user can afford to buy. If the users of the Web site live in several countries (for example, the Web site sells items in Japan and India), see "Handling Multiple Currencies" in Appendix A.

Sample REAPI Usage

OP includes a sample program (REAPI Demo) that illustrates the use of many of the REAPI methods. This sample program can be used to learn about REAPI calls and can also be used to verify that OP is correctly installed.

After you have installed OP, start REAPI Demo by opening the following URL in Netscape or Internet Explorer:

http://server/redemo/

where server is the name of the system where Oracle9iAS is installed. The REAPI test site is displayed.

To view the source code for the OP REAPI Demo, click "View Source Code."

For information about how run the demo, see Getting Started with Oracle9iAS Personalization. There are also some examples of how to perform typical tasks using REAPI in Appendix A of this manual and a complete example using all REAPI functionality in Appendix B.

Creating an REProxyRT Object

Before you can use any of the REAPI methods, you must create at least one REPRoxyRT object; see Appendix A for details.

Starting a Session

If the Web application is sessionful, it must start a session. The Web application must take care to specify a unique session ID for each application session. For an example of how to do this, see Appendix A.

If the Web application is sessionless, it does not have to start a session. (In this case OP will start an internal session for a given user when the Web application makes the first REAPI call.)

OP starts a session for each user, as defined by the user ID provided by the Web application. If two people are using a site at the same time and they both use the same user ID (and the application does not distinguish between different sessions), then OP assigns the same session ID to both users. OP treats them as a single user. After the OP session times out, OP assigns a new session ID when the user logs in again.

Sessionful and sessionless applications get recommendations on behalf of a user. User IDs must be unique.

Creating Instances of Objects

To use the REAPI, you must create instances of the objects used by the API method signatures. Use the REAPI supporting classes, described in Chapter 2, to create these instances. It is always necessary, for example, to create an IdentificationData object. For examples, see Appendix A and the complete example in Appendix B.

Providing Data

OP generates recommendations based on data describing past and/or current user behavior.

If the Web application has user data stored in an Oracle table, the data must be transformed and stored in the Mining Table Repository (MTR) before it can be used to generate recommendations.

A Web application can also collect data during the current session. This data can be used to make recommendations during the current session and it can be stored to make recommendations in future sessions.

The following methods manage data that you collect during the current session:

addItem();
addItems();
removeItem();
removeItems(); 

These methods add information to or remove information from the OP Recommendation Engine (RE) and its cache for a specified OP internal session ID. The session ID is stored in the IdentificationData passed in the REAPI method.

Getting Recommendations

To get a recommendation, the Web application calls one of the following recommendation methods:

• crossSellForItemFromHotPicks()

• crossSellForItemsFromHotPicks()

• rateItem()

• rateItems()

• recommendBottomItems()

• recommendCrossSellForItem()

• recommendCrossSellForItems()

• recommendFromHotPicks()

• recommendTopItems()

• selectFromHotPicks()

These methods are used to get recommendations for either visitors or customers.

Creating Recommendations

OP uses rule tables stored in the RE cache to calculate the recommendations requested by the methods listed above. The specific rule table used depends upon the REAPI method made. In general, the antecedents of the rules are matched against the data in cache (both historical and current session data) and the probabilities of the various consequents are computed. These items are then ordered by probability, and numberOfItems (an API argument) items are returned.

If there is enough memory in the RE database, the RE caches all rules associated with a particular package deployed from the MTR to the RE, not just the most recently used rules.

Scoring for Visitors:

For visitors, only current session data is used. Usually only navigational data (click stream) data is persisted for visitors, but if the Web application persists other kinds of data for visitors, that data will also be used for model building. (OP builds a model when it creates a package.) The scoring of these different methods uses only the data stored in the RE cache by addItem() methods.

Scoring for Customers:

For customers, the scoring is the same as for visitors. For customers, historical data can also be used for scoring.

The OP Mining Table Repository (MTR) contains historical rating, transactional data, and navigational data stored in both detailed and aggregated formats. The MTR also contains demographic data. When scoring for customers, the RE retrieves the demographic data and the aggregated version of the other data source types.

Making Recommendations

REAPI methods that make recommendations return the recommendations to the Web application. The Web application then decides which recommendations to pass to the user.

Closing a Session

A sessionful Web application should use closeSession() to close the OP session. If there is no explicit closeSession() method, OP automatically closes the session when it times out.

In a sessionless Web application, the OP session closes when it times out.

For either sessionless or sessionful Web applications, the time-out period is specified as a configuration parameter.

See the Oracle9iAS Personalization Administrator's Guide for information about configuration parameters.

Removing the REProxyRT Object

Before you exit the application, you should destroy any proxy objects that you created. To do this, use one of the following methods in the class REProxyManager: destroyProxy or destroyAllProxies.