在非 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 Player
Web Stories 依賴 AMP Story Player，以 <amp-story-player> 元素的形式，在非 AMP 網站上整合和播放故事。透過在文件 head 中包含以下兩個指令碼來實作 amp-story-player 元素
<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 Player 的大小
我們建議盡可能使 Web Story Player 全螢幕顯示。這可讓讀者沉浸在故事內容中，同時新增播放器提供的額外功能。新增跳至下一個控制項，以獲得最佳的桌面全螢幕體驗。
在無法全螢幕顯示的情況下，您可以像調整任何其他 HTML 元素一樣調整 Web Story Player 的大小。您可以內嵌或以任何其他元素的樣式定義故事播放器的寬度、高度和其他樣式。
<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
透過在 <amp-story-player> 元素內包含 href 屬性指向所需 Web Story URL 的 <a> 標籤，連結至 Web Story。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>
提供預留位置
透過新增 <img> 標籤作為故事 <a> 標籤的子項，並使用以下設定，以包含代表性的海報圖片。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 Story
在 <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 Player 會顯示第一個故事。在前一個故事完成後，或使用滑動手勢跳過後，它會自動向使用者呈現下一個故事的封面頁。Web Story Player 沒有任何內建 UI 功能來通知使用者單一播放器中有多個故事。相反地，建構使用者進入點以顯示可用的故事並允許使用者選擇。
循環故事包裝
您可以透過將 circular-wrapping 動作新增至 JSON 設定來建立一組故事的循環消費。當包含 circular-wrapping 時，Web Story Player 會在使用者完成最後一個故事後，向使用者顯示第一個故事。
<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 Player 中瀏覽故事。若要執行此操作，請包含 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 網址變數 ${offset} 來新增參數。Web Story Player 會將 ${offset} 替換為實際的 offset。例如，如果發布商提供 https://example.com/my-endpoint.json?offset=${offset} 且 Web Story Player 已載入 5 個故事，則它會傳送 https://example.com/my-endpoint.json?offset=5。
回應
Web Story Player 預期 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 Player UI 介面
您可以自訂 Web Story Player 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 Player 不包含關閉控制項。您可以透過指定名稱為「close」的控制項物件，將關閉圖示新增至 Web Story Player。當在以 lightbox 或全螢幕檢視顯示播放器的實作中使用播放器時，建議使用此設定。
「close」控制項支援以下可自訂屬性
position：「start」或「end」。- 在 LTR 語言中，將圖示定位在左側 ("start") 或右側 ("end")。
- 在 RTL 語言中，將圖示定位在左側 ("end") 或右側 ("start")。
visibility：「hidden」或「visible」(預設)。- 切換控制項的可見性。如果省略，則預設為可見。
backgroundImageUrl：具有網址或資料字串 (已逸出) 的字串。- 將圖示圖片變更為提供的網址或資料字串 (用於內嵌 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：具有網址或資料字串 (已逸出) 的字串。- 將圖示圖片變更為提供的網址或資料字串 (用於內嵌 svg)。
跳至下一個控制項
透過指定名稱為「skip-to-next」的控制項物件，新增一個跳至播放器內下一個故事的控制項。此功能僅在桌面上可用，因為行動使用者可以使用「滑動」手勢跳至下一個故事。
「skip-to-next」控制項支援以下可自訂屬性
position：「start」或「end」。- 在 LTR 語言中，將圖示定位在左側 ("start") 或右側 ("end")。
- 在 RTL 語言中，將圖示定位在左側 ("end") 或右側 ("start")。
visibility：「hidden」或「visible」(預設)。- 切換控制項的可見性。如果省略，則預設為可見。
backgroundImageUrl：具有網址或資料字串 (已逸出) 的字串。- 將圖示圖片變更為提供的網址或資料字串 (用於內嵌 svg)。
自訂控制項
透過指定以下必要屬性，將自訂控制項新增至 Web Story Player
- name：具有控制項名稱的字串。例如「lightbox」。發送的事件將取決於此名稱。自訂事件將是控制項名稱，並加上 amp-story-player-* 前綴。例如 amp-story-player-lightbox。
backgroundImageUrl：具有網址或資料字串 (已逸出) 的字串。- 將圖示圖片變更為提供的網址或資料字串 (用於內嵌 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 Player 互動性
您可以呼叫 Web Story Player 的方法，以程式化方式控制播放器。這些方法包括何時初始化播放器、將音訊靜音和暫停故事。
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 Player 規格中的方法清單。
互動事件
Web Story Player 會發送您可以監聽和回應的事件。使用這些事件來建立互動式體驗並追蹤分析。完整的事件清單可以在 Web Story Player 規格中找到。
在以下範例中，我們使用 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 Player 顯示您的故事，您必須透過進入點將它們介紹給您的網站使用者。以下指南將教您如何建立遵循最佳 UX 實務的進入點。