Introdução ao SDK de incorporação

Observação:esta página é uma referência para o SDK de incorporação 2.0.0. Embora a API 2.0.0 seja compatível com versões anteriores do SDK de incorporação 1.8.x, a implementação subjacente mudou para algumas funcionalidades. O SDK 1.8.x exportou várias classes. O SDK 2.0.0 substitui essas classes por interfaces marcadas como descontinuadas (interfaces alternativas são identificadas). Recomendamos que os aplicativos usem as interfaces com um prefixo "I". As interfaces com e sem prefixos são idênticas. Os aplicativos atualizados para o SDK 2.0.0 vão continuar funcionando e se comportando como antes. Para aproveitar as melhorias da API, será necessário fazer uma refatoração. As seguintes mudanças importantes estão incluídas no SDK de incorporação 2.0.0:

• Não é mais necessário recriar um iframe para navegar entre painéis, análises detalhadas e Looks. Em vez disso, os métodos loadDashboard, loadLook, loadExplore e loadUrl podem ser usados para navegar no iframe do Looker.
• O connect agora retorna uma conexão unificada em vez de uma conexão relacionada apenas a um painel, um Look ou uma análise detalhada. A conexão unificada permite que os aplicativos de incorporação detectem um usuário navegando dentro do iframe.
• Adicionamos suporte a mais conteúdo incorporado do Looker para relatórios e visualizações de consultas do Looker.

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, Looks, relatórios e análises detalhadas incorporados no seu app da Web.

Observação: os relatórios do Looker ficam disponíveis quando o recurso de relatórios do Looker está ativado. Os relatórios podem ser incorporados com o método de incorporação assinada, sem cookies ou privada. Para mais detalhes, consulte Incorporar relatórios do Looker.

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

• Fornecendo o encapsulamento do conteúdo incorporado sem a necessidade de criar manualmente elementos HTML.
• 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 sua página da Web 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 hospedar 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 do Looker e do SDK da API 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 dá acesso à API Looker.
• A API 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 o ID 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 fluente. Depois de instalar o SDK de incorporação, crie o conteúdo incorporado e conecte-se 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 ver o código de exemplo ou a demonstração, use o repositório do SDK de incorporação do Looker.

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

1. Instale o Node.js, se ainda não tiver feito isso.
2. Baixe ou clone o repositório /looker-open-source/embed-sdk.
3. Em uma janela de terminal, acesse o diretório /embed-sdk e execute estes comandos:

npm install
npm start

Como construir o conteúdo incorporado

Primeiro, inicialize o SDK com o endereço do servidor do Looker e o endpoint do servidor de aplicativos de incorporação que vai criar um URL de login incorporado assinado do Looker. Esses servidores são usados por todo o conteúdo incorporado. Para incorporação particular, omita o endpoint de assinatura.

Observação: inclua o número da porta se for necessário para acessar o servidor do Looker em clientes de navegador. Por exemplo: looker.example.com:443

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 usando um painel id ou um url que se refere a um painel (criado pelo processo descrito na página de documentação Incorporação assinada).

getEmbedSDK().createDashboardWithId('id')

ou

getEmbedSDK().createDashboardWithUrl('url')

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

Observação: as funções create[ContentType]WithUrl podem ser usadas com incorporações assinadas e sem cookies a partir do SDK de incorporação 2.0.0. Antes do SDK de incorporação 2.0.0, a incorporação sem cookies só era compatível com create[ContentType]WithId.

Por exemplo, é possível especificar onde inserir a interface 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 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 no iframe real. A forma como o valor src é gerado depende de como o SDK de incorporação é inicializado:

1. Assinado: o endpoint especificado pelo segundo argumento da chamada init é chamado. O endpoint precisa retornar um URL de login incorporado assinado.
2. Sem cookies: o endpoint ou a função especificada pelo segundo argumento da chamada initCookieless é chamada. Espera-se que o endpoint ou a função retorne tokens sem cookies, especificamente os tokens de autenticação e navegação. Os tokens são anexados ao URL de login incorporado.
3. Privada: a conexão de incorporação é privada 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 incorporação particular, espera-se 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 uma Promise que é resolvida para a interface de conexão do iframe incorporado.

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

Interação

O SDK de incorporação 2.0.0 retorna uma conexão unificada que permite interagir com todos os tipos de conteúdo do Looker. O aplicativo de incorporação pode determinar o tipo de conteúdo que está sendo exibido e interagir de acordo.

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, use os métodos de conexão loadDashboard, loadLook, loadExplore ou loadUrl. Os métodos loadDashboard, loadLook e loadExplore aceitam um id. O método loadUrl aceita uma incorporação URL 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 Embed não vai chamar os endpoints de assinatura ou aquisição de sessão novamente. Em vez disso, ele vai construir o iframe src diretamente do builder. Se for necessário criar uma nova sessão de incorporação, o SDK Embed 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 chamando a API Looker Create Signed Embed URL. A geração e a assinatura manuais de URLs evitam chamar a API Looker, o que diminui a latência. Chamar a API Looker exige 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 })
})

Confira o exemplo em Python no repositório.

Configuração avançada 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.

É 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 Embed é criado com base no chatty. O Chatty usa debug para geração de 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 = ''