Intent to Implement: Premutate amp-bind state

[josh313]

Background

amp-bind allows developers to create interactive pages that can change content and show/hide different sections through user interactions. In some cases, it would be useful for an AMP viewer to be able to “deep-link” the user into a specific part of the page by setting the page’s AMP state.

Proposal

We should make amp-bind support a new message from the viewer called premutate which sets the amp-bind state of the AMP doc and re-computes all bindings. The message payload would have a single key state whose value is the state to set in the page. In order to allow a given AMP doc to be premutated like this, the page developer would have to add an overridable attribute to any amp-states that they would like to allow to be premutated by the viewer. The AMP doc responds to the premutate message with a list of the top-level state keys that were set.

Example

For the following AMP document:

...
<amp-state id="foo" overridable>
  <script type="application/json">
    {
      "data": 1
    }
  </script>
</amp-state>
<amp-state id="bar">
  <script type="application/json">
    {
      "data": 2
    }
  </script>
</amp-state>
...

If the viewer sent a premutate message with:

{
  "type": "q",
  "name": "premutate",
  "payload": {
    "state": {
      "foo": {
        "data": 3
      },
      "bar": {
        "data": 4
      }
    }
  }
}

The resulting state would be:

{
  "foo": {
    "data": 3
  },
  "bar": {
    "data": 2
  }
}

The foo state gets updated (because it has the overridable attribute), but the bar state doesn’t (because it doesn’t have the overridable attribute). The AMP doc would respond with the following message:

{
  "type": "s",
  "name": "premutate",
  "payload": {
    "updatedKeys": ["foo"],
    "ignoredKeys": ["bar"]
  }
}