BEA WebLogic Portal. Guide to Events and Behavior Tracking

Transcription

1 BEA WebLogic Portal Guide to Evets ad Behavior Trackig Versio 4.02 Documet Date: November 2001

2 Copyright Copyright 2001 BEA Systems, Ic. All Rights Reserved. Restricted Rights Leged This software ad documetatio is subject to ad made available oly pursuat to the terms of the BEA Systems Licese Agreemet ad may be used or copied oly i accordace with the terms of that agreemet. It is agaist the law to copy the software except as specifically allowed i the agreemet. This documet may ot, i whole or i part, be copied, photocopied, reproduced, traslated, or reduced to ay electroic medium or machie-readable form without prior coset, i writig, from BEA Systems, Ic. Use, duplicatio or disclosure by the U.S. Govermet is subject to restrictios set forth i the BEA Systems Licese Agreemet ad i subparagraph (c)(1) of the Commercial Computer Software-Restricted Rights Clause at FAR ; subparagraph (c)(1)(ii) of the Rights i Techical Data ad Computer Software clause at DFARS , subparagraph (d) of the Commercial Computer Software--Licesig clause at NASA FAR supplemet ; or their equivalet. Iformatio i this documet is subject to chage without otice ad does ot represet a commitmet o the part of BEA Systems, Ic. THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. FURTHER, BEA Systems, Ic. DOES NOT WARRANT, GUARANTEE, OR MAKE ANY REPRESENTATIONS REGARDING THE USE, OR THE RESULTS OF THE USE, OF THE SOFTWARE OR WRITTEN MATERIAL IN TERMS OF CORRECTNESS, ACCURACY, RELIABILITY, OR OTHERWISE. Trademarks or Service Marks BEA, WebLogic, Tuxedo, ad Jolt are registered trademarks of BEA Systems, Ic. How Busiess Becomes E-Busiess, BEA WebLogic E-Busiess Platform, BEA Builder, BEA Maager, BEA elik, BEA WebLogic Commerce Server, BEA WebLogic Persoalizatio Server, BEA WebLogic Portal, BEA WebLogic Process Itegrator, BEA WebLogic Collaborate, BEA WebLogic Eterprise, ad BEA WebLogic Server are trademarks of BEA Systems, Ic. All other product ames may be trademarks of the respective compaies with which they are associated. Guide to Evets ad Behavior Trackig Documet Editio Date Software Versio 4.02 November 2001 WebLogic Portal 4.0 WebLogic Persoalizatio Server 4.0

3 Cotets 1. Overview of Evets ad Behavior Trackig What Are Evets? Behavior Trackig Stadard Evets Sessio Evets SessioBegiEvet SessioEdEvet SessioLogiEvet Registratio Evet UserRegistratioEvet Product Evets ClickProductEvet DisplayProductEvet Cotet Evets ClickCotetEvet DisplayCotetEvet Cart Evets AddToCartEvet RemoveFromCartEvet PurchaseCartEvet Buy Evet BuyEvet Rules Evet RuleEvet Campaig Evets CampaigUserActivityEvet Guide to Evets ad Behavior Trackig iii

4 DisplayCampaigEvet ClickCampaigEvet Servlet Lifecycle Evets ad Servlet Filter Evets Evet Geerators Logi ad Creatio Evets Evet Mechaism Evet Sequece Creatig Custom Evets Overview of Creatig a Custom Evet Writig a Custom Evet Class Writig a Custom Evet Listeer Istallig a Listeer Class i the Evet Service Writig a Behavior Trackig Evet Class Cofigurig Evets Buffer Sweepig Facilitatig OffLie Processig TrackigEvet Base Class Costructor Istallig Behavior Trackig Evets XML Creatio of Behavior Trackig Evets Custom Behavior Trackig Evet Listeers Writig Custom Evet Geerators Debuggig the Evet Service Registerig a Custom Evet Persistig Behavioral Trackig Data Activatig Behavior Trackig Evet Properties Cofigurig the Behavior Trackig Service i WebLogic Server Cofigurig a Data Source Data Storage Relatioal Databases Database Directory Paths Behavior Trackig Database Schema The EVENT Database Table The EVENT_ACTION Database Table iv Guide to Evets ad Behavior Trackig

5 The EVENT_TYPE Database Table Costraits ad Idexes Scripts Developmet Eviromet Sceario Productio Eviromet Sceario Descriptio of Each Script JSP Tag Library Referece for Evets ad Behavior Trackig Idex Cotet <tr:clickcotetevet> Example <tr:displaycotetevet> Example Product <trp:clickproductevet> Example <trp:displayproductevet> Example Guide to Evets ad Behavior Trackig v

6 vi Guide to Evets ad Behavior Trackig

7 About This Documet This documet describes evets ad behavior trackig i BEA WebLogic Portal ad BEA WebLogic Persoalizatio Server. This documet icludes the followig topics: Chapter 1, Overview of Evets ad Behavior Trackig, which describes the high-level architecture for evets ad behavior trackig. It also provides detailed iformatio about each evet type. Chapter 2, Creatig Custom Evets, describes how to create custom evets, custom behavior trackig evets, custom evet listeers, ad custom behavior trackig listeers. Chapter 3, Persistig Behavioral Trackig Data, which describes how to record behavior trackig data ad the database structure for behavior trackig. What You Need to Kow This documet is iteded for the followig audieces: The Commerce Busiess Egieer (CBE) or JSP cotet developer, who uses JSP templates to specify which products ad Web site cotet trigger evets. The busiess aalyst, who defies the compay s busiess protocols for its Web sites. This user may desig sceario actios used i campaigs. The System Aalyst or Database Admiistrator, who admiisters databases. The Java developer, who creates Java code for custom evets. Guide to Evets ad Behavior Trackig vii

8 e-docs Web Site BEA product documetatio is available o the BEA corporate Web site. From the BEA Home page, click o Product Documetatio or go directly to the e-docs Product Documetatio page at How to Prit the Documet You ca prit a copy of this documet from a Web browser, oe file at a time, by usig the File >Prit optio o your Web browser. A PDF versio of this documet is available o the WebLogic Portal ad the WebLogic Persoalizatio Server documetatio Home page o the e-docs Web site (ad also o the documetatio CD). You ca ope the PDF i Adobe Acrobat Reader ad prit the etire documet (or a portio of it) i book format. To access the PDFs, ope the WebLogic Portal ad WebLogic Persoalizatio Server documetatio Home page, click the PDF files butto ad select the documet you wat to prit. If you do ot have the Adobe Acrobat Reader, you ca get it for free from the Adobe Web site at Related Iformatio The followig WebLogic Portal ad WebLogic Persoalizatio Server documets cotai iformatio that is relevat to usig evets ad behavior trackig. Guide to Usig the E-Busiess Cotrol Ceter. Guide to Registerig Customers ad Maagig Customer Services. viii Guide to Evets ad Behavior Trackig

9 Cotact Us! Your feedback o WebLogic Portal ad WebLogic Persoalizatio Server documetatio is importat to us. Sed us at docsupport@beasys.com if you have questios or commets. Your commets will be reviewed directly by the BEA professioals who create ad update the WebLogic Portal ad WebLogic Persoalizatio Server documetatio. I your message, please idicate that you are usig the documetatio for WebLogic Portal ad WebLogic Persoalizatio Server Product Versio: release. If you have ay questios about this versio of WebLogic Portal or WebLogic Persoalizatio Server, or if you have problems istallig ad ruig WebLogic Portal or WebLogic Persoalizatio Server, cotact BEA Customer Support through BEA WebSUPPORT at You ca also cotact Customer Support by usig the cotact iformatio provided o the Customer Support Card, which is icluded i the product package. Whe cotactig Customer Support, be prepared to provide the followig iformatio: Your ame, address, phoe umber, ad fax umber Your compay ame ad compay address Your machie type ad authorizatio codes The ame ad versio of the product you are usig A descriptio of the problem ad the cotet of pertiet error messages Guide to Evets ad Behavior Trackig ix

10 Documetatio Covetios The followig documetatio covetios are used throughout this documet. Covetio boldface text Ctrl+Tab italics moospace text moospace boldface text moospace italic text UPPERCASE TEXT Item Idicates terms defied i the glossary. Idicates that you must press two or more keys simultaeously. Idicates emphasis or book titles. Idicates code samples, commads ad their optios, data structures ad their members, data types, directories, ad fileames ad their extesios. Moospace text also idicates text that you must eter from the keyboard. Examples: #iclude <iostream.h> void mai ( ) the poiter psz chmod u+w * \tux\data\ap.doc tux.doc BITMAP float Idetifies sigificat words i code. Example: void commit ( ) Idetifies variables i code. Example: Strig expr Idicates device ames, eviromet variables, ad logical operators. Examples: LPT1 SIGNON OR x Guide to Evets ad Behavior Trackig

11 Covetio Item { } Idicates a set of choices i a sytax lie. The braces themselves should ever be typed. [ ] Idicates optioal items i a sytax lie. The brackets themselves should ever be typed. Example: buildobjcliet [-v] [-o ame ] [-f file-list]... [-l file-list]... Separates mutually exclusive choices i a sytax lie. The symbol itself should ever be typed.... Idicates oe of the followig i a commad lie: That a argumet ca be repeated several times i a commad lie That the statemet omits additioal optioal argumets That you ca eter additioal parameters, values, or other iformatio The ellipsis itself should ever be typed. Example: buildobjcliet [-v] [-o ame ] [-f file-list]... [-l file-list] Idicates the omissio of items from a code example or from a sytax lie. The vertical ellipsis itself should ever be typed. Guide to Evets ad Behavior Trackig xi

12 xii Guide to Evets ad Behavior Trackig

13 1 Overview of Evets ad Behavior Trackig To help persoalize campaigs ad to effectively aalyze customer iteractios with a Web site, you eed a comprehesive evet trackig ad loggig system. To fulfill this requiremet, BEA WebLogic Portal ad BEA WebLogic Persoalizatio Server iclude a Evet ad Behavior Trackig system. Evets idetify how a customer is curretly iteractig with a e-commerce site ad the Behavior Trackig system records the evet iformatio. With these systems you have the ability to specify, customize, ad record selected iformatio. Evet data ca be used by leadig e-aalytics ad e-marketig systems to evaluate behavioral ad trasactioal data from your olie customers. With this aalysis you ca create ad ehace persoalizatio rules, customize product offers, ad optimize iteractive marketig campaigs. This topic itroduces you to Evets ad Behavior Trackig ad provides a geeral survey of the elemets that make up this system. This topic icludes the followig sectios: What Are Evets? Behavior Trackig Stadard Evets Evet Geerators Evet Mechaism Evet Sequece Guide to Evets ad Behavior Trackig 1-1

14 1 Overview of Evets ad Behavior Trackig What Are Evets? I geeral, a evet is a otificatio that somethig has happeed i a computer program. WebLogic Portal ad WebLogic Persoalizatio Server provide various poits for geeratig evets. Evets provide a detailed ad comprehesive view of the etire customer life cycle across your e-commerce site. These poits ca be tailored for your applicatios. You ca use evets with campaigs to ehace promotio of products ad services. Additioally, you ca use evets to gather itelligece to evaluate the effectiveess of a campaig. Uderlyig campaigs are scearios. Scearios are executed i the cotext of a campaig. Scearios are a set of rules, called sceario actios, that allow you to persoalize customer experieces o your e-commerce site. For example, if a customer clicks a Subscribe Me lik o your Web site, you may wat to sed that customer a cofirmig the subscriptio. Usig evets ad scearios, you ca choreograph the iteractios betwee customers ad your Web site. With regard to trackig visitor behavior for aalysis, the primary iterest is i what the customer saw ad what the customer did. Iheret i this ivestigatio is iformatio about whe customers came to the site ad whe they left it, plus kowledge about which rules were fired durig their visit. Behavior Trackig The Evet service passes messages to Behavior Trackig. Whe Behavior Trackig is tured o, this data is recorded i a relatioal database. This iformatio ca the be used by data-miig systems to provide Web site customer iformatio for e-marketig aalysis. Behavior Trackig provides the followig kids of iformatio: Whe did customers start, ed, or logi to their sessios? What cotet or products did customers see? What cotet or products did customers click o? What did customers put i their shoppig cart? 1-2 Guide to Evets ad Behavior Trackig

15 Stadard Evets What did customers buy? What rules were triggered? The iformatio geerated from these evets allows various kids of behavior aalyses, such as the followig: Associatios: Whe oe evet ca be correlated to aother evet. Sequeces: Whe oe evet leads to aother later evet. Classificatio: The recogitio of patters ad a resultig ew orgaizatio of data. Clusterig: Fidig ad visualizig groups of facts ot previously kow. Forecastig: Discoverig patters i the data that ca lead to predictios about future customer behavior. Stadard Evets This sectio provides iformatio about the stadard evets provided by BEA. Specifically, it cotais a descriptio of each kid of evet, what geerates the evet, the class where evet geeratio occurs, which product cotais the evet, ad the elemets of the evet. Evets elemets comprise the data that is preset withi each evet object. Evets are orgaized ito categories. The followig list presets each type of evet category alog with a brief descriptio of what actios geerates the evet: Sessio: The start time, ed time, ad if executed, the logi time of the customer s sessio. Registratio: The customer registers o the e-commerce site. Product: The customer is preseted with a product or clicks (selects) the preseted product. Cotet: The customer is preseted some cotet, such as a ad, or clicks (selects) the preseted cotet. Guide to Evets ad Behavior Trackig 1-3

16 1 Overview of Evets ad Behavior Trackig Cart: A item is added, removed, or updated to the customer s shoppig cart. Also geerated whe a etire order is purchased. Buy: The customer completes the purchase of oe or more items. Rules: The rules that are fired as a customer avigates a Web site. Campaig: The evets geerated withi the cotext of a campaig. Sessio Evets SessioBegiEvet Sessio evets fire at the start time, ed time, ad if executed, the logi time of a customer s sessio. Descriptio Occurs whe a customer begis iteractig with a Web site. Geerator See Servlet Lifecycle Evets ad Servlet Filter Evets o page Elemets Products evet-date evet-type sessio-id user-id Specific to WebLogic Persoalizatio Server, available i WebLogic Portal. SessioEdEvet Descriptio Occurs whe a customer leaves a Web site, or whe the customer s sessio has timed out. Geerator See Servlet Lifecycle Evets ad Servlet Filter Evets o page Guide to Evets ad Behavior Trackig

17 Stadard Evets Elemets Products evet-date evet-type sessio-id user-id Specific to WebLogic Persoalizatio Server, available i WebLogic Portal. SessioLogiEvet Descriptio Geerator Elemets Products Occurs whe a customer logs o a Web site. TrackigEvetHelper.dispatchSessioLogiEvet(), P13NAuthFilter, ad/or Iput Processor. See Logi ad Creatio Evets o page evet-date evet-type sessio-id user-id Specific to WebLogic Persoalizatio Server, available i WebLogic Portal. Registratio Evet UserRegistratioEvet Oly oe registratio evet exists. It is described i the followig table. Descriptio Geerator Occurs whe customer registers o a Web site. TrackigEvetHelper.dispatchUserRegistratioEve t() ad/or Iput processor. Guide to Evets ad Behavior Trackig 1-5

18 1 Overview of Evets ad Behavior Trackig Example Class Elemets Products examples.wlcs.sampleapp.customer.webflow.logicu stomerip located i PORTAL_HOME\applicatios\wlcsApp\wlcs\WEB-INF\sr c evet-date evet-type sessio-id user-id Specific to WebLogic Persoalizatio Server, available i WebLogic Portal. Product Evets ClickProductEvet These evets occur whe customer is preseted with a product or clicks (selects) the preseted product. Descriptio Geerator Elemets Products Occurs whe a customer clicks a product lik. JSP Tag. Also see Servlet Lifecycle Evets ad Servlet Filter Evets o page evet-date evet-type sessio-id user-id documet-type documet-id sku category-id applicatio-ame WebLogic Portal oly. 1-6 Guide to Evets ad Behavior Trackig

19 Stadard Evets DisplayProductEvet Descriptio Geerator Elemets Products Occurs whe a product is displayed to the customer. JSP Tag evet-date evet-type sessio-id user-id documet-type documet-id sku category-id applicatio-ame WebLogic Portal oly. Cotet Evets ClickCotetEvet These evets occur whe the customer is preseted some cotet, such as a advertisemet, or clicks the preseted cotet. Descriptio Geerator Elemets Occurs whe a customer clicks some Web site cotet, such as a lik or baer. JSP Tag. Also see Servlet Lifecycle Evets ad Servlet Filter Evets o page evet-date evet-type sessio-id user-id documet-type documet-id Guide to Evets ad Behavior Trackig 1-7

20 1 Overview of Evets ad Behavior Trackig Products Specific to WebLogic Persoalizatio Server, available i WebLogic Portal. DisplayCotetEvet Descriptio Geerator Elemets Products Occurs whe cotet is preseted to a customer, usually ay cotet from a cotet maagemet system. JSP Tag evet-date evet-type sessio-id user-id documet-type documet-id Specific to WebLogic Persoalizatio Server, available i WebLogic Portal. Cart Evets AddToCartEvet These evets idicate that oe or more items are added or removed from a customer s shoppig cart. Descriptio Geerator Example Class Occurs whe a item is added to a customer s shoppig cart. Pipelie compoet. Located i PORTAL_HOME\applicatios\wlcsApp-project\applica tio-syc\pipelies. examples.wlcs.sampleapp.trackig.pipelie.addtoc arttrackerpc located i PORTAL_HOME\applicatios\wlcsApp\src 1-8 Guide to Evets ad Behavior Trackig

21 Stadard Evets Elemets Products evet-date evet-type sessio-id user-id sku quatity uit-list-price currecy applicatio-ame WebLogic Portal oly. RemoveFromCartEvet Descriptio Geerator Example Class Elemets Products Occurs whe a item is removed from a customer s shoppig cart. Pipelie compoet. Located i PORTAL_HOME\applicatios\wlcsApp-project\applica tio-syc\pipelies examples.wlcs.sampleapp.trackig.pipelie.remove FromCartTrackerPC located i PORTAL_HOME\applicatios\wlcsApp\src evet-date evet-type sessio-id user-id sku quatity uit-price currecy applicatio-ame WebLogic Portal oly. Guide to Evets ad Behavior Trackig 1-9

