Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

📖 Interactive docs first final version #30594

Merged
merged 23 commits into from
Nov 3, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
fe3dc8a
Add documentation for interactives
mszylkowski Sep 23, 2020
ecb8066
Sourcecode to triple ticks
mszylkowski Sep 23, 2020
5f5c562
Upload images and docs
mszylkowski Sep 24, 2020
af8ae2d
Add results image
mszylkowski Sep 24, 2020
a05a74f
Uploaded latest changes to interactive docs
mszylkowski Sep 24, 2020
dfcaa72
Added changes to interactive docs
mszylkowski Sep 25, 2020
b42afd0
Started fixing comments
mszylkowski Sep 29, 2020
031e639
Added backticks to attributes
mszylkowski Sep 29, 2020
9d0ece4
Update extensions/amp-story-interactive/amp-story-interactive.md
mszylkowski Sep 29, 2020
22dcd0e
Update extensions/amp-story-interactive/amp-story-interactive.md
mszylkowski Sep 29, 2020
6d0b790
Updated documentation
mszylkowski Sep 29, 2020
d2e5685
Merge branch 'interactive_docs' of github.com:mszylkowski/amphtml int…
mszylkowski Sep 29, 2020
6018154
Updated documentation
mszylkowski Sep 29, 2020
f9323bb
Updated link
mszylkowski Sep 29, 2020
352fa93
Apply suggestions from code review
mszylkowski Oct 5, 2020
9ecad78
Code suggestions
mszylkowski Oct 5, 2020
b511702
Merge branch 'interactive_docs' of github.com:mszylkowski/amphtml int…
mszylkowski Oct 5, 2020
439a288
Apply suggestions from code review
mszylkowski Oct 7, 2020
508c43a
Updated documentation
mszylkowski Oct 9, 2020
e369771
Merge branch 'interactive_docs' of github.com:mszylkowski/amphtml int…
mszylkowski Oct 9, 2020
5a665f3
Merge branch 'master' of github.com:ampproject/amphtml into interacti…
mszylkowski Oct 9, 2020
9e381c9
Updated documentation
mszylkowski Nov 2, 2020
04be526
Switched backend url for backend.com
mszylkowski Nov 3, 2020
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 6 additions & 19 deletions extensions/amp-story-interactive/README.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
# Interactive components

### Developer preview - August 2020

## Summary

The interactive components extension provides story creators with a set of interactive experiences they can use to make stories more engaging.

