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

重要事項：本文件不適用於您目前選取的格式 stories！

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。回應必須包含具有布林值類型 showNotification 欄位的單一 JSON 物件。如果此欄位為 true，則會顯示通知，否則不會顯示。

{"showNotification": true}

data-show-if-geo

當指定時，amp-user-notification 僅會在 amp-geo 國家/地區群組符合逗號分隔的國家/地區群組清單之一時觸發。

在以下範例中，如果使用者位於墨西哥 (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-user-notification 僅會在 amp-geo 國家/地區群組與提供的清單不符時觸發。

在此範例中，墨西哥的使用者不會觸發通知，但位於不明國家/地區 (指派給 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 欄位來儲存使用者先前已看過通知。它與未來請求傳遞至 data-show-if-href 的值相同。

{"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 來觸發

dismiss (預設)

關閉使用者通知。

樣式設定

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