22 1 Overview of Evets ad Behavior Trackig PurchaseCartEvet Descriptio Geerator Example Class Elemets Products Occurs oce for a etire order, ulike the BuyEvet, which occurs for each lie item. This evet is useful for campaigs. You ca use it whe writig sceario actios to kow whe your customer makes a purchase with specific characteristics, such as a order greater tha $100 or the purchase of a particular product. Pipelie compoet. Located i PORTAL_HOME\applicatios\wlcsApp-project\applica tio-syc\pipelies. examples.wlcs.sampleapp.trackig.pipelie.purcha setrackerpc located i PORTAL_HOME\applicatios\wlcsApp\src sessio-id user-id evet-date evet-type total-price order-id currecy applicatio-ame WebLogic Portal oly Guide to Evets ad Behavior Trackig

23 Stadard Evets Buy Evet BuyEvet Oly oe buy evet exists. It is described i the followig table. Descriptio Geerator Example Class Elemets Products Occurs whe a customer completes the purchase. A BuyEvet occurs for each lie item. A purchase may cosist of oe or more lie items. A lie item may cosist of oe or more items. For example, although a particular lie item may have quatity of four items, oly oe BuyEvet occurs. Pipelie compoet examples.wlcs.sampleapp.trackig.pipelie.purcha setrackerpc located i PORTAL_HOME\applicatios\wlcsApp\src evet-date evet-type sessio-id user-id sku quatity uit-price currecy applicatio-ame order-lie-id WebLogic Portal oly. Rules Evet Oly oe rule evet exists. It is described i the followig table. Guide to Evets ad Behavior Trackig 1-11

24 1 Overview of Evets ad Behavior Trackig RuleEvet Descriptio Geerator Elemets Products Idicates the rules that were fired as a customer avigates a Web site. Fired iterally from advislets evet-date evet-type sessio-id user-id ruleset-ame rule-ame Specific to WebLogic Persoalizatio Server, available i WebLogic Portal. Campaig Evets These evets occur whe a customer participates i a campaig. CampaigUserActivityEvet Descriptio Geerator Elemets Occurs whe a customer participates i a campaig. Specifically, this evet is fired wheever oe or more sceario actios are true ad the campaig service is activated. You ca limit this evet to a sigle occurrece for a particular sceario. This evet is iteded for use by aalytic software. Fired iterally from the campaig service evet-date evet-type sessio-id user-id campaig-id sceario-id 1-12 Guide to Evets ad Behavior Trackig

25 Stadard Evets Products WebLogic Portal oly. DisplayCampaigEvet Descriptio Geerator Elemets Products Occurs whe campaig cotet, such as a ad, is preseted to the customer. Specifically, this evet is fired wheever a campaig placeholder displays a ad placed i the ad bucket by a campaig. You ca use this evet to trigger aother campaig. Aalytic software uses this evet to determie if a customer saw a ad as a result of a campaig. Fired iterally from the campaig service evet-date evet-type sessio-id user-id documet-type documet-id campaig-id sceario-id applicatio-ame placeholder-id WebLogic Portal oly. ClickCampaigEvet Descriptio Geerator Occurs whe a campaig item, such as a ad, is clicked o by the customer. Specifically, this evet is fired wheever a customer clicks a campaig ad that was placed i the ad bucket by a campaig. You ca use this evet to trigger aother campaig. Aalytic software uses this evet to determie if a customer clicked o a ad as a result of a campaig. Fired iterally from campaig service. Also see Servlet Lifecycle Evets ad Servlet Filter Evets o page Guide to Evets ad Behavior Trackig 1-13

26 1 Overview of Evets ad Behavior Trackig Elemets Products evet-date evet-type sessio-id user-id documet-type documet-id campaig-id sceario-id applicatio-ame placeholder-id WebLogic Portal oly. Servlet Lifecycle Evets ad Servlet Filter Evets The followig evets are geerated usig the Servlet 2.3 API: SessioBegiEvet SessioEdEvet These evets are defied as part of the Servlet 2.3 lifecycle evets. They are listeers o the sessio Created() ad sessio Destroyed() evets, which are geerated by the servlets defied i the web.xml file. This file is located at: PORTAL_HOME\applicatios\wlcsApp\wlcs\WEB-INF where PORTAL_HOME is the directory i which you istalled BEA WebLogic Portal or BEA WebLogic Persoalizatio Server. The followig evets are geerated by JSP tags ad filtered by the Servlet 2.3 <filter> elemet: ClickCotetEvet ClickProductEvet ClickCampaigEvet For each Web page displayed, the Web Applicatio servlet checks for the presece of a click evet i the HttpServletRequest. Each page click is the filtered by Web Applicatio servlet as defied by the Servlet 2.3 filter <elemet>. The click evets are geerated automatically whe the <filter> elemet is called o each ivocatio of 1-14 Guide to Evets ad Behavior Trackig

27 Evet Geerators the servlet. The ClickThroughFilter determies which type of evet is geerated by checkig the evet type i the HttpServletRequest. The valid types are defied at: PORTAL_HOME\classes\clickthrough-evet-types.properties where PORTAL_HOME is the directory i which you istalled BEA WebLogic Portal or BEA WebLogic Persoalizatio Server. Evet Geerators The stadard evets supplied by BEA are geerated at importat poits i a e-commerce site. The compoets that eable evets iclude Java APIs, JSP tags, JSP scriptlets, Webflow iput processors, Pipelie compoets, cotet selectors, ad classificatio advislets. You ca add or customize geerators for each of the followig evets: DisplayCotetEvet DisplayProductEvet ClickCotetEvet ClickProductEvet Note: DisplayProductEvet ad ClickCotetEvet are available i WebLogic Portal oly. Each of these evets are geerated by JSP tags. You ca use the JSP tags that iitiate these evets to specify which products ad what cotet geerates these evets. For example, i the wlcsapp E-Commerce Applicatio, the JSP tag for the DisplayProductEvet is located i the details.jsp. The tag show i Listig 1-1 geerates a evet for ay product displayed o a catalog detail page. If you wat to geerate a evet for oe particular product, you ca write a scriptlet that keys off the SKU for that product. Guide to Evets ad Behavior Trackig 1-15

28 1 Overview of Evets ad Behavior Trackig Listig 1-1 JSP Tag <%-- oce the product is displayed, fire off a displayproductevet --%> <producttrackig:displayproductevet documetid="<%= item.getname() %>" documettype="<%= DisplayProductEvet.ITEM_BROWSE %>" sku="<%= item.getkey().getidetifier() %>" /> Whe you add a JSP tag for a evet, you should iclude a referece to the tag library descriptor, as show below: <%@ taglib uri="producttrackig.tld" prefix="producttrackig" %> Notes: For more iformatio about JSP tags, see Chapter 4, JSP Tag Library Referece for Evets ad Behavior Trackig. The details.jsp is located at: PORTAL_HOME\cofig\wlcsDomai\wlcsApp\wlcs\commerce\catalog\det ails.jsp where PORTAL_HOME is the directory i which you istalled WebLogic Portal. Logi ad Creatio Evets This sectio discusses differet methods for geeratig logi ad user registratio evets. You ca geerate the SessioLogiEvet i either of the followig ways: If you are maually usig the <um:logi> tag or weblogic.servlet.security.servletautheticatio to hadle logi, use the com.bea.p13.trackig.trackigevethelper.dispatchsessiologieve t() method. If you are directly usig j_security_check FORM-based logi, register the com.bea.p13.servlets.p13nauthfilter as the <auth-filter> i your Web Applicatio s WEB-INF\weblogic.xml file. You do ot eed to code a JSP or Webflow Processor Guide to Evets ad Behavior Trackig

29 Evet Geerators Use the com.bea.p13.trackig.trackigevethelper.dispatchuserregistratio Evet() method to geerate the UserRegistratioEvet. You should geerate this evet after the SessioLogiEvet (which should occur durig user creatio). You ca use either a Iput Processor or i a JSP. If you are usig the Portal Webflow framework, the SessioLogiEvet ad the UserRegistratioEvet are geerated automatically from the com.bea.portal.appflow.processor.security.postlogiprocessor i the security webflow as eeded. Guide to Evets ad Behavior Trackig 1-17

30 1 Overview of Evets ad Behavior Trackig Evet Mechaism The Evet service is a extesible, geeral purpose, evet costructio ad propagatio system. As show i Figure 1-1, a evet is geerated by a trigger, such as a JSP tag, which creates the evet object, locates the Evet service bea, ad passes the evet object to the Evet service. The Evet service works with plug-i listeers that dissemiate evets to listeers iterested i receivig the evets. At creatio time, each evet listeer returs the list of evet types that it wats to receive. Whe the Evet service receives a evet, it checks the type of the evet ad seds the evet to all listeers that are subscribed to receive that evet s type. The Evet service has two sets of listeers: those that respod to evets sychroously ad those that respod to evets asychroously. The sychroous listeers use the thread of executio that created ad trasmitted the evet to perform actios i respose to that evet. Behavior Trackig listeers use oly the sychroous listeers. The asychroous listeers receive the evet from the thread where it was created ad some time later, hadles the evet i a differet thread of executio. The asychroous service exists so that log-ruig evet hadlers ca execute without delayig the applicatio from a Web site visitor s perspective. Whether a particular plug-i listeer is istalled o the sychroous or the asychroous side of the Evet service is based o the requiremets of the applicatio ad is specified i the applicatio-cofig.xml file. Note: To edit the applicatio-cofig.xml file, use the WebLogic Server Admiistratio cosole. For more iformatio, see Istallig a Listeer Class i the Evet Service o page Guide to Evets ad Behavior Trackig

31 Evet Mechaism Figure 1-1 Evet Mechaism Evet listeers implemet the com.bea.p13.evets.evetlisteer iterface. The iterface defies sigatures for two public methods: public Strig[] gettypes() Guide to Evets ad Behavior Trackig 1-19

32 1 Overview of Evets ad Behavior Trackig public void hadleevet( Evet theevet ) The first method returs a list of evet types that the listeer is iterested i receivig from the Evet service. For example, if a listeer is desiged to receive evets of type Foo, the listeer returs Foo as a item i the array retured from ivokig gettypes() o the listeer. The secod method is ivoked whe a evet is passed to the listeer. A listeer has o kowledge of whether it is sychroous or asychroous. If you wish to create a listeer iterested i oly campaig evets, you would list the listeer s fully-qualified classame i the applicatio-cofig.xml file i either the evetservice.listeers property or the asychrooushadler.listeers property (for sychroous or asychroous hadlig, respectively). The listeer would implemet the EvetListeer iterface ad retur the followig evet types: { ClickCampaigEvet, DisplayCampaigEvet, CampaigUserActiv ityevet } whe its gettypes() method is ivoked. Warig: For proper operatio, the WebLogic Server requires that chages to the applicatio-cofig.xml file be made usig the WebLogic Server Admiistratio Cosole. To edit the applicatio-cofig.xml file, use the WebLogic Server Admiistratio cosole. For more iformatio, see Istallig a Listeer Class i the Evet Service o page 2-8. After the listeer is istalled, evets of oe of these three types arrive through the listeer s hadleevet( Evet theevet ) iterface. The Asychroous Delivery graphic i Figure 1-1 idicates that the asychroous evet hadler receives evets trasmitted asychroously from the sychroous side of the Evet service. It the dispatches evets to the pluggable asychroous listeers based o the evet types each listeer is subscribed to receive. Evet Sequece Figure 1-2 ad Figure 1-3 provide a sample of the firig of evets. These figures are iteded to give you a sese of the order i which evets fire, ot a comprehesive examiatio of evet sequecig Guide to Evets ad Behavior Trackig

33 Evet Sequece Figure 1-2 Evet Sequece Sample Part 1 Guide to Evets ad Behavior Trackig 1-21

34 1 Overview of Evets ad Behavior Trackig Figure 1-3 Evet Seqeuece Sample Part Guide to Evets ad Behavior Trackig

35 2 Creatig Custom Evets This topic provides the iformatio ecessary to write a custom evet. You ca create a custom evet for aythig you wish to track. For example, you could create a evet that would tell you which pages are displayed for each customer. You could the use the iformatio to determie how may pages are viewed o average per sessio ad which pages are the most popular. Additioally, marketig professioals could use this evet whe developig sceario actios that are based o the display of particular pages. To demostrate how to write a custom evet, a simple example is provided. Each sectio refereces ad expads the example. This topic icludes the followig sectios: Overview of Creatig a Custom Evet Writig a Custom Evet Class Writig a Custom Evet Listeer Writig a Behavior Trackig Evet Class Debuggig the Evet Service To register a custom evet, use the Evet Editor i the E-Busiess Cotrol Ceter. Registerig a evet is actually creatig a property set for the evet. A step-by-step procedure is available i both the E-Busiess Cotrol Ceter olie help ad Creatig ad Maagig Property Sets i the Guide to Buildig Persoalized Applicatios. Guide to Evets ad Behavior Trackig 2-1

36 2 Creatig Custom Evets Overview of Creatig a Custom Evet The creatio of a custom evet is a multiple-step process. The followig list provides a overview of the process ad refereces the iformatio ot covered i this topic: Write the code that defies the evet ad evet listeer. Istall the evet usig the WebLogic Server Admiistratio cosole. For more iformatio, see Istallig a Listeer Class i the Evet Service o page 2-8. Write the code to geerate the evet with a JSP tag or a API call. Register the evet. For more iformatio, see Registerig a Custom Evet o page To record the evet data to the EVENT table, create a etry for the evet i the EVENT_TYPE table. For more iformatio, see Chapter 3, Persistig Behavioral Trackig Data. Writig a Custom Evet Class To create a custom evet, you first write a evet object. This object ecapsulates all the ecessary iformatio for correctly iterpretig ad hadlig the evet whe it arrives at a listeer. All custom evets must subclass the com.bea.p13.evets.evet class. This base class hadles settig ad retrievig a evet s timestamp ad type ad provided access to the custom evet s attributes. Two Evet class methods set ad retrieve attributes: setattribute( Strig thekey, Serializable thevalue ) getattribute( Strig thekey ) These methods ca be called from the custom evet s costructor to set attributes specific to the ew evet. Keep i mid that all objects set as values i the Evet object must be Java serializable. The gettimestamp() method returs the date of the evet s creatio i millisecods. The type of a evet is accessed usig the Evet class s gettype() method. The timestamp ad type of a Evet object istace ca be set oly at creatio time i the Evet costructor. 2-2 Guide to Evets ad Behavior Trackig

37 Writig a Custom Evet Class To illustrate the process of creatig a custom evet, a simple example is preseted here, called TestEvet. The example is a basic demostratio of how to create a evet subclass. A actual custom evet would probably be more elaborate. A custom evet must first have a type. This type should be passed to the superclass costructor (for example, i the Evet class); this type is retured at gettype() ivocatios o custom-evet object istaces. For example: /** Evet Type */ public static fial Strig TYPE = "TestEvet"; To properly iitialize the Evet base class of the custom evet object, the value TYPE is passed to the evet costructor. The type of all evets must be a simple Java strig object. After defiig the type, you must defie the keys that access the attributes stored i the custom evet. These attributes ca be give values i the costructor. For example, the TestEvet class has two properties, userpropertyoe ad userpropertytwo; the type of the value associated with userpropertyoe is a Strig ad userpropertytwo is a Double. The keys are defied as follows: /** * Evet attribute key ame for the first user defied property * Attribute value is a Strig */ public static fial Strig USER_PROPERTY_ONE_KEY = "userpropertyoe"; /** * Evet attribute key ame for the secod user defied property * Attribute value is a Double */ public static fial Strig USER_PROPERTY_TWO_KEY = "userpropertytwo"; Fially, a costructor brigs the evet type ad the process of settig attributes together to create a evet object. The costructor looks like: /** * Create a ew TestEvet * * userpropertyoe some user defied property typed as * a Strig userpropertytwo some user defied property typed as * a Double */ public TestEvet( Strig userpropertyoevalue, Guide to Evets ad Behavior Trackig 2-3

38 2 Creatig Custom Evets { Double userpropertytwovalue ) /* calls the Evet class costructor with this evet s type */ super( TYPE ); if( userpropertyoevalue!= ull ) setattribute( USER_PROPERTY_ONE_KEY, userpropertyoevalue ); } if( userpropertytwovalue!= ull ) setattribute( USER_PROPERTY_TWO_KEY, userpropertytwovalue ); Puttig all the parts together, the etire custom evet class is show i Listig 2-1. Listig 2-1 TestEvet Class /* Start TestEvet class */ public class TestEvet exteds com.bea.p13.evets.evet { /** Evet Type */ public static fial Strig TYPE = "TestEvet"; /** * Evet attribute key ame for the first user defied property * Attribute value is a Strig */ public static fial Strig USER_PROPERTY_ONE_KEY = "userpropertyoe"; /** * Evet attribute key ame for the secod user defied property * Attribute value is a Double */ public static fial Strig USER_PROPERTY_TWO_KEY = "userpropertytwo"; /** * Crate a ew TestEvet * * userpropertyoe some user defied property typed as a Strig userpropertytwo some user defied property typed as a Double */ public TestEvet( Strig userpropertyoevalue, Double userpropertytwovalue ) 2-4 Guide to Evets ad Behavior Trackig

39 Writig a Custom Evet Listeer { /* calls the Evet class costructor with this evet s type */ super( TYPE ); if( userpropertyoevalue!= ull ) setattribute( USER_PROPERTY_ONE_KEY, userpropertyoevalue ); if( userpropertytwovalue!= ull ) setattribute( USER_PROPERTY_TWO_KEY, userpropertytwovalue ); } } /* Ed TestEvet class */ The example i Listig 2-1 shows you how to use the fudametal aspects of the Evet base class ad the evet service. A actual custom evet costructor would probably be more complex. For example, it might check for default values or disallow ull attributes. Additioally, the custom-evet object might have more methods or member data. Writig a Custom Evet Listeer I order to liste for a evet, you must defie a evet listeer. All evet listeers must implemet the com.bea.p13.evets.evetlisteer iterface ad have a o argumets (default) costructor. This iterface specifies two methods that are fudametal to trasmittig evets of a give type to iterested listeers: public Strig[] gettypes() public void hadleevet( Evet ev ) The first method returs the types, i a strig array, that the listeer is iterested i receivig. The evet service dispatches evets of a give type to listeers that retur the evet s type i the types array. Whe the evet service has determied that a give listeer has registered to receive the type of the curret evet, a evet of that type is dispatched to the listeer usig the hadleevet( Evet ev ) call. Guide to Evets ad Behavior Trackig 2-5

