Recommendation API - interactions

Page views

When a user visits a product or article page, you can send product_detail_page_view interactions to track the behavior. This information can be used to improve the user experience and provide more relevant recommendations.

First you could specify the user ID for a registered user, or the anonymous ID for an anonymous user:

client.context.user_id = 'user_id';
// or
client.context.anonymous_id = 'some_anonymous_id';
  • If you omit both user_id and anonymous_id, the SDK will generate an anonymous ID remembers it automatically.

Then you can send the product_detail_page_view interaction:

client.api.interactions.upload({
  type: 'product_detail_page_view',
  product_ids: ['my_article_id', ...], // the IDs of the products or articles in your catalog
  timestamp: '2024-01-01T00:00:00Z', // optional
});
  • If you omit the timestamp, the Miso API will use the current time.

Historical data

It is encouraged to send historical data to the Miso API. This will help Miso to understand the user's behavior and preferences better in a short time.

  • When sending historical data, make sure to include timestamp in the interaction payload.

The UI plugin of SDK sends user interactions to Miso API for analytics automatically. You can send interactions manually if needed.

Syntax

client.api.interactions.upload({
  type: 'impression', // or 'viewable_impression', 'click', 'submit'
  miso_id: '...', // miso_id from API response
  context: {
    custom_context: {
      api_group: 'recommendation',
      api_name: 'product_to_products', // or 'user_to_products', 'user_to_trending'
      property: '...',
      items: [...], // if subjects are not catalog items
    },
  },
});

API names

  • product_to_products
  • user_to_products
  • user_to_trending

Properties

The property field in the interaction payload refers to the subject of the interaction. It usually corresponds to a field in the API response with a few exceptions.

Property Associated required field Interactions
products product_ids impression, viewable_impression, click

Interaction types

Type Definition
impression The content of a subject is rendered in DOM tree, regardless of being seen or not.
viewable_impression At least 50% of the content of a subject shows up in viewport for a consecutive 1 second.
click The user clicks on the link of a subject, which may lead to an article/product page or answers page.

Interaction payload fields

Top-level fields:

Field Type Required Description
type string ✓ Interaction type.
miso_id string ✓ Miso-generated unique ID in each API response.
product_ids array of strings product_id values of the subject items (when they are catalog items).

Fields under context.custom_context:

Field Type Required Description
api_group string ✓ The first segment of API path, in snake case.
api_name string ✓ The second segment of API path, in snake case.
property string ✓ The subject name of the interaction, which usually correspond to a field in the API response.
site string The site name. Only required when you serve multiple sites from a single Miso app.
unit_id string The unit id of the workflow unit. Only required when you have multiple units in your site. When omitted, the unit name shows Home for URL path / and otherwise Article in analytics.
items array of strings Subject items (when they are non-catalog items, such as related_questions).

References