Introducción al SDK de Embed

El SDK de incorporación de Looker es una biblioteca de funciones que puedes agregar al código de tu aplicación web basada en el navegador para administrar paneles, looks y exploraciones incorporados en tu app web. El SDK de incorporación facilita la incorporación de las siguientes maneras:

  • Proporciona el encapsulamiento del contenido incorporado sin necesidad de crear elementos HTML de forma manual.
  • Proporcionar comunicación punto a punto para que no haya comunicación entre tramas El SDK de incorporación controla el paso de mensajes entre dominios entre tu página web host y tu contenido incorporado de Looker, con un canal de mensajes dedicado.

Sin el SDK de incorporación, puedes invocar o responder eventos en el contenido incorporado de Looker con eventos de JavaScript, como dashboard:run:start o page:changed, que se describen en la página de documentación Eventos de JavaScript incorporados. Los desarrolladores que incorporan contenido de Looker con eventos de JavaScript deben crear los elementos HTML para alojar el contenido incorporado y depender de los eventos de transmisión de ventanas para las comunicaciones entre la app web y el contenido incorporado.

Ten en cuenta que el SDK de incorporación de Looker es diferente de la API de Looker y del SDK de la API de Looker:

  • El SDK de incorporación de Looker se encuentra en el código del cliente de tu aplicación web y administra el contexto y el contenido de incorporación de Looker. (el SDK de incorporación no proporciona acceso a la API de Looker).
  • La API de Looker reside en el servidor con tu instancia de Looker y ejecuta comandos en el servidor de Looker.
  • Los SDKs cliente de la API de Looker residen en el código de aplicaciones que no son de navegador para proporcionar un acceso sencillo a las funciones de la API de Looker.

Ten en cuenta que Looker no controla el orden en que los navegadores envían eventos a las aplicaciones web. Esto significa que el orden de los eventos no está garantizado en todos los navegadores o plataformas. Asegúrate de escribir tu código JavaScript de forma adecuada para tener en cuenta el manejo de eventos de los diferentes navegadores.

Ejemplo rápido

En este ejemplo, se construye un contexto de incorporación de Looker, se inserta en un elemento DOM con un ID de dashboard y, luego, se muestra un panel con un ID de 11 en el contexto de incorporación de Looker. Los eventos dashboard:run:start y dashboard:run:complete se usan para actualizar el estado de la IU de la ventana de incorporación, y se escribe una secuencia de comandos para un botón con un ID de run para enviar un mensaje dashboard:run al panel.

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

En la página de documentación de la demo de incorporación del SDK, se describe un ejemplo más completo.

Cómo configurar el SDK de incorporación de Looker

El SDK de incorporación de Looker usa un patrón de interfaz fluida. Una vez que instales el SDK de Embed, construirás el contenido incorporado y te conectarás a él.

Instala el SDK de Embed

Puedes obtener la biblioteca del SDK de incorporación de Looker a través del administrador de paquetes de nodos (NPM) en https://www.npmjs.com/package/@looker/embed-sdk. Sin embargo, si quieres ver el código de muestra o la demo, debes usar el repositorio del SDK de Looker Embed.

Para instalar el SDK de incorporación de Looker con el repositorio del SDK de incorporación de Looker, sigue estos pasos:

  1. Instala Node.js si aún no lo tienes.
  2. Descarga o clona el repositorio de /looker-open-source/embed-sdk.
  3. En una ventana de terminal, navega al directorio /embed-sdk y ejecuta estos comandos:
npm install
npm start

Cómo construir el contenido incorporado

Primero, inicializa el SDK con la dirección de tu servidor web y, de manera opcional, el extremo de tu servidor que realizará la autenticación. Todos los contenidos incorporados los usan.

Incluye el número de puerto si es necesario para llegar al servidor de Looker desde clientes de navegador. Por ejemplo: looker.example.com:443

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

Luego, el contenido incorporado se compila con una serie de pasos para definir sus parámetros. Algunos de estos parámetros son opcionales y otros son obligatorios.

El proceso comienza con la creación del compilador, ya sea con un id de panel o con un url que haga referencia a un panel (creado por el proceso que se describe en la página de documentación de Integración firmada).

LookerEmbedSDK.createDashboardWithId(id)

o

LookerEmbedSDK.createDashboardWithUrl(url)

Luego, puedes agregar atributos adicionales al compilador para completar la configuración. Por ejemplo, puedes especificar en qué parte de tu página web insertar la IU incorporada de Looker. La siguiente llamada coloca la IU incorporada de Looker dentro de un elemento HTML con un valor de ID de dashboard:

.appendTo('#dashboard')

Puedes agregar controladores de eventos:

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

Para terminar, compila el elemento incorporado:

.build()

Cómo conectarse al contenido incorporado

Si quieres enviar y recibir mensajes del elemento incorporado, debes llamar a connect(), que muestra una promesa que se resuelve en la interfaz de comunicación del elemento determinado:

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

Cómo compilar URLs para el SDK

La documentación principal de las URLs de incorporación firmadas de Looker se encuentra en la página de documentación Incorporación firmada. La única diferencia cuando creas URLs para el SDK es que deberás agregar un parámetro sdk=2 a la URL de incorporación junto con otros parámetros, como los filtros y el parámetro embed_domain. Este parámetro permite que Looker determine que el SDK está presente y aproveche las funciones adicionales que proporciona. Por ejemplo:

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

El SDK no puede agregar este parámetro porque forma parte de la URL de incorporación firmada.

El extremo de autenticación

Debido a que el secreto de incorporación debe protegerse cuidadosamente, no se pueden crear URLs de incorporación firmadas en el navegador. Para que el proceso sea más fácil y seguro, puedes seguir estos pasos:

  1. Implementa una función de firma de URL en tu servidor web. El servidor debe mostrar una URL firmada con uno de los procesos documentados en el repositorio de GitHub Looker Embed SSO Examples.
  2. Pasa la URL de incorporación firmada a ese extremo de firma en el SDK de incorporación. El parámetro authUrl en LookerEmbedSDK.init() especifica la ubicación del extremo.

Si se especifica, cada vez que se crea un elemento incorporado con solo un ID, su URL de incorporación se genera con el tipo del elemento, el host de Looker proporcionado y los parámetros proporcionados. Por ejemplo:

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

El ejemplo anterior llamará al extremo /looker_auth y mostrará una URL de incorporación firmada que se puede usar para crear el contenido incorporado:

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

Configuración de autenticación avanzada

El extremo de autenticación se puede configurar para permitir encabezados de solicitud personalizados y compatibilidad con CORS. Para ello, pasa un objeto de opciones al método init:


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

Ayudante de nodos

En server_utils/auth_utils.ts, se proporciona un método de ayuda de firma createSignedUrl(). Su uso es el siguiente:

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 });
});

Esta es la estructura de los datos del usuario:

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: {}
}

El parámetro access_filters se quitó en Looker 3.10, pero aún es obligatorio con un marcador de posición vacío en la URL de incorporación.

Soluciona problemas

Logging

El SDK de incorporación se compila sobre chatty. Chatty usa depuración para el registro. Puedes habilitar el registro en la consola de un navegador con este comando:

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