Creating Visitor Data Assets

37 Creating Visitor Data Assets

Oracle WebCenter Sites: Engage lets you design online sites that gather information about your site visitors and customers, and then use that information to personalize the product placements and promotional offerings for each visitor. The information about visitors is stored in visitor data assets. There are three kinds of visitor data assets: visitor attributes, history attributes, and history types. The definitions of visitor data types are treated as assets in the WebCenter Sites database.

Topics:

37.1 About Visitor Data Assets

Do you want to group your site visitors into segments? You can do this with the three types of visitor data assets: Visitor attributes, History attributes, and History types.

To create visitor data assets, you create entries in the visitor data tables in the WebCenter Sites database and reserve a place in the database to store information of that kind for your site visitors.

See these topics:

37.1.1 Visitor Attributes

Visitor attributes hold types of information that specify one characteristic only (scalar values). For example, you can create visitor attributes named years of experience, job description, or number of children.

When the visitor changes the data, the new data overwrites the old data. Engage does not assign a timestamp to the data that is stored as a visitor attribute and does not store revisions. For example, if a visitor changes his entry for job description from butcher to baker, the information that the visitor was once a butcher is overwritten. You cannot, for example, create a segment based on bakers who used to be butchers.

For historical data, you must use history types.

37.1.2 History Attributes and History Definitions

History attributes are individual information types that you group together to create a vector of information that Engage treats as a single record. This record is the history definition. For example, a history definition called purchases can consist of the history attributes SKU, itemname, quantity, and price.

Engage references data stored as a history definition as a whole or an aggregate. It assigns a timestamp to each instance of the recorded definition and keeps each of those records. This means that you can sum or count history definitions and you can determine the first time or the last time a history definition was recorded for a visitor. Using the example in the preceding paragraph, you can create a segment based on the amount of money a visitor spends on specific items during a set period of time.

History definitions store historical data.

37.1.3 Segments

Segments are assets that divide visitors into groups based on common characteristics. Segments are built by determining which visitor data assets to base them on and then setting qualifying values for those criteria.

To create visitor data assets, you create fields that can be used in two places:

As criteria for segments. That is, as configuration options in the Engage Segment Filtering forms (because you define segments with the visitor data assets). In other words, the choices you make about the data types for the attributes determine their appearance and behavior in the Segment forms. When you create these assets, you are customizing the Segment forms.
On your public site pages. That is, as form fields or hidden fields on registration pages and other pages.

Segments are the key to personalizing merchandising messages with Engage. When visitors browse your site, the information they submit is used to qualify them for segment membership. When the site opens a page with a recommendation or promotion, Engage determines which segments a visitor belongs to and opens the product recommendations or promotional messages that are designated for those segments.

Configuring Bluekai Type of Segments

Websites that use Bluekai (Oracle Marketing Data Cloud) can track site visitors using the Bluekai related WebCenter Sites APIs. WebCenter Sites provides two types of APIs that help identify visitor behavior and recommend personalized content respectively.

Bluekai Client Side API: This JavaScript API helps identify the visitor behavior. It is available at <sites-war>/integration/bluekai/bluekaihelper.js. This API uses a JavaScript object whose constructor contains the following signature:

 function(bluekaiSitesCookieName, bkSegmentsCookiePrefix, pixelLimit, expires)

where:

bluekaiSitesCookieName: Value of the bluekai.sites.cookie property in WebCenter Sites.
bkSegmentsCookiePrefix :Value of the bluekai.segments.cookie.prefix property in WebCenter Sites.
pixelLimit – It’s a Bluekai property. It indicates the number of slots available in the container for firing image tags. (See Integrating into the Oracle Bluekai Platform in Using Oracle Data Cloud) If you do not provide any value for this parameter in the constructor, API sets its default value as 1.
expires : A numeric value indicating the cookie expiry time as number of days. This expiry time is for the cookie which this JavaScript API creates. To address the case when a user does not want to store this cookie for a fixed period (that is, the cookie should remain only for the current session), the value for this property should be zero (0). The default value is 1.

