amp-access

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

AMP Access 或「AMP 付費牆和訂閱支援」讓發布商可以根據讀者的訂閱狀態、瀏覽次數和其他因素，控制讀者可以存取哪些內容以及哪些限制。

與 amp-subscriptions 的關係

amp-subscriptions 擴充功能提供與 amp-access 類似的功能。但是，它支援更專業的存取付費牆協定。一些值得注意的差異是

1. amp-subscriptions 授權回應與 amp-access 授權類似，但經過嚴格定義和標準化。
2. amp-subscriptions 擴充功能允許多個服務針對頁面進行設定，以參與存取/付費牆決策。它們會同時執行，並根據哪個服務傳回正面回應來決定優先順序。
3. AMP 檢視器可以根據與發布商的獨立協議，提供 amp-subscriptions 簽署的授權回應，作為存取證明。
4. 在 amp-subscriptions 中，內容標記已標準化，讓應用程式和檢索器可以輕鬆偵測優質內容區塊。

由於標記標準化、多供應商支援和改良的檢視器支援，建議新的發布商和付費牆供應商實作使用 amp-subscriptions。

解決方案

建議的解決方案讓發布商可以控制以下決策和流程

• 建立和維護使用者
• 計量控制 (允許一定數量的免費瀏覽)
• 負責登入流程
• 負責驗證使用者身分
• 負責存取規則和授權
• 每個文件皆可彈性設定存取參數

此解決方案包含以下元件

1. AMP 讀者 ID：由 AMP 生態系統提供，這是 AMP 所見讀者的唯一識別碼。
2. 存取內容標記：由發布商撰寫，定義在哪些情況下文件的哪些部分可見。
3. 授權端點：由發布商提供，傳回說明讀者可以消費文件哪些部分的回應。
4. 回呼端點：由發布商提供，用於傳送文件的「瀏覽」曝光。
5. 登入連結和登入頁面：允許發布商驗證讀者身分，並將其身分與 AMP 讀者 ID 建立關聯。

Google AMP 快取將文件傳回給讀者，並使用存取內容標記遮蔽某些區塊。AMP 執行階段呼叫授權端點，並使用回應來隱藏或顯示存取內容標記定義的不同區塊。在文件顯示給讀者後，AMP 執行階段會呼叫回呼端點，發布商可以使用該端點來更新倒數計量器 (已使用的免費瀏覽次數)。

此解決方案也允許發布商在 AMP 文件中放置登入連結，以啟動登入/訂閱頁面，發布商可以在其中驗證讀者身分，並將讀者在其系統中的身分與 AMP 讀者 ID 建立關聯。

在其基本形式中，此解決方案會將完整 (但已遮蔽) 的文件傳送給讀者，並根據授權回應簡單地顯示/隱藏受限制的區塊。但是，此解決方案也提供「伺服器」選項，其中受限制的區塊可以從初始文件傳遞中排除，並且僅在授權確認後才下載。

支援 AMP Access 需要發布商實作上述元件。存取內容標記和授權端點是必要的。回呼端點和登入頁面是選用的。

AMP 讀者 ID

為了協助存取服務和使用案例，AMP Access 引入了讀者 ID 的概念。

讀者 ID 是由 AMP 生態系統建立的匿名且唯一 ID。對於每個讀者/發布商配對而言，它是唯一的 - 對於兩位不同的發布商，讀者的識別方式會有所不同。這是一個不可逆的 ID。讀者 ID 包含在所有 AMP/發布商通訊中，並具有非常高的熵。發布商可以使用讀者 ID 來識別讀者，並將其對應到他們自己的身分系統。

讀者 ID 是在使用者裝置上建構的，旨在長期存在。但是，它遵循正常的瀏覽器儲存規則，包括針對無痕視窗的規則。讀者 ID 的預期生命週期為 1 年 (在每次使用之間)，或直到使用者清除其 Cookie 為止。讀者 ID 目前不會在裝置之間共用。

讀者 ID 的建構方式與用於建構 ExternalCID 的機制類似，請參閱此處的說明。讀者 ID 範例為 amp-OFsqR4pPKynymPyMmplPNMvxSTsNQob3TnK-oE3nwVT0clORaZ1rkeEz8xej-vV6。

AMP Access 和 Cookie

發布商可以使用自己的驗證 Cookie，也可以依賴讀者 ID，或兩者結合使用。

存取內容標記

存取內容標記決定哪些區塊可見或隱藏，這取決於從授權端點傳回的授權回應。它是透過特殊的標記屬性來描述的。

授權端點

授權是由發布商提供的端點，並由 AMP 執行階段或 Google AMP 快取呼叫。它是一個具有憑證的 CORS GET 端點。此端點會傳回存取參數，內容標記可以使用這些參數來隱藏或顯示文件的不同部分。

回呼端點

回呼是由發布商提供的端點，並由 AMP 執行階段或 Google AMP 快取呼叫。它是一個具有憑證的 CORS POST 端點。當讀者開始檢視文件時，AMP 執行階段會自動呼叫此端點。在讀者成功完成登入流程後，也會呼叫此端點。回呼的主要目標之一是讓發布商更新計量資訊。

回呼是選用的。可以透過將 noPingback 設定屬性設為 true 來停用它。

登入頁面和登入連結

登入頁面由發布商實作和提供服務，並由 AMP 執行階段呼叫。它通常顯示為瀏覽器對話方塊。

當讀者點擊登入連結時，會觸發登入頁面，發布商可以將登入連結放置在文件中的任何位置。

規格 v0.1

設定

所有端點都在 AMP 文件中設定為文件 HEAD 中的 JSON 物件

<script id="amp-access" type="application/json">
  {
    "property": value,
    ...
  }
</script>

此設定中定義了以下屬性

<URL> 值指定具有替換變數的 HTTPS 網址。替換變數在下方的「存取網址變數」章節中更詳細地介紹。

以下是 AMP Access 設定的範例

<script id="amp-access" type="application/json">
  {
    "authorization": "https://pub.com/amp-access?rid=READER_ID&url=SOURCE_URL",
    "pingback": "https://pub.com/amp-ping?rid=READER_ID&url=SOURCE_URL",
    "login": "https://pub.com/amp-login?rid=READER_ID&url=SOURCE_URL",
    "authorizationFallbackResponse": {"error": true}
  }
</script>

多個存取供應商

可以使用陣列而不是單一物件來指定多個存取供應商，並為每個項目提供 namespace。

<script id="amp-access" type="application/json">
  [
    {
      "property": value,
      ...
      "namespace": value
    },
    ...
  ]
</script>

存取網址變數

在設定各種端點的網址時，發布商可以使用替換變數。這些變數的完整清單在 AMP 變數規格中定義。此外，此規格還新增了一些存取專用變數，例如 READER_ID 和 AUTHDATA。下表描述了一些最相關的變數

以下是使用讀者 ID、標準網址、參照資訊和隨機快取清除器擴充網址的範例

https://pub.com/access?
   rid=READER_ID
  &url=CANONICAL_URL
  &ref=DOCUMENT_REFERRER
  &_=RANDOM

AUTHDATA 變數可用於回呼和登入網址。它允許將授權回應中的任何欄位作為網址參數傳遞。例如，AUTHDATA(isSubscriber)。也允許巢狀運算式，例如 AUTHDATA(other.isSubscriber)。如果使用命名空間，則可以在欄位前加上命名空間，例如 AUTHDATA(anamespace.afield)。

存取內容標記

存取內容標記描述哪些區塊可見或隱藏。它包含兩個 AMP 屬性：amp-access 和 amp-access-hide，可以放置在任何 HTML 元素上。

amp-access 屬性提供運算式，該運算式根據授權端點傳回的授權回應產生 true 或 false。結果值表示元素及其內容是否可見。

amp-access 值是以類似 SQL 的語言定義的布林運算式。語法在「附錄 A」中定義。它定義如下

<div amp-access="expression">...</div>

屬性和值是指授權端點傳回的授權回應的屬性和值。這提供了一個彈性的系統來支援不同的存取情境。如果使用命名空間，只需在屬性名稱前加上命名空間，例如 anamespace.aproperty。

amp-access-hide 屬性可用於在收到授權回應之前，樂觀地隱藏元素，這可以顯示它。它提供「預設隱藏」的語意。授權稍後傳回的回應可能會撤銷此預設值，並使區塊可見。當省略 amp-access-hide 屬性時，預設情況下將顯示/包含該區塊。amp-access-hide 屬性只能與 amp-access 屬性結合使用。

<div amp-access="expression" amp-access-hide>...</div>

如果授權要求失敗，則不會評估 amp-access 運算式，區塊是否可見或隱藏取決於文件最初提供的 amp-access-hide 屬性的存在。

我們可以根據需要擴充 amp-access-* 屬性的集合，以支援不同的混淆和呈現需求。

如果授權要求失敗，且文件中未指定「authorizationFallbackResponse」回應，則不會評估 amp-access 運算式，區塊是否可見或隱藏取決於文件最初提供的 amp-access-hide 屬性的存在。

以下範例顯示登入連結或完整內容，具體取決於訂閱狀態

<header>
  Title of the document
</header>

<div>
  First snippet in the document.
</div>

<div amp-access="NOT subscriber" amp-access-hide>
  <a on="tap:amp-access.login">Become a subscriber now!</a>
</div>

<div amp-access="subscriber">
  Full content.
</div>

這裡

• subscriber 是授權端點傳回的授權回應中的布林欄位。此區塊預設為隱藏，這是選用的。
• 此範例選擇樂觀地顯示完整內容。

以下是另一個範例，向讀者顯示關於計量狀態的免責聲明

<section amp-access="views <= maxViews">
  <template amp-access-template type="amp-mustache">
    You are reading article {{views}} out of {{maxViews}}.
  </template>
</section>

以下範例顯示給高級訂閱者的額外內容

<section amp-access="subscriptonType = 'premium'">
  Shhh… No one but you can read this content.
</section>

授權端點

授權透過「AMP Access 設定」章節中的 authorization 屬性進行設定。它是一個具有憑證的 CORS GET 端點。請參閱「CORS 來源安全性」以了解應如何保護此要求。

授權可以採用「存取網址變數」章節中定義的任何參數。例如，它可以傳遞 AMP 讀者 ID 和文件網址。除了網址參數外，發布商還可以使用透過 HTTP 協定自然傳遞的任何資訊，例如讀者的 IP 位址。必須包含 READER_ID。

此端點產生授權回應，可用於內容標記運算式中，以顯示/隱藏內容的不同部分。

要求格式為

https://publisher.com/amp-access.json?
   rid=READER_ID
  &url=SOURCE_URL

回應是一個自由格式的 JSON 物件：它可以包含任何屬性和值，但有一些限制。限制如下

• 屬性名稱必須符合「amp-access」運算式語法定義的限制 (請參閱「附錄 A」)。這主要表示屬性名稱不能包含空格、破折號和其他不符合「amp-access」規格的字元。
• 屬性值只能是以下類型之一：字串、數字、布林值。
• 值也可以巢狀結構化為物件，其值類型相同：字串、數字、布林值。
• 序列化授權回應的總大小不得超過 500 位元組。
• 請確保回應不包含任何個人身分識別資訊 (PII) 或個人資料。

以下是可能從授權端點傳回的屬性的一些想法

• 計量資訊：允許的最大瀏覽次數和目前的瀏覽次數。
• 讀者是否已登入或為訂閱者。
• 更詳細的訂閱類型：基本、高級
• 地理位置：國家/地區、區域、自訂發布區域

以下是讀者不是訂閱者且計量為每月 10 篇文章，並且已瀏覽 6 篇文章時的回應範例

{
  "maxViews": 10,
  "currentViews": 6,
  "subscriber": false
}

以下是讀者已登入且具有高級訂閱類型時的回應範例

{
  "loggedIn": true,
  "subscriptionType": "premium"
}

此 RPC 可以在預先呈現階段呼叫，因此不應用於計量倒數，因為讀者可能永遠不會實際看到文件。

另一個重要的考量是，在某些情況下，AMP 執行階段可能需要每個文件曝光呼叫授權端點多次。當 AMP 執行階段認為讀者的存取參數已顯著變更時，可能會發生這種情況，例如在成功登入流程之後。

授權回應可能會被 AMP 執行階段和擴充功能用於三個不同的目的

1. 在評估 amp-access 運算式時。
2. 在評估 <template> 範本時，例如 amp-mustache。
3. 在使用 AUTHDATA(欄位) 時，為回呼和登入網址提供額外變數。

授權端點由 AMP 執行階段作為具有憑證的 CORS 端點呼叫。因此，它必須實作 CORS 協定。它應使用 CORS 來源和來源來源來限制對此服務的存取，如「CORS 來源安全性」中所述。此端點可能會根據其需求使用發布商 Cookie。例如，它可以關聯讀者 ID 和發布商自己的使用者身分之間的繫結。AMP 本身不需要知道此事 (並且最好不知道)。如需更多詳細資訊，請參閱「AMP 讀者 ID」和「AMP Access 和 Cookie」文件。

當呼叫授權端點時，AMP 執行階段 (或更確切地說是瀏覽器) 會觀察快取回應標頭。因此，可以重複使用快取的回應。這可能是可取的，也可能不是可取的。如果不可取，發布商可以使用適當的快取控制標頭和/或端點網址的 RANDOM 變數替換。

如果授權要求失敗，AMP 執行階段將會後備到「authorizationFallbackResponse」(如果在設定中指定)。在這種情況下，授權流程將照常進行，並使用「authorizationFallbackResponse」屬性的值來取代授權回應。如果未指定「authorizationFallbackResponse」，則授權流程將會失敗，在這種情況下，將不會評估 amp-access 運算式，區塊是否可見或隱藏將取決於文件最初提供的 amp-access-hide 屬性的存在。

授權要求會在 3 秒後自動逾時，並假定為失敗。

AMP 執行階段在授權流程期間使用以下 CSS 類別

1. 當授權流程開始時，amp-access-loading CSS 類別會設定在文件根目錄上，並在流程完成或失敗時移除。
2. 當授權流程失敗時，amp-access-error CSS 類別會設定在文件根目錄上。

在伺服器選項中，對授權端點的呼叫是由 Google AMP 快取作為簡單的 HTTPS 端點進行的。這表示在這種情況下，無法傳遞發布商的 Cookie。

回呼端點

回呼透過「AMP Access 設定」章節中的 pingback 屬性進行設定。它是一個具有憑證的 CORS POST 端點。請參閱「CORS 來源安全性」以了解應如何保護此要求。

回呼網址是選用的。可以使用 "noPingback": true 停用它。

回呼網址可以採用「存取網址變數」章節中定義的任何參數。例如，它可以傳遞 AMP 讀者 ID 和文件網址。必須包含 READER_ID。

回呼不會產生回應 - AMP 執行階段會忽略任何回應。

當讀者開始檢視文件時，以及在讀者成功完成登入流程後，會呼叫回呼端點。

發布商可以選擇使用回呼

• 以倒數頁面的免費瀏覽次數
• 將 AMP 讀者 ID 對應到發布商的身分，因為作為具有憑證的 CORS 端點，回呼可能包含發布商 Cookie

要求格式為

https://publisher.com/amp-pingback?
   rid=READER_ID
  &url=SOURCE_URL

登入頁面

登入頁面的網址在「AMP Access 設定」章節中透過 login 屬性進行設定。

設定可以指定單一登入網址或按登入類型鍵入的登入網址地圖。單一登入網址的範例

{
  "login": "https://publisher.com/amp-login.html?rid={READER_ID}"
}

多個登入網址的範例

{
  "login": {
    "signin": "https://publisher.com/signin.html?rid={READER_ID}",
    "signup": "https://publisher.com/signup.html?rid={READER_ID}"
  }
}

網址可以採用「存取網址變數」章節中定義的任何參數。例如，它可以傳遞 AMP 讀者 ID 和文件網址。RETURN_URL 查詢替換可用於指定傳回網址的查詢參數，例如 ?ret=RETURN_URL。傳回網址是必要的，如果未指定 RETURN_URL 替換，則會自動注入，預設查詢參數名稱為「return」。

登入頁面只是一個普通的網頁，沒有特殊限制，除了它應該作為瀏覽器對話方塊運作良好。請參閱「登入流程」章節以取得更多詳細資訊。

要求格式為

https://publisher.com/amp-login.html?
   rid=READER_ID
  &url=SOURCE_URL
  &return=RETURN_URL

請注意，如果未指定 RETURN_URL 替換，AMP 執行階段會自動新增「return」網址參數。一旦登入頁面完成其工作，它必須重新導向回指定的「傳回網址」，格式如下

RETURN_URL#success=true|false

請注意使用網址雜湊參數「success」。值為「true」或「false」，取決於登入成功還是放棄。理想情況下，登入頁面在可能的情況下，會在成功或失敗的情況下都傳送訊號。

如果傳回 success=true 訊號，AMP 執行階段將重複呼叫授權和回呼端點，以更新文件的狀態並報告具有新存取設定檔的「瀏覽」。

登入連結

發布商可以選擇將登入連結放置在文件內容中的任何位置。

一個或多個登入網址在「AMP Access 設定」章節中透過「login」屬性進行設定。

登入連結可以在任何允許「on」屬性的 HTML 元素上宣告。通常，這會是錨點或按鈕元素。當設定單一登入網址時，格式為

<a on="tap:amp-access.login">Login or subscribe</a>

當設定多個登入網址時，格式為 tap:amp-access.login-{type}。範例

<a on="tap:amp-access.login-signup">Subscribe</a>

當使用命名空間時，格式為 tap:amp-access.login-{namespace} 或 tap:amp-access.login-{namespace}-{type}。

AMP 不區分登入和訂閱。此區分可以由發布商使用多個登入網址/連結或在發布商端進行設定。

與 amp-analytics 整合

與 amp-analytics 的整合記錄在「amp-access-analytics.md」中。

CORS 來源安全性

授權和回呼端點是 CORS 端點，它們必須實作「AMP CORS 安全性規格」中描述的安全性協定。

計量

計量系統是指在某段期間內，讀者可以免費瀏覽幾個文件來查看優質內容的系統。一旦達到某些配額，就會啟動付費牆，讀者改為看到部分內容，其中包含追加銷售訊息和註冊/登入連結。例如，計量可以定義為「讀者每月可以免費閱讀 10 篇文章」。

AMP Access 提供以下功能來實作計量存取

1. READER_ID 應用於儲存計量資訊。由於發布商不能依賴始終能夠在第三方環境中設定 Cookie，因此此資料應儲存在伺服器端。
2. 「閱讀次數」只能在回呼端點中更新。
3. 只有唯一的文件才能計入配額。也就是說，重新整理同一文件十次構成單次瀏覽。為此，授權和回呼端點可以注入 SOURCE_URL 或類似的網址變數。請參閱「存取網址變數」。

首次點擊免費

Google 的首次點擊免費 (或 FCF) 政策在此處說明，最新的更新在此處更詳細地說明。

為了實作 FCF，發布商必須 (1) 能夠判斷每次瀏覽的參照服務，以及 (2) 能夠計算每位讀者每天的瀏覽次數。

AMP Access 規格涵蓋了這兩個步驟。參照位址可以使用「存取網址變數」中描述的 DOCUMENT_REFERRER 網址替換注入到授權和回呼網址中。瀏覽次數計數可以使用伺服器端的回呼端點完成。這與「計量」中描述的計量實作非常相似。

登入流程

AMP 會啟動登入對話方塊作為第一方視窗或快顯視窗或標籤頁。在可能的情況下，AMP 檢視器應嘗試在瀏覽器環境中啟動登入對話方塊，以便它可以利用最上層的瀏覽器 API。

當讀者啟動登入連結時，AMP 執行階段會啟動登入流程，並且描述性地，它會遵循以下步驟

