Event Format

Metarank expects to receive a predefined set of events, describing visitor activity and item metadata:

1. Item metadata events. They describe what should be known about items.

2. User metadata events. They describe what we may know about visitors.

3. Ranking events. What was presented to the visitor.

4. Interaction events. What visitor did with the ranking (clicks, likes, purchases).

Event format

Metarank expects to receive these events in JSON format for simplicity. There is also a plan to add support for protobuf in some future version. Each event has a couple of shared required fields:

• id - which is a unique identifier for the event, should be generated by your app

• timestamp - number of milliseconds from 1970-01-01T00:00:00 (see timestamp format description on which formats are supported)

• event - one of item/user/ranking/interaction values.

There is also a shared optional "tenant" field for multi-tenancy cases.

fields parameter

fields parameter is used in all events, however it is optional for ranking and interaction events. You can provide some additional context, like a search query, selected filters or shipping data that can be used as features of your personalization model.

"fields": [
  {"name": "title", "value": "You favourite cat"}
]

fields.name: name of the field. fields.value: can be any of the following types:

• boolean

• string

• number

• list of strings

• list of numbers

Item metadata event

Metadata event is used to provide Metarank with updates of your content items (new items added, updates of values for existing items). You don't need to pass all values that your items have; only the ones that you might use as your personalization model features.

Event format

{
  "event": "item",
  "id": "81f46c34-a4bb-469c-8708-f8127cd67d27",
  "timestamp": "1599391467000",
  "item": "item1", 
  "fields": [
    {"name": "title", "value": "You favourite cat"},
    {"name": "color", "value": ["white", "black"]},
    {"name": "is_cute", "value": true}
  ]
}

• id: event id.

• item: id of the content item.

• fields: an array of content item properties, see event fields chapter for details.

User metadata event

User metadata is useful when you have some extra knowledge about your visitor. For example, if visitor filled a signup form, it could be gender or age.

Event format

{
  "event": "user",
  "id": "81f46c34-a4bb-469c-8708-f8127cd67d27",
  "timestamp": "1599391467000",
  "user": "user1",
  "fields": [
    {"name": "age", "value": 33},
    {"name": "gender", "value": "m"}
  ]
}

• id: event id. This field is not yet used, but the value must be provided at the moment.

• user: id of the visitor.

• fields: an array of content item properties, see event fields chapter for details.

Ranking event

Ranking event is used to indicate what items and in what order are shown to a visitor. This information is used by personalization algorithms to understand which items are relevant for the visitor.

Event format

{
  "event": "ranking",
  "id": "81f46c34-a4bb-469c-8708-f8127cd67d27",
  "timestamp": "1599391467000",
  "user": "user1",
  "session": "session1",
  "fields": [
      {"name": "query", "value": "cat"},
      {"name": "source", "value": "search"}
  ],
  "items": [
    {"id": "item3", "fields": [{"name": "relevancy", "value": 2.0}]},
    {"id": "item1", "fields": [{"name": "relevancy", "value": 1.0}]},
    {"id": "item2", "fields": [{"name": "relevancy", "value": 0.1}]} 
  ]
}

• id: a request identifier later used to join ranking and interaction events. Should match the value that is sent to the Ranking API.

• user: an optional unique visitor identifier.

• session: an optional session identifier, a single visitor may have multiple sessions.

• fields: an optional array of extra fields that you can use in your model, as described above.

• items: which particular items were displayed to the visitor.

• items.id: id of the content item. Should match the item property from metadata event.

• items.fields: a set of optional per-item fields.

• items.label: an optional field for explicit relevance judgments.

Interaction event

Interaction event identifies which actions the visitor performed on the items displayed. Some of the example of such events are: click, like, purchase. The type field must match the name provided in the Configuration.

Event format

{
  "event": "interaction",
  "id": "0f4c0036-04fb-4409-b2c6-7163a59f6b7d",
  "ranking": "81f46c34-a4bb-469c-8708-f8127cd67d27",
  "timestamp": "1599391467000",
  "user": "user1",
  "session": "session1",
  "type": "purchase",
  "item": "item1",
  "fields": [
    {"name": "count", "value": 1},
    {"name": "shipping", "value": "DHL"}
  ]
}

• id: a request identifier.

• ranking: an optional identifier of the parent ranking event. Some interactions may happen outside of the ranking event (for example, likes happened on an item page), so it can be legally empty.

• user: an optional unique visitor identifier.

• session: an optional session identifier, a single visitor may have multiple sessions.

• type: internal name of the event.

• item: id of the content item. Should match the item property from metadata event.

• fields: an optional array of extra fields that you can use in your model, as described above.