Looker Embedding with Embed SDK

Published in

Google Cloud - Community

5 min readFeb 9, 2023

Introduction:

In the previous blog of the Single Sign-On (SSO) Embedding Looker Content in Web Application, we discussed Embedding of Looker dashboards with SSO based approach (without Embed SDK). In this article, we will be define how to make use of Looker Embed SDK to integrate with our application.

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

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.

Prerequisites:

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 /looker-open-source/embed-sdk repository.
In a terminal window, navigate to the /embed-sdk directory and run these commands:

npm install

Implementation:

NOTE : Before me move to the implementation, make sure you do not share your Looker secrets with anyone, do not reset your secrets once created and do not store the secrets in your web browser.

Step 1: Enable embedding in your Looker instance

Navigate to Admin > Platform Embed on your Looker instance. This requires Admin privileges.
The demo server runs by default at http://localhost:8080. By adding that address to the Embedded Domain Allowlist you can enable the demo to receive messages from Looker.
Turn on Embed Authentication.
In order to view your embed secret you must reset it. Copy the secret to a secure place.

Step 2: Customize the demo settings for your Looker instance

Provide your embed secret to the server. You can do this a couple ways:

Set it as LOOKER_EMBED_SECRET in your shell environment.
Create a file named .env in the root of the sdk directory. Add a line to that file: LOOKER_EMBED_SECRET="YourLookerSecret"

The following is a template that can be used to create the file (in the root of this repo). The .env file should never be stored in your git repo and is included in the repo's .ignore file.

LOOKER_EMBED_HOST=mycompany.looker.com
LOOKER_EMBED_API_URL=https://mycompany.looker.com:19999
LOOKER_DEMO_HOST=localhost
LOOKER_DEMO_PORT=8080
LOOKER_EMBED_SECRET=
LOOKER_CLIENT_ID=
LOOKER_CLIENT_SECRET=
LOOKER_DASHBOARD_ID=1
LOOKER_LOOK_ID=1
LOOKER_EXPLORE_ID=thelook::orders
LOOKER_EXTENSION_ID=extension::my-great-extension
COOKIE_SECRET=cookie_stash

Provide your Looker instance host address to the server by either:

Setting it as LOOKER_EMBED_HOST in your shell environment.
Adding LOOKER_EMBED_HOST="yourinstance.looker.com:yourport" to the .env file.

Edit the demo/demo_config.ts file to be appropriate for the pages you want to embed.

// The address of your Looker instance. Required.
export const lookerHost = 'self-signed.looker.com:9999'

// A dashboard that the user can see. Set to 0 to disable dashboard.
export const dashboardId = 1
// A Look that the user can see. Set to 0 to disable look.
export const lookId = 1

Edit the demo/demo_user.json file to be appropriate for the type of user you want to embed.

{
  // External embed user ID. IDs are not shared with regular users. Required
  "external_user_id": "user1",
  // First and last name. Optional
  "first_name": "Pat",
  "last_name": "Embed",
  // Duration before session expires, in seconds. Required.
  "session_length": 3600,
  // Enforce logging in with these permissions. Recommended.
  "force_logout_login": true,
  // External embed group ID. Optional.
  "external_group_id": "group1",
  // Looker Group IDs. Optional
  "group_ids": [],
  // Permissions. See documentation for details. Required.
  // Can any combination of:
  //   access_data
  //   see_looks
  //   see_user_dashboards
  //   see_lookml_dashboards
  //   explore
  //   create_table_calculations
  //   download_with_limit
  //   download_without_limit
  //   see_drill_overlay
  //   see_sql
  //   save_content
  //   embed_browse_spaces
  //   schedule_look_emails
  //   send_to_sftp
  //   send_to_s3
  //   send_outgoing_webhook
  //   schedule_external_look_emails
  "permissions": [
    "access_data",
    "see_looks",
    "see_user_dashboards",
    "explore"
    "save_content",
    "embed_browse_spaces"
  ],
  // Model access permissions. Required.
  "models": ["powered_by", "thelook"],
  // User attributes. Optional.
  "user_attributes": { "locale": "en_US" },
}

Embed Group

In the Groups pane, add a new Group, let’s call it the Embed Group. Once created, go back to the Roles pane, and add this group to the SSO Permissions role.

Step 3: Build and run the demo

Node server

Run npm install
Run npm start

The server will print out what host and port it is running on. If it is different than http://localhost:8080 then you will need to add it to your Embedded Domain Allowlist.

If you want to use the demo_self_signed.py example you will need to update packages.json and replace demo.py with demo_self_signed.py.

Logging

The Embed SDK is built on top of chatty. Chatty uses debug for logging. You can enable logging in a browser console with

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

localStorage.debug = ''

Conclusion:

I hope with this article and this Looker Embedding article series, you will have fair understanding of how Embedding in Looker works and which embedding option best fit your use case. With minimum efforts, you can integrate your Looker Dashboards or Looks in your existing Web Application and make it more interactive for the users.

References:

Reach out to me at LinkedIn for more inputs around Looker Embedding or anything related to Google Cloud Platform.