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 元件使用請求來源國家/地區，格式為 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 會逐一查看這些群組。對於包含目前國家/地區的任何群組，系統都會將名為 amp-geo-group- 後接群組名稱的類別新增至 <body>。群組名稱只能包含 a-z、A-Z 和 0-9，且不得以數字開頭。如果沒有符合的國家/地區群組，系統會將 amp-geo-no-group 類別新增至 body。

範例：產生的 CSS 類別

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

範例：使用 CSS 類別和國家/地區群組將「soccer」變更為「football」

在以下範例中，我們會判斷使用者是否位於「soccer」國家/地區，並針對這些使用者顯示「football」訊息。

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

如果使用者位於其中一個「soccer」國家/地區，amp-geo-group-soccer CSS 類別就會套用至 body 標記。

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

接著，您可以使用 CSS 輕鬆選取正確的字詞 (即 football)。

<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 變數替換取得

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 檔案。如果無法判斷國家/地區，「unknown」國家/地區可以透過讓檔案保持未修補狀態或使用長度相等的空格字串進行修補來表示。

偵錯

在文件網址中新增 #amp-geo=XX 會強制國家/地區顯示為國家/地區 XX。這可讓您進行測試，而無需 VPN 連線到國家/地區。基於安全性考量，為了防止共用地理位置詐騙網址，這項功能僅適用於已啟用實驗性管道或在本機進行測試的使用者 (也就是透過 amp serve 以開發人員模式提供 amp-geo.js)。

由於 ITP，DevChannel 中的偵錯功能可能無法在 Safari 中運作。

驗證

請參閱 AMP 驗證器規格中的 amp-geo 規則。

需要更多協助嗎？

您已經讀過這份文件十幾次，但內容仍然沒有涵蓋您的所有問題？或許其他人也有相同的感受：請在 Stack Overflow 上與他們交流。

前往 Stack Overflow

發現錯誤或缺少功能？

AMP 專案大力鼓勵您的參與和貢獻！我們希望您能成為我們開放原始碼社群的長期參與者，但我們也歡迎針對您特別關注的問題提供一次性貢獻。

前往 GitHub