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 argumentoprojectId
no objeto de configuração, como:
-
Passando o identificador do projeto diretamente nos dados da coleta, utilizando a chave
lum_event.projectId
, como:
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
.
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
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
Em páginas de domínio servido pelo LumisXP deve-se utilizar a opção 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. |
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) -
Configurando o
baseHref
(uso em um site externo ao LumisXP, por exemplo) e para o armazenamento ser em cookie ao invés de localStorage. -
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. -
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. -
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.
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 |
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
Esta operação fornece automaticamente valores para os campos |
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
- Registrando a ocorrência de um evento customizado e fornecendo uma função de callback
- Registrando a ocorrência de um evento customizado com informações para campos deste evento usando um objeto estilo dicionário
- 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
) - Registrando a ocorrência de um evento customizado com informações para campos deste evento usando objetos hierárquicos
- Registrando a ocorrência de um evento customizado com informações para campos deste evento e fornecendo uma função de 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
- Preenchendo atributos
firstName
elastName
, removendo qualquer valor existente no atributo customizado com identificadorcompany
e fornecendo uma função de 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.
- Identificando um usuário em um cenário onde o CPF é utilizado como identificador amigável, e fornecendo uma função de 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.
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:
|
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
- Faz o usuário consentir um determinado termo de privacidade
- Revoga o consentimento do usuário a um determinado termo de privacidade