amp-geo

描述

提供近似的国家/地区级地理位置接口。

必需脚本

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

支持的布局

nodisplay

示例

amp-geo 基于地理位置的同意流程

用法

amp-geo 组件提供国家/地区级地理位置。 amp-geo 组件还提供了一种简单的机制来对国家/地区进行分组，从而可以更轻松地一次将属性应用于多个国家/地区。

amp-geo 组件使用请求来源国家/地区（以 ISO 3166-1 alpha-2 国家/地区代码的形式）。amp-geo 组件通过客户端的 IP 地址确定此代码。 ISO 国家/地区代码可能与顶级域名不同。例如，英国的代码是 gb 而不是 uk。

在 WHOIS 数据库中包含国家/地区信息的 IP 地址可能在 amp-geo 中没有国家/地区信息。如果无法确定国家/地区，则该值设置为 unknown。如果使用分组功能，则至少一个组必须包含 unknown。

amp-geo 组件提供 CSS、amp-bind 和变量替换接口。

生成的 CSS 类

如果将 amp-iso-country-XX 类应用于 body 元素，其中 XX 替换为 ISO 国家/地区代码或值 unknown，则可以使用 CSS 修改 body 元素。

在以下示例中，我们添加 <amp-geo> 以确定用户的位置，以便我们可以显示相应的标志。

<amp-geo layout="nodisplay"></amp-geo>

如果用户位于加拿大，则 amp-geo 组件会将 amp-iso-country-ca CSS 类应用于 body 标记。然后，我们可以使用 CSS 来应用加拿大的正确背景图像

/* defaults */
.flag {
  background-image: './starsandstripes.png';
}
/* override */
.amp-iso-country-ca .flag {
  background-image: './mapleleaf.png';
}

用于分组位置的可选配置

或者，您可以在 amp-geo 标记中包含 JSON 配置脚本。 ISOCountryGroups 键允许按国家/地区代码组进行选择。

<amp-geo layout="nodisplay">
  <script type="application/json">
    {
      "ISOCountryGroups": {
        "soccer": ["au", "ca", "ie", "nz", "us", "za"],
        "football": ["unknown"]
      }
    }
  </script>
</amp-geo>

如果指定了国家/地区组，则 amp-geo 会迭代这些组。对于包含当前国家/地区的任何组，会在 <body> 中添加一个名为 amp-geo-group- 的类，后跟组名称。组名称只能包含 a-z、A-Z 和 0-9，并且不能以数字开头。如果没有匹配的国家/地区组，则会在 body 中添加 amp-geo-no-group 类。

示例：生成的 CSS 类

<body class="amp-geo-group-football amp-iso-country-gb …"></body>

示例：使用 CSS 类和国家/地区组将“soccer”更改为“football”

在以下示例中，我们确定用户是否位于“足球”国家/地区，并为这些用户显示“足球”消息。

<amp-geo layout="nodisplay">
  <script type="application/json">
    {
      "ISOCountryGroups": {
        "soccer": ["au", "ca", "ie", "nz", "us", "za"],
        "football": ["unknown"]
      }
    }
  </script>
</amp-geo>

如果用户位于“足球”国家/地区之一，则会将 amp-geo-group-soccer CSS 类应用于 body 标记。

/* defaults */
.football:after {
  content: 'football';
}
/* override */
.amp-geo-group-soccer .football:after {
  content: 'soccer';
}

然后，使用 CSS 选择正确的单词（即，足球）就很简单了。

<div>The game is called <span class="football"></span>!</div>

预设国家/地区组

除了用户指定的国家/地区组之外，amp-geo 还支持预设国家/地区列表。请参阅 amp-geo-presets.js 以获取可用的预设列表。

GOOGLE 和 AMP 提供此信息是为了方便您，但不保证此处包含的任何信息的准确性或完整性。此信息按“原样”提供，不提供任何明示或暗示的担保，包括但不限于对适销性和特定用途适用性的暗示担保。

美国加利福尼亚州检测

当 amp-geo 组件确定请求来自加利福尼亚州时，它会提供 ISO 3166-2 信息。预设列表中的 preset-us-ca 值支持此功能。

