50 Coding Engage Pages

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.

Topics:

• Commerce Context and Visitor Context

• Identification of Visitors and Linking Sessions

• Collection of Visitor Data

• Coding of Site Pages That Collect Visitor Data

• Templates and Recommendations

• What You May Need to Know About Shopping Carts and Engage

• Debugging Site Pages

Note:

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.

50.1 Commerce Context and Visitor Context

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.

50.2 Identification of Visitors and Linking Sessions

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 VMVISITORALIAS table.

Figure 50-1 VMVISITORALIAS Table

Description of "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.

The VMVISITORALIAS table grows quickly. See Visitor Tables (Engage) in Oracle Fusion Middleware Administering Oracle WebCenter Sites.

50.3 Collection of Visitor Data

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.

  Note:

  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
VDM.SETSCALAR vdm:setscalar	VMVISITORSCALARVALUE
VDM.SAVESCALAROBJECT vdm:savescalarobject	VMVISITORSCALARBLOB
VDM.RECORDHISTORY vdm:recordhistory	VMz------------ (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.

50.4 Coding of Site Pages That Collect Visitor Data

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:

1. 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.

2. Create a submit page that validates the data that the visitor entered in the fields (either by using JavaScript or with a server-side validation method). The input data must comply with the constraints that you set for the attributes. For example, when a visitor attribute of type string has a length of 30, the form must not try to submit data from the form field with a length of 31.

3. 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:

• Example 1: Visitor Attributes

• Example 2: History Definition

• Example 3: Visitor Attribute of Type Binary

50.4.1 Example 1: Visitor Attributes

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"/>

50.4.2 Example 2: History Definition

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.

50.4.3 Example 3: Visitor Attribute of Type Binary

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:

1. 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.

2. 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

   • COMMERCECONTEXT.CALCULATESEGMENTS

   COMMERCECONTEXT.CALCULATEPROMOTIONS recalculates both the segments that the visitor belongs to and the promotions that apply to those segments.

3. 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.

   Use the ASSETSET.ESTABLISHRATINGS tag to refresh the asset ratings of the assets in a set.

   Note:

   For information about these and other Engage XML and JSP object methods, see the Oracle Fusion Middleware Tag Reference for Oracle WebCenter Sites Reference.

50.5 Templates and Recommendations

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 assettype and 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: assettype and assetid.

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 COLLECTION argument.

Note:

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.

50.5.1 Creating Templates for Recommendations

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:

1. Create a template element that invokes a recommendation asset. Use the object method described in the preceding section.
2. Code the template to display the items that are returned by the recommendation. The returned items are stored in a variable designated by the LISTVARNAME argument. 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, Name, Price, and SKU).

   You can use the ASSETSET.SETLISTEDASSETS and ASSETSET.GETASSETLIST object methods to sort and display the returned assets and their attributes.

3. Open Engage. Under New, choose Template. Create a corresponding Template asset for this Template element. Enter a name that describes what the element does so that when you create a recommendation asset, you know which Template to assign to it. Identify the path to the element (its location in the element catalog) in the Element Name field.
4. Publish the Template asset when other assets are published.
5. Render the recommendations on the appropriate site pages.

50.5.2 Creation of Templates for Recommendations Using Oracle Real-Time Decisions

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.

Note:

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:

• The commercecontext:getrecommendations tag, where engine and engineparameters are generic parameters that can be set to invoke any engine. For integration with Oracle RTD, the engine parameter must be set to rtd and engineparameters must name a list of the following Oracle RTD-specific parameters: advisor (integration point), attributes (visitor profile), sessionkey, and assetattributes.

• The commercecontext:inform tag, which also takes the parameters engine and engineparameters. For this tag, engineparameters must name a list of the following parameters: informant (integration point), attributes (visitor profile), and sessionkey.

Note:

The choices parameter (choice of recommendations) was removed from this tag. The list of choices is now passed to RTD with the list tag attribute.

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.

Note:

Using the commercecontext:getrecommendations and commercecontext:inform tags to invoke Oracle RTD requires adding the following properties to the wcs_properties.json file: rtd.inline.service.name and rtd.host.

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.inline.service.name property, rtd.host property, and rtd.choiceId.pattern property, see the Oracle Fusion Middleware Property Files Reference for Oracle WebCenter Sites.

50.6 What You May Need to Know About Shopping Carts and Engage

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.

  Use the COMMERCECONTEXT.DISCOUNTCART and 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.

50.7 Debugging Site Pages

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:

• Session Links

• Visitor Data Collection

• Recommendations and Promotions

50.7.1 Session Links

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.

• <VDM.GETCOMMERCEID VARNAME="varname"/>

  Retrieves the visitor's commerce ID from session data.

• <VDM.GETACCESSID KEY="pluginname" VARNAME="varname"/>

  Retrieves the visitor's access ID from session data.

50.7.2 Visitor Data Collection

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.

50.7.3 Recommendations and Promotions

Use the following Commerce Context object methods to verify pages that display recommendations and promotions:

• <COMMERCECONTEXT.CALCULATESEGMENTS/>

  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.

• <COMMERCECONTEXT.GETPROMOTIONS LISTVARNAME="promotionlist"/>

  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.

• <COMMERCECONTEXT.GETSEGMENTS LISTVARNAME="segmentlist"/>

  Retrieves the list of segments that the current visitor belongs to.