How to embed Looker with the Embed SDK

1. Before you begin

In this codelab, we will use the Looker Embed SDK to embed a Looker dashboard in your webpage. You will call a series of SDK methods that will automatically create an iframe, embed your Looker content in it, and set up communications between your iframe and your webpage.

Prerequisites

  • Have a running Looker instance
  • Have a Looker dashboard you want to embed in your web application or webpage
  • Be familiar with JavaScript and JavaScript promises.

What you'll learn

  • How to privately embed your Looker content with the Embed SDK
  • How to send and receive messages (actions and events) with your embedded Looker content with the Embed SDK

What you'll need

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

2. Preparations

You need to prepare your HTML and Looker instance before you can embed with the Embed SDK.

Add the embed iframe's container element

Inside your web page's HTML, create a div element and define an id attribute on it.

<div id="looker-embed" />

Allowlist the embed's domain in the Looker instance

You need to allowlist the embed's domain in your Looker instance.

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

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. Build the embed

Now let's create and configure the SDK's embed builder to "build" your embedded Looker content.

Initialize the SDK

First import and then initialize the SDK with the domain of your Looker instance.

// Import the Embed SDK as LookerEmbedSDK

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

Create the embed builder

Next, determine the ID of the Looker dashboard you want to embed. If your dashboard is at instance_name.looker.com/dashboard/12345, then your dashboard's ID is 12345.

Call the SDK createDashboardWithId() method with the dashboard ID to create an embed builder. This method will return the embed builder.

LookerEmbedSDK.createDashboardWithId(12345)

Configure and build the embed builder

Now, let's configure the embed builder before we tell it to build the embedded iframe. Add the following code sample directly after the previous code sample's createDashboardWithId() method call.

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

Each method of the embed builder returns the embed builder itself, so we chain the method calls together. Let's walk through each method:

  1. The appendTo() method determines the iframe's parent element. We pass in the id of the HTML element we defined previously in the Preparation step.
  2. The withFrameBorder() method sets the frame-border attribute on the iframe. This is one of several methods that define HTML attributes on the iframe.
  3. The build() method creates the iframe with the configured HTML attributes

Final check

With the previous steps, your code should look like this:

// Import the Embed SDK as LookerEmbedSDK

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

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

You now have your Looker dashboard embedded inside your webpage with the Embed SDK!

4. Send and receive embed messages

Now let's look at how to send and receive messages with your embedded Looker content with the Embed SDK. We call the messages your application sends to the iframe as actions, and call the messages your application receives from the iframe as events.

Receive events

Let's work with our previous code. To listen to events, we call the embed builder's on() method before we call the build() method.

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

Here we call the on() method to set an event listener on the dashboard:run:complete event coming from the iframe when the iframe is built. The event will tell us when the dashboard finishes loading. Check out the event reference for other events to listen to.

Send actions

Let's continue with our previous code. To send actions to the iframe, we call the embed builder's connect() method after we call the build() method to initialize message sending and receiving with the iframe.

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

Let's walk through this code sample:

  1. We call the connect() method which returns a promise. The promise resolves to an embed object representing the embedded iframe after the message sending and receiving mechanism has been initialized.
  2. We call the send() method on the embed object to send a dashboard:run action. Check out the actions reference for other actions to send.
  3. We add a catch() method in case there's any errors during initialization.

Final check

With the previous steps, your code should now look like this:

// 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!')

You now can communicate with your embedded Looker dashboard!

5. Additional information

Congratulations! You can now use the Embed SDK to privately embed your Looker dashboard and send and receive messages from the iframe. Check out these resources for further information: