UI for linear advertisements

Requirements

Provide a set of components for displaying and controlling linear advertisements. The controls layer would provide functionality to:

• Play/Pause ad playback (SSAI and CSAI)
• Prevent UI based seeking
• Provide a click-thru element
• Display ad details like “Ad X fo Y”

Proposal 1

Create a <media-ad-controller> element which bootstraps the ad SDK and act as a wrapper element for a separate set of ad controls. The ad ui would use the standard media-* controls, i.e. buttons like play and fullscreen, and the <media-ad-controller> would intercept the MEDIA_X_REQUEST events and perform any ad specific logic.

<media-controller>
  <video slot="media"></video>
  <media-control-bar>
    <media-play-button />
    <media-mute-button />
    <media-volume-range />
    <media-time-range />
    <media-pip-button />
    <media-fullscreen-button />
  </media-control-bar>
  <media-ad-controller>
    <media-ad-info />
    <media-control-bar>
      <media-play-button />
      <media-mute-button />
      <media-volume-range />
      <media-time-range />
      <media-pip-button />
      <media-fullscreen-button />
    </media-control-bar>
  </media-ad-controller>
</media-controller>

Pros

• Keeps the ad logic and controls contained to the <media-ad-controller> instead of having each component be aware of what type of media is playing and switching its logic accordingly.
• A completely custom “ad view” can be achieved entirely in mark down by simply adding the desired controls as children of <media-ad-controller>. With a single control bar for both modes, the playback mode would need to be made available in a way that CSS and JS could be written to customize the control for the given mode.
• In the future, if the library is ever delivered in an “unbundled” manner (individual ES6 modules), having that ad logic in a standalone component would allow for the ad code to be omitted entirely when not needed.

Cons

• More verbose markdown at the page level.
• The ad controller will need to be aware of the video element (ad SDK usually require a reference). Since the media element is not a child of <media-ad-controller> the reference would need to be injected some how:
  • Perhaps in a similar way to how state is passed down?
  • Sibling query selector?

Proposal 2

Similar to the first proposal but with the <media-ad-controller> wrapping the entire UI.

<media-controller>
  <media-ad-controller>
    <video slot="media"></video>
    <media-control-bar>
      <media-play-button />
      <media-mute-button />
      <media-volume-range />
      <media-time-range />
      <media-pip-button />
      <media-fullscreen-button />
    </media-control-bar>
  </media-ad-controller>
</media-controller>

Pros

• Less verbose markdown at the page level.
• Similar future “tree shaking” benefits as proposal one

Cons

• No ability to create custom ad views in markdown. At minimum the <media-ad-controller> would need to have a mode attribute that could be used to create CSS selectors, i.e:

  media-ad-controller[mode="ad"] media-time-range { 
    pointer-events: none; 
  }
  

Other considerations

The current set of web components revolve around a stable public API: HTMLMediaElement. There is no similar standard for ad playback. When using a raw playback engine likehls.js or dash.js the ad implementation would need to be done separately. This could easily be encapsulated using <media-ad-controller> as a base class, and creating a ad-vendor specific element such as <ima-ad-controller>. For full featured players like Shaka and Video.js, ad APIs are provided directly by the SDK, or via a plugin. In those cases there would need to be a element that translates the player specific APIs into a normalized API that <media-ad-controller> could use. Similar to the way <youtube-video> provides an API to mirror HTMLMediaElement.

[littlespex]

I’m open to any naming changes, and I would go with media-ad-break. For mediaadend, I can’t think of a UI reason for this event that couldn’t be met by adplay or adbreakend. I will update the previous comment with these changes, as well as a note about a new slot for an ad container.

[heff]

If the ad controller wraps the entire UI, there would need to be a new set of controls that fire ad specific events so that the ad controller could differentiate between the content actions and ad actions.

Had more thoughts on this one, incase UI level integrations are still a direction we need to go. I don’t know that we would need ad specific UI events here. The ad-controller could add event listeners to media-play-request and other events, and preventDefault to block further actions when needed (similar to how the IMA SDK works). This is a benefits of having every request funneled through the controller now rather than UI elements talking directly to the media element. Then the ad-controller can rely on its own current media-ad-playing state to determine if UI events should apply to the ad or the media.

There does seem to be a key long term implication to consider here, which is whether or not <media-controller> base media states (e.g. media-duration, media-current-time) are updated to reflect the ad state or maintain the primary media’s state. For example if media-current-time is updated to reflect the ad’s current time, then external elements now need to be “ad-aware”. For example an external text transcript that’s following along with the video. Or just a captions element. I think the answer is we don’t want that.

(this is very complicated… sorry for the all the long exploratory comments)

Pulling from various ideas, here’s a proposal…

1. Add first-class ad states to media-controller

<media-controller media-ad-playing media-ad-duration="100" media-ad-current-time="10" ...>

2. media-controller listens for ad-events on the media element, and updates ad state accordingly

<media-controller media-ad-playing>
  <jw-player></jw-player> <!-- media element with internal ads -->
</media-controller>

3a. A UI-level client-side ad integration can wrap media-controller and update its ad state accordingly.

The ad integration element can listen for a media-play-request on media-controller and preventDefault to block media playback and play an ad.

<media-ima-ads>
  <media-controller media-ad-playing>
    <video></video>
  </media-controller>
</media-ima-ads>

3b. A UI-level client-side ad integration could also wrap the media element, taking the the place of the media and exposing the html5 video API.

<media-controller media-ad-playing>
  <ima-video slot="media">
    <hls-video></hls-video>
  <ima-video>
</media-controller>

4a. For all cases, controls could then be built with a special control bar (Matt’s idea) that translates events/states

<media-controller>
  <video></video>
  <media-control-bar> <!-- control bar for media -->
    <media-play-button />
  </media-control-bar>
  <media-ad-control-bar> <!-- control bar for ads (special) -->
    <media-play-button />
  </media-ad-control-bar>
</media-controller>

4b. For the media-controller wrapping ad integration case, controls could also optionally live outside the media-controller, and not require a special control bar.

<media-ima-ads>
  <media-controller media-ad-playing>
    <video></video>
    <media-control-bar /> <!-- control bar for media -->
  </media-controller>
  <media-control-bar /> <!-- control bar for ads (not special) -->
</media-ima-ads>

Thoughts on that?