1. 登入對話方塊 (第一方視窗) 由 AMP 執行階段或檢視器針對指定的登入網址開啟。網址包含額外的「傳回網址」網址查詢參數 (&return=RETURN_URL)。許多其他參數也可以擴充到網址中，例如讀者 ID。如需更多詳細資訊，請參閱「登入頁面」章節。
2. 發布商顯示自由格式的登入頁面。
3. 讀者遵循登入步驟，例如輸入使用者名稱/密碼或使用社群登入。
4. 讀者提交登入。發布商完成驗證、設定 Cookie，最後將讀者重新導向到先前要求的「傳回網址」。重新導向包含網址雜湊參數 success，它可以是 true 或 false。
5. 登入對話方塊遵循重新導向到「傳回網址」。
6. AMP 執行階段重新授權文件。

只有步驟 2-5 需要由發布商處理：發布商僅提供他們自己的登入頁面，並確保在完成後正確重新導向。登入頁面沒有施加任何特殊限制，除了它應該作為對話方塊運作良好。

與往常一樣，讀者 ID 應包含在對登入頁面的呼叫中，並且發布商可以使用它進行身分對應。作為第一方視窗，發布商也將收到他們的 Cookie，並且能夠設定它們。如果結果證明讀者已在發布商端登入，建議發布商立即重新導向回「傳回網址」，並傳回 success=true 回應。

AMP 詞彙表

• AMP 文件 - 遵循 AMP 格式並由 AMP 驗證器驗證的 HTML 文件。AMP 文件可由 Google AMP 快取快取。
• AMP 驗證器 - 一個電腦程式，它對 HTML 文件執行靜態分析，並根據文件是否符合 AMP 格式傳回成功或失敗。
• AMP 執行階段 - 執行 AMP 文件的 JavaScript 執行階段。
• Google AMP 快取 - AMP 文件的 Proxy 快取。
• AMP 檢視器 - 顯示/嵌入 AMP 文件的 Web 或原生應用程式。
• Publisher.com - AMP 發布商的網站。
• CORS 端點 - 跨來源 HTTPS 端點。如需更多資訊，請參閱 https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS。請參閱「CORS 來源安全性」以了解如何保護此類要求。
• 讀者 - 實際檢視 AMP 文件的人。
• AMP 預先呈現 - AMP 檢視器可以利用預先呈現，在隱藏文件可以顯示之前呈現它。這增加了顯著的效能提升。但重要的是要考慮到文件預先呈現不構成瀏覽，因為讀者可能永遠不會實際看到文件。

修訂

• 2016-09-02：新增「noPingback」設定屬性和選用回呼。
• 2016-03-03：登入後重新傳送回呼 (v0.5)。
• 2016-02-19：更正範例以從網址變數替換中移除 {}。
• 2016-02-15：「設定」和「授權端點」現在允許「authorizationFallbackResponse」屬性，該屬性可在授權失敗時使用。
• 2016-02-11：「授權端點」中的授權要求逾時。
• 2016-02-11：現在允許巢狀欄位參照，例如 object.field。
• 2016-02-09：「首次點擊免費」和「計量」章節。
• 2016-02-03：將「來源來源」安全性規格新增至「CORS 來源安全性」。
• 2016-02-01：登入頁面的「return」查詢參數可以使用 RETURN_URL 網址替換自訂。

附錄 A：「amp-access」運算式語法

最新的 BNF 語法可在 access-expr-impl.jison 檔案中取得。

此語法的關鍵摘錄如下

search_condition:
    search_condition OR search_condition
  | search_condition AND search_condition
  | NOT search_condition
  | '(' search_condition ')'
  | predicate

predicate:
    comparison_predicate | truthy_predicate

comparison_predicate:
    scalar_exp '=' scalar_exp
  | scalar_exp '!=' scalar_exp
  | scalar_exp '<' scalar_exp
  | scalar_exp '<=' scalar_exp
  | scalar_exp '>' scalar_exp
  | scalar_exp '>=' scalar_exp

truthy_predicate: scalar_exp

scalar_exp: literal | field_ref

field_ref: field_ref '.' field_name | field_name

literal: STRING | NUMERIC | TRUE | FALSE | NULL

請注意，amp-access 運算式由 AMP 執行階段和 Google AMP 快取評估。這不是發布商需要實作的規格的一部分。此處僅供參考。

詳細討論

本節將詳細說明 amp-access 規格背後的設計，並闡明設計選擇。即將推出。

驗證

請參閱 AMP 驗證器規格中的「amp-access 規則」。