Introdução ao SDK incorporado

O SDK incorporado do Looker é uma biblioteca de funções que podem ser adicionadas ao código do seu aplicativo da Web baseado em navegador para gerenciar painéis incorporados, visuais e explorações no seu aplicativo da Web. O SDK incorporado facilita a incorporação das seguintes maneiras:

  • Oferecer o encapsulamento do conteúdo incorporado sem a necessidade de criar manualmente elementos HTML.
  • Oferecer comunicação ponto a ponto para que não haja comunicação entre os frames. O SDK incorporado incorpora a transmissão de mensagens entre domínios entre a página da Web do host e o conteúdo do Looker incorporado, usando um canal de mensagens dedicado.

Sem o SDK incorporado, você pode invocar ou responder a eventos no conteúdo do Looker incorporado usando eventos JavaScript como dashboard:run:start ou page:changed, que são descritos na página de documentação sobre eventos de JavaScript incorporados. Os desenvolvedores que incorporam o conteúdo do Looker com eventos JavaScript precisam criar os elementos HTML para hospedar o conteúdo incorporado e confiar em eventos de transmissão de janela para comunicações entre o app da Web e o conteúdo incorporado.

O SDK incorporado do Looker é diferente da API Looker e do SDK da API Looker:

  • O SDK incorporado do Looker reside no código do lado do cliente do seu aplicativo da Web e gerencia o contexto e o conteúdo incorporados pelo Looker. O SDK incorporado não fornece acesso à API Looker.
  • A API Looker fica no servidor com sua instância do Looker e executa comandos no servidor do Looker.
  • Os SDKs do cliente da API Looker residem no código de aplicativos que não são de navegador para facilitar o acesso às funções da API Looker.

Saiba que o Looker não controla a ordem em que os navegadores enviam eventos para aplicativos da Web. Isso significa que a ordem dos eventos não é garantida em vários navegadores ou plataformas. Escreva seu JavaScript corretamente para lidar com o gerenciamento de eventos de diferentes navegadores.

Exemplo rápido

Este exemplo constrói um contexto de incorporação do Looker, insere-o em um elemento DOM com um ID de dashboard e exibe um painel com um ID de 11 no contexto de incorporação do Looker. Os eventos dashboard:run:start e dashboard:run:complete são usados para atualizar o estado da IU da janela de embedding, e um botão com um código de run é programado para enviar uma mensagem dashboard:run ao painel.

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

Um exemplo mais completo é descrito na página da documentação Incorporar demonstração do SDK.

Configurar o SDK incorporado do Looker

O SDK incorporado do Looker usa um padrão de interface fluente. Depois de instalar o SDK incorporado, você cria o conteúdo incorporado e se conecta ao conteúdo incorporado.

Como instalar o SDK incorporado

Acesse a biblioteca incorporada do SDK do Looker no Gerenciador de pacotes do nó (NPM, na sigla em inglês) em https://www.npmjs.com/package/@looker/embed-sdk. No entanto, se você quiser ver o exemplo de código ou a demonstração, use o repositório do SDK incorporado do Looker.

Para instalar o SDK do Looker Embed usando o repositório do SDK do Looker Embed:

  1. Instale o Node.js, caso ainda não tenha feito isso.
  2. Faça o download ou clone o repositório /looker-open-source/embed-sdk.
  3. Em uma janela do terminal, navegue até o diretório /embed-sdk e execute estes comandos:
npm install
npm start

Como criar o conteúdo incorporado

Primeiro, inicialize o SDK com o endereço do seu servidor da Web e, opcionalmente, o endpoint no servidor que realizará a autenticação. Elas são usadas por todo o conteúdo incorporado.

Inclua o número da porta se for necessário entrar em contato com o servidor Looker por meio de clientes de navegador. Por exemplo: looker.example.com:443

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

Em seguida, o conteúdo incorporado é criado seguindo uma série de etapas para definir os parâmetros. Alguns desses parâmetros são opcionais, outros são obrigatórios.

O processo começa com a criação do builder com um painel id ou um url que se refere a um painel (criado pelo processo descrito na página de documentação Incorporação de Logon único (SSO)).

LookerEmbedSDK.createDashboardWithId(id)

ou

LookerEmbedSDK.createDashboardWithUrl(url)

Em seguida, é possível adicionar outros atributos ao builder para concluir a configuração. Por exemplo, é possível especificar onde a página da Web do Looker deve ser inserida. A chamada a seguir coloca a IU incorporada do Looker em um elemento HTML com um valor de ID dashboard:

.appendTo('#dashboard')

É possível adicionar manipuladores de eventos:

.on('dashboard:run:start',
  () => updateState('#dashboard-state', 'Running')
)
.on('dashboard:run:complete',
  () => updateState('#dashboard-state', 'Done')
)

Para terminar, crie o elemento incorporado:

.build()

Como se conectar ao conteúdo incorporado

Se você quiser enviar mensagens e receber mensagens do elemento incorporado, vai precisar chamar connect(), que retorna uma promessa que é resolvida na interface de comunicação do elemento especificado:

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

Como criar URLs para o SDK

A documentação principal dos URLs de incorporação do SSO do Looker está disponível na página da documentação Incorporação de Logon único (SSO). A única diferença ao criar URLs para o SDK é que você precisará adicionar um parâmetro sdk=2 ao URL incorporado, além de outros parâmetros, como filtros e embed_domain. Com esse parâmetro, o Looker pode determinar se o SDK está presente e aproveitar os recursos adicionais oferecidos. Exemplo:

/embed/looks/4?embed_domain=https://mywebsite.com&sdk=2
                                                 ^^^^^^

O SDK não pode adicionar este parâmetro porque faz parte do URL do SSO assinado.

O endpoint de autenticação

Como a chave secreta de incorporação precisa ser protegida com cuidado, os URLs de SSO incorporados não podem ser criados no navegador. Para tornar o processo mais fácil e seguro, faça o seguinte:

  1. Implemente uma função de assinatura de URL no seu servidor da Web. O servidor retornará um URL assinado usando um dos processos documentados no repositório Exemplos de SSO incorporado do Looker (em inglês).
  2. Transmita o URL do SSO incorporado ao endpoint de assinatura no SDK incorporado. O local do endpoint é especificado pelo parâmetro authUrl em LookerEmbedSDK.init().

Se especificado, sempre que um elemento de incorporação for criado usando apenas um ID, o URL de incorporação dele será gerado usando o tipo do elemento, o host do Looker fornecido e os parâmetros fornecidos. Exemplo:

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

Isso chamará o endpoint /looker_auth e retornará um URL de SSO assinado que pode ser usado para criar o conteúdo incorporado:

src=https://looker.example.com/embed/dashboards/11?sdk=2&embed_host=https://yourhost.example.com

Configuração avançada do Authentication

É possível configurar ainda mais o endpoint de autenticação para permitir cabeçalhos de solicitação personalizados e suporte ao CORS. Para fazer isso, transmita um objeto de opções para o 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
  })

Auxiliar de nó

Um método auxiliar de assinatura createSignedUrl() é fornecido em server_utils/auth_utils.ts. Seu uso é o seguinte:

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 é a estrutura de dados do usuário:

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: {}
}

O parâmetro access_filters foi removido no Looker 3.10, mas ainda é necessário com um marcador vazio no URL incorporado.

Solução de problemas

Geração de registros

O SDK incorporado é criado com base no chatty. O Chatty usa debug para geração de registros. Ative a geração de registros em um console do navegador com 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 = ''