Looker

Developers

Looker

Developers

    Starting June 2022, API 3.x is deprecated. Read our deprecation notice to see how this affects you.

    SSO Embedding with Embed SDK

    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.

    Without the embed SDK, you can invoke or respond to events in embedded Looker content using JavaScript events such as dashboard:run:start or page:changed, which are described on the Embedded JavaScript events 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 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.

    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

    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: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.

    LookerEmbedSDK.init('looker.example.com', '/auth')
    const setupDashboard = (dashboard) => {
    document.querySelector('#run').addEventListener('click', () => {
    dashboard.send('dashboard:run')
    })
    }
    LookerEmbedSDK.createDashboardWithId(11)
    .appendTo('#dashboard')
    .on('dashboard:run:start',
    () => updateState('#dashboard-state', 'Running')
    )
    .on('dashboard:run:complete',
    () => updateState('#dashboard-state', 'Done')
    )
    .build()
    .connect()
    .then(setupDashboard)
    .catch((error: Error) => {
    console.error('An unexpected error occurred', error)
    })

    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:

    1. Install Node.js, if you don't already have it.
    2. Download or clone the /looker-open-source/embed-sdk repository.
    3. In a terminal window, navigate to the /embed-sdk directory 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: looker.example.com:443

    LookerEmbedSDK.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 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).

    LookerEmbedSDK.createDashboardWithId(id)

    or

    LookerEmbedSDK.createDashboardWithUrl(url)

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

    .appendTo('#dashboard')

    You can add event handlers:

    .on('dashboard:run:start',
    () => updateState('#dashboard-state', 'Running')
    )
    .on('dashboard:run:complete',
    () => updateState('#dashboard-state', 'Done')
    )

    You finish by building the embedded element:

    .build()
    ## 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:

    .connect()
    .then(setupDashboard)
    .catch(console.error)

    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:

    /embed/looks/4?embed_domain=https://mywebsite.com&sdk=2
    ^^^^^^

    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:

    1. 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.
    2. Pass the embed SSO URL to that signing endpoint in the embed SDK. The location of the endpoint is specified by the authUrl parameter in LookerEmbedSDK.init().

    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:

    LookerEmbedSDK.init('looker.example.com', '/looker_auth')
    LookerEmbedSDK.createcreateDashboardWithId(11)
    .build()

    This will call the /looker_auth endpoint and return a signed SSO URL that can be used to create the embedded content:

    src=https://looker.example.com/embed/dashboards/11?sdk=2&embed_host=https://yourhost.example.com

    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 init method:

    LookerEmbedSDK.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
    })

    Node helper

    A signing helper method createSignedUrl() is provided in server_utils/auth_utils.ts. Its usage is as follows:

    import { createSignedUrl } from './auth_utils'
    app.get('/looker_auth', function(req, res) {
    // TO DO: Add your code here to authenticate that the request is from a valid user
    const src = req.query.src;
    const host = 'https://looker.example.com'
    const secret = YOUR_EMBED_SECRET
    const user = authenticatedUser
    const url = createSignedUrl(src, user, host, secret);
    res.json({ url });
    });

    This is the user data structure:

    interface LookerEmbedUser {
    external_user_id: string
    first_name?: string
    last_name?: string
    session_length: number
    force_logout_login?: boolean,
    permissions: LookerUserPermission[]
    models: string[]
    group_ids?: number[]
    external_group_id?: string
    user_attributes?: {[key: string]: any}
    access_filters: {}
    }

    The access_filters parameter was deprecated in Looker 3.10, but it is still required with an empty placeholder in the embed URL.

    Troubleshooting

    Logging

    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 = ''

    Build on Examples and Tutorials

    Python SDK Examples

    Source code examples and projects that use SDKs to communicate with the Looker API.

    Language Specific Content

    Content related to the language that is currently selected or generic content that works for all languages.

    Data from a Look to a Block

    The Get Look Data Block contains an API call for retrieving the results of a Look.

    Keep up with Looker developer updates

    API

    OverviewGetting StartedInteractive ReferenceAdvanced UsageExamples & SamplesArticles & Tutorials

    Embedding

    OverviewGetting StartedEmbed SDKAdvanced EmbeddingTroubleshooting

    Actions

    OverviewGetting StartedWriting Custom ActionsExamples & Samples

    Extensions

    OverviewGetting StartedAPI ReferenceExamples & Samples

    Components

    OverviewGetting StartedInteractive ReferenceDesign FoundationsVisualization Components

    Marketplace

    OverviewGetting StartedVisit the Marketplace

    Community

    EventsForumsOpen Source

    © 2021 Looker Data Sciences, Inc.
    Privacy | Terms | Cookies