在非 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>

在 playground 中開啟此程式碼片段

包含 Web Story 播放器

Web Stories 依賴 AMP Story Player，以 <amp-story-player> 元素的形式，在非 AMP 網站上整合和播放故事。透過在文件標頭中包含以下兩個腳本來實作 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 播放器設為全螢幕。這可以讓讀者沉浸在故事內容中，同時增加播放器提供的額外功能。新增跳至下一個控制項，以獲得最佳的桌面全螢幕體驗。

查看 lightbox Web Story 播放器 codepen，以取得關於如何建立沉浸式 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>

在 playground 中開啟此程式碼片段

提供預留位置

透過新增 <img> 標籤作為故事 <a> 標籤的子元素，並使用以下設定來包含代表性的海報圖像。AMP story 播放器會在載入完整故事時顯示此圖像。

<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>

在 playground 中開啟此程式碼片段

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 語言中，將圖示定位在左側（「開始」）或右側（「結束」）。
- 在 RTL 語言中，將圖示定位在左側（「結束」）或右側（「開始」）。
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 語言中，將圖示定位在左側（「開始」）或右側（「結束」）。
- 在 RTL 語言中，將圖示定位在左側（「結束」）或右側（「開始」）。
visibility：「hidden」或「visible」（預設）。
- 切換控制項的能見度。如果省略，預設為可見。
backgroundImageUrl：具有 url 或資料字串（已逸出）的字串。
- 將圖示圖像變更為提供的 URL 或資料字串（適用於內嵌 svg）。

透過指定具有「skip-to-next」名稱的控制項物件，新增一個控制項，可跳至播放器內的下一個故事。此功能僅在桌面上可用，因為行動使用者可以使用「滑動」手勢跳至下一個故事。

「skip-to-next」控制項支援以下可自訂屬性

position：「start」或「end」。
- 在 LTR 語言中，將圖示定位在左側（「開始」）或右側（「結束」）。
- 在 RTL 語言中，將圖示定位在左側（「結束」）或右側（「開始」）。
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() 之前連接到 DOM。

請參閱 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 實務的進入點。