MediaEngagedPayload media.engaged@1

Generated at from openvibe-contracts v0.419.0 and openvibe-sdk v0.161.0.

Version
1.0.0
Owner
media
Visibility
internal
Status
active
Compatibility
backward
Decision
ADR-004
Schema
https://openvibe.network/contracts/events/payloads/media.engaged.v1.json

media.engaged v1 (OpenVibe.Media server/views/service.js, POST /api/v1/views). A viewer became engaged with an item for the first time: they watched 30 seconds or a third of its length (whichever came first, of_seconds known) on a watch, or 60 seconds of a live stream. One event per person (or anonymous session) per item, ever, however many heartbeats follow. ref names the item in its owner's id space; site and creator are the same optional Report dimensions as media.viewed. seconds is the cumulative watch time that reached the threshold, threshold the number that was needed. No IP address, user agent or raw anonymous session id is in the payload or stored with the view. Events are outbox rows written with the count in the same transaction and relayed to OpenVibe.Events; subject { type: <kind>, id: <id> }, visibility internal, actor service:media.

Fields

FieldTypeRequiredDescriptionConstraints
refobjectyes
  • no other fields
ref.servicestringyes
  • pattern ^[a-z][a-z0-9-]{1,39}$
ref.kindstringyes
  • pattern ^[a-z][a-z0-9_]{1,39}$
ref.idstringyes
  • minLength 1
  • maxLength 200
ref.sitestring | nullThe site the view happened on, or null when it is the owning service.
  • maxLength 40
ref.creatorstring | nullThe creator's canonical subject or channel username, or null when unknown.
  • maxLength 200
howenumyesA preview never engages.
  • one of "watch", "live"
occurred_atstringyesWhen Media marked the viewer engaged.
  • pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,3})?Z$
  • format date-time
secondsnumberyesThe cumulative watch time that reached the threshold.
  • minimum 1
  • maximum 86400
thresholdnumberyesThe seconds that were needed: 60 for a live stream, else min(30, of_seconds / 3) when of_seconds was known, otherwise 30.
  • minimum 1
  • maximum 60
of_secondsnumber | nullThe item's length when the client knew it.
  • maximum 86400
concurrentinteger | nullLive watchers Media saw at that moment (how = live), null otherwise.
  • minimum 1

Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

Valid: watch
{
  "ref": {
    "service": "media",
    "kind": "clip",
    "id": "7"
  },
  "how": "watch",
  "occurred_at": "2026-11-12T10:04:05.123Z",
  "seconds": 30,
  "threshold": 30,
  "of_seconds": 120
}
Rejected: preview
{
  "ref": {
    "service": "media",
    "kind": "clip",
    "id": "7"
  },
  "how": "preview",
  "occurred_at": "2026-11-12T10:04:05.123Z",
  "seconds": 30,
  "threshold": 30
}

Validate

const contracts = require('openvibe-contracts');
contracts.validate('media.engaged@1', value);   // { valid, errors: [{ path, message }] }