Premium

Entity attributes

Use entity attributes to pass product or content information to Adobe Target Recommendations.

Entities refer to the items you want to recommend. Entities can include products, content (articles, slide shows, images, movies, and television shows), job listings, restaurants, and so forth.

Recommendations sends the productId or productPurchasedId (referred to as entity.id in the code) that is used in the algorithms.

Consider the following:

• entity.id must match the productPurchasedId sent to the order confirmation page and the productId used in Adobe Analytics product reports.
• Entity attribute values that you pass to Recommendations expire after 61 days. Adobe recommends that you pass the latest value of each entity attribute to Recommendations at least once per month for each item in your catalog.

Most predefined parameters accept a single value only, with new values overwriting old values. The categoryId parameter can accept a comma-delimited list of values for each category containing that product. New categoryId values do not overwrite existing values but instead are appended during entity update (250-character limit).

In general, the display information mbox looks like the following example if you are using at.js 1.x with mboxCreate. All entity parameter attributes are case-sensitive.

<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=/help/baseball/giants-tix/giantsvrockies5.12.2000-67833',

'entity.venue=AT&T PARK',

'entity.secondary=ROCKIES',

'entity.thumbnailUrl=/help/baseball/giants-tix/giants-136px.gif',

'entity.message=FAMILY SPECIAL',

'entity.value=15.99',

'entity.inventory=1'

);

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

Available variables

The following list describes the available variables.

entity.id

Singe value only.

This required parameter identifies the product. This alphanumeric ID must be the same across all Adobe Experience Cloud products that are used, including Analytics, for the various products to recognize the item and share data about it.

The entity.id values must not contain spaces, slashes, ampersands, question marks, percentage symbols, commas, or other punctuation characters that require URL encoding when passed in a REST API call. Hyphens and underscores are allowed. Including invalid punctuation in an entity.id value causes some Recommendations functionality to fail.

Example: 'entity.id=67833'

entity.name

Single-value only.

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

Example: 'entity.name=Giants& vs& Rockies& 5/12'

entity.categoryId

Supports multi-value (comma-delimited list).

Category of the current page. The entity.categoryID can include multiple categories, such as a cardigans sub-subsection (for example, womens, womens:sweaters, womens:sweaters:cardigans). Multiple categories must be separated by commas.

The categoryId value is limited to 250 characters.

Examples:

• Example Product Detail Page: womens, womens:sweaters, womens:sweaters:cardigans
• Example Category Page Sweaters: womens:sweaters
• Example Category Page Cardigans: womens:sweaters:cardigans

For category-based recommendations, a comma separates category value. Any values separated by commas become categories. You can also define subcategories by using a different separator, such as a colon (:), to separate subcategories within the category value.

For example, in the following code the Women’s category is divided into several subcategories:

mboxCreate('mboxName', 'entity.id=343942-32', 'entity.categoryId= Womens, Womens:Outerwear, Womens:Outerwear:Jackets, Womens:Outerwear:Jackets:Parka, Womens:Outerwear:Jackets:Caban', 'entity.thumbnailUrl=...', 'entity.message=...', );

For the mbox delivery, the longest attribute name is used for the key. If there is a tie, the last attribute is used. In the example above, the category key is Womens:Outerwear:Jackets:Caban.

entity.brand

Single-value only.

Displays an item’s brand name.

Example: 'entity.brand=brandxyz'

entity.pageUrl

Single-value only.

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

Single-value only.

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

Example: 'entity.thumbnailUrl=baseball/giants-tix/giants-136px.gif'

entity.message

Single-value only.

A message about the product that is displayed in the recommendation, such as “on sale” or “clearance.” The message is typically more verbose than the product name. Use entity.message to define additional information to display with the product in the template.

Example: 'entity.message=Family special'

entity.inventory

Single-value only. Requires an integer or long value.

Displays the inventory level of the item.

Example: 'entity.inventory=1'

Empty Inventory Attribute Handling: For delivery, if you have an inclusion rule, collection rule, or criteria setting with entity.inventory > 0 or entity.inventory = 0 and the product has inventory not set, Target evaluates this value to TRUE and includes products where the inventory is not set. As a result, products with inventory that is not set display in recommendation results.

Similarly, if you have a global exclusion rule with entity.inventory = 0 and entity.inventory is not set, Target evaluates this rule to be TRUE and excludes the product.

Known issue: Product Search is inconsistent with delivery for inventory value attributes that are not set. For example, for a rule with entity.inventory = 0 , Product Search does not display products where the inventory value is not set.

entity.value

Single-value only.

Defines the price or value of the item.

Example: 'entity.value=15.99'

entity.value supports decimal format only (for example, 15.99). The comma format (15,99) is not supported.

entity.margin

Single-value only.

The profit margin or other value of the item.

Example: 'entity.margin=1.00'

entity.custom

Supports multi-value (JSON array).

Define up to 100 custom variables that provide additional information about the item. You can specify any unused attribute name for each custom attribute. For example, you can create a custom attribute called entity.genre to define a book or movie. A ticket vendor can create attributes for an event venue for a secondary performer, such as a visiting team in a sporting event or an opening act in a concert.

Restrictions:

• You cannot use predefined entity attribute names for custom entity attributes.
• The attribute entity.environment is reserved by the system and cannot be used for custom entity attributes. Attempts to pass entity.environment using targetPageParams, feed, or API are ignored.

Examples:

'entity.venue=AT&T Park'

'entity.secondary=Rockies'

Custom entity attributes support multiple values. See Custom entity attributes for character and value limits.

Example: 'entity.secondary=["band1", "band2"]'

Multi-value custom entity attributes require valid JSON arrays. For correct syntax information, see Custom Entity Attributes.

entity.event.detailsOnly

Single-value only.

Used to prevent an mbox call from incrementing behavioral data counters for an algorithm.

Example: 'entity.event.detailsOnly=true'

In the examples below, the first mbox call updates the catalog and behavioral data. The second mbox call updates only the catalog.

mboxCreate('myMbox', 'profile.geo.city = new york', 'profile.geo.state = new york',  'entity.id = 'entity.inventory = 4' )
mboxCreate('myMbox',  'profile.geo.city = new york', 'profile.geo.state = new york',  'entity.id = 123', 'entity.inventory = 4' 'entity.event.detailsOnly=true' )