如何透過 Embed SDK 嵌入 Looker

1. 事前準備

在本程式碼研究室中，我們將使用 Looker 嵌入 SDK 在網頁中嵌入 Looker 資訊主頁。您將呼叫一系列 SDK 方法，這些方法會自動建立 iframe、在其中嵌入 Looker 內容，並設定 iframe 和網頁之間的通訊。

必要條件

  • 具備執行中的 Looker 執行個體
  • 取得要嵌入網頁應用程式或網頁的 Looker 資訊主頁
  • 熟悉 JavaScript 和 JavaScript 的承諾。

課程內容

  • 如何使用 Embed SDK 私密嵌入 Looker 內容
  • 如何使用 Embed SDK 收發內嵌 Looker 內容的訊息 (動作和事件)

軟硬體需求

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

2. 準備事項

您必須備妥 HTML 和 Looker 執行個體，才能嵌入 Embed SDK。

新增嵌入 iframe 的容器元素

在網頁的 HTML 中建立 div 元素，並在該元素中定義 id 屬性。

<div id="looker-embed" />

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

您必須在 Looker 執行個體中將內嵌網域加入許可清單。

請先決定要嵌入 Looker 內容的網頁網域。假設網頁的網址是 https://mywebsite.com/with/embed，那麼網頁的網域就是 https://mywebsite.com。

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

在「內嵌網域許可清單」欄位中輸入嵌入的網域。輸入完畢後，按下 Tab 鍵，讓網域顯示在方塊中。結尾不得為斜線 /。

選取「更新」按鈕。

3. 建立嵌入項目

現在，讓我們建立並設定 SDK 的嵌入建構工具，來「建構」嵌入的 Looker 內容。

初始化 SDK

請先匯入 SDK，然後使用 Looker 例項的網域初始化 SDK。

// Import the Embed SDK as LookerEmbedSDK

LookerEmbedSDK.init('instance_name.looker.com')

建立嵌入建構工具

接下來，請決定要嵌入的 Looker 資訊主頁 ID。如果資訊主頁位於 instance_name.looker.com/dashboard/12345，則資訊主頁 ID 為 12345。

使用資訊主頁 ID 呼叫 SDK createDashboardWithId() 方法，建立嵌入建構工具。這個方法會傳回嵌入建構工具。

LookerEmbedSDK.createDashboardWithId(12345)

設定及建構嵌入工具

現在，讓我們先設定嵌入建構工具，再要求嵌入 iframe。直接在先前程式碼範例的 createDashboardWithId() 方法呼叫後方加入下列程式碼範例。

  .appendTo(‘looker-embed')
  .withFrameBorder(‘0')
  .build()

每個嵌入建構工具的方法都會傳回嵌入建構工具，因此我們會將方法呼叫鏈結在一起。讓我們逐步說明每種方法：

  1. appendTo() 方法會決定 iframe 的父項元素。我們會傳入先前在「準備」步驟中定義的 HTML 元素 ID。
  2. withFrameBorder() 方法會在 iframe 上設定 frame-border 屬性。這是在 iframe 上定義 HTML 屬性的幾種方法之一。
  3. build() 方法會使用已設定的 HTML 屬性建立 iframe

最終檢查

在先前的步驟中，您的程式碼應如下所示：

// Import the Embed SDK as LookerEmbedSDK

LookerEmbedSDK.init('instance_name.looker.com')

LookerEmbedSDK.createDashboardWithId(12345)
  .appendTo(‘looker-embed')
  .withFrameBorder(‘0')
  .build()

您現在可以透過 Embed SDK，將 Looker 資訊主頁嵌入網頁中！

4. 收發嵌入訊息

現在來看看如何使用 Embed SDK 透過嵌入式 Looker 內容收發訊息。我們將應用程式傳送至 iframe 的訊息稱為「動作」，而將應用程式從 iframe 接收的訊息稱為「事件」。

接收事件

接著使用先前的程式碼。如要監聽事件，我們會先呼叫內嵌建構工具的 on() 方法，再呼叫 build() 方法。

...
  .on('dashboard:run:complete',() => console.log(‘Embedded dashboard loaded!')
...

這裡會呼叫 on() 方法，以便為建立 iframe 時從 iframe 發出的 dashboard:run:complete 事件設定事件監聽器。這個事件會在資訊主頁載入完成時通知我們。請參閱事件參考資料，瞭解其他要監聽的事件。

傳送動作

讓我們繼續使用先前的程式碼。如要將動作傳送至 iframe，我們會先呼叫 build() 方法，以便使用 iframe 初始化訊息傳送和接收。接著，我們會呼叫內嵌建構工具的 connect() 方法，將動作傳送至 iframe。

...  
  .connect()
  .then((embed) => {
     embed.send(‘dashboard:run');
   })
  .catch(console.error(‘Something errored!')
...

讓我們逐步瞭解這個程式碼範例：

  1. 我們會呼叫 connect() 方法，該方法會傳回承諾。在訊息傳送和接收機制完成初始化後，承諾會解析為代表嵌入式 iframe 的嵌入物件。
  2. 我們會對內嵌物物件呼叫 send() 方法，傳送 dashboard:run 動作。如要瞭解其他可傳送的動作，請參閱動作參考資料。
  3. 我們新增 catch() 方法，以防初始化期間發生錯誤。

最終檢查

完成上述步驟後，您的程式碼應如下所示：

// Import the Embed SDK as LookerEmbedSDK

LookerEmbedSDK.init('instance_name.looker.com')

LookerEmbedSDK.createDashboardWithId(12345)
  .appendTo(‘looker-embed')
  .withFrameBorder(‘0')
  .on('dashboard:run:complete',() => console.log(‘Embedded dashboard loaded!')
  .build()
  .connect()
  .then((embed) => {
     embed.send(‘dashboard:run');
   })
  .catch(console.error(‘Something errored!')

你現在可以與嵌入式 Looker 資訊主頁通訊了！

5. 其他資訊

恭喜！您現在可以使用 Embed SDK 私密地嵌入 Looker 資訊主頁，並透過 iframe 傳送及接收訊息。如需更多資訊，請參閱下列資源：