其他国家/地区可以包含在预设列表中，如以下 myList 示例所示。

<amp-geo layout="nodisplay">
  <script type="application/json">
    {
      "ISOCountryGroups": {
        "eea": ["preset-eea"],
        "usca": ["preset-us-ca"],
        "myList": ["preset-eea", "preset-us-ca", "ca", "au", "nz"]
      }
    }
  </script>
</amp-geo>

美国行政区划检测

当 amp-geo 组件确定请求来自美国州或哥伦比亚特区（华盛顿特区）时，它会提供 ISO 3166-2 信息。这些值采用 ${country}-${subdivision} 格式，并且支持以下代码。

us-al - 阿拉巴马州
us-ak - 阿拉斯加州
us-az - 亚利桑那州
us-ar - 阿肯色州
us-ca - 加利福尼亚州
us-co - 科罗拉多州
us-ct - 康涅狄格州
us-de - 特拉华州
us-dc - 哥伦比亚特区
us-fl - 佛罗里达州
us-ga - 佐治亚州
us-hi - 夏威夷州
us-id - 爱达荷州
us-il - 伊利诺伊州
us-in - 印第安纳州
us-ia - 爱荷华州
us-ks - 堪萨斯州
us-ky - 肯塔基州
us-la - 路易斯安那州
us-me - 缅因州
us-md - 马里兰州
us-ma - 马萨诸塞州
us-mi - 密歇根州
us-mn - 明尼苏达州
us-ms - 密西西比州
us-mo - 密苏里州
us-mt - 蒙大拿州
us-ne - 内布拉斯加州
us-nv - 内华达州
us-nh - 新罕布什尔州
us-nj - 新泽西州
us-nm - 新墨西哥州
us-ny - 纽约州
us-nc - 北卡罗来纳州
us-nd - 北达科他州
us-oh - 俄亥俄州
us-ok - 俄克拉荷马州
us-or - 俄勒冈州
us-pa - 宾夕法尼亚州
us-ri - 罗德岛州
us-sc - 南卡罗来纳州
us-sd - 南达科他州
us-tn - 田纳西州
us-tx - 德克萨斯州
us-ut - 犹他州
us-vt - 佛蒙特州
us-va - 弗吉尼亚州
us-wa - 华盛顿州
us-wv - 西弗吉尼亚州
us-wi - 威斯康星州
us-wy - 怀俄明州

其他国家/地区/行政区划可以包含在预设列表中，如以下 usWithSubdivisions 示例所示。

<amp-geo layout="nodisplay">
  <script type="application/json">
    {
      "ISOCountryGroups": {
        "usca": ["preset-us-ca"],
        "usco":["us-co"],
        "usct":["us-ct"],
        "usva":["us-va"],
        "usWithSubdivisions": ["us-ca", "us-co", "us-ct", "us-va"]
      }
    }
  </script>
</amp-geo>

渲染阻塞

默认情况下，amp-geo 组件不会阻止渲染。也就是说，即使 amp-geo 尚未加载和执行，页面也会加载并且元素会渲染。如果某些元素在特定地理区域中永远不会渲染非常重要，请使用 amp-geo-pending 类来提供选择性渲染阻塞。发布者通过将 amp-geo-pending 添加到 <body> 元素来实现此功能。当 amp-geo 脚本加载时，它会删除 amp-geo-pending 类，同时添加 amp-iso-country... 和 amp-geo-group-... 类。

示例：要在美国始终禁止显示具有 foo 类的元素，请设置 <body class="amp-geo-pending">，并在 CSS 中包含以下内容

.amp-geo-pending .foo,
.amp-iso-country-us .foo {
  display: none;
}

此 CSS 会隐藏具有 foo 类的元素，直到 amp-geo 加载，如果国家/地区是 us，则会继续隐藏该元素。

当设置为 display: none 时，诸如 amp-ad 和 amp-iframe 之类的元素不会发出外部网络请求。

与 amp-bind 集成

如果配置中存在 AmpBind 键，则 amp-geo 会插入一个 amp-state 标记，其中包含当前国家/地区和组信息。使用上面的足球示例，将 AmpBind 标志设置为 true 以启用 amp-bind 集成。