40 2 Creatig Custom Evets Whe writig a custom evet listeer, both methods must be implemeted from the EvetListeer iterface. Cotiuig with the TestEvet example, the TestEvetListeer listes for istaces of TestEvet that are set through the evet service. This ca be specified as follows: /** The types this listeer is iterested i */ private Strig[] evettypes = {"TestEvet"}; /** The method ivoked by the evet service to determie the types to propagate to this listeer. */ public Strig[] gettypes() { retur evettypes; } To hadle the evet, the hadleevet( Evet evt ) method is implemeted as follows: /** * Hadle evets that are set from the evet service */ public void hadleevet( Evet ev ) { System.out.pritl("TestListeer::hadleEvet " + " -> received a evet" + " of type: " + ev.gettype() ); /* Do the work here */ } retur; Puttig all of these pieces together with a costructor, Listig 2-2 shows a simple evet listeer that registers to receive TestEvet objects. Listig 2-2 Evet Listeer import com.bea.p13.evets.evetlisteer; import com.bea.p13.evets.evet; /** * TestListeer to demostrate the ease with which listeers ca be plugged * ito the behavior trackig system. * 2-6 Guide to Evets ad Behavior Trackig

41 Writig a Custom Evet Listeer * This class should be added to the property evetservice.listeers * i order to receive evets. The fully qualified classame must be added * to this property; do t forget to add the ",\" at the ed of the previous * lie or the properties parser will ot fid the ew classame. * * The types of evets that are heard are listed i the evettypes * Strig array. Add ad remove strigs of that type as ecessary. * Copyright (c) 2001 by BEA Systems, Ic. All Rights Reserved. */ public class TestListeer implemets EvetListeer { private Strig[] evettypes = {"TestEvet"}; public TestListeer() { } public Strig[] gettypes() { retur evettypes; } public void hadleevet( Evet ev ) { System.out.pritl("TestListeer::hadleEvet -> received a evet" + " of type: " + ev.gettype() ); } } retur; As with writig a simple evet, writig a simple EvetListeer is also straightforward. Ay evet listeer s iterals should be geeric; the same TestEvetListeer istace may ot hadle all TestEvet objects. Therefore TestEvetListeer should be etirely stateless ad should operate o data that is cotaied i the evet object or stored exterally (that is, i a database). Note: Multiple istaces of ay listeer may execute cocurretly. Guide to Evets ad Behavior Trackig 2-7

42 2 Creatig Custom Evets Istallig a Listeer Class i the Evet Service To add or remove listeers to the evet service, use the WebLogic Server Admiistratio Cosole. To eable Behavior Trackig, you must add Behavior Trackig as a listeer. Warig: For proper operatio, the WebLogic Server requires that chages to the applicatio-cofig.xml file be made usig the WebLogic Server Admiistratio Cosole. Note: For more iformatio o usig the WebLogic Server Admiistratio Cosole, see the WebLogic Server Documetatio Ceter. To add a sychroous or asychroous listeer, take the followig steps: Note: Behavior Trackig listeers ca oly be implemeted as sychroous listeers. 1. I the WebLogic Server Cosole, avigate to Sychroous or Asychroous Listeers tab i the ode tree for wlcsdomai as follows: wlcsdomai Deploymets wlcsapp Service Cofiguratios Evet Service Cofiguratio Tab Sychroous Listeers or Asychroous Listeers 2. Add the sychroous or asychroous listeer to the correspodig fields, as show i Figure 2-2. Figure 2-1 WebLogic Server Admiistratio Cosole Evet Service 2-8 Guide to Evets ad Behavior Trackig

43 Writig a Behavior Trackig Evet Class Writig a Behavior Trackig Evet Class A Behavior Trackig evet is a special type of evet that tracks a customer s iteractios with a e-commerce site. E-aalysis systems use the data gathered from Behavior Trackig evets to evaluate customer behavior. The evaluatio is primarily used for campaig developmet ad optimizig customer experiece o a Web site. A Behavior Trackig evet ad its listeers are created i much the same way as the TestEvet class ad TestEvetListeer examples. A simple example is also preseted here. The example trackig evet is called TestTrackigEvet. All Behavior Trackig evets persisted (recorded) to a database for use with BEA Behavior Trackig are hadled by the com.bea.p13.trackig.listeers.behaviortrackiglisteer. The BehaviorTrackigListeer exteds the com.bea.p13.evets.evetlisteer class. The BehaviorTrackigListeer receives ad persists Behavior Trackig evets from the evet service whe it is plugged ito oe of the listeer s properties i the applicatio-cofig.xml file. Notes: For scalability reasos, you should plug the BehaviorTrackigListeer ito the evetservice.listeers property. This listeer receives evets from the evet service ad adds them to a buffer that is itermittetly persisted to the Evet tables i the database. The frequecy of the sweepig of evets from the buffer is cotrolled by the followig properties i the applicatio-cofig.xml file: MaxBufferSize Sets the maximum size of the evet buffer. Settig this to 0 meas all evets are persisted as they are received. SweepIterval Sets the iterval, i secods, at which to check the buffers to see whether evets i the buffer must be persisted. Evets are persisted whe either the maximum buffer size (MaxBufferSize) is reached or the maximum time to wait i the buffer (SweepMaxTime) has bee exceeded. SweepMaxTime Set the time, i secods, to wait before forcig a flush to the database. This is the logest amout of time that a evet ca exist i ay cache. Guide to Evets ad Behavior Trackig 2-9

44 2 Creatig Custom Evets You should tue these properties to optimize performace. A buffer sweep should be performed ofte eough that writig to the database is ot too time cosumig but ot so frequet that the operatio is wasteful. Cofigurig Evets Buffer Sweepig Warig: For proper operatio, the WebLogic Server requires that chages to the applicatio-cofig.xml file be made usig the WebLogic Server Admiistratio Cosole. Note: For more iformatio o usig the WebLogic Server Admiistratio Cosole, see the WebLogic Server Documetatio Ceter. To cofigure the sweepig of the evets buffer, take the followig steps: 1. I the WebLogic Server Cosole, avigate to Behavior Trackig i the ode tree for wlcsdomai as follows: wlcsdomai Deploymets wlcsapp Service Cofiguratios Behavior Trackig 2. Eter the ew buffer values i the appropriate fields, as show i Figure 2-2. Figure 2-2 WebLogic Server Admiistratio Cosole Behavior Trackig 2-10 Guide to Evets ad Behavior Trackig

45 Writig a Behavior Trackig Evet Class Facilitatig OffLie Processig For facilitatig offlie processig of customer iteractios with a Web site, Behavior Trackig evets are desiged to be persisted to a table i the database, called the EVENT table. Part of the process of recordig data from Behavior Trackig evets is creatig a XML represetatio of the data, which is stored i the xml_defiitio colum of the EVENT table. You ca persist evets i a alterate locatio ad table structure as requiremets dictate. This discussio assumes that you are plaig to use the BEA Behavior Trackig evet persistece mechaism. Therefore, to persist evets i the provided EVENT table, your custom evet must coform to the descriptios i this sectio so that it is created ad persisted properly. To formally specify the data comprisig a Behavior Trackig evet, you eed to develop a XML-XSD schema for the ew evet. While XSDs are ot used iterally to verify the creatio of XML, the XML that is created represets the evet s data i the database. If the evet class is properly developed ad used, it will coform to the XML-XSD schema. With a XSD documet, developmet of the costructor ad attribute keys for a Behavior Trackig evet follows easily. To correctly tur a Behavior Trackig evet ito a XML represetatio, the Behavior Trackig evet must have several pieces of member data that fully describe a XML istace documet for the schema associated with the evet type. This data describes the amespace ad XSD file associated with the evet. For example, Listig 2-3 ad Listig 2-4 show the associatio betwee the followig files: com.bea.campaig.trackig.evets.clickcampaigevet ad /lib/schema/clickcampaigevet.xsd i PORTAL_HOME\lib\campaig\ejb\campaig.jar. For more examples, look at the existig XSD files. Listig 2-3 ClickCampaigEvet.java /** Evet for trackig click of campaig */ public class ClickCampaigEvet exteds ClickEvet { /** The evet type */ public static fial Strig TYPE = "ClickCampaigEvet"; Guide to Evets ad Behavior Trackig 2-11

46 2 Creatig Custom Evets /** The XML amespace for this evet */ private static fial Strig XML_NAMESPACE = " /** The XSD file cotaiig the schema for this evet */ private static fial Strig XSD_FILE = "ClickCampaigEvet.xsd"; /** * Evet attribute key ame for the campaig id * Attribute value is a Strig */ public static fial Strig CAMPAIGN_ID = "campaig-id"; /** * Evet attribute key ame for the sceario id * Attribute value is a Strig */ public static fial Strig SCENARIO_ID = "sceario-id"; /** * Evet attribute key ame for storefrot (aka applicatio) * Attribute value is a Strig */ public static fial Strig APPLICATION_NAME = "applicatio-ame"; /** * Evet attribute key ame for item category id * Attribute value is a Strig */ public static fial Strig PLACEHOLDER_ID = "placeholder-id"; /** Suggestios for etry ito the documettype data passed to the costructor Attribute value is a Strig */ public static fial Strig BANNER_AD_PROMOTION = "baeradpromotio"; /** These are the keys ad their order for elemets that will be preset i the XML represetig this object */ private static fial Strig localschemakeys[] = { SESSION_ID, USER_ID, DOCUMENT_TYPE, DOCUMENT_ID, 2-12 Guide to Evets ad Behavior Trackig

47 Writig a Behavior Trackig Evet Class }; CAMPAIGN_ID, SCENARIO_ID, APPLICATION_NAME, PLACEHOLDER_ID /** * Create a ew ClickCampaigEvet. * thesessioid from HttpSessio.getId() theuserid from HttpServletRequest.getRemoteUser() or * equivalet (ull if ukow) therequest the http servlet request object adocumettype Documet Type for the clicked cotet (optioally * ull) adocumetid Documet ID for the clicked cotet (optioally ull) acampaigid campaig id for the campaig from which the item was * clicked ascearioid sceario id for the sceario (withi the campaig) * for which the item was clicked aapplicationame applicatio ame (aka storefrot) (optioally * ull) aplaceholderid a placeholder id */ public ClickCampaigEvet( Strig thesessioid, Strig theuserid, HttpServletRequest therequest, Strig adocumettype, Strig adocumetid, Strig acampaigid, Strig ascearioid, Strig aapplicationame, Strig aplaceholderid ) { super( TYPE, thesessioid, theuserid, XML_NAMESPACE, XSD_FILE, localschemakeys, therequest, adocumettype, adocumetid); } if( acampaigid!= ull ) setattribute( CAMPAIGN_ID, acampaigid ); if( ascearioid!= ull ) setattribute( SCENARIO_ID, ascearioid ); if( aapplicationame!= ull ) setattribute( APPLICATION_NAME, aapplicationame ); if( aplaceholderid!= ull ) setattribute( PLACEHOLDER_ID, aplaceholderid ); Guide to Evets ad Behavior Trackig 2-13

48 2 Creatig Custom Evets } Notice the cross-referece betwee ClickCampaigEvet ad the XSD schema. Listig 2-4 Correspodig XSD Schema <xsd:schema targetnamespace=" /clickcampaig" xmls=" aig" xmls:xsd=" xmls:xsi=" xsi:schemalocatio=" elemetformdefault="qualified" attributeformdefault="uqualified" versio="2.1">... The source code for your Behavior Trackig evet should also list the keys ad their order for creatig a XML istace documet from a evet object. For a example, see Listig 2-3. The structure of a XSD documet ad details o XML amespaces ca be foud at Several XSD schemas for BEA Behavior Trackig evets ca be foud i /lib/schema at the followig locatio: PORTAL_HOME\lib\p13\ejb\evets.jar where PORTAL_HOME is the directory i which you istalled BEA WebLogic Portal or BEA WebLogic Persoalizatio Server. The amespace ad schema are specified as: /** The XML amespace for this evet */ private static fial Strig XML_NAMESPACE= " URI>/testtrackig"; 2-14 Guide to Evets ad Behavior Trackig

49 Writig a Behavior Trackig Evet Class /** The XSD file cotaiig the schema for this evet */ private static fial Strig XSD_FILE="TestTrackigEvet.xsd"; Note: These values are used whe creatig a istace documet to populate the fields. The schemakeys are a list of strigs which are keys to the evet class s getattribute ad setattribute methods. These keys are used to extract the data that populate elemets i the XML istace documet which represet the Behavior Trackig evet. The keys should be listed i a array that cosists of strig-typed objects. Their order specifies the order i which they appear i the XML istace documet. I the XSD files that the Behavior Trackig system geerates, the order of the elemets is importat; a XML file will ot validate with a XSD file if elemets are out of order. Elemets ca be omitted by usig the XML umoccurs keyword ad settig the value to zero. For examples of how this is doe, see the XSD schemas for BEA Behavior Trackig evets i /lib/schema, at the followig locatio: PORTAL_HOME\lib\p13\ejb\evets.jar A example array for the Behavior Trackig versio of the TestEvet described above might appear as: /** These are the keys ad their order for elemets that will be preset i the XML represetig this object. */ private static fial Strig localschemakeys[] = { SESSION_ID, USER_ID, USER_PROPERTY_ONE_KEY, USER_PROPERTY_TWO_KEY }; The SESSION_ID ad the USER_ID are data elemets i the localschemakeys array that are useful i implemetig a trackig evet. The SESSION_ID is the WebLogic Server sessio ID that is created for every sessio object. (For more iformatio, see the WebLogic Server 6.0 Documetatio Ceter.) The USER_ID field (which may be ull) is the userame of the Web site customer associated with the sessio from which the evet was geerated. For some evets, a user may ot be associated with a evet; as previously metioed, the umoccurs for the USER_ID field i a XSD file should be zero. To persist evets i the EVENT table, the SESSION_ID must be o-ull. Guide to Evets ad Behavior Trackig 2-15

50 2 Creatig Custom Evets All Behavior Trackig evets must exted the com.bea.p13.trackig.evets.trackigevet class. This class defies three keys that are useful for settig attributes for all trackig evets, as follows: TrackigEvet.SESSION_ID TrackigEvet.USER_ID TrackigEvet.REQUEST. These keys are used i setattribute calls made i the TrackigEvet costructor whe settig the SESSION_ID, USER_ID, ad REQUEST (a HttPServletRequest object), respectively. They should also be used to retrieve values associated with each key whe ivokig Evet.getAttribute (Strig Key) o evet objects that exted TrackigEvet. TrackigEvet Base Class Costructor The TrackigEvet base class has a costructor that is more complicated tha the Evet class s costructor. The Evet costructor is ivoked by the super( Strig evettype ) call i the TrackigEvet costructor. The TrackigEvet costructors are show i Listig 2-5 ad Listig 2-6. Listig 2-5 Trackig Evet Costructor Example 1 /** * Create a ew TrackigEvet. * theevettype the evet s type thesessioid from HttpSessio.getId() theuserid from HttpServletRequest.getRemoteUser() or equivalet * (ull if ukow) thexmlnamespace the amespace for a XML represetatio of this evet * type thexsdfile the file that cotais the schema which specifies ad * eforces typig o the data i the XML file theschemakeys the list of keys (i their order i the XSD schema) * represetig the data to be persisted i this evet s XML */ public TrackigEvet( Strig theevettype, Strig thesessioid, Strig theuserid, 2-16 Guide to Evets ad Behavior Trackig

51 Writig a Behavior Trackig Evet Class Strig thexmlnamespace, Strig thexsdfile, Strig[] theschemakeys ) The TrackigEvet costructor show i Listig 2-6 takes a HttpServletRequest object. Listig 2-6 Trackig Evet Costructor Example 2 /** * Create a ew TrackigEvet. * theevettype the evet s type thesessioid from HttpSessio.getId() theuserid from HttpServletRequest.getRemoteUser() or equivalet * (ull if ukow) thexmlnamespace the amespace for a XML represetatio of this evet * type thexsdfile the file that cotais the schema which specifies ad * eforces typig o the data i the XML file theschemakeys the list of keys (i their order i the XSD schema) * represetig the data to be persisted i this evet s XML therequest the http servlet request object */ public TrackigEvet( Strig theevettype, Strig thesessioid, Strig theuserid, Strig thexmlnamespace, Strig thexsdfile, Strig[] theschemakeys, HttpServletRequest therequest ) I the first costructor, show i Listig 2-5, the oly data that is optioal (that is, that ca be ull) is theuerid; all other data is required so that the trackig evet is correctly persisted to the EVENT table. I the secod costructor, show i Listig 2-6, the HttpServletRequest object ca be passed i from geeratig locatios where the HttpServletRequest object is available. This object provides the data eeded to fire rules agaist evet istaces. Guide to Evets ad Behavior Trackig 2-17

52 2 Creatig Custom Evets Note: I order to fire rules o a custom Behavior Trackig evet, the HttpServletRequest ad the USER_ID must be o-ull. Geerally, a o-ull USER_ID meas that a customer is logged ito a Web site. Rules caot be fired o a evet with a ull-user. The TestTrackigEvet costructor is show i Listig 2-7. Listig 2-7 TestTrackigEvet Costructor /** * Create a ew TestTrackigEvet * thesessioid from HttpSessio.getId() theuserid from HttpServletRequest.getRemoteUser() or equivalet * (ull if ukow) userpropertyoe some user defied property typed as a Strig userpropertytwo aother user defied property typed as a Double */ public TestTrackigEvet( Strig thesessioid, Strig theuserid, Strig userpropertyoevalue, Double userpropertytwovalue ) { super( TYPE, thesessioid, theuserid, XML_NAMESPACE, XSD_FILE, localschemakeys ); } if( userpropertyoevalue!= ull ) setattribute( USER_PROPERTY_ONE_KEY, userpropertyoevalue ); if( userpropertytwovalue!= ull ) setattribute( USER_PROPERTY_TWO_KEY, userpropertytwovalue ); This costructor calls the TrackigEvet costructor to populate the required values ad the sets the attributes ecessary for this particular Behavior Trackig evet type. The etire TestTrackigEvet is show i Listig Guide to Evets ad Behavior Trackig