A more complete version of this document can be found in [amp.dev](https://amp.dev/documentation/components/amp-story-interactive/?format=stories).

<table>
<tr>
<td><img src="https://user-images.githubusercontent.com/22420856/89562666-4e0bc480-d7e8-11ea-8897-372a24b6fb8b.png"></td>
Expand All @@ -12,19 +14,6 @@
</tr>
</table>

This release contains the developer documentation for some of the features we plan to launch on the interactive components extension for web stories in September. All the APIs are final unless noted otherwise, but more functionality will be added in the following weeks. The goal of this beta preview is to flush out any inconsistencies or bugs, and polish the behaviors.

This developer preview update covers:

- Details on the new quiz and poll components, as well as quiz and category results
- Code examples to show proper configuration
- API to support a backend and integration details
- Fully functional example Stories demonstrating good usage of these components
- Additional demos for the variety of styling and customization options
- Examples for how you can easily integrate these components into WYSIWYG editors and tools
- Additional explorations and roadmap
- FAQs (please feel free to reach out with other questions & thoughts)

## List of interactive components

<table>
Expand All @@ -46,16 +35,14 @@ This developer preview update covers:
<tr>
<td>
<strong>amp-story-interactive-results</strong>
<br><br>Component that can display 2-4 different states/categories depending on the options selected on the previous pages of a story.<br><br>Requires polls or quizzes in previous pages to feed into the state of the component, and the state will be calculated following the strategy specified: correctness, category-voting, etc.<br><br>Note: we're still finalizing the design for the component, check status of <a href="https://github.com/ampproject/amphtml/pull/29837">#29837</a<</td>
<br><br>Component that can display 2-4 different states/categories depending on the options selected on the previous pages of a story.<br><br>Requires polls or quizzes in previous pages to feed into the state of the component, and the state will be calculated following the strategy specified: correctness, category-voting, etc.</td>
<td><img src="https://user-images.githubusercontent.com/22420856/89945317-2b661b00-dbef-11ea-9319-e36bede95460.png"></td>
</tr>
</table>

## Environment setup

Optional: Most things covered here will work out of the box, but be sure to activate the nightly releases for any bug fixes and latest updates to the codebase. In order to run the nightly version of AMP on your machine, go to the [AMP Experiments](https://cdn.ampproject.org/experiments.html) and enable the nightly release.

Also add the following import to your AMP documents:
Add the following import to your AMP documents:

```html
<script
Expand Down
32 changes: 12 additions & 20 deletions extensions/amp-story-interactive/amp-story-interactive.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ formats:
teaser:
text: A rich set of interactive experiences for stories, including quizzes, polls and results.
draft:
- true
- false
tags:
- dynamic-content
- social
Expand All @@ -28,14 +28,12 @@ See the License for the specific language governing permissions and
limitations under the License.
-->

[tip type="important"]Change image sources to ampproject/amphtml/master!!![/tip]

The `amp-story-interactive` component provides a set of experiences, such as quizzes or polls, in [Web Stories](https://amp.dev/documentation/guides-and-tutorials/start/create_successful_stories/?format=stories).

<div layout="container" width="3" height="2">
<div style="width:32%;display:inline-block"><amp-img src="https://github.com/mszylkowski/amphtml/raw/interactive_docs/extensions/amp-story-interactive/img/quiz-art.png" layout="responsive" width="200" height="350"/></div>
<div style="width:32%;display:inline-block"><amp-img src="https://github.com/mszylkowski/amphtml/raw/interactive_docs/extensions/amp-story-interactive/img/animal-poll.png" layout="responsive" width="200" height="350"/></div>
<div style="width:32%;display:inline-block"><amp-img src="https://github.com/mszylkowski/amphtml/raw/interactive_docs/extensions/amp-story-interactive/img/results-art.png" layout="responsive" width="200" height="350"/></div>
<div style="width:32%;display:inline-block"><amp-img src="https://github.com/ampproject/amphtml/raw/master/extensions/amp-story-interactive/img/quiz-art.png" layout="responsive" width="200" height="350"/></div>
<div style="width:32%;display:inline-block"><amp-img src="https://github.com/ampproject/amphtml/raw/master/extensions/amp-story-interactive/img/animal-poll.png" layout="responsive" width="200" height="350"/></div>
<div style="width:32%;display:inline-block"><amp-img src="https://github.com/ampproject/amphtml/raw/master/extensions/amp-story-interactive/img/results-art.png" layout="responsive" width="200" height="350"/></div>
</div>

## Usage
Expand All @@ -52,12 +50,12 @@ The `amp-story-interactive-binary-poll` element provides a two option voting use

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

<amp-img src="https://github.com/mszylkowski/amphtml/raw/interactive_docs/extensions/amp-story-interactive/img/binary-poll-raw.png" layout="intrinsic" width="400" height="230">
<amp-img src="https://github.com/ampproject/amphtml/raw/master/extensions/amp-story-interactive/img/binary-poll-raw.png" layout="intrinsic" width="400" height="230">

```html
<amp-story-interactive-binary-poll
id="pizza-binary-poll"
endpoint="https://endpoint.com/v1/interactives"
endpoint="https://backend.com/v1/interactives"
prompt-text="Like Pizza?"
option-1-text="Yes"
option-1-confetti="🍕"
Expand All @@ -73,13 +71,13 @@ The `amp-story-interactive-poll` element provides a voting experience with 2-4 o

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-img src="https://github.com/mszylkowski/amphtml/raw/interactive_docs/extensions/amp-story-interactive/img/poll-raw.png" layout="intrinsic" width="400" height="450">
<amp-img src="https://github.com/ampproject/amphtml/raw/master/extensions/amp-story-interactive/img/poll-raw.png" layout="intrinsic" width="400" height="450">

[sourcecode:html]
<amp-story-interactive-poll
id="season-poll"
theme="dark"
endpoint="https://endpoint.com/v1/interactives"
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="☀️"
Expand All @@ -94,12 +92,12 @@ The `amp-story-interactive-quiz` element provides a guessing experience with 2-4

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-img src="https://github.com/mszylkowski/amphtml/raw/interactive_docs/extensions/amp-story-interactive/img/quiz-raw.png" layout="intrinsic" width="400" height="450">
<amp-img src="https://github.com/ampproject/amphtml/raw/master/extensions/amp-story-interactive/img/quiz-raw.png" layout="intrinsic" width="400" height="450">

[sourcecode:html]
<amp-story-interactive-quiz
id="arts-quiz"
endpoint="https://endpoint.com/v1/interactives"
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="🎨"
Expand All @@ -116,7 +114,7 @@ Each category specifies its content `option-{1/2/3/4}-{text/image/results-catego

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-img src="https://github.com/mszylkowski/amphtml/raw/interactive_docs/extensions/amp-story-interactive/img/results-raw.png" layout="intrinsic" width="400" height="500">
<amp-img src="https://github.com/ampproject/amphtml/raw/master/extensions/amp-story-interactive/img/results-raw.png" layout="intrinsic" width="400" height="500">

[sourcecode:html]
<amp-story-interactive-results
Expand Down Expand Up @@ -167,13 +165,7 @@ POST_BODY = {'option_selected': 1}
Response: No response necessary
[/sourcecode]

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

- Google hosted: _coming soon_

[tip type="note"]
Before setting up a backend, consider if the already existing backends satisfy your requirements.
[/tip]
Backends need to be specified on the necessary components (binary-poll, poll, quiz), and can be deployed by publishers, tools or others.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In a separate PR, can we work on providing some very simple documentation on what the JSON API looks like for people to build a backend?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sunds good


## Attributes

Expand Down