recommendations user guide

Recommendations

VERSION 2.4 USER GUIDE

2.4.01142010

Copyright 1996-2010. Adobe Systems Incorporated. All rights reserved. Omniture® is a registered trademark of

Adobe Systems Incorporated in the United States, Japan, and the European Community.

Terms of Use | Privacy Center

Omniture products and services are licensed under the following Netratings patents: 5,675,510, 5,796,952,

6,115,680, 6,108,637, 6,138,155, 6,643,696, and 6,763,386.

A trademark symbol (®, ™, etc.) denotes an Omniture trademark. An asterisk (*) denotes a third-party trademark. All

third-party trademarks are the property of their respective owners.

https://my.omniture.com/p/l10n/1.0/terms.html



https://my.omniture.com/p/l10n/1.0/privacy.html

https://my.omniture.com/p/l10n/1.0/privacy.html

Omniture Recommendations Version 2.4 User Guide - i

Preface

Omniture Recommendations automatically displays products that might interest your customers based on previous user activity on your

Web site. Recommendations helps direct customers to items they might otherwise not know about, improving sales generated on your

Web site.

User Guide Purpose

The Omniture Recommendations User Guide helps you create and manage the recommendations that you place on your Web site. It

also helps you understand how to measure the success of your recommendations so you can maximize their effect on your business. This

guide is meant primarily for Web marketers, but also contains some information that is useful for Web designers.

This guide contains the following chapters:

l Chapter 1: Getting Started with Omniture Recommendations

Contains information about starting recommendations and accessing recommendations functions.

l Chapter 2: Managing Your Recommendations

Contains information to help you set up and use recommendations, including understanding the information on a

recommendation card, creating or editing a recommendation, testing results, and deleting a recommendation.

l Chapter 3: Managing Templates

Contains information about creating and using the templates that control how a recommendation appears on a Web page.

l Chapter 4: Managing Recommendations Settings

Contains information about some advanced settings, including global exclusions, bulk editing recommendation information in

a spreadsheet or text editor, and downloading the mbox.js script.

l Chapter 5: Managing Mboxes

Contains information about how to implement mboxes (marketing boxes) on your Web site to provide customized content

based on your recommendations.

l Chapter 6: Managing Recommendations with Omniture Test&Target

Contains information about using Omniture Test&Target to provide advanced testing of your recommendations and target them

to certain customers based on specific criteria.

l Chapter 7: Using the Recommendations Download API

Contains information about using the Recommendations download API to download your recommendations in a .CSV file that

can be viewed in a spreadsheet or text editor. The .CSV file lists all recommendations for each product key.

l Chapter 8: Integrating Recommendations with Email

Contains information about using templates to integrate Recommendations with your email system.

Omniture Recommendations Version 2.4 User Guide - ii

Account Support

Omniture’s support team is here to:

l Answer specific product questions

l Ensure that you can utilize the reports to their maximum capacity

l Help resolve any technical difficulties you might have

For information about contacting Account Support, see Contact Information .

Service and Billing Information

Depending on the service level you purchased, some options described in this manual might not be available to you. Because each

account is unique, refer to your contract for pricing, due dates, terms and conditions. If you would like to add to or otherwise change

your service level, or if you have questions regarding your current service, please contact your Account Support Manager.

Feedback

We welcome any suggestions or feedback regarding Omniture SearchCenter or this manual. Please send comments to your Account

Support Manager.

Contact Information

Use the following information if you need to contact Omniture.

Corporate address Omniture, An Adobe Compay

550 East Timpanogos Circle

Orem, UT 84097

Phone 1.801.722.7000

Fax 1.801.722.7001

Toll free 1.877.722.7088 (support, billing and sales)

Support e-mail [email protected]

Sales e-mail [email protected]

Information e-mail [email protected]

Corporate URL http://www.omniture.com

Log-in URL http://my.omniture.com

Omniture Recommendations Version 2.4 User Guide - iii

Table of Contents

Preface i

User Guide Purpose i

Account Support ii

Service and Billing Information ii

Feedback ii

Contact Information ii

Chapter 1: Getting Started with Omniture Recommendations 1

1.1 What's New in This Release 2

1.2 Prerequisites 2

1.3 Preparing Your Web Site for Recommendations 2

Referencing the mbox.js File on Your Web Pages 3

Setting the Content Type for Remote Offers 3

Implementing Display Data Mboxes 4

Implementing an Order-Confirmation Details Mbox 4

Placing Mboxes to Display Recommendations 5

1.4 Starting Omniture Recommendations 6

1.5 Accessing Recommendations Functions 7

Chapter 2: Managing Your Recommendations 9

2.1 Understanding a Recommendation Card 10

2.2 Creating a New Recommendation 11

2.3 Activating or Deactivating a Recommendation 12

2.4 Previewing a Recommendation 12

2.5 Using Preview Options to Change the Page View 13

2.6 Editing a Recommendation 14

2.7 Setting the Recommendation Key 15

2.8 Selecting an Algorithm 17

2.9 Specifying a Data Source 18

2.10 Selecting a Template and Recommendation Area 18

2.11 Specifying How Many Visitors See Default Content 18

2.12 Deleting a Recommendation 19

Omniture Recommendations Version 2.4 User Guide - iv

2.13 Testing Recommendation Results 19

Viewing Test Results on the Recommendation Card 19

Viewing Complete Test Results 20

2.14 Understanding Recommendation Parameters 21

2.15 Creating a Custom Algorithm 24

Naming a Custom Algorithm with the Algorithm Name API 24

Uploading Custom Algorithm Data with the Upload API 24

Deleting a Custom Algorithm 26

2.16 Managing Recommendations with Omniture Test&Target 26

Chapter 3: Managing Templates 28

3.1 Creating a New Template 28

Creating a Flash Template 30

3.2 Editing a Template 30

3.3 Customizing a Template 31

3.4 Copying a Template 32

3.5 Deleting a Template 33

3.6 Using a Download-Only Template 33

3.7 Using the Template Manager 33

Chapter 4: Managing Recommendations Settings 35

4.1 Creating Global Exclusions 35

4.2 Uploading Entities to Recommendations 36

Downloading the Entity Upload Template 36

Editing the Entity Upload Template 36

Uploading the Entity Information to Recommendations 37

4.3 Downloading the Mbox.js Library File 37

Chapter 5: Managing Mboxes 39

5.1 Using an Mbox on Your Web Site 41

Preparing for the Mbox 41

Creating the mbox.js Reference 41

Creating the Mbox 42

Placing an Mbox Around a Table 42

Placing an Mbox Around a Table Cell 43

Creating Multiple Mboxes on a Page 44

Omniture Recommendations Version 2.4 User Guide - v

Creating a Whole Page as an Mbox 44

Dynamic Mboxes 44

5.2 Troubleshooting Mboxes 45

Troubleshooting the Debug Window 45

Mbox Troubleshooting Guide 46

Troubleshooting Resources 46

5.3 Understanding Display Attributes 47

5.4 Sending Sales Data Values 48

Chapter 6: Using the Recommendations Download API 50

Chapter 7: Deleting an Item From Your Catalog 51

Chapter 8: Deleting All Items From Your Catalog 52

Chapter 9: Integrating Recommendations with Email 53

Chapter 1: Getting Started with Omniture Recommendations

OmnitureRecommendations Version 2.4 User Guide - 1

Chapter 1Chapter 1:

Getting Started with OmnitureRecommendations

Omniture Recommendations automatically displays products or content that might interest your customers based on previous user

activity on your Web site. Recommendations helps direct customers to items they might otherwise not know about, improving sales

generated on your Web site.

Recommendations helps you:

l Choose sophisticated algorithms to automate recommendations across multiple areas of your site

l Automatically display the recommendations by using a few JavaScript snippets on your site

l Test and optimize the display templates and algorithms that display the Recommendations

This section contains the following topics:

l What's New in This Release

l Prerequisites

l Preparing Your Web Site for Recommendations

l Starting Omniture Recommendations

l Accessing Recommendations Functions

Terminology

Throughout this guide, new terms are defined as they are introduced. However, you should understand the distinction between

Recommendations (the name of the application) and recommendations (the Web site content created by the product).



1.1 What's New in This Release

This release of Recommendations includes the following new features:

l Flash template support:

l Easily display Recommendations in Flash ads and widgets on your sites.

l When you upload Flash files to Recommendations, Recommendations scans them for entity variables. Then, the

merchandiser can choose which values to display in the Flash file.

l Backup recommendations are now optional, allowing clients to decide whether they want generalized recommendations to

backfill their data.

l Environment support improvements enable clients to choose whether to use staging/dev data in those environments or to

always use production data.

l Improved synchronization between Recommendations and Test&Target:

l Deleting a recommendation in Recommendations also deletes the campaign in Test&Target.

l Errors are handled better when you cannot save the recommendation.

1.2 Prerequisites

You can use Omniture Recommendations alone or combine it with any of the following Omniture products:

l SiteCatalyst

l Test&Target

l SiteSearch

Although most functionality remains the same whether Recommendations is used alone or with other products, some recommendation

types are only available when you add the features of another product, as explained in Creating a New Recommendation.

1.3 Preparing Your Web Site for Recommendations

Before you use Recommendations, you need to prepare your Web site. To display your recommendations to site visitors, you must set up

sections of your Web pages as mboxes, special marketing boxes that enable you to dynamically change the content of selected areas on

your Web pages based on information gathered about site visitors.

If you do not set up mboxes on your pages, you can still use Recommendations to create and test recommendations, but you cannot

display dynamic content on your pages based on the test results.

Typically, mboxes are set up by Web site designers, not the marketers who normally create and use recommendations. Setting up an

mbox requires some familiarity with HTML coding and JavaScript, although you can follow the instructions in this guide even if you are

not a Web designer.

Implementing mboxes requires the following steps:



l Include references to the mbox.js file on your Web pages. See Creating the mbox.js Reference

l Set the content type for your page. See Setting the Content Type for Remote Offers

l Create mboxes to contain the latest information about each product that you want to recommend. See Implementing Display

Data Mboxes

l Create an mbox to capture order information. See Implementing an Order-Confirmation Details MboxPreparing Your Web Site

for Recommendations

l Create mboxes to display the recommendations. See Placing Mboxes to Display Recommendations

Referencing the mbox.js File on Your Web Pages

Referencing the mbox.js File on Your Web Pages

Any Web page that includes an mbox must reference the mbox.js file on the host. This allows the page to contact the Omniture

Recommendations server.

1. Create the reference code.

For example, if the mbox.js file is saved in a directory called /js, the reference must be similar to:

<script src="http://www.mycompany.com/js/mbox.js" type="text/javascript"></script>

2. Add areference to the head section of all Web pages that will have an mbox.

For example:

<head>


</head>

Tip: Add the mbox.js reference to an include or header file that exists in the head all of your Web pages.

Keep the following points in mind when adding the mbox.js reference to a Web page:

l Add the reference to the Web page only once, regardless of the number of mboxes on the page.

l Use a relative or absolute path depending on where you saved your mbox.js and as suits your file structure.

An absolute path is preferred.

l Best practice is to place the reference in the head section, but you can place it anywhere before the first mbox on your page.

Setting the Content Type for Remote Offers

When creating the "offers outside Omniture Test&Target" offer type, the ContentType HTTP Header must be correctly set to include the

charset for non ISO-8859-1 encoded content (UTF-8, Big5).

For example:

ContentType="text/html;charset=Big5"

Or:



ContentType="text/html;charset=UTF-8"

Implementing Display Data Mboxes

Display data mboxes send updated and dynamic catalog data to Omniture Recommendations so the recommendations displayed on your

site always include the most updated information about your products, without requiring an offline catalog import strategy.

This mbox sends the productId (referred to as entity.id in the code) that is used in the algorithms.

Note: entity.id must match the productId sent to Omniture Recommendations on the order confirmation page and the productId

used in SiteCatalyst product reports).

In general, the display information mbox might look like the following example. Change the details to refer to your products.

<div class="mboxDefault"></div><script language="JavaScript1.2">

mboxCreate('productPage',

'entity.id=67833',

'entity.name=Giants vs Rockies 5/12',

'entity.categoryId=baseball, Giants, SF Bay Area',

'entity.pageURL=http://www.tixplace.com/baseball/giants-tix/giantsvrockies5.12.2000-67833',

'entity.venue=AT&T Park',

'entity.secondary=Rockies',

'entity.thumbnailURL=http://www.tixplace.com/baseball/giants-tix/giants-136px.gif',

'entity.message=Family special',

'entity.value=15.99',

'entity.inventory=1'

);

</script>

Note: The display information mbox can also show recommendations. Place the mbox on your product details page in a location

where you want to show a recommendation.

Implementing an Order-Confirmation Details Mbox

You should place an mbox on the order confirmation page so Omniture Recommendations can capture order information as input to be

used by algorithms and for measuring performance in Recommendations.

Sales data can be sent to Omniture Recommendations from any mbox, but the parameters must follow the strict syntax in the sample

code below. The parameters orderId and orderTotal are required. The productPurchasedId attribute must match the entity.id display

variable.

Note: Replace the text shown in all caps with the real values for your product.



<div class="mboxDefault"></div>

<script type=”text/javascript">

mboxCreate('orderConfirmPage',

'productPurchasedId=LIST OF PRODUCT IDs FROM ORDER PAGE',

'orderId=ORDER ID FROM ORDER PAGE',

'orderTotal=ORDER TOTAL FROM ORDER PAGE');

</script>

Placing Mboxes to Display Recommendations

You should place mboxes everywhere on the site where your recommendations display. This might include the home page, category

pages, product or article pages, shopping cart, order confirmation pages, and so on.

The div before the mbox should be around the default content that displays if no recommendation is returned. The mbox name is

completely customizable, but it must be shorter than 255 characters.

If you display affinity recommendations (those based on a dynamic entity.categoryId or entity.Id) in the mbox, then pass the applicable

value as an mbox parameter in themboxCreate call.

You can display a recommendation based either on a category or on a product. For a category-based recommendation, the code might

look like this:

<body>

My existing page.

<div class="mboxDefault">

Part that I'd like to overlay when a recommendation is displayed

</div>

<script type=”text/javascript”>

