使用 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 攔截

若要啟用 xhr 攔截，請在初始化時讓 Viewer 選擇加入 xhrInterceptor 功能。如需瞭解如何執行這項操作以及 xhr 攔截的範例，請參閱 Viewer 範例。接著，AMP 文件必須選擇允許 XHR 攔截。文件選擇加入的方式是在 <html amp4email> 標記中新增 allow-xhr-interception 屬性。電子郵件用戶端必須在彩現 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 元件中，也會將要求代理至 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 程式庫依附元件，也不會清理內容。

下圖說明更實際的範例，說明電子郵件用戶端 Viewer 中具有 viewerRenderTemplate 功能的 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 撰寫