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(field) 為回呼和登入網址提供其他變數時。

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 Runtime 重新授權文件。

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

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

AMP 詞彙表

• AMP 文件 - 遵循 AMP 格式並通過 AMP 驗證器驗證的 HTML 文件。AMP 文件可由 Google AMP 快取記憶體快取。
• AMP 驗證器 - 一種電腦程式，可對 HTML 文件執行靜態分析，並根據文件是否符合 AMP 格式傳回成功或失敗。
• AMP 執行階段 - 執行 AMP 文件的 JavaScript 執行階段環境。
• Google AMP 快取 - AMP 文件的代理快取。
• 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-Sep-02：「noPingback」組態屬性和選用的 Pingback。
• 2016-Mar-03：登入後重新傳送 Pingback (v0.5)。
• 2016-Feb-19：修正範例以從 URL 變數替換中移除 {}。
• 2016-Feb-15：組態 和 授權端點 現在允許「authorizationFallbackResponse」屬性，可用於授權失敗時。
• 2016-Feb-11：授權端點 中的授權請求逾時。
• 2016-Feb-11：現在允許巢狀欄位參考，例如 object.field。
• 2016-Feb-09：首次點擊免費 和 計量 章節。
• 2016-Feb-03：將「來源來源」安全性規範新增至 CORS 來源安全性。
• 2016-Feb-01：登入頁面的「return」查詢參數可以使用 RETURN_URL 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 規則。