Introdução ao SDK de incorporação

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

• A navegação entre painéis, Explores e Looks não exige mais a recriação de um iframe. 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 um Explore. 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 Embed do Looker é uma biblioteca de funções que podem ser adicionadas ao código do aplicativo da Web baseado em navegador para gerenciar painéis, Looks, relatórios e Explores incorporados no 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, o método de incorporação sem cookies ou o método de incorporação particular. 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.
• Fornecendo comunicação ponto a ponto para que não haja comunicação entre frames. O SDK Embed 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 Embed, é 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 de 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 dependem de eventos de transmissão de janela para comunicações entre o app da Web e o conteúdo incorporado.

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

• O SDK Embed do Looker fica no código do lado do cliente do aplicativo da Web e gerencia o contexto e o conteúdo incorporados do Looker. O SDK Embed não fornece acesso à API Looker.
• A API Looker fica no servidor com a 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 do navegador 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 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 um ID de 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 Embed.

Como configurar o SDK Embed do Looker

O SDK Embed do Looker usa um padrão de interface fluente. Depois de instalar o SDK Embed, você então cria o conteúdo incorporado e se conecta a ele. O aplicativo de hospedagem pode interagir com o conteúdo incorporado depois que a conexão é estabelecida.

Como instalar o SDK Embed

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

Para instalar o SDK Embed do Looker usando o repositório do SDK Embed do Looker, siga estas etapas:

1. Instale o Node.js, se ainda não tiver.
2. Faça o download ou clone o /looker-open-source/embed-sdk repositório.
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 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 ela for necessária 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 com um painel id ou com um url que se refere a um painel (criado pelo processo descrito na página de documentação de incorporação assinada).

getEmbedSDK().createDashboardWithId('id')

ou

getEmbedSDK().createDashboardWithUrl('url')

Em seguida, você pode adicionar outros atributos ao builder para concluir a configuração.

Observação: As funções create[ContentType]WithUrl podem ser usadas com incorporação assinada e sem cookies a partir do SDK Embed 2.0.0. Antes do SDK Embed 2.0.0, a incorporação sem cookies só oferecia suporte a create[ContentType]WithId.

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

.appendTo('#dashboard')

Adicionar 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 é criado, chame connect para criar o iframe. O processo de conexão cria o atributo src usado para o iframe real. A maneira como o valor src é gerado depende de como o SDK Embed é inicializado:

1. Assinado: o endpoint especificado pelo segundo argumento da chamada init é chamado. Espera-se que o endpoint retorne um URL de login incorporado assinado.
2. Sem cookies: o endpoint ou a função especificada pelo segundo argumento da chamada initCookieless é chamado. 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. 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 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 na interface de conexão do iframe incorporado.

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

Interação

O SDK Embed 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 que tipo de conteúdo 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, 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 de incorporação, e esse método 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 de aquisição de sessão novamente. Em vez disso, ele vai criar o src do iframe 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 Embed, é necessário fornecer um serviço de back-end que processe a assinatura do URL de incorporação. Esse serviço é chamado pelo SDK Embed 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 Create Signed Embed URL do Looker. A geração e a assinatura manuais de URL 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 de 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 do 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 a depuração 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 = ''