使用 AMP Viewer 算繪電子郵件

重要事項：本說明文件不適用於您目前選取的格式「故事」！

有意支援 AMP 電子郵件的電子郵件用戶端，應使用 AMP Viewer 來託管寄件者的 AMP 電子郵件。使用 AMP Viewer 程式庫建構的 Viewer 封裝了 AMP 文件，並啟用功能，可透過 postMessage 與 AMP 文件進行雙向通訊。這些功能包括授予電子郵件顯示權限、轉送使用者指標，以及提供確保電子郵件發出 XHR 要求安全性的方法。

Viewer XHR 攔截

AMP Viewer 程式庫的 xhrInterceptor 功能可讓 Viewer 攔截傳出的 XHR 要求。AMP Viewer 可以檢查要求的有效性和意圖，以確保使用者受到保護和隱私受到保障。

XHR 要求

AMP 元件 (例如 <amp-list> 和 <amp-form>) 需要呼叫端點來張貼或擷取資料。這些呼叫歸類為 XHR 要求。

Viewer 和 AMP 文件通訊

Viewer 和 AMP 文件之間通訊使用的協定是透過 postMessage 達成。以下是 postMessage 在 XHR 攔截用途中運作的簡單範例，其中 Viewer 會處理從 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 攔截。請參閱 Viewer 範例，瞭解如何完成這項操作，以及 XHR 攔截範例。接著，AMP 文件必須選擇允許 XHR 攔截。文件會將 allow-xhr-interception 屬性新增至 <html amp4email> 標記，以選擇加入。電子郵件用戶端必須在算繪 AMP 文件之前，在 AMP 文件中設定此屬性，因為這是有意設定的無效屬性，在 AMP 文件驗證期間會標示為無效。

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

Viewer 伺服器端範本算繪

viewerRenderTemplate 功能可讓 Viewer 管理 <amp-list> 和 <amp-form> 範本算繪。啟用此功能後，AMP 執行階段會將包含原始 XHR 呼叫、範本資料，以及算繪元件內容所需的任何其他詳細資料的要求，Proxy 處理至 Viewer。這可讓 Viewer 檢查端點資料內容，並管理 Mustache 範本的算繪，以驗證及清理資料。請注意，如果同時啟用此功能和 xhrInterceptor，在 amp-form 和 amp-list 元件中，也會將要求 Proxy 處理至 Viewer 的 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 功能的電子郵件用戶端 Viewer 中的 AMP 文件，如何處理 <amp-list> 範本的算繪。

AMP 執行階段會將 <amp-list> 元件資料擷取要求 Proxy 處理至 Viewer，而 Viewer 接著會將此要求轉送至電子郵件用戶端伺服器。伺服器會將此網址和網址擷取結果饋送至各種服務，可能會檢查網址有效性、從該網址傳回的資料內容，並使用該資料算繪 Mustache 範本。接著，伺服器會傳回算繪的範本，並以以下 JSON 回應格式傳送回 Viewer。

{
  "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 文件中以進行算繪。

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

Viewer 功能	受影響的元件
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