在非 AMP 頁面中整合 Web Stories
Web Stories 是一種全螢幕沉浸式內容體驗，使用者可以按照自己的步調點擊或輕觸瀏覽。它們存在於開放網路中，擁有自己的 URL，因此易於分享。本指南將教您如何在非 AMP 頁面中整合 Web Stories，並將其呈現給讀者。
<!DOCTYPE html>
<html>
<head>
<script
async
src="https://cdn.ampproject.org/amp-story-player-v0.js"
></script>
<link
href="https://cdn.ampproject.org/amp-story-player-v0.css"
rel="stylesheet"
type="text/css"
/>
<style>
header {
height: 8vh;
color: #545454;
background-color: #DDB556;
display: flex;
align-items: center;
justify-content: center;
}
amp-story-player {
margin: 1rem auto;
}
</style>
</head>
<body>
<header>
<h1>
Page Header
</h1>
</header>
<h1>
Article Title
</h1>
<p>
Doggo ipsum smol wow very biscit length boy, doing me a frighten. Borking
doggo doggo heckin dat tungg tho, heckin good boys. Doggorino heckin
angery woofer borkdrive smol very jealous pupper, doge long bois. Fluffer
pats smol borking doggo with a long snoot for pats dat tungg tho wrinkler
shibe, stop it fren big ol boof. Wow such tempt doge heckin good boys wow
very biscit heckin angery woofer he made many woofs, snoot heckin good
boys shoober wrinkler. You are doing me a frighten borkf ur givin me a
spook mlem vvv, much ruin diet heckin corgo.
</p>
<amp-story-player style="width: 370px; height: 622px;">
<script type="application/json">
{
"behavior": {
"autoplay": true
}
}
</script>
<a
href="https://preview.amp.dev/documentation/examples/introduction/stories_in_amp/"
>
<img data-amp-story-player-poster-img src="https://amp.dev.org.tw/static/samples/img/story_dog2_portrait.jpg" width="370" height="622" loading="lazy">
Stories in AMP - Hello World
</a>
</amp-story-player>
<p>
Such treat big ol pupper. Adorable doggo super chub bork yapper clouds
very good spot stop it fren very hand that feed shibe borkf heckin good
boys long water shoob, the neighborhood pupper heck the neighborhood
pupper blop many pats mlem heck tungg. noodle horse. Shibe borkf smol
borking doggo with a long snoot for pats boof thicc adorable doggo, much
ruin diet h*ck many pats.
</p>
</body>
</html>
包含 Web Story 播放器
Web Stories 依賴 AMP Story Player，以 <amp-story-player> 元素的形式，在非 AMP 網站上整合和播放故事。若要實作 amp-story-player 元素，請在文件 head 中加入以下兩個腳本
<script async src="https://cdn.ampproject.org/amp-story-player-v0.js"></script>
<link href="https://cdn.ampproject.org/amp-story-player-v0.css" rel="stylesheet" type="text/css">
第一個腳本匯入 AMP Story Player 的邏輯。第二個腳本設定預設樣式。
加入每個腳本後，在文件 body 內加入一個 <amp-story-player> 元素。
<amp-story-player style="width: 370px; height: 622px;">
<a
href="https://preview.amp.dev/documentation/examples/introduction/stories_in_amp/"
>
<img data-amp-story-player-poster-img src="https://amp.dev.org.tw/static/samples/img/story_dog2_portrait.jpg" width="370" height="622" loading="lazy">
Stories in AMP - Hello World
</a>
</amp-story-player>
調整 Web Story 播放器的大小
我們建議盡可能將 Web Story 播放器設為全螢幕。這能讓讀者沉浸在故事內容中，同時增加播放器提供的額外功能。加入跳至下一個控制項以獲得最佳的桌面全螢幕體驗。
如果無法全螢幕，您可以像調整任何其他 HTML 元素一樣調整 Web Story 播放器的大小。您可以內嵌定義故事播放器的寬度、高度和其他樣式，或像定義任何其他元素的樣式一樣。
<body>
...
<amp-story-player style="width: 370px; height: 622px;">
...
</amp-story-player>
...
</body>
我們建議維持 69:116 的長寬比以獲得最佳使用者體驗，但您可以定義任何寬度和高度。
回應式調整大小
故事播放器的回應式運作方式與任何其他區塊元素相同。使用 CSS 維持寬度和高度比率，例如以下範例：html
<amp-story-player style="width: 50vw; height: 84.05vw;">
...
</amp-story-player>
顯示 Web Story
連結到 Web Story，方法是在 <amp-story-player> 元素內加入一個 <a> 標籤，並將 href 屬性指向所需的 Web Story URL。href 端點可以是託管 Web Story 的 URL 或相對路徑。將故事標題放在 <a> 標籤內。
<!DOCTYPE html>
<html>
<head>
<script
async
src="https://cdn.ampproject.org/amp-story-player-v0.js"
></script>
<link
href="https://cdn.ampproject.org/amp-story-player-v0.css"
rel="stylesheet"
type="text/css"
/>
<style>
header {
height: 8vh;
color: #545454;
background-color: #DDB556;
display: flex;
align-items: center;
justify-content: center;
}
amp-story-player {
margin: 1rem auto;
}
</style>
</head>
<body>
<header>
<h1>
Page Header
</h1>
</header>
<h1>
Article Title
</h1>
<amp-story-player style="width: 370px; height: 622px;">
<a href="https://ampfest-story-player-demo.web.app/examples/amp-story/AMPFestPlayerDemo/s3">
<img src="https://ss.makestories.io/get?story=-MHy2RL_9ZnDFYTFB2PY&version=1600916568756" loading="lazy" data-amp-story-player-poster-img width="370" height="622"></img>
</a>
</amp-story-player>
</body>
</html>
提供預留位置
加入代表性的海報圖片，方法是在故事的 <a> 標籤中加入一個 <img> 標籤作為子元素，並使用以下設定。AMP story player 會在載入完整故事時顯示此圖片。
<amp-story-player style="width: 50vw; height: 83.35vw;">
<a href="https://www.example.com/story.html">
<img src="https://www.example.com/assets/cover1.html" loading="lazy" width="100%" height="100%" data-amp-story-player-poster-img>
A title that describes this story.
</a>
</amp-story-player>
為了獲得最佳使用者體驗，我們強烈建議加入海報圖片。如果您未加入海報圖片，故事播放器將顯示一個帶有灰色背景的載入旋轉圖示。
自動播放故事
預設情況下，當播放器在使用者視窗中可見時，播放器中的第一個故事將自動開始播放。
您可以透過使用以下設定來選擇停用預設行為。這將防止播放器中的第一個故事開始播放，直到您在播放器上呼叫 play()。
<amp-story-player>
<script type="application/json">
{
"behavior": {
"autoplay": false
}
}
</script>
<a href="./story1.html"> ... </a>
<a href="./story2.html"> ... </a>
...
指定多個 Web Stories
在 <amp-story-player> 元素內加入所需數量的 <a> 標籤，並將每個 href 屬性指向所需的 Web Story URL。
<!DOCTYPE html>
<html>
<head>
<script
async
src="https://cdn.ampproject.org/amp-story-player-v0.js"
></script>
<link
href="https://cdn.ampproject.org/amp-story-player-v0.css"
rel="stylesheet"
type="text/css"
/>
<style>
header {
height: 8vh;
color: #545454;
background-color: #DDB556;
display: flex;
align-items: center;
justify-content: center;
}
amp-story-player {
margin: 1rem auto;
}
</style>
</head>
<body>
<header>
<h1>
Page Header
</h1>
</header>
<h1>
Article Title
</h1>
<amp-story-player style="width: 370px; height: 622px;">
<a href="https://ampfest-story-player-demo.web.app/examples/amp-story/AMPFestPlayerDemo/s1"></a>
<a href="https://ampfest-story-player-demo.web.app/examples/amp-story/AMPFestPlayerDemo/s2"></a>
<a href="https://ampfest-story-player-demo.web.app/examples/amp-story/AMPFestPlayerDemo/s3"></a>
</amp-story-player>
</body>
</html>
Web Story 播放器會顯示第一個故事。在完成前一個故事後，或使用滑動手勢跳過時，它會自動向使用者呈現下一個故事的封面頁。Web Story 播放器沒有任何內建 UI 功能來告知使用者單一播放器中有多個故事。相反地，請建立使用者入口點以顯示可用的故事並允許使用者選擇。
循環故事包裝
您可以透過將 circular-wrapping 動作加入 JSON 設定，來建立一組故事的循環消費。當包含 circular-wrapping 時，Web Story 播放器會在使用者完成最後一個故事後，向使用者顯示第一個故事。
<amp-story-player>
<script type="application/json">
{
"behavior": {
"on": "end",
"action": "circular-wrapping"
}
}
</script>
<a href="./story1.html"> ... </a>
<a href="./story2.html"> ... </a>
...
</amp-story-player>
JSON 設定必須是 <amp-story-player> 元素的直接子元素，並包含 type="application/json" 屬性。
個人化和無限故事
當使用者在 Web Story 播放器中瀏覽故事時，您可以建立「無限滾動」體驗。若要執行此操作，請包含 fetch 動作，並在 JSON 設定中指定端點。當使用者接近最後載入的故事時，播放器會自動擷取更多故事。您可以透過設定後端個人化系統並使用 fetch 動作來提供故事，為使用者自訂擷取的故事。
<amp-story-player>
<script type="application/json">
{
"behavior": {
"on": "end",
"action": "fetch",
"endpoint": "https://example.com/my-endpoint.json?offset=${offset}"
}
}
</script>
<a href="./story1.html"> ... </a>
<a href="./story2.html"> ... </a>
...
JSON 設定必須是 <amp-story-player> 元素的直接子元素，並包含 type="application/json" 屬性。對於分頁，請使用選用的 endpoint url 變數 ${offset} 來加入參數。Web Story 播放器會將 ${offset} 取代為實際偏移量。例如，如果發布商提供 https://example.com/my-endpoint.json?offset=${offset} 且 Web Story 播放器已載入 5 個故事，則它會傳送 https://example.com/my-endpoint.json?offset=5。
回應
Web Story 播放器預期收到一個 JSON，其中包含故事物件的陣列作為回應。
[
{
"href": "https://example.com/story3.html",
"title": "My third cool story", // optional
"posterImage": "https://example.com/assets/story3.png" // optional
},
{
"href": "https://example.com/story4.html",
"title": "My fourth cool story", // optional
"posterImage": "https://example.com/assets/story4.png" // optional
}
]
href
您的故事所在的 URL。
title (選用)
您的故事標題。
posterImage (選用)
您的故事海報圖片。
自訂 Web Story 播放器 UI
您可以自訂 Web Story 播放器 UI 的控制項。您可以加入新的控制按鈕，並變更其位置或外觀。控制項設定為 JSON，並以 type="application/json" 作為 <amp-story-player> 元素的子元素。加入所需「controls」的陣列。
<amp-story-player>
<script type="application/json">
{
"controls": [
{
"name": "close",
"position": "start"
},
{
"name": "skip-to-next"
}
]
}
</script>
<a href="./story1.html"> ... </a>
<a href="./story2.html"> ... </a>
</amp-story-player>
關閉控制項
預設情況下，Web Story 播放器不包含關閉控制項。您可以透過指定名稱為「close」的控制物件，將關閉圖示加入 Web Story 播放器。建議在以燈箱或全螢幕檢視顯示播放器的實作中使用此功能。
「close」控制項支援以下可自訂屬性
position：「start」或「end」。- 在 LTR 語言中，將圖示放在左側（「start」）或右側（「end」）。
- 在 RTL 語言中，將圖示放在左側（「end」）或右側（「start」）。
visibility：「hidden」或「visible」（預設）。- 切換控制項的顯示狀態。如果省略，則預設為顯示。
backgroundImageUrl：具有 url 或資料字串（已逸出）的字串。- 將圖示圖片變更為提供的 url 或資料字串（適用於內嵌 svg）。
當使用者按一下/輕觸關閉按鈕時，關閉按鈕會發送 amp-story-player-close 事件。
<amp-story-player>
<script type="application/json">
{
"controls": [
{
"name": "close",
"backgroundImageUrl": "data:image\/svg+xml;charset=utf-8,<\/svg>",
"position": "start"
}
]
}
</script>
<a href="./story1.html"> ... </a>
<a href="./story2.html"> ... </a>
</amp-story-player>
分享控制項
分享控制項在所有故事中都可見，但您可以自訂外觀和位置。
「share」控制項支援以下可自訂屬性
position：「start」或「end」。- 在 LTR 語言中，將圖示放在左側（「start」）或右側（「end」）。
- 在 RTL 語言中，將圖示放在左側（「end」）或右側（「start」）。
visibility：「hidden」或「visible」（預設）。- 切換控制項的顯示狀態。如果省略，則預設為顯示。
backgroundImageUrl：具有 url 或資料字串（已逸出）的字串。- 將圖示圖片變更為提供的 url 或資料字串（適用於內嵌 svg）。
跳至下一個控制項
透過指定名稱為「skip-to-next」的控制物件，加入一個可跳到播放器內下一個故事的控制項。此功能僅適用於桌面版，因為行動使用者可以使用「滑動」手勢跳到下一個故事。
「skip-to-next」控制項支援以下可自訂屬性
position：「start」或「end」。- 在 LTR 語言中，將圖示放在左側（「start」）或右側（「end」）。
- 在 RTL 語言中，將圖示放在左側（「end」）或右側（「start」）。
visibility：「hidden」或「visible」（預設）。- 切換控制項的顯示狀態。如果省略，則預設為顯示。
backgroundImageUrl：具有 url 或資料字串（已逸出）的字串。- 將圖示圖片變更為提供的 url 或資料字串（適用於內嵌 svg）。
自訂控制項
透過指定以下必要屬性，將自訂控制項加入 Web Story 播放器
- name：具有控制項名稱的字串。例如：「lightbox」。發送的事件將取決於此名稱。自訂事件將是控制項的名稱，並以 amp-story-player-* 作為前綴。例如：amp-story-player-lightbox。
backgroundImageUrl：具有 url 或資料字串（已逸出）的字串。- 將圖示圖片變更為提供的 url 或資料字串（適用於內嵌 svg）。
<script type="application/json">
{
"controls": [
{
"name": "custom-control",
"backgroundImageUrl": "data:image\/svg+xml;charset=utf-8,<\/svg>"
}
],
}
</script>
事件自訂控制項發送取決於 name 屬性。事件會以「amp-story-player-*」作為前綴，然後是自訂控制項的名稱。例如，「custom-control」會發送事件「amp-story-player-custom-control」。
const player = document.body.querySelector("amp-story-player");
// Listen to when the specified control was clicked.
player.addEventListener("amp-story-player-custom-control", () => {
// This will trigger when the control with the "custom-control" name is clicked.
performCustomAction();
});
您可以透過以下選用屬性進一步個人化自訂控制項
position：「start」或「end」。- 在 LTR 語言中，將圖示放在左側或右側。
visibility：「hidden」或「visible」（預設）。- 切換控制項的顯示狀態。如果省略，則預設為顯示。
Web Story 播放器互動性
您可以呼叫 Web Story 播放器的方法，以程式化方式控制播放器。這些方法包括何時初始化播放器、靜音音訊和暫停故事。
const playerEl = document.body.querySelector('amp-story-player');
playerEl.play()
可用的方法會在 HTML 元素上公開
const playerEl = document.querySelector('amp-story-player')
當動態建立播放器時，例如 document.createElement('amp-story-player')，您可以使用全域類別變數 AmpStoryPlayer 手動載入播放器。
const player = new AmpStoryPlayer(window, playerEl)
load()。請參閱 Web Story 播放器規格中的方法清單。
互動式事件
Web Story 播放器會發送您可以監聽和回應的事件。使用這些事件來建立互動式體驗和追蹤分析。完整的事件清單可以在 Web Story 播放器規格中找到。
在以下範例中，我們使用 page-attachment-close、page-attachment-open 和 amp-story-player-back 事件來變更頁面上不同元素的背景。
player.addEventListener('page-attachment-close', () => {
textEl.style.backgroundColor = 'blue';
})
player.addEventListener('page-attachment-open', () => {
textEl.style.backgroundColor = 'red';
})
player.addEventListener('amp-story-back', () => {
textEl.style.backgroundColor = 'green';
})
使用者入口點
現在您已讓 Web Story 播放器顯示您的故事，您必須透過入口點將它們介紹給您的網站使用者。以下指南將教您如何建立遵循最佳 UX 實務的入口點。