ZWMAP Annotation Type Specification

1. Overview

Annotation types are used to describe interactive areas on the video screen and interactive events on the timeline. The protocol follows the Separation of Mechanism and Policy principle: it provides the underlying UI container and atomic actions, allowing users to freely combine them for specific business scenarios.

Annotation data contains two types of elements:

Hotspots: Interactive areas displayed on the video screen, occupying specific positions and time ranges
Events: Interactive panels triggered on the timeline, such as quizzes, tooltips, forms, etc.

At least one of hotspots or events must be provided.

2. ZWMAP Header

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "annotation"
}

zwp_protocol and zwp_type are required fields. Backward compatibility is not supported; the ZWMAP protocol header must be included.

3. Hotspot Object

A hotspot describes an interactive area on the video screen.

Field	Type	Required	Description
`id`	string	Yes	Unique identifier
`time_range`	array	Yes	Display time range `[start, end]` (seconds)
`position`	object	Yes	Position and size `{ "x", "y", "w", "h" }` (percentage 0-100)
`action`	object	No	Action triggered on click (at least one of `action` or `content` is required)
`content`	object	No	Content to display (text, image, etc.)
`style`	object	No	Style configuration (border, opacity, background color, animation, etc.)
`hint`	string	No	Hover tooltip text

4. Action Types

All Action type values use UPPER_SNAKE_CASE.

4.1 Media Control

type	Parameters	Description
`SEEK_TIME`	`target`(number), `show_back_btn`(bool)	Seek on timeline
`LOAD_ITEM`	`target`(string)	Switch playlist item
`PAUSE_MEDIA`	None	Force pause
`PLAY_MEDIA`	None	Resume playback

4.2 UI and Routing

type	Parameters	Description
`OPEN_LINK`	`url`(string), `target`(_blank/_self), `pause`(bool)	Open external link
`SET_VISIBILITY`	`target_id`(string), `visible`(bool), `auto_hide`(number)	Control hotspot visibility

4.3 Data and Communication

type	Parameters	Description
`EMIT_MESSAGE`	`payload`(object)	Send postMessage to host environment
`SUBMIT_DATA`	`api_url`(string), `method`(POST/PUT/PATCH), `body`(object)	Send request to external API

4.4 State Management

type	Parameters	Description
`SET_VARIABLE`	`key`(string), `value`(any)	Set session variable

5. Event Types

All Event type values use UPPER_SNAKE_CASE, representing 5 basic UI containers.

type	Description	Core Fields
`INFO_CARD`	Info card/Popup	`title`, `content`, `media_url`, `buttons`
`CHOICE_BOARD`	Selection panel (unified quiz/branch/questionnaire)	`prompt`, `options`, `is_evaluative`, `allow_multiple`
`INPUT_FORM`	Data form	`title`, `fields`, `submit_url`
`TOAST_NOTICE`	Light tooltip/Bubble	`text`, `position`, `duration`
`WEB_VIEW`	External view container	`src`, `width`, `height`

Event object fields:

Field	Type	Required	Description
`id`	string	Yes	Unique identifier
`time`	number	Yes	Trigger time point (seconds)
`type`	string	Yes	Event type
`interrupt`	boolean	No	Whether to interrupt playback (pause video)
`data`	object	Yes	Event content data

6. Complete Example

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "annotation",
  "zwp_version": "1.0",
  "hotspots": [
    {
      "id": "hs_link_01",
      "time_range": [3.0, 15.0],
      "position": { "x": 10, "y": 20, "w": 25, "h": 15 },
      "action": {
        "type": "OPEN_LINK",
        "url": "https://www.example.com",
        "pause": true
      },
      "style": {
        "border_color": "#FF6B6B",
        "border_style": "solid",
        "border_width": 1,
        "animation": "pulse"
      },
      "hint": "点击查看详情"
    },
    {
      "id": "hs_msg_01",
      "time_range": [10.0, 30.0],
      "position": { "x": 70, "y": 5, "w": 15, "h": 8 },
      "content": {
        "type": "text",
        "text": "加入购物车 →",
        "style": { "color": "#fff", "font_size": 13 }
      },
      "action": {
        "type": "EMIT_MESSAGE",
        "payload": { "action": "ADD_TO_CART", "sku": "12345" }
      }
    }
  ],
  "events": [
    {
      "id": "quiz_01",
      "time": 60.0,
      "type": "CHOICE_BOARD",
      "interrupt": true,
      "data": {
        "prompt": "以下哪个是正确的？",
        "is_evaluative": true,
        "options": [
          { "text": "选项 A", "value": "A", "is_correct": false },
          { "text": "选项 B", "value": "B", "is_correct": true },
          { "text": "选项 C", "value": "C", "is_correct": false }
        ],
        "feedback": { "correct": "回答正确！", "wrong": "请重试" },
        "max_attempts": 2,
        "fallback_time": 10.0,
        "on_complete": { "type": "PLAY_MEDIA" }
      }
    },
    {
      "id": "toast_01",
      "time": 15.0,
      "type": "TOAST_NOTICE",
      "data": {
        "text": "精彩内容即将到来！",
        "position": "top_center",
        "duration": 3
      }
    }
  ]
}

7. Constraints

Each id must be unique throughout the document (no conflicts between hotspots and events)
position values are in percentage (0-100), not pixels
The first value of time_range must be less than the second value
At least one of action or content must be provided
The target_id of SET_VISIBILITY must point to an existing hotspot ID
Events are triggered by the time value; the player should process them in chronological order
Unknown Action or Event types must be silently ignored and must not cause the player to crash