Importing Interaction Data


Once you’ve loaded your product catalog data into Miso, the next step is to load the interaction data. This is the clickstream data about your customers’ interactions with your site. Miso analyzes events pertaining to the whole gamut of the conversion funnel – impressions, searches, checkouts, and more. For the initial engine training, a historic data load of ~3 months of clickstream data is recommended. You will also need to set up a data pipeline to send real-time interaction updates to Miso from your site. This enables Miso to continually provide in-session 1:1 personalization, even for first time, anonymous users.

In total, Miso has support for 23 different interaction types, divided into the following five groups:

Core click-streams

  • product_detail_page_view: a user viewed the detail page for a product
  • category_page_view: a user viewed the page for a specific “group” or “category” of products in your catalog
  • search: a user made a search request with keywords and (optionally) filters
  • impression: a user saw or was presented with a product (but didn't yet interact with it)

The above interactions are the core for Miso's personalization Engines, because they happen in a much higher frequency than other interactions and provide an unbiased and high-fidelity view of users' interests on your site. The collection of these interactions is highly important for Miso's personalization performance. At the minimum, you should send Miso the  product_detail_page_view interaction.

Conversion (e-commerce)

  • add_to_cart: a user added a product to the shopping cart
  • remove_from_cart: a user removed a product from the shopping cart
  • subscribe: a user subscribed to a product
  • checkout: a user checked out and started the payment process
  • refund: a user refunded the product

The above interactions are the main revenue drivers for e-commerce sites. It’s important to collect them so that Miso can not only improve click-through rates, but also improve the revenue in a targeted way. To start with, you should send Miso the add_to_cart interaction.

Consumption (content media)

  • readwatch, and listen interactions capture how and for how long a user consumed a piece of content
  • add_to_collection: a user added a product to their personal collection
  • remove_from_collection: a user removed a product from their personal collection

If you are a content site, the above interactions are the main drivers of users' satisfaction on the site. Collecting these interactions allows Miso to drive consumption rates and consumption durations for the content on your site. If you run a content site, you should send Miso at least one of these interactions.

Feedback signals

  • likedislikesharerate, and bookmark are common ways users express their interests.

These are strong signals for Miso to understand each user's preferences regarding your products or content. You should send these signals to Miso if you have any of these UI patterns on your site.

Additional click-streams

  • home_page_view: user viewed your home page
  • promo_page_view: user viewed the promotion pages about certain products
  • product_image_view: user clicked on or otherwise interacted with the product image (e.g. enlarged the image)

The above interactions are additional signals for Miso to understand users' behavior on the site.

Sample Record

Below is a sample record of a product_detail_page_view interaction:

    "type": "product_detail_page_view",
    "duration": 61.5,
    "product_ids": [],
    "product_group_ids": [],
    "user_id": "user_1234",
    "anonymous_id": "86D51273AD8BF84217E1567B6CBE7152D7034404",
    "timestamp": "2019-08-24T14:15:22Z",
    "miso_id": "123e4567-e89b-12d3-a456-426614174000",
    "context": {
        "campaign": {
            "name": "spring_sale",
            "source": "Google",
            "medium": "cpc",
            "term": "running+shoes",
            "content": "textlink"
        "truncated_ip": "",
        "locale": "en-US",
        "region": "US East",
        "page": {
            "url": "",
            "referrer": "",
            "title": "My Product Page"
        "user_agent": "Mozilla/5.0",
        "custom_context": {
            "session_variable_1": [

Figure 1 - The list of supported interaction attributes

A few important notes:

  1. The type field defines the type of interaction. It must be one of the interactions listed above.
  2. The miso_id field is an automatically generated unique id for each recommendation or search result. When a user clicks on a recommendation or search result, you should pass the associated  miso_idto the next page view and associate the miso_idwith the interactions that take place on that page. Miso uses this field to track and fine-tune the performance of the personalized recommendations and search results.
  3. For anonymous site visitors, you should use a unique id (such as a hash of the user’s IP address and user agent) and pass it into the anonymous_id field. If they eventually sign in or create an account, Miso will reconcile the anonymous and permanent user profiles as long a request containing the user_id and anonymous_id are sent together at least once.

Importing Interaction Data using APIs

Interaction data can be imported using the Interactions API. The basic call pattern looks like below, with each interaction in the array following the schema shown in Figure 1:

POST /v1/interactions
    "data": [

Figure 2 - A basic call pattern for the Interactions API

Here’s what a sample request might look like using JavaScript:

const apiKey = "<your private api key>"
const url = `${apiKey}`

// interaction objects are wrapped inside {"data": [...]}
const payload = [
        "type": "product_detail_page_view",
        "product_ids": [
        "user_id": "user_123",
        "timestamp": "2021-08-24T14:15:22Z"

fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    body: payload
.then(response => response.json())

Figure 3 - A JavaScript example of an API request to Miso

Making it real-time

Using the direct, REST API interface as part of the real-time data pipeline is an efficient solution for organizations who are already collecting individualized clickstream data and sending it to an event streaming platform like Apache Kafka or Amazon Kinesis. For these scenarios, Miso can simply be added as an additional consumer. For organizations that do not currently collect this data, a 3rd party integration or Miso’s client-side SDK may be more appropriate.

Importing Interaction Data Using Miso's SDK

Miso maintains a client-side SDK for JavaScript that can be used to collect and send interaction data in real-time. The SDK can be installed as a module or by using a <script> tag in the page header. This is a great solution for organizations who do not currently collect interaction data. For more on Miso's SDK, please see here.

Importing Interaction Data Using an Integration

Miso integrates with popular CDPs and Analytics platforms, such as Segment and Mixpanel, as well as all-in platforms such as Shopify and Wordpress to import both historic and real-time interaction data. Please see the full list of integrations and instructions here.

Importing Interaction Data Using Dojo

Dojo provides an intuitive, no-code UI for managing your Miso data sets and engines.

The recommended method for importing interaction data is either via the Interactions API or an integration. However, if you are more comfortable using a point-and-click UI, you can upload a JSON file containing a list of interactions directly through Dojo. Note that manually uploading clickstream logs in Dojo is only viable for the initial, historic data load.

  1. From the left navigation pane of the Dojo Dashboard, under the Data sets category, select Interactions.

    Figure 4 - Dojo navigation pane

  2. Select Import data file and either drag and drop the JSON file, or click in the designated area to upload a file from a file browser.

    Figure 5 - Importing a data file in Dojo

  3. Select Next step.

  4. A progress bar will appear as the interaction data is loaded into Miso. When it’s at 100%, select Next step.

  5. If the data load is successful, you will be taken to a dashboard where you can view the uploaded data.

    Figure 6 - Interaction data dashboard in Dojo

Next: Importing User Data

Icon/Activity Icon/Add Icon/API Icon/Arrow/Down Icon/Arrow/Left Icon/Arrow/Right Icon/Arrow/TopRight Icon/Arrow/Up Icon/Bento Icon/Billing Icon/Bin Icon/Book Icon/Bookmark/Default Icon/Bookmark/Filled Icon/Calendar Icon/Caret/Down Icon/Caret/Up Icon/Chavron/DownIcon/Chavron/LeftIcon/Chavron/RightIcon/Chavron/UpIcon/Checknox/CheckedIcon/Checknox/Unchecked Icon/Checklist Icon/Chip Icon/Clipboard / Copied Icon/Clipboard/Default Icon/Clock/Stopwatch Icon/CMD Icon/Data/Catalog Icon/Data/Engine Icon/Data/Group Icon/Data/Interact Icon/Data/Users Icon/Dive Icon/Docs/Key Icon/Dojo Icon/Email Icon/Env/Development Icon/Env/Playground Icon/Env/Prod Icon/Folder Icon/Fullscreen/Collapse Icon/Fullscreen/Expand Icon/Guides/Multiple Icon/Guides/Single Icon/Hashtag Icon/Heart/Outline Icon/Heart/Solid Icon / Cart z Icon / Click Icon / Clock Icon / Data Icon / Doc Icon / EmptyCart z Icon/Social/Facebook Icon / Genome Incognito Icon / Money Icon/Social/ProductHunt Icon / Search Icon/Social/Twitter Icon / User Icon/Info/Error Icon/Info/Info Icon/Info/Question Icon/Info/Warning Icon/Interact/Download Icon/Interact/Edit Icon/Interact/External v2 Icon/Interact/External Icon/Interact/Filter Icon/Interact/Logout Icon/Interact/Options Icon/Interact/Re-order Icon/Interact/Reload Icon/Interact/Remove Icon/Interact/Replace Icon/Interact/Search Icon/Interact/Shuffle Icon/Interact/Undo Icon/Interact/Upload Icon/Interact/Video Icon/Invoice Icon/Loading Icon/Loading Icon/Lock/Locked Icon/Lock/Unlocked Icon/Lock Icon/Mapping Menu Icon/Notification Icon/Overview Icon/Person/Team Icon/Person/User Icon/Plan/Enterprise Icon/Plan/Growth Icon/Plan/Startup Icon/Plan/Trial Icon/Recipe Icon/Rocket Icon/Settings/App Icon/Settings/User Icon/Settings Icon/Shrine Icon/Sidebar/Close Icon/Sidebar/Open Icon/Slideout Icon/Sort/Ascending Icon/Sort/Default Icon/Sort/Descending Icon/Star/Filled Icon/Star/Outlined Stopwatch Icon/Support Icon/Tag Icon/Interact/Thumb/Dislike Icon/Interact/Thumb/Like Icon/Tick Icon/Trend/New Icon/Trend/Trending Icon/Tutorial Icon/Lock/Unlocked Icon/View/Grid Icon/View/List Icon/Watchlist/Add