API Javascript de Monitoramento

Introdução

A API javascript de monitoramento foi projetada para ser usada em páginas web, criadas pelo LumisXP 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 LumisXP, 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 LumisXP ela pode ser automaticamente inicializada, caso se tenha configurado nas propriedades de canais ou páginas para este script ser 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 LumisXP utilizado é https://www.meulumisxp.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 LumisXP, deve-se fazer configurações em Regras de CORS 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.
Para maiores detalhes, veja a página de exemplos completos.

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 LumisXP onde será armazenado as informações coletadas.	Se `window.g_LumisRootPath` estiver definida (por padrão incluída automaticamente em páginas do LumisXP), 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 LumisXP deve-se utilizar a opção `"cookie"` para que a API javascript funcione integrada com cookies que o servidor LumisXP 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 LumisXP), seu valor será utilizado como padrão. Caso contrário `"/"` é o valor padrão.
domain	Domínio para ser atribuído ao cookie, conforme RFC6265. Por exemplo: `meusite.meudominio.com`. Esta configuração só é relevante se o clientStorage for cookie.	Caso não seja informado nenhum valor, o valor aplicado ao cookie automaticamente pelo navegador será o domínio da URL do documento atual.

Exemplos de uso

Configurando o baseHref (uso em um site externo ao LumisXP, por exemplo): lum_track("config", { baseHref: "https://www.meulumisxp.com.br/" });
Configurando o baseHref (uso em um site externo ao LumisXP, por exemplo) e para o armazenamento ser em cookie ao invés de localStorage.: lum_track("config", { baseHref: "https://www.meulumisxp.com.br/", clientStorage: "cookie" });
Configurando o baseHref (uso em um site externo ao LumisXP, 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.meulumisxp.com.br/", clientStorage: "cookie", cookiePath: "/caminho" });
Configurando o baseHref (uso em um site externo ao LumisXP, por exemplo) e para o armazenamento ser em cookie ao invés de localStorage, e limitando a utilização do cookie a um domínio específico.: lum_track("config", { baseHref: "https://www.meulumisxp.com.br/", clientStorage: "cookie", domain: "meusite.meudominio.com" });

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.trackId`, 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.trackId, 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 fornecendo 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", phone: ["(00)1234-5678","(11)98765-4321"] } });
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);

ready

Executa uma função após a inicialização desta biblioteca. Caso já esteja inicializada, a função será executada imediatamente. Caso ocorra erro na inicialização da biblioteca (por exemplo, falha na comunicação com o servidor) a função não será executada.

A função receberá como argumento um objeto que fornece acesso a operações não disponíveis diretamente pelo lum_track, por depender da inicialização desta biblioteca. O argumento oferece as seguintes operações:

Nome	Descrição	Tipo de Retorno
getTrackId()	Retorna o identificador de rastreamento do usuário atual, ou `null` se ele não está sendo monitorado ou se não foi possível recuperar seu identificador.	String

Sintaxe

lum_track("ready", custom_function)

Argumentos

Nome	Descrição	Tipo	Requerido
custom_function	Função que será executada.	Function	Sim

Exemplos de uso

Em uma página web de um sistema externo, usando a API javascript de monitoramento para obter o identificador de rastreamento do usuário para efetuar uma chamada REST para o LumisXP para obter conteúdos personalizados para este usuário.: lum_track("ready", function(tracker) { // obtém o identificador de rastreamento var trackId = tracker.getTrackId(); // valida se foi possível obter o identificador if (!trackId) { console.error("Track identifier could not be obtained"); return; } // obtém conteúdos do REST passando o identificador de rastreamento no cabeçalho especial x-lum-monuid para a resposta ser personalizada para o usuário var xhr = new XMLHttpRequest(); xhr.open("GET", "http://www.example.com/lumis/api/rest/news/lumgetdata/list", true); xhr.setRequestHeader("x-lum-monuid", trackId); xhr.setRequestHeader("accept", "application/json"); xhr.onreadystatechange = function() { if(this.readyState === 4) { if (this.status === 200) { // ler json de resposta do REST var data = JSON.parse(this.responseText); // usar data para exibir os conteúdos para o usuário. neste exemplo apenas fazendo log. console.log(data); } else { console.error("Erro na execução do REST"); } } } xhr.send(); });