40 Coding Engage Pages

This chapter presents information about designing an online site that gathers visitor information and personalizes promotional messages for each visitor based on that information.

This chapter contains the following sections:

• Section 40.1, "Commerce Context and Visitor Context"

• Section 40.2, "Identifying Visitors and Linking Sessions"

• Section 40.3, "Collecting Visitor Data"

• Section 40.4, "Coding Site Pages That Collect Visitor Data"

• Section 40.5, "Templates and Recommendations"

• Section 40.6, "Shopping Carts and Engage"

• Section 40.7, "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 WebCenter Sites Tag Reference.

40.1 Commerce Context and Visitor Context

During a visitor's session at an Engage site, a visitor context is created for that visitor. 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

The commerce context encompasses the visitor context and gives you access to it.

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.

40.2 Identifying 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 40-1 VMVISITORALIAS Table

Description of "Figure 40-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 that 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. For information about managing it and the other visitor data tables, see the Oracle Fusion Middleware WebCenter Sites Administrator's Guide.

40.3 Collecting Visitor Data

To collect visitor data, you must program your online pages to gather it, validate it, and then write it to the WebCenter Sites database.

There are three Visitor Data Manager object methods that write this 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.

These are the tables that store the visitor data:

Table 40-1 Object Methods and Database Tables

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. For information about managing them, see the Oracle Fusion Middleware WebCenter Sites Administrator's Guide.

There are also a number of Visitor Data Manager object methods that retrieve this information from the WebCenter Sites database. See Chapter 10, "Error Logging and Debugging."

Note:

For information about these and other Engage XML and JSP tags, see the Oracle Fusion Middleware WebCenter Sites Tag Reference

40.4 Coding Site Pages That Collect Visitor Data

This section presents an overview of the general steps that you follow when you code your site pages to collect visitor data:

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 Chapter 38, "Creating Visitor Data Assets" for more information.

   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, if you created a visitor attribute of type string with a length of 30, be sure that the form does 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:

This section contains the following topics:

• Section 40.4.1, "Example 1: Visitor Attributes"

• Section 40.4.2, "Example 2: History Definition"

• Section 40.4.3, "Example 3: Visitor Attribute of Type Binary"

40.4.1 Example 1: Visitor Attributes

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

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

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

40.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 sample site delivered with Engage uses two visitor attributes of type binary: one to store shopping carts across sessions and one to store saved searches.

To see these examples, use Oracle WebCenter Sites Explorer to examine ElementCatalog/OpenMarket/Demos/CatalogCentre/GE/Navigation/stylesheet.xml and ElementCatalog/OpenMarket/Demos/CatalogCentre/GE/myge.xml

1. If you want to gather data about visitor behavior (clickstream information, for example), you can program your pages to gather that without using input forms. For example, the demo site delivered with Engage uses a history definition to record the number of times a visitor browses the site.

   For this examples, use Oracle WebCenter Sites Explorer to examine ElementCatalog/OpenMarket/Demos/CatalogCentre/GE/Navigation/stylesheet.xml

2. Whenever visitor data is written to the database, segments and promotions can also change. Therefore, 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. Therefore, 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 WebCenter Sites Tag Reference

40.5 Templates and Recommendations

The key Commerce Context object method for invoking a recommendation asset is this one:

<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. If you plan to use the same template for several recommendations, code the template to supply the identity of the recommendation 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. For an example, use Oracle WebCenter Sites Explorer to examine ElementCatalog/OpenMarket/Demos/CatalogCentre/GE/cart.xml.

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

If the segment list and the promotion list have not yet been created and placed in the visitor context, this object method invokes the methods that calculate them. Remember that promotions do not have templates, they override the template that a recommendation is using. If there are any promotions that apply to the current visitor and that override the recommendation named by the COLLECTION argument, the object method returns the ID of the promotion asset rather than the items identified by the recommendation asset.

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. See the Oracle Fusion Middleware WebCenter Sites Tag Reference for information about this object method and its JSP equivalent.

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 will be displayed.

Creating Templates for Recommendations

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. (Name, price, SKU, for example.)

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

   For an example, use Oracle WebCenter Sites Explorer to examine ElementCatalog/OpenMarket/Demos/CatalogCentre/Templates/GE/recommendation.xml.

3. Open Engage. Under New, select 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 ElementCatalog) in the Element Name field.

4. Publish the Template asset when other assets are published.

5. Render the recommendations on the appropriate site pages.

Creating 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 via the list tag attribute.

Once 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, once 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 futuretense_xcel.ini 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 WebCenter Sites Tag Reference. For information about the rtd.inline.service.name property, rtd.host property, and rtd.choiceId.pattern property, see the Oracle Fusion Middleware WebCenter Sites Property Files Reference.

40.6 Shopping Carts and Engage

When you are using the shopping cart interface with Engage, there are a number of additional facts and tips to keep in mind while you code your shopping cart pages:

• 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 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, you would want to merge the carts.

For information about the CART object methods and their JSP equivalents, see the Oracle Fusion Middleware WebCenter Sites Tag Reference.

For an example of a Engage shopping cart, use Oracle WebCenter Sites Explorer to examine ElementCatalog/OpenMarket/Demos/CatalogCentre/GE/cart.xml.

40.7 Debugging Site Pages

During your development phase, you must verify that session linking is set up correctly, that specific attributes obtain the value that you expect, and that 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 section lists the Visitor Data Manager object methods that you will probably use the most. For information about these and any other XML and JSP object methods, see the Oracle Fusion Middleware WebCenter Sites Tag Reference

This section contains the following topics:

• Section 40.7.1, "Session Links"

• Section 40.7.2, "Visitor Data Collection"

• Section 40.7.3, "Recommendations and Promotions"

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

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

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