amp-viewer-assistance

Supported Functions

The amp-viewer-assistance extension currently has two functions that can be invoked via AMP expressions. For example, you may invoke the signIn function on a button tap:

<button on="tap:amp-viewer-assistance.signIn">
  Sign In
</button>

UpdateActionState Payloads

A valid amp-viewer-assistance.updateActionState payload can either be an update object of the format:

{
  "actionStatus": "COMPLETED_ACTION_STATUS" | "ACTIVE_ACTION_STATUS" | "FAILED_ACTION_STATUS",
  "result": { ... }, // optional field used with COMPLETED_ACTION_STATUS
}

or an error standard Response object.

Handling Errors

In the event of an error with the amp-list extension, we can listen to the fetch-error event and call amp-viewer-assistance.updateActionState to pass the error to the viewer. With an error parameter, amp-viewer-assistance will transform the parameter into a FAILED_ACTION_STATUS payload before sending it to the viewer.

<amp-list
  id="my-failing-list"
  src="failing.xhr.address.com"
  on="fetch-error:amp-viewer-assistance.updateActionState(error=event.response)"
>
</amp-list>

Messages Sent

There are several messages that can be sent from the amp-viewer-assistance extension to the external viewer.

Events Triggered

In order to act upon a successful sign in from the viewer assistance, a signedIn event is emitted from the amp-viewer-assistance script element. On the element, an expression can be attached via the on attribute. In this example, we are showing a success message after a user has signed in:

<script
  id="amp-viewer-assistance"
  type="application/json"
  on="signedIn:success-message.show"
>
  {
    "myConfigItem1": {
      "foo": 123,
      "bar": 456
    }
  }
</script>
<div id="success-message" hidden>
  Successfully Signed In!
</div>

Utilizing an Identity Token

Given a viewer with identity capabilities, the amp-viewer-assistance extension can pass an identity token back to the amphtml run-time to attach to remote XHRs. To attach the identity token to a remote XHR request in an amp-state, amp-list, or amp-form element, simply attach the attribute crossorigin="amp-viewer-auth-token-via-post" to the performing element. The request will be transformed into a POST request, and within the request body will be an ampViewerAuthToken variable set to the authorization token from the viewer.

Here are some examples:

amp-state:

<amp-state
  id="myRemoteState"
  src="https://data.com/articles.json"
  crossorigin="”amp-viewer-auth-token-via-post”"
>
</amp-state>

yields a POST request body:

ampViewerAuthToken=AUTH_TOKEN_FROM_VIEWER_ASSISTANCE

amp-form:

<form
  id="name-form"
  method="post"
  target="_top"
  action-xhr="https://data.com/formsubmit"
  crossorigin="amp-viewer-auth-token-via-post"
>
  <div class="form-header">Full Name</div>
  <input type="text" name="name" value="Default name value" />
  <button type="submit">
    <span class="order-button-text">Submit Name</span>
  </button>
</form>

yields a POST request form-data payload of:

--------formDataBoundary--------
Content Disposition: form-data; name="name"
Default name value
--------formDataBoundary--------
Content Disposition: form-data; name="ampViewerAuthToken"
AUTH_TOKEN_FROM_VIEWER_ASSISTANCE

Identity Class

Upon a successful sign in or identity token retrieval from the viewer, an amp-viewer-assistance-identity-available class will be attached to the root element of the AMP document. This can be used to manipulate elements with compound CSS classes.

In this example, we have a message telling the user they are signed out. If the identity is available through the extension, the message's display attribute will be overwritten to display:none.

.signedOutMessage {
  display: block;
}

.amp-viewer-assistance-identity-available .signedOutMessage {
  display: none;
}

Example

Wrapping up the above, here is an example implementation of a page utilizing sign in, as well as an updateActionState after a form submission.

<script
  id="amp-viewer-assistance"
  type="application/json"
  on="signedIn:success-message.show"
>
  {
    "myConfigItem1": {
      "foo": 123,
      "bar": 456,
    },
  }
</script>
<button on="tap:amp-viewer-assistance.signIn">
  Sign In
</button>
<div id="success-message" hidden>
  Successfully Signed In!
</div>
<div id="signed-out-message">
  Signed Out!
</div>

<form
  id="state-change-form"
  method="POST"
  action-xhr="myAuthorizedRemoteXHR/endpoint"
  crossorigin="amp-viewer-auth-token-via-post"
  on="submit-success:amp-viewer-assistance.updateActionState(update=event.response)"
></form>
<button on="tap:state-change-form.submit">
  Change State
</button>