Introducción al SDK Embed

Nota: Esta página es una referencia para el SDK Embed 2.0.0. Aunque la API 2.0.0 es compatible con versiones anteriores del SDK Embed 1.8.x, la implementación subyacente ha cambiado en algunas funciones. El SDK 1.8.x exportó varias clases. El SDK 2.0.0 sustituye estas clases por interfaces marcadas como obsoletas (se identifican interfaces alternativas). Recomendamos que las aplicaciones usen las interfaces que tengan el prefijo "I" (las interfaces que tienen prefijos son idénticas a las que no los tienen). Las aplicaciones que se actualicen al SDK 2.0.0 deberían seguir funcionando y comportándose como antes. Para aprovechar las mejoras de la API, será necesario refactorizar el código. La versión 2.0.0 del SDK Embed incluye los siguientes cambios importantes:

• Para desplazarse entre paneles de control, Exploraciones y Looks, ya no es necesario volver a crear un iframe. En su lugar, se pueden usar los métodos loadDashboard, loadLook, loadExplore y loadUrl para desplazarse por el iframe de Looker.
• connect ahora devuelve una conexión unificada en lugar de una conexión relacionada únicamente con un panel de control, un Look o una exploración. La conexión unificada permite que las aplicaciones insertadas detecten cuando un usuario se desplaza por el iframe.
• Se ha añadido compatibilidad con contenido insertado de Looker adicional para los informes y las visualizaciones de consultas de Looker.

El SDK de inserción de Looker es una biblioteca de funciones que puedes añadir al código de tu aplicación web basada en navegador para gestionar los paneles, los Looks, los informes y los Exploraciones insertados en tu aplicación web.

Nota: Los informes de Looker están disponibles cuando la función de informes de Looker está habilitada. Los informes se pueden insertar con el método de inserción firmado, el método de inserción sin cookies o el método de inserción privado. Para obtener más información, consulta el artículo Insertar informes de Looker.

El SDK de inserción facilita la inserción de las siguientes formas:

• Proporciona la encapsulación del contenido insertado sin necesidad de crear elementos HTML manualmente.
• Proporciona comunicación punto a punto para que no haya comunicación entre marcos. El SDK de inserción gestiona la transferencia de mensajes entre dominios entre la página web host y el contenido de Looker insertado mediante un canal de mensajes específico.

Sin el SDK Embed, puedes invocar o responder a eventos en contenido de Looker insertado mediante eventos de JavaScript, como dashboard:run:start o page:changed, que se describen en la página de documentación Eventos de JavaScript insertados. Los desarrolladores que inserten contenido de Looker con eventos de JavaScript deben crear los elementos HTML para alojar el contenido insertado y usar eventos de emisión de ventanas para las comunicaciones entre la aplicación web y el contenido insertado.

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 para inserciones se encuentra en el código del lado del cliente de tu aplicación web y gestiona el contexto y el contenido de la inserción de Looker. El SDK de inserció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 de cliente de la API de Looker se encuentran 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 el 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 el código JavaScript correctamente para tener en cuenta la gestión de eventos de los distintos navegadores.

Breve ejemplo

En este ejemplo, se crea un panel de control 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 interfaz de usuario de la ventana insertada, y se programa un botón con el ID run para enviar un mensaje dashboard:run al panel de control.

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

Puede consultar un ejemplo más completo en la página de documentación de la demo del SDK de inserción.

Configurar el SDK de inserción de Looker

El SDK de Looker para insertar usa un patrón de interfaz fluida. Una vez que hayas instalado el SDK Embed, podrás crear el contenido insertado y conectarte a él. La aplicación de alojamiento puede interactuar con el contenido insertado una vez que se haya establecido la conexión.

Instalar el SDK de Embed

Puedes obtener la biblioteca del SDK de Looker para insertar 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 ejemplo o la demo, debes usar el repositorio del SDK de Looker Embed.

Para instalar el SDK de Looker Embed mediante 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 terminal, ve al directorio /embed-sdk y ejecuta estos comandos:

npm install
npm start

Crear el contenido insertado

