重要提示：此文档不适用于您当前选择的 ads 格式！

amp-user-notification

描述

向用户显示可关闭的通知。

必需的脚本

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

支持的布局

nodisplay

用法

需要 id，因为允许多个 amp-user-notification 元素，并且 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>

在以下情况下会显示通知

本地没有用户已使用指定的 ID 关闭通知的记录。
指定时，data-show-if-href 端点会返回 { "showNotification": true }。

关闭通知后

AMP 会在本地存储指定 ID 的“关闭”记录。这将阻止再次显示通知。
指定时，会调用 data-dismiss-href，并且可用于远程创建“关闭”记录。

JSON 字段

elementId (string): 在 amp-user-notification 元素上使用的 HTML ID。
ampUserId (string): 此 ID 会传递到 data-show-if-href GET 请求（作为查询字符串字段）和 data-dismiss-href POST 请求（作为 json 字段）。对于该用户而言，该 ID 将来会保持相同，但 AMP 中的其他任何请求都不会发送相同的 ID。您可以使用该 ID 在您这边查找/存储用户之前是否已关闭该通知。
showNotification (boolean)：指示是否应显示通知。如果为 false，则会立即解析与该元素关联的 Promise。

延迟客户端 ID 生成，直到确认通知

（可选）您可以延迟生成用于分析和类似用途的客户端 ID，直到用户确认 amp-user-notification。有关如何实现此操作，请参阅这些文档

属性

data-show-if-href（可选）

指定时，AMP 将使用凭据对指定的 URL 进行 CORS GET 请求，以确定是否应显示通知。AMP 会将 elementId 和 ampUserId 查询字符串字段附加到 data-show-if-href 属性上提供的 href（有关为什么这是 GET 而不是 POST，请参阅 #1228）。

作为一种最佳实践，为防止浏览器缓存 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。响应必须包含一个 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 字段存储用户之前已看到该通知。它与将来发送到 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 语法触发这些操作

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