嵌入式 Looker iframe 訊息

1. 事前準備

您應將 Looker 內容嵌入 iframe 中,並使用私人嵌入單一登入 (SSO) 嵌入功能。在本程式碼研究室中,我們會透過 JavaScript 與 iframe 互動,讓網頁更具動態性。網頁會向 iframe 嵌入的 Looker 內容傳送訊息,並接收該內容傳送的訊息。

必要條件

課程內容

  • 如何為 iframe 和 Looker 執行個體做好與 JavaScript 互動的準備
  • 如何監聽 iFrame 中的事件
  • 如何將動作訊息傳送至 iframe

軟硬體需求

  • 存取管理 iframe 的前端程式碼 HTML 和 JavaScript
  • 可存取 Looker 執行個體中的管理員嵌入設定

2. 準備事項

請先備妥 iframe 和 Looker 執行個體,才能與 iframe 互動。

在 iframe 中加入 id 屬性

您需要驗證來自 iframe 的郵件。方法是在 iframe 上定義 id 屬性:

<iframe 
    id="looker"
    src="https://instance_name.looker.com/embed/dashboards/1"
>
</iframe>

將嵌入網域新增至 iframe 的 src 屬性

判斷代管 iframe 的網頁網域。假設該網頁的網址為 https://mywebsite.com/with/embed,則該網頁網域為 https://mywebsite.com

如果您使用私人嵌入功能,請在 iframe 的 src 中,將網域新增為 embed_domain 查詢參數:

<iframe
    id="looker"
    src="https://instance_name.looker.com/embed/dashboards/1?embed_domain=https://mywebsite.com"
>
</iframe>

如果您使用 SSO 嵌入功能,請將網域加入嵌入網址做為 embed_domain 查詢參數。

將嵌入網域加入 Looker 執行個體中的許可清單

最後,您需要在 Looker 例項中將內嵌網域加入許可清單,才能傳送訊息。

前往 Looker 執行個體「管理」專區中的「嵌入」頁面。https://your_instance.looker.com/admin/embed

在「嵌入網域允許清單」欄位中輸入嵌入網域的網域。輸入完成後,按下 Tab 鍵,網域就會出現在方塊中。結尾不得為斜線 /

選取「更新」按鈕。

3. 監聽來自 iframe 的事件訊息

嵌入 Looker 內容的 iframe 會傳送訊息給主機網頁。這些「事件」訊息包含嵌入式 Looker 內容的相關即時資訊,例如內嵌資訊主頁已開始載入,或是使用者已在嵌入內容中選取「下載」選項。讓我們接收並剖析這些事件

瞭解事件物件結構定義

事件物件的結構定義如下:

{
  type: "...",
  eventSpecificProperty1: ...,
  eventSpecificProperty2: ...,
  ...
}

該事件一律都會有 type 屬性,可讓您判斷事件為何。如需其他事件專屬屬性的定義,請參閱事件參考資料

接收並剖析事件

將以下程式碼新增至網頁的 JavaScript 初始化或管理 iframe 的位置:

window.addEventListener("message", function(message) {
  const iframeElement = document.getElementById("looker");
  if (message.source === iframeElement.contentWindow) {
    if (message.origin === "https://instance_name.looker.com") {
      const event = JSON.parse(message.data);
      switch (event.type):
        case "dashboard:run:start":
          console.log("The embedded dashboard has started loading"); 
    }
  }
});

程式碼片段會執行以下作業:

  1. 監聽 window 物件的 "message" 事件。
  2. 檢查訊息的 source 屬性是含有嵌入式 Looker 內容的 iframe。
  3. 檢查訊息的 origin 屬性是否為 Looker 執行個體的網域。
  4. JSON 會剖析訊息的 data 屬性,以存取及剖析事件物件。
  5. 在事件物件的 type 屬性上進行切換,以判斷其事件並對其採取行動。

這樣一來,主機網頁就能動態回應嵌入的 Looker 內容所發出的事件!

4. 將操作訊息傳送至 iframe

主機網頁也可以將訊息傳送至 iframe 的嵌入 Looker 內容。這些動作訊息可變更嵌入式 Looker 內容的狀態,例如更新嵌入式資訊主頁的篩選器。接下來,我們要建立動作訊息,告知嵌入的資訊主頁執行查詢並將訊息傳送至您的 iframe。

建立動作訊息

在網頁的 JavaScript 中建立動作訊息:

const action = { type: "dashboard:run" };
const actionJSONFormatted = JSON.stringify(action);

action 物件遵循與前一個 event 物件相同的格式。這個物件一律會包含 type 屬性,以及在動作參考資料中定義的動作專屬屬性。動作訊息必須採用 JSON 格式。

傳送動作訊息

在網頁的 JavaScript 中,將 JSON 格式的動作傳送至 iframe:

const iframeElement = document.getElementById("looker");
iframeElement.contentWindow.postMessage(actionJSONFormatted, 'https://instance_name.looker.com');
  1. 決定要傳送動作的 iframe。
  2. 對 iframe 的 contentWindow 屬性呼叫 postMessage() 方法,即可傳送訊息。

代管網頁現在可以動態變更嵌入式 Looker 內容的狀態!

5. 其他資訊

恭喜!您現在可以監聽 iframe 嵌入 Looker 內容的事件,並傳送動作至該內容。詳情請參閱下列資源: