Interaction Model - Cobi Documentation

Important: User interaction records have dependencies students. The system validates the student_id against existing records in the database. You should upload student data before uploading user interaction records to ensure proper data validation. The item_id field must reference the correct item type as specified by item_type.

Schema

{
  "type": "object",
  "required": [
    "interaction_type",
    "student_id",
    "item_type",
    "event_timestamp"
  ],
  "properties": {
    "interaction_type": {
      "type": "string",
      "description": "Type of interaction. One of: FILTER_CLICK, SHARE, PAGE_VIEW, DISCOUNT_CODE"
    },
    "user_id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the student"
    },
    "student_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "UUID of the student"
    },
    "item_type": {
      "type": "string",
      "description": "One of: TAG, OFFER, SHOP, KEYWORD"
    },
    "item_id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the item (TAG, OFFER, KEYWORD or SHOP) as determined by item_type"
    },
    "city": {
      "type": "string",
      "description": "City where the interaction occurred"
    },
    "country": {
      "type": "string",
      "description": "Country where the interaction occurred"
    },
    "platform": {
      "type": "string",
      "description": "One of: ANDROID, IOS, WEB, OTHER"
    },
    "event_timestamp": {
      "type": ["integer", "string"],
      "description": "Event timestamp (positive integer or ISO datetime string)"
    }
    "source": {
      "type": "string",
      "nullable": true,
      "description": "Source of interaction. Set to 'COBI' when the interaction is from a recommendation API response, null otherwise"
    },
    "recommendation_id": {
      "type": "string",
      "nullable": true,
      "description": "Recommendation ID of cobi recommended interaction, null otherwise"
    },
  }
}

Field Descriptions

Required Fields

Field	Type	Description
`interaction_type`	string	Type of interaction. One of: FILTER_CLICK, SHARE, PAGE_VIEW, DISCOUNT_CODE
`item_type`	string	One of: TAG, OFFER, SHOP
`item_id`	string (UUID)	UUID of the item (TAG, OFFER, KEYWORD or SHOP) as determined by `item_type`
`event_timestamp`	int/ISO string	Event timestamp (positive integer or ISO datetime string)

Optional Fields

Field	Type	Description
`user_id`	string	Psuedo Id of the student
`student_id`	string (UUID)	UUID of the student
`city`	string	City where the interaction occurred
`country`	string	Country where the interaction occurred
`platform`	string	One of: ANDROID, IOS, WEB, OTHER
`source`	string	Source of interaction. Set to ‘COBI’ when from recommendation API, null otherwise
`recommendation_id`	string (UUID)	Source of interaction. Set to ‘COBI’ when from recommendation API, null otherwise

Example

{
  "interaction_type": "FILTER_CLICK",
  "user_id": "75962b04e5caa7e582e2bc2949587ed9"
  "student_id": null,
  "item_type": "TAG",
  "item_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "city": "Berlin",
  "country": "Germany",
  "platform": "WEB",
  "event_timestamp": 1718035200,
  "source": "COBI",
  "recommendation_id": "6fc7eb1d-a516-4a9b-8dcc-313976461ae4"
}

Source Field for Recommendation Feedback

The source field is used to track whether user interactions originated from recommendation API responses:

null: The interaction occurred through normal user browsing (not from a recommendation)
"COBI": The interaction occurred when a user clicked on or interacted with an item that was recommended by the Cobi recommendation API

This field is crucial for:

Feedback Loop: Helps the recommendation system understand which recommendations led to user engagement
Analytics: Track the effectiveness of recommendation algorithms
Model Training: Improve future recommendations based on user interaction patterns

Example Usage

When a user receives recommendations from the API and clicks on a recommended offer:

{
  "interaction_type": "PAGE_VIEW",
  "student_id": "00000000-9779-438e-ae0d-b52099f6be51",
  "item_type": "OFFER",
  "item_id": "00000000-aaca-4844-9cb0-54af8f897322",
  "event_timestamp": 1718035200,
  "source": "COBI"
}

Best Practices

Data Validation: Ensure all required fields are present and properly formatted.
Timestamps: Use a valid positive integer or ISO 8601 string for event_timestamp.
Platform: Use one of the allowed values for platform.
Source Tracking: Always set source to “COBI” when tracking interactions from recommendation API responses.

Need help? Contact our support team at [email protected]

​Schema

​Field Descriptions

​Required Fields

​Optional Fields

​Example

​Source Field for Recommendation Feedback

​Example Usage

​Best Practices

Schema

Field Descriptions

Required Fields

Optional Fields

Example

Source Field for Recommendation Feedback

Example Usage

Best Practices