LayersPortal.js

A funcionalidade de Portais da Layers permite que apps adicionem telas personalizadas à nossa interface. Os Apps podem também habilitar a funcionalidade de autenticação OAuth para que os usuários que acessarem o portal sejam autenticados e o app possa acessar informações consentidas por eles. Além disso, utilizar essa funcionalidade permite que o App utilize nosso sistema de Push Notifications, que permite um fácil envio de push notifications para os usuários do app mobile e web.

Criando um portal na Layers

Para que um app possa utilizar essa funcionalidade da Layers ele deve estar cadastrado, ter a funcionalidade "portais" habilitada e disponibilizar o link de uma página que utilize a lib de portais da Layers. Essa biblioteca permite que o app receba eventos quando o app estiver pronto e quando estiver conectado para que ele possa ser acessado através da Layers.

LayersPortal.js

Importando e configurando a lib

Uma vez que o app está registrado ele poderá ser instalado nas comunidades e utilizado pelos usuários da comunidade em específico. Para que tudo funcione de forma segura e fluida para o usuário final, a página que será acessada através da Layers deve importar nossa lib de portais da maneira que está exemplificado abaixo. Através dessa lib, apps podem acessar informações e funcionalidades da Layers.

<!DOCTYPE html>
<html>
  <head>
    <script>
      window.LayersPortalOptions = {
        appId: String,
        insidePortalOnly: Boolean,
      };
    </script>
    <script
      type="text/javascript"
      src="https://js.layers.digital/v1/LayersPortal.js"
    ></script>
  </head>
</html>

CopiarCopiado

Configurações do portal

O objeto LayersPortalOptions deve ser definido com as seguintes propriedades:

appId: String contendo o identificador do app
insidePortalOnly: Booleano indicando se a página deve ser acessível apenas através da Layers

Utilizando a lib

A lib de portais disponibiliza uma série de eventos e promises para que apps que usam a funcionalidade de portais possam monitorar o status da lib e da sua conexão com a Layers.

Eventos

ready: O evento ready é emitido quando a lib de portais é carregada, indicando que ele foi importado com sucesso.

LayersPortal.on("ready", function () {
  //função chamada quando a lib for carregada
});

CopiarCopiado

connected: O evento connected é emitido quando a lib de portais está conectada com a Layers, indicando que apps podem acessar propriedades e métodos da lib. A função chamada quando receber esse evento pode receber o objeto data com informações de usuário e seção como parâmetro.

LayersPortal.on("connected", function (data) {
  //função chamada quando a lib estiver conectada com a Layers
});

CopiarCopiado

Promises

Além dos eventos, apps podem optar por usar promises para controlar o status da lib.

readyPromise: A propriedade readyPromise é, como o nome sugere, uma promise que será resolvida quando a lib for importada com sucesso.
connectedPromise: Assim como a propriedade anterior, a propriedade connectedPromise será resolvida quando a lib estiver conectada com a Layers retornando as informações de seção e do usuário acessando o portal.

A lib de portais também oferece propriedades e métodos que permitem que apps acessem informações não sensíveis do usuário acessando o portal e funcionalidades de navegação Layers

Propriedades

ready: Booleano que indica se a lib de portais foi importada com sucesso
connected: Booleano que indica se a lib de portais está conectada com a Layers
platform: String que pode ter o valor de "iframe", "ios" ou "android" se a página estiver sendo acessada através da Layers ou null se estiver sendo acessada fora da Layers.
session: String da seção
userId: String do identificador único do usuário na Layers
communityId: String do identificador da comunidade através do qual o usuário está acessando o portal
accountId: String do identificador único da conta do usuário acessando o portal
preferredLanguages: Array de strings que indicam os idiomas que o usuário utiliza na Layers.

Layers Portal: Parâmetros

ready: Por padrão, o controle de carregamento de portais na Layers é automático, mas é possível também controlar o carregamento manualmente. Para isso, o portal deve estar configurado com a feature manually-control-loading. Se o portal estiver usando essa feature, o loading da Layers aparecerá enquanto o portal não chamar o método de ready como mostrado abaixo.

LayersPortal("ready");

CopiarCopiado

update: O parâmetro 'params' permite que apps atualizem a URL e/ou o título do portal. Para isso, o app deve chamar a função como mostrado no exemplo abaixo:

LayersPortal("update", {
  url: String, // nova URL (opcional)
  title: String, // novo título (opcional)
});

CopiarCopiado

go: O parâmetro 'go' permite que portais redirecionem para outras páginas de portais ou da Layers. Para isso, o app deve chamar a função passando como parâmetro a URL da página para a qual o usuário deve ser redirecionado.
close: O parâmetro 'close' permite que o app feche o portal
download: O parâmetro download permite que o app faça download de arquivos no dispositivo do usuário. Para isso o app deve chamar a função passando como parâmetro um objeto contendo a URL do arquivo e o nome do arquivo como mostrado no exemplo abaixo.

await LayersPortal("download", {
  url: String, //URL do arquivo
  filename: String, //Nome do arquivo com extensão
});

CopiarCopiado

startGeolocation: O parâmetro 'startGeolocation' permite que portais iniciem a coleta de localização de um usuário. Para isso o app deve chamar a função passando como parâmetro um objeto contendo o intervalo de tempo entre coletas de localização e a duração da coleta de localização.

await LayersPortal("startGeolocation", {
  interval: Number, // Intervalo entre coleta de localização em milissegundos
  duration: Number, // Tempo pelo qual o app permanecerá coletando localização em milissegundos
});

CopiarCopiado

Importante: o intervalo mínimo entre coletas de informação é de 5000ms (5s) e o máximo é de 60000ms (1min). A duração mínima para a coleta é de 5000ms (5s) e a máxima é de 3600000ms (1hr).

stopGeolocation: O parâmetro 'stopGeolocation' permite que portais parem a coleta de informação de localização de um usuário antes da expiração do duration enviado na função 'startGeolocation'.

Autenticação

A autenticação pode ser feita através do uso das informações na lib de portais e da rota de validar sessão. Essa rota recebe nos parâmetros da query a session, o userId e a community. Fora isso, a rota também necessita da utilização de um token de aplicação, que é fornecido pela Layers à Startup durante o processo de integração. As informações necessárias podem ser extraídas da lib de portais da seguinte maneira:

const { session, communityId, userId } = LayersPortal;

CopiarCopiado

Assim, a aplicação pode fazer uma requisição na URL de validação de sessão no seguinte formato:

Authorization: Bearer {{ AppToken }}

CopiarCopiado

GET https://api.layers.digital/v1/sso/session/validate?session={SESSION}&community={COMMUNITY}&userId={USER_ID}

CopiarCopiado

Caso as informações enviadas sejam válidas, a rota de validação de sessão responderá com status 200 confirmando que essa é uma sessão válida e o usuário está autenticado na Layers.

Requisitando informações do usuário

Com a sessão validada, para requisitar informações do usuário em questão basta utilizar a rota de informações do usuário do Layers Data Sync