Introducción al SDK de Embed

El SDK de Embed de Looker es una biblioteca de funciones que puedes agregar al código de tu aplicación web basada en el navegador para administrar los paneles, las Looks, los informes y las Exploraciones integrados en tu aplicación web.

El SDK de Embed facilita la incorporación de las siguientes maneras:

  • Proporciona la encapsulación 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 marcos El SDK de Embed controla el paso de mensajes entre dominios entre tu página web host y tu contenido de Looker incorporado, y utiliza un canal de mensajes dedicado.

Sin el SDK de Embed, puedes invocar eventos en el contenido de Looker integrado o responder a ellos con eventos de JavaScript, como dashboard:run:start o page:changed, que se describen en la página de documentación de eventos de JavaScript integrados. 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 Looker Embed es diferente de la API de Looker y del SDK de la API de Looker:

  • El SDK de Looker Embed se encuentra en el código del cliente de tu aplicación web y administra el contexto y el contenido de la incorporación de Looker. (El SDK de Embed 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 de cliente de la API de Looker residen en el código de las 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 control de eventos de los diferentes navegadores.

Ejemplo rápido

En este ejemplo, se crea un panel con el ID 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 programa 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 demostración del SDK de Embed, se describe un ejemplo más completo.

Cómo configurar el SDK de Looker Embed

El SDK de Looker Embed usa un patrón de interfaz fluida. Una vez que instales el SDK de Embed, construye el contenido integrado y conéctate a él. La aplicación de hosting 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 Embed de Looker a través del administrador de paquetes de Node (NPM) en https://www.npmjs.com/package/@looker/embed-sdk. Sin embargo, si quieres ver el código de muestra o la demostración, debes usar el repositorio del SDK de Looker Embed.

Para instalar el SDK de Looker Embed con el repositorio del SDK de Looker Embed, sigue estos pasos:

  1. Instala Node.js si aún no lo tienes.
  2. Descarga o clona el repositorio /looker-open-source/embed-sdk.
  3. En una ventana de la 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 la aplicación incorporada que creará una URL de acceso incorporado firmada de Looker. Todos los servidores de contenido incorporado utilizan estos servidores. Para la incorporación privada, omite el extremo de firma.

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

Luego, el contenido integrado 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 Incorporació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 de Looker integrada. La siguiente llamada coloca la IU de Looker integrada 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')
)

Crea un cliente integrado llamando al método build:

.build()

Conexión al contenido incorporado

Una vez que se compila 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 de src se basa en cómo se inicializa el SDK de Embed:

  1. Firmado: Se llama al extremo que se especifica en el segundo argumento de la llamada a init. Se espera que el extremo muestre una URL de acceso integrada firmada.
  2. Sin cookies: Se llama al extremo o a la función que se especifica en 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 agregan a la URL de acceso integrada.
  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 necesarios para la incorporación de Looker. En el caso de 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 devuelve un Promise que se resuelve en la interfaz de conexión del iframe integrado.

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

Interacciones

El SDK de Embed 2.0.0 devuelve 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 objeto URL de incorporación, 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 firma o adquisición de sesión. En cambio, construirá el iframe src directamente desde el compilador. Si es necesario crear una nueva sesión de incorporación, el SDK de Embed deberá reinicializarse de la siguiente manera:

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

Extremo de autorizació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 Embed, debes proporcionar un servicio de backend que controle la firma de la URL de incorporación. El SDK de Embed 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 por sí mismo con un secreto de incorporación, o bien puede generar la URL llamando a la API de Looker Create Signed Embed URL. La generación y firma manuales de URLs evitan 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.

En server/utils/auth_utils.ts, puedes encontrar un ejemplo en JavaScript de un método auxiliar que genera una URL firmada, createSignedUrl(). 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 avanzada de autenticación 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.

Puedes configurar el extremo de autorización para permitir encabezados de solicitudes personalizados y compatibilidad con CORS pasando 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 Embed se basa en chatty. Chatty usa debug para el registro. Puedes habilitar el registro en una consola del 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 = ''