Introducción al SDK de Embed

Nota: Esta página es una referencia para el SDK de Embed 2.0.0. Si bien la API 2.0.0 es retrocompatible con el SDK de Embed 1.8.x, la implementación subyacente cambió para algunas funciones. El SDK 1.8.x exportó varias clases. El SDK 2.0.0 reemplaza estas clases con interfaces que se marcan como obsoletas (se identifican interfaces alternativas). Recomendamos que las aplicaciones usen las interfaces que tienen un prefijo "I" (las interfaces que tienen prefijos son idénticas a las que no los tienen). Las aplicaciones que se actualizan al SDK 2.0.0 deberían seguir funcionando y comportándose como lo hacían antes. Para aprovechar las mejoras de la API, se requerirá una refactorización. Los siguientes cambios importantes se incluyen en el SDK de Embed 2.0.0:

• Navegar entre paneles, Explorar y Looks ya no requiere que se vuelva a crear un iframe. En su lugar, se pueden usar los métodos loadDashboard, loadLook, loadExplore y loadUrl para navegar dentro del iframe de Looker.
• connect ahora muestra una conexión unificada en lugar de una conexión que solo está relacionada con un panel, un Look o una exploración. La conexión unificada permite que las aplicaciones de incorporación detecten a un usuario que navega dentro del iframe.
• Se agregó compatibilidad con contenido incorporado adicional de Looker para informes de Looker y visualizaciones de consultas.

El SDK de Embed de Looker es una biblioteca de funciones que puedes agregar al código de tu aplicación web basada en navegador para administrar paneles, Looks, informes y Explorar incorporados en tu app web.

Nota: Los informes de Looker están disponibles cuando se habilita la función de informes de Looker. Los informes se pueden incorporar con el método de incorporación firmado, el método de incorporación sin cookies o el método de incorporación privada. Para obtener más detalles, consulta Incorpora informes de Looker.

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

• Proporciona la encapsulación del contenido incorporado sin la necesidad de crear elementos HTML de forma manual.
• Proporciona comunicación de 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 incorporado de Looker, mediante un canal de mensajes dedicado.

Sin el SDK de Embed, puedes invocar o responder a eventos en 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 de 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 Embed de Looker es diferente de la API de Looker y del SDK de la API de Looker:

• El SDK de Embed de Looker reside en el código del cliente de tu aplicación web y administra el contexto y el contenido incorporados 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 cliente de la API de Looker residen en el código de aplicaciones que no son navegadores 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 JavaScript de forma adecuada para tener en cuenta el control de eventos de 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 un botón con un ID de run está programado 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)
}

Se describe un ejemplo más completo en la página de documentación de la demostración del SDK de Embed.

Cómo configurar el SDK de Embed de Looker

El SDK de Embed de Looker usa un patrón de interfaz fluida. Una vez que instalas el SDK de Embed, compilas el contenido incorporado y te conectas a él. La aplicación de hosting puede interactuar con el contenido incorporado una vez que se establece la conexión.

Cómo instalar el SDK de Embed

Puedes obtener la biblioteca del SDK de Embed 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 demostración, debes usar el repositorio del SDK de Embed de Looker.

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

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

npm install
npm start

Cómo compilar el contenido incorporado

Primero, inicializa el SDK con la dirección del servidor de Looker y el extremo del servidor de la aplicación de incorporación que creará una URL de acceso incorporada de Looker firmada. Todos los contenidos incorporados usan estos servidores. Para la incorporación privada, omite el extremo de firma.

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

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 con un panel id o con un url que hace 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.

Nota: Las funciones create[ContentType]WithUrl se pueden usar con la incorporación firmada y sin cookies a partir del SDK de Embed 2.0.0. Antes del SDK de Embed 2.0.0, la incorporación sin cookies solo admitía create[ContentType]WithId.

Por ejemplo, puedes especificar en qué lugar de tu página web insertar la IU de incorporación de Looker. La siguiente llamada coloca la IU de incorporación 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 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 src se basa en la forma en que se inicializa el SDK de Embed:

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

connect muestra una Promise que se resuelve en la interfaz de conexión para el iframe incorporado.

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

Interacciones

El SDK de Embed 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 en consecuencia.

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 una URL incorporada, y este método 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 ni de adquisición de sesión. En su lugar, compilará el iframe src directamente desde el compilador. Si es necesario crear una sesión incorporada nueva, se deberá reinicializar el SDK de Embed 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 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 la firma manuales de la URL 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.

Puedes encontrar un ejemplo de JavaScript de un método auxiliar 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 avanzada 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.

Puedes configurar el extremo de autenticación para permitir encabezados de solicitud 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 = ''