53 Writig a Behavior Trackig Evet Class Listig 2-8 TestTrackig Evet import com.bea.p13.trackig.evets.trackigevet; /** * Test, user-defied behavior trackig evet. * * This evet ca be persisted to the database. * */ public class TestTrackigEvet exteds TrackigEvet { /** Evet type */ public static fial Strig TYPE = "TestTrackigEvet"; /** The XML amespace for this evet */ private static fial Strig XML_NAMESPACE=" URI>/testtrackig"; /** The XSD file cotaiig the schema for this evet */ private static fial Strig XSD_FILE="TestTrackigEvet.xsd"; /** * Evet attribute key ame for the first user defied property * Attribute value is a Strig */ public static fial Strig USER_PROPERTY_ONE_KEY = "userpropertyoe"; /** * Evet attribute key ame for the secod user defied property * Attribute value is a Double */ public static fial Strig USER_PROPERTY_TWO_KEY = "userpropertytwo"; /** These are the keys ad their order for elemets that will be preset i the XML represetig ths object. */ private static fial Strig localschemakeys[] = { SESSION_ID, USER_ID, USER_PROPERTY_ONE_KEY, USER_PROPERTY_TWO_KEY }; Guide to Evets ad Behavior Trackig 2-19

54 2 Creatig Custom Evets /** * Create a ew TestTrackigEvet * thesessioid from HttpSessio.getId() theuserid from HttpServletRequest.getRemoteUser() or equivalet * (ull if ukow) userpropertyoe some user defied property typed as a Strig userpropertytwo aother user defied property typed as a Double */ public TestTrackigEvet( Strig thesessioid, Strig theuserid, Strig userpropertyoevalue, Double userpropertytwovalue ) { super( TYPE, thesessioid, theuserid, XML_NAMESPACE, XSD_FILE, localschemakeys ); if( userpropertyoevalue!= ull ) setattribute( USER_PROPERTY_ONE_KEY, userpropertyoevalue ); } } if( userpropertytwovalue!= ull ) setattribute( USER_PROPERTY_TWO_KEY, userpropertytwovalue ); The TestTrackigEvet, show i Listig 2-8, correctly sets its ow attributes ad sets the attributes i its istatiatio of TrackigEvet. This eables correct populatio of the XML istace documet at the time of its creatio. Recall that the XML istace documet represets the TestTrackigEvet i the database s EVENT table. If you wat the custom Behavior Trackig evet type to be persisted i the database, the evet must be added to the behaviortrackig.persisttodatabase property i the applicatio-cofig.xml file. If you are ot persistig the evet, you do ot eed to add the evet type to this property. Istallig Behavior Trackig Evets Warig: For proper operatio, the WebLogic Server requires that chages to the applicatio-cofig.xml file be made usig the WebLogic Server Admiistratio Cosole Guide to Evets ad Behavior Trackig

55 Writig a Behavior Trackig Evet Class Note: For more iformatio o usig the WebLogic Server Admiistratio Cosole, see the WebLogic Server Documetatio Ceter. To istall a Behavior Trackig Evet listeer, take the followig steps: 1. I the WebLogic Server Cosole, avigate to Behavior Trackig i the ode tree for wlcsdomai as follows: wlcsdomai Deploymets wlcsapp Service Cofiguratios Behavior Trackig 2. Eter the ame of the evet i the Persisted Evet Types field, as show i Figure 2-3. Figure 2-3 WebLogic Server Admiistratio Cosole Behavior Trackig XML Creatio of Behavior Trackig Evets Whe persistig Behavior Trackig evets to the EVENT table, the bulk of the data must be coverted to XML. The XML documet should coform to a XML XSD schema that you create which specifies the order of the XML elemets i the XML istace documet. Additioally, the schema must iclude the types of elemets ad their cardialities. The process of creatig XML from a evet object is hadled by a helper class that utilizes variables ad costats i a Behavior Trackig evet s class file. All schema documets use the amespace: ad all istaces of Behavior Trackig schemas use the amespace: The XML created i Listig 2-9 will coform to the XSD schema. Guide to Evets ad Behavior Trackig 2-21

56 2 Creatig Custom Evets Listig 2-9 XSD Documet Example <schema targetnamespace=" xmls:bt=" xmls=" <elemet ame="buyevet"> <complextype> <sequece> <elemet ref="bt:evet_date"/> <elemet ref="bt:evet_type"/> <elemet ref="bt:sessio_id"/> <elemet ref="bt:user_id" mioccurs="0"/> <elemet ref="bt:sku"/> <elemet ref="bt:quatity"/> <elemet ref="bt:uit_price"/> <elemet ref="bt:currecy" mioccurs="0"/> <elemet ref="bt:applicatio_ame" mioccurs="0"/> <elemet ref="bt:order_lie_id"/> </sequece> </complextype> </elemet> <elemet ame="evet_date" type="timeistat"/> <elemet ame="evet_type" type="strig"/> <elemet ame="sessio_id" type="strig"/> <elemet ame="user_id" type="strig"/> <elemet ame="sku" type="strig"/> <elemet ame="quatity" type="double"/> <elemet ame="uit_price" type="double"/> <elemet ame="currecy" type="strig"/> <elemet ame="applicatio_ame" type="strig"/> <elemet ame="order_lie_id" type="log"/> </schema> Creatio of a evet s represetatio i XML takes place geerically relative to the evet s type. Cosequetly, to create a accurate XML istace documet, each evet must specify the amespace, evet type, elemets, ad order of its elemets. Usig the TestTrackigEvet example, the XML represetig a istace of the TestTrackigEvet is costructed as follows: Note: Assume that testtrackigevet is a well-formed istace of a TestTrackigEvet. 1. Get the evet s type with the testtrackigevet.gettype() call Guide to Evets ad Behavior Trackig

57 Writig a Behavior Trackig Evet Class 2. Get the evet s amespace with the ((TrackigEvet)testTrackigEvet).getXMLNamespace()call. 3. Get the evet s XSD fileame with the ((TrackigEvet)testTrackigEvet).getXSDFile() call. Usig the schema keys from the TestTrackigEvet class, values are iserted ito the XML documet. Schema key/attribute value pairs correspod to XML elemets i this way: <schema Key>value</schema Key> The helper class that creates XML for Behavior Trackig assumes that the elemets iserted ito a XML istace documet are ot deeply ested. Additioally, the tostrig() method is used to create a represetatio of the value object that is retrieved through the Evet classes s getattribute( Strig Key ) call. The cotets of the strig retured by ivokig tostrig() o the value object must match the type specified i the evet s schema documet. The TestTrackigEvet retrieves values usig the followig keys i the order specified i the schemakeys array: SESSION_ID USER_ID USER_PROPERTY_ONE_KEY USER_PROPERTY_TWO_KEY The values for these keys are retrieved usig the testtrackigevet.getattribute( <schema Key> ) call. The order i which the XML formatted key/value pairs are iserted ito the istace documet is specified by the costat schemakeys array, which is defied ad populated i the TestTrackigEvet class. The steps assembled to create a XML istace documet for the TestTrackigEvet are preseted i Listig Listig 2-10 XML Istace Documet Example <TestTrackigEvet xmls=" URI>/testtrackig" xmls:xsi=" xsi:schemalocatio=" URI>/testtrackig TestTrackigEvet.xsd" Guide to Evets ad Behavior Trackig 2-23

58 2 Creatig Custom Evets > <evet_date>xml time istat formatted evet date</evet_date> <evet_type>testtrackigevet</evet_type> <sessio_id>thesessioidvalue</sessio_id> <user_id>theuseridvalue</user_id> <userpropertyoe>userpropertyoevalue</userpropertyoe> <userpropertytwo>userpropertytwovalue</userpropertytwo> </TestTrackigEvet> The XML creatio is performed automatically whe evets arrive at the com.bea.p13.trackig.listeers.behaviortrackiglisteer, which eables Behavior Trackig i WebLogic Portal or WebLogic Persoalizatio Server. The Behavior Trackig listeer is istalled by addig it to the <EvetService Listeers="..."> property i the applicatio-cofig.xml file. For iformatio o how to istall a Behavior Trackig listeer, see Istallig Behavior Trackig Evets o page You must be careful whe defiig the amespaces, XSD documets, ad schema keys variables i custom Behavior Trackig evet classes, especially if they will be persisted to the EVENT table. The method for creatig ad storig XML preseted i this discussio exactly follows the variables ad costats specified i the evet class. You are free to develop other ways of creatig ad storig XML; this sectio is directed oly at the process of persistig XML Behavior Trackig represetatios i the BEA EVENT table. Note: The Evet's date is retrieved usig the Evet class's gettimestamp() call, which returs a Java primitive log typed value. That log must be coverted ito the type specified for the evet_date elemet i the XSD schema documet. The type i this case is time istat. Evet date ad evet type the first two elemets i all XML istace documets created through the BehaviorTrackigListeer. Custom Behavior Trackig Evet Listeers To create a custom Behavior Trackig listeer, i additio to or istead of the default BehaviorTrackigListeer, follow the example preseted i Writig a Custom Evet Listeer o page 2-5. Add the ew evet types to the custom listeer s evettypes array (for example, TestTrackigEvet). A give listeer ca liste 2-24 Guide to Evets ad Behavior Trackig

59 Writig a Behavior Trackig Evet Class for ay umber of evet types that may or may ot be Behavior Trackig evets. The custom Behavior Trackig listeer ca be istalled o either the sychroous or asychroous side of the evet service, whichever is appropriate. Writig Custom Evet Geerators Oce evets are created, you must set up a mechaism for geeratig evets i the applicatio. Evets may be geerated from pipelie compoets, iput processors, JSP scriptlets, or JSP tags. Some Behavior Trackig evets are geerated from withi WebLogic Portal or WebLogic Persoalizatio Server software. After determiig the mechaism for geeratig evets, trackig evets ca be set to the evet system usig the com.bea.p13.trackig.trackigevethelper class. This class defies helper methods that pass evets to the evet service. Listig 2-11 shows a example of passig the TestTrackigEvet. Listig 2-11 Dispatchig a Evet /* * Create the evet */ Evet theevet = ew TestTrackigEvet( "<some sessio id>", "<some user id> ", ew Strig("userPropertyOeValue"), ew Double( 3.14 ) ); /* * Dispatch the evet */ TrackigEvetHelper.dispatchEvet( theevet ); To dispatch a TestEvet to the evet service, the evet service ame ca be looked up i the JNDI, ad a istace of the EvetService bea ca be obtaied by ivokig the create() method o a EvetServiceHome istace. The JNDI ame of the EvetServiceHome iterface is the classame of the EvetServiceHome class (com.bea.p13.evets.evetservicehome). Listig 2-12 shows a example. Guide to Evets ad Behavior Trackig 2-25

60 2 Creatig Custom Evets Listig 2-12 JNDI Example import com.bea.p13.util.helper.jndihelper; import com.bea.p13.evets.evet; import com.bea.p13.evets.evetservicehome; import com.bea.p13.evets.evetservice; import javax.ejb.createexceptio; import javax.rmi.portableremoteobject; /* code here */ public void demostrateevetdispatch() { Evet evet = <some evet istace>; try { EvetServiceHome home = (EvetServiceHome) JNDIHelper.lookup( "java:comp/ev/ejb/evetservice" ), EvetServiceHome.class ); EvetService evetservice = home.create(); evetservice.dispatchevet( evet ); } catch( Exceptio e ) { /* Do exceptio hadlig here */ } } /* more code here */ Debuggig the Evet Service To debug the evet service, create a debug.properties file i the followig directory: %PORTAL_HOME%\debug.properties (Widows) $PORTAL_HOME/debug.properties (UNIX) 2-26 Guide to Evets ad Behavior Trackig

61 Debuggig the Evet Service The cotets of this file are show i Listig Listig 2-13 Debuggig the Evet Service usepackagenames: o com.bea.p13.cache: o # Turs o debug for all classes uder evets com.bea.p13.evets: o # com.bea.p13.evets.iteral.evetservicebea: o # Turs o debug for all classes uder # com.bea.p13.trackig: o com.bea.p13.trackig.iteral persistece: o # Selectively tur o classes com.bea.p13.mbeas.behaviortrackiglisterer: o com.bea.p13.trackig.listeers.behaviortrackiglisterer: o com.bea.p13.trackig.sessioevetlisterer: o Guide to Evets ad Behavior Trackig 2-27

62 2 Creatig Custom Evets Registerig a Custom Evet Whe you create a custom evet, you must register the evet. Registerig a custom evet lets the E-Busiess Cotrol Ceter kow that the custom evet exists. Registerig permits campaig developers usig the E-Busiess Cotrol Ceter to create sceario actios that refer to the evet. Registerig also idetifies the evet s properties. Cautio: Wheever you chage the evet code, you must update the evet registratio. Coversely, wheever you chage the evet registratio, you must also update the evet code. A possible ramificatio of evet modificatio is that the sceario actios that refer to the evet s properties may eed to be modified. Note: You caot chage ay of the stadard evets supplied with WebLogic Portal or WebLogic Persoalizatio Server. To register a custom evet, use the Evet Editor i the E-Busiess Cotrol Ceter. Registerig a evet is actually creatig a property set for the evet. A step-by-step procedure is available i both the E-Busiess Cotrol Ceter olie help ad Creatig ad Maagig Property Sets i the Guide to Buildig Persoalized Applicatios Guide to Evets ad Behavior Trackig

63 Activatig Behavior Trackig 3 Persistig Behavioral Trackig Data To record how olie customers are iteractig with your e-commerce site, you ca record evet iformatio to a database. These kids of evets are called Behavior Trackig evets. E-aalytics ad e-marketig systems ca the aalyze these evets offlie to evaluate customer behavior ad trasactioal data. You ca use the kowledge gaied from aalysis to create ad optimize persoalizatio rules, set up product offers, ad develop iteractive marketig campaigs. This sectio describes the requiremets ad database schema eeded to log evet data for aalytical use. This topic icludes the followig sectios: Activatig Behavior Trackig Data Storage Costraits ad Idexes Scripts Activatig Behavior Trackig Before Behavior Trackig evets ca be recorded to a database, you must eable the Behavior Trackig listeer. This is accomplished by addig a class to the applicatio-cofig.xml file. Guide to Evets ad Behavior Trackig 3-1

64 3 Persistig Behavioral Trackig Data Warig: For proper operatio, the WebLogic Server requires that chages to the applicatio-cofig.xml file be made usig the WebLogic Server Admiistratio Cosole. Note: For more iformatio o usig the WebLogic Server Admiistratio Cosole, see the WebLogic Server Documetatio Ceter. To add the Behavior Trackig listeer, take the followig steps: 1. I the WebLogic Server Cosole, avigate to Sychroous or Asychroous Listeers tab i the ode tree for wlcsdomai as follows: wlcsdomai Deploymets wlcsapp Service Cofiguratios Evet Service Cofiguratio Tab Sychroous Listeers 2. Add the Behavior Trackig listeer (com.bea.p13.trackig.listeers.behaviortrackiglisteer) to the Liste Class to Add field, ad the click the Add butto. See Figure 3-1. Figure 3-1 WebLogic Server Admiistratio Cosole Evet Service Note: You must cofigure your database before activatig Behavior Trackig. For iformatio o how to do this, see Productio Eviromet Sceario o page Guide to Evets ad Behavior Trackig

65 Activatig Behavior Trackig Evet Properties This sectio describes Behavior Trackig properties more fully ad details the mechaism that persists Behavior Trackig evet data to the database. Each Behavior Trackig evet property described here ca be cofigured i the WebLogic Server Admiistratio Cosole. Cofigurig the Behavior Trackig Service i WebLogic Server o page 3-3 details how to set these properties. As previously metioed, Behavior Trackig evets are placed i a buffer ad the itermittetly persisted to the Evet tables i the database where they ca be aalyzed offlie. A asychroous service is used so that log-ruig evet hadlers ca execute without delayig the applicatio from a Web site visitor s perspective. The buffered Behavior Trackig evets are swept ito the database usig a pool of data coectios. The default Data Source is weblogic.jdbc.jts.commercepool. You ca use a differet Data Source. To do this, create ad cofigure the ew Data Source (see Cofigurig a Data Source o page 3-4) ad substitute the ame of the default Data Source with the ame of the ew Data Source i the WebLogic Server Admiistratio Cosole. The particular evets that are persisted to the database are specified i the behaviortrackig.persisttodatabase property. You ca view ad alter the list of the persisted evets i the WebLogic Server Admiistratio Cosole. The types i this list must match the type specified i the evet; for example, the SessioBegiEvet has as its type the strig SessioBegiEvet. The frequecy of the sweepig of evets from the buffer is cotrolled by the followig properties i the applicatio-cofig.xml file: MaxBufferSize SweepIterval SweepMaxTime You should tue these properties to optimize performace. A buffer sweep should be performed ofte eough that writig to the database is ot too time cosumig but ot so frequet that the operatio is wasteful. Cofigurig the Behavior Trackig Service i WebLogic Server To cofigure the various Behavior Trackig properties, take these steps: Guide to Evets ad Behavior Trackig 3-3

66 3 Persistig Behavioral Trackig Data Warig: For proper operatio, the WebLogic Server requires that chages to the applicatio-cofig.xml file be made usig the WebLogic Server Admiistratio Cosole. Note: For more iformatio o usig the WebLogic Server Admiistratio Cosole, see the WebLogic Server Documetatio Ceter. 1. I the WebLogic Server Cosole, avigate to the Behavior Trackig Service (show i Figure 3-1) i the ode tree for wlcsdomai, as follows: wlcsdomai Deploymets wlcsapp Service Cofiguratios Behavior Trackig Figure 3-2 WebLogic Server Admiistratio Cosole Behavior Trackig Service 2. To chage the Data Source, eter the fully-qualified ame of the Data Source i the Data Source JNDI Name field. 3. To chage the sweepig of evets from the buffer, eter the ew buffer values i the appropriate fields. 4. To specify whether a particular evet is persisted, add or remove the evet from the Persisted Evet Types list box. Cofigurig a Data Source This sectio provides a brief descriptio about cofigurig a ew Data Source for a coectio pool used for persistig evets. To cofigure a ew Data Source, take the followig steps. 3-4 Guide to Evets ad Behavior Trackig

67 Data Storage Note: For more iformatio o usig the WebLogic Server Admiistratio Cosole, see the WebLogic Server Documetatio Ceter. 1. I the WebLogic Server Cosole, avigate to the Behavior Trackig Service (show i Figure 3-1) i the ode tree for wlcsdomai, as follows: wlcsdomai Services JDBC Data Sources Behavior Trackig Figure 3-3 WebLogic Server Admiistratio Cosole JDBC Data Sources 2. I the right pae, click Cofigure a ew JDBC Data Source. 3. Eter the appropriate values for the ew Data Source i the appropriate tabs ad fields. Data Storage This sectio provides a overview of relatioal databases ad the database schemas ad tables that are required for recordig Behavior Trackig evets. Guide to Evets ad Behavior Trackig 3-5