User event data specifications

HOME , LAND Event Types

These event types’ JSON payloads are identical.

  • HOME event type is when a shopper views your website's main or home page.
  • LAND event type is when a shopper is visiting your website from an external source (ex. Google Shopping).

JSON body parameters

NameData TypeRequired or RecommendedDescription
idString (up to 128 characters)RecommendedUnique ID of a User Event generated by the Platform. Moloco Commerce Media uses it for various purposes, like data deduplication.
event_typestringRequiredSet value as HOME or LAND
timestampstringRequiredUnix timestamp in milliseconds– not seconds – that the event happened at. (e.g., 1617870506121)
channel_typestringRequiredUse APP if the data source was a mobile app.
Use SITE if it was from a web app.
page_idstring (up to 128 characters)RecommendedPage ID should be a uniquely assigned value for each page in the app or website. Provide a string that can identify the context of the event, such as electronics, categories/12312, azd911d or /classes/foo/lectures/bar. Any value will be acceptable if it helps identify unique pages.
user_idstring (up to 128 characters)RequiredLogged-in user ID of the platform. Do not use this field if the user is not logged in. We recommended hashing the user ID before sending.
device.persistent_idstring (up to 128 characters)RequiredIdentifier for tracking users regardless of sign-in status. Please follow Generating persistent identifiers for more details.
referrer_page_idstring (up to 128 characters)RecommendedSimilar to the referrer in HTTP, this value indicates from which page the user came to the current page.
deviceobjectRecommendedDevice information that the user event generated from.

JSON body parameter example

{
  "id": "164686671692740224564",
  "event_type": "HOME",
  "timestamp": "1692740224564",
  "channel_type": "APP",
  "user_id": "yKDTEr",
  "session_id": "617949A9D05448498064F878AE85740E1692740027697",
  "referrer_page_id": "https://mycommerce.com/category/furniture",
  "device": {
    "os": "iOS",
    "os_version": "14.4.1",
    "advertising_id": "7acefbed-d1f6-4e4e-aa26-74e93dd017e4",
    "persistent_id": "617949A9-D054-4849-8064-F878AE85740E",
    "model": "iPhone 11 Pro",
    "ua": "Mozilla/5.0",
    "language": "en"
  }
}

ITEM_PAGE_VIEW, ADD_TO_CART, and ADD_TO_WISHLIST Event Types

Three event types’ JSON payloads are identical.

  • ITEM_PAGE_VIEW event type is when a shopper visits a product detail page.
  • ADD_TO_CART event type is when a shopper adds an item to the cart.
  • ADD_TO_WISHLIST event type is when a shopper puts an item into the wish list.

JSON body parameters

NameData TypeRequired or RecommendedDescription
idString (up to 128 characters)RecommendedUnique ID of a User Event generated by the Platform. Moloco Commerce Media uses it for various purposes, like data deduplication.
event_typestringRequiredSet value as ITEM_PAGE_VIEW, ADD_TO_CART, or ADD_TO_WISHLIST.
timestampstringRequiredUnix timestamp in milliseconds– not seconds – that the event happened at. (e.g., 1617870506121)
channel_typestringRequiredUse APP if the data source was a mobile app.
Use SITE if it was from a web app.
itemsarray of objectsRequiredSet the item id information as a JSON object [{ "id": "173762" }]
page_idString (up to 128 characters)RecommendedPage ID should be a uniquely assigned value for each page in the app or website. Provide a string that can identify the context of the event, such as electronics, categories/12312, azd911d or /classes/foo/lectures/bar. Any value will be acceptable if it helps identify unique pages.
user_idString (up to 128 characters)RequiredLogged-in user ID of the platform. Do not use this field if the user is not logged in. We recommend hashing the user id before sending.
device.persistent_idString (up to 128 characters)RequiredIdentifier for tracking users regardless of sign-in status. Please follow Generating persistent identifiers for more details.
referrer_page_idString (up to 128 characters)RecommendedSimilar to the referrer in HTTP, this value indicates from which page the user came to the current page.
deviceobjectRecommendedDevice information that the user event generated from.

JSON body parameter example

{
  "id": "164686671692740224564",
  "event_type": "ITEM_PAGE_VIEW",
  "timestamp": "1692740224564",
  "channel_type": "APP",
  "items": [
    {
      "id": "173762"
    }
  ],
  "user_id": "yKDTEr",
  "session_id": "617949A9D05448498064F878AE85740E1692740027697",
  "referrer_page_id": "https://mycommerce.com/category/furniture",
  "device": {
    "os": "iOS",
    "os_version": "14.4.1",
    "advertising_id": "7acefbed-d1f6-4e4e-aa26-74e93dd017e4",
    "persistent_id": "617949A9-D054-4849-8064-F878AE85740E",
    "model": "iPhone 11 Pro",
    "ua": "Mozilla/5.0",
    "language": "en"
  }
}

SEARCH Event Type

SEARCH event type is when a shopper searches items with keywords or phrases from your site.

JSON body parameters

NameData TypeRequired or RecommendedDescription
idString (up to 128 characters)RecommendedUnique ID of a User Event generated by the Platform. Moloco Commerce Media uses it for various purposes, like data deduplication.
event_typestringRequiredSet value as SEARCH
timestampstringRequiredUnix timestamp in milliseconds– not seconds – that the event happened at. (e.g., 1617870506121)
channel_typestringRequiredUse APP if the data source was a mobile app.
Use SITE if it was from a web app.
search_querystringRequiredQuery string for the search.
page_idstring (up to 128 characters)RecommendedPage ID should be a uniquely assigned value for each page in the app or website. Provide a string that can identify the context of the event, such as electronics, categories/12312, azd911d or /classes/foo/lectures/bar. Any value will be acceptable if it helps identify unique pages.
user_idString (up to 128 characters)RequiredLogged-in user ID of the platform. Do not use this field if the user is not logged in. We recommended hashing the user id before sending.
device.persistent_idString (up to 128 characters)RequiredIdentifier for tracking users regardless of sign-in status. Please follow Generating persistent identifiers for more details.
referrer_page_idString (up to 128 characters)RecommendedSimilar to the referrer in HTTP, this value indicates from which page the user came to the current page.
deviceobjectRecommendedDevice information that the user event generated from.

JSON body parameter example

{
  "id": "164686671692740224564",
  "event_type": "SEARCH",
  "timestamp": "1692740224564",
  "channel_type": "APP",
  "search_query": "microwave ovens",
  "user_id": "yKDTEr",
  "session_id": "617949A9D05448498064F878AE85740E1692740027697",
  "referrer_page_id": "https://mycommerce.com/category/furniture",
  "device": {
    "os": "iOS",
    "os_version": "14.4.1",
    "advertising_id": "7acefbed-d1f6-4e4e-aa26-74e93dd017e4",
    "persistent_id": "617949A9-D054-4849-8064-F878AE85740E",
    "model": "iPhone 11 Pro",
    "ua": "Mozilla/5.0",
    "language": "en"
  }
}

PAGE_VIEW Event Type

PAGE_VIEW event type is when a shopper visits a page other than the product detail pages or the home page of your site.

JSON body parameters

NameData TypeRequired or RecommendedDescription
idString (up to 128 characters)RecommendedUnique ID of a User Event generated by the Platform. Moloco Commerce Media uses it for various purposes, like data deduplication.
event_typestringRequiredSet value as PAGE_VIEW
timestampstringRequiredUnix timestamp in milliseconds– not seconds – that the event happened at. (e.g., 1617870506121)
channel_typestringRequiredUse APP if the data source was a mobile app.
Use SITE if it was from a web app.
page_idString (up to 128 characters)RequiredPage ID should be a uniquely assigned value for each page in the app or website. Provide a string that can identify the context of the event, such as "electronics", "categories/12312", "azd911d" or "/classes/foo/lectures/bar". Any value will be acceptable if it helps identify unique pages.
user_idString (up to 128 characters)RequiredLogged-in user ID of the platform. Do not use this field if the user is not logged in. We recommended hashing the user ID before sending.
device.persistent_idString (up to 128 characters)RequiredIdentifier for tracking users regardless of sign-in status. Please follow Generating persistent identifiers for more details.
referrer_page_idString (up to 128 characters)RecommendedSimilar to the HTTP referrer, this value indicates from which page the user came to the current page.
deviceObjectRecommendedDevice information that the user event generated from.

JSON body parameter example

{
  "id": "164686671692740224564",
  "event_type": "PAGE_VIEW",
  "timestamp": "1692740224564",
  "channel_type": "APP",
  "page_id": "electronics",
  "user_id": "yKDTEr",
  "session_id": "617949A9D05448498064F878AE85740E1692740027697",
  "referrer_page_id": "https://mycommerce.com/category/furniture",
  "device": {
    "os": "iOS",
    "os_version": "14.4.1",
    "advertising_id": "7acefbed-d1f6-4e4e-aa26-74e93dd017e4",
    "persistent_id": "617949A9-D054-4849-8064-F878AE85740E",
    "model": "iPhone 11 Pro",
    "ua": "Mozilla/5.0",
    "language": "en"
  }
}

PURCHASE Event Type

PURCHASE event type is when a shopper purchases a product.

JSON body parameters

NameData TypeRequired or RecommendedDescription
idString (up to 128 characters)RecommendedUnique ID of a User Event generated by the Platform. Moloco Commerce Media uses it for various purposes, like data deduplication.
event_typeStringRequiredSet value as PURCHASE
timestampStringRequiredUnix timestamp in milliseconds– not seconds – that the event happened at. (e.g., 1617870506121)
channel_typeStringRequiredUse APP if the data source was a mobile app.
Use SITE if it was from a web app.
itemsArray of ObjectsRequiredList of items with item ID and price information.

Example:
"items": [{
"id": "396172",
"price": {
"currency": "USD",
"amount": "429.98"
},
"quantity": "1"
}]
revenueObjectRequiredThe total amount of the purchase translation. The amount would be equal to or less than the sum of the item prices, depending on whether you want to represent the price discounts in the sales attribution.

Example:
"revenue": {
"currency": "USD",
"amount": "429.98"
}
shipping_chargeObjectRecommendedThe shipping cost of the PURCHASE event. Ignore the field if there is no shipping charge.

Example:
"shipping_charge": {
"currency": "USD",
"amount": 9.99
}
user_idString (up to 128 characters)RequiredLogged-in user ID of the platform. Do not use this field if the user is not logged in. We recommended hashing the user ID before sending.
device.persistent_idString (up to 128 characters)RequiredIdentifier for tracking users regardless of sign-in status. Please follow Generating persistent identifiers for more details.
referrer_page_idString (up to 128 characters)RecommendedSimilar to the referrer in HTTP, this value indicates which page the user came to the current page from.
deviceObjectRecommendedDevice information that the user event generated from.
decision_track_idStringOptionalA custom attribution tracking field. Please ignore it unless the Moloco team recommends sending the parameter.

JSON body parameter example

{
  "id": "164686671692740224564",
  "event_type": "PURCHASE",
  "timestamp": "1692740224564",
  "channel_type": "APP",
  "user_id": "yKDTEr",
  "session_id": "617949A9D05448498064F878AE85740E1692740027697",
  "referrer_page_id": "https://mycommerce.com/category/furniture",
  "items": [
    {
      "id": "396172",
      "price": {
        "currency": "USD",
        "amount": "429.98"
      },
      "quantity": "1"
    }
  ],
  "revenue": {
    "currency": "USD",
    "amount": "429.98"
  },
  "shipping_charge": {
    "currency": "USD",
    "amount": "11"
  },
  "device": {
    "os": "iOS",
    "os_version": "14.4.1",
    "advertising_id": "7acefbed-d1f6-4e4e-aa26-74e93dd017e4",
    "persistent_id": "617949A9-D054-4849-8064-F878AE85740E",
    "model": "iPhone 11 Pro",
    "ua": "Mozilla/5.0",
    "language": "en"
  },
  "decision_track_id": "208564fc-81af-11ee-b962-0242ac120002"
}

Device object

Device object is a common JSON object for mobile devices' User Event data

NameData TypeRequired or RecommendedDescription
osStringRecommendedOS of the device. "iOS" or "Android" must be included for the App channel type.
os_versionStringRecommendedThe device OS version is taken from the device without manipulation or normalization. (e.g., "14.4.1")
advertising_idStringRecommendedFor app traffic, IDFA of iOS or ADID of Android should be filled in this field. (e.g., 7acefbed-d1f6-4e4e-aa26-74e93dd017e4)
device.persistent_idString (up to 128 characters)RequiredIdentifier for tracking users regardless of sign-in status. Please follow Generating persistent identifiers for more details.
modelStringRecommendedThe device model string is taken from the device without manipulation or normalization. (e.g., "iPhone 15 Pro")
uaStringRecommendedUser Agent. (e.g. "Mozilla/5.0 (iPhone; CPU iPhone OS 14_4_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/111FFF")
languageStringRecommendedISO-639-1 alpha-2 language code. (e.g., "en")
ipStringRecommendedIP in IPv4 format. (e.g., 216.212.237.213)
...
"device": {
    "os": "iOS",
    "os_version": "14.4.1",
    "advertising_id": "7acefbed-d1f6-4e4e-aa26-74e93dd017e4",
    "persistent_id": "617949A9-D054-4849-8064-F878AE85740E",
    "model": "iPhone 11 Pro",
    "ua": "Mozilla/5.0",
    "language": "en"
  }
...