2 REAPI Overview

2.2.1 REAPI End Users (Customers and Visitors)

End users (users of a Web site that uses OracleAS Personalization 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.

2.2.2 Web Applications and Sessions

Some Web applications are stateful, that is, they maintain the state of the client activities during a certain time period; other Web applications are stateless. Most Web applications that support eCommerce are stateful or sessionful. A client session often starts with a login and ends with either an explicit logout or when the session times out. OracleAS Personalization maintains its own session for data mining purpose regardless of whether the application is stateful or stateless. If the application is stateful, the session that OracleAS Personalization maintains can be perfectly mapped as the application's session. (For an eCommerce application, the recommendation made to the user is based on the user activities.) If the application does not maintain user sessions, OracleAS Personalization then tracks each user session itself. In this case, the OracleAS Personalization session starts when a particular user ID appears in any REAPI method call the first time, and the session ends when the session times out, that is, when the user ID remains inactive for a preset time period.

In summary, the Web application that calls REAPI can be either of the following:

• sessionful (stateful), 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

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

During the OracleAS Personalization session, the Web application can collect data or request recommendations or both.

2.2.3 REAPI Sessionful Web Applications

If the Web application is sessionful, OracleAS Personalization will map its session to the application session. To create a sessionful application, use 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.

2.2.4 REAPI Sessionless Web Applications

If the Web application is sessionless, the recommendation engine (RE) will maintain OracleAS Personalization sessions by itself. An OracleAS Personalization session will be created when the first REAPI method (either data collection or recommendation request) issued for a given customerId. The RE will track user activity until the session is timed out, that is, until the given customerId is inactive for a specified period.

The Web application uses the createSessionless() method of the class IdentificationData to create user identification for the session.

2.2.5 REAPI Data Collection

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

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 mining table repository (MTR) database. 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 Oracle Application Server Personalization Administrator's Guide.

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

2.2.6 REAPI 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

2.2.7 REAPI 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 OracleAS Personalization administrator in the Mining Table Repository (MTR); each hot picks group is identified by a (long) integer.

2.3.1 REAPI Demo Program

OracleAS Personalization includes 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 OracleAS Personalization is correctly installed.

After you have installed OracleAS Personalization, 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 Oracle Application Server is installed. The REAPI test site is displayed.

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

For information about how run the demo, see the Oracle Application Server Personalization User's Guide. There are also some examples of how to perform typical tasks using REAPI in Chapter 5 of this manual and a complete example using all REAPI functionality in Appendix A.

2.3.2 Creating REProxyRT Objects

Before any recommendation or data collection requests can be processed using REAPI methods, at least one REProxyRT object that connects to the designated RE must be created.

In a Web application environment, it is better to create all required proxy objects during the initialization stage to avoid proxy startup overhead when making the first recommendation request. See Chapter 5 for more information about proxies.

2.3.3 Starting an REAPI 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 Chapter 5.

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

OracleAS Personalization 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 OracleAS Personalization assigns the same session ID to both users. OracleAS Personalization treats them as a single user. After the OracleAS Personalization session times out, OracleAS Personalization 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.

2.3.4 Creating Instances of REAPI Supporting Classes

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 3, to create these instances. It is always necessary, for example, to create an IdentificationData object. The following classes are frequently used in REAPI signatures:

• IdentificationData

• FilteringSettings

• TuningSettings

• Item

• DataItem

• Recommendation

• Recommendation Content

For examples, see Chapter 5 and the complete example in Appendix A.

2.3.5 Collecting Data for REAPI Recommendations

OracleAS Personalization generates recommendations based on data describing past or current user behavior or both.

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.

Use the following methods to collect and manage data during the current session:

   addItem();

   addItems();

   removeItem();

   removeItems();

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

OracleAS Personalization Data Caching

When one of the OracleAS Personalization data collection methods (addItem() or addItems()) is called, the user profile data is first saved in a buffer (the Data Collection Cache) on the Application Server. The data collection cache is created as part of the initialization of an REProxy object. The size of the data buffer is custom-configurable and is specified by the input parameter cacheSize of the method REProxyManager.createProxy(). The data saved in the buffer is periodically saved (archived) in the database. An overloaded createProxy method allows the archive interval to be set. The data collection cache consists of two identical buffers; when one buffer is being archived, the other is used for saving the incoming data. Thus the data collection operation runs without interruption.

2.3.6 Getting REAPI 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.

How REAPI Creates Recommendations

OracleAS Personalization 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 invoked. 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, current visitor session data is used in conjunction with the historical information collected for previous visitors and customers. Usually only navigational data (click stream) 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. (OracleAS Personalization 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 of customers can also be used for scoring.

The OracleAS Personalization Mining Table Repository (MTR) contains historical rating, transactional data, and navigational data stored in both detailed and aggregated formats for the customer. 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.

2.3.7 Making REAPI 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.

2.3.8 Closing an REAPI Session

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

In a sessionless Web application, the OracleAS Personalization 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 Oracle Application Server Personalization Administrator's Guide for information about configuration parameters.

2.3.9 Removing REProxyRT Objects

If you wish to destroy proxies programmatically you can use one of the following methods:

• destroyProxy(), which destroys one name proxy

• destroyAllProxies(), which destroys all existing proxies.

Both methods forcefully remove proxies regardless of their active status. Any active sessions will eventually timeout based on the setting in the RE_CONFIGURATION table in the RE schema.

See detailed discussion in Chapter 5 for different usage models.