> [!NOTE]
> **Note:** This page is a reference for the Embed SDK 2.0.0. While the 2.0.0 API is backwards-compatible with Embed SDK 1.8.x, 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). We recommend that applications use the interfaces that have an 'I' prefix (the interfaces that have prefixes are identical to the interfaces that don't have them). Applications that are upgraded to SDK 2.0.0 should continue to work and behave as they did previously. To take advantage of the API improvements, some refactoring will be required. The following major changes are included in Embed SDK 2.0.0:
>
> - Navigating between dashboards, Explores, and Looks no longer requires that an iframe be recreated. 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 that is related only to a dashboard, a Look, or an Explore. The unified connection allows embedding applications to detect a user navigating inside of the iframe.
> - Support for additional Looker embedded content has been added for Looker reports and query visualizations.

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, reports, and Explores in your web app.

> [!NOTE]
> **Note:** Looker reports are available when the [Looker reports feature is enabled](https://docs.cloud.google.com/looker/docs/2622/enabling-studio-in-looker). Reports can be embedded with the signed embed method, cookieless embed method, or private embed method. For more details, see [Embed Looker reports](https://docs.cloud.google.com/looker/docs/2622/embed-reports.md.txt).

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 that there's no cross-frame communication. The Embed SDK handles cross-domain message passing between your host web page and your embedded Looker content, making use of a dedicated message channel.

Without the Embed SDK, you can invoke or respond to events in embedded Looker content by using JavaScript events such as [`dashboard:run:start`](https://docs.cloud.google.com/looker/docs/2622/embedded-javascript-events.md.txt#dashboard:run:start) or [`page:changed`](https://docs.cloud.google.com/looker/docs/2622/embedded-javascript-events.md.txt#page:changed), which are described on the [Embedded JavaScript events](https://docs.cloud.google.com/looker/docs/2622/embedded-javascript-events.md.txt#event_type_reference) documentation page. Developers who embed Looker content with JavaScript events must create the HTML elements to house the embedded content and rely on window broadcast events for communications between the web app and the embedded content.

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](https://docs.cloud.google.com/looker/docs/2622/api-getting-started.md.txt) lives on the server with your Looker instance and executes commands on the Looker server.
- [Looker API client SDKs](https://docs.cloud.google.com/looker/docs/2622/api-sdk.md.txt) reside in the code of non-browser applications to provide access to Looker API functions.

Be aware that Looker does not control the order in which browsers dispatch events to web applications. This means that the order of events is not guaranteed across browsers or platforms. Be sure to write your JavaScript appropriately to account for the event handling of different browsers.

## Quick example

In this example, a dashboard with an ID of `11` is created inside a DOM element with the ID `embed_container`. The [`dashboard:run:start`](https://docs.cloud.google.com/looker/docs/2622/embedded-javascript-events.md.txt#dashboard:run:start) and [`dashboard:run:complete`](https://docs.cloud.google.com/looker/docs/2622/embedded-javascript-events.md.txt#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.

```javascript
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 is described on the [Embed SDK demo](https://docs.cloud.google.com/looker/docs/2622/embed-sdk-demo.md.txt) documentation page.

## Setting up the Looker Embed SDK

The Looker Embed SDK uses a fluent interface pattern. Once you [install](https://docs.cloud.google.com/looker/docs/2622/embed-sdk-intro.md.txt#installing_the_embed_sdk) the Embed SDK, you then [construct the embedded content](https://docs.cloud.google.com/looker/docs/2622/embed-sdk-intro.md.txt#constructing_the_embedded_content) and [connect to the embedded content](https://docs.cloud.google.com/looker/docs/2622/embed-sdk-intro.md.txt#connecting_to_the_embedded_content). The hosting application may interact with the embedded content once the connection is established.

### 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](https://docs.cloud.google.com/looker/docs/2622/embed-sdk-demo.md.txt), you should instead use the Looker Embed SDK repository.

To install the Looker Embed SDK using the Looker Embed SDK repository, follow these steps:

1. Install [Node.js](https://nodejs.org/en/download/), if you don't already have it.
2. Download or clone the [`/looker-open-source/embed-sdk`](https://github.com/looker-open-source/embed-sdk) repository.
3. In a terminal window, navigate to the `/embed-sdk` directory and run these commands:

```javascript
npm install
npm start
```

### Constructing the embedded content

First, 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. These servers are used by all the embedded content. For private embedding, omit the signing endpoint.

> [!NOTE]
> **Note:** Include the port number if it's required to reach the Looker server from browser clients. For example: `looker.example.com:443`

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

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 either with a dashboard `id` or with a `url` that refers to a dashboard (created by the process that is described on the [Signed embedding](https://docs.cloud.google.com/looker/docs/2622/single-sign-on-embedding) documentation page).

```javascript
getEmbedSDK().createDashboardWithId('id')
```

or

```javascript
getEmbedSDK().createDashboardWithUrl('url')
```

You can then add additional attributes to the builder to complete your setup.

> [!NOTE]
> **Note:** The `create[ContentType]WithUrl` functions can be 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[ContentType]WithId`.

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 `dashboard`:

```javascript
.appendTo('#dashboard')
```

Add event handlers:

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

Create an embedded client by calling the build method:

```javascript
.build()
```

### Connecting to the embedded content

Once the client is built, call `connect` to create the iframe. The connect process creates the `src` attribute that is used for the actual iframe. The way that the `src` value is generated is based on how the embed SDK is initialized:

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

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

```javascript
  .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 being displayed and interact accordingly.

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

The iframe does not need to be recreated when different content needs to be loaded. Instead, the connection methods `loadDashboard`, `loadLook`, `loadExplore`, or `loadUrl` can be used. The `loadDashboard`, `loadLook`, and `loadExplore` methods accept an `id`. The `loadUrl` method accepts an embed `URL`, and this method can be used to specify additional parameters (such as filters).

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

If it is necessary to create a new iframe, the Embed SDK won't 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 in the following way:

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

## Signed URL auth endpoint

This section does not apply to cookieless embed. See [Cookieless embedding](https://docs.cloud.google.com/looker/docs/2622/cookieless-embed.md.txt) for details.

To use the Embed SDK, you must supply a backend service that handles signing of the embed URL. This service is called by the Embed SDK to generate a signed URL that is unique to the requesting user. The backend process can either generate the signed embed URL itself by using an embed secret, or the backend process can generate the URL by calling the [Looker Create Signed Embed URL API](https://docs.cloud.google.com/looker/docs/reference/looker-api/latest/methods/Auth/create_sso_embed_url.md.txt). Manual URL generation and signing avoids calling the Looker API, which decreases latency. Calling the Looker API requires less code and is easier to maintain.

A JavaScript example of a helper method that generates a signed URL, `createSignedUrl()`, can be found in [server/utils/auth_utils.ts](https://github.com/looker-open-source/embed-sdk/blob/master/server/utils/auth_utils.ts). It is used in the following way:

```javascript
import { createSignedUrl } from './utils/auth_utils'

app.get('/looker_auth', function (req, res) {
  // It is assumed that the request is authorized
  const src = req.query.src
  const host = 'looker.example.com'
  const secret = ... // Embed secret from Looker Server Embed Admin page
  const user = ... // Embedded user definition
  const url = createSignedUrl(src, user, host, secret)
  res.json({ url })
})
```

See the [python example in the repository](https://github.com/looker-open-source/embed-sdk/blob/master/server_utils/auth_utils.py).

### Signed URL advanced auth configuration

This section does not apply to cookieless embed. See [Cookieless embedding](https://docs.cloud.google.com/looker/docs/2622/cookieless-embed.md.txt) for details.

You can configure the auth endpoint to allow custom request headers and CORS support by passing an options object to the `init` method.

```javascript
getEmbedSDK().init('looker.example.com', {
  url: 'https://api.acme.com/looker/auth',
  headers: [{ name: 'Foo Header', value: 'Foo' }],
  params: [{ name: 'foo', value: 'bar' }],
  withCredentials: true, // Needed for CORS requests to Auth endpoint include Http Only cookie headers
})
```

## Troubleshooting

The Embed SDK is built on top of [chatty](https://github.com/looker-open-source/chatty). Chatty uses [debug](https://github.com/visionmedia/debug) for logging. You can enable logging in a browser console with this command:

````javascript
localStorage.debug = 'looker:chatty:*'
```none

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:

```javascript
localStorage.debug = ''
````