Mensagens incorporadas do iframe do Looker

1. Antes de começar

O conteúdo do Looker precisa ser incorporado em um iframe com incorporação privada ou incorporação de SSO. Neste codelab, interagiremos com seu iframe via JavaScript para tornar sua página da Web mais dinâmica. Sua página da Web vai enviar e receber mensagens do conteúdo do Looker incorporado do iframe.

Pré-requisitos

O que você vai aprender

  • Como preparar a instância do iframe e do Looker para a interação com JavaScript
  • Como detectar eventos do seu iframe
  • Como enviar mensagens de ação para seu iframe

O que é necessário

  • Acesso ao HTML e JavaScript do código de front-end que gerencia o iframe
  • Acesso às configurações de incorporação do administrador na sua instância do Looker

2. Preparações

É preciso preparar o iframe e a instância do Looker antes de interagir com o iframe.

Adicionar um atributo id ao iframe

Você vai precisar validar as mensagens enviadas pelo iframe. Para fazer isso, defina um atributo id no iframe:

<iframe 
    id="looker"
    src="https://instance_name.looker.com/embed/dashboards/1"
>
</iframe>

Adicionar o domínio da incorporação ao atributo src do iframe

Determine o domínio da página da Web que hospeda o iframe. Digamos que o URL da página da Web seja https://mywebsite.com/with/embed. O domínio da página da Web é https://mywebsite.com.

Se você estiver usando a Inserção privada, adicione o domínio como um parâmetro de consulta embed_domain no src do iframe:

<iframe
    id="looker"
    src="https://instance_name.looker.com/embed/dashboards/1?embed_domain=https://mywebsite.com"
>
</iframe>

Se você estiver usando a Inserção de SSO, adicione o domínio como um parâmetro de consulta embed_domain ao URL de incorporação.

Colocar o domínio da incorporação na lista de permissões na instância do Looker

Por fim, inclua o domínio da incorporação na sua instância do Looker na lista de permissões para permitir o envio de mensagens.

Navegue até a página Incorporar na seção Administrador da instância do Looker. https://your_instance.looker.com/admin/embed

No campo Permissão de domínios incorporados, digite o domínio da incorporação. Depois de digitar, pressione a tecla Tab para que o domínio apareça em uma caixa. Não inclua uma barra final /.

Selecione o botão Atualizar.

3. Ouvir mensagens de eventos do iframe

Seu iframe com conteúdo incorporado do Looker envia mensagens para a página da Web do host. Essas mensagens de evento contêm informações oportunas sobre o conteúdo incorporado do Looker, como se o painel incorporado começou a carregar ou se o usuário selecionou a opção "Download" no conteúdo incorporado. Vamos receber e analisar esses eventos.

Entender o esquema de objetos de evento

O esquema do objeto de evento é:

{
  type: "...",
  eventSpecificProperty1: ...,
  eventSpecificProperty2: ...,
  ...
}

O evento sempre terá uma propriedade type que permite determinar qual é o evento. Todas as outras propriedades específicas do evento são definidas na nossa referência de eventos.

Receber e analisar o evento

Adicione isso ao local em que o JavaScript da sua página da Web inicializa ou gerencia o iframe:

window.addEventListener("message", function(message) {
  const iframeElement = document.getElementById("looker");
  if (message.source === iframeElement.contentWindow) {
    if (message.origin === "https://instance_name.looker.com") {
      const event = JSON.parse(message.data);
      switch (event.type):
        case "dashboard:run:start":
          console.log("The embedded dashboard has started loading"); 
    }
  }
});

O snippet de código faz o seguinte:

  1. Detecta o evento "message" do objeto window.
  2. Verifica se a propriedade source da mensagem é o iframe com o conteúdo incorporado do Looker.
  3. Verifica se a propriedade origin da mensagem é o domínio da instância do Looker.
  4. O JSON analisa a propriedade data da mensagem para acessar e analisar o objeto de evento.
  5. Ativa a propriedade type do objeto de evento para determinar qual evento é e agir de acordo com ele.

Agora, a página da Web do host pode reagir dinamicamente aos eventos emitidos pelo conteúdo incorporado do Looker.

4. Enviar mensagem de ação para o iframe

A página da Web host também pode enviar mensagens para o conteúdo do Looker incorporado do iframe. Essas mensagens de ação podem mudar o estado do conteúdo incorporado do Looker, como atualizar os filtros no seu painel incorporado. Vamos criar uma mensagem de ação que orienta o painel incorporado a executar as consultas e enviar a mensagem ao iframe.

Criar uma mensagem de ação

Crie uma mensagem de ação no JavaScript da sua página da Web:

const action = { type: "dashboard:run" };
const actionJSONFormatted = JSON.stringify(action);

O objeto action segue o mesmo formato do objeto event anterior. Ele sempre terá uma propriedade type e, em seguida, vai realizar propriedades específicas de ação que são definidas na nossa referência de ação. A mensagem de ação precisa estar no formato JSON.

Enviar a mensagem de ação

No JavaScript da sua página da Web, envie a ação formatada em JSON para o iframe:

const iframeElement = document.getElementById("looker");
iframeElement.contentWindow.postMessage(actionJSONFormatted, 'https://instance_name.looker.com');
  1. Determine o iframe para onde você vai enviar a ação.
  2. Chame o método postMessage() na propriedade contentWindow do iframe para enviar a mensagem.

Agora sua página da Web host pode mudar dinamicamente o estado do conteúdo incorporado do Looker.

5. Informações adicionais

Parabéns! Agora é possível detectar eventos e enviar ações para o conteúdo do Looker incorporado do seu iframe. Confira estes recursos para mais informações: