Interaction Upload API

Authorizations

api_key

string

query

required

Your secret API key is used to access every Miso API endpoint. You should secure this key and only use it on a backend server. Never leave this key in your client-side JavaScript code. If the private key is compromised, you can revoke it in Dojo and get a new one.

Specify your secret key in the api_key query parameter. For example:

POST /v1/users?api_key=039c501ac8dfcac91c6f05601cee876e1cc07e17

Body

application/json

data

required

Show child attributes

data.type

enum<string>

required

Used when a user views the detail page of a product. Viewing a product detail page usually indicates a user is interested in the product to certain degree, especially, when the duration of the page view is long. When duration of the page view is very short (< 5 seconds), product_detail_page_view may indicate neural or negative interest in the product.

Available options:

product_detail_page_view

data.duration

number

How long (in seconds) the user stayed on this page, or consumed (listened, read, or watched) a product. This field is optional, but it's very important in scenarios where consumption duration matters, including product_detail_page_view, category_page_view, watch, listen, and read. For example, if a user only views or consumes a product for less than 5 seconds, that user is probably not interested in the product. On the other hand, if a user stays on a page for a while, it usually means they are seriously engaging with or considering the product. When duration is absent, we will use the timestamp of the next interaction to infer a rough duration value.

Example:

{"duration": 61.5}

Example:

61.5

data.product_ids

string[]

Products or content the user is interacting with. This field is required by almost all the interaction types. We use product_ids to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets.

Example:

{"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]}

Maximum string length: 512

Example:

["123ABC-BLACK"]

data.product_group_ids

string[]

The product groups the user is interacting with. You only need this field if you model product variants using product_id and product_group_id (see Product API). If so, you should use this field, when a user is interacting with a product group rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet.

In such situations, the product_id is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use product_group_ids to capture such interactions in place of product_ids.

In the situations where specific product_ids are available, for example, when user selected a particular size of the T-Shirt, use product_ids instead.

Example:

{"product_group_ids": ["123ABC"]}

Maximum string length: 512

Example:

["123ABC"]

data.user_id

string

Identifies the signed-in user who performed the interaction. We will use user_id to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see anonymous_id.

Maximum string length: 512

Example:

"user_1234"

data.anonymous_id

string

A pseudo-unique substitute for the User Id. We use anonymous_id to identify a visitor who has not signed in. anonymous_id can be implemented using mechanisms such as cookies or browser localStorage. If anonymous_id is not given, we will default it to SHA1(<API key>:<IP address>:<user agent>:<date>). When a visitor 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.

Maximum string length: 1024

Example:

"86D51273AD8BF84217E1567B6CBE7152D7034404"

data.timestamp

string<date-time>

The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution.

Example:

{"timestamp": "2018-11-07T00:25:00.073876Z"}

data.miso_id

string<uuid>

Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use miso_id to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated miso_id to the next page view, and associate the miso_id with the interactions that take place on the page (e.g. product_detail_page_view, add_to_cart, add_to_collection, like, etc.). In this way, Miso will learn which recommendations work and which didn't.

Example:

{"misoId": "123e4567-e89b-12d3-a456-426614174000"}

Example:

"123e4567-e89b-12d3-a456-426614174000"

data.context

Context · object

Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly.

Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through).

Example:

{"context": {
    "campaign":
    {
        "name": "spring_sale",
        "source": "Google",
        "medium": "cpc",
        "term": "running+shoes",
        "content": "textlink"
    },
    "truncated_ip": "1.1.1.0",
    "locale": "en-US",
    "region": "US East",
    "page":
        {
            "url": "https://example.com/miso-tshirt-123ABC",
            "referrer": "https://example.com/",
            "title": "My Product Page"
        },
        "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)"
    },
    "custom_context": {
        "other_context_var_1": "value_1",
        "other_context_var_2": "value_2"
    }
}

Show child attributes

data.context.campaign

Campaign · object

The campaign that resulted in the interaction. Campaign dictionary contains standard UTM parameters: name, source, medium, term, content. We use campaign information to infer users' interests and fine-tune the personalization and search results based on the current user's campaign information.

Show child attributes

data.context.campaign.name

string

Name of the campaign. Identifies a specific product promotion or strategic campaign. (see UTM parameters)

Example:

"spring_sale"

data.context.campaign.source

string

Source of the campaign. Identifies which site sent the traffic. (see UTM parameters)

Example:

"Google"

data.context.campaign.medium

string

Medium of the campaign that identifies what type of link was used, such as cost per click or email. (see UTM parameters)

Example:

"cpc"

data.context.campaign.term

string

Term of the campaign that identifies search terms. (see UTM parameters)

Example:

"running+shoes"

data.context.campaign.content

string

Content of the campaign that identifies what specifically was clicked to bring the user to the site, such as a banner ad or a text link. It is often used for A/B testing and content-targeted ads. Identifies search terms. (see UTM parameters)

Example:

"textlink"

data.context.truncated_ip

string<ipv4>

User's truncated IP address. We use IP address to determine the country of the users.

Example:

"1.1.1.0"

data.context.locale

string

Locale string of the current session, for example en-US.

Example:

"en-US"

data.context.region

string

The region/location of the site the user is visiting. This is for sites that serve different regions or markets. You can define your own region keywords, for example, US East, Europe, LATM, etc.

Example:

"US East"

data.context.page

Page · object

The current page in the browser. Page dictionary containing referrer, title and url. we will use page view as a pseudo interaction to infer users' interest.

Show child attributes

data.context.page.url

string

required

Url of the page

Example:

"https://example.com/miso-tshirt-123ABC"

data.context.page.referrer

string

Url of the referrer page

Example:

"https://example.com/"

data.context.page.title

string

Title of the page

Example:

"My Product Page"

data.context.user_agent

string

User agent of the device making the request. We use this to determine if a user is browsing the site on mobile or desktop, and tailor the recommendations and search results accordingly.

Example:

{"user_agent":
    "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0"}

Example:

"Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0"

data.context.custom_context

Custom Context · object

Dictionary of custom context variables for the current browsing session. You can specify context variables specific to your websites or apps in a {"KEY":VALUE} format, where KEY must be a string, and VALUE can be:

a bool
a string or an array of string
a number or an array of numbers
an array of objects
null

Miso will take these variables into account when generating recommendations.

Show child attributes

data.context.custom_context.{key}

Example:

{
  "session_variable_1": ["value_1", "value_2"]
}

Response

Successful Response

message

string

required

Human-readable message

Example:

"success"

API Documentation

Experiment APIs

Data APIs

Anonymous users

Schema validation

Authorizations

Body

Response