<amp-geo layout="nodisplay">
  <script type="application/json">
    {
      "AmpBind": true,
      "ISOCountryGroups": {
        "soccer": ["au", "ca", "ie", "nz", "us", "za"],
        "football": ["unknown"]
      }
    }
  </script>
</amp-geo>

如果用户位于加拿大，则插入的 amp-state 将如下所示

<amp-state id="ampGeo">
  <script type="application/json">
    {
      "ISOCountry": "ca",
      "soccer": true
    }
  </script>
</amp-state>

变量替换

还可以通过 AMP 变量替换来获取国家/地区代码

AMP_GEO 或 ${ampGeo} 返回匹配的组列表（以逗号分隔）。AMP_GEO(ISOCountry) 或 ${ampGeo(ISOCountry)} 返回国家/地区代码（或 unknown）。

还可以通过 AMP 变量替换来获取行政区划代码

AMP_GEO 或 ${ampGeo} 返回匹配的组列表（逗号分隔）。AMP_GEO(ISOSubdivision) 或 ${ampGeo(ISOSubdivision)} 返回国家/地区细分（或 unknown）。

缓存

amp-geo JavaScript 文件提供 30 分钟的缓存生命周期 (Cache-control: private, max-age=1800)，以防止使用过时的地理位置数据，并确保当用户移动位置时地理位置的准确性。

预渲染

amp-geo 组件支持预渲染。如果文档是从发布者源提供的，并且它已经包含与 amp-iso-country-* 匹配的类，则 amp-geo 会尊重该值。amp-geo 将使用提供的国家/地区和配置向合作的 AMP 扩展（例如，amp-consent）提供数据。如果检测到预渲染的国家/地区代码，则 amp-geo 不会修改文档以添加国家/地区组或 amp-state 的类。

但是，如果文档是通过 AMP 缓存之一提供的，则 amp-geo 会删除并替换任何提供的地理位置类，并且如果 amp-bind 配置键为 true，则会相应地更新 <amp-state id="ampGeo">。这允许发布者在文档直接从其源提供时使用他们自己的地理位置代码，同时在从缓存提供时保留动态配置。

希望预渲染 amp-geo 的缓存应打开一个问题，请求从预渲染覆盖中删除。

自托管

重新托管 AMP JavaScript 文件的发布者和缓存必须实现 amp-geo-0.1.js 文件的服务器端修补或预渲染（见上文）。

从 cdn.ampproject.org 提供的文件不应用作修补的基础，因为它在下载时已经被修补。相反，应该使用基本 ./dist/v0/amp-geo-0.1.js 文件。

字符串 {{AMP_ISO_COUNTRY_HOTPATCH}} 必须在提供时替换为与请求 IP 地址对应的小写 2 字母 ISO 3166-1 alpha-2 国家/地区代码。此值应填充以匹配原始长度，以避免破坏 amp-geo-0.1.max.js.map 文件。如果无法确定国家/地区，则可以通过保留文件不修补或用等长的空格字符串修补来指示“未知”国家/地区。

调试

在文档 URL 中添加 #amp-geo=XX 会强制国家/地区显示为国家/地区 XX。这允许您在无需 VPN 连接到某个国家/地区的情况下进行测试。出于安全原因，为了防止共享地理欺骗 URL，此功能仅适用于已启用实验性频道或在本地进行测试（即，amp-geo.js 通过 amp serve 在开发模式下提供）的用户。

由于 ITP，在 Safari 中进行 DevChannel 调试可能无法正常工作。

验证

请参阅 AMP 验证器规范中的 amp-geo 规则。

需要更多帮助？

您已经阅读此文档十几次了，但它并没有真正涵盖您所有的问题？也许其他人也有同样的感觉：在 Stack Overflow 上联系他们。

前往 Stack Overflow

发现错误或缺少功能？

AMP 项目强烈鼓励您的参与和贡献！我们希望您能成为我们开源社区的持续参与者，但也欢迎您为自己特别感兴趣的问题做出一次性贡献。

前往 GitHub