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 Runtime 會呼叫授權端點，並使用回應來隱藏或顯示不同的區段，如存取內容標記所定義。在文件顯示給讀者後，AMP Runtime 會呼叫回呼端點，發布商可以使用該端點來更新倒數計量器 (已使用的免費瀏覽次數)。

此解決方案也允許發布商在 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 Runtime 或 Google AMP 快取呼叫。它是一個經過憑證的 CORS GET 端點。此端點會傳回存取參數，內容標記可以使用這些參數來隱藏或顯示文件的不同部分。

回呼端點

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

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

登入頁面與登入連結

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

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

規格 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 Runtime 可能需要每個文件曝光呼叫授權端點多次。當 AMP Runtime 認為讀者的存取參數已顯著變更時，可能會發生這種情況，例如在成功登入流程之後。

授權回應可能會被 AMP Runtime 和擴充功能用於三種不同的目的：

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

授權端點由 AMP Runtime 作為經過憑證的 CORS 端點呼叫。因此，它必須實作 CORS 協定。它應該使用 CORS 來源和來源來源來限制對此服務的存取，如CORS 來源安全性中所述。此端點可能會使用發布商 Cookie 來滿足其需求。例如，它可以將讀者 ID 與發布商自己的使用者身分之間的繫結建立關聯。AMP 本身不需要知道這一點 (而且最好不知道)。如需更多詳細資訊，請參閱AMP 讀者 ID 和 AMP Access 與 Cookie 文件。

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

如果授權請求失敗，AMP Runtime 將回退到「authorizationFallbackResponse」(如果已在設定中指定)。在這種情況下，授權流程將正常進行，並以「authorizationFallbackResponse」屬性的值取代授權回應。如果未指定「authorizationFallbackResponse」，則授權流程將失敗，在這種情況下，將不會評估 amp-access 表達式，區段是可見還是隱藏將取決於文件中最初提供的 amp-access-hide 屬性的存在。

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

AMP Runtime 在授權流程期間使用以下 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 Runtime 會忽略任何回應。

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

發布商可以選擇使用回呼：

• 來倒數頁面的免費瀏覽次數
• 將 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 Runtime 會自動新增「return」網址參數。一旦登入頁面完成其工作，它必須重新導向回指定的回傳網址，格式如下：

RETURN_URL#success=true|false

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

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

登入連結

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

一個或多個登入網址是透過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 Runtime 會啟動登入流程，描述性地說，它遵循以下步驟：

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

只有步驟 2-5 需要發布商處理：發布商僅需提供自己的登入頁面，並確保登入完成後能正確重新導向。登入頁面沒有其他特殊限制，僅需作為對話框能良好運作即可。

如同往常，讀者 ID 應包含在對登入頁面的呼叫中，發布商可使用此 ID 進行身分對應。作為第一方視窗，發布商也會收到他們的 Cookie，並能夠設定 Cookie。如果發現讀者已在發布商端登入，建議發布商立即重新導向回「Return URL」，並帶有 success=true 回應。

AMP 詞彙表

• AMP 文件 - 遵循 AMP 格式並通過 AMP Validator 驗證的 HTML 文件。AMP 文件可由 Google AMP Cache 快取。
• AMP Validator - 一種電腦程式，可對 HTML 文件執行靜態分析，並根據文件是否符合 AMP 格式傳回成功或失敗。
• AMP Runtime - 執行 AMP 文件的 JavaScript 執行環境。
• Google AMP Cache - AMP 文件的代理快取。
• AMP Viewer - 顯示/嵌入 AMP 文件的 Web 或原生應用程式。
• Publisher.com - AMP 發布商的網站。
• CORS endpoint - 跨來源 HTTPS 端點。更多資訊請參閱 https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS。有關如何保護此類請求的安全，請參閱 CORS Origin Security。
• Reader - 實際瀏覽 AMP 文件的人。
• AMP Prerendering - AMP Viewer 可能會利用預先呈現，在文件顯示之前先呈現隱藏的文件。這可以顯著提升效能。但務必考量到文件預先呈現並不構成一次瀏覽，因為讀者可能永遠不會實際看到該文件。

修訂

• 2016-Sep-02：「noPingback」組態屬性和選用的 Pingback。
• 2016-Mar-03：登入後重新傳送 Pingback (v0.5)。
• 2016-Feb-19：修正範例以從 URL 變數替換中移除 {}。
• 2016-Feb-15：Configuration 和 Authorization Endpoint 現在允許「authorizationFallbackResponse」屬性，可用於授權失敗時。
• 2016-Feb-11：Authorization Endpoint 中的授權請求逾時。
• 2016-Feb-11：現在允許巢狀欄位參照，例如 object.field。
• 2016-Feb-09：First-click-free 和 Metering 章節。
• 2016-Feb-03：將「來源 origin」安全性規範新增至 CORS Origin security。
• 2016-Feb-01：可以使用 RETURN_URL URL 替換來自訂登入頁面的「return」查詢參數。

附錄 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 Runtime 和 Google AMP Cache 評估。這並非發布商需要實作的規格的一部分。此處僅供參考。

詳細討論

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

驗證

請參閱 AMP validator 規格中的 amp-access 規則。