使用AquaLogic Interaction Analytics 2.0 OpenUsage API

摘要

　　BEA AquaLogic Interaction Analytics 2.0用于收集有关发生在门户和Web应用程序中的行为的信息，这样就能更好地对用户需求做出响应。Analytics 2.0提供有关使用特定内容项和portlet，以及诸如文档下载和讨论发表这样的社区行为的详细信息。它甚至能跟踪小组或单个用户的行为。这些详细的使用信息可以确保为用户开发和交付最佳内容和应用程序。

　　借助Analytics OpenUsage API，您可以利用自定义应用程序中的Analytics功能。这份指南简要介绍了OpenUsage，并提供了基本的用例和一个简化的例子。示例应用程序包括调用OpenUsage Java API和使用OpenUsage事件标记的例子。

简介

　　可以使用OpenUsage API从自定义portlet和应用程序引发Analytics事件，并把它们保存在Analytics数据库中。使用这个API惟一的要求就是拥有OpenUsage库和到支持UDP通信的网络的连接。Analytics系统的基本架构如图1所示。

　　图1. Analytics 架构

　　OpenUsage API把来自门户服务器上交互组件的门户使用跟踪信息，以及来自外部应用程序的自定义门户和非门户事件，通过门户消息总线（Portal Message Bus，PMB）发送到Analytics Collector Service。Analytics服务安装在单独的Analytics Services Server上。Analytics数据库保存了收集到的所有信息，并把它们返回给Analytics Services Server或外部应用程序。Analytics Service通过门户服务器上的Analytics Console或Analytics portlet将Analytics数据提供给最终用户。

　　想要了解安装和配置Analytics组件的详细信息，可以参见产品文档中的Installation and Upgrade Guide for BEA AquaLogic Interaction Analytics一文。

　　Analytics 2.0引入了新的OpenUsage方法，用于在运行时定义和设置事件类型。AquaLogic Interaction门户中的Analytics Administration实用工具提供了一个简单的界面，用于定义自定义事件、参数和维度。然后就可以使用SQL查询事件数据，再报告给非门户应用程序。

　　通常通过以下这些步骤，您就可以开始使用Analytics和OpenUsage API了：

• 步骤1：定义事件模型：决定要捕捉哪些事件，以及如何在Analytics数据库中定义它们。这一节包括4个简单的例子：User interest statistics、Customer follow-through statistics、Content repository usage statistics和Advertising campaign statistics。
• 步骤2：在Analytics Administration中注册和配置事件：使用Analytics Administration配置要收集并保存在Analytic数据库中的自定义事件和参数。
• 步骤3：给应用程序添加Analytics 事件：使用OpenUsage从自定义应用程序中引发事件。这一节包括使用OpenUsage event tag和OpenUsage Java API的例子。
• 步骤4：配置和运行Analytics：配置服务器与Analytics进行通信，然后启动Analytics Collector Service。这一节仅提供了简单的指导。想要了解配置Analytics的详细信息，可以参见产品文档中的Installation and Upgrade Guide for BEA AquaLogic Interaction Analytics一文。
• 步骤5：查询Analytics并显示统计信息：从Analytics数据库获取数据并显示报告来说明统计信息。这个例子使用了JFreeCharts和cewolf标记来显示结果。

　　让我们开始吧。

步骤1：定义事件模型

　　在自定义应用程序中使用Analytics功能的第一个步骤是，决定有用的事件和要跟踪的信息。Analytics数据库使用了标准的星型模式，为数据存储提供了几乎是无限的灵活性。

　　需要按照下面的步骤来定义事件模型：

1. 识别要捕捉的事件。事件通常定义了一个用户操作，例如点击、页面访问或下载。在很多情况下，可以使用门户事件来捕捉需要的信息。OpenUsage API提供对以下标准门户事件的访问：
   • 目录查看
   • 文档查看
   • 页面查看
   • Portlet查看和使用
   • 搜索查询及结果
   • 登录/注销

   　　还可以引发自定义事件和定义自己的参数。对于每个自定义事件来说，已经为它们在Analytics数据库中创建了一张新的事实表。想要了解Analytics数据库实现的详细信息，可以参考产品文档中的AquaLogic Interaction Analytics Database Schema一文。

2. 找出关于要跟踪的事件的事实，例如，日期、时间、页面、用户、组或成员状态。每个事件都包括几个事实，由事件参数表示，它们定义了由事件生成的数据类型。默认情况下，每个事件均包括以下事件参数：

   参数	描述
   USERID	触发事件的用户的ID。必须使用OpenUsage API设置User ID。
   TIMEID	为事件的每次出现所创建的惟一ID编号。这个值是由Analytics设置的。
   VISITID	触发事件的用户的门户访问ID。这个参数只适用于出现在门户中的事件。
   OCCURRED	生成事件的日期和时间。日期/时间戳的格式是由数据库类型决定的。这个值是由Analytics设置的。

   　　OpenUsage API中的所有接口都包括用于获取和设置标准参数的方法，包括用户ID、portlet ID、页面ID、URL和引用者。想要获得每个事件类型的标准参数的完整列表，可以参见OpenUsage API 文档（javadoc）。还可以创建自己的事件参数，以便捕捉提供的默认参数中没有定义的数据。

3. 要捕捉非数字数据，可以定义维度表，例如URL、页面名称、用户名称、组名称或成员级别。可以在自己的应用程序表中使用维度，或者在Analytics Administration中创建新的维度（参见步骤2：在Analytics Administration中注册和配置事件）。

例子

　　下面的例子描述了事件模型。

#1：用户兴趣统计信息

　　Palo Alto Golf Course（PAGC）将建立新的类别，想知道用户对哪些主题最感兴趣。他们决定在Golf Digest的Web站点上发布一个portlet，该portlet列出了3篇特定于问题的文章，然后跟踪哪个链接的用户点击率最高。他们还想跟踪用户的技巧水平，因为门户中将其定义为一个用户属性。因为用户分为3个门户组，PAGC还想跟踪用户的组成员关系。

　　解决方案：

　　PAGC创建了一个用于显示通向3篇文章的链接的portlet。每个链接都指向一个重定向页面，这些页面将调用OpenUsage API中的sendEvent方法，传递该页面的事件类型ID、日期-时间和用户ID。重定向页面重定向到了实际的链接目标。

　　管理员在Analytics Administration中为文章点击注册了一个自定义事件，以及相应的事件参数（事件类型ID、日期-时间和用户ID）。用户ID参数对应于现有的门户用户维度表，该表包含了技巧水平和组成员关系。

　　PAGC创建了一个用于显示哪个链接点击率最高的报告，按照技巧水平或门户组进行分组。

#2：客户行为统计信息

　　BMW正在开发一个用于在线定购汽车配件的门户应用程序。该应用程序允许用户浏览配件目录，查看详细信息，把配件加入购物车，以及购买添加到购物车中的配件。BMW想要跟踪以下统计信息：

• 用户点击浏览目录的次数。
• 用户选择查看每个配件的详细描述的次数（对每个配件进行统计）。
• 启动的购物车会话个数。
• 每个配件添加到购物车中的次数（对每个配件进行统计）。
• 每个配件转化为订单的次数（对每个配件进行统计）。

　　解决方案：

　　从门户应用程序调用OpenUsage API可以捕捉到所有的事件。还可以通过在详细信息页面上放置一个OpenUsage事件标记而捕捉到VIEW_ITEM事件。

　　管理员在Analytics Administration中注册了5个自定义事件：

• BROWSE：当用户点击目录浏览按钮时发送。
• VIEW_ITEM：当用户查看特定配件时发送。配件ID作为参数进行传递。
• NEW_SHOPPING_CART：当启动新的购物车会话时发送。
• ADD_ITEM：当用户添加一个配件到购物车中时发送。配件ID作为参数进行传递。
• CONVERTED_ITEM：当某个配件转化为订单时发送。配件ID作为参数进行传递。

　　BMW创建报告来显示多少用户曾经点击浏览目录，显示启动了多少购物车会话，并显示每个配件被查看、添加到购物车中和/或购买的详细情况。

#3：内容库使用统计信息

　　Netformx Software在其支持页面上已经有一个知识库搜索portlet，允许用户搜索用户手册、文章、营销材料和/或白皮书中的术语。Netformx希望通过该portlet知道这4个库中哪一个搜索的频率最高。

　　解决方案：

　　点击Search按钮之后，portlet就会调用OpenUsageAPI，并传入正确的知识库作为事件参数。如果被选中的库不止一个，则会为每个被选中的库发送一个事件。

　　如果portlet使用ISearchEvent或IDirView接口引发标准的门户事件，就不需要在Analytics Administration中注册自定义事件。

　　Netformx创建了一份报告来比较4个库的使用情况。

#4：广告活动统计信息

　　St. Paul Brewing Company计划推出一种新款啤酒，这种啤酒没有掺碳，不含卡路里，也没什么味道。他们计划通过电子邮件和Google及Yahoo上的广告来提升这款啤酒的知名度。他们对如下统计信息感兴趣：

• 读取电子邮件的次数。
• 每次活动（即电子邮件、Google、Yahoo）的点击次数。
• 每次活动中通过点击而创建的新用户帐号的个数。
• 对每次营销活动中生成的新啤酒社区的社区访问次数。
• 每次营销活动中下载的免费啤酒招待券的数量（记载在kd中）。

　　解决方案：

　　就像其他例子一样，所有事件均可通过参数正确的OpenUsage API调用进行发送。可以使用OpenUsage标记跟踪页面访问。管理员可以在Analytics Administration中注册任何自定义事件和自定义事件参数。可以创建一些报表来显示活动中的统计信息。

　　步骤2：在Analytics Administration中注册和配置事件

　　下一步是在Analytics Administration中注册任意自定义事件，这样Analytics Collector Service才能识别这些事件。门户事件的收集是自动进行的。自定义（非门户）事件在Analytics Administration中叫做托管事件（Managed Event）。

　　要捕捉非数字数据，必须使用维度表。可以使用现有的维度表或创建新的维度表，在Analytics Administration中叫做托管维度（Managed Dimension）。创建新的维度之后，必须创建一个String类型的新事件参数，并把它关联到维度上（参见下面的步骤3到5）。要使用现有的维度表，可以创建一个Integer类型的参数，该参数映射到维度表中的ID列。我们建议不要创建过多的新维度，因为它们将会降低数据采集和报表的速度。

　　这个例子中使用的示例应用程序在一个portlet中显示了链接，并跟踪用户访问了哪个页面。该应用程序还跟踪哪个OpenUsage方法用于引发事件。事件模型使用一个带有4个参数的自定义事件，其中2个参数已经与维度表关联起来。这些说明解释如何在Analytics Administration中注册这个自定义事件：

1. 打开AquaLogic Interaction portal Administration。点击Select Utility下拉列表，然后选择Analytics Administration。
2. 来到Analytics Manager中的Event Registration页面，如图2所示。

   

   　　图2. Analytics Manager事件注册

3. 在Managed Dimensions下单击Add。创建一个名为event method的新维度。（维度名称的长度最多为20个字符，只能包含字母、数字、空格和下划线。）保留默认的表名称。如果希望维度的值是惟一的，您可以选择“Unique?”复选框来减小表的大小。
4. 在Managed Dimensions下单击Add。创建一个名为page name的新维度。保留默认的表名称。
5. 在Managed Events下单击Add。创建一个名为demo event的新事件，下面的表中列出了这个事件所带的参数。保留默认的表名和列名，如图3所示。（事件和参数名称的长度最多为14个字符，只能包含字母、数字、空格和下划线。）

   名称	数据类型	维度
   page id	Integer	-
   page name	String	page name
   event method	String	event method
   date	Date	-

   

   　　图3. Analytics Manager Create Event编辑器

6. 单击Finish保存事件。
7. 在Event Registration页面上选择demo event旁边的复选框，然后单击Enable。（默认情况下，单击Enable之后30分钟，Analytics Collector Service开始保存事件的数据。）
8. 单击Finish保存修改。警告：在Event Registration页面上单击Finish之后，便无法删除或重命名事件或其参数。

注意：Event Registration页面列出了数据库中为自定义事件及其维度所创建的表的名称（ASCFACT_*用于事实表，而ASCDIM_*用于维度表）。这些表名仅用于查询数据库。OpenUsage API使用UI中定义的事件或维度名称（即使用"demo event"而不是"ASCFACT_DEMO_EVENT"）。

　　要了解 Analytics Administration中其他页面的详细信息，可以参见在线帮助或Administrator Guide for BEA AquaLogic Interaction Analytics。

步骤3：给应用程序添加Analytics事件

　　在Analytics Administration中定义事件之后，可以使用OpenUsage引发事件，从而对用户操作做出响应。

　　这个例子是一个实现为portlet的示例应用程序，如图4所示。该portlet是一个JSP页面，显示了2个静态链接和一个带有提交按钮（"Go to My Demo Page!"）的文本框。在该portlet的底部，有2个单选按钮和另一个提交按钮（"View Events!"）。

　　图4. Analytics演示portlet（点击小图可观看全图）

　　portlet中的每个链接都使用了不同的方法来引发事件。

使用OpenUsage 事件标记

　　第一个链接（"OpenUsage Rocks"）把用户带到另一个JSP页面，后者使用<pt:as.event>标记来引发事件。正如下面的代码片段所示，该标记的实现方式是在页面中包含它。对于为Analytics Administration中的事件定义的每个参数，都包含了一个pt:as.fact属性。要了解详细的语法，可以参见OpenUsage TagDocs。

　　注意：标记只能用在portlet和作为网关的页面中，因为它们必须由AquaLogic Interaction Tag Transformation Engine进行处理。要了解关于使用标记的介绍，可以参见ALUI开发文档中的Using ALI Adaptive Tags。

<p><html>
<body>
...
<h1>OpenUsage Rocks!</h1>
<p>(This page generates an event using the OpenUsage Portal Tag Library)
<p><a href="demo.jsp">Back</a>

<!-- Send the event using the OpenUsage tag library -->
<span xmlns:pt='http://www.plumtree.com/xmlschemas/ptui/'>
<pt:as.event pt:name="demo event" pt:userID="1">
  <pt:as.fact pt:name="page id" pt:value="1" pt:type="integer"/>
  <pt:as.fact pt:name="page name" pt:value="OpenUsage Rocks!" pt:type="string"/>
  <pt:as.fact pt:name="event method" pt:value="OpenUsage Tag Library" pt:type="string"/>
  <pt:as.fact pt:name="date" pt:value="<%= currentDateString%>" pt:type="date"/>
</pt:as.event>
</span>

</body>
</html>

使用OpenUsage Java API

　　Portlet中的第二个链接把用户带到另一个使用OpenUsage API引发事件的JSP页面。首先，使用ASEventFactory.createManagedEvent()方法创建一个新事件。对于为Analytics Administration中事件定义的每个参数，调用set*Fact()方法。最后，引发事件并使用sendEvent()方法把它发送给Analytics。这些方法可以用在任何可以访问OpenUsage库并连接到支持UDP通信的网络的应用程序中。要了解关于这些方法的更多详细信息，可以参见OpenUsage API documentation（javadoc）。

<p><%@page import="java.text.SimpleDateFormat"%>
<%@page import="com.plumtree.analytics.openusage.*"%></p><p><html>
<body>
<h1>OpenUsage Is A-OK!</h1>
<p>
  (This page generates an event using the OpenUsage Java API)
<p>
<a href="demo.jsp">Back</a

<%
  // create the event using the OpenUsage Java API
  IManagedEvent evt = ASEventFactory.createManagedEvent("demo event");
  evt.setUserId(new Integer(1));
  evt.setFact("page id", new Integer(3));
  evt.setFact("page name", "OpenUsage Is A-OK!");
  evt.setFact("event method", "OpenUsage Java API");
  evt.setLongAsDateFact("date", new Long(System.currentTimeMillis()));</p><p> // send it!
  evt.sendEvent(); 
%>
</body>
</html>

　　Portlet中的文本框/提交按钮（"Go to My Demo Page!"）还使用了OpenUsage API来引发事件。表单包括一个隐藏的输入元素，该元素触发Java servlet来引发事件。servlet用于引发事件的代码与上面的完全一样，除了它接受了在文本框中输入的页面名称。这个值保存在页面名称维度表中。

　　在 下载 部分中可以找到这个示例应用程序中使用的所有文件。

步骤4：配置和运行Analytics

　　必须通过修改database.properties和openusage.xml文件，把Analytics配置为保存自定义应用程序中的事件。由于仅仅是为了举个例子，下面的说明也就相应地做了简化。要了解Analytics使用的端口列表和配置Analytics数据库的详细信息，可以参见Installation and Upgrade Guide for BEA AquaLogic Interaction Analytics。

• 在openusage.xml文件中输入Analytics服务器端口：

<UNICAST_MODE>YES</UNICAST_MODE>
<UNICAST_IP>$analytics_server_host$|port=31314</UNICAST_IP>

• 在database.properties文件中输入Analytics Server的数据库信息。（使用适用于配置的驱动程序和URL。）

jdbc.driver=com.plumtree.jdbc.sqlserver.SQLServerDriver
jdbc.url=jdbc\:plumtree\:sqlserver\://$analytics_database_server$\:1433;DatabaseName\=$analytics_database_name$
jdbc.user=$analytics_database_user$
jdbc.password=$analytics_database_password$

• 在正确的配置位置放置这2个配置文件。openusage.xml文件可以放在任何地方，但是当初始化OpenUsage时代码必须引用这个文件。这是通过调用下面的方法来实现的，在这个方法中，configDirectory是openusage.xml文件所在的文件夹。（在应用程序运行期间，通常是在启动期间，只需要调用这个方法一次。）

ASEventFactory.setConfig("configDirectory", "openusage.xml"); 

　　在示例应用程序中，OpenUsageDemoServlet在init()方法中调用setConfig。web.xml文件中把configDirectory参数定义为.\openusage-demo\config\settings。要修改这个位置，打开.war文件，然后修改web.xml中的configDirectory init-param。

• 把应用程序 .war文件部署到任意Java Servlet Container中。
• 在Analytics服务器对话框上，确保启动了Analytics Collector Service。

步骤5：查询Analytics和显示统计信息

　　Analytics包括一组用于显示门户事件的标准报表，请参见Administrator Guide for BEA AquaLogic Interaction Analytics。要从Analytics数据库的自定义报表中检索数据，可以使用SQL。要定义或确定表名和列名，可以参考Analytics Administration的Event Registration页面（参见步骤2：在Analytics Administration中注册和配置事件）。要了解对Analytics提供的表的说明，参见产品文档中的AquaLogic Interaction Analytics Database Schema。

　　在这个示例应用程序中，按下按钮可以看到一个JSP页面，上面显示了指示每个页面名称的点击次数百分比的饼图，如图5所示，或者是指示事件方法使用百分比的饼图，如图6所示。

　　图5.按页面名称进行分组的结果

　　图6.按照方法名称进行分组的结果

　　处理Analytics数据库查询和引发Go to My Demo Page!事件的是同一个servlet。

/**
* View "demo event" data using JFreeCharts and cewolf tag libraries.
*
* @param req HttpServletRequest
* @param res HttpServletResponse
*/
public void viewEvents(HttpServletRequest req, HttpServletResponse res) 
throws IOException, ServletException {
try {
Connection conn = getDatabaseConnection();
Statement stmt = conn.createStatement();
String query = "";
if ("EVENT_METHOD".equals(req.getParameter("groupby"))) {
// group by eventMethod
query = "select count(*), method.value " + "from ascfact_demo_event fact, ascdim_page_name page, ascdim_event_method
method " + "where fact.page_name = page.id and fact.event_method = method.id " + "group by method.value";
req.getSession().setAttribute("GROUP_BY_CHECKED", "EVENT_METHOD"); 
} else {
// group by pageName
query = "select count(*), page.value " + "from ascfact_demo_event fact, ascdim_page_name page, ascdim_event_method
method " + "where fact.page_name = page.id and fact.event_method = method.id " + "group by page.value";
req.getSession().setAttribute("GROUP_BY_CHECKED", "PAGE_NAME"); 
}
// execute the query
ResultSet results = stmt.executeQuery(query);
// create a JFreeChart DatasetProducer which will be rendered by the cewolf tag library
DatasetProducer datasource = new PieChartDatasetProducer(results);
req.setAttribute("datasource", datasource);
// close database resources
results.close();
stmt.close();
conn.close();
} catch (Exception e) {
e.printStackTrace();
throw new ServletException("Exception while creating DatasetProducer - " + e);
}
RequestDispatcher dis = req.getRequestDispatcher("demo_chart.jsp"); 
dis.forward(req, res);
}

　　示例应用程序使用JFreeCharts数据集生产者对数据进行迭代。显示饼图的JSP页面使用cewolf标记来呈现来自JFreeCharts数据集生产者的数据。要查看这些组件的代码，参见例子下载中的PieChartDatasetProducer.java和demo_chart.jsp文件。

结束语

　　BEA AquaLogic Interaction Analytics支持对行为和使用情况进行跟踪，以确保用户能够发现所需的资源。Analytics OpenUsage API提供各种方式在门户和Web应用程序中引发自定义事件，以便把这些事件保存在Analytics数据库中。