在非 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 網站上整合和播放故事。透過在您文件的 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 的邏輯。第二個指令碼設定預設樣式。
加入每個指令碼後，在文件主體內加入 <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
透過在 <amp-story-player> 元素中加入一個 <a> 標記，並將 href 屬性指向所需的 Web Story URL 來連結至 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 播放器會顯示第一個故事。在完成前一個故事後，或使用滑動手勢跳過後，它會自動向使用者呈現下一個故事的封面頁。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> 元素的子項。加入所需「控制項」的陣列。
<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 實務的進入點。