Interactions data entities

  • Article

This article provides guidance on how to configure your interactions data entities in the Intelligent Recommendations data contract.

Data entities review

A data entity is a set of one or more data text files, each having a list of columns (also called attributes) and rows containing the actual data values.

Intelligent Recommendations defines logical groups of data entities, each with its own purpose.

Note

Data entities are optional, unless explicitly stated otherwise, which means that their data can be empty or missing.

Go to the full list of data entities

Introduction to interactions data entities

Interactions represent the set of all ways that a user interacts with the catalog items. Some common user actions include transactional interactions (purchases), views (click-through), ratings, or any other action that occurs between a user and an item or item variant.

The following data entities are part of the interactions data entities:

Interactions

Data entity name: Reco_Interactions.

Description: All user interactions with items and item variants.

Attributes:

Name Data type Mandatory Default value Invalid value behavior Comments
InteractionGroupingId String(256) Yes Drop entry A grouping ID for several interactions. Length limited to 256 characters.
ItemId String(16) Yes Drop entry See Required data entities per recommendations scenario for item ID.
ItemVariantId String(16) No Drop entry See Required data entities per recommendations scenario for item variant ID.
UserId String(256) No Drop entry An empty value represents an anonymous interaction. Length limited to 256 characters.
InteractionType String No Transaction Drop entry Transaction is the only valid value for this attribute and doesn't affect the recommendation results.
TimeStamp DateTime No 1970-01-01T00:00:00.000Z Drop entry See Required data entities per recommendations scenario for DateTime values.
String Attribute String(64) No Drop entry Length is limited to 64 characters. A string attribute that can be used according to the business' needs and doesn't affect the modeling process.
Double Attribute Double No Drop entry A double attribute that can be used according to the business' needs and doesn't affect the modeling process.
Channel String(64) No 0 Trim value Length limited to 64 characters.
Catalog String(64) No 0 Trim value Length limited to 64 characters.
Strength Double No 1.0 Drop entry Represents how significant the interactions are (compared to other interactions). This attribute can help improve transaction processes and performance, but transparency and ethical use of data are important considerations. Supported in Next Best Action, User Picks and Similar (AlgoType=MF).
IsPositive Bool No True See Required data entities per recommendations scenario for Boolean values.

Guidelines:

  • InteractionGroupingId is the main collaborative indicator grouping items together in a single multi-item interaction. It can be anything that, in the scope of your business, creates relationships between items. For example, items purchased in the same interactions (basket) might be connected/related, so basket/transaction ID could be a good fit for this field. If a collaborative factor is the user (person) interacting with items, you might want to copy UserId to this field and have it in the UserId field as well.

  • Make sure that Interactions data entity contains interactions of the same type (type can be - likes, transactions, views, etc.). In order to get recommendations for various interaction types, it's recommended that a modeling component reads interactions of the same type. Consolidating different types of transactions into the same model return mixed recommendations with different and not necessarily desired meaning than working with separated models/IR accounts.

  • Unsupported interaction types are ignored.

  • All data rows that represent the same operation (for example, a transaction of several items) should have the same unique grouping ID.

  • Negative interactions (such as item returns or dislikes) are represented by IsPositive=False.

  • Double Attribute, String Attribute and Interaction Type columns listed can be left empty for now.

  • Using "0" as the value for either the "Channel" or "Catalog" attributes result in a processing error.

  • On Next Best Action scenario, Strength attribute is capped at 10. values above 10 are replaced by 10.

  • Examples of when to use strength include:

    • Prioritize products with a higher likelihood of being interacted with (i.e. viewed, watched, etc.). If you prefer to have higher prioritization on recent purchases, consider trying the Picks API using the RecentPurchases Algo-type, which already prioritizes the most recent interactions of a user.
    • Rating scores to products in scale of 1-5 can be reflected by setting the strength of the relevant transaction as the rating score that the user gave to the item.
    • Prioritizing the duration of watching a video by giving longer views a higher strength than the videos of shorter views.

Sample data:

Headers appear for convenience only and shouldn't be part of the actual data.

InteractionGroupingId ItemId ItemVariantId UserId InteractionType Timestamp String Attribute Double Attribute Channel Catalog Strength IsPositive
Interaction100 Item1 Item1Var1 Transaction 2020-04-01T10:00:00.000Z
Interaction100 Item2 Transaction 2020-04-01T10:00:00.000Z 2.0
Interaction101 Item2 User1 Like 2020-05-01T13:25:00.000Z Interaction-101-RT False
Interaction101 Item3 User2 Rating 2020-07-12T08:45:00.000Z Europe MySale 4.0 False

Go to the full list of data entities

See also

Data contract overview
Data entities mapping table
Catalog data entities
Reco configuration data entities
External lists data entities
Opted-out users data entities
Recommendations enrichment data entities
Image to item mapping data entities
Intelligent Recommendations API
Quick start guide: Set up and run Intelligent Recommendations with sample data