AMP

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

amp-viewer-assistance

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="https://cdn.ampproject.org/v0/amp-viewer-assistance-0.1.js"></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
</button>
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:

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

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="signedIn:success-message.show">
{
  "myConfigItem1": {
    "foo": 123,
    "bar": 456
  }
}
</script>
<div id="success-message" hidden>
  Successfully Signed In!
</div>
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:

<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>
需要更多帮助?

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