Do you build things with AMP? Fill out the AMP Developer Survey!
AMP

amp-story-interactive

Description

A rich set of interactive experiences for stories, including quizzes, polls and results.

Required Scripts

<script async custom-element="amp-story-interactive" src="https://cdn.ampproject.org/v0/amp-story-interactive-0.1.js"></script>

The amp-story-interactive component provides a set of experiences, such as quizzes or polls, in Web Stories.

Usage

The amp-story-interactive component encompasses a set of interactive experiences. Specify an interactive experience by defining one of the elements below. For best results, only use one element per amp-story-page.

Most elements require a backend endpoint that will store aggregate data for each interactive, as well as persist the selected option for a user across sessions. Elements will fetch the percentage of votes for each option as well as the user selection (if any) from this endpoint, and display it with the options after the user has selected one.

To see all the components in action, check out the example story.

amp-story-interactive-binary-poll

The amp-story-interactive-binary-poll element provides a two option voting user interface. Users may select one of two valid options. When selected, the highlighted option fills the container and displays the total percentage of votes.

Does not support pairing with amp-story-interactive-results, and can optionally have a prompt.

<amp-story-interactive-binary-poll
  id="pizza-binary-poll"
  endpoint="https://backend.com/v1/interactives"
  prompt-text="Like Pizza?"
  option-1-text="Yes"
  option-1-confetti="🍕"
  option-2-text="No"
  option-2-confetti="🤢"
>
</amp-story-interactive-binary-poll>

amp-story-interactive-poll

The amp-story-interactive-poll element provides a voting experience with 2-4 options displayed vertically, where all options are valid. When selected, each option displays the total percentage of votes.

Display different categories based on user poll answers by pairing amp-story-interactive-poll with amp-story-interactive-results. Add a prompt for extra context.

<amp-story-interactive-poll
    id="season-poll"
    theme="dark"
    endpoint="https://backend.com/v1/interactives"
    prompt-text="Pick a season"
    option-1-text="Spring" option-1-confetti="🌼"
    option-2-text="Summer" option-2-confetti="☀️"
    option-3-text="Fall" option-3-confetti="🍁"
    option-4-text="Winter" option-4-confetti="☃️">
</amp-story-interactive-poll>

amp-story-interactive-quiz

The amp-story-interactive-quiz element provides a guessing experience with 2-4 options, one of which is correct. It displays the voting percentages after the user makes a selection. The user selection is green if correct and red if incorrect.

Display different categories based on percentage of correct user answers by pairing amp-story-interactive-quiz with amp-story-interactive-results. Add a prompt for extra context.

<amp-story-interactive-quiz
    id="arts-quiz"
    endpoint="https://backend.com/v1/interactives"
    prompt-text='Who was the artist that created the famous painting "The Last Supper"?'
    option-1-text="Michelangelo"
    option-2-text="Leonardo da Vinci" option-2-correct option-2-confetti="🎨"
    option-3-text="Rahael"
    option-4-text="Sandro Boticelli">
</amp-story-interactive-quiz>

amp-story-interactive-results

The amp-story-interactive-result element displays a customized state defined by the user's selection from previous polls or quizzes. This element requires use of polls or quizzes from previous pages to calculate an answer-based state. Each result category may include an image, title and description to display to the user.

Each category specifies its content option-{1/2/3/4}-{text/image/results-category} attributes, where -results-category refers to the name of the category, -image refers to the image that will be displayed if that category is selected, and -text refers to the description.

Results can feed its state from quizzes if all categories also specify option-{1/2/3/4}-results-threshold. If no categories have thresholds, the state will count the option-{1/2/3/4}-results-category from options selected in polls.

<amp-story-interactive-results
    theme="dark"
    prompt-text="You are a"
    option-1-results-category="Dog" option-1-image="dog.png"
    option-1-text="You always have energy and love being with friends. Outdoors is your favorite place"
    option-2-results-category="Cat" option-2-image="cat.png"
    option-2-text="Cats are great animals for WFH">
</amp-story-interactive-results>

Store and display user selection

All selectable interactive elements (amp-story-interactive-binary-poll, amp-story-interactive-poll, amp-story-interactive-quiz) show the percentage of users that selected each option. The backend specified with the endpoint attribute will store the aggregate data for the interaction following the API described below. To fetch the data for an interactive element, the necessary fields are:

  • interactiveId: the base64encode(CANONICAL_URL) + "+" + element.id
  • interactiveType: enum from amp-story-interactive-abstract:48
  • endpoint: the attribute element.getAttribute("endpoint")
  • ampId: client ID that identifies the session, optional

