Introducción al SDK de incorporación

El SDK de inserció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 los paneles incorporados, las apariencias y las exploraciones en tu aplicación 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.
  • Proporciona una comunicación punto a punto para que no haya comunicación entre marcos. El SDK de incorporación administra el paso de mensajes entre dominios entre la página web del host y el contenido incorporado de Looker mediante un canal de mensajes dedicado.

Sin el SDK de Embed, puedes invocar o responder eventos en el contenido integrado de Looker mediante 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 basarse en eventos de transmisión de ventanas para las comunicaciones entre la aplicación web y el contenido incorporado.

Ten en cuenta que el SDK de Looker para incorporaciones es diferente de la API de Looker y el 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 Embed no proporciona acceso a la API de Looker).
  • La API de Looker reside en el servidor con su instancia de Looker y ejecuta comandos en el servidor de Looker.
  • Los SDK de cliente de la API de Looker residen en el código de aplicaciones que no son de navegador para brindar un acceso fácil a las funciones de la API de Looker.

Ten en cuenta que Looker no controla el orden en el que los navegadores envían los 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 manera adecuada para tener en cuenta el manejo de eventos de 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 genera un script con un botón con un ID de run para enviar un mensaje de 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)
  })

Puedes encontrar un ejemplo más detallado en la página de documentación Demostración del SDK de incorporación.

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 instales el SDK incorporado, construirás el contenido incorporado y te conectarás al contenido incorporado.

Cómo instalar el SDK de Embed

Puedes obtener la biblioteca del SDK de Embed para Looker mediante el administrador de paquetes de nodo (NPM) en https://www.npmjs.com/package/@looker/embed-sdk. Sin embargo, si deseas 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 mediante el repositorio del SDK de Embed de Looker, haz lo siguiente:

  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 la terminal, navega al directorio /embed-sdk y ejecuta estos comandos:
npm install
npm start

Crea el contenido incorporado

Primero, inicializa el SDK con la dirección de tu servidor web y, opcionalmente, el extremo de tu servidor que realizará la autenticación. Todo el contenido incorporado las usa.

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

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

Luego, el contenido incorporado se crea mediante 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 un url que hace referencia a un panel (creado por el proceso descrito en la página de documentación Incorporación de inicio de sesión único [SSO]).

LookerEmbedSDK.createDashboardWithId(id)

o

LookerEmbedSDK.createDashboardWithUrl(url)

Luego, puedes agregar atributos adicionales al compilador para completar tu configuración. Por ejemplo, puedes especificar dónde se insertará la IU de incorporación de Looker en tu página web. 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')

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

Conexión con el contenido incorporado

Si deseas 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 dado:

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

Compila URL para el SDK

La documentación principal de las URL de incorporación de SSO de Looker se encuentra en la página de documentación Incorporación de inicio de sesión único (SSO). La única diferencia cuando creas URL para el SDK es que deberás agregar un parámetro sdk=2 a Embed URL junto con otros parámetros, como filtros y embed_domain. Este parámetro permite que Looker determine que el SDK está presente y que aproveche las funciones adicionales que proporciona el SDK. 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 SSO firmada.

El extremo de Auth

Debido a que el secreto de incorporación debe protegerse cuidadosamente, las URL de SSO incorporadas no se pueden crear en el navegador. Para facilitar y asegurar el proceso, puedes hacer lo siguiente:

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

Si se especifica, cada vez que se crea un elemento incorporado con solo un ID, su URL incorporada se genera con el tipo de elemento, el host de Looker proporcionado y cualquier parámetro proporcionado. Por ejemplo:

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

Esto llamará al extremo /looker_auth y mostrará una URL de SSO 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 avanzada de autenticación

El extremo de Auth se puede configurar aún más 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
  })

Asistente de nodo

En server_utils/auth_utils.ts, se proporciona un método auxiliar 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: {}
}

Se quitó el parámetro access_filters en Looker 3.10, pero aún se requiere con un marcador de posición vacío en la URL incorporada.

Soluciona problemas

Registros

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