Embedded Looker iframe messaging

1. Before you begin

You should have Looker content embedded inside an iframe with either private embedding or SSO embedding. In this codelab, we will interact with your iframe via JavaScript to make your webpage more dynamic. Your web page will send messages to and receive messages from the iframe's embedded Looker content.

Prerequisites

What you'll learn

  • How to prepare your iframe and Looker instance for JavaScript interaction
  • How to listen to events from your iframe
  • How to send action messages to your iframe

What you'll need

  • Access to your frontend code's HTML and JavaScript that manages the iframe
  • Access to the admin embed settings in your Looker instance

2. Preparations

You need to prepare your iframe and Looker instance before you can interact with the iframe.

Add an id attribute to the iframe

You will need to validate the messages coming from the iframe. To do this, define an id attribute on the iframe:

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

Add the embed's domain to the iframe's src attribute

Determine the domain of the webpage hosting the iframe. Say the webpage's URL is https://mywebsite.com/with/embed then the webpage's domain is https://mywebsite.com.

If you're using Private Embedding, in the iframe's src, add the domain as an embed_domain query parameter:

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

If you're using SSO Embedding, add the domain as an embed_domain query parameter to the embed URL.

Allowlist the embed's domain in the Looker instance

Lastly, you need to allowlist the embed's domain in your Looker instance to allow message sending.

Navigate to the Embed page in your Looker instance's Admin section. https://your_instance.looker.com/admin/embed

In the Embedded Domain Allowlist field, enter the embed's domain. After typing it, hit the Tab key so that the domain appears in a box. Do not include a trailing slash /.

Select the Update button.

3. Listen to event messages from the iframe

Your iframe with embedded Looker content sends messages to its host webpage. These event messages contain timely information about the embedded looker content, like if the embedded dashboard has started loading or the user has selected the Download option within the embedded content. Let's receive and parse these events.

Understand the event object schema

The event object's schema is:

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

The event will always have a type property that lets you determine what event it is. All other event specific properties are defined in our events reference.

Receive and parse the event

Add this to where your webpage's JavaScript initialize or manages your 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"); 
    }
  }
});

The code snippet does the following:

  1. Listens for the "message" event from the window object.
  2. Checks the message's source property is the iframe with the embedded Looker content.
  3. Checks the message's origin property is your Looker instance's domain.
  4. JSON parses the message's data property to access and parse the event object.
  5. Switches on the event object's type property to determine what event it is and act on it..

Now your host webpage can dynamically react to events your embedded Looker content emits!

4. Send action message to the iframe

Your host webpage can also send messages to your iframe's embedded Looker content. These action messages can change the state of your embedded Looker content, like updating the filters on your embedded dashboard. Let's create an action message that tells your embedded dashboard to run its queries and send the message to your iframe.

Create an action message

Create an action message inside your webpage's JavaScript:

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

The action object follows the same format as the previous event object. It will always have a type property and then action specific properties which are defined in our action reference. The action message must be JSON formatted.

Send the action message

Inside your webpage's JavaScript send the JSON formatted action to your iframe:

const iframeElement = document.getElementById("looker");
iframeElement.contentWindow.postMessage(actionJSONFormatted, 'https://instance_name.looker.com');
  1. Determine your iframe that you will send your action to.
  2. Call the postMessage() method on the iframe's contentWindow property to send the message.

Now your host webpage can dynamically change the state of your embedded Looker content!

5. Additional information

Congratulations! You can now listen to events from and send actions to your iframe's embedded Looker content. Check out these resources for further information: