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 Javascript 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.

Todas as coletas de eventos são realizadas no escopo de algum projeto.
A REST API de Monitoramento tenta inferir o projeto a qual a coleta se refere de forma automática. Porém, caso não seja possível essa inferência ou caso se necessite alterar o identificador do projeto por alguma razão, há duas formas de se fazer isso:

Definindo o identificador do projeto na configuração da API Javascript de monitoramento.
Para isso, basta definir o argumento projectId no objeto de configuração, como:
lum_track("config", { baseHref: "https://www.meulumisxp.com.br/", projectId: "identificador-do-meu-projeto" });
Passando o identificador do projeto diretamente nos dados da coleta, utilizando a chave lum_event.projectId, como: lum_track("event", "customeventid", { ... "lum_event.projectId": "identificador-do-meu-projeto" });

Caso haja um identificador de projeto em ambos os locais, o que será considerado é o que estiver dos dados do evento.

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.

Caso esteja utilizando esta API em uma página servida pelo LumisXP e as operações desta API serão feitas para este mesmo servidor, o armazenamento do rastreio deve ser feito através de cookie com nome lumMonUid no mesmo caminho e domínio gerado pelo servidor, para que desta forma esta API funcione integrada com o cookie gerado pelo LumisXP. Os valores padrões tentam detectar a presença de window.g_LumisRootPath (normalmente presente em páginas servidas pelo LumisXP) para assumir valores padrões que normalmente atendem este cenário. Mas dependendo das configurações de seu ambiente pode ser necessário ajustar alguma configuração para que o cookie correto seja utilizado.

Caso esteja utilizando esta API em uma página servida pelo LumisXP, mas esta API está sendo utilizada para acessar outro servidor LumisXP independente, o nome do cookie deve ser alterado usando a configuração cookieName para evitar que ele conflite com o cookie lumMonUid gerado pelo LumisXP que serviu a página. Deve-se fazer isto mesmo caso configure o clientStorage como local, pois o cookie ainda poderá ser utilizado em navegadores onde o localStorage esteja indisponível.

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.
cookieName	Nome utilizado para o cookie de rastreamento. O valor padrão é `lumMonUid`.
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.
projectId	Identificador do projeto a ser utilizado na coleta de eventos.	O padrão é sem valor. Nesse caso, não haverá um identificador de projeto padrão a ser enviado no momento das coletas.

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, limitando a utilização do cookie a um domínio específico e especificando um nome para ser utilizado para o cookie.: lum_track("config", { baseHref: "https://www.meulumisxp.com.br/", clientStorage: "cookie", cookieName: "mytrackid", domain: "meusite.meudominio.com" });
Configurando o baseHref (uso em um site externo ao LumisXP, por exemplo) e definindo um identificador de projeto padrão a ser utilizado nas coletas de eventos.: lum_track("config", { baseHref: "https://www.meulumisxp.com.br/", projectId: "identificador-do-meu-projeto" });

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 um objeto estilo dicionário e passando um identificador de projeto nos dados da coleta (sob a chave lum_event.projectId): lum_track("event", "customeventid", { "custom.field1": "value", "custom.field2": ["value1","value2"], "lum_event.projectId": "identificador-do-meu-projeto" });
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.

Uma vez que esta operação é disparada, outras operações do lum_track chamadas posteriormente ficarão enfileradas até que esta complete sua execução. Isto é para garantir que as operações subsequentes sejam executadas como o usuário identificado por esta operação. Observe que caso esta operação resulte em erro, as operações subsequentes ainda assim serão executadas, mas sem a alteração de usuário atualmente rastreado que esta operação faria. Se por alguma razão esta operação não completar sua execução (como por exemplo: falha na comunicação de rede ou cancelamento de seu envio pelo navegador por causa de uma navegação para outra página), as demais operações enfileradas não executarão. Para ter informações mais precisas sobre o resultado desta operação e assim poder ter mais controle no comportamento a ser adotado em cada caso, pode-se utilizar um callback ao chamar esta operação.

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.withCredentials = true; 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(); });

privacyTerm

Realiza as operações referentes a API REST de Termo de Privacidade.

Sintaxe

lum_track("privacyTerm", operation, serviceInstanceId, callback)

Argumentos

Nome	Descrição	Tipo	Requerido
operation	A operação a ser realizada no serviço de termo de privacidade. As operações permitidas são: `isAllAccepted`: Retorna se o usuário aceitou todas as finalidades do termo de privacidade cadastrado nessa instância de serviço; `acceptAll`: Aceita todas as finalidades do termo de privacidade cadastrado nessa instância de serviço; `revokeAll`: Revoga todas as finalidades aceitas pelo usuário no termo de privacidade cadastrado nessa instância de serviço.	String	Sim
serviceInstanceId	O identificador da instância de serviço de termo de privacidade onde as operações serão realizadas.	String	Sim
callback	Função de callback.	Function	Não

Exemplos de uso

Verifica se um usuário consentiu um determinado termo de privacidade: lum_track("privacyTerm", "isAllAccepted", "<serviceInstanceId>", function(e) { // verifica se a requisição foi realizada com sucesso if (e.success) { // retorna o resultado da consulta em um alert, 'result' é um booleano indicando se o usuário consentiu ou não o termo associado a esta instância de serviço alert(e.result); } });
Faz o usuário consentir um determinado termo de privacidade: lum_track("privacyTerm", "acceptAll", "<serviceInstanceId>", function(e) { // verifica se a requisição foi realizada com sucesso if (!e.success) { alert('A operação falhou'); } });
Revoga o consentimento do usuário a um determinado termo de privacidade: lum_track("privacyTerm", "revokeAll", "<serviceInstanceId>", function(e) { // verifica se a requisição foi realizada com sucesso if (!e.success) { alert('A operação falhou'); } });

abtest

Realiza operações referentes ao Modo de Teste A/B. Abaixo cada operação desta categoria é detalhada em mais detalhes. Estas operações recebem como parâmetro o identificador do experimento. Para obter este identificador, utilize a administração do Modo de Teste A/B, onde é possível visualizar exemplos já com o identificador do experimento selecionado.

applyExperiment

Inicia um experimento para o usuário atual. Quando essa ação for chamada, a experiência do usuário atual será alterada de acordo com as configurações da variante escolhida pelo framework , caso a mesma não seja o grupo de controle. Caso essa operação já tenha sido realizada na sessão atual do usuário, a mesma variante escolhida previamente será utilizada para alterar o comportamento do usuário mantendo, assim, sua experiência uniforme durante toda a sua sessão. Caso contrário, o framework irá utilizar todas as regras de publicação e probabilidades para escolher uma variante do experimento para ser aplicada ao usuário atual. Essa mesma variante será aplicada durante toda a sessão do usuário. Nesse caso, um evento de início de experimento será coletado com as informações do experimento e da variante escolhida.

Se o experimento ou a variante que já está associada à sessão não existe mais (foi excluído), a chamada REST resultará em erro e nada será aplicado à página.

Sintaxe

lum_track("abtest", "applyExperiment", experimentId, callback, element, timeout)

Argumentos

Nome	Descrição	Tipo	Requerido
experimentId	O identificador do experimento a ser aplicado.	String	Sim
callback	Função de callback.	Function	Não
element	Elemento base na qual o experimento será aplicado.	HTMLElement	Não
timeout	Tempo máximo (em milissegundos) que a chamada ao servidor irá aguardar.	Number	Não

Exemplos de uso

Aplicar um experimento de teste A/B na página atual.: lum_track("abtest", "applyExperiment", "4028E38174DB00800174DC13DC3409A8", function(e) { // verifica se a requisição foi realizada com sucesso if (!e.success) { alert('A operação falhou'); } });

experimentGoalAchieved

Indica que o objetivo de um experimento foi alcançado, contabilizando esta ocorrência com um evento de objetivo de experimento alcançado. A sessão atual guarda a informação de que esse experimento teve objetivo alcançado. Mesmo após um experimento ter seu objetivo alcançado em uma sessão, ela continuará utilizando a mesma variante de um experimento quando aplicado.

Caso esta operação seja executada em uma sessão onde o respectivo experimento ainda não foi aplicado, já teve seu objetivo alcançado ou tenha sido abandonado, esta operação não fará nada. Neste caso o valor de success no callback também será true, pois não representa cenário de erro e é o comportamento esperado.

Sintaxe

lum_track("abtest", "experimentGoalAchieved", experimentId, callback)

Argumentos

Nome	Descrição	Tipo	Requerido
experimentId	O identificador do experimento que teve seu objetivo alcançado.	String	Sim
callback	Função de callback.	Function	Não

Exemplos de uso

Indicar que um experimento atingiu seu objetivo.: lum_track("abtest", "experimentGoalAchieved", "4028E38174DB00800174DC13DC3409A8", function(e) { // verifica se a requisição foi realizada com sucesso if (!e.success) { alert('A operação falhou'); } });

abandonExperiment

Abandona o andamento de um experimento, contabilizando esta ocorrência com um evento de experimento abandonado. A sessão atual guarda a informação de que esse experimento foi abandonada. Mesmo após um experimento ser abandonado em uma sessão, ela continuará utilizando a mesma variante de um experimento quando aplicado.

Sintaxe

lum_track("abtest", "abandonExperiment", experimentId, callback)

Argumentos

Nome	Descrição	Tipo	Requerido
experimentId	O identificador do experimento a ser abandonado.	String	Sim
callback	Função de callback.	Function	Não

Exemplos de uso

Abandonar um experimento.: lum_track("abtest", "abandonExperiment", "4028E38174DB00800174DC13DC3409A8", function(e) { // verifica se a requisição foi realizada com sucesso if (!e.success) { alert('A operação falhou'); } });