Important: this component does not support your currently selected format email!


Description Amp-viewer-assistance provides assistive behaviors on AMP pages facilitated by a viewer. Messages are passed between the amp-viewer-assistance extension and the external viewer as outlined below.
Availability Stable
Required Script
<script async custom-element="amp-viewer-assistance" src=""></script>
Required Element <script id="amp-viewer-assistance" type="application/json"></script>

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
Function Name Description
signIn The amp-viewer-assistance extension sends a message to the viewer to sign in expecting an identity token back.
updateActionState A function to send a message to the outer viewer representing a state change. Requires either an update or error object parameter

UpdateActionState Payloads

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

  "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"

Messages Sent

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

Message Name Description
viewerAssistanceConfig A message containing the initial json config within the amp-viewer-assistance element. This message is sent during the extension's initialization.
requestSignIn Requests for a sign in from the viewer expecting a string identity token back from the viewer. Passes a json argument with a property providers containing an array of identity providers. Currently only supports actions-on-google-gsi.
getAccessTokenPassive Similar to requestSignIn however, only requests for the identity token instead of a fresh sign in. Passes a json argument with a property providers containing an array of identity providers. Currently only supports actions-on-google-gsi.
updateActionState A message representing a change in state. Can be sent with an argument payload.

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="">
  "myConfigItem1": {
    "foo": 123,
    "bar": 456
<div id="success-message" hidden>
  Successfully Signed In!
Event Name Emitting Element Description
signedIn amp-viewer-assistance An action emitted upon a successful signIn by the external viewer.

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 id="myRemoteState" src=""

yields a POST request body:



<form id="name-form"
  <div class="form-header">Full Name</div>
  <input type="text"
      value="Default name value"/>
  <button type="submit">
    <span class="order-button-text">Submit Name</span>

yields a POST request form-data payload of:

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

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;


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="">
  "myConfigItem1": {
    "foo": 123,
    "bar": 456,
<button on="tap:amp-viewer-assistance.signIn">
  Sign In
<div id="success-message" hidden>
  Successfully Signed In!
<div id="signed-out-message">
  Signed Out!

<form id="state-change-form"
<button on="tap:state-change-form.submit">
  Change State
Need more help?

You've read this document a dozen times but it doesn't really cover all of your questions? Maybe other people felt the same: reach out to them on Stack Overflow.

Go to Stack Overflow
Found a bug or missing a feature?

The AMP project strongly encourages your participation and contributions! We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about.

Go to GitHub