Skip to main content

Incorporação Estática

Incorporação estática

Também conhecido como: incorporação independente ou incorporação assinada.

Em geral, a incorporação funciona exibindo uma URL do Analytics dentro de um iframe no seu site. Uma incorporação estática (ou incorporação assinada) é um iframe que carrega uma URL do Analytics protegida por um JSON Web Token (JWT) assinado. O Analytics só carregará a URL se a requisição fornecer um JWT assinado com o segredo compartilhado entre seu app e seu Analytics. O JWT também inclui referência ao recurso a ser carregado, por exemplo, o ID do dashboard, e quaisquer valores para parâmetros bloqueados.

Você não pode usar incorporações estáticas com data sandboxes, drill-through, e dados específicos do usuário não são capturados em analytics de uso porque os JWTs assinados não criam sessões de usuário (sessões no servidor). Para esses recursos, veja incorporação interativa.

Você pode, no entanto, restringir dados em incorporações estáticas para pessoas ou grupos específicos bloqueando parâmetros (locked parameters).

Como a incorporação estática funciona

Se quiser configurar filtros interativos do Analytics no seu iframe, seu servidor web precisará fazer requisições ao Analytics para obter dados atualizados cada vez que um visitante atualizar um widget de filtro.

Para solicitar dados atualizados do Analytics, seu servidor web gerará uma nova URL de incorporação do Analytics. Por exemplo, se um visitante do site inserir o valor “true” em um widget de filtro incorporado, seu servidor web gerará uma nova URL de incorporação com um parâmetro extra:

your_analytics_embedding_url?filter=true

Para evitar que pessoas editem a URL de incorporação para acessar outras partes do seu Analytics (por exemplo, alterando o parâmetro para filter=company_secrets), seu servidor web adicionará um JWT assinado à nova URL de incorporação:

your_analytics_embedding_url/your_signed_jwt?filter=true

O JWT assinado é gerado usando sua chave secreta do Analytics. Essa chave informa ao Analytics que a requisição para os dados filtrados pode ser confiável, então é seguro exibir os resultados na nova URL de incorporação. Note que essa chave secreta é compartilhada por todas as incorporações estáticas, então quem tiver acesso a essa chave terá acesso a todos os artefatos incorporados.

Se quiser incorporar gráficos com recursos interativos adicionais, como drill-down e querying self-service, veja Incorporação interativa.

Ativando o recurso de incorporação no Analytics

  1. Acesse Configurações > Configurações administrativas > Incorporação.
  2. Ative a opção Habilitar incorporação.

Tornando uma pergunta ou dashboard incorporável

Botão para compartilhar e incorporar dashboard

Para criar uma incorporação estática:

  1. Acesse a pergunta ou dashboard que deseja incorporar no seu site.
  2. Clique no ícone de compartilhamento.
  3. Selecione Incorporar.
  4. Selecione Incorporação estática.
  5. Opcional: personalize a aparência da incorporação.
  6. Opcional: adicione parâmetros à incorporação.
  7. Clique em Publicar.

Pré-visualização

Adicionando a URL de incorporação ao seu site

A URL de incorporação para uma pergunta ou dashboard é a URL do Analytics que será exibida no iframe do seu site. Ela é gerada pelo seu servidor web usando a URL do site do Analytics, JWT assinado e parâmetros:

analytics_site_url/embed/question/your_jwt_token?parameter_name=value

Depois de tornar uma pergunta ou dashboard incorporável, você precisará incluir a URL de incorporação para ela no seu site:

  1. Acesse a pergunta ou dashboard > ícone de compartilhamento > Incorporar.
  2. Faça as alterações desejadas e copie o código.
  3. Pré-visualize o código.
  4. Adicione o código ao código do servidor que gera seu site.
  5. Adicione o código de frontend à página onde deseja que o item incorporado apareça.

Para mais exemplos, consulte nosso repositório de apps de referência.

Pré-visualizando o código de uma incorporação

  1. Acesse a pergunta ou dashboard > ícone de compartilhamento > Incorpore este item em uma aplicação.
  2. Clique em Código.
  3. No bloco superior, você encontrará um código de exemplo para seu servidor web, além do snippet de iframe para incluir no seu template HTML ou aplicação SPA.

Quando você modifica a aparência ou as configurações dos parâmetros, o Analytics atualizará o código e destacará as mudanças. Certifique-se de copiar essas mudanças para seu código real no servidor.

Exemplos de código para incorporação

O Analytics gera código para servidor em:

  • Clojure
  • Node.js
  • Python
  • Ruby

Para snippets de iframe em:

  • ERB
  • JSX
  • Mustache
  • Pug/Jade

Se você serializa seu Analytics, use Entity IDs em suas incorporações estáticas

Usar Entity IDs em suas incorporações estáticas assegura que os IDs sejam estáveis ao exportar de um Analytics e importar para outro.

Para usar um Entity ID numa incorporação estática, basta editar o mapa resource no payload usado para assinar seu token. Substitua o ID (autopreenchido) pelo Entity ID e pronto.

Então, no código abaixo você trocaria { question: <ID> } para:

const payload = {
  resource: { question: <Entity ID goes here> },
  params: {},
  exp: Math.round(Date.now() / 1000) + (10 * 60) // expiração de 10 minutos
};

Se você não serializa seu Analytics, não se preocupe qual ID usar; ambos funcionarão sem problemas.

Editando uma pergunta ou dashboard incorporado

Se você alterar os parâmetros do item incorporado:

  1. Depois de fazer as alterações, copie o código gerado pelo Analytics.
  2. Clique em Publicar novamente.
  3. Atualize o código no seu servidor para que corresponda ao código gerado.

Desativando a incorporação para uma pergunta ou dashboard

Você pode ver todas as incorporações estáticas de perguntas e dashboards em Configurações > Configurações administrativas > Incorporação > Incorporação estática > Gerenciar.

  1. Acesse a pergunta ou dashboard incorporável.
  2. Clique no ícone de compartilhamento (quadrado com seta apontando para o canto superior direito).
  3. Selecione Incorporar.
  4. Selecione Incorporação estática.
  5. Clique em Cancelar publicação.

Personalizando a aparência das incorporações estáticas

Veja Personalização da aparência das incorporações estáticas.

Atualização automática dos resultados de um dashboard incorporado

A atualização automática está disponível apenas para dashboards, não para perguntas.

Para atualizar os resultados de um dashboard com uma frequência específica, você pode parametrizar a URL incorporada com refresh. Por exemplo, para configurar um dashboard incorporado para atualizar a cada 60 segundos, adicione refresh=60 à URL.

Por exemplo, o código abaixo gera uma URL de iframe para um dashboard que exibirá o título do dashboard e atualizará seus resultados a cada 60 segundos.

var iframeUrl =
  ANALYTICS_SITE_URL + "/embed/dashboard/" + token + "#titled=true&refresh=60";

Para a lista completa de opções que podem ser parametrizadas, veja personalizando a aparência de uma incorporação estática.

Removendo o banner “Powered by Analytics”

Powered by Analytics

O banner aparece em incorporações estáticas criadas com a versão open-source do Analytics. Para removê-lo, é necessário fazer upgrade para um plano Pro ou Enterprise.

Regenerando a chave secreta da incorporação estática

Sua chave secreta de incorporação é usada para assinar os JWTs de todas as suas URLs de incorporação.

  1. Acesse Configurações > Configurações administrativas > Incorporação.
  2. Na seção Incorporação estática, clique em Gerenciar.
  3. Em Regenerar chave secreta, clique em Regenerar chave.

Essa chave é compartilhada em todas as incorporações estáticas. Quem tiver acesso a ela poderá acessar todos os artefatos incorporados, então mantenha esta chave segura. Se regenerar essa chave, será necessário atualizar seu código do servidor com a nova chave.

Redimensionando dashboards para ajustar ao conteúdo

Dashboards têm proporção fixa, mas para garantir que se ajustem automaticamente na vertical ao conteúdo, você pode usar o script iFrame Resizer. O Analytics fornece uma cópia para conveniência:

<script src="http://analytics.exemplo.com/app/iframeResizer.js"></script>
<iframe
  src="http://analytics.exemplo.com/embed/dashboard/TOKEN"
  onload="iFrameResize({}, this)"
></iframe>

Devido a mudanças na licença do iframe-resizer, recomendamos usar a versão 4.3.2 ou inferior do iframe-resizer.

Destinos customizados em dashboards com incorporações estáticas

Você pode usar apenas a opção URL para destinos customizados em dashboards com incorporação estática. URLs externas abrirão em uma nova aba ou janela.

É possível propagar valores de filtros para a URL externa, a menos que o filtro esteja bloqueado.

Leituras adicionais

Leia a documentação para outras versões do Analytics.

Back to top