Interaction Upload API

Miso’s Interaction APIs let you manage your Interaction records stored with Miso.

Interaction records

Your Interaction records tell Miso about user interactions with products and content on your site or application. From these interactions, Miso understands how users move through your conversion funnels: which products or content assets attract the attention of each individual user, and which products or content ultimately will be purchased or consumed by each of them. With these insights, Miso makes real-time tailored recommendations for each user, and responds to each of their clicks and views on the site (even for anonymous users).

Interaction records share some common attributes, but are distinguished by their type. Miso captures 23 different interaction types, divided into the following 6 groups:

Core click-streams

• product_detail_page_view: a user viewed the detail page for a product
• search: a user made a search request with keywords and (optionally) filters

The above interactions are the core fuel 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 the site. The collection of these interactions is highly important for Miso’s personalization performance. At the minimum, you should implement the product_detail_page_view interaction to start with.

Conversion (eCommerce)

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

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

Consumption (content media)

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

If you are a content site, the above interactions are the main drivers to 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 implement at least one of these interactions.

Feedback signals

• like, dislike, share, rate, 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.

Performance Checking

• impression: a user saw or was presented with a product or content asset (but didn’t yet interact with it)
• viewable_impression: the product or content presented is actually viewed by the user (for example, minimum of 50% of the pixels were in viewable space for at least one continuous second.)
• click: a user clicked on something (for example, a product item)

Additional click-streams

• home_page_view: user viewed your home page
• category_page_view: a user viewed the page for a specific “group” or “family” or products or content in your catalog
• 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.

Custom

• custom interaction types are reserved for you to define your own business-specific interaction types.

Miso will analyze any custom interactions you define to infer users’ interests and preferences.

Bulk API to insert Interaction records. This endpoint accepts POST requests with JSON data containing an array of Interaction records wrapped in a dictionary:

POST /v1/interactions

{"data": [interaction_1, interaction_2, interaction_3]}

For real-time tracking, we recommend sending the interaction records to this API as soon as the interactions take place. This API is also ideal for bulk-inserting historical records that your site collected before using Miso. Miso can analyze the historical records and provide personalization for your users from the get-go. We recommend limiting your calls to around 10,000 records at a time to avoid memory issues or timeout risks.

Anonymous users

For users who did not sign in, we can still make recommendations for them by tracking their anonymous_id, which is a pseudo-unique substitute for the user_id. The personalization and search APIs all accept anonymous_id in the place of user_id to return tailored results for anonymous users.

When an anonymous user later signs in and the user_id and anonymous_id are both present, the anonymous_id will be linked to the user_id along with the past interactions associated with it.

The typical mechanism to generate an anonymous_id is to use cookies or the browser localStorage. However, if you don’t collect such information in your historical records, a hash of the IP address, optionally combined with the User-Agent string, is also a reasonable substitute for anonymous_id, and is most likely collected by your web server logs already.

Schema validation

The Interaction Upload API will validate the inserted records against the API schema. Any schema errors will cause the whole request to fail, and none of the records will be inserted (status_code=422). You should check the response.errors field to see if there are any errors.

For example, the response below means there are no errors (status_code=200):

{
    "message": "success"
}

Any schema error will cause the whole request to fail: the API will return status_code=422, and none of the records will be inserted. You should check data field in the response to see where the errors are located. For example, the response below means there are schema errors in the interaction record at index 0:

{
    "errors": true, // there are errors. please check!
    "message": "None of the records were inserted because at least one of them contained schema errors. Please see the `data` field for details.",
    "data": [
        "data.0.product_ids is invalid. The attribute was expected to be of type ''array', 'null'' but type 'string' was given.",
        "data.0.timestamp is invalid. The attribute should match the 'date-time' format."
    ]
}