Background

For quite some time, we've been ideating about rich embedding experiences for stories on publisher's own sites. This issue tries to scope smaller projects that can be composed into the larger initiative.

Goals

Distributing our own embed library means we can ensure quality of embedded experience
We can get the embed JS out in the wild early on and improve upon embedded experience over time (AKA the "AMP as a Service" paradigm)

Non-Goals

Embedding within native applications
Altering the UI of the publisher page (i.e. showing the story in a lightbox, etc)

Features

Prerendering
Prefetching and caching resources
Customizable embed UI / chrome
Swipe/tap to next/previous

High-level API Design

There are three primary high-level goals of the API:

Allow the AMP and non-AMP implementations to have the same API
The AMP API should be idiomatic AMP
The stories themselves should be represented in a way that search engines would consider a link between the embedding document and the embedded document (story)
If the JavaScript fails to load, the experience should degrade gracefully

As such, we have settled on this API:

<amp-story-embed>
  <a href="https://www.example.com/story1.html"></a>
  <a href="https://www.example.com/story2.html"></a>
  <a href="https://www.example.com/story3.html"></a>
  <a href="https://www.example.com/story4.html"></a>
</amp-story-embed>

This feels like idiomatic AMP, can be used in both the AMP and non-AMP version, and with each representing a story, would allow search engines to crawl embedded stories. The tag will also continue to work, even if the JavaScript does not upgrade the to an embed.

Since each represents a story, we can include story-level metadata on the tag, as follows:

<a href="https://www.example.com/story1.html"
    data-poster-portrait-src="https://example.com/story1-portrait.png"
    data-poster-landscape-src="https://example.com/story1-landscape.png"
    data-poster-square-src="https://example.com/story1-square.png"
    data-publisher-logo-src="https://example.com/logo.png"
    data-title="My Awesome Story"
    data-publisher="The AMP Team">
</a>

Milestones

Milestone 1: "Simple" iframe embed

Write some simple JS to create a sandboxed iframe and propagate the story's src from the embed API to the iframe. That iframe should be wrapped in a shadow root, to prevent publisher styles from targeting any DOM output by this script (primarily as a means of future-proofing the script to allow it to output arbitrary UI elements outside of the iframe context).

As an optimization, we should load the cache URL for the story (we can hardcode cdn.ampproject.org at first, and allow publishers to configure their AMP cache of choice if the need arises).

Get this JS compiled and served from from cdn.ampproject.org. As a precedent, we can look to video-iframe-integration.js, which is also a JavaScript API that is served from cdn.ampproject.org, but not "part of AMP" (instead, rather, communicates with AMP over a postMessage-based API).

Usage

<script async src="https://cdn.ampproject.org/amp-story-embed-v0.js">
<!-- ... -->
<amp-story-embed>
  <a href="https://www.example.com/story1.html"></a>
</amp-story-embed>

Milestone 2: Add embed modes

Add a parameter that publishers can specify in the DOM/JSON configuration that can be passed through to the embedMode fragment parameter, to allow specifying embed modes.

Usage

<script async src="https://cdn.ampproject.org/amp-story-embed-v0.js">
<!-- ... -->
<amp-story-embed embed-mode="no-sharing">
  <a href="https://www.example.com/story1.html"></a>
</amp-story-embed>

Milestone 3: Switch from plain iframe to open source viewer implementation

The open source viewer implementation handles the messaging API between the viewer and the runtime, including the initial handshake, as well as sending messages. Using this JS API with the iframe implemented in Milestone 1 above will create a minimal AMP viewer.

Usage

From a user's perspective, this should be a no-op from Milestone 2.

Milestone 4: Ensure the document is a valid story

By virtue of the fact that it is loaded from the cache, we can be sure that the document is valid AMP. We should also ensure it is valid story (not just valid AMP), by either:

Have amp-story send an "I am story" message to the viewer
Parse the DOM and look for <amp-story standalone> (which, when combined with the fact that the document is valid AMP, should be sufficient to indicate it is a valid story)
- This is tricky, since we potentially want to make the iframe 3p

Usage

From a user's perspective, this should be a no-op from Milestone 2 and Milestone 3, as long as the document was a valid story.

Milestone 5: Allow prerendering

The open source viewer implementation should already support prerendering, with the visibilityState=prerender fragment parameter, as well as the visibilitychange request. The bigger question here will be how to best expose prerendering as an API to publishers (i.e. how do we know what to prerender? how do we keep from prerendering too little? too much?)

Usage

TBD. This milestone would have to expose some type of hook for publishers to indicate that a given URL should be prerendered.

Milestone 6: Allow tapping/swiping to next/previous story

Once prerendering is allowed, we should allow tapping/swiping to the next/previous story.

Both require setting up multiple viewer iframes and prerendering the next story. Swipe events should be handled manually and animate to the next story's iframe, positioned after the current iframe, along the x-axis. To enable tapping to the next story, the viewer should handle the selectDocument request, and inspect its payload to determine whether it should move the previous or next story's iframe into focus.

Usage

<script async src="https://cdn.ampproject.org/amp-story-embed-v0.js">
<!-- ... -->
<amp-story-embed embed-mode="no-sharing">
  <a href="https://www.example.com/story1.html"></a>
  <a href="https://www.example.com/story2.html"></a>
  <a href="https://www.example.com/story3.html"></a>
</amp-story-embed>

Milestone 7: Preloading

Native apps have a distinct advantage over web content in that they can preload content when users are in other contexts (e.g. on a list of stories, they can begin preloading the assets for the stories in that list). We can simulate this behavior by including code to either directly prefetch content, or to install a service worker to do the same.

Usage

TBD. This milestone would have to expose some type of hook for publishers to indicate that a given URL should have its resources preloaded.

Closed Questions

Does iframing a story in hurt SEO?
- Before script execution, the DOM structure simply uses tags to allow crawling. This should be no different than simply including a link to the story.
Where does this code live?
- Let's put it under ampproject/amphtml/src and add the open source web viewer as an npm package
- amp-script does similar with workerdom: package.json | import
How do we validate publisher configurations, since this does not go through the AMP validator?
- Console errors
Can we enable a bundle size check for the amp-story-embed bundle?
- Yes, coming soon: Bundle size checks for extensions #20843

Open Questions

How will we keep the AMP and non-AMP implementations in sync?
- We might be able to use some Bento work to do this.
For the AMP implementation (i.e. embedding a story inside of an AMP page), this will necessitate multiple runtimes running at once. Does this cause too much of a demand for resources?
How do editors using CMSes (e.g. Arc) to create articles embed this into said articles?
- Is there a hook to paste some embed code?
- Would that let you also import a script?
Logging?

I2I: amp-story-player #24539

Description

Describe the new feature or change to an existing feature you'd like to see

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions