Introdução ao Serviço de Analítica

Bem-vindo à Introdução ao serviço de Analítica. Esta página é o ponto de início para o aprendizado de serviço de Analítica. Os seguintes tópicos serão cobertos:

Visão Geral

O aplicativo serviço de Analítica foi criado para complementar o uso do dojox.analytics e dos plug-ins relacionados do Dojo Toolkit for JavaScript. O Analítica fornece uma forma de controlar eventos (Dojo, cliques do mouse e assim por diante) e gerar a criação de log de código do lado do cliente. As informações analíticas são frequentemente gerenciadas no cliente e enviadas, potencialmente, a diversos servidores diferentes de analítica. Isso pode ser incômodo e, normalmente, requer a comunicação com domínios fora do servidor que forneceu o aplicativo. O serviço de Analítica fornece uma forma de tratar a multiplexação da analítica e da criação de log no lado do servidor. O código dojox.analytics existente no cliente envia os eventos para o mesmo servidor que forneceu o aplicativo, o que elimina qualquer problema de domínio cruzado.

No servidor, o aplicativo serviço de Analítica inclui um recurso JAX-RS do lado do servidor que aceita as solicitações enviadas do código dojox.analytics dos clientes. Os parâmetros de inicialização do servlet podem ser configurados no aplicativo serviço de Analítica para configurar como ele trata os eventos de analítica. Por padrão, todos os eventos são enviados para um único arquivo de log, analytics_default.log.

Pré-requisitos

Pré-requisito do produto Version
Java Technology Edition 5.0 e posterior
Servidor de aplicativos Java Platform, Enterprise Edition 5 (Java EE) e posterior

WebSphere Application Server Versão 6.1.0.x e posterior

WebSphere Application Server Community Edition Versão 2.X

Navegador da Web Qualquer navegador da Web atualizado, como o Internet Explorer 7 e posterior, Mozilla Firefox 3.x e posterior, Google Chrome, Safari, Opera

Usando o serviço de Analítica

O serviço de Analítica será útil somente se o JavaScript do lado do cliente estiver fazendo uso do dojox.analytics. Para acessar as ferramentas do dojox.analytics, o JavaScript do lado do cliente precisa somente incluir a instrução dojo.require adequada. Com essa dependência determinada, diversas opções estão disponíveis para gerar eventos. Verifique os seguintes exemplos:

Ativar a capacidade de gerar eventos.

dojo.require("dojox.analytics.plugins.dojo");

Gerar um evento dojox.analytics com texto arbitrário.

console.rlog("Qualquer sequência de caracteres entre aspas é colocada aqui.");

Registrar algo com um registro de data e hora de alta precisão.

dojox.analytics.addData("timestamp", [new Date().getTime(), "on-load executed"]);

Além de selecionar quais eventos serão controlados pelo dojox.analytics, é necessária a configuração para identificar a URL relativa ou absoluta do serviço de analítica. Você também pode usar os seguintes parâmetros:

parâmetro djConfig significado e possíveis valores Necessário?
analyticsUrl: URL do serviço de Analítica, completa ou relativa para o recurso atual Sim
sendMethod 'script' ou 'xhrPost' (padrão) sendMethod: 'script' será necessário se o serviço de analítica estiver em um domínio diferente daquele da página referida.
sendInterval Número de milissegundos para acumular eventos, antes de enviar para o serviço de analítica Não, o padrão é 5000 milissegundos

A configuração padrão envia todos os eventos para um único arquivo de log, analytics_default.log, localizado no diretório definido pela propriedade de sistema java.io.tmpdir do servidor, a partir do servidor JVM. Este nome e caminho do arquivo de log de saída pode ser customizado por meio das configurações de propriedade no arquivo web.xml. Para isso, será necessário especificar o caminho completo do arquivo no qual deseja que os eventos sejam registrados, no param-value para o param-name com.ibm.ws.mobile.appsvcs.analytics.logger.LocalFileLogger. Também será necessário especificar um valor de '1.0' para identificar a versão de sintaxe a ser usada pelo serviço. Isso é necessário e simplesmente para permitir a versão no futuro.

A seguinte parte do arquivo web.xml demonstra seu uso:

... <init-param>
    <param-name>com.ibm.ws.mobile.appsvcs.analytics.logger.LocalFileLogger</param-name>
    <param-value>1.0,/tmp/events.log</param-value> </init-param> ...

Também é possível customizar ainda mais o formato do log, especificando quais outras informações são registradas como parte de cada entrada de log. Isso pode ser feito por meio das configurações de propriedade no arquivo web.xml. Para isso, simplesmente especifique uma ou mais palavras-chave predefinidas no param-value para o param-name com.ibm.ws.mobile.appsvcs.analytics.logger.LocalFileLogger.LogFormat.

A seguinte parte do arquivo web.xml demonstra seu uso:

... <init-param>
    <param-name>com.ibm.ws.mobile.appsvcs.analytics.logger.LocalFileLogger.LogFormat</param-name>
    <param-value>CLIENT_IP,CLIENT_SESSION,HTTP_REFERER</param-value> </init-param> ...

É possível escolher qualquer uma das seguintes palavras-chave predefinidas:

entrada do formato do log o que é registrado
CLIENT_SESSION registra o HttpServletRequest#getRequestedSessionId(), O ID de sessão da solicitação especificada pelo cliente
CLIENT_SESSION_FORCED registra o HttpServletRequest#getSession(true).getId(), forçando a criação de uma sessão HTTP se ela não existir e criando log do id da sessão
CLIENT_IP registra o HttpServletRequest#getRemoteAddr(), o endereço do Protocolo da Internet (IP) do cliente
HTTP_REFERER registra o HttpServletRequest#getHeader(), o cabeçalho da solicitação

A etapa seguinte no uso do Serviço de Analítica é iniciar o aplicativo e configurá-lo. Iniciá-lo requer apenas a instalação e implementação do arquivo .ear.

Interface REST do serviço de Analítica

Quando um cliente está usando o dojox.analytics, os eventos que ele gera resultam no envio de solicitações de HTTP a um servidor de analítica. O serviço de Analítica processa essas solicitações ao expor uma interface Representation State Transfer (REST). Consulte a seguinte tabela, que descreve as operações disponíveis.

O serviço de Analítica tratará as solicitações previstas em http://<server>:<port>/<context-root>/<url-pattern>/analytics/logger. A raiz de contexto será definida pelo arquivo application.xml, se o arquivo archive Web (.war) for compactado em um arquivo archive corporativo (.ear). Se o .war for instalado por ele mesmo, a raiz de contexto será definida no momento da instalação pelo usuário. O mapeamento de uri é definido no WEB-INF/web.xml, no arquivo .war.

No appsvcs-analytics.ear fornecido, o arquivo application.xml especifica uma raiz de contexto de "/appsvcs-analytics" e o arquivo web.xml especifica um padrão URL de "/rest/*".

Descrição da Operação Método URI Parâmetros
Relatar uma lista de eventos GET /appsvcs-analytics/rest/analytics/logger Há dois parâmetros de consulta necessários (id e dados) e um opcional (retorno de chamada).
Relatar uma lista de eventos POST /appsvcs-analytics/rest/analytics/logger A solicitação POST usa os mesmos parâmetros, mas eles não fazem parte da consulta de URI. Em vez disso, eles fazem parte do corpo da solicitação de HTTP. Os exemplos são fornecidos abaixo.

A seguinte tabela fornece uma descrição de cada um dos parâmetros.

Parâmetro de Consulta Descrição
id Identificador de evento exclusivo
dados Matriz formatada de eventos JSON
retorno de chamada O nome do método JavaScript que deverá ser incluído na resposta. Consulte as seguintes informações sobre o formato da resposta.

As respostas das solicitações POST e GET não são diferentes. Entretanto, o formato da resposta será ligeiramente diferente, se nenhum parâmetro de retorno de chamada for incluído na solicitação. Os seguintes exemplos abaixo delineiam o formato.

Descrição Solicitação de Amostra Resposta de Amostra
GET com retorno de chamada GET /appsvcs-analytics/rest/analytics/logger?id=1&callback=method &data=[{"plugin":"dojo","data":{"locale":"en-us"}}] method({"eventsReceived":1,"id":"1"})
GET sem retorno de chamada GET /appsvcs-analytics/rest/analytics/logger?id=1 &data=[{"plugin":"dojo","data":{"locale":"en-us"}}] {"eventsReceived":1,"id":"1"}
POST com retorno de chamada POST /appsvcs-analytics/rest/analytics/logger, HTTP body: id=1&callback=method &data=[{"plugin":"dojo","data":{"locale":"en-us"}}] method({"eventsReceived":1,"id":"1"})
POST sem retorno de chamada POST /appsvcs-analytics/rest/analytics/logger, HTTP body: id=1 &data=[{"plugin":"dojo","data":{"locale":"en-us"}}] {"eventsReceived":1,"id":"1"}

Cada solicitação enviada para o serviço REST resulta em uma resposta de HTTP, que inclui um código de status para indicar o tipo de sucesso ou falha. Esses resultados mapeiam bem com códigos de status de HTTP comum.

Código de Status Descrição
200 A operação solicitada foi bem-sucedida.
400 A solicitação incluía valores incorretos nos parâmetros ou no corpo da solicitação.
405 Uma URI não suportada está na solicitação REST.
406 O cliente não suporta o formato JSON necessário, conforme os cabeçalhos da solicitação.
415 A solicitação do cliente inclui um tipo de conteúdo não suportado.
500 Ocorreu um erro inesperado no servidor.

Instalando o serviço de Analítica

Consulte as seguintes instruções de instalação específica da versão:

Instruções de instalação do WebSphere Application

Esta seção descreve o procedimento para instalar o serviço de Analítica na Versão 6.1.0.X e posterior do IBM WebSphere Application Server. Presume-se que esteja familiarizado com a instalação e administração do aplicativo do servidor de aplicativos.

Antes de começar

Localize o arquivo archive corporativo (EAR) do serviço de Analítica fornecido com a instalação do produto. É possível localizar o arquivo EAR na árvore de instalação na qual o IBM WebSphere Application Server Feature Pack for Web 2.0 and Mobile foi instalado. Por exemplo, se instalou o feature pack no seguinte local:

Linux e UNIX: /opt/WebSphere/AppServer
Ponto de montagem do z/OS: <install_root>
Windows: c:\WebSphere\AppServer

Em seguida, será possível localizar o arquivo EAR em:

Linux e UNIX: /opt/WebSphere/AppServer/web2mobilefep_1.1/installableApps/application_services/analytics/appsvcs-analytics.ear
z/OS: <install_root>/web2mobilefep_1.1/installableApps/application_services/analytics/appsvcs-analytics.ear
Windows: c:\WebSphere\AppServer\web2mobilefep_1.1\installableApps\application_services\analytics\appsvcs-analytics.ear

Instalando o serviço de Analítica usando o console administrativo

  1. Efetue login no console administrativo do servidor de aplicativos.
  2. Navegue até Aplicativos > Novo Aplicativo. (Nota: No WebSphere Application Server Versão 6.1, selecione Instalar Novo Aplicativo)
  3. Selecione Novo Aplicativo Corporativo. (Nota: No WebSphere Application Server Versão 6.1, ignore esta etapa)
  4. Navegue no sistema de arquivos e selecione o arquivo appsvcs-graphics.ear localizado anteriormente. Clique em Avançar.
  5. Clique em Avançar para se preparar para a instalação do aplicativo. (Nota: No WebSphere Application Server Versão 6.1, ignore esta etapa)
  6. Clique em Avançar para aceitar as opções de instalação padrão.
  7. Clique em Avançar para aceitar as opções padrão para módulos de mapa para servidores.
  8. Clique em Avançar para aceitar as opções padrão para Metadados para módulos. (Nota: No WebSphere Application Server Versões 6.1 e 7, ignore esta etapa)
  9. Clique em Avançar para aceitar as opções padrão para hosts virtuais de mapa para módulos da Web.
  10. Revise o resumo das opções de instalação.
  11. Clique em Concluir.
  12. Clique em Salvar na configuração principal.
  13. Navegue até Aplicativos > Tipos de Aplicativos > Aplicativos Corporativos do WebSphere. (Nota: No WebSphere Application Server Versão 6.1, navegue até Aplicativos > Aplicativos Corporativos)
  14. Selecione IBM WebSphere Application Server - Serviço de Analítica e clique em Iniciar.

Acessar o cliente demo do aplicativo instalado

Aponte o navegador da Web para a instalação de servidor de aplicativos: http://<application server hostname>:<port>/appsvcs-analytics/

O nome do host e o número da porta do servidor de aplicativos são específicos da instalação de servidor de aplicativos. Uma porta do contêiner da Web da instalação padrão do servidor de aplicativos é 9080. Se estiver executando o navegador da Web na mesma estação de trabalho como a instalação de servidor de aplicativos e tiver aceito todos os valores padrão, então use a seguinte URL: http://localhost:9080/appsvcs-analytics/.

Instruções de instalação do WebSphere Application Server Community Edition Versão 2.X

Esta seção descreve o procedimento para instalar o Serviço de Analítica na Versão 2.X do IBM WebSphere Application Server Community Edition. Presume-se que esteja familiarizado com a instalação e administração do aplicativo do servidor de aplicativos.

Antes de começar

Localize o arquivo archive corporativo (EAR) do Serviço de Analítica fornecido com a instalação do produto. É possível localizar o arquivo EAR na árvore de instalação na qual o IBM WebSphere Application Server Feature Pack for Web 2.0 and Mobile foi instalado. Por exemplo, se instalou o feature pack no seguinte local:

Linux e UNIX: /opt/WebSphere/AppServerCommunityEdition
Windows: c:\WebSphere\AppServerCommunityEdition

Em seguida, será possível localizar o arquivo EAR e os arquivos de biblioteca em:

Linux e UNIX: /opt/WebSphere/AppServerCommunityEdition/web2mobilefep_1.1/AppServices/installableApps/analytics/appsvcs-analytics.ear
Windows: c:\WebSphere\AppServerCommunityEdition\web2mobilefep_1.1\AppServices\installableApps\analytics\appsvcs-analytics.ear

Instalação por meio do console administrativo

Efetue login no console administrativo do servidor de aplicativos.

  1. Clique em Aplicativos > Implementador no menu da esquerda. (Nota: No WebSphere Application Server Community Edition Versão 2.0, clique em Aplicativos> Implementar Novo)
  2. No campo Archive, navegue no sistema de arquivos e selecione o arquivo appsvcs-analytics.ear localizado anteriormente. Mantenha o campo Plano vazio e as opções padrão selecionadas. Em seguida, clique em Instalar.

O aplicativo será iniciado automaticamente e a instalação concluída.

Acessar o cliente demo do aplicativo instalado

Aponte o navegador da Web para a instalação de servidor de aplicativos: http://<application server hostname>:<port>/appsvcs-analytics/.

O nome e a porta do host do servidor de aplicativos são específicos da instalação de servidor de aplicativos. Uma porta do contêiner da Web da instalação padrão do servidor do WebSphere Application Server Community Edition é 8080. Se estiver executando o navegador na mesma estação de trabalho da instalação de servidor de aplicativos e tiver aceito todos os valores padrão, então use a seguinte URL:

http://localhost:8080/appsvcs-analytics/