">文档：<amp-user-notification> - amp.dev - AMP 框架
AMP
EN
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>

支持的布局

用法

需要一个 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>

在以下情况下显示通知

  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 生成，直至通知得到确认

另外，您可以在用户确认 amp-user-notification 之前延迟生成用于分析和类似用途的客户端 ID。请参阅这些文档了解如何实现此功能

属性

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 将使用此内容类型发送关闭后请求。

<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