Then, the requests and responses are:

// Getting the votes for an interactive.
// If no client param, selected will always be false
// (can be used to display the results on a dashboard).

GET_URL = "{endpoint}/{interactiveId}?type={interactiveType}&client={ampId}"

Response: {
"options": [
{"index": 0, "selected": false, "count": 0},
{"index": 1, "selected": false, "count": 5},
{"index": 2, "selected": false, "count": 7},
{"index": 3, "selected": false, "count": 2}
]
}
// Posting the vote for an interactive. Client param is required.

POST_URL = "{endpoint}/{interactiveId}:vote?type={interactiveType}&client={ampId}"
POST_BODY = {'option_selected': 1}

Response: No response necessary

Backends need to be specified on the necessary components (binary-poll, poll, quiz), and can be deployed by publishers, tools or others.

Attributes

The interactive experience elements from amp-story-interactive share an API language for customizing options.

id (required for binary-poll, poll, quiz)

Element ID that identifies the interactive component in the story. Used to compose the interactiveId sent to the backend. Should be unique for each component in the story.

endpoint (required for binary-poll, poll, quiz)

Complete URL of backend. Stores interactive element votes.

theme (optional)

Controls the color of the chips and text. Can be light (default), dark.

chip-style (optional for poll, quiz, results)

Controls the style of the component. Can be flat (default), shadow, or transparent. Results and binary-poll elements don't support shadow.

prompt-text (optional)

Adds a prompt to the top of the component. Use prompt-text to write the poll/quiz question, or as a prefix to the category in the amp-story-interactive-result element.

prompt-size (optional for binary-poll, poll, quiz)

Controls the font-size of prompt text. Can be small, medium (default), large. Large prompts will hold up to 3 lines of text, other sizes will hold up to 4 lines of text.

This attribute does not apply styling to amp-story-interactive-result category prefix text.

option-{1/2/3/4}-text (required)

String that represents a numbered option. Binary polls require 2 options. Polls and quizzes may include between 2 and 4 options.

The amp-story-interactive-result element uses this string value as category description.

option-{1/2/3/4}-confetti (optional for binary-poll, poll, quiz)

Emoji that bursts in an explosion animation when selecting an options. On quizzes, only the correct option should have a confetti.

option-{1/2/3/4}-results-category (optional for poll, required for results)

The name of the category on the amp-story-interactive-results element. Shows in large text after the prompt-text and before the category description. It displays category with the most options selected in polls from the entire story if option-{1/2/3/4}-results-threshold is not defined.

On polls it links the options to the result with that name as mentioned above. The string has to match perfectly for the options to link.

Example:

<amp-story-interactive-poll
    prompt-text="What's your favorite food"
    endpoint="https://backend.com/v1/interactives"
    option-1-results-category="Bunny" option-1-text="Carrots"
    option-2-results-category="Dog" option-2-text="Bones"
    option-3-results-category="Cat" option-3-text="Fish">
</amp-story-interactive-poll>

<!-- Each option in the poll above will count towards a category in the result's state, linked using the `option-{1/2/3/4}-results-category` attribute. Stories should have many polls with linked categories, but in this example we only show one. -->

<amp-story-interactive-results
    prompt-text="You are a"
    option-1-results-category="Dog" option-1-image="dog.png"
    option-2-results-category="Cat" option-2-image="cat.png"
    option-3-results-category="Bunny" option-3-image="bunny.png">
</amp-story-interactive-results>

option-{1/2/3/4}-results-threshold (optional for results)

Determines the lower boundary for the amp-story-interactive-results category when linked to quiz elements. The component calculates a score from a percentage (between 0 and 100) of questions answered correctly. It displays the category that is lower or equal to the score. If all thresholds are higher than the score, it displays the category with the lowest score. If a threshold is present for any option, all other options also need a threshold.

Example:

<!-- State is "beginner" if less than 80% of the quizzes were correct, state is "expert" otherwise. -->

<amp-story-interactive-results
    prompt-text="Your level is"
    option-1-results-category="Beginner" option-1-image="beginner.png"
    option-1-results-threshold="0"
    option-2-results-category="Expert" option-2-image="expert.png"
    option-2-results-threshold="80">
</amp-story-interactive-results>

Styling

View all theming options in action in the example story.

