With Oracle WebCenter Sites: Engage you can design online sites that gather information about visitors which is useful in discerning products and services that visitors would be interested in. Based on this information, these sites display personalized promotional messages for each visitor.
This chapter refers to specific XML tags that you use to accomplish the tasks being described. In all cases, there are also equivalent JSP tags. The XML and JSP tags are all documented in the Oracle Fusion Middleware Tag Reference for Oracle WebCenter Sites Reference.
At an Engage site, a visitor context is created during a visitor's session. This context includes session objects such as the shopping cart, visitor segments and promotions. The commerce context encompasses the visitor context and gives you access to it.
Five types of session objects are placed in the visitor context:
Current shopping cart.
List of segments that the visitor belongs to.
List of promotions that the visitor qualifies for.
Time object that is used for calculating time-based rules for segments and promotions.
Utility object that gives you, the developer, access to product attributes.
There are two sets of XML and JSP object methods that serve as your interface to these contexts:
Commerce context methods, which you use to place objects in the visitor context.
Visitor Data Manager methods, which you use to gather, store, and retrieve visitor data and to associate a visitor's data with the correct visitor.
Engage creates a unique visitor ID for each visitor for each session. It stores these IDs in the
VMVISITOR table in the WebCenter Sites database. The data gathered for a visitor during that session is identified by that visitor ID. To link the data gathered from one session to the data from another, your site pages must assign aliases that link those visitor IDs.
You use the following Visitor Data Manager object method to create an alias:
<VDM.SETALIAS KEY="keyvalue" VALUE="aliasvalue"/>
When you use this tag, Engage associates the visitor session ID with the alias, and writes them both to the
Figure 50-1 VMVISITORALIAS Table
The values in this table link the data that is gathered in separate sessions to the same visitor because the alias provides a link to the visitor IDs that are recorded for that visitor. In the illustration above, the data recorded in the session associated with the visitor ID 973717492772 is linked to the data associated with the visitor ID 973717564355 because they have aliases with the same key/value pair.
All visitor information is associated with sessions that are linked through common aliases. That is, aliases with the same key/value pairs can be accessed during the current session. It is considered current visitor information. You can create aliases with cookies, with login IDs, or with any other unique identifier that your site uses to recognize visitors.
VMVISITORALIAS table grows quickly. See Visitor Tables (Engage) in Oracle Fusion Middleware Administering Oracle WebCenter Sites.
You need to program your online pages for collecting, validating, and writing the visitor data to the WebCenter Sites database. There are three Visitor Data Manager object methods that write visitor information to the database.
<VDM.SETSCALAR ATTRIBUTE="attribute" VALUE="value"/> records visitor attributes.
<VDM.RECORDHISTORY ATTRIBUTE="attribute" LIST="valuelist"/> records history definitions.
<VDM.SAVESCALAROBJECT ATTRIBUTE="attribute" OBJECT="objectname"/> records visitor attributes of type binary. The demo site delivered with Engage uses this method to store shopping carts across sessions and to store saved searches for visitors.
Because these tags write information to the database, they can be a factor in the performance of your delivery system. Be sure to use them efficiently.
This table shows the tables that store the visitor data:
Table 50-1 Tables to Store Visitor Data
|XML or JSP Object Method||Database Table That It Writes To|
(These tables are dynamically generated for each history definition. Engage creates a unique table for each one.)
These tables grow quickly. See Visitor Tables (Engage) in Oracle Fusion Middleware Administering Oracle WebCenter Sites.
There are also several Visitor Data Manager object methods that retrieve this information from the WebCenter Sites database. See Logging and Debugging Errors.
For information about these and other Engage XML and JSP tags, see the Oracle Fusion Middleware Tag Reference for Oracle WebCenter Sites Reference.
It takes you three steps to code site pages that collect visitor data. Create forms to capture the data, create a submit page to validate the data, and program the submit page to write the validated data to the database.
The general steps to code your site pages to collect visitor data are:
Create forms to capture the data that you need your visitors to manually provide. It is a good practice to create form fields with names that match the names of the attributes that you created. See Creating Visitor Data Assets.
Attributes are listed by their descriptions rather than by their names in the Engage Segment forms. Be sure that you do not confuse their attribute names with attribute descriptions when you are creating form fields or writing values to the WebCenter Sites database.
Program the submit page to write the validated data to the WebCenter Sites database. Be sure to use the names of the attributes and history definitions and not their descriptions. Here are some examples:
See these topics:
The following example uses attribute names to write the registration information to the database:
<!-- Write the registration information to the database.--> <VDM.SETSCALAR ATTRIBUTE="name" VALUE="Variables.name"/> <VDM.SETSCALAR ATTRIBUTE="age" VALUE="Variables.age"/> <VDM.SETSCALAR ATTRIBUTE="jobdesc" VALUE="Variables.jobdesc"/>
Because history definitions hold multiple values as an aggregate, you must create a list of the data before you can write it to the database. In this example, a form writes an order to the WebCenter Sites database:
<!-- Write the order details to a list. --> <!-- assume that Variables.order_id is set to the order id --> <!-- assume that Variables.wasCouponUsed is set to 1 (yes) or 0 (no) --> <!-- assume that Variables.shippingtype is set to UPS or FedEx --> <!-- assume that Variables.order_price is set to the total amount of the order --> <LISTOBJECT.CREATE NAME="histList" COLUMNS="orderid, shippingtype, price, couponUsed"/> <LISTOBJECT.ADDROW NAME="histList" orderid="Variables.order_id" shippingtype="Variables.shippingtype" price="Variables.order_price" couponUsed="Variables.wasCouponUsed"/> <LISTOBJECT.TOLIST NAME="histList" LISTVARNAME="itemList"/> <!-- Write the list to the history definition named visitorOrderHistory in the WebCenter Sites database.--> <VDM.RECORDHISTORY ATTRIBUTE="visitorOrderHistory" LIST="itemList"/>
You can use that record to determine information about how many orders a visitor had made, when their first or last purchase was, and the total amount they've spent.
Binary visitor attributes allow you to convert an object from the WebCenter Sites name space into a binary form. The following procedure uses two visitor attributes of type binary: one to store shopping carts across sessions and one to store saved searches:
To gather data about visitor behavior (such as clickstream information), program your pages to collect the data without using input forms.
For example, you can use a history definition to record the number of times a visitor browses the site.
Whenever visitor data is written to the database, segments and promotions can also change. After any change to visitor data, be sure to recalculate the segments and promotions lists. There are two Commerce Context object methods that you can use:
COMMERCECONTEXT.CALCULATEPROMOTIONS recalculates both the segments that the visitor belongs to and the promotions that apply to those segments.
Whenever visitor data is written to the database, ratings for assets can also change. After any change to visitor data, be sure to refresh the ratings of any assets that are in an existing asset set.
ASSETSET.ESTABLISHRATINGS tag to refresh the asset ratings of the assets in a set.
For information about these and other Engage XML and JSP object methods, see the Oracle Fusion Middleware Tag Reference for Oracle WebCenter Sites Reference.
You need to create a template element that invokes a recommendation asset and displays the items that the recommendation returns. You use the key Commerce Context object method to invoke a recommendation asset. This method retrieves and lists the assets that meet the recommendation criteria. The object method invokes other methods that calculate the segment and promotion lists.
<COMMERCECONTEXT.GETRECOMMENDATIONS COLLECTION="recommendationname" [LIST="inputlist" VALUE="rating" MAXCOUNT="assetcount"] LISTVARNAME="assetlist"/>
This method retrieves and lists the assets that match the recommendation constraints passed to the method. It uses the following arguments:
COLLECTION: The name of the recommendation. To use the same
Template for several recommendations, code it to supply the recommendation identity through a variable.
LIST: The name of the list of assets. This is the name that you want to be used as the input for the calculation.
You use this argument when the recommendation named by
COLLECTION is a context-based recommendation. Columns are
assetid. You can create this list by creating a list object and adding rows for each asset that you want to use as input.
VALUE: The default rating for assets that do not have one. If you do not declare a value, unrated assets are assigned a default rating of 50 on a scale of 0-100. It is recommended that you keep this value set to 50.
MAXCOUNT: (Optional.) The maximum number of assets to return. Use this value to constrain the list of recommended assets.
LISTVARNAME: The name that you want to assign to the list of assets. Its columns are:
The object method invokes the methods that calculate the segment list and the promotion list, if they have not yet been created and placed in the visitor context. Remember that promotions do not have templates, they override the
Template that a recommendation is using. Rather than the items identified by the recommendation asset, the object method returns the promotion asset's ID if promotions apply to the current visitor and override the recommendation named by the
COMMERCECONTEXT.GETSINGLERECOMMENDATION object method returns one recommended asset based on the recommendation criteria passed to the method. Typical uses for this method are to feature one product or to put one product on sale. For information about this object method and its JSP equivalent, see the Oracle Fusion Middleware Tag Reference for Oracle WebCenter Sites Reference.
Before you begin coding the
Templates for recommendations, be sure to complete the following tasks:
Meet with the marketing team to define all the merchandising messages that you want to display on your site and plan how to represent those messages in recommendations and promotions. For example, do you want to display a list of links to other products? What information should the link include? The product name only or also the price? What will be displayed when a recommendation returns a promotion rather than a list of assets?
Determine where and on which pages the recommended assets from each recommendation are displayed.
To use templates to render items that are returned by recommendation assets, you must complete at least the following basic steps:
LISTVARNAMEargument. This list includes the asset IDs and asset types of those items. Use that information to extract the asset attributes that you want to display (for example,
You can use the
ASSETSET.GETASSETLIST object methods to sort and display the returned assets and their attributes.
Templateasset for this
Templateelement. Enter a name that describes what the element does so that when you create a recommendation asset, you know which
Templateto assign to it. Identify the path to the element (its location in the element catalog) in the Element Name field.
Templateasset when other assets are published.
Oracle Real-Time Decisions (RTD) is an engine that helps site visitors make decisions by recommending the best options when they make their choices. When the
commercecontext:getrecommendations tag is invoked, it sends a list of recommendations and certain visitor profile information to Oracle RTD. Oracle RTD then ranks the recommendations and, using the
maxcount="<n>" parameter, returns a refined list of n recommendations best suited for the visitor's profile.
This release of WebCenter Sites supports Oracle Real-Time Decisions (RTD) version 3.0 series. RTD 11g is not supported.
Oracle RTD (and other engines) can be integrated with WebCenter Sites by use of the following tags:
commercecontext:getrecommendations tag, where
engineparameters are generic parameters that can be set to invoke any engine. For integration with Oracle RTD, the engine parameter must be set to
engineparameters must name a list of the following Oracle RTD-specific parameters:
advisor (integration point),
attributes (visitor profile),
commercecontext:inform tag, which also takes the parameters
engineparameters. For this tag,
engineparameters must name a list of the following parameters:
informant (integration point),
attributes (visitor profile), and
choices parameter (choice of recommendations) was removed from this tag. The list of choices is now passed to RTD with the list
After Oracle RTD learns the list of attributes from the
commercecontext:getrecommendations tag, you, the developer, can use the
sessionkey parameter to map visitors to their profiles for subsequent
commercecontext:inform calls. For example, after a
commercecontext:getrecommendations call has been made to Oracle RTD, the next call from the same visitor may pass an empty string for attributes and use the same
sessionkey to get recommendations.
commercecontext:inform tags to invoke Oracle RTD requires adding the following properties to the
For more information about the
commercecontext tags, parameter definitions, integration with Oracle RDT, and sample code, see the Oracle Fusion Middleware Tag Reference for Oracle WebCenter Sites Reference. For information about the
rtd.host property, and
rtd.choiceId.pattern property, see the Oracle Fusion Middleware Property Files Reference for Oracle WebCenter Sites.
When you code your shopping cart pages using the shopping cart interface with Engage there are some facts and tips that you should keep in mind.
If your site uses promotions, you must code your cart pages to apply the discounts from the promotions.
COMMERCECONTEXT.DISCOUNTTEMPCART object methods to apply promotional discounts to the shopping cart.
It is a good practice to clear existing discounts from the cart before applying them again.
You can store carts across sessions by writing them to the database as a visitor attribute of type binary (a scalar object). Be sure to write the cart object to the database each time the cart is modified.
If your site uses a visitor login feature, there can be conditions under which you should merge shopping carts. For example, a visitor adds products to her cart before she logs in. Then, when she logs in, Engage finds a stored cart that also has items in it. In such a case, merge the carts.
For information about the
CART object methods and their JSP equivalents, see the Oracle Fusion Middleware Tag Reference for Oracle WebCenter Sites Reference.
During development phase, you must verify that session linking is set up correctly, specific attributes obtain the value that you expect, and recommendations return the items that you expect. There are several Engage object methods that you can use to retrieve and review information and values by writing information to a browser window or to the JRE log.
This topic lists the Visitor Data Manager object methods that you probably use the most. For information about these and any other XML and JSP object methods, see the Oracle Fusion Middleware Tag Reference for Oracle WebCenter Sites Reference.
See these topics:
Use the following Visitor Data Manager object methods to verify that pages that handle session linking are creating the aliases correctly:
<VDM.GETALIAS KEY="keyvalue" VARNAME="varname"/>
Retrieves an alias.
Retrieves the visitor's commerce ID from session data.
<VDM.GETACCESSID KEY="pluginname" VARNAME="varname"/>
Retrieves the visitor's access ID from session data.
Use the following Visitor Data Manager object methods to retrieve values stored for specific visitor attributes, history attributes, and history definitions (records):
<VDM.GETSCALAR ATTRIBUTE="attribute" VARNAME="varname"/>
Retrieves a specific visitor attribute.
<VDM.LOADSCALAROBJECT ATTRIBUTE= "attribute" VARNAME= "varname"/>
Retrieves (materializes) an object stored as a visitor attribute of type binary.
<VDM.GETHISTORYCOUNT ATTRIBUTE="attribute"VARNAME="varname"[STARTDATE="date1" ENDDATE="date2"LIST="constraints"]/>
Retrieves the number of history definition records that were recorded for the visitor that match the specified criteria.
<VDM.GETHISTORYSUM ATTRIBUTE="attribute" VARNAME="varname"[STARTDATE="date1" ENDDATE="date2" LIST="constraints"]FIELD="fieldname"/>
Sums the entries in a specific field for the specified history definition.
<VDM.GETHISTORYEARLIEST VARNAME="varname" [STARTDATE="date1"ENDDATE="date2" LIST="constraints"]/>
Retrieves the timestamp of the first time the specified history definition was recorded for this visitor.
<VDM.GETHISTORYLATEST VARNAME="varname"[STARTDATE="date1"ENDDATE="date2" LIST="constraints"] />
Retrieves the timestamp of the last time (that is, the most recent time) the specified history definition was recorded for this visitor.
Use the following Commerce Context object methods to verify pages that display recommendations and promotions:
Lists the segments that the visitor belongs to. It examines the available visitor data, compares it to the data types that define the segments, and then lists the segments that are a match.
Creates the list of promotions that the current visitor is eligible for.
<COMMERCECONTEXT.GETRATINGS ASSETS="assetlist" LISTVARNAME="ratinglist" DEFAULTRATING="defaultrating"/>
Calculates the ratings of the assets in a named list according to how important the asset is to this visitor based on the segments that the visitor belongs to.
Retrieves the list of segments that the current visitor belongs to.