Amphtml: Intent to implement: AMP Access client-side via iframe

[dvoytenko]

Introduction

AMP Access spec provides a way for to lock/unlock content.

At the core of the protocol are three concepts:

1. AMP Reader ID. Globally unique session identifier in AMP context.
2. Authorization endpoint. A credentialed CORS GET HTTPS endpoint that returns the authorization response that can be used to unlock premium content. It can also be used to render auxiliary sections, such as growls.
3. Pingback endpoint. A credentialed CORS POST HTTPS endpoint that confirms the impression.

Metering implementation is specifically described in the Metering section of the AMP Access spec. It suggests that publishers store metering count on their backend system keyed by AMP Reader ID and/or any session information delivered via CORS protocol.

The goal of this ITI is to create a client-side solution that does not require CORS request (or doesn't always require it). This solution is based on 3p iframes.

Some important considerations when designing this solution:

1. Performance. Putting an iframe loading into critical path of document rendering is CPU/memory-heavy and slow. A typical iframe is has a multi-stage loading/execution sequence: load and parse iframe HTML, load main JavaScript, which in turn likely executes a remote XHR. So, this could be as bad as three sequential network requests before the response can be returned. All of these combined could easily reach into > 7s average. Some steps here optimizable, such as JavaScript can be directly bundled into HTML. But it’s hard to require such an optimization.
2. Local storage and cookie spaces could be partitioned on some browsers and Safari ITP makes this even less predictable.

The solution

The solution has several components:

1. Iframe config and instantiation, parametrized by the AMP Access configuration.
2. Iframe communication protocol to invoke authorize and pingback methods.
3. AMP-side caching solution with strict one-behind semantics.
4. AMP-side timeout semantics with one-behind continuation.

Iframe config and instantiation

This part is very straightforward. It roughly executed as following.

First, the new config extension is provided:

<script id="amp-access" type="application/json">
{
  "type": "iframe",
  "iframeSrc": "https://pub/iframe",
  "iframeVars": [
    "EXPRESSION1",
    "EXPRESSION2",
    ...
  ],
  "defaultResponse": {
    ...
  },
  // Additional properties.
}
</script>

The iframe is instantiated as following:

const iframeController = createIframe(config.src);
iframeController.connect(config).then(() => {
  // Continue to authorization, etc.
});

Iframe communication protocol

AMP will define communication protocol to invoke iframe's methods, most notably authorize and pingback.

Most important, the iframe will establish connection with AMP Runtime via a basic handshake:

1. When iframe is ready, it will exchange handshake messages with the AMP Runtime which will include config object.
2. The iframe will first confirm the origin of the AMP page and then perform its internal init/config steps. The iframe then will accept the connection.
3. After this, the AMP page and the iframe can communicate freely.

To execute authorization, AMP Runtime will:

1. Resolve all variables requested in the config.iframeVars.
2. Send authorize message to the iframe that includes these variables.
3. Await the authorize-response response message.
4. Apply authorization response as it does now.

To execute pingback, AMP Runtime will:

1. Resolve all variables requested in the config.pingbackVars.
2. Send pingback message to the iframe that includes these variables.

AMP-side caching with one-behind semantics

So far, this proposal is simple and similar to the AMP Access spec with CORS. However, this section will attempt to address performance issues. We'd like to use the previous response for the next page impression if possible. For the first visit, we also get some of the worst performance factors. So, we would rely on the defaultResponse to do the initial rendering when cache is not available, which will be assumed to be positive. However, we can speed up the follow up impression. The steps are:

1. If the authorization response is available in the local storage of the AMP Runtime and it's a positive response, use it to open up the page immediately. Delay rendering of any templates, however.
2. If the authorization response is not available in the local storage, open the page immediately using the defaultResponse.
3. In either case, in parallel, run the authorization iframe request. Include the previous response as an argument (this could also help with some storage inconsistencies).
4. Wait for the new response.
5. Store new response in the local storage of the AMP Runtime.
6. Render templates, if any, using the new response.

This requires us to define the notion of the positive response. It means that the authorization response grants read access. We will start by mandating a boolean granted field in the authorization response.

The cache can have an upper-bound expiration limit, e.g. the cached response is dropped after 7 days.

Thus, only the negative authorizations are render-blocking. Depending on metering quota, this could significantly reduce optimistic render blocks. It'd also normally result in no more than one extra view by the user.

AMP-side timeout semantics and one-behind

In case of previous negative response, the authorization is render-blocking. We normally apply a strict time-out of 3 seconds to authorization requests and we’d like to do the same here.

However, we can do one improvement: even if we timeout the authorization, we can still allow the iframe authorization request to continue and update the cache ones it completes. Thus, the next impression should hopefully proceed faster.

---

Based on #2970.

[cramforce]

I really like the compromise between developer flexibility and performance.

[cpapazian]

this is great. we currently use amp-iframe for some custom tracking of auth-ed users, but there has been no way yet for us to pass this data back to AMP. let me know if there's anything I can do to help this along ...

[ericlindley-g]

Checking in: is this work speculative at this point, or do we have a timeline in mind?

[rudygalfi]

Implementation is started. Not all pieces are yet merged.

A few pointers:

• An example of how code in iframe can be arranged is in this file: https://github.com/dvoytenko/amphtml/blob/58d9c72bc0324606f43689b432d3183b7361396d/examples/article-access-iframe.provider.html
• The main entry point in code is https://github.com/dvoytenko/amphtml/blob/58d9c72bc0324606f43689b432d3183b7361396d/extensions/amp-access/0.1/iframe-api/iframe-api.js
• Note: Using this requires turning on the "amp-access-iframe" experiment.

[rudygalfi]

The initial batch of PRs have made it in. The docs are in https://github.com/ampproject/amphtml/blob/master/extensions/amp-access/0.1/iframe-api/README.md

[dvoytenko]

The #14254 adds configuration parameters, defines authorization response more clearly and adds more docs.

[rudygalfi]

Just as clarification, the additional docs were appended to: https://github.com/ampproject/amphtml/blob/master/extensions/amp-access/0.1/iframe-api/README.md

[czarnechmurki]

How would one actually reference the sync script used in the iframe? That is, what will the absolute URL for that script (seen as the relative URL /dist.3p/current/amp-iframe-api-export.js in the article-access-iframe.provider.html example) be?

[dvoytenko]

@czarnechmurki amp-iframe-api-export.js is just the concatenation of two files: messenger.js and iframe-api.js. The synchronous /dist.3p/current/amp-iframe-api-export.js is just an example. Concatenation can be done manually, using tools such as rollup, or just take amp-iframe-api-export.js file we provide and drop it in your project. You most likely will want to compile these two files into your own JS binary to avoid extra downloads and sync issues - the startup time for this iframe is pretty important so reducing number of binaries would help.

We will eventually deploy bundled messenger.js and iframe-api.js as an npm module for those who manage dependencies/compile via npm. Let us know if it'd help you.

[dvoytenko]

The merged #14295 functionally completes the access-via-iframe integration. Remaining tasks are mostly administrative, such as exposing npm package, and fixing bugs. But otherwise we are starting tracking toward the launch.

[dvoytenko]

I'm closing this issue and we'll proceed with separate issues for additional fixed and features.

[lannka]

Pls clean up the feature flag if this is fully launched.

[alanorozco]

@lannka cleaned up