Looker’s embed SDK is a library of functions that you can add to the code of your browser-based web application to manage embedded dashboards, Looks, and Explores in your web app. The embed SDK facilitates embedding in the following ways:
- Providing the encapsulation of the embedded content without the need to manually create HTML elements.
- Providing point-to-point communication so there’s no cross-frame communication. The embed SDK handles cross-domain message passing between your host webpage and your embedded Looker content, making use of a dedicated message channel.
Note that the Looker embed SDK is different from the Looker API and the Looker API SDK:
- The Looker embed SDK lives in the client-side code of your web application and manages the Looker embed context and content. (The embed SDK does not provide access to the Looker API).
- The Looker API lives on the server with your Looker instance and executes commands on the Looker server.
- Looker API client SDKs reside in the code of non-browser applications to provide easy access to Looker API functions.
This example constructs a Looker embed context, inserts it into a DOM element with an ID of
dashboard, and then displays a dashboard with an ID of
11 in the Looker embed context. The
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.
A more complete example is described on the Embed SDK demo documentation page.
Setting up the Looker embed SDK
The Looker embed SDK uses a fluent interface pattern. Once you install the embed SDK, you then construct the embedded content and connect to the embedded content.
Installing the embed SDK
You can get Looker’s embed SDK library through the node package manager (NPM) at https://www.npmjs.com/package/@looker/embed-sdk. However, if you want to see the sample code or the demo, you should instead use the Looker embed SDK repository.
To install the Looker embed SDK using the Looker embed SDK repo:
- Install Node.js, if you don’t already have it.
- Download or clone the
- In a terminal window, navigate to the
/embed-sdkdirectory and run these commands:npm install npm start
Constructing the embedded content
First, initialize the SDK with address of your web server and, optionally, the endpoint on your server that will perform authentication. These are used by all the embedded content.
Include the port number if it is required to reach the Looker server from browser clients. For example:
Then the embedded content is built using a series of steps to define its parameters. Some of these parameters are optional, and some are mandatory.
The process starts with creating the builder with a dashboard
id, or a
url that refers to a dashboard (created by the process described on the Single sign-on (SSO) embedding documentation page).
You can then add additional attributes to the builder to complete your setup. For example, you can specify where in your web page to insert the Looker embed UI. The following call places the Looker embed UI inside an HTML element with an ID value of
You can add event handlers:
You finish by building the embedded element:
Connecting to the embedded content
If you want to send messages to and receive messages from the embedded element, you need to call
connect(), which returns a Promise that resolves to the communication interface of the given element:
Building URLs for the SDK
The main documentation for Looker SSO embed URLs is on the Single sign-on (SSO) embedding documentation page. The only difference when creating URLs for the SDK is that you will need to add an
sdk=2 parameter to the Embed URL alongside other parameters like filters and the
embed_domain parameter. This parameter allows Looker to identify that the SDK is present and can take advantage of additional features provided by the SDK. For example:
The SDK cannot add this parameter itself because it is part of the signed SSO URL.
The Auth endpoint
Because the embed secret needs to be carefully guarded, embed SSO URLs cannot be created in the browser. To make the process easier and secure, you can instead do the following:
- Implement a URL signing function in your web server. The server should return a signed URL using one of the processes documented in the Looker Embed SSO Examples Github repository.
- Pass the embed SSO URL to that signing endpoint in the embed SDK. The location of the endpoint is specified by the
If specified, whenever an embed element is created using just an ID, its embed URL is generated using the type of the element, the provided Looker host, and any provided parameters. For example:
This will call the
/looker_auth endpoint and return a signed SSO URL that can be used to create the embedded content:
Advanced Auth configuration
The Auth endpoint can be configured further to allow custom request headers as well as CORS support. You can do this by passing an options object to the
A signing helper method
createSignedUrl() is provided in
server_utils/auth_utils.ts. Its usage is as follows:
This is the user data structure:
access_filtersparameter was removed in Looker 3.10, but it is still required with an empty placeholder in the embed URL.
The embed SDK is built on top of chatty. Chatty uses debug for logging. You can enable logging in a browser console with this command:
localStorage.debug = 'looker:chatty:*'
Note that both the parent window and the embedded content have separate local storage, so you can enable logging on one, the other, or both. You can disable logging with this command:
localStorage.debug = ''