API Integration
Custom JavaScript for the Interaction Studio Catalog should be managed under your dataset's Site-Wide JavaScript configuration. This code, as included in the Interaction Studio JavaScript Beacon, will execute function calls to the Catalog JavaScript API to capture item data and actions in your site.
- Log into Interaction Studio as an Administrator
- In the Channels & Campaigns section, select Web > Site-Wide JavaScript
- Make the necessary changes
- Click SAVE
The following functions are available on the Interaction Studio 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 for Events
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 |
| alternateId | No | A 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. |
| margin | No | Gross 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 |
| created | auto-updated | |
| updated | auto-updated | |
| published | No | Date an item was published or became available - Item will not be promoted before this date |
| expiration | No | Date an item should be expired - Item will not be promoted after this date |
| promotionState | No | One of Prioritized or Excluded |
| rating | No | The average rating score for reviews on this item |
| numRatings | No | The count of reviews on this item |
| location.longlat | No | The location associated with this item, longitude first. For instance, Boston, MA is [-71.127197,42.3134791] |
| custom | No | Up 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);
Overview
Content Tools