Amphtml: [amp-story-player] [master tracker] UI Custom Controls API

[Enriqe]

We should allow publishers to specify icons and their corresponding events to be dispatched. We should also allow some basic customization like vertical (header/footer) and horizontal (start/end) placement. See https://github.com/ampproject/amphtml/issues/30031#issuecomment-685842504 for more details on the API.

Work plan:

• [x] Consume JSON configuration from player (PR: #30500)
• [x] Send a message from player to story with desired configuration (PR: #30501) (API spec: #30588)
• [x] From the story side, build the system layer with desired configuration. (PR: #30502)
  
  
  
  • [x] Fix pagination buttons for pre-rendered documents bug. (PR: #30503)
  
  
  • [x] Validate configuration (limit amount of icons - mobile and desktop have different limits).
    
    
  
  
  • [x] Add click listeners that sends message back to player for those buttons that are appropiate. (PR #30745)
  
  
• [x] Listen to messages from player side and perform corresponding action (skip next story in desktop, dispatch custom event, etc..) (PR: #30745) (API Spec: #30588)

Button-specific:

• [x] Skip button: disable when there are no next stories. (PR #30745)
• [x] Close button: always position at start/end of other icons .(PR: #30502)

[Enriqe]

The player will accept an inline JSON object with the desired configuration, the fields and requirements are as follows:

  “controls”: array of objects, each one containing:
    “name”: a string with the name of the button. If the name is part of the default set of buttons (close / (un)mute / share) the following fields are optional but overridable.
    “backgroundImageUrl”:  (required when not part of the default set of buttons) accepts  URLS and `data:image` URIs like base64 images and svgs. 
    “visibility”: “hidden” or “visible”
    “position”: “end” or “start” string values

An example of it being used within the player:

<amp-story-player style="width: 360px; height: 600px;">
  <script type="application/json">
    {
        "controls": [ // Required.
          {
            "name": "mute", // If name is part of default set: the default event/behavior and icon will be used, but can be overridden. 
            "backgroundImageUrl": "icon.jpg",  // Supports URLS and `data:image` URIs like base64 images and svgs.
          },
          {
            "name": "close",
            "position": "start", // Values: "start" or "end".
          },
          {
            "name": "customButton", // If not part of default set, the following fields will be required.
            "backgroundImageUrl": "data:image/svg+xml;charset=utf-8,<svg ... "
          }
        ]
    }
  </script>
  <a href="story.com/1.html">...</a>
  <a href="story.com/2.html">...</a>
</amp-story-player>

For the dev preview version, we will only allow up to 3 controls in mobile, and 6 in desktop.

The default set will include: (mobile) share, speaker, close (desktop) share, speaker, play/pause, skip-next, close. If limit is reached, other buttons are discarded.

[newmuis]

Looks good! We need semantics to avoid name collisions on the buttons (e.g. amp-mute instead of mute). Otherwise we can't add new default buttons or we might break someone that was using that.... Right?

Or will the icon and event even override default buttons?

[Enriqe]

The idea is that icon and event are optional if part of the default set, but overridable if desired. So if publisherX is using a buttonX with their own icon and event, and we later introduce buttonX as part of the default set, we will still respect the pubisherX's icon and event, because it overrides the default behavior. Does this sound good to you? @newmuis @gmajoulet

[newmuis]

Thanks for clarifying!

[Enriqe]

All main tasks have been finished. Remaining items are:

• Deleting previous exit-control API.
• Writing documentation.

Will file separate issues for those.