Mensagens incorporadas do iframe do Looker

1. Antes de começar

Você precisa ter conteúdo do Looker 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 incorporado do Looker no iframe.

Pré-requisitos

O que você vai aprender

  • Como preparar sua 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 o 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ê terá que validar as mensagens provenientes do 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 e o domínio dela seja https://mywebsite.com.

Se você usar a embedding particular, 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 Incorporaçã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, você precisa autorizar o domínio da incorporação na instância do Looker para permitir o envio de mensagens.

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

No campo Permitir domínio incorporado, digite o domínio da incorporação. Depois de digitá-lo, 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 do Looker incorporado, por exemplo, se o dashboard 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 esta linha ao local em que o JavaScript da sua página da Web inicializa ou gerencia seu 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 é o evento e realizar ações com base nele.

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 do host também pode enviar mensagens para o conteúdo incorporado do Looker no iframe. Essas mensagens de ação podem mudar o estado do conteúdo incorporado do Looker, como atualizar os filtros do dashboard 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. Ela sempre terá uma propriedade type e, em seguida, ações específicas, 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 que vai receber 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 ao conteúdo do Looker incorporado no seu iframe. Confira estes recursos para mais informações: