使用 AMP Viewer 算繪電子郵件

重要事項：本文件不適用於您目前選取的格式廣告！

有意支援 AMP for Email 的電子郵件用戶端應使用 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 達成。以下是在 XHR 攔截使用案例中 postMessage 運作方式的簡易範例，其中 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 攔截

在初始化時將 Viewer 選入 xhrInterceptor 功能，即可啟用 xhr 攔截。請參閱 Viewer 範例，瞭解如何完成此作業，以及 xhr 攔截的範例。接著，AMP 文件必須選擇允許 XHR 攔截。文件可透過將 allow-xhr-interception 屬性新增至 <html amp4email> 標記來選擇加入。電子郵件用戶端必須在算繪 AMP 文件之前設定此屬性，因為此屬性刻意設為無效，並會在 AMP 文件驗證期間標示為無效。

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

Viewer 伺服器端範本算繪

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

viewer.html 範例說明如何處理從 AMP 文件傳送的 viewerRenderTemplate 訊息。在該範例中，Viewer.prototype.processRequest_ 會攔截 viewerRenderTemplate 訊息，並根據要求中提供的 amp 元件類型，傳送 HTML 以在下列 JSON 格式中算繪。

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> 元件資料擷取要求代理至 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