The JavaScript object contains these methods:

fetchSements(siteID): Based on information from Bluekai, this method determines WebCenter Sites segments for which the current visitor qualifies. Client side developers should use this API in web pages (preferably in a wrapper) of their site as follows:

<html> <html>
<head>
<script type="text/javascript" src="http://<server host n port>/sites/js/integrations/bluekai/bluekaihelper.js"></script>
</head>
<body>
<script>
var bkClient = new com.oracle.bluekai.Client('<%=ics.GetProperty("bluekai.sites.cookie")%>','<%=ics.GetProperty("bluekai.segments.cookie.prefix")%>',1,2); // expiry time is 2 days for cookies to be created using call 'fetchSegments'
bkClient.fetchSegments(bluekaiContainerID); //'bluekaiContainerID' is the site ID created in the Bluekai partner website.
</script>
....
...
</html>

Assuming that some segments of the Bluekai type have been created in WebCenter Sites, the above code identifies those Segment assets that the current site visitor qualifies for, based on the data (campaigns) returned by Bluekai. This API then sets these segment names (comma separated) in a cookie. The naming convention of the cookie is as follows:

<bluekai.segments.cookie.prefix><bluekaiContainerID>

For example, if the value of the bluekai.segments.cookie.prefix property is extSegments and bluekaiContainerID’s value is '55552', then the cookie name would be 'extSegments55552'. And, its value would be the names of the Bluekai type of Segments. If no segments are qualified (either because Bluekai knows nothing about current visitor OR WebCenter Sites has no Bluekai Segments matching campaigns returned by Bluekai), then the cookie value would be 'none'. Before the cookie expires, the subsequent call to the fetchSegments method does not hit Bluekai anymore. This saves money, as each call to Bluekai incurs cost.

postUserData(siteId, data): Websites can use this Java Script API to post the visitor behavior data to Bluekai on behalf of the current site visitor. For example, if a website is dedicated to tennis fans, it can let the API know that the website visitors are interested in the 'Tennis' sport. To inform the API, the website can post a key-value pair to Bluekai indicating that the current visitor is interested in tennis, as follows:

var data = [];
				data["interest"]="Tennis"; data["location"] = "India";
				bkClient.postUserData(<siteID>,data);

In Bluekai terminology, these pieces of information are called pHints. You should create 'rules' in the Bluekai partner site, say interest is Tennis. You use these rules in a category and use that category while creating Audience to associate a campaign with that audience. Once this is done, the above code sends data to Bluekai that enables the current site visitor to qualify for this campaign.

Server Side API: The Java API BluekaiHelper (available in the package oracle.fatwire.integrations.bluekai) provides the names of qualified bluekai segments by reading the cookie created above. This API should be used in conjunction with WebCenter Sites Engage API to display recommended items to a site visitor. Class BluekaiHelper includes the getQualifiedBluekaiSegments(ICS) method, which can be used to get recommended assets. For example, you create a segment named interestedInTravel which uses a campaign created in Bluekai, meant for identifying visitors interested in travelling. You create a recommendation asset, say named TravelRecommendation which uses this segment to define what all articles/assets should be shown to a visitor that qualifies for the interestedInTravel segment. So, the server side code to fetch recommended articles for current visitor (this sample code is assumed to be in a template controller) can be as follows:

List<Map> recommendations = newRecommendationReader()
					        .forSegments(BluekaiHelper.getInstance().getQualifiedBluekaiSegments(ics) )
                            .forSite("avisports")
					        .readRecommendations("TravelRecommendation");

37.1.4 Developing Visitor Data Assets: Process Overview

There are five general steps for creating and using visitor data assets (fields):

A cross-functional design team including developers and marketers determines what kind of data you want to gather about your site visitors.
You (the developers) create and define the necessary visitor attributes, history attributes, and history definitions by using the forms in Engage.
The marketers use the Segment Filtering forms in Engage to categorize groups of visitors based on these visitor attributes, history attributes, and history definitions.
You program the appropriate site pages with the Engage XML or JSP object methods to collect and store the data, using either server-side validation or Javascript to validate the input on the pages. For example, you can create an online registration form for visitors to fill out by using JavaScript to validate the input and the Engage XML or JSP tags to process and store that information in the WebCenter Sites database.
When visitors browse your site, the information they submit is used to qualify them for segment membership. If your site is using promotions and recommendations based on segments, the message displayed for the visitor is personalized based on the segments that he or she qualifies for.

37.2 Creating Visitor Data Assets

Before you begin creating visitor data assets, meet with the marketing and design teams to determine the kinds of data that you want to collect about visitors. And, examine the Segment Filtering forms to understand the context in which the visitor data assets that you create are used by the marketers.

Additionally, note that the visitor data assets are listed by their descriptions rather than by their names in the Segment Filtering forms.

You can use the following data definitions for your visitor and history attributes:

Note:

When you're using the vdm:setscalar API, keep in mind that it doesn't validate the size limit that you’ve specified for each data type. Therefore, Oracle recommends that you follow these ranges when you're specifying values for scalar attributes for each type.

String: Can hold up to 255 characters.
Boolean: True and false are the only legal values.
Short: Valid range of values is 0 through 255.
Integer: Valid range of values is 0 through 65,535.
Long: Valid range of values is 0 through 65,535.
Double: Valid range of values is 0 through 4,294,967,295.
Date: format is yyyy-mm-dd hh:mm:ss.s
Money: Format is currency; valid range of values is unlimited.
Binary: For visitor attributes only; used for binary data such as image files or cart objects.

Note:

Binary visitor attributes can record binary data for individual visitors. Visitor attributes of this type are not displayed in the Segment Filtering forms and cannot be used to define a segment. Creating an attribute of type binary reserves space in the WebCenter Sites database that you use to store objects by using the XML object method VDM.SAVESCALAROBJECT or its JSP equivalent vdm:savescalarobject to convert an object from the WebCenter Sites name space into a binary form.

This section includes the following topics:

37.2.1 Creating Visitor Attributes

Create visitor attributes with the Engage forms.

To create a new visitor attribute:

Open the Admin interface.
Click New on the button bar.
From the list of asset types, select New Visitor Attribute. (Site Visitor Attribute asset types must be enabled for your site.)

The Site Visitor Attribute form opens.

Figure 37-1 Site Visitor Attribute

Description of "Figure 37-1 Site Visitor Attribute"

Note:

Visitor Attribute does not appear in the menu when your login password combination doesn't have administrator rights. Contact the site administrator and request that the admin user profile be assigned to your user name.
In the Name field, enter a unique, descriptive name for the attribute (field). You can enter up to 32 alphanumeric characters, including spaces. The first character must be a letter.
In the Description field, enter a description of the attribute (field). Enter a value (alphanumeric characters) that help you easily identify the attribute (attributes are listed by their descriptions rather than their names in the Segment Filtering forms).
In the Category field, enter the category for the attribute. The text that you enter in this field determines where the attribute is listed in the Segment Filtering form. You can enter up to 32 alphanumeric characters.

Note:

Categories for visitor attributes must be different from the categories for history definitions.

37.2.1.1 Configure the Data Type

To configure the data type:

From the Type drop-down list, choose a data type.
If you chose string, then in the Length field enter the maximum number of characters allowed for input in the attribute (field). You can enter a value up to 255.
From the Null allowed drop-down list, choose true to allow null values or false to require input for the attribute when it is used. For example, an attribute with a Boolean data type cannot allow a null value.
If you chose false from the Null allowed drop-down list, then in the Default Value field enter a default value that is appropriate for the attribute's data type. For example, for the integer datatype, the default value must be a number.

Note:

If you selected binary as the data type, you cannot specify a default value for the attribute.

37.2.1.2 Configure the Constraint Criteria

The constraint options that are available for validating input into the attribute depend on the data type that you designated for the attribute.

Option 1: Configure the Attribute to Accept Free-Form Text

From the Constraint type drop-down list, choose none. For example, a visitor attribute named residence of type string might accept unconstrained text as input.

Option 2: Configure the Attribute to Accept Input from a Range of Values

To configure the attribute to accept a specific range of values, the data type must be integer, short, long, double, or money.

From the Constraint type drop-down list, choose range.

The form displays range fields.
In the Lower range limit field, specify the smallest possible value that can be accepted in the attribute when it is used as a field. This value cannot be a negative number.
In the Upper range limit field, enter the largest possible value that can be accepted in the attribute when it is used as a field. (For a short data type, you can enter a value up to 255; for integer, up to 65,535; for double, up to 4,294,967,295; for money, unlimited.)

For example, an attribute named Age can be restricted to accept values between 1 and 110 only.

Option 3: Configure the Attribute to Offer a Set List of Values in a Drop-Down List

From the Constraint type drop-down list, choose enumeration.

The form displays text boxes for adding options.
In the Add Enumerated Value field, enter the name of the first option. For example, an attribute named gender can have female as an option.
Click Add.

The option is moved to the list.

Figure 37-2 Enumeration Constraints

Description of "Figure 37-2 Enumeration Constraints"
Repeat these steps for each of the options that you want to make available for this attribute (field).

37.2.1.3 Save the Attribute

(Optional) If you have access to multiple sites, specify whether you want to share this attribute with them. On the Inspect form, from the More menu, choose Share Visitor Attribute.
When you are finished configuring the visitor attribute, click Save.

Engage creates an entry for this attribute in the visitor data asset tables in the WebCenter Sites database and reserves a place in the database to store information of that type for your site visitors.

Engage opens a summary of the attribute in the Inspect form.

You can now use this visitor attribute in a segment.

Note:

After a visitor attribute is used to define a segment, deleting the attribute invalidates the segment. Be sure to correct your segments if you delete an attribute.

37.2.2 Creating History Attributes

The purpose of history attributes is different from the purpose of visitor attributes: you create history attributes to be used by history definitions. You cannot use them in the Segment Filtering forms until they are used to define a history definition.

Perform the procedures in this section to create history attributes by using the Engage forms.

Note:

You cannot edit or delete a history attribute after it has been used to define a history definition. You also cannot remove it from the history definition. Therefore, stop using the history definition whose history attribute has been changed. Create a new history attribute, create a new history definition, and then start using the new history definition.

To create a new history attribute:

Open the Admin interface.
On the button bar, click New, then select New History Attribute from the list.

The History Attribute form opens.

Figure 37-3 History Attribute Form

Description of "Figure 37-3 History Attribute Form"

Note:

If History Attribute does not appear in the menu, it means that your login/password combination does not give you administrator rights. Contact the site administrator and request that the admin user profile be assigned to your user name.
In the Name field of the History Attribute form, enter a unique, descriptive name for the attribute (field). You can enter up to 32 alphanumeric characters, including spaces. The first character must be a letter.
In the Description field, enter a description of the attribute (field). Enter a value (alphanumeric characters) that help you easily identify the attribute (attributes are listed by their descriptions rather than their names in the Segment Filtering forms).
From the Type drop-down list, choose a data type.
If you selected string, in the Length field enter the maximum number of characters allowed for input in the attribute (field).
To make this attribute a required field when the history definitions that use it define a segment, select true in the Must be specified field.
From the Filter drop-down list, choose true.

If you do not set Filter by to true, the marketers cannot use the attribute (field) as a constraint for any history definition that it belongs to when they create segments.

If the data type for this attribute is numeric, then by default the attribute is included in the list of attributes that can be selected for a Total constraint in a segment, whether you set Filter by to true or to false. However, to use a numeric attribute as a constraint in any other way, you must set Filter by to true.
From the Null allowed drop-down list, choose true to allow null values or false to require input for the attribute when it is used. For example, an attribute with a Boolean data type cannot allow a null value.
If you chose false from the Null allowed drop-down list, in the Default Value field enter a default value that is appropriate for the attribute's data type. For example, the default value for the integer datatype must be a number.

37.2.2.1 Configure the Constraint Criteria

The constraint options available for validating input into the attribute depend on the data type you designated for the attribute.

Configure the Attribute to Accept Free-Form Text

From the Constraint type drop-down list, choose none. For example, a history attribute named Street Name of type string might accept unconstrained text as input.

Configure the Attribute to Accept Input from a Range of Values

To configure the attribute to accept a specific range of values, the data type must be integer, short, long, double, or money. This figure shows the range constraints and related fields.

Figure 37-4 Range Constraints and Related Fields

Description of "Figure 37-4 Range Constraints and Related Fields"

From the Constraint type drop-down list, choose range.

The form displays range fields.
In the Lower range limit field, specify the smallest possible value that can be accepted in the attribute when it is used as a field. This value cannot be a negative number.
In the Upper range limit field, enter the largest possible value that can be accepted in the attribute when it is used as a field. (For a short data type, you can enter a value up to 255; for integer, up to 65,535; for double, up to 4,294,967,295; for money, unlimited.)

For example, an attribute named Number of Items can be restricted to accept values between 1 and 50 only.

Configure the Attribute to Offer a Drop-Down List of Specific Values

From the Constraint type field, choose enumeration.

The form displays text boxes for adding options.

Figure 37-5 Enumeration Constraints Fields

Description of "Figure 37-5 Enumeration Constraints Fields"
In the Add Enumerated Value field, enter the name of the first option.
Click Add.
Repeat these steps for each of the options that you want to make available for this attribute.

37.2.2.2 Save the History Attribute

When you are finished configuring the history attribute, click Save.

Engage creates an entry for this attribute in the visitor data asset tables in the WebCenter Sites database and reserves a place in the database to store information of that type for your site visitors.

You can now use this history attribute to define a history definition.

37.2.3 Creating History Definitions

History definitions are made up of history attributes. Therefore, there must be at least one history attribute created before you can create a history definition.

To create history definitions using the Engage forms:

Log in to the Admin interface.
Click New and select History Definition from the list.

The History Definition form opens.

Figure 37-6 History Definitions Fields

Description of "Figure 37-6 History Definitions Fields"

Note:

History Definition does not appear in the menu if your login/password combination does not have administrator rights. Contact the site administrator and request that the admin user profile be assigned to your user name.
In the Name field, enter a unique, descriptive name for the history definition (record). You can enter up to 32 alphanumeric characters, including spaces. The first character must be a letter.
In the Description field, enter a description of the history definition. Enter a value (alphanumeric characters) that help you easily identify the history definition (history definitions are listed by their descriptions rather than their names in the Segment Filtering forms).
In the Category field, enter a category for the history definition. The text that you enter in this field determines how the history definition is sorted and displayed in the Segment Filtering forms. You can enter up to 32 alphanumeric characters.

Note:

Categories for history definitions must be different from the categories for visitor attributes.
In the Fields area, select the history attributes that make up this history definition. Select an attribute and then click the right arrow to move it to the list on the right. Use Ctrl+click to select multiple attributes at the same time.

Note:

After a history attribute is used to define a history definition, you can no longer edit or delete that history attribute.
Click Save.

Engage creates an entry for this history definition (record) in the visitor data asset tables in the WebCenter Sites database and reserves a place in the database to store information of that type for your site visitors.

Engage then opens a summary of the history definition in the Inspect form.

You can now use this history definition in a segment.

37.3 Verifying Visitor Data Assets

To determine that the visitor attributes, history attributes, and history definitions are properly set up, examine the Segment Filtering forms and check whether the visitor assets that you created were configured correctly.

Create segments that use each of the visitor attributes and history definitions that you created.
Determine that the constraint definitions are correct and that the input ranges are accepting the correct range of input.

37.4 Approving Visitor Data Assets

To correctly publish a history definition, you must also approve its history attributes for publishing.

When your visitor data assets are ready, approve them so that they can be published to the delivery system.

To approve any asset, choose Approve for Publish from the drop-down list in the icon bar in the asset's Edit or Inspect form.