amp-user-notification

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

用法

`id` 為必填，因為允許多個 `amp-user-notification` 元素，且 `id` 用於區分它們。

透過提供兩個 URL，在顯示通知之前和關閉通知之後會呼叫這兩個 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` 為止。請參閱這些文件以瞭解如何實作此功能

• CLIENT_ID URL 替換
• amp-ad
• amp-analytics

屬性

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 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 的「已關閉」旗標。

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` 規則。