AMP
繁體中文
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 回應值，最佳做法是在 data-show-if-href 屬性值中新增 TIMESTAMP URL 替換 值。您可以將其新增為查詢字串欄位 (例如，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-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 欄位來儲存使用者先前已看過通知的資訊。此值與未來傳遞至 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 關閉要求。

<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