AMP
EN
Deutsch Français العربية Español Italiano Indonesia 日本語 한국어 Português Русский Türkçe 中文 Polski Tiếng việt

amp-user-notification

描述

向使用者顯示可關閉的通知。

 

必要指令碼

<script async custom-element="amp-user-notification" src="https://cdn.ampproject.org/v0/amp-user-notification-0.1.js"></script>

支援版面配置

用法

因為允許多個 amp-user-notification 元素，所以需要 id，而 id 用於區分它們。

透過提供在顯示通知之前和關閉通知之後調用的兩個 URL，可以針對每個使用者控制是否應顯示通知 (使用 ampUserId 值)。例如，它可能僅顯示給特定地理位置的使用者，或防止再次向先前已關閉通知的使用者顯示。如果未指定這些 URL，則將在本機查詢和/或儲存關閉狀態，以確定是否向使用者顯示通知。

若要關閉 amp-user-notification，請將 on 屬性新增至按鈕，並使用以下值方案 on="event:idOfUserNotificationElement.dismiss" (請參閱以下範例)。此使用者動作也會觸發對 data-dismiss-href URL 的 GET 請求。請非常注意瀏覽器快取 GET 回應；詳細資訊請參閱以下 data-show-if-href 章節。(我們建議在 GET URL 中新增唯一值，例如時間戳記作為查詢字串欄位)。

當頁面上有多個 amp-user-notification 元素時，一次只會顯示一個 (一旦一個被關閉，下一個就會顯示)。目前顯示通知的順序是不確定的。

<amp-user-notification
  layout="nodisplay"
  id="amp-user-notification1"
  data-show-if-href="https://foo.com/api/show-api?timestamp=TIMESTAMP"
  data-dismiss-href="https://foo.com/api/dismissed"
>
  This site uses cookies to personalize content.
  <a href="">Learn more.</a>
  <button on="tap:amp-user-notification1.dismiss">I accept</button>
</amp-user-notification>

通知會在以下情況顯示：

  1. 本機沒有使用者已關閉具有指定 ID 的通知的記錄。
  2. 當指定時，data-show-if-href 端點會傳回 { "showNotification": true }。

當通知被關閉時：

  1. AMP 會在本機儲存指定 ID 的「關閉」記錄。這將防止再次顯示通知。
  2. 當指定時，會調用 data-dismiss-href，可用於遠端建立「關閉」記錄。

JSON 欄位

  • elementId (字串)：amp-user-notification 元素上使用的 HTML ID。
  • ampUserId (字串)：此 ID 會傳遞到 data-show-if-href GET 請求 (作為查詢字串欄位) 和 data-dismiss-href POST 請求 (作為 JSON 欄位)。對於此使用者而言，此 ID 將在未來保持不變，但 AMP 中的其他請求不會傳送相同的 ID。您可以在您的端使用此 ID 來查詢/儲存使用者是否先前已關閉通知。
  • showNotification (布林值)：指示是否應顯示通知。如果為 false，則與元素相關聯的 Promise 會立即解決。

延遲用戶端 ID 生成直到通知被確認

(選填) 您可以延遲用於分析和類似目的的用戶端 ID 的生成，直到使用者確認 amp-user-notification 為止。請參閱這些文件以了解如何實作

屬性

data-show-if-href (選填)

當指定時，AMP 將使用憑證向指定的 URL 發出 CORS GET 請求，以確定是否應顯示通知。AMP 會將 elementId 和 ampUserId 查詢字串欄位附加到 data-show-if-href 屬性上提供的 href (請參閱 #1228，了解為何這是 GET 而不是 POST)。

作為避免瀏覽器快取 GET 回應值的最佳實務，您應將 TIMESTAMP URL 替換 值新增至 data-show-if-href 屬性值。您可以將其作為查詢字串欄位新增 (例如，data-show-if-href="https://foo.com/api/show-api?timestamp=TIMESTAMP")。

如果未指定 data-show-if-href 屬性，AMP 將僅檢查使用者是否已在本機「關閉」具有指定 ID 的通知。如果沒有，則會顯示通知。

如需處理 CORS 請求和回應，請參閱 AMP CORS 規格。

CORS GET 請求 查詢字串欄位：elementId、ampUserId

https://foo.com/api/show-api?timestamp=1234567890&elementId=notification1&ampUserId=cid-value

CORS GET 回應 JSON 欄位：showNotification。回應必須包含單個 JSON 物件，其中包含布林值類型的 showNotification 欄位。如果此欄位為 true，則會顯示通知，否則不會顯示。

{"showNotification": true}

data-show-if-geo

當指定時，只有當 amp-geo 國家/地區群組符合逗號分隔的國家/地區群組列表之一時，amp-user-notification 才會觸發。

在以下範例中，如果使用者位於墨西哥 (mx)，amp-geo 將傳回 nafta 國家/地區群組。nafta 在 data-show-if-geo 屬性中，因此會顯示通知。

<amp-geo layout="nodisplay">
  <script type="application/json">
    {
      "ISOCountryGroups": {
        "nafta": ["ca", "mx", "us"],
        "waldo": ["unknown"],
        "anz": ["au", "nz"]
      }
    }
  </script>
</amp-geo>

<amp-user-notification
  layout="nodisplay"
  id="amp-user-notification1"
  data-show-if-geo="nafta, anz"
  data-dismiss-href="https://example.com/api/echo/post"
>
  This notice is only shown in Canada, Mexico and USA.
  <a class="btn" on="tap:amp-user-notification1.dismiss">I accept</a>
</amp-user-notification>

data-show-if-not-geo

這與 data-show-if-geo 相反。當指定時，只有當 amp-geo 國家/地區群組與提供的列表不符時，amp-user-notification 才會觸發。

在此範例中，位於墨西哥的使用者不會觸發通知，但位於未知國家/地區 (分配到 whereIsWaldo 群組) 的使用者會觸發通知。

<amp-geo layout="nodisplay">
  <script type="application/json">
    {
      "ISOCountryGroups": {
        "nafta": ["ca", "mx", "us"],
        "whereIsWaldo": ["unknown"],
        "anz": ["au", "nz"]
      }
    }
  </script>
</amp-geo>

<amp-user-notification
  layout="nodisplay"
  id="amp-user-notification1"
  data-show-if-not-geo="anz, nafta"
  data-dismiss-href="https://example.com/api/echo/post"
>
  This notice is only shown in Canada, Mexico and USA.
  <a class="btn" on="tap:amp-user-notification1.dismiss">I accept</a>
</amp-user-notification>

只能設定一個 data-show-if-* 屬性。

data-dismiss-href (選填)

當指定時，只有在使用者明確同意後，AMP 才會向指定的 URL 發出 CORS POST 請求，傳輸 elementId 和 ampUserId。

如果未指定此屬性，AMP 在關閉時不會傳送請求，並且只會在本地儲存指定 ID 的「已關閉」旗標。

如需處理 CORS 請求和回應，請參閱 AMP CORS 規格。

POST 請求 JSON 欄位：elementId、ampUserId

如果您想避免將來顯示通知，請使用 ampUserId 欄位來儲存使用者先前已看過通知。

{"elementId": "id-of-amp-user-notification", "ampUserId": "ampUserIdString"}

POST 回應 應為 200 HTTP 程式碼，且不預期傳回任何資料。

data-persist-dismissal (選填)

預設情況下，此設定為 true。如果設定為 false，AMP 將不會記住使用者關閉通知。如果 data-show-if-href 結果為顯示通知，則通知將始終顯示。如果未提供 data-show-if-href，則通知將始終顯示。

範例 1

<amp-user-notification
  layout="nodisplay"
  id="amp-user-notification5"
  data-persist-dismissal="false"
  data-show-if-href="https://example.com/api/shouldShow?timestamp=TIMESTAMP"
  data-dismiss-href="https://example.com/api/echo/post"
>
  This notification should ALWAYS show - if shouldShow endpoint response was
  true.
  <a href="#learn-more">Learn more.</a>
  <button on="tap:amp-user-notification5.dismiss">Dismiss</button>
</amp-user-notification>

範例 2

<amp-user-notification
  layout="nodisplay"
  id="amp-user-notification6"
  data-persist-dismissal="false"
>
  This notification should ALWAYS show on every page visit.
  <a href="#learn-more">Learn more.</a>
  <button on="tap:amp-user-notification6.dismiss">Dismiss</button>
</amp-user-notification>

enctype (選填)

預設情況下，此設定為 application/json;charset=utf-8。但您可以將其設定為 application/x-www-form-urlencoded，AMP 將改用此內容類型傳送 post dismiss 請求。

<amp-user-notification
  layout="nodisplay"
  id="amp-user-notification7"
  enctype="application/x-www-form-urlencoded"
  data-persist-dismissal="false"
  data-show-if-href="https://example.com/api/shouldShow?timestamp=TIMESTAMP"
  data-dismiss-href="https://example.com/api/echo/post"
>
  This notification should ALWAYS show - if shouldShow endpoint response was
  true.
  <a href="#learn-more">Learn more.</a>
  <button on="tap:amp-user-notification7.dismiss">Dismiss</button>
</amp-user-notification>

動作

amp-user-notification 公開以下動作，您可以使用 AMP on-syntax 觸發

關閉 (預設)

關閉使用者通知。

樣式

amp-user-notification 元件應始終具有 layout=nodisplay，並且在版面配置後將為 position: fixed (預設為 bottom: 0，可以覆寫)。如果頁面有多個 amp-user-notification 元素，則通知會排隊，且僅在前一個通知被關閉時顯示。

當顯示通知時，會新增 amp-active (visibility: visible) 類別，當關閉通知時會移除。當關閉通知時，會新增 amp-hidden (visibility: hidden)。

例如，您可以掛鉤到這些類別以實現「淡入」轉場效果。

範例：不含供應商前綴

@keyframes fadeIn {
  from {
    opacity: 0;
  }
  to {
    opacity: 1;
  }
}

amp-user-notification.amp-active {
  opacity: 0;
  animation: fadeIn ease-in 1s 1 forwards;
}

驗證

請參閱 AMP 驗證器規格中的 amp-user-notification 規則。

需要更多協助嗎？

您已閱讀本文檔十幾次，但它仍然沒有涵蓋您的所有問題？也許其他人也有同樣的感受：在 Stack Overflow 上與他們聯繫。

前往 Stack Overflow
發現錯誤或缺少功能？

AMP 專案強烈鼓勵您的參與和貢獻！我們希望您能成為我們開放原始碼社群的持續參與者，但我們也歡迎針對您特別熱衷的問題做出一次性貢獻。

前往 GitHub