使用 AMP 檢視器轉譯電子郵件

有意支援 AMP 電子郵件的電子郵件用戶端應使用 AMP 檢視器來託管其寄件者的 AMP 電子郵件。使用 AMP 檢視器程式庫建置的檢視器封裝了 AMP 文件，並啟用功能，允許透過 postMessage 與 AMP 文件進行雙向通訊。這些功能包括授予電子郵件可見性的控制權、轉發使用者指標，以及提供確保從電子郵件發出的 XHR 請求安全性的方法。

檢視器 XHR 攔截

AMP 檢視器程式庫的 xhrInterceptor 功能允許檢視器攔截外發的 XHR 請求。AMP 檢視器可以檢查請求的有效性和意圖，以確保其使用者的保護和隱私。

XHR 請求

AMP 元件，例如 <amp-list> 和 <amp-form>，需要呼叫端點以發布或檢索資料。這些呼叫歸類為 XHR 請求。

檢視器與 AMP 文件通訊

檢視器和 AMP 文件之間通訊使用的協定是透過 postMessage 實現的。以下是在 XHR 攔截使用案例中 postMessage 運作的簡單範例，其中檢視器處理從 AMP 文件傳送的 xhr postMessage 並傳回自訂回應。

// The viewer iframe that will host the amp doc.
viewerIframe = document.createElement('iframe');
viewerIframe.contentWindow.onMessage = (xhrRequestIntercepted) => {
   const blob = new Blob([JSON.stringify({body: 'hello'}, null, 2)], {type: 'application/json'});
   const response = new Reponse(blob, {status: 200});
   return response;
};

啟用 XHR 攔截

透過在初始化時將檢視器選擇加入 xhrInterceptor 功能來啟用 xhr 攔截。請參閱檢視器範例，了解如何完成此操作以及 xhr 攔截的範例。然後，AMP 文件必須選擇允許 XHR 攔截。文件透過將 allow-xhr-interception 屬性新增至 <html amp4email> 標籤來選擇加入。電子郵件用戶端必須在轉譯 AMP 文件之前在 AMP 文件上設定此屬性，因為它有意設定為無效屬性，並且在 AMP 文件驗證期間將被標記為無效。

<!doctype html>
<html ⚡4email allow-xhr-interception>
  ...    
</html>

檢視器伺服器端範本轉譯

viewerRenderTemplate 功能允許檢視器管理 <amp-list> 和 <amp-form> 範本轉譯。啟用此功能後，AMP 執行階段會將包含原始 XHR 呼叫、範本資料以及轉譯元件內容所需的任何其他詳細資訊的請求代理到檢視器。這允許檢視器檢查端點資料內容，並管理 Mustache 範本的轉譯，以驗證和清理資料。請注意，如果同時啟用此功能和 xhrInterceptor，則在 amp-form 和 amp-list 元件中，也將請求代理到檢視器的 viewerRenderTemplate 功能將優先於 xhrInterceptor 的功能。

viewer.html 範例示範了如何處理從 AMP 文件傳送的 viewerRenderTemplate 訊息。在該範例中，Viewer.prototype.processRequest_ 捕獲 viewerRenderTemplate 訊息，並根據請求中可用的 amp 元件類型，傳回要在以下 JSON 格式中轉譯的 html。

Viewer.prototype.ssrRenderAmpListTemplate_ = (data) => Promise.resolve({
  "html":
    "<div role='list' class='i-amphtml-fill-content i-amphtml-replaced-content'>"
      + "<div class='product' role='listitem'>Apple</div>"
      + "</div>",
  "body" : "",
  "init" : {
    "headers": {
      "Content-Type": "application/json",
    }
  }
});

這是一個簡單的範例，其中沒有 Mustache 程式庫依賴性或內容清理。

下圖說明了更真實世界的範例，說明具有 viewerRenderTemplate 功能的電子郵件用戶端檢視器中的 AMP 文件如何處理 <amp-list> 範本的轉譯。

AMP 執行階段會將 <amp-list> 元件資料擷取請求代理到檢視器，而檢視器又會將此請求轉發到電子郵件用戶端伺服器。伺服器會將此 URL 和 URL 擷取結果饋送到各種服務，可能檢查 URL 有效性、從該 URL 傳回的資料內容，並使用該資料轉譯 Mustache 範本。然後，它會傳回轉譯的範本，並以以下 JSON 回應格式將其傳送回檢視器。

{
  "html": "<div role='list' class='i-amphtml-fill-content i-amphtml-replaced-content'> <div class='product' role='listitem'>List item 1</div> <div class='product' role='listitem'>List item 2</div> </div>",
  "body": "",
  "init" : {
    "headers": {
      "Content-Type": "application/json",
    }
  }
}

JSON 酬載中的 html 值將是被注入到 AMP 文件中以進行轉譯的內容。

下表概述了功能和受影響的元件

檢視器功能	受影響的元件
xhrInterceptor	`[amp-form](../../../documentation/components/reference/amp-form.md?format=email), [amp-list](../../../documentation/components/reference/amp-list.md?format=email), [amp-state](https://amp.dev.org.tw/documentation/components/amp-bind?format=email#initializing-state-with-amp-state)`
viewerRenderTemplate	`[amp-form](../../../documentation/components/reference/amp-form.md?format=email), [amp-list](../../../documentation/components/reference/amp-list.md?format=email)`

作者： @alabiaga