View and play with amp-story-interactive elements and styles in this Codepen collection!

CSS Variables

Style all amp-story-interactive elements with CSS variables and attributes. Override default variables by assigning a class to the element.

  • --interactive-accent-color: The accent color of the component.
  • --interactive-prompt-text-color: Color of the top text where applicable (elements with prompts or results with thresholds).
  • --interactive-prompt-background: Background of the top text where applicable (elements with prompts or results with thresholds but no images). Can be a color (including transparent) or CSS gradient.
  • --interactive-prompt-alignment: Alignment of the prompt where applicable (elements with prompts). Will default to center if the component has the transparent style or if it's a binary poll, otherwise it will default to initial.

Themes

The theme attribute controls the chip color and text color of the component. Can be light (default) or dark. The chip-style attribute controls the style details of the component. Can be flat (default), shadow or transparent.

Sizing

All amp-story-interactive elements use the container layout, so the width can be manipulated but the height is automatically computed. You may override the font-size on the element to any value in rems, ems, or other units, and the element will scale accordingly. You may override the width to any value between the max and min widths (explained below) using CSS to update the element's aspect ratio.

The default font-size is 3*var(--story-page-vmin) so that elements take 75% of the width of portrait stories, independently of the screen size.

The amp-story-interactive-poll and amp-story-interactive-quiz elements have a min-width: 14em and max-width: 25em. The amp-story-interactive-binary-poll and amp-story-interactive-results have a min-width: 14em and max-width: 18em.

Sizing within amp-story-grid-layer[aspect-ratio]

It's possible to use the aspect-ratio layer in order to create layouts that will scale perfectly with different screen sizes, by setting the font-size in ems or % on the component. Users should not use pixels and they don't scale accordingly with different screen sizes.

The width can be set either in ems or percentages of the parent width, and it will behave perfectly consistent (while keeping it between the min and max widths).

<amp-story-grid-layer template="fill" aspect-ratio="400:600">

  <div class="center-quiz">
    <amp-story-interactive-quiz
      style="font-size:0.2em"
      ...>
    </amp-story-interactive-quiz>
  </div>
</amp-story-grid-layer>

Adaptive font sizes for options

Polls and binary polls can adapt their font-sizes according to the content types. Depending on the number of lines that they have for the option text, they can increase or decrease the font size. The font-size will default to the largest possible that accommodates all the texts measured. For instance, if one of the options requires a small font-size (because it has a lot of text) but the other options don't, all the involved text elements will use a small font-size. Note that this only optimizes the content of the options to fit better, but they don't change the inherent size of the elements.

Binary polls only on post-selection will show different font-sizes for the options. They will hold a large font-size if all the options are either emojis or have short texts (length <= 3). The element will use medium font-size if at least one of the options are longer than 3 characters but both can be displayed in one line; and small font-size if at least one option has two lines.

Polls will also adapt the font-size of the options depending on the content. If all the options fit in one line, they will use a large font-size. If any of the options require 2 lines, all the options will reduce in size to accommodate the option text in the chip.

For a live demo, check out the binary-poll and poll Codepens, and change the option texts (be sure to select "Answered" on the binary-poll demo to see the size change).

Animations

Enhance interactivity by adding an animation to the element when entering the page or when transitioning from option selection to data display. Pick from the amp-story animations and add the animate-in attribute to desired elements.

Analytics

The amp-story-interactive component elements support amp-analytics. Report a selected option by adding the story-interactive event to your configuration:

  • storyInteractiveId: the element id
  • storyInteractiveResponse: the option selected
  • storyInteractiveType: the enum InteractiveType
<amp-analytics id="my-analytics">
  <script type="application/json">
    {
      "requests": {
        "interactive": "https://example.com/interactive?id=${storyInteractiveId}&response=${storyInteractiveResponse}"
      },
      "triggers": {
        "interactiveSelected": {
          "on": "story-interactive",
          "request": "interactive"
        }
      }
    }
  </script>
</amp-analytics>

Validation

See validation rules in amp-story-interactive validator.

需要更多帮助?

您已多次阅读本文档,但它仍未能涵盖您的所有问题?也许其他人也这么觉得:在 Stack Overflow 上与他们联系。

前往 Stack Overflow
发现错误或缺少功能?

AMP 项目强烈鼓励您参与并做出贡献!我们希望您能成为我们开放源代码社区的持续参与者,但我们也欢迎您对所热衷问题做出一次性贡献。

前往 GitHub