amp-user-notification

描述

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

必需脚本

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

支持的布局

nodisplay

示例

新闻文章 amp-user-notification

用法

需要一个 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 (字符串): 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 语法触发。

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