Esta é a documentação do Looker. Para conferir a documentação do Looker Studio, acesse https://support.google.com/looker-studio.

Introdução ao SDK incorporado

O SDK de incorporação do Looker é uma biblioteca de funções que você pode adicionar ao código do seu aplicativo da Web baseado no navegador para gerenciar painéis, Looks e Explores incorporados 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.
Proporciona comunicação ponto a ponto para que não haja comunicação entre frames. O SDK de incorporação lida com mensagens de vários domínios transmitidas entre sua página da Web host e seu conteúdo incorporado do Looker, usando um canal de mensagem dedicado.

Sem o SDK incorporado, é possível invocar ou responder a eventos no conteúdo incorporado do Looker usando eventos JavaScript, como dashboard:run:start ou page:changed, que estão descritos na página 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 Looker e do SDK da API Looker:

O SDK do Looker Embed 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 nele.
Os SDKs do cliente da API Looker residem no código de aplicativos fora do navegador para fornecer acesso fácil à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 nos navegadores ou plataformas. Escreva seu JavaScript da forma adequada 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 dashboard e mostra um painel com um ID 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 interface da janela de incorporação, e um botão com o ID 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)
  })

Confira um exemplo mais completo na página de documentação Demonstração de incorporação do SDK.

Como 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 incorporado, você vai criar o conteúdo incorporado e se conectar a ele.

Como instalar o SDK de incorporação

Faça o download da biblioteca Embed SDK 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 de incorporação do Looker.

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

Instale o Node.js, se ainda não o tiver.
Faça o download ou clone o repositório /looker-open-source/embed-sdk.
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 seu servidor da Web e, opcionalmente, o endpoint no servidor que vai fazer a autenticação. Eles são usados por todo o conteúdo incorporado.

Inclua o número da porta se for necessário para acessar o servidor do Looker pelos clientes do navegador. Por exemplo: looker.example.com:443

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

Em seguida, o conteúdo incorporado é criado usando uma série de etapas para definir os parâmetros dele. Alguns desses parâmetros são opcionais e outros 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 Incorporação assinada).

LookerEmbedSDK.createDashboardWithId(id)

LookerEmbedSDK.createDashboardWithUrl(url)

Em seguida, adicione outros atributos ao builder para concluir a configuração. Por exemplo, você pode especificar em que parte da página da Web inserir a UI de incorporação do Looker. A chamada a seguir coloca a UI de incorporação do Looker dentro de um elemento HTML com um valor de ID de dashboard:

.appendTo('#dashboard')

Você pode adicionar manipuladores de eventos:

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

Para terminar, você precisa criar o elemento incorporado:

.build()

Como se conectar ao conteúdo incorporado

Se você quiser enviar e receber mensagens do elemento incorporado, chame 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 para URLs de incorporação assinados pelo Looker está na página de documentação Incorporação assinada. A única diferença ao criar URLs para o SDK é que você vai precisar adicionar um parâmetro sdk=2 ao URL incorporado com outros parâmetros, como filtros e embed_domain. Com esse parâmetro, o Looker consegue determinar se o SDK está presente e aproveitar outros recursos disponibilizados por ele. Exemplo:

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

O SDK não pode adicionar esse parâmetro por conta própria porque ele faz parte do URL de incorporação assinado.

O endpoint de autenticação

Como o secret de incorporação precisa ser protegido cuidadosamente, URLs de incorporação assinados não podem ser criados no navegador. Para tornar o processo mais fácil e seguro, siga estas etapas:

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 do GitHub Exemplos de SSO de incorporação do Looker.
Transmita o URL de incorporação assinado para esse endpoint de assinatura no SDK de incorporação. O local do endpoint é especificado pelo parâmetro authUrl no LookerEmbedSDK.init().

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

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

O exemplo anterior chamará o endpoint /looker_auth e retornará um URL de incorporação 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 de autenticação avançada

O endpoint de autenticação pode ser configurado ainda mais para permitir cabeçalhos de solicitação personalizados e suporte a 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ós

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 de incorporação é criado com base no chat. O Chatty usa debug para gerar registros. Para ativar a geração de registros em um console do navegador, use 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 = ''