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, informes 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, y usa 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 acceso 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 crea un panel con un ID de 11 dentro de un elemento DOM con el ID embed_container. 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.

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

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. La aplicación de host puede interactuar con el contenido incorporado una vez que se establece la conexión.

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 del servidor de Looker y el extremo del servidor de aplicaciones de incorporación que creará una URL de acceso incorporada firmada de Looker. Todo el contenido incorporado usa estos servidores. Para la incorporación privada, omite el extremo de firma.

getEmbedSDK().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 panel id 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).

getEmbedSDK().createDashboardWithId('id')

o

getEmbedSDK().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')

Agrega controladores de eventos:

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

Llama al método de compilación para crear un cliente incorporado:

.build()

Cómo conectarse al contenido incorporado

Una vez que se compile el cliente, llama a connect para crear el iframe. El proceso de conexión crea el atributo src que se usa para el iframe real. La forma en que se genera el valor src se basa en cómo se inicializa el SDK incorporado:

  1. Firmado: Se llama al extremo que especifica el segundo argumento de la llamada init. Se espera que el extremo devuelva una URL de acceso de incorporación firmada.
  2. Sin cookies: Se llama al extremo o a la función que especifica el segundo argumento de la llamada a initCookieless. Se espera que el extremo o la función devuelvan tokens sin cookies, específicamente los tokens de autenticación y navegación. Los tokens se adjuntan a la URL de acceso incorporada.
  3. Privada: La conexión de incorporación es privada si no se proporciona el segundo argumento de la llamada a init. En este caso, la URL se deriva del compilador y se decora con los parámetros que se requieren para la incorporación de Looker. Para la incorporación privada, se espera que el usuario ya haya accedido a Looker o que la URL de incorporación incluya el parámetro allow_login_screen=true.

connect muestra un Promise que se resuelve en la interfaz de conexión del iframe incorporado.

  .connect()
  .then((connection) => {
    // Save the connection
  })
  .catch(console.error)

Interacción

El SDK de incorporación 2.0.0 muestra una conexión unificada que admite la interacción con todos los tipos de contenido de Looker. La aplicación de incorporación puede determinar qué tipo de contenido se muestra y, luego, interactuar según corresponda.

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

No es necesario volver a crear el iframe cuando se debe cargar contenido diferente. En su lugar, se pueden usar los métodos de conexión loadDashboard, loadLook, loadExplore o loadUrl. Los métodos loadDashboard, loadLook y loadExplore aceptan un id. El método loadUrl acepta un URL incorporado y se puede usar para especificar parámetros adicionales (como filtros).

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

Si es necesario crear un iframe nuevo, el SDK de Embed no volverá a llamar a los extremos de sesión de firma o adquisición. En su lugar, construirá el iframe src directamente desde el compilador. Si es necesario crear una nueva sesión de incorporación, se deberá volver a inicializar el SDK de incorporación de la siguiente manera:

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

Extremo de autenticación de URL firmada

Esta sección no se aplica a la incorporación sin cookies. Consulta Incorporación sin cookies para obtener más detalles.

Para usar el SDK de incorporación, debes proporcionar un servicio de backend que controle la firma de la URL de incorporación. El SDK de incorporación llama a este servicio para generar una URL firmada que sea única para el usuario solicitante. El proceso de backend puede generar la URL de incorporación firmada con un secreto de incorporación, o bien puede generar la URL llamando a la API de Create Signed Embed URL de Looker. La generación y firma de URLs manuales evita llamar a la API de Looker, lo que disminuye la latencia. Llamar a la API de Looker requiere menos código y es más fácil de mantener.

Puedes encontrar un ejemplo de JavaScript de un método de ayuda que genera una URL firmada, createSignedUrl(), en server/utils/auth_utils.ts. Se usa de la siguiente manera:

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

Consulta el ejemplo de Python en el repositorio.

Configuración de autenticación avanzada de URLs firmadas

Esta sección no se aplica a la incorporación sin cookies. Consulta Incorporación sin cookies para obtener más detalles.

Para configurar el extremo de autenticación de modo que permita encabezados de solicitud personalizados y compatibilidad con CORS, pasa un objeto de opciones al método init.

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

Soluciona problemas

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