Introdução ao SDK de incorporação

O SDK de incorporação do Looker é uma biblioteca de funções que pode ser adicionada ao código do seu aplicativo da Web baseado em navegador para gerenciar painéis incorporados, Looks, relatórios e análises detalhadas no seu app da Web.

O SDK de incorporação facilita a incorporação das seguintes maneiras:

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

Sem o SDK de incorporação, é possível invocar ou responder a eventos no conteúdo incorporado do Looker usando eventos JavaScript, como dashboard:run:start ou page:changed, que são descritos na página de documentação Eventos JavaScript incorporados. Os desenvolvedores que incorporam conteúdo do Looker com eventos JavaScript precisam criar os elementos HTML para armazenar o conteúdo incorporado e usar eventos de transmissão de janela para comunicações entre o app da Web e o conteúdo incorporado.

O SDK de incorporação do Looker é diferente da API e do SDK do Looker:

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

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 todos os navegadores ou plataformas. Escreva seu JavaScript de maneira adequada para considerar o processamento de eventos de diferentes navegadores.

Exemplo rápido

Neste exemplo, um painel com o ID 11 é criado dentro de um elemento DOM com o ID embed_container. Os eventos dashboard:run:start e dashboard:run:complete são usados para atualizar o estado da interface da janela de incorporação, e um botão com um ID de run é programado para enviar uma mensagem dashboard:run ao painel.

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

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

Configurar o SDK de incorporação do Looker

O SDK de incorporação do Looker usa um padrão de interface fluída. Depois de instalar o SDK de incorporação, construa o conteúdo incorporado e se conecte a ele. O aplicativo de hospedagem pode interagir com o conteúdo incorporado depois que a conexão é estabelecida.

Como instalar o SDK de incorporação

Você pode acessar a biblioteca do SDK de incorporação do Looker pelo gerenciador de pacotes do nó (NPM) em https://www.npmjs.com/package/@looker/embed-sdk. No entanto, se você quiser conferir o código de exemplo ou a demonstração, use o repositório do SDK do Embed do Looker.

Para instalar o SDK de incorporação do Looker usando o repositório do SDK de incorporação do Looker, siga estas etapas:

1. Instale o Node.js, se ainda não tiver.
2. Faça o download ou clone o repositório /looker-open-source/embed-sdk.
3. Em uma janela de 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 servidor do Looker e o endpoint do servidor do aplicativo de incorporação que vai criar um URL de login incorporado do Looker assinado. Esses servidores são usados por todo o conteúdo incorporado. Para a incorporação particular, omita o endpoint de assinatura.

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

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

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

getEmbedSDK().createDashboardWithId('id')

ou

getEmbedSDK().createDashboardWithUrl('url')

Em seguida, adicione outros atributos ao criador para concluir a configuração.

Por exemplo, é possível especificar onde inserir a UI de incorporação do Looker na sua página da Web. A chamada a seguir coloca a UI incorporada do Looker em um elemento HTML com um valor de ID de dashboard:

.appendTo('#dashboard')

Adicione manipuladores de eventos:

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

Crie um cliente incorporado chamando o método de build:

.build()

Como se conectar ao conteúdo incorporado

Depois que o cliente for criado, chame connect para criar o iframe. O processo de conexão cria o atributo src que é usado para o iframe real. A forma como o valor de src é gerado é baseada na inicialização do SDK incorporado:

1. Assinado: o endpoint especificado pelo segundo argumento da chamada init é chamado. O endpoint precisa retornar um URL de login de incorporação assinado.
2. Sem cookie: o endpoint ou a função especificada pelo segundo argumento da chamada initCookieless é chamado. O endpoint ou a função precisa retornar tokens sem cookies, especificamente os tokens de autenticação e navegação. Os tokens são anexados ao URL de login incorporado.
3. Particular: a conexão de incorporação é particular se o segundo argumento da chamada init não for fornecido. Nesse caso, o URL é derivado do builder e decorado com os parâmetros necessários para a incorporação do Looker. Para a incorporação privada, é esperado que o usuário já tenha feito login no Looker ou que o URL de incorporação inclua o parâmetro allow_login_screen=true.

connect retorna um Promise que é resolvido na interface de conexão do iframe incorporado.

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

Interação

O SDK Embedded 2.0.0 retorna uma conexão unificada que oferece suporte à interação com todos os tipos de conteúdo do Looker. O aplicativo de incorporação pode determinar o tipo de conteúdo que está sendo mostrado e interagir de acordo com isso.

if (connection.getPageType() === 'dashboards') {
  connection.asDashboardConnection().run()
} else (connection.getPageType() === 'looks') {
  connection.asLookConnection().run()
} else (connection.getPageType() === 'explore') {
  connection.asExploreConnection().run()
}

O iframe não precisa ser recriado quando um conteúdo diferente precisa ser carregado. Em vez disso, os métodos de conexão loadDashboard, loadLook, loadExplore ou loadUrl podem ser usados. Os métodos loadDashboard, loadLook e loadExplore aceitam um id. O método loadUrl aceita um URL incorporado e pode ser usado para especificar outros parâmetros, como filtros.

connection.loadDashboard('42')
// OR
connection.loadUrl('/embed/dashboards/42?state=california')

Se for necessário criar um novo iframe, o SDK de incorporação não vai chamar os endpoints de assinatura ou aquisição de sessão novamente. Em vez disso, ele vai criar o iframe src diretamente no builder. Se for necessário criar uma nova sessão de incorporação, o SDK vai precisar ser reinicializado da seguinte maneira:

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

Endpoint de autenticação de URL assinado

Esta seção não se aplica à incorporação sem cookies. Consulte Incorporação sem cookies para mais detalhes.

Para usar o SDK de incorporação, você precisa fornecer um serviço de back-end que processe a assinatura do URL de incorporação. Esse serviço é chamado pelo SDK de incorporação para gerar um URL assinado exclusivo para o usuário solicitante. O processo de back-end pode gerar o URL de incorporação assinado usando um segredo de incorporação ou chamar a API Create Signed Embed URL do Looker. A geração e a assinatura manuais de URLs evitam a chamada da API Looker, o que diminui a latência. Chamar a API Looker requer menos código e é mais fácil de manter.

Um exemplo em JavaScript de um método auxiliar que gera um URL assinado, createSignedUrl(), pode ser encontrado em server/utils/auth_utils.ts. Ele é usado da seguinte maneira:

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

Consulte o exemplo de Python no repositório.

Configuração de autenticação avançada de URL assinado

Esta seção não se aplica à incorporação sem cookies. Consulte Incorporação sem cookies para mais detalhes.

É possível configurar o endpoint de autenticação para permitir cabeçalhos de solicitação personalizados e suporte a CORS transmitindo um objeto de opções para o 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
})

Solução de problemas

O SDK incorporado é criado com base no chatty. O Chatty usa debug para gerar registros. É possível ativar 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 = ''