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>

支持的布局

用法

由于允许多个 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，则会立即解析与该元素关联的承诺。

延迟客户端 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 dismiss 请求。

<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