Primero, inicialice el SDK con la dirección del servidor de Looker y el endpoint del servidor de la aplicación insertada que creará una URL de inicio de sesión insertada de Looker firmada. Todos los contenidos insertados usan estos servidores. Para la inserción privada, omite el endpoint de firma.

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

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

A continuación, se crea el contenido insertado siguiendo una serie de pasos para definir sus parámetros. Algunos de estos parámetros son opcionales y otros obligatorios.

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

getEmbedSDK().createDashboardWithId('id')

o

getEmbedSDK().createDashboardWithUrl('url')

Después, puede añadir atributos adicionales al creador para completar la configuración.

Nota: Las funciones create[ContentType]WithUrl se pueden usar tanto con la inserción con firma como con la inserción sin cookies a partir del SDK de inserción 2.0.0. Antes de la versión 2.0.0 del SDK de inserción, la inserción sin cookies solo admitía create[ContentType]WithId.

Por ejemplo, puede especificar en qué parte de su página web quiere insertar la interfaz de usuario de Looker. La siguiente llamada coloca la interfaz de usuario de Looker insertada dentro de un elemento HTML con el valor de ID dashboard:

.appendTo('#dashboard')

Añadir controladores de eventos:

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

Crea un cliente insertado llamando al método de compilación:

.build()

Conectarse al contenido insertado

Una vez que se haya creado el cliente, llama a connect para crear el iframe. El proceso de conexión crea el atributo src, que se usa para el iframe propiamente dicho. La forma en que se genera el valor src depende de cómo se inicialice el SDK de inserción:

1. Firmado: se llama al endpoint especificado por el segundo argumento de la llamada init. El endpoint debe devolver una URL de inicio de sesión insertada firmada.
2. Sin cookies: se llama al endpoint o a la función especificados en el segundo argumento de la llamada initCookieless. Se espera que el endpoint o la función devuelvan tokens sin cookies, concretamente los tokens de autenticación y de navegación. Los tokens se añaden a la URL de inicio de sesión insertada.
3. Privada: la conexión de inserción es privada si no se proporciona el segundo argumento de la llamada init. En este caso, la URL se deriva del generador y se decora con los parámetros necesarios para la inserción de Looker. En el caso de las inserciones privadas, se espera que el usuario ya haya iniciado sesión en Looker o que la URL de inserción incluya el parámetro allow_login_screen=true.

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

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

Interactuar

Embed SDK 2.0.0 devuelve una conexión unificada que permite interactuar con todos los tipos de contenido de Looker. La aplicación insertada puede determinar qué tipo de contenido se muestra e 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 objeto id. El método loadUrl acepta una inserción URL 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 nuevo iframe, el SDK de inserción no volverá a llamar a los endpoints de firma ni de adquisición de sesión. En su lugar, creará el iframe src directamente desde el creador. Si es necesario crear una nueva sesión de inserción, el SDK de inserción deberá reinicializarse de la siguiente manera:

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

Endpoint de autenticación de URL firmada

Esta sección no se aplica a la inserción sin cookies. Para obtener más información, consulta Insertar sin cookies.

Para usar el SDK de inserción, debes proporcionar un servicio de backend que gestione la firma de la URL de inserción. El SDK de inserción llama a este servicio para generar una URL firmada que sea única para el usuario que hace la solicitud. El proceso de backend puede generar la URL de inserción firmada por sí mismo mediante un secreto de inserción o puede generar la URL llamando a la API Create Signed Embed URL de Looker. La generación y la firma manuales de URLs evitan llamar a la API de Looker, lo que reduce la latencia. Llamar a la API de Looker requiere menos código y es más fácil de mantener.

Puedes consultar 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 URLs firmadas

Esta sección no se aplica a la inserción sin cookies. Para obtener más información, consulta Insertar sin cookies.

Puede configurar el endpoint de autenticación para permitir encabezados de solicitud personalizados y compatibilidad con CORS. Para ello, debe pasar 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
})

Solución de problemas

El SDK de inserción se basa en chatty. Chatty usa debug para registrar datos. 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 = ''