Skip to end of metadata
Go to start of metadata

The reality is that no two businesses are alike. Even two retailers selling women’s apparel will have different requirements for how they want to use and report on their product catalog. And different media companies, technology providers, and financial services firms all have vastly different catalogs. To accommodate each unique catalog of items as well as your own company's internal preferences, the Evergage Catalog includes the option to configure custom dimensions.


The Evergage Catalog requires JavaScript API integration to capture information about product and/or article interactions on your site. Contact your Customer Success Manager (CSM) or Evergage Support at support@evergage.com to learn more about the options for the setup of the Evergage Catalog.

This Article Explains

This article details how to setup the Evergage Catalog to capture information about product and/or article interactions on your site including how to configure Custom Dimensions.

Sections in this Article

Catalog Setup

The Evergage Catalog includes three catalog item types (Article, Blog Post, Product) which can have categories, as well as up to 20 custom dimensions. Depending on your business, you may have any combination of item types. For example, an e-commerce site might have blog posts, articles, and products, but a demand generation site may have only blog posts and articles. Dimensions describe a particular aspect about a catalog item, and add an additional layer of trackable organization to your catalog. For example, a product could have brand, style, gender, and color dimensions, and an article could have author and keywords dimensions. Note, dimensions were formerly known as tags.

Adjust Catalog Settings

You can make changes to catalog settings including whether you will filter outliers, the type of currency used on your site, and your primary locale. Additionally, you can Configure Static Relationships on this page which are used when creating Recommendations recipe Variations.

  1. Log into the Evergage Platform with Administrator permissions
  2. Select Catalog > Catalog Setup
  3. Select Filter Outliers if you want to remove outliers (e.g. bulk orders, or significantly large orders)from reporting and statistics. For more information on outliers, please refer to the Glossary and Campaign Statistics Overview
    1. Maximum - anything above this number will not be counted in reporting and statistics
    2. Minimum - anything below this number will not be counted in reporting and statistics
  4. Set your Primary Locale which is used to interpret the SmartSearch queries and to format currency
  5. Set your Primary Currency as the currency you want to use for formatting, statistics tracking, and attribution analysis. If your site processes more than one currency, Evergage will use the current exchange rate to convert these values for reports and analytics
  6. Select Enable Localization of Catalog Metadata Based on Page Locale if your site supports multiple locales. Evergage will track and store the metadata separately for each language. Also if recommendations are shown to a site visitor, Evergage will format the language and currency using the visitor's locale. For example if a visitor is located in Italy and this option is selected, the recommendations will show in Italian and currency will show in Euros.
  7. Set the Millisecond Timestamp Slop for Upserted Purchases if you are upserting offline or older orders to Evergage and you are concerned about duplicates. Evergage will remove duplicate orders that have timestamps within the millisecond timestamp slop 
  8. Add Static Relationship Names to use Variations in RecommendationsRecipes
  9. Click SAVE to save changes


Add Item Types to the Catalog

Before you add item types to the Evergage catalog, you need to decide what type of data you want to track. For example, if your site is for e-commerce, you need to add products and categories to your catalog. If you sell more than one brand or item line, you should include brands if you want to do things like track the product brands which bring in the most revenue or target users with messages based on their favorite brands or those most popular among your customers. If your site includes content, you should include articles as an item type. This will make it possible to track which articles are most popular, recommend popular related articles, or cross-promote between products and content. You can also track article authors and keywords. Finally, if your site contains a blog, you can track blog articles the same as you would track news or content articles, again with associated tags and authors.

  1. Select an Item Type you want to include in your catalog. 
    1. Selected Item Types are indicated by 
    2. Default Item Types include:
      1. Article - use this item type for articles that are not blog posts
      2. Blog Post - use this item type for blog posts
      3. Product - this item type is for individual products
      4. Promotion - use this to indicate hero images used for a particular sale or promotion
      5. Category - indicate a category of items like "dresses" or "thought leadership"
  2. Refer to Edit Item Types below for details on how to configure and enable item types


Edit Item Types

  1. Select the item type you want to edit
  2. You can change the label to be something more relevant to you
  3. Add a Description if needed
  4. Enter a Base URL if your catalog items have relative URLs
  5. Add a Custom Attribute if you have additional attributes to use in item templates or track in addition those available on the Item Edit page for the item type 
  6. Add a Dimension to the Item Type

    NOTE

    You must configure the dimension on the left rail for it to be available to add under Edit Item Type


Add Custom Attributes

You can define a Custom Attribute if you have additional attributes to use in item templates or track in addition those available on the Item Edit page for the item type. For example, if your catalog contains product, you may want to add attributes related to certain features about your products you want to showcase in the template like the image alternate text, price, or date added. And if your site contains content, you may want to add attributes to show things like author, subject, or keyword.

  1. Click NEW ATTRIBUTE
  2. Add an alphanumeric Attribute Name
  3. Add the Label as the text you want to appear in Evergage
  4. Select the Type
    1. String - select this for text attributes - alphanumeric
    2. Integer - whole numbers - counts
    3. Decimal - numbers that have decimals 
  5. Click  to save changes
  6. Click  to cancel


Add Dimensions

Custom Dimensions provide more flexibility and control around how you organize, execute, and analyze your company's product or content catalogs. With Custom Dimensions you can:

  • Rename default dimension labels (e.g. Gender, Style, Class, etc.)
  • Enable or disable certain dimensions
  • Create new product or content dimensions
  • Associate with one or more item types

Once dimensions are configured, you can associate them with item types to offer those dimensions throughout Evergage both for display and reporting purposes. You can also use them in Recommendations for exclusions, boosters, and variations. Any tags you previously configured have been converted to dimensions, but you can change the label for any of those tags to better suit your business needs.

  1. Click Add Dimension on the left rail
  2. Enter a unique Name to be used as the primary key for the dimension
  3. Enter a Label to be used as the display name in the Dimensions section
  4. Enter a Description of the dimension to detail how the dimension is intended to be used in the catalog
  5. Select the Cardinality
    1. One Per Item - select this option if there can be only one option for this dimension per item. Brand is an example of a dimension that would be One Per Item because an item can have only one brand
    2. Many Per Item - select this less common option if this dimension can have many different values. Keyword is an example of a dimension that would be Many Per Item because items like products or articles could have multiple keywords
    3. One Per SKU - select this option if this dimension has different values, but only one that would apply to a particular item SKU. For example, a sneaker could have multiple colors, but each SKU of that sneaker would have only one color 
  6. Associated Item Types can be added by editing the item type and clicking Add Dimension
  7. You can define Custom Attributes if you have additional attributes to use in item templates or track in addition those available on the Item Edit page for the item type
  8. Click SAVE to save the dimension


Edit Dimensions

  1. Select the dimension you want to edit
  2. Make changes to the Label, Description, and Cardinality as needed
  3. Click NEW ATTRIBUTE to add Custom Attributes if you have additional attributes to use in item templates or track in addition those available on the Item Edit page for the item type
  4. Click SAVE to save changes

API Integration

Custom JavaScript for the Evergage Catalog should be managed under your dataset's Site-Wide JavaScript configuration. This code, as included in the Evergage JavaScript Beacon, will execute function calls to the Catalog JavaScript API to capture item data and actions in your site.

  1. Log into the Evergage Platform as an Administrator
  2. In the Channels & Campaigns section, select Web > Site-Wide JavaScript
  3. Make the necessary changes
  4. Click SAVE

The following functions are available on the Evergage object instantiated by the JavaScript Beacon:

 

Function

Description

viewItem(item)

Declares this page to be an item page and sends information about the item

viewItemDetail(item)

Used to track detail item clicks such as viewing other product images or a specifications tab

viewCategory(category)

Declares this to be a category page

viewTag(tag)

Declares this to be one of the relevant dimension (formerly called "tags") pages where the dimension name can be any configured dimension

addToCart(lineItem)

Add an item into a cart.

purchase(order)

Complete an order and mark its status as purchased

review(item)

Declare that a user has reviewed an item

share(item)

Declare that a user has shared an item, such as a social share on facebook

comment(item)

A user comments on an item or posts a review

favorite(item)

A user declares interest in an item, potentially adding a product to a wish list or an article to a favorites menu

Required and Optional Item Fields 

Property

Required

Description

type

Yes

One of {p, a, b } - For Product (p), Article (a) and Blog (b)

_id

Yes

The unique identifier of this item such as a product id or SKU

alternateIdNoA unique identifier other than the _id which can be used to mark the item out of stock when _id is not known

name

Yes

Name of the product or title of the article

description

No

Overview text about the item

price

No

Current price of the item

priceDescription

No

Descriptive text for the price (e.g. "Sale Price")

listPrice

No

Alternative list price e.g. MSRP for comparison or to illustrate discount.

marginNoGross margin as a percentage of sale price. If a product sells for $10 and it cost the merchant $5 margin is 0.5

inventoryCount

No

A count of available units (or may be {0,1} indicating basic availability).

imageUrl

No

Fully qualified url for the image representing this item

url

No

Link to this item

currency

No

ISO code for the pricing currency of this item such as {USD, EUR, GBP}

categories

No

Categories this item belongs to

tags

No

Additional dimensions (formerly called "tags") about an item such as Brand for products or Author and Keywords for articles

createdauto-updated 
updatedauto-updated 
publishedNo

Date an item was published or became available - Item will not be promoted before this date

expirationNoDate an item should be expired - Item will not be promoted after this date
promotionStateNo

One of Prioritized or Excluded

ratingNoThe average rating score for reviews on this item
numRatingsNo

The count of reviews on this item

location.longlatNoThe location associated with this item, longitude first. For instance, Boston, MA is [-71.127197,42.3134791]
customNoUp to 10 custom string fields. For example, custom.alternateImage = "https://example.com/img2.png"

Required and Optional Category Fields

Property

Required

Description

type

Yes

Must be "c"

_id

Yes

A unique identifier for the category. If you wish to utilize hierarchical tracking, you should pass ids with the pipe (|) character used to append the id's together. E.g. "Outdoor|Furniture|Chairs"

name

No

A display name for the category

description

No

Overview text about the item

imageUrl

No

Fully qualified url for the image representing this item

url

No

Link to this item

Required and Optional Review Fields

Property

Required

Description

rating

Yes

Number between 0 and 100

title

No

Summary field

content

No

Review text

userDisplayName

No

Public name of user writing review

purchased

No

Boolean representing if the user has previously purchased this item 

Examples

Example: View Category
var catNodes = ajq('div.breadcrumb > a:not(:first), div#breadcrumb > a:not(:first)');
var egCategoryName = '';
for (var i = 0; i < catNodes.length; i++) {
    var node = $(catNodes[i]);
    if (i > 0) egCategoryName += '|';
    egCategoryName += node.text();
}

var category = {
    type: Evergage.ItemType.Category,
    _id: egCategoryName,
    url: $(catNodes[catNodes.length-1]).attr('href')
};

Evergage.viewCategory(category);

 

 

Example: View Item
var exampleItem = {
   type: Evergage.ItemType.Product,
   _id: $('#productId").text(),
   name: $("#productName").text(),
   description: $('#productDescription),
   price: parseFloat($("#productPrice").text().trim().substring(1)),
   imageUrl: "http://" + window.location.host + $('#productImage').attr('src'),
   url: window.location.href,
   currency: 'USD',
   categories: [category],
   tags: [{ type: Evergage.ItemType.Tag, tagType: "Brand", _id: $('#productBrand').text()}]
 };
Evergage.viewItem(exampleItem);

 

 

Example: Add To Cart
var exampleLineItem = {
   item: exampleItem,
   quantity: $("#prodQuantityId").val()
 };

Evergage.addToCart(lineItem); // Omit optional order object

 

 

Example: Purchase
var exampleLineItem2 = {
   item: exampleItem2,
   // Omitted quantity is assumed to mean one.
 };
var exampleOrder = {
  _id: $('#orderId").text()
};
exampleOrder.lineItems.push(exampleLineItem);
exampleOrder.lineItems.push(exampleLineItem2);
Evergage.purchase(exampleOrder);

 

 

Example: Review
var review = {"rating":"4","title":"Cool","content":"Very cool shirt","userDisplayName":"Greg"};
Evergage.review(item, review);