API Javascript de Monitoramento

Introdução

A API javascript de monitoramento foi projetada para ser usada em páginas web, criadas pelo Lumis Portal ou em sistemas externos, para permitir rastrear e coletar informações de uso, comportamento e características dos usuários, armazenando estas informações no framework de monitoramento do Lumis Portal, que pode ser visualizado na área disponibilizada pelo serviço de Customer Experience.

Inicialização

A inicialização da API javacript depende onde ela será utilizada. Caso seja utilizada em uma página do Lumis Portal ela já é automaticamente inicializada, exceto em casos onde customizações tenham eliminados scripts padrões do Lumis Portal ou que se tenha configurado nas propriedades de canais ou páginas para este script não ser automaticamente incluído.

Nos demais casos o script precisa ser inicializado manualmente incluindo um código de javascript, que se recomenda que seja incluido no fim do <head>. Tipicamente um sistema externo que deseja usar esta API, assumindo que o endereço base do website do Lumis Portal utilizado é https://www.meulumisportal.com/ (e deve ser substituído de acordo) será:

No script acima, a primeira linha de script é fixa e disponibiliza a função da API para poder ser usada enquanto o script será carregado e inicializado em segundo plano. A segunda linha, que executa a operação config, pode receber outras configurações conforme a necessidade. Para mais detalhes veja a documentação da operação config.

A partir daí, a função lum_track pode ser utilizada para executar operações desejadas. Enquanto o script é inicializado em segundo plano, qualquer chamada ao lum_track vai enfilerar a operação requisitada, e esta fila será executada quando o script for inicializado.

Para utilizar esta API a partir de páginas externas ao Lumis Portal, deve-se fazer configurações em Requisições cross-site para liberar acesso de GET em /lumis/portal/monitor/script/track.js e todos os métodos em /lumis/api/rest/lumis/monitor/v1/.*, para todas as origens que deseje permitir utilizar esta API.

Operações

As operações são executadas utilizando a sintaxe lum_track(NOME_OPERAÇÃO, arg1, arg2, ...), onde argx são os argumentos para a operação.

Algumas operações aceitam como argumento uma função de callback. Nestes casos a função de callback fornecida receberá um argumento que é um objeto com a propriedade success de tipo boolean indicando se a operação foi ou não bem sucedida. O uso de callback é algo para cenários mais avançados, como por exemplo quando se precisa confirmar o resultado de uma operação antes de executar alguma ação. Observe que podem haver situações em que a função nunca seja chamada, como por exemplo por algum problema na rede ou servidor que impeça ter notificação de sucesso ou erro da operação.

A seguir é apresentada cada operação em detalhe.

config

Permite configurar alguns comportamentos da API. Esta operação deve ser utilizada apenas após a declaração do lum_track mas antes da inclusão do track.js.

Sintaxe

lum_track("config", configOptions)

Argumentos

Ela recebe como argumento configOptions um objeto com as opções de configuração a serem aplicadas. Este objeto pode conter quaisquer das seguintes opções como propriedade:

Nome Descrição Valor padrão

baseHref URI, absoluta ou relativa ao documento atual, da base de um website do Lumis Portal onde será armazenado as informações coletadas. Se window.g_LumisRootPath estiver definida (por padrão incluída automaticamente em páginas do Lumis Portal), ela será utilizada para calcular o valor desta configuração. Caso contrário não há valor padrão e é requirido que essa configuração seja fornecida para o funcionamento desta API.

clientStorage

Nome	Descrição	Valor padrão
baseHref	URI, absoluta ou relativa ao documento atual, da base de um website do Lumis Portal onde será armazenado as informações coletadas.	Se `window.g_LumisRootPath` estiver definida (por padrão incluída automaticamente em páginas do Lumis Portal), ela será utilizada para calcular o valor desta configuração. Caso contrário não há valor padrão e é requirido que essa configuração seja fornecida para o funcionamento desta API.
clientStorage	O valor para esta configuração pode ser `"local"`, para armazenamentos de dados no navegador serem baseado em window.localStorage, ou `"cookie"` para serem baseados em document.cookie. O tipo de armazenamento também afeta o isolamento do rastreamento. Isso porque document.cookie é isolado por domínio (opcionalmente também pelo caminho conforme opção `cookiePath` abaixo), enquanto que window.localStorage, além de domínio, também é isolado por protocolo e porta. Por isso, se deseja que o rastreamento seja compartilhado entre diferentes protocolos e portas, deve-se utilizar `"cookie"` ao invés de `"local"`. Em páginas de domínio servido pelo Lumis Portal deve-se utilizar a opção `"cookie"` para que a API javascript funcione integrada com cookies que o servidor Lumis Portal gera. Caso o navegador não disponibilize window.localStorage ou seja Internet Explorer (que possui não conformidades em sua implementação de localStorage), esta configuração será ignorada e funcionará como se estivesse configurada para cookie.	Se `window.g_LumisRootPath` estiver definida utiliza como valor padrão `"cookie"`, caso contrário `"local"`.
cookiePath	path utilizado no cookie gerado pela API. Esta configuração só é relevante se o clientStorage for cookie.	Se existir a variável `window.g_LumisRootPath` (por padrão incluída automaticamente em páginas do Lumis Portal), seu valor será utilizado como padrão. Caso contrário `"/"` é o valor padrão.

O valor para esta configuração pode ser "local", para armazenamentos de dados no navegador serem baseado em window.localStorage, ou "cookie" para serem baseados em document.cookie.

O tipo de armazenamento também afeta o isolamento do rastreamento. Isso porque document.cookie é isolado por domínio (opcionalmente também pelo caminho conforme opção cookiePath abaixo), enquanto que window.localStorage, além de domínio, também é isolado por protocolo e porta. Por isso, se deseja que o rastreamento seja compartilhado entre diferentes protocolos e portas, deve-se utilizar "cookie" ao invés de "local".

Em páginas de domínio servido pelo Lumis Portal deve-se utilizar a opção "cookie" para que a API javascript funcione integrada com cookies que o servidor Lumis Portal gera.

Caso o navegador não disponibilize window.localStorage ou seja Internet Explorer (que possui não conformidades em sua implementação de localStorage), esta configuração será ignorada e funcionará como se estivesse configurada para cookie.

Se window.g_LumisRootPath estiver definida utiliza como valor padrão "cookie", caso contrário "local".

cookiePath path utilizado no cookie gerado pela API. Esta configuração só é relevante se o clientStorage for cookie. Se existir a variável window.g_LumisRootPath (por padrão incluída automaticamente em páginas do Lumis Portal), seu valor será utilizado como padrão. Caso contrário "/" é o valor padrão.

Exemplos de uso

Configurando o baseHref (uso em um site externo ao Lumis Portal, por exemplo): lum_track("config", { baseHref: "https://www.meulumisportal.com.br/" });
Configurando o baseHref (uso em um site externo ao Lumis Portal, por exemplo) e para o armazenamento ser em cookie ao invés de localStorage.: lum_track("config", { baseHref: "https://www.meulumisportal.com.br/", clientStorage: "cookie" });
Configurando o baseHref (uso em um site externo ao Lumis Portal, por exemplo) e para o armazenamento ser em cookie ao invés de localStorage, e limitando a utilização do cookie a um caminho específico.: lum_track("config", { baseHref: "https://www.meulumisportal.com.br/", clientStorage: "cookie", cookiePath: "/caminho" });

event

Contabiliza a ocorrência de um evento, armazenando informações relacionadas.

Sintaxe

lum_track("event", eventId, eventData, callback)

Argumentos

Nome Descrição Tipo Requerido

eventId O identificador do evento. String Sim

eventData

Nome	Descrição	Tipo	Requerido
eventId	O identificador do evento.	String	Sim
eventData	Objeto contendo os dados para o evento ser coletado. O Objeto pode ser um dicionário de identificadores de campos do evento para o valor correspondente, ou uma hierarquia de objetos onde os nomes de suas propriedades correspondem aos identificadores dos campos. Os tipos dos valores devem corresponder aos tipos dos campos definidos no evento. No caso de campo tipo `datetime` o valor pode ser um objeto tipo Date, String no formato ISO 8601 ou number com quantidade de milisegundos desde 1/1/1970 00:00 GMT. Esta operação fornece automaticamente valores para os campos `lum_event.datetime`, `lum_client.url`, `lum_client.origin.url` e `lum_user.id`, caso não estejam presentes neste argumento. Esta operação utiliza internamente API REST de coleta de ocorrência de evento, com parâmetro `fromEventClient` com valor `true`, e todo cálculo de valores padrões para os campos naquela API REST se aplica também para esta operação.	Objeto	Não
callback	Função de callback.	Function	Não

Objeto contendo os dados para o evento ser coletado. O Objeto pode ser um dicionário de identificadores de campos do evento para o valor correspondente, ou uma hierarquia de objetos onde os nomes de suas propriedades correspondem aos identificadores dos campos. Os tipos dos valores devem corresponder aos tipos dos campos definidos no evento. No caso de campo tipo datetime o valor pode ser um objeto tipo Date, String no formato ISO 8601 ou number com quantidade de milisegundos desde 1/1/1970 00:00 GMT.

Esta operação fornece automaticamente valores para os campos lum_event.datetime, lum_client.url, lum_client.origin.url e lum_user.id, caso não estejam presentes neste argumento. Esta operação utiliza internamente API REST de coleta de ocorrência de evento, com parâmetro fromEventClient com valor true, e todo cálculo de valores padrões para os campos naquela API REST se aplica também para esta operação.

Objeto

Não

callback Função de callback. Function Não

Exemplos de uso

Registrando uma ocorrência de um evento sem informações para campos deste evento: lum_track("event", "customeventid");
Registrando a ocorrência de um evento customizado e fornencendo uma função de callback: lum_track("event", "customeventid", callback);
Registrando a ocorrência de um evento customizado com informações para campos deste evento usando um objeto estilo dicionário: lum_track("event", "customeventid", { "custom.field1": "value", "custom.field2": ["value1","value2"] });
Registrando a ocorrência de um evento customizado com informações para campos deste evento usando objetos hierárquicos: lum_track("event", "customeventid", { custom: { field1: "value", field2: ["value1","value2"] } });
Registrando a ocorrência de um evento customizado com informações para campos deste evento e fornecendo uma função de callback: lum_track("event", "customeventid", { "custom.field1": "value", "custom.field2": ["value1","value2"] }, callback);

userAttributes

Permite armazenar valores em atributos do usuário atualmente rastreado por esta API.

Sintaxe

lum_track("userAttributes", attributes, callback)

Argumentos

Nome	Descrição	Tipo	Requerido
attributes	Objeto tipo dicionário indicando quais atributos devem ser atualizados e seus respectivos valores. Este objeto deve ser similar à estrutura JSON da requisição da API REST de atualizar atributos do usuário.	Object	Sim
callback	Função de callback.	Function	Não

Exemplos de uso

Preenchendo vários atributos do usuário atual: lum_track("userAttributes", { firstName: "John", middleName: "Doe", lastName: "Smith", email: "jds@example.com", customAttributes: { active: false, classes: 5, company: "Acme", memberSince: "1980-12-02T05:23:26-03:00" } });
Preenchendo atributos firstName e lastName, removendo qualquer valor existente no atributo customizado com identificador company e fornecendo uma função de callback: lum_track("userAttributes", { firstName: "John", lastName: "Smith", customAttributes: { company: null } }, callback);

identify

Identifica o usuário atualmente sendo rastreado por esta API. Esta operação internamente executa a API REST identify para o usuário atualmente rastreado.

O uso desta operação é relevante apenas para soluções que utilizam identificador amigável, conforme apresentado nos cenários na introdução da API REST de usuários monitorados.

Sintaxe

lum_track("identify", friendlyId, callback)

Argumentos

Nome	Descrição	Tipo	Requerido
friendlyId	Identificador amigável.	String, até 255 caracteres	Sim
callback	Função de callback.	Function	Não

Exemplos de uso

Identificando um usuário em um cenário onde e-mail é utilizado como identificador amigável.: lum_track("identify", "jds@example.com");
Identificando um usuário em um cenário onde o CPF é utilizado como identificador amigável, e fornecendo uma função de callback.: lum_track("identify", "11111111111", callback);