Parâmetros para embeds estáticos

Parâmetros para embeds estáticos

Também conhecidos como: parâmetros para embeds assinados, ou embeds independentes.

Parâmetros são informações que são passadas entre o Analytics e seu site através da URL de embed. Você pode usar parâmetros para especificar como os itens do Analytics devem aparecer e funcionar dentro do iframe no seu site.

Tipos de parâmetros

Parâmetros podem ser assinados (signed) ou não assinados (unsigned).

Parâmetros assinados

Parâmetros assinados, como nomes e valores de filtros, precisam ser adicionados no código do seu servidor.

• Parâmetros editáveis
• Parâmetros bloqueados

Parâmetros não assinados

Parâmetros não assinados, como configurações de aparência, devem ser adicionados diretamente no atributo src do iframe.

• Valores padrão para parâmetros editáveis
• Configurações de visibilidade para parâmetros editáveis
• Configurações de aparência

Adicionando um widget de filtro a um embed estático

Você pode usar parâmetros editáveis para adicionar widgets de filtro a dashboards ou perguntas SQL embutidas.

1. Vá até seu dashboard ou pergunta SQL. Certifique-se de que você configurou um filtro no dashboard ou uma variável SQL.
2. Clique no ícone de compartilhamento > Embed this item in an application.
3. Em Parameters, você verá os nomes dos filtros do dashboard ou das variáveis SQL.
4. Selecione Editable para cada parâmetro que deve receber um widget de filtro no embed.
5. Clique em Publish para salvar suas alterações.
6. Adicione ou atualize o código no seu servidor para estar de acordo com o código gerado pelo Analytics.

Parâmetros editáveis são responsáveis por passar os valores dos filtros do widget embutido (exibido no iframe) para os filtros no dashboard ou pergunta SQL original (no Analytics).

Você não pode desabilitar parâmetros quando a pergunta ou dashboard original exige um valor

Se o filtro em um dashboard ou pergunta está configurado como Always require a value, você não poderá desabilitar o parâmetro ao fazer o embed.

Preenchendo um widget de filtro embutido com um valor padrão

Se desejar definir um valor padrão para seu widget de filtro editável, você pode passar esse valor padrão para o nome do parâmetro correspondente no atributo src do iframe:

your_embedding_url?parameter_name=value

Por exemplo, se seu dashboard embutido tem um filtro conectado a um parâmetro editável chamado “Breakfast” e você quer definir o valor padrão como “Hash browns”:

your_embedding_url?breakfast=Hash_browns

Para especificar valores padrão para vários filtros, separe-os com e comercial (&):

your_embedding_url?breakfast=Hash_browns&lunch=Sandwich

Você pode definir múltiplos valores padrão para um único filtro separando os valores com e comercial (&):

your_embedding_url?breakfast=Hash_browns&breakfast=Pancakes

Escondendo widgets de filtro de um embed estático

Se você tem múltiplos parâmetros editáveis (resultando em múltiplos widgets de filtro), pode esconder específicos deles do seu embed estático adicionando #hide_parameters ao final da URL no atributo src do iframe:

your_embedding_url#hide_parameters=parameter_name

Por exemplo, para esconder um filtro chamado “Breakfast” do dashboard embutido:

your_embedding_url#hide_parameters=breakfast

Você pode esconder múltiplos widgets de filtro separando os nomes dos parâmetros com vírgulas:

your_embedding_url#hide_parameters=breakfast,lunch

Você também pode simultaneamente atribuir um valor padrão a um parâmetro e esconder seu widget de filtro:

your_embedding_url?breakfast=Hash_browns#hide_parameters=breakfast

Sintaxe dos parâmetros não assinados

Ao adicionar um parâmetro à URL de embed no atributo src do iframe, observe que:

• Os nomes dos parâmetros são em letras minúsculas.
• Os valores são sensíveis a maiúsculas e minúsculas (os valores devem corresponder aos seus dados).
• Espaços devem ser substituídos por underscores.

Restringindo dados em um embed estático com parâmetros bloqueados

Se quiser restringir os dados exibidos em um dashboard ou pergunta SQL embutida, você pode configurar um parâmetro bloqueado. Um parâmetro bloqueado filtra os dados no dashboard ou pergunta SQL antes dos resultados serem exibidos para usuários em um embed estático.

1. Vá até seu dashboard ou pergunta SQL. Certifique-se de que configurou um filtro no dashboard ou uma variável SQL.
2. Clique no ícone de compartilhamento > Embed this item in an application.
3. Em Parameters, você verá os nomes dos filtros do dashboard ou das variáveis SQL.
4. Selecione Locked para cada parâmetro que deseja usar para restringir seus dados.
5. Opcional: selecione um valor em Preview locked parameters para ver como ficarão os dados restritos.
6. Clique em Publish para salvar as alterações.
7. Adicione ou atualize o código no servidor para estar de acordo com o código gerado pelo Analytics.

Você pode usar parâmetros bloqueados para exibir dados filtrados com base em atributos capturados pelo seu servidor web, como nome de usuário ou ID de tenant. Para mais exemplos, veja o repositório de apps de referência.

Parâmetros bloqueados aplicam os valores de filtro ao seu dashboard ou pergunta SQL original, mas não são exibidos como widgets de filtro no embed. Parâmetros bloqueados também podem limitar os valores exibidos em seus widgets de filtro editáveis.

Se você apenas quiser exigir um valor para o parâmetro, pode configurar o filtro como editável e configurar a pergunta ou dashboard para sempre exigir um valor.

Atualizando um parâmetro bloqueado

Coisas para considerar caso precise alterar seus parâmetros bloqueados.

Inclua todos os parâmetros bloqueados no seu código do servidor

Depois de publicar um gráfico ou dashboard com um parâmetro bloqueado, você deve incluir o nome do parâmetro bloqueado no código do servidor. Se você deixar o nome do parâmetro de fora, os logs irão avisar suavemente: You must specify a value for :parameter in the JWT.

Para desativar um parâmetro bloqueado, passe um array vazio como valor no JWT

Se não quiser que o filtro bloqueado seja aplicado, você pode passar um array vazio, [], como valor do parâmetro no JWT.

Garanta que o nome do filtro corresponda ao nome do parâmetro bloqueado

Se você alterar o nome de um filtro do query builder usado como parâmetro bloqueado, lembre-se de atualizar o nome e os valores do parâmetro no seu código do servidor também. Se seu parâmetro bloqueado estiver conectado a uma variável SQL, não é necessário alterar o nome ou os valores do parâmetro.

Múltiplos parâmetros bloqueados ou múltiplos valores

Os valores do parâmetro bloqueado no código do servidor devem corresponder exatamente aos valores do filtro. A melhor forma de configurar múltiplos parâmetros bloqueados, ou passar múltiplos valores para um parâmetro bloqueado, é selecionar um valor no Preview locked parameters e visualizar o código do servidor gerado pelo Analytics.

Ao usar múltiplos parâmetros bloqueados juntos, a filtragem será feita com AND, não OR. Se você quiser aplicar apenas um subconjunto dos parâmetros bloqueados, deve informar ao Analytics para ignorar os demais parâmetros bloqueados.

Parâmetros bloqueados limitam os valores disponíveis para outros parâmetros editáveis

Como parâmetros bloqueados filtram os dados antes dos resultados serem exibidos no embed, eles limitam os valores disponíveis para outros widgets de filtro editáveis.

Por exemplo, suponha que você esteja embutindo um dashboard com dois filtros, Estado e Cidade. Se você bloquear o parâmetro Estado com o valor “Vermont”, o Analytics exibirá apenas o widget do filtro Cidade no dashboard, e o menu suspenso desse widget será limitado às cidades de Vermont. Embora você não vincule explicitamente os dois filtros, eles se comportam implicitamente como filtros vinculados.

Parâmetros bloqueados em dashboards com perguntas SQL

Se seu parâmetro bloqueado estiver ligado a um filtro de dashboard que, por sua vez, está ligado a uma pergunta SQL, você só poderá escolher um valor para o parâmetro bloqueado.

Por exemplo, imagine um filtro “Breakfast” no dashboard com as opções “Hash browns”, “Muffin” e “Waffles”. Se esse filtro “Breakfast” estiver ligado a qualquer pergunta SQL no dashboard, você só poderá escolher uma das opções para um parâmetro bloqueado vinculado ao filtro “Breakfast”.

Usando parâmetros bloqueados para alimentar widgets customizados em sua aplicação

Como o Analytics não exibe os parâmetros bloqueados como widgets de filtro, você pode usá-los para alimentar widgets customizados que você constrói em sua aplicação. Você pode querer criar seus próprios widgets de filtro para:

• Tornar os widgets mais consistentes com o design e funcionamento do seu aplicativo.
• Incluir lógica customizada, por exemplo, para lembrar valores recentes no filtro.
• Reutilizar um mesmo dashboard de formas diferentes em diferentes partes do seu app. Por exemplo, um dashboard de vendas com múltiplos parâmetros bloqueados, usando um parâmetro em um contexto, e outro parâmetro em outro contexto — como um dashboard bloqueado por “região” em uma parte do app, por “time” em outra.

Customizando a aparência de um embed estático

Você pode alterar a aparência de um item embutido adicionando parâmetros hash (por exemplo, #theme=night) ao final da URL no atributo src do iframe.

Por exemplo, a seguinte URL de embed mostrará o item embutido em modo escuro, sem borda, e com o título original:

your_embedding_url#theme=night&bordered=false&titled=true

Você pode visualizar configurações de aparência a partir das configurações de aparência embutida do seu dashboard ou pergunta.

Nome do parâmetro	Valores possíveis
background	true (padrão), false. Apenas dashboards.
bordered	true (padrão), false.
locale*	Exemplo: ko. Veja lista de idiomas suportados
titled	true (padrão), false.
theme	null (padrão), night. theme=transparent deve funcionar, mas está obsoleto (veja Fundos transparentes).
refresh (apenas dashboards)	inteiro (segundos, ex: refresh=60).
font*	nome da fonte
downloads**	true (padrão), false, results, pdf

* Disponível nos planos Pro e Enterprise

** Desabilitar downloads está disponível nos planos Pro e Enterprise

Para configurações globais de aparência, como cores e fontes usadas em toda a instância do Analytics, veja Customizando a aparência do Analytics.

Definindo o idioma para um embed estático

Para alterar o idioma da interface de um embed estático, você pode configurar seu locale. Por exemplo, para definir o idioma de um link público para coreano, adicione #locale=ko:

https://analytics.example.com/public/dashboard/7b6e347b-6928-4aff-a56f-6cfa5b718c6b?category=&city=&state=#locale=ko

Se você tiver múltiplos parâmetros, separe-os com um e comercial (&):

category=Gadget&state=Vermont#theme=night&locale=ko

O parâmetro locale altera apenas o idioma dos elementos da interface do Analytics. O idioma do conteúdo é definido por quem criou o item. Por exemplo, o Analytics não traduziria o nome de uma pergunta, mas traduziria o texto da interface como “Export to PDF”.

Fundos transparentes para embeds

Para tornar um embed transparente, depende do tipo de embed:

• Dashboards: configure background=false. O parâmetro background pode ser combinado com theme (por exemplo, background=false&theme=night).
• Perguntas: configure theme=transparent (obsoleto, mas ainda suportado).

Desabilitar downloads para uma pergunta ou dashboard embutido

Por padrão, o Analytics incluirá um botão Download em perguntas embutidas e uma opção Export to PDF em dashboards embutidos.

Você pode configurar essas opções com o parâmetro downloads na URL de embed do atributo src do iframe, veja customizando a aparência de embeds estáticos.

downloads aceita os seguintes valores:

• true (padrão): inclui tanto o botão Download quanto a opção Export to PDF.
• false: esconde tanto o botão Download quanto a opção Export to PDF.
• results: mostra o botão Download.
• pdf: mostra a opção Export to PDF (apenas dashboards).

Você pode combinar as opções explícitas: downloads=results,pdf é o mesmo que downloads=true.

O parâmetro downloads substitui o parâmetro antigo hide_download_button.

Tamanho máximo da requisição

O tamanho máximo da URL de embed estático (incluindo todos os parâmetros) é determinado pela sua variável de ambiente MB_JETTY_REQUEST_HEADER_SIZE. O padrão é 8192 bytes.

Se sua URL de embed exceder o tamanho máximo do header, você verá uma mensagem de log como URI too long. Você pode atualizar a variável de ambiente para aceitar headers maiores. Se usar um servidor proxy, talvez precise configurar uma propriedade correspondente no servidor também.

Leituras adicionais

• Documentação de embedding estático.
• Estratégias para oferecer análises para clientes.
• Publicando visualizações de dados na web.