Looker JavaScript Embed SDK

Embed SDK version 2.0.0

The following document has been updated to reflect the creation of Embed SDK 2.0.0. Technically the 2.0.0 API is backwards compatible with Embed SDK 1.8.x but the underlying implementation has changed for some functionality. SDK 1.8.x exported a number of classes. SDK 2.0.0 replaces these classes with interfaces that are marked as deprecated (alternative interfaces are identified). It is preferred that applications use the 'I' prefixed interfaces (which are identical to the non prefixed interfaces). Applications upgrading to SDK 2.0.0 should behave the same. In order to take advantage of the API improvements some refactoring will be required.

The major changes included in Embed SDK 2.0.0 are:

Navigating between Dashboards, Explores and Looks no longer requires the recreation of an IFRAME. Instead the loadDashboard, loadLook, loadExplore and loadUrl methods can be used to navigate within the Looker IFRAME.
connect now returns a unified connection rather than a connection related to a Dashboard, Look or Explore. The unified connection allows embedding applications to be aware of the user navigating inside of the IFRAME.
Support for additional Looker embedded content has been added:
- Reports.
- Query Visualizations.

Introduction

The Looker JavaScript Embed SDK is designed to facilitate using Looker embedded content in a web application. The goal is to make communication between a host website and one or more embedded Dashboards, Looks, Explores, Reports and Extensions easier and more reliable.

The Looker JavaScript Embed SDK typically uses embed SSO to sign an embed url in order to authenticate the user of the embedded content. This mechanism relies on Looker cookies being available to the embedded IFRAME in order for the application to work. It is recommended that customers use vanity domains where the embedded server and the Looker server run on the same domain but different subdomains. By doing this third party cookie blocking is mitigated (as the cookies are no longer third party). Alternatively Looker provides a mechanism that allows embedded Looker IFRAMEs to work without the need for cookies. Details can be found here.

A typical setup might look like this. In this case, a dashboard with an id of 11 is created inside a DOM element with the id embed_container. The dashboard:run:start and dashboard:run:complete events are used to update the state of the embedding window's UI, and a button with an id of run is scripted to send a dashboard:run message to the dashboard.

getEmbedSDK().init('looker.example.com', '/auth')

const setupConnection = (connection) => {
  document.querySelector('#run').addEventListener('click', () => {
    connection.asDashboardConnection().run()
  })
}

try {
  connection = await getEmbedSDK()
    .createDashboardWithId('11')
    .appendTo('#embed_container')
    .on('dashboard:run:start', () => updateStatus('Running'))
    .on('dashboard:run:complete', () => updateStatus('Done'))
    .build()
    .connect()
  setupConnection(connection)
} catch (error) {
  console.error('An unexpected error occurred', error)
}

A more complete example can be found here and here.

Details

The Looker Embed SDK uses the fluent interface pattern. The construction of the embedded content is broken into two phases, building and connecting. The hosting application may interact with the embedded content once the connection is established.

Building

Initialize the SDK with the address of the Looker server and the endpoint of the embedding application server that will create a signed Looker embedded login URL (for private embedding, omit the signing endpoint).

getEmbedSDK().init('looker.example.com', '/auth')

In this example, /auth is a backend service that must be implemented as described in the Signed URL Auth Endpoint section.

After the SDK is initialized, create the builder using an id or URL. For example, to create a Dashboard embed builder do one of the following:

getEmbedSDK().createDashboardWithId('42')
// OR
getEmbedSDK().createDashboardWithUrl('/embed/dashboards/42?state=california')

The create[ContentType]WithUrl functions can used with both signed and cookieless embed starting with Embed SDK 2.0.0. Prior to Embed SDK 2.0.0, Cookieless Embed only supported create[CotentType]WithId.

Additional attributes can be added to the builder to complete the setup:

  .appendTo('#dashboard')

Event handlers can be added:

  .on('dashboard:run:start',
      () => updateStatus('Running')
  )
  .on('dashboard:run:complete',
      () => updateStatus('Done')
  )

Create an embedded client by calling the build method:

  .build()

Connecting

Once the client is built, call connect to create the IFRAME. The connect process creates the src attribute used for the actual IFRAME. How the src value is generated is based upon how the embed SDK is initialized.

Signed - the endpoint specified by the 2nd argument of the init call is called. The endpoint is expected to return a signed embed login URL.
Cookieless - the endpoint or the function specified by the 2nd argument of the initCookieless call is called. The endpoint or function is expected to return cookieless tokens, in particular the authentication and navigation tokens. The tokens are appended to the embed login URL.
Private - the embed connection is private if the 2nd argument of the init call is not provided. In this case the URL is derived from the builder and decorated with the parameters required for Looker embed. For private embed, it is expected that the user is already logged into Looker OR that embedding URL include the allow_login_screen=true parameter.

connect returns a Promise that resolves to the connection interface for the embedded IFRAME.

  .connect()
  .then((connection) => {
    // Save the connection
  })
  .catch(console.error)

Interacting

Embed SDK 2.0.0 returns a unified connection that supports interacting with all Looker content types. The Embedding application can determine what kind of content is currently being displayed and interact accordingly.

if (connection.getPageType() === 'dashboards') {
  connection.asDashboardConnection().run()
} else (connection.getPageType() === 'looks') {
  connection.asLookConnection().run()
} else (connection.getPageType() === 'explore') {
  connection.asExploreConnection().run()
}

It is no longer necessary to recreate the IFRAME when there is a need to load different content. Instead the connection loadDashboard, loadLook, loadExplore or loadUrl methods can be used. The loadDashboard, loadLook, loadExplore methods accept an id. The loadUrl method accepts an Embed URL and so can be used to specify additional parameters, filters for example.

connection.loadDashboard('42')
// OR
connection.loadUrl('/embed/dashboards/42?state=california')

If it is necessary to create a new IFRAME, the Embed SDK will not call the signing or acquire session endpoints again. Instead it will construct IFRAME src directly from the builder. Should it be necessary to create a new Embed session, the Embed SDK will need to be reinitialized as follows:

getEmbedSDK(new LookerEmbedExSDK()).init('looker.example.com', '/auth')

Building URLs for the SDK

The Embed SDK 2.0.0 now supports URL building for cookieless embed.

The main documentation for Looker SSO embed URLs is here.

The Embed SDK will sanitize the URL if necessary:

It will strip hostname and protocol if present.
It will prefix the URL with /embed if missing.
It will add the sdk parameter if missing.
It will add the embed_domain parameter if missing.
It will throw an error if the URL is invalid.

/embed/looks/4?embed_domain=https://mywebsite.com becomes /embed/looks/4?embed_domain=https://mywebsite.com&sdk=3.