Início rápido de incorporação interativa

Início rápido de incorporação interativa

Você incorporará a aplicação completa do Analytics em seu app. Uma vez logados, as pessoas poderão visualizar um dashboard do Analytics no seu aplicativo web e usar a aplicação completa do Analytics para explorar seus dados, e apenas seus dados.

Crie um POC funcional em apenas uma hora.

Participe do nosso próximo Workshop de Incorporação Interativa.

Registre-se agora

Pré-requisitos

• Você possui um app onde pode incorporar o Analytics.
• Você possui uma assinatura Pro ou Enterprise do Analytics. Se não souber por onde começar, faça um teste gratuito para Pro On-Prem. Se tiver o Docker Desktop instalado, pode buscar pela imagem “analytics-enterprise” para rodar o container. Alternativamente, siga estas instruções.

O código apresentado neste guia está disponível em nosso repositório de exemplo.

Configurar SSO e incorporação interativa no Analytics

Tenha um dashboard pronto para incorporar

Você precisará primeiro de um dashboard para incorporar. Se ainda não tiver, pode usar o Example Dashboard que o Analytics inclui em novas instâncias ou gerar um usando x-rays.

Visite esse dashboard e anote sua URL, por exemplo /dashboard/1-e-commerce-insights. Você precisará colocar essa URL relativa no seu app, pois será a primeira página que os usuários logados verão ao acessar a seção de analytics no seu app. Basta incluir o ID apenas, omitindo o restante da URL, por exemplo /dashboard/1.

Você também pode usar o Entity ID do dashboard. No dashboard, clique no botão info. Na aba Overview, localize o Entity ID do dashboard. Copie esse Entity ID. Você usará esse Entity ID na URL do iframe no atributo src: por exemplo, src=/dashboard/entity/[Entity ID].

Habilitar incorporação interativa

No Analytics, clique no ícone de engrenagem no canto superior direito e vá em Admin settings > Settings > Embedding. Procure por Interactive Embedding e clique no toggle para Enabled.

Clique no botão Configure em Interactive Embedding. Em Authorized origins, adicione a URL do site ou app web onde deseja incorporar o Analytics. Se estiver rodando seu app localmente, pode adicionar localhost com a porta, por exemplo http://localhost:8080.

Configuração de SameSite

Se estiver incorporando o Analytics em um domínio diferente, pode ser necessário configurar o cookie de sessão com SameSite = none.

Configurar SSO com JWT no seu Analytics

Ativar autenticação com JWT

Ainda no painel de Admin em Settings, clique em Authentication.

Na área do JWT, clique no botão Setup (pode ser necessário rolar a página para encontrar a seção JWT).

Definir JWT Identity Provider URI

Em seu app, crie uma rota para SSO em /sso/analytics. No campo JWT IDENTITY PROVIDER URI, insira a URL da sua rota de SSO. Por exemplo, no app de exemplo que rodamos na porta 8080, esse URI pode ser http://localhost:8080/sso/analytics.

Gerar uma chave de assinatura JWT

Clique no botão Generate key para gerar uma chave de assinatura. Mantenha essa chave em segredo. Você usará essa chave no backend do seu app. Se gerar outra chave, a anterior será sobrescrita, então será necessário atualizar a chave no seu app também.

Copie essa chave, pois precisará dela na próxima seção.

Salvar e ativar autenticação JWT

Vamos configurar a sincronização de grupos mais tarde, mas por enquanto, clique no botão Save and enable para ativar a autenticação JWT.

Configurar SSO com JWT no servidor do seu app

Adicione a chave de assinatura e a URL do site do Analytics ao seu app

Aqui você precisará configurar alguns valores para o SSO funcionar.

Declare as seguintes constantes em seu app:

• ANALYTICS_JWT_SHARED_SECRET, onde deve colocar a chave de assinatura JWT obtida do Analytics.
• ANALYTICS_SITE_URL, que aponta para a URL raiz do seu Analytics.

const ANALYTICS_JWT_SHARED_SECRET = "SUA_CHAVE_DE_ASSINATURA";
const ANALYTICS_SITE_URL = "https://seu-dominio.analyticsapp.com";

Para evitar o risco de expor sua chave, o ideal é configurar a chave de assinatura como uma variável de ambiente, para que não seja acidentalmente enviada ao repositório do seu app.

Adicione uma biblioteca JWT ao backend do seu app

Adicione uma biblioteca JWT ao seu app. Por exemplo, se estiver usando Node.js no backend, recomendamos a biblioteca jsonwebtoken.

No terminal:

npm install jsonwebtoken --save

E no seu app, importe a biblioteca:

import jwt from "jsonwebtoken";

Restringindo acesso a certas rotas

Presumivelmente, seu app já possui alguma forma de garantir que certas rotas sejam acessíveis apenas após o login. Nosso exemplo usa uma função auxiliar chamada restrict para proteger essas rotas:

function restrict(req, res, next) {
  if (req.session.user) {
    next();
  } else {
    req.session.returnTo = req.originalUrl;
    req.session.error = "Acesso negado!";
    res.redirect("/login");
  }
}

Adicione uma função para assinar usuários

Precisamos criar uma função para assinar os tokens JWT dos usuários, usando a biblioteca JWT.

const signUserToken = user =>
  jwt.sign(
    {
      email: user.email,
      first_name: user.firstName,
      last_name: user.lastName,
      exp: Math.round(Date.now() / 1000) + 60 * 10, // expira em 10 minutos
    },
    ANALYTICS_JWT_SHARED_SECRET,
  );

Adicione uma rota sso/analytics

Você precisará adicionar uma rota para autenticar as pessoas no Analytics via SSO com JWT. Se a pessoa ainda não tiver feito login no seu app, ela deverá ser redirecionada para o fluxo de autenticação do seu app. No código abaixo, essa verificação e redirecionamento é realizada pela função restrict que apresentamos anteriormente.

app.get("/sso/analytics", restrict, (req, res) => {
  const ssoUrl = new URL("/auth/sso", ANALYTICS_SITE_URL);
  ssoUrl.searchParams.set("jwt", signUserToken(req.session.user));
  ssoUrl.searchParams.set(
    "return_to",
    req.query.return_to?.toString() ?? "/",
  );

  res.redirect(ssoUrl.href);
});

Se a pessoa nunca tiver feito login no Analytics antes, o Analytics criará uma conta para ela.

PONTO DE VERIFICAÇÃO: faça login no seu Analytics usando SSO

Certifique-se de estar deslogado(a) do Analytics. Na página de login do Analytics, clique em “Sign in with SSO”. Você deverá ser redirecionado para seu app.

Faça o login no seu app. Seu app deve redirecionar você para a página de boas-vindas do Analytics. Se a pessoa ainda não possuir uma conta no Analytics, a conta será criada automaticamente.

Incorpore o Analytics em seu app

Agora para incorporar o Analytics no seu app. Configure uma rota para servir seu analytics incorporado. Vamos nomeá-la como /analytics. Note que estamos usando a função auxiliar restrict (definida acima), porque essa página deve ser acessível somente após o usuário fazer login no seu app.

Nesta rota, precisamos renderizar um iframe que carregará seu Analytics. O atributo src do iframe deve apontar para o caminho relativo da rota SSO do seu app. Após a pessoa fazer login no seu app (e, portanto, no Analytics), adicionamos o parâmetro de query string return_to para que o iframe exiba o dashboard solicitado.

ANALYTICS_DASHBOARD_PATH deve apontar para o caminho relativo do dashboard que você criou no início deste guia (/dashboard/[ID] ou, se usar o Entity ID do dashboard, /dashboard/entity/[Entity ID]).

app.get("/analytics", restrict, (req, res) => {
  const ANALYTICS_DASHBOARD_PATH = "/dashboard/entity/[Entity ID]"; // ex: `/dashboard/1` ou `/dashboard/entity/nXg0q7VOZJp5a3_hceMRk`
  const iframeUrl = `/sso/analytics?return_to=${ANALYTICS_DASHBOARD_PATH}`;

  res.send(
    ``,
  );
});

O ANALYTICS_DASHBOARD_PATH é apenas a primeira coisa que as pessoas verão ao logar, mas você pode definir esse caminho para qualquer URL do Analytics. E como está incorporando o Analytics completo, as pessoas poderão navegar pelos dados, visualizar outras perguntas, dashboards e coleções.

PONTO DE VERIFICAÇÃO: visualize o dashboard do Analytics no seu app

Os usuários do seu app agora devem conseguir acessar /analytics e visualizar o dashboard incorporado do Analytics.

Como testar: faça login no seu app e visite a rota /analytics. Você deverá ver o dashboard do Analytics.

Se estiver usando o navegador Safari, e seu Analytics e app estiverem em domínios diferentes, pode ser necessário desativar em Safari o recurso Impedir rastreamento entre sites nas configurações do navegador.

Configure um grupo no Analytics

Agora que você configurou o SSO e a incorporação interativa, é hora de criar grupos para aplicar permissões aos seus itens incorporados do Analytics (perguntas, dashboards, coleções, etc.).

Adicione uma chave groups ao seu token

Retomando a função signUserToken usada para criar os JWTs, adicione uma chave groups no token assinado que corresponda a um array. O Analytics verificará os valores nesse array para saber se eles correspondem a algum grupo definido no Analytics (vamos mostrar como mapear grupos adiante).

const signUserToken = user =>
  jwt.sign(
    {
      email: user.email,
      first_name: user.firstName,
      last_name: user.lastName,
      groups: ["Customer-Acme"],
      exp: Math.round(Date.now() / 1000) + 60 * 10, // expira em 10 minutos
    },
    ANALYTICS_JWT_SHARED_SECRET,
  );

Crie um grupo no Analytics

No Analytics, clique no ícone de engrenagem e vá em Admin settings > People > Groups. Clique em Criar grupo. Adicione um grupo que corresponda a um grupo do seu app. Se estiver usando o app de exemplo, adicione o grupo chamado Customer Acme.

Sincronize grupos entre o Analytics e seu app

Você mapeará essa string presente no array groups para um grupo no Analytics, para que quando o usuário fizer login via SSO, o Analytics automaticamente o adicione ao grupo correto.

No painel admin do Analytics, vá para Settings > Authentication. Na seção JWT, clique em Edit.

Na seção Group schema, ative Synchronize group memberships. Para cada grupo que deseja sincronizar, adicione um mapeamento. Clique em New mapping, digite “Customer-Acme”, a string que você colocou no array groups do payload JWT. Depois, associe esse nome de grupo ao grupo “Customer Acme” criado anteriormente no Analytics.

Não esqueça de clicar em Save changes.

PONTO DE VERIFICAÇÃO: verifique se o Analytics atribui grupos ao fazer login

Primeiro, deslogue do Analytics e faça login usando SSO.

Depois deslogue e faça login no Analytics como administrador, vá em Admin settings > People e verifique que o Analytics adicionou a pessoa ao grupo correto.

Atenção: apenas administradores e gerentes de grupo veem os grupos no Analytics. Usuários normais não têm conhecimento dos grupos nem acesso a essa informação.

Defina permissões

Agora, aplique permissões para que as pessoas vejam apenas os dados específicos das suas contas.

Redefina permissões para o grupo All Users

O Analytics vem com dois grupos iniciais: “Admins” e “All Users”. Por padrão, o Analytics dá acesso ao grupo “All Users” às fontes de dados conectadas. Como o Analytics concede o privilégio do grupo mais permissivo do usuário, você deve restringir o que o grupo All Users pode acessar antes de atribuir usuários a grupos com acesso restrito ou nenhum acesso às fontes de dados e coleções.

Para redefinir as permissões do grupo All Users, clique no ícone de engrenagem e vá em Admin settings > Permissions. Na aba Data, selecione o grupo All Users. Para o Sample Database na coluna View data, selecione “Blocked”. Clique em Save changes e confirme as mudanças no modal que aparecer.

Permita acesso de visualização à coleção de dashboards automaticamente gerados

Ainda na aba Permissions, clique na sub-aba Collections, depois na coleção Automatically generated dashboards, e defina a permissão Collection access para o grupo All Users como View.

Clique em Save changes, e confirme clicando em Yes.

Adicione um atributo de usuário ao token

Você pode incluir atributos de usuário no token JWT. O Analytics irá extrair todas as chaves do payload do JWT e armazená-las como atributos de usuário. Entre outras utilidades, esses atributos podem ser usados para aplicar permissões em nível de linha nas tabelas, garantindo que as pessoas vejam somente os dados referentes às suas contas.

Se estiver usando o app de exemplo, edite a função signUserToken para adicionar a chave account_id com valor 28.

const signUserToken = user =>
  jwt.sign(
    {
      email: user.email,
      first_name: user.firstName,
      last_name: user.lastName,
      // ID da conta fixo adicionado ao objeto
      // apenas para testar isolamento com a tabela Invoices do Sample Database do Analytics
      account_id: 28,
      groups: ["Customer-Acme"],
      exp: Math.round(Date.now() / 1000) + 60 * 10, // expira em 10 minutos
    },
    ANALYTICS_JWT_SHARED_SECRET,
  );

Esse account_id corresponderá à coluna Account ID na tabela Invoices do Sample Database. Usaremos esse atributo de usuário para isolar dados da tabela Invoices, assim as pessoas verão somente as linhas que contêm seu ID de conta.

Note que para persistir o atributo de usuário no Analytics, é necessário fazer login. Entre no seu app como um usuário não-admin e acesse a página com o Analytics incorporado.

Defina permissões em nível de linha com sandbox de dados

No Analytics, vá em Admin settings > Permissions. Na aba Data, selecione um grupo. Para o “Sample Database”, mude a coluna Data access para Granular.

O Analytics exibirá uma lista de tabelas do banco. Depois, altere o Data access da tabela “Invoices” para Sandboxed.

Em seguida, o Analytics solicitará que você associe uma coluna dessa tabela a um atributo de usuário.

Mantenha selecionada a opção Filter by a column in a table e associe a coluna “Account ID” da tabela Invoices ao atributo de usuário account_id. (O Analytics exibirá os atributos somente se o usuário já tiver feito login via SSO antes.)

Clique em Save para confirmar a seleção. Depois, clique em Save changes no canto superior direito.

O Analytics perguntará se tem certeza. Pode confirmar.

PONTO DE VERIFICAÇÃO: visualize o dashboard sandboxed

Certifique-se de que você tenha saído da sessão anterior.

Faça login no seu app e navegue até /analytics. O dashboard agora apresentará informações diferentes, pois a pessoa só verá um subconjunto filtrado dos dados. Clique em Browse Data na parte inferior do menu esquerdo. Visualize a tabela Invoices com sandbox e observe que só aparecem as linhas relacionadas à conta do usuário.

Escondendo elementos do Analytics

Você pode decidir mostrar ou ocultar diversos elementos da interface do Analytics, como barra de navegação, busca e botão +New, entre outros.

Por exemplo, para esconder o logo e a barra de navegação superior do seu Analytics incorporado, você adicionaria os parâmetros de query string ?logo=false&top_nav=false na URL return_to que inclui na redirecionamento de SSO.

No handler da rota /sso/analytics, acrescente os parâmetros de query assim:

ssoUrl.searchParams.set(
  "return_to",
  `${req.query.return_to ?? "/"}?logo=false&top_nav=false`,
);

PONTO DE VERIFICAÇÃO: verifique os elementos da UI escondidos

Deslogue e faça login no seu app novamente e acesse /analytics. Seu Analytics incorporado não deve incluir o logo nem a navegação superior.

Próximos passos

Você pode customizar o visual do Analytics no seu app: fontes, cores e logos.