mboxCreate('sidebar_recommendations','entity.categoryId=EN:Guide:1';

</script>

</body>

For a product-based recommendation, the code might look like this:

<body>

My existing page.


Part that I'd like to overlay when a recommendation is displayed

</div>


mboxCreate('sidebar_recommendations',’entity.id=12345’);

</script>



</body>

For more information about placing an mbox, see "Using an Mbox on Your Web Site" in the Omniture Recommendations help.

1.4 Starting Omniture Recommendations

Omniture Recommendations is accessed along with other Omniture products from the Omniture Suite landing page. When you purchase

Omniture Recommendations, you receive the user name, password, and other information required for accessing the application. If you

already have other Omniture products, such as SiteCatalyst, you can log in to Recommendations with the same credentials.

1. Log in to http://my.omniture.com with your Omniture login credentials.

2. Click Recommendations

The first time you start Recommendations, you see the Manage Recommendations screen:

l To learn more about Recommendations, click the links below Create New Recommendation.

These links appear only if you have not yet saved a recommendation.

l To create your first recommendation, see Creating a New Recommendation.

l To create a new template to use for your recommendations, see Creating a New Template.

l To use other Recommendations features, see Accessing Recommendations Functions.

http://my.omniture.com/



You can also access your other Omniture products from the product buttons along the top of the screen.

1.5 Accessing Recommendations Functions

The Recommendations menu displays when you log in to Recommendations and is available from all main screens.

The Recommendations menu contains the following options:

Menu Item Description

Recommendations Opens the Manage Recommendations page, where you can:

l View details and statistics for each recommendation

l Create a new recommendation

l Activate or deactivate a recommendation

l Preview a recommendation

l Edit a recommendation

l Delete a recommendation

For more information about managing recommendations, see Managing Your Recommendations.

Templates Opens the Template Manager page. You can perform the following actions from the Template

Manager page:

l Create a new template

l View the number of active and inactive recommendations that use each template

l Edit a template

l Delete a template

l Copy a template

For more information about templates, see Managing Templates.

Settings Opens the Settings page. You can perform the following actions from the Settings page:

l Create exclusions that prevent entities that contain specified criteria from being included in

a recommendation

l Upload a file containing additional product display information to show in your

recommendations

l Download the mbox.js JavaScript library file

l Reset the client API token



Menu Item Description

For more information about settings, see Managing Recommendations Settings .

Chapter 2: Managing Your Recommendations


Chapter 2Chapter 2:

Managing Your Recommendations

Use recommendations to configure the criteria that determine what should be offered to a customer based on the customer's behavior

on the Web site. To view your recommendations, select Recommendations from the main menu.

The Manage Recommendations page opens.

The Manage Recommendations page contains cards showing the details of each of your recommendations.


l Understanding a Recommendation Card

l Creating a New Recommendation

l Activating or Deactivating a Recommendation

l Previewing a Recommendation

l Editing a Recommendation

l Deleting a Recommendation

l Testing Recommendation Results

l Understanding Recommendation Parameters



2.1 Understanding a Recommendation Card

Recommendations are shown in cards on the Manage Recommendations page. Each card displays key information about a

recommendation.

Recommendation cards display the following information:

Element Explanation

Recommendation Name Displays the name of the recommendation at the top of each card.

Status Flag Shows whether the recommendation is active ( ) or inactive ( ). For

information about changing the status, see Activating or Deactivating a Recommendation.

The status flag does not appear next to a download-only recommendation because there is

nothing to activate or deactivate.

Toolbar Contains tools that help you manage your recommendation:

Deactivate ( ) or Activate ( ) changes the status of your recommendation. This icon

changes depending on the current status of the recommendation. See Activating or

Deactivating a Recommendation. TheDeactivate/Activate icon does not appear next to a

download-only recommendation because there is nothing to activate or deactivate.

Preview ( ) opens a preview of your recommendation in a browser window. The Preview

button is not available if the recommendation uses a Download Only template. See

Previewing a Recommendation.

Edit ( ) lets you change the details of your recommendation. See Editing a

Recommendation.

Delete ( ) permanently deletes a recommendation you no longer need. See Deleting a

Recommendation.

Recommendation Type Describes the type of recommendation to be offered. Mouse over this text for statistics that

show how the recommendation is performing. For a list of recommendation types, see

Editing a Recommendation.

No Recommendation Mouse over this text to show the performance statistics when users are not shown a

recommendation. When combined with the recommendation type described above, this

enables you to compare performance with and without the recommendation.

Statistics Shows the amount of lift, the revenue earned per customer visit, the number of orders

resulting from the recommendation, and the number of times the recommendation has been

clicked and the resulting number of site visits. Mouse over the recommendation type and No

Recommendation text to alternate between statistics with and without the recommendation.



Element Explanation

Templates and algorithms Shows the number of templates and algorithms being tested in the recommendation.

2.2 Creating a New Recommendation

A recommendation determines how a product is suggested to a Web site user, depending on that user's activities on the site. For

example, if you discover that users who purchase a portable DVD player often buy batteries, you might create a recommendation that

shows items that are often purchased together, using the people who bought this also bought that algorithm.

To create a new recommendation:

1. Click New Recommendation or Create New Recommendation ( ).

The Edit Recommendation page opens.

2. Click the Click here to name... text, then type a name for the recommendation.

The name should be descriptive enough that you can recognize it later.



3. Select one or more recommendation key, as explained in Setting the Recommendation Key.

4. Select the algorithm for each recommendation type, as explained in Selecting an Algorithm.

5. Select a data source, as explained in Specifying a Data Source.

6. Select a template, as explained in Selecting a Template and Recommendation Area.

If supported by the selected template, you can also set the area where the recommendation displays.

7. Specify the percentage of visitors who see default content, as explained in Specifying How Many Visitors See Default Content

8. Click Save.

After you save your new recommendation, it appears on the Manage Recommendations page as inactive. See Activating or Deactivating

a Recommendation for information about activating the new recommendation.

2.3 Activating or Deactivating a Recommendation

You can set whether a recommendation is active. If a recommendation is not active, it does not run on your Web pages or recommend

offers to your customers. You can easily recognize whether a recommendation is active by the status flag that appears beneath the

recommendation name on the Manage Recommendations page:

l

l

The icons on the toolbar change depending on the status of the recommendation. If the recommendation is active, the Deactivate icon (

) displays. Likewise, if the recommendation is inactive, the Activate ( ) icon displays.

To activate an inactive recommendation

1. On the Manage Recommendations page, find the inactive recommendation you want to activate.

2. Click Activate ( ).

To deactivate an active recommendation

1. On the Manage Recommendations page, find the active recommendation you want to deactivate.

2. Click Deactivate ( ).

2.4 Previewing a Recommendation

You can preview a recommendation to see how it looks in a browser. Browse around the site to see how the pages change with and

without the recommendations and mboxes.

Note: The Preview option is not available for recommendations that use a Download Only template.

To preview a recommendation:

1. On the Manage Recommendations page, find the recommendation you want to preview.

2. Click Preview ( ).

A new browser window opens, displaying a preview of your recommendation.



2.5 Using Preview Options to Change the Page View

The top of the preview screen contains a number of options:

View slider: Click either end of the slider to change the page view so you can compare how the page looks with and without a

recommendation.

More: ClickMore to see information about the recommendation target, the conversion, the location of the mbox, and the offer.



Less: Click Less to hide the additional information.

Hide mboxes: Prevents the mbox overlays from displaying.

2.6 Editing a Recommendation

You can change the details of a recommendation at any time.

You can test multiple recommendation types against each other by adding more than one algorithm.

Note: For information about using Omniture Test&Target to edit and manage a recommendation, see Managing Recommendations

with Omniture Test&Target.

1. On the Manage Recommendations page, find the recommendation you want to edit.

2. Click Edit ( ).

The Edit Recommendation page opens.



3. To change the recommendation name, click on the current name and type a new one.

4. Change the recommendation type if desired, as explained in Setting the Recommendation Key.

5. Change the algorithm if desired, as explained in Selecting an Algorithm.

6. Change the data source if desired, as explained in Specifying a Data Source.

7. Change the template if desired, as explained in Selecting a Template and Recommendation Area.

If supported by the selected template, you can also change the area where the recommendation displays.

8. Change the percentage of visitors who see default content, if desired, as explained in Specifying How Many Visitors See Default

Content

9. Click Save.

2.7 Setting the Recommendation Key

You can create multiple keys and test them against each other. Each algorithm is defined in its own tab. Traffic is split evenly across your

different algorithm tests. In other words, if you have two algorithms, traffic is divided equally between them. if you have two algorithms

and two templates, traffic is split evenly between the four combinations. You can also specify a percentage of site visitors who see the



default content, for comparison. In that case, the specified percentage of visitors see the default content, and the rest are split between

your algorithm and template combinations.

1. Create a new recommendation, or find the recommendation whose type to set and click Edit ( ).

2. To change the recommendation type, select the new type from the Base the recommendation on: dropdown list.

The list contains the following options:

Option Description

Current Page Activity This set of recommendation types is defined by the visitor's activity on the current page.

Current Item The recommendation is determined by the item the visitor is currently viewing.

Recommendations are set up to display other items that might interest visitors who are

interested in the specified item.

When this option is selected, the entity.id value must be passed as a parameter in the

display mbox.

Current Category The recommendation is determined by the product category that the visitor is currently

viewing. Recommendations are set up to display items in the specified product

category.

When this option is selected, the entity.categoryId value must be passed as a parameter

to the display mbox.

Custom Algorithms This set of recommendation types lists any custom algorithms that have been defined. If

there are no custom algorithms, this portion of the Recommendation Type list is empty.

Past Behavior This set of recommendation types is defined by the past behavior of your site visitors.

Last Purchased Item The recommendation is determined by the last item that was purchased by each unique

visitor. This is captured automatically by Recommendations, so no values need to be

passed on the page.

Last Viewed Item The recommendation is determined by the last item that was viewed by each unique vis-

itor. This is captured automatically by Recommendations, so no values need to be

passed on the page.

Most Viewed Item The recommendation is determined by the item that has been viewed most often, using

the same method as used for favorite category.

This is determined by recency/frequency algorithm that works as follows:

l 10 pts for 1st product view

l 5 pts for every one after

l At end of session divide all values by 2

For example, viewing surfboardA then surfboardB in one session results in A: 10, B: 5.

When the session ends, you will have A: 5, B: 2.5. If you view the same items in the next

session, the values change to A: 15 B: 7.5.

Favorite Category The recommendation is determined by the category that has received the most activity,

using the same method used for "most viewed item" except that categories are scored

instead of products.

Popularity The recommendation is determined by the popularity of items on your site. Popularity



Option Description

includes top sellers and top viewed by mbox data and, if you using SiteCatalyst, all of

the metrics available in the product report (previously called optimize on any metric).

These recommendations rank the items based on the criteria you choose in the Algo-

rithm dropdown.

Site Search The recommendation is determined by th esearch results on a particular page. Those

search results are used as input to the recommendation to determine complementary

items.

3. Click Save.

2.8 Selecting an Algorithm

The algorithm determines which action will result in which recommendation. You can test multiple recommendation types against each

other by adding more than one algorithm.

Note: If you are running a recommendation and change its algorithm, you will lose your settings data. A warning message reminds

you that this will occur.

1. Create a new recommendation, or find the recommendation whose algorithm you want to set and click Edit ( ).

2. Select an algorithm from the Algorithm dropdown list.

The following algorithms are available:

People who viewed this bought that: The items that are most often purchased in the same session that the specified item

is viewed. This option is not always displayed. If it is not displayed, contact your Omniture representative to have it enabled.

Because of the amount of data collected by this algorithm and its impact on algorithm processing speed, it is strongly

recommended that you set this algorithm to use one month of data or less.

People who bought this bought that: The items that are most often purchased by customers in the same order as the

specified item.

Popularity by Metric Choose any metric from the products report in SiteCatalyst to show the top products by revenue,

orders, cart adds, ratings, etc.

Top Sellers: The items that are purchased most often.

Most Viewed: The items that are viewed most often.

People who viewed this viewed that: The items that are most often viewed in the same session that the specified item is

viewed.

In addition, the following algorithm types are available if you use the relevant Omniture products:

Site Affinity: If you have both SiteCatalyst and DataWarehouse, this determines which products are best to recommend with

other products based on the following criteria:



l Product page views

l Cart adds

l Cart removes

l Purchases

l Site activity

You can configure this recommendation type to determine how much data is required before a recommendation is presented.

The site affinity recommendation is based on the certainty of a relationship between two products. For example, if you select

Strong, then the products with the strongest certainty of a match are recommended.

Omniture SiteSearch Recommendation: If you have SiteSearch, this people who searched for this bought that

recommendation displays in a promo area on the SiteSearch page. The placement of the mbox is determined with your

SiteSearch consulting team.

Advanced users can create custom algorithm types, as explained in Creating a Custom Algorithm.

3. Click Save.

2.9 Specifying a Data Source

1. Create a new recommendation, or find the recommendation whose algorithm you want to set and click Edit ( ).

2. Select a source from the Data Source dropdown list.

3. Click Save.

2.10 Selecting a Template and Recommendation Area

1. Create a new recommendation, or find the recommendation whose template you want to set and click Edit ( ).

2. To change the template used for the recommendation, click Presentation then select a template from the Display Template

drop-down list.

You can select multiple templates if you want to test templates against each other. For more information about templates, see

Managing Templates

3. If available for the selected template, select the recommendation area (mbox) where you want to display the recommendation.

4. Click Save.

2.11 Specifying How Many Visitors See Default Content

If testing is enabled, specify a percentage of users who will see default content. The remaining users see the recommendation. You can

compare the results from those who saw the recommendation against those who saw default content to determine how effective the

recommendation is at directing users toward your desired results.



1. Create a new recommendation, or find the recommendation whose template you want to set and click Edit ( ).

2. To change the template used for the recommendation, click Testing & Results.

3. To change the percentage of visitors who see default content, specify a percentage.

4. Click Save.

2.12 Deleting a Recommendation

You can delete a recommendation when you no longer want to use it.

1. On the Manage Recommendations page, find the recommendation you want to delete.

2. Click Delete ( ).

When you delete a recommendation, any results data associated with the recommendation is also deleted. The template is not deleted.

2.13 Testing Recommendation Results

You can compare the results of a recommendation with the results you get without it. This provides a clear picture of how well your

recommendations are working so you can adjust them for maximum performance.

When you create a recommendation (see Creating a New Recommendation), you can choose to enable testing. When you enable

testing, you decide how large to make each test group. For example, you might choose to display the recommendation to 80% of the

people who view a page. That means that 20% of the viewers will not see the recommendation. By comparing the success rates of the

two groups, you can see how effective your recommendations are. The viewers who do not see the recommendation see the default

content in the HTML code for the page.

Viewing Test Results on the Recommendation Card

The cards on the Manage Recommendations page show data about each recommendation, including the number of clicks, the amount

of money earned per page visit, and so on. The card shows the results for the top performing recommendation based on RPV, and for

the No Recommendation control group.

If you are testing multiple combinations of templates and algorithms, and want to see all of your results, not just the top performer, you

can do so on the recommendation's edit page, as explained in Viewing Complete Test ResultsViewing Test Results on the

Recommendation Card.

You can compare this information to the same data without the recommendation to see whether your recommendation is improving

sales.



To compare data with and without a recommendation, mouse over either the recommendation type (such as Top Sellers) orNo

Recommendation. The data changes to reflect the selected data type.

Viewing Complete Test Results

You can view more complete test results, including the results for multiple combinations of algorithms and templates, on the Edit page.

1. Click the recommendation whose results you want to view.

2. Click Testing & Results.

The test results display.

This report helps you compare the results of all your tested recommendations.



2.14 Understanding Recommendation Parameters

The following table lists all possible parameters you can set when creating or editing a recommendation, and the algorithms

where each parameter can be used.

Parameter Description Algorithm

Only recommend

products with

inventory greater

than or equal to

Specify how many items must be in stock before a

product is recommended.

The product is not recommended unless there are

at least the specified number in stock. This helps to

prevent recommending products that are sold out

or nearly sold out. You can also use this setting to

try to reduce the inventory of products that are

overstocked.

Top Sellers

Most Viewed

People Who Bought This Bought That

People Who Viewed This Bought That

Popularity By Metric

Site Affinity

Omniture SiteSearch Recommendation

Only recommend

products within the

price range

Specify the price range that products must fit into

before they are recommended.

This helps you target recommended products to

buyers. If, for example, a customer usually

purchases bargain products, lower-priced products

are recommended.

Top Sellers

Most Viewed




Only use data from

the previous

Specify the period for which data should be used

when calculating recommendations.

This helps you target recommendations based on

recent activity over a specified time period. Set the

time period to provide enough data for a valid

recommendation, but not so much data that the

recommendation is out of date.

The available choices are:

l Day

l Two days

l One week

l Two weeks

l One month

l Two months

Top Sellers

Most Viewed



People Who Viewed This Viewed That


Site Affinity


From which

categories would you

like to include

products?

Specify the categories that the recommendations

come from.

This helps you target recommendations based on a

customer's past purchases.

Top Sellers

Most Viewed




You can choose one of the following options:

l All categories

l Categories given by request parameter

l Select categories

If you choose Select categories, a list of possible

categories appears. Shift-Click or Ctrl-Click to select

multiple categories.

If you choose Categories given by request

parameter, the page that shows the

recommendation will request a specific category at

load time.

Attribute Weighting Apply a higher weighting items you want to show

more often. For example, give on-sale items a

higher weighting so they are recommended more

often than non-sale items. Multiple weightings can

be applied to the same algorithm, and the weight-

ings can be tested on split traffic in the rec-

ommendation.

Top Sellers

Most Viewed





Strength of

connection between

recommended

products and the

referenced product

Specify the affinity between the recommended

products and the source product.

This helps you target your recommendations based

on how often people act on the source product and

the recommended product during the sameWeb

session. The strength is calculated according to the

number of times the recommended product has

been viewed, added to the cart, or purchased in the

same session as the source product.

If you want to make recommendations without

very much affinity data, selectWeak. If you prefer

to wait until there's a lot of data before the

algorithm starts to make recommendations, select

Strong.

Site Affinity




Site Catalyst Report

Suite

Specify the SiteCatalyst report suite used to track

the data used with this recommendation.

Top Sellers

Most Viewed



Site Affinity


SiteCatalyst Metric Use any metric available on the product report in

SiteCatalyst to drive your algorithm. You can

choose algorithms that rank your products based

on any metric, such as “add to carts,” revenue,

units sold, etc.


Attribute Weighing Use attribute weighting to ”nudge” the algorithm.

Marketers can now influence the algorithm based

on important description or metadata about the

content catalog. Apply a higher weighting to these

on-sale items so they show more often in the

recommendation. Non-sale items are not

completely excluded, but they display less often.

Multiple weightings can be applied to the same

algorithm, and the weightings can be tested on

split traffic in the recommendation.




Top Sellers

Most Viewed


Include Only When Show this recommendation only if one or more

selected variables exactly matches the specified

criteria. For example, you can set this option to

specify that the recommendation shows only for a

specific entityID.

Site Affinity






Top Sellers

Most Viewed



2.15 Creating a Custom Algorithm

You can create one or more custom algorithms and provide a list of the recommended items to show for a specific key.

Note: Creating a custom algorithm requires the use of two APIs. This process should only be performed by advanced users.

To create a custom algorithm, you must use two APIs.

l Name the custom algorithm

l Upload the data displayed by the custom algorithm

These APIs must be used sequentially in the order shown above. However, they can be done at different times. Also, after you have

created the algorithm name, you can upload data whenever needed (for example, on a schedule to keep the information up to date)

without repeating the Algorithm Name API call.

You can also delete a custom algorithm, as explained in Deleting a Custom Algorithm.

Naming a Custom Algorithm with the Algorithm Name API

Use the Algorithm Name API to create a name for a custom algorithm.

The syntax for the Algorithm Name API is:

https://recommendations.omniture.com/rest?action=algorithm.upload&client=clientCode&clientToken=51dafdf4-f825-4581-a7c0-8ce9db31bd31&algorithmName=sampleCustomAlgorithm

Where:

recommendations.omniture.com is the domain for the current recommendations environment you are using.

clientCode is your client code in Recommendations..

51dafdf4-f825-4581-a7c0-8ce9db31bd31 is the client token that is displayed on the settings page in Recommendations. The

token shown is a sample; yours will be different.

sampleCustomAlgorithm is the name of the algorithm as it will be displayed in the algorithm selection dropdown when you create or

edit a recommendation. You can name it whatever you like, but it has a 250 character limit. This name is used when you upload the

recommendation data, as shown in Uploading Custom Algorithm Data with the Upload API.

After you use this API, the new name appears immediately as an algorithm type in Recommendations.

Uploading Custom Algorithm Data with the Upload API

After you create a custom algorithm name (as shown in Naming a Custom Algorithm with the Algorithm Name API), you can upload a list

of the recommended items to display for a specific key item when you use that custom algorithm.

Note: If you try to upload recommendations data to a custom algorithm that has not yet been created, you receive an error stating

that the algorithm does not exist.



The syntax for the Upload API is:

https://recommendations.omniture.com/rest?action=entity.recommendations.upload&client=clientCode&clientToken=51dafdf4-f825-4581-a7c0-8ce9db31bd31&algorithmName=sampleCustomAlgorithm&recommendations=<recommendations><recommendation><key>1</key><entityId>2</entityId><entityId>3</entityId><entityId>4</entityId></recommendation></recommendations>

Where:





sampleCustomAlgorithm is the name of the algorithm created in Naming a Custom Algorithm with the Algorithm Name API.

<recommendations>...</recommendations> is the XML representation of the recommendations that will display. A

<recommendation>must be included for each key. The <entityId> values are the recommended items for the specified key. In proper

XML syntax, the recommendation might look similar to the following:

<recommendations>

<recommendation>

<key>1</key>

<entityId>4</entityId>



</recommendation>

<recommendation>

<key>2</key>




</recommendation>

...

</recommendations>



Deleting a Custom Algorithm

To delete a custom algorithm name, use the following API call:

https://recommendations.omniture.com/rest?action=algorithm.delete&client=clientCode&clientToken=51dafdf4-f825-

4581-a7c0-8ce9db31bd31&algorithmName=sampleCustomAlgorithm

Where:





sampleCustomAlgorithm is the name of the algorithm created in Naming a Custom Algorithm with the Algorithm Name API.

Note: If you try to delete a custom algorithm that has not yet been created, you receive an error stating that the algorithm does not

exist.

Chapter 2

2.16 Managing Recommendations with OmnitureTest&Target

Note: This section is useful only for Recommendations users who also use Omniture Test&Target.

You can use Omniture Test&Target to manage Recommendations. When you click to edit a recommendation within Test&Target,

Recommendations opens so you can edit the recommendation.

If you want to add Test&Target features to your Recommendation—such as targeting, segmenting, or additional success metrics—a new

T&T campaign should be used and the Recommendation offer should be applied to that campaign.

After you create a recommendation in Recommendations, it appears in your Test&Target Campaign list.

1. Log in to Test&Target

Your Campaign list opens. Recommendations campaigns are prepended by the word Recommendations (for example,

Recommendations: Jerseys).



2. Locate the Recommendations campaign you want to manage.

You can hold the mouse pointer over a campaign name for information about the start and end date and approval status.

3. Click the campaign to open it in Recommendations.

Chapter 3: Managing Templates


Chapter 3Chapter 3:

Managing Templates

Templates determine how your recommendations look on a Web page or flashbox. You can create customized templates to provide the

appearance you desire.


l Using the Template Manager

l Creating a New Template

l Creating a Flash Template

l Editing a Template

l Copying a Template

l Deleting a Template

l Using a Download-Only Template

3.1 Creating a New Template

You can create customized templates that provide the look you want for your recommendations.

1. From the recommendations menu, select Templates.

The list of current templates opens. This list includes the template name and information about how often each template is used

in active and inactive recommendations.

2. Select HTML Template, then click Create New Template ( ).

The Edit Template screen opens.



3. Edit the code for the template.

Recommendations templates use the open-source Velocity template language. Information about Velocity can be found at

http://velocity.apache.org. For more information, see Customizing a Template.

You can start with one of three size options by clicking the size you want:

3 Across: Displays three recommendations in a one-row table with three columns.

3 Down: Displays three recommendations in a one-column table with three rows.

2x2: Displays four recommendations in two rows, each with two columns.

You are not limited to these options. For more information about creating or editing a template, see Customizing a Template.

4. (Optional) Select the template usage statistics you'd like to view.

You can see how many recommendations are using the template. Select All, Active, or Inactive to see the recommendations

that use the template. Links to the recommendations that use the template appear to the right of the template usage statistics.

5. Click Save.

For information about the variables you can use for displaying data, see Understanding Display Attributes.

http://velocity.apache.org/



Creating a Flash Template

You can create customized templates that provide the look you want for your recommendations.

1. From the recommendations menu, select Templates.

The list of current templates opens. This list includes the template name and information about how often each template is used

in active and inactive recommendations.

2. Select Flash Template, then click Create New Template ( ).

3. Upload the Flash file you want to use, or type the absolute URL to the Flash file, then click Upload.

The Flash file must be hosted or trafficked outside of Recommendations, following your standard methods. When you upload

the file, Recommendations scans it for syntax and variables, which helps a marketer create the template variables. The file is not

hosted by Recommendations.

4. Replace the displayed Flash variables with Recommendations $entity.variable variables.

5. Click Save.

For information about the variables you can use for displaying data, see Understanding Display Attributes.

3.2 Editing a Template

You can edit a template if you want to modify the look of your recommendations.

1. From the Recommendations menu, select Templates.

2. In the Template Name list, place the mouse pointer over the template you want to edit.

The Edit ( ) Delete ( ), and Copy ( )icons appear.

3. Click Edit ( ).

4. Edit the code for the template.


http://velocity.apache.org. For more information, see Customizing a Template.

You can start with one of three size options by clicking the size you want:

3 Across: Displays three recommendations in a one-row table with three columns.




3 Down: Displays three recommendations in a one-column table with three rows.

2x2: Displays four recommendations in two rows, each with two columns.

You are not limited to these options. For more information about creating or editing a template, see Customizing a Template.

5. (Optional) Select the template usage statistics you'd like to view.

You can see how many recommendations are using the template. Select All, Active, or Inactive to see the recommendations

that use the template. Links to the recommendations that use the template appear to the right of the template usage statistics.

6. Click Save.

3.3 Customizing a Template


http://velocity.apache.org.

All Velocity logic, syntax, and so on can be used for a Recommendation template. This means that you can create for loops, if

statements, and other code using Velocity rather than JavaScript.

Any variable sent to recommendation in the productPage mbox or the CSV upload can be displayed in a template. These values are

referenced with the following syntax:

$entityN.variable

Note that, because multiple values can be stored for categoryId, categoryId cannot be displayed in a template. If you want to display the

category, pass it in as the categoryId for algorithm manipulation, then duplicate it in a custom attribute as explained in Editing the Entity

Upload Template.

For example, if you want a template that displays something similar to this:

you can use the following code:

<table style="border:1px solid #CCCCCC;">

<tr>

<td colspan="3" style="font-size: 130%; border-bottom:1px solid #CCCCCC;"> You May AlsoLike... </td>

</tr>

<tr>

<td style="border-right:1px solid #CCCCCC;">




<div class="search_content_inner" style="border-bottom:0px;">

<div class="search_title"><a href="$entity1.pageUrl" style="color: rgb(112, 161, 0); font-weight: bold;">$entity1.id</a></div>

By $entity1.message <a href="?x14=brand;q14=$entity1.message">(More)</a><br/>

sku: $entity1.prodId<br/> Price: $$entity1.value

<br/><br/>

</div>

</td>

<td style="border-right:1px solid #CCCCCC; padding-left:10px;">




sku: $entity2.prodId<br/>

Price: $$entity2.value

<br/><br/>

</div>

</td>

<td style="padding-left:10px;">




sku: $entity3.prodId<br/> Price: $$entity3.value

<br/><br/>

</div>

</td>

</tr>

</table>

3.4 Copying a Template

You can copy a template if you want to base a new template on an existing template.


2. In the Template Name list, place the mouse pointer over the template you want to copy.

The Edit ( ) Delete ( ), and Copy ( ) icons appear.



3. Click Copy ( ).

A copy of the template appears in the template list.

4. Place the mouse pointer over the template and click Edit ( ).

5. Give the copy of the template a unique name.

6. Make changes to the template as needed.

7. Click Save.

3.5 Deleting a Template

You can delete a template you no longer need.


2. In the Template Name list, place the mouse pointer over the template you want to delete.

The Edit ( ) Delete ( ), and Copy ( )icons appear.

3. Click Delete ( ).

4. Click OK to confirm that you want to delete the template.

The template is removed from the template list.

3.6 Using a Download-Only Template

Use a Download-Only template if you do not have display mboxes on your site and you want to run a recommendation and download

the results or export them using the Recommendations API. This results in a downloaded CSV file that list the recommendations with one

row per key.

For example, if you have a People who bought this bought that recommendation, the key is the product ID that you want to show

recommendations for (typically passed to Recommendations through the display mbox) and the products that were purchased with that

product are recommended. If you are using the Top seller in category algorithm, the key is the category and the recommendations are

the top sellers in that category.

3.7 Using the Template Manager

The Template Manager lists your templates so you can see how many active and inactive recommendations use each template, and so

you can edit, delete, or copy a template. You can also create a new template.

1. Click Templates.

The Template Manager opens.



The Active Recommendations and Inactive Recommendations columns show how many recommendations use each template.

2. Mouse over a template name to access a toolbar that enables you to edit, delete, or copy the template.

3. Click New Template ( ) or Create New Template to create a new template.

Chapter 4: Managing Recommendations Settings


Chapter 4Chapter 4:

Managing Recommendations Settings

The Settings option on the recommendations menu provides access to Recommendations settings.


l Creating Global Exclusions

l Uploading Entities to Recommendations

l Downloading the Mbox.js Library File

4.1 Creating Global Exclusions

Exclusions let you specify that a product or item never be included in your recommendations if they meet specific criteria.

1. From the recommendations menu, select Settings.

2. In the Global Exclusions section, click Add exclusion rule.

3. Specify an entity parameter.

The possible parameters are:

Parameter Definition

category The product category used to organize products on your site. A product can have multiple cat-

egories, but only one category can be entered in this field.

entityid The number used to identify the product.

name The product name that is displayed on the Web site when the product is recommended.

thumbnailUrl The absolute URL that points to the thumbnail image of the product that is displayed in the rec-

ommendation.

pageUrl The URL of the product page displayed in the recommendation.

message A message about the product that is displayed in the recommendation. The message is typically more

verbose than the product name.

value The price or value of the product.

margin The profit margin or other value of the item.

inventory The current amount of the product in inventory.

Custom attributes You can include up to ten custom attributes for your products. You can specify any unused attribute

name for each custom attribute. For example, you might create a custom attribute called brand that




specifies the brand name of the product.

4. Specify the string that must be matched for the exclusion to be used.

5. Click Save.

4.2 Uploading Entities to Recommendations

You can create a .CSV file that contains display information for your products, then bulk upload it into Recommendations.

You can use this method to send display information if you don't have mboxes on your page, or you want to supplement your display

information with items that are not available on your site. For example, you might want to send Recommendations inventory information

that might not be published on your site.

Any data uploaded using the upload template file overwrites that value in our database, so if you send price information in JavaScript

and then send different price values in the file, the values in the file override the information sent with JavaScript.

Downloading the Entity Upload Template

Omniture provides a template file that you should download if you want to upload entity information. Using the template ensures that

your entity information is properly uploaded.

1. From the recommendations menu, click Settings.

The Settings screen opens.

2. In the Entity Upload Section, click the link to download the template file.

3. Save the file.

Editing the Entity Upload Template

After you have downloaded the entity upload template, you can edit it.

1. Open the upload template file in Excel or a text editor.

2. Make the desired changes.

For example, you could fill out this file with productIds and inventory information, and leave the other fields blank.

Entity upload data uses the form entity.attribute. For example, if you sell athletic shoes, the entity is the Air Jordan Show

and an attribute could be the $120 price for that shoe.

The possible parameters are:


entity.id The number used to identify the product.

entity.name The product name that is displayed on the Web site when the product is recommended.

entity.categoryId The product category used to organize products on your site. A product can have multiple cat-

egories, but only one category can be entered in this field.

entity.message A message about the product that is displayed in the recommendation. The message is typically more

verbose than the product name.




entity.thumbnailURL The absolute URL that points to the thumbnail image of the product that is displayed in the rec-

ommendation.

entity.value The price or value of the product.

entity.pageURL The URL of the product page displayed in the recommendation.

entity.inventory The current amount of the product in inventory.

entity.margin The profit margin or other value of the item.

Custom attributes You can include up to ten custom attributes for your products. You can specify any unused attribute

name for each custom attribute. For example, you might create a custom attribute called enti-

ty.brand that specifies the brand name of the product.

3. Save the file.

Uploading the Entity Information to Recommendations

After you have downloaded and edited the template and saved your upload file, you can upload the file.

Any data uploaded using the upload template file overwrites that value in our database, so if you send price information in JavaScript

and then send different price values in the file, the values in the file override the info sent with JavaScript.

1. From the recommendations menu, click Settings.


2. In the Entity Upload Section, browse to your save upload file.

3. Click Upload.

It takes a moment for the upload to be processed. When the upload is complete, a message tells you how many data lines were

processed and that the upload was successful.

4.3 Downloading the Mbox.js Library File

Save the mbox.js library file on all hosts (domains) serving mboxes. You need only one copy on each host. All pages with mboxes must

reference this file.

To download mbox.js

1. From the Recommendations menu, click Settings.


2. In the Entity Upload Section, click the link to download mbox.js.

3. Save the file.



To Verify the Mbox.js download

After you download the mbox.js file, you should validate the download.

1. Open a Web browser and browse to your Web domain.

2. Browse to the URL where you saved your mbox.js file.

For example, if the mbox.js file is saved in a directory called /js, browse to http://www.yourserver.com/js/mbox.js.

You have successfully downloaded mbox.js if any of the following occur:

l The mbox.js appears in your browser as a text file filled with JavaScript functions.

l Your browser attempts to download the file, prompting you for where to save it.

l Your browser warns you about JavaScript.

http://www.yourserver.com/js/mbox.js

Chapter 5: Managing Mboxes


Chapter 5Chapter 5:

Managing Mboxes

An mbox is a "marketing box," a portion of your Web page that can be configured to show different content in different situations. An

mbox can also log the behavior of visitors to your site. Mboxes are defined in the code for each Web page.

Mboxes are essential to campaigns and tests. Any mbox may do one, both or none of the following as you choose:

l Display and swap content for visitors.

l Log visitor behavior in real-time.

The following image highlights an mbox that recommends two products.




l Using an Mbox on Your Web Site

l Troubleshooting Mboxes

l Understanding Display Attributes

l Sending Sales Data Values



5.1 Using an Mbox on Your Web Site

To create an mbox, you must perform three steps:

1. Preparing for the Mbox

2. Creating the mbox.js Reference

3. Creating the Mbox

Preparing for the Mbox

Decide the following based on the strategy and design of your recommendations:

l The Web site locations of the mboxes needed to display recommendations

l The boundaries of the default content for each mbox

The default content of display mboxes should be a size and shape that supports the offers (creative) designed for the

recommendations.

l The mbox names, which Operators will recognize when setting up recommendations

Mbox names are case sensitive. Omniture Recommendations recognizes Mymbox and myMbox as two different mboxes.

Creating the mbox.js Reference

Any Web page that includes an mbox must reference the mbox.js file as it is saved on the host. This allows the page to contact the

Omniture Recommendations server.

1. Create the reference code.

For example, if the mbox.js file is saved in a directory called /js, the reference must be:


2. Add this reference to the head section of all Web pages that will have an mbox.

<head>


</head>

Tip: Add the mbox.js reference to an include or header file that exists in the head all of your Web pages.

Keep the following points in mind when adding the mbox.js reference to a Web page:

l Add the reference only once to the Web page, regardless of the number of mboxes on the page.

l Use a relative or absolute path depending on where you saved your mbox.js and as best suits your file structure.

An absolute path is preferred.

l Best practice is to place the reference in the head section, but you can place it anywhere before the first mbox on your page.



Creating the Mbox

1. Ensure the Web page contains a reference to mbox.js.

It is recommended you insert this reference in the file's <head> section.

2. In the body of the HTML page where you wish to insert an mbox, define the beginning and end of the default content with the

div tags as shown below.

If the mbox will only track and not display, insert no content between the default div tags.

3. Immediately follow the default content close </div> tag with themboxCreate function.

Give the mbox the unique name Operators will recognize when creating a campaign or test. In the example below, the mbox is

named myMbox.

Before After

<head>

</head>

<head>

<script src="http://www.mycompany.com/myfolder/mbox.js"type="text/javascript"></script>

</head>

<body>

My existing page.

Part that I'd like to overlayduring a campaign or test.

</body>

<body>

My existing page.

<div class="mboxDefault">Part that I'd like to overlay during acampaign or test.

</div>


mboxCreate('sidebar_recommendations','entity.categoryId=EN:Guide:1';

</script>

</body>

ThemboxCreate function contains the following parts in the example shown above:

l Mbox name: 'sidebar_recommendations'

l Display variable: 'entity.categoryId=EN:Guide:1'

This option specifies the information to display if a category algorithm (such as Top Sellers or Most Viewed) is used for the

recommendation.

If you prefer to use a product-based algorithm, replace the display variable with a product ID, such as:

'entity,id=12345'

This specifies the product ID for the item being recommended. This ID must be the same as the product ID sent to SiteCatalyst

(the s.products variable) if you are gathering data from SiteCatalyst.

Placing an Mbox Around a Table

Wrap the default mbox around an entire table. Do not wrap rows.



Right Wrong


<table>

<tr>

<td>peaches</td>

<td>cherries</td>

</tr>

<tr>

<td>walnuts</td>

<td>almonds</td>

</tr>

</table>

</div>

<script type="text/javascript" >mboxCreate('myMbox');

<table>


<tr>

<td>peaches</td>

<td>cherries</td>

</tr>

<tr>

<td>walnuts</td>

<td>almonds</td>

</tr>

</div>

</table>

Placing an Mbox Around a Table Cell

Insert the default mbox within the cell, not outside the cell.

Right Wrong

<table>

<tr>

<td>


Peaches

</div>

<script type="text/javascript" >mboxCreate('myMbox');

</td>

<td>cherries</td>

</tr>

<tr>

<td>walnuts</td>

<td>almonds</td>

</tr>

</table>

<table>

<tr>


<td> peaches > </td>

</div>

<td>cherries</td>

</tr>

<tr>

<td>walnuts</td>

<td>almonds</td>

</tr>

</table>



Creating Multiple Mboxes on a Page

Since each mbox adds some load time to the page, try to limit the number of mboxes on each page to ten.

Follow the instructions for inserting a single mbox, as explained in Creating the Mbox. Repeat steps 2 and 3 for each mbox. Only

reference thembox.js file once.

Tip:Multiple test elements on a page can be combined into a single larger-sized mbox.

Creating a Whole Page as an Mbox

Use an mbox to replace all of the content between the <body></body> tags.

<html>

<body>

<div class=”mboxDefault”>

<…>

...

</…>

</div>

<script type="text/javascript" > mboxCreate(‘wholePageMbox’);

</script>

</body>

</html>

Tip: Do not place the mbox outside the body tags. Mboxes depend on the <body> onLoad function to execute, and mbox recursion

problems can occur when a <body> is used in an offer.

Dynamic Mboxes

Many Rich Internet Applications (RIAs) manipulate HTML after the page has already loaded by using technologies like DHTML and AJAX.

For example, after clicking a button, your Web page might display a new section of content. Omniture supports this scenario, allowing

you to define dynamic Mboxes through itsmboxDefine() and mboxUpdate() functions.

For example, if you want to serve content when an HTML node called "dynamicElement" appears on the page:

<div id="dynamicElement"></div>

Then you could trigger the following script on a JavaScript event:

<script type="text/javascript" >mboxDefine('dynamicElement’,'mbox_dynamic’,

'parameter1=value1’);mboxUpdate('mbox_dynamic’, 'parameter1=value1’);



</script>

Of note:

l mboxDefine() defines an HTML element as a container for content to be served.

This function takes in the unique element id, the mbox name, and any number of parameters. The parameters can be used for

targeting by the active campaign, even if not passed in again with a latermboxUpdate() call.

mboxDefine() does not actually serve content so it should be followed with mboxUpdate().

l mboxUpdate() retrieves the content from Omniture.

This function may be called multiple times if you want to further change the content. LikemboxCreate, it takes in the mbox

name and any number of parameters.

l The usual mboxCreate() function only works for HTML elements that exist on the page on the initial load.

l mboxUpdate() can also be used for mboxes created with mboxCreate() rather than mboxDefine().

This allows the page to update content dynamically after the initial page load.

5.2 Troubleshooting Mboxes

This section contains information about debugging mboxes:

l Troubleshooting the Debug Window

l Mbox Troubleshooting Guide

l Troubleshooting Resources

Troubleshooting the Debug Window

If the Debug window does not appear as expected, use the following information to solve the problem.

If the Debug window does not appear:

l Confirm thembox.js reference is correct on all Web pages with the mboxes.

l Confirm you have downloaded thembox.js into a folder with public permissions.

If the Debug window appears but enabled = false:

l Delete your cookies and clear cache. Close and reopen a browser and reload the page.

l If enabled=false persists, seek and remove JavaScript errors. Some common errors include:

l Improper termination of quotes in mbox arguments

l Spelling mistakes in your mbox functions

l Script tags that are not invoked or that are not closed

l If enabled=false persists, contact your Omniture representative.



If the mboxes are not listed in the mboxDebug popup window, or if mboxes appear blank on the page,

review your page code for the following:

l Confirm thembox.js reference is correct on all Web pages with the mboxes.

l Confirm that any tag opened before the mbox script is closed after the mbox script.

l Remove JavaScript errors.

l Scrub layout to support DOM rendering by all browser types.

Mboxes insert new nodes into the DOM tree as the browser creates it. Each brand of browser has its own implementation of the

W3C DOM specification, so mboxes can affect page rendering differently based on the browser type. Specify absolute sizes of

table cells and images to help the browser more accurately display a page's HTML layout.

Mbox Troubleshooting Guide

Troubleshooting Resources

The Mozilla Firefox browser includes a JavaScript console that quickly finds and lists the JavaScript errors in your page.

The Firebug extension for Firefox, available here: (https://addons.mozilla.org/en-US/firefox/addon/1843) provides a full-

featured JavaScript debugging tool, and also shows generated source with mbox code.



5.3 Understanding Display Attributes

Information is passed to the mbox by using display attributes. This section describes the available variables.

Note: The names of attributes have changed from earlier versions of the display attributes. Although the old attributes are still

supported, it is recommended that you use the new format.

Entity Attribute Description

entity.id This required parameter identifies the product. This ID must be the same across all Omniture

products that are used, including SiteCatalyst, for the various products to recognize the item

and share data about it.

Example:

'entity.id=67833'

entity.name Provides a name for the item.

Example:

'entity.name=Giants vs Rockies 5/12'

entity.pageURL Defines the relative URL of the page where the item can be purchased.

Example:

'entity.pageURL=baseball/giants-tix/giantsvrockies5.12.2000-67833'

entity.thumbnailURL Defines the relative URL to the thumbnail image that displays with the item.

Example:

'entity.thumbnailURL=baseball/giants-tix/giants-136px.gif'

entity.message Defines additional information to display with the product in the template, such as "on sale"

or "clearance."

Example:

'entity.message=Family special'

entity.inventory Displays the inventory level of the item.

Example:


entity.value Defines the price of the item.

Example:

'entity.value=15.99'

entity.<custom> Define up to ten custom variables that provide additional information about the item. For

example, a ticket vendor might create attributes for the venue where an event will take place

or for a secondary performer, such as a visiting team in a sporting event or an opening act in

a concert.

Examples:



Entity Attribute Description

'entity.venue=AT&T Park'

'entity.secondary=Rockies'

Note: If you want to add information after the variable value, you can do so using formal notation. For example:${entity1.thumbnailUrl}.gif

For example, the mbox code might look like the following:

<div class="mboxDefault"></div><script language="JavaScript1.2">

mboxCreate('productPage',

'entity.id=67833',

'entity.name=Giants vs Rockies 5/12',

'entity.pageURL=http://www.tixplace.com/baseball/giants-tix/giantsvrockies5.12.2000-67833',

'entity.venue=AT&T Park',

'entity.secondary=Rockies',

'entity.thumbnailURL=http://www.tixplace.com/baseball/giants-tix/giants-136px.gif',

'entity.message=Family special',

'entity.value=15.99',


);

</script>

If the mbox is on a product page, you can include both the product ID and category ID. The selected algorithm determines which

displays. The product ID is used for affinity algorithms and the category ID is used for category algorithms.

5.4 Sending Sales Data Values

Sales data can be sent to Omniture Test&Target from any mbox, but the parameters must follow the strict syntax below. The parameters

orderId and orderTotal are required. The productPurchasedId attribute must match the entity.id display variable.

<script type=”text/javascript">

mboxCreate('orderConfirmPage',

'productPurchasedId=LIST OF PRODUCT IDs FROM ORDER PAGE',

'orderId=ORDER ID FROM ORDER PAGE',

'orderTotal=ORDER TOTAL FROM ORDER PAGE');

</script>



Note: You must pass the orderId parameter value as it allows Omniture Test&Target to remove double calls (duplicate orders). The

parameter names are also case-sensitive and must be followed as shown above.

Chapter 6: Using the Recommendations Download API


Chapter 6Chapter 6:

Using the Recommendations Download API

Use the Recommendations download API to download your recommendations in a .CSV file that can be viewed in a spreadsheet or text

editor. The .CSV file lists all recommendations for each product key.

Every time you download the results, all of the data is refreshed, not just the data that changed between when you last ran the algorithm

and when you downloaded the results.

The algorithm server updates the recommendations every two to six hours. Changes are reflected immediately in the results of the

download API.

This API is always available except during regularly scheduled maintenance windows, which occur on Thursday nights at 8 PM Pacific

Time or later.

API Structure

The download API uses a simple structure in a REST call. For example:

http://recommendations.omniture.com/rest?action=downloadRecommendations&id=43&clientKey=24be79b2-d631-4207-a435-c6d5dd11059a

Where:

Id is the recommendation ID visible in the app. Find the ID by looking at the URL on the recommendation's Edit page. Use the id=XXX

value, not the groupId value.

clientKey is the API token that can be viewed and changed on the Settings page of the Recommendations application.

If you provide an invalid client key or recommendation ID, the error "Client key or recommendation id invalid" is returned.

Chapter 7: Deleting an Item From Your Catalog


Chapter: 7Chapter 7:

Deleting an Item From Your Catalog

You can use the Catalog Item Delete API to remove a single item from your catalog. This API deletes all information about an individual

entity. Once the Recommendations cache is updated after a few hours, the entity no longer shows in any recommendations. These

entities will be eligible to be “relearned” through a productPage mbox request or a CSV product upload.

Note: There is no undo for this API.

The syntax for the Catalog Item Delete API is:

https://recommendations.omniture.com/rest?action=entity.delete&client=clientCode&clientToken=76bde9de-74f7-434b-ad1a-6d2d4c1b42d9&entityIds=Entity_ID

Where:



76bde9de-74f7-434b-ad1a-6d2d4c1b42d9 is the client token that is displayed on the settings page in Recommendations. The


Entity_ID is the ID of the item you want to delete. You can delete multiple items by including multiple entityIds separated by comma.

Chapter 8: Deleting All Items From Your Catalog


Chapter 8Chapter 8:

Deleting All Items From Your Catalog

You can use the Catalog Delete API to remove all item from your catalog. This API deletes all information about an individual entity.

Once the Recommendations cache is updated after a few hours, the entity no longer shows in any recommendations. These entities will

be eligible to be “relearned” through a productPage mbox request or a CSV product upload.

Note: There is no undo for this API.

The syntax for the Catalog Delete API is:

https://recommendations.omniture.com/rest?action=entity.deleteAll&client=clientCode&clientToken=76bde9de-74f7-434b-ad1a-6d2d4c1b42d9

Where:



76bde9de-74f7-434b-ad1a-6d2d4c1b42d9 is the client token that is displayed on the settings page in Recommendations. The


Chapter 9: Integrating Recommendations with Email


Chapter 9Chapter 9:

Integrating Recommendations with Email

There are two ways to integrate email with Recommendations. The email service provider’s capabilities determine which method to use.

Note: It is suggested that you talk with your Omniture consultant before implementing either of these options.

Option 1: Using a "Rawbox" Email Template

This is the preferred option.

Set up a recommendation as usual in Recommendations, using a template that has the desired look and feel for the email. Instead of

choosing an mbox on your site to show the recommendations, select a “rawbox” that is in the email template in your ESP system. At

email build time, ESP makes a call to Recommendations for each rawbox in each email that is being generated. A rawbox call is very

similar to an adbox, but instead of returning an image, Recommendations returns raw HTML.

The ESP needs a way to take this HTML and include it in the email when it is sent. This approach allows us to track performance of

recommendations in emails, test them in the normal way with a recommendation, and continue tracking on the site.

Sample rawbox URL:

http://CLIENT_CODE.tt.omtrdc.net/m2/CLIENT_CODE/ubox/raw?mbox=MBOX_NAME&mboxContentType=text/html&mboxPC=UNIQUE_ID_PER_EMAIL&mboxSession=UNIQUE_ID_PER_EMAIL,&mboxXDomain=disabled&mboxDefault=DEFAULT_URL

Change the capitalized values per client/recommendation combination.

Option 2: Using the Download-Only Template

Set up a recommendation as usual in Recommendations, but choose download only in the presentation section instead of a template

and mbox combination. Then in the ESP, tell the ESP what recommendation ID you created. The ESP accesses the recommendation

data via API. This data shows which items should be recommended for a particular category or key item, such as the item abandoned in

the cart. The ESP then stores this data, connects it with their own look and feel, displays information about each item, and then delivers

that in the emails. With this option, Recommendations cannot directly track the performance of a recommendation or split traffic across

multiple algorithm/template combinations.

For more information about the download API, see Using the Recommendations Download API.

recommendations user guide

Documents