Hybris Marketing Web Tracking

Transcription

1 Integration Information SAP Hybris Marketing 1602 Document Version: Hybris Marketing Web Tracking How to Set Up Components for the Hybris Marketing Web Tracking

2 Typographic Conventions Type Style Example Description Words or characters quoted from the screen. These include field names, screen titles, pushbuttons labels, menu names, menu paths, and menu options. Textual cross-references to other documents. Example EXAMPLE Example Example <Example> Emphasized words or expressions. Technical names of system objects. These include report names, program names, transaction codes, table names, and key concepts of a programming language when they are surrounded by body text, for example, SELECT and INCLUDE. Output on the screen. This includes file and directory names and their paths, messages, names of variables and parameters, source text, and names of installation, upgrade and database tools. Exact user entry. These are words or characters that you enter in the system exactly as they appear in the documentation. Variable user entry. Angle brackets indicate that you replace these words and characters with appropriate entries to make entries in the system. EXAM PLE Keys on the keyboard, for example, F2 or EN TER SAP AG or an SAP affiliate company. All rights reserved.

3 Document History Caution Before you start the implementation, make sure that you have the latest version of this document that is available on SAP Service Marketplace at Version Date Change Initial Version Feedback We d really like to know what you think of the quality, structure or content of this guide. Please send your feedback to us at saphybrismarketingfeedback@sap.com. Hybris Marketing Web Tracking Document History 2015 SAP AG or an SAP affiliate company. All rights reserved. 3

4 Table of Contents 1 Overview hybris Business Event Extensions Initial Installation Adding Business Event Extensions Verifying hybris Business Event Extensions SAP Event Stream Processor License Installation SAP Java Connector Starting the ESP Cluster Logon to the ESP Cockpit Providing an Restricted User for Project Access Configuring the Web Service Provider Setting up the Standard Project Using the ESP Cockpit to Manage Projects Manage Projects with the Command Console Configuring a Web Server or CMS More Information SAP AG or an SAP affiliate company. All rights reserved. Hybris Marketing Web Tracking Table of Contents

5 1 Overview In SAP hybris Marketing, you can use the results of website visitors tracking as provided by hybris Commerce Platform (ECP) web shops, for example, to measure campaign success, or to offer real-time personalization. To enable the use of tracking results, set up a system landscape as described in the following sections. See the following chart for an overview of the system landscape. Note The procedures described in the guide apply when you use a Windows operating system SAP AG or an SAP affiliate company. All rights reserved. 5

6 2 hybris Business Event Extensions To enable the website visitors tracking in a hybris Commerce Platform (ECP) web shop, you require the hybris Commerce Suite version 5.7 or higher. By default, the hybris Business Event Extensions are configured requiring an installation of the message oriented middleware server (see chapter Apache ActiveMQ) on the server where the ECP is installed. If you install the middleware server on a different server, consider the configuration information in the hybris Business Event Extensions - Technical Guide at: +Technical+Guide#hybrisBusinessEventExtensions-TechnicalGuide-ExtensionConfiguration Extension Configuration. 2.1 Initial Installation When you initially install the hybris Commerce Suite make sure to include the hybris Business Event Extensions. For the details, see the hybris Business Event Extensions - Technical Guide at: +Technical+Guide#hybrisBusinessEventExtensions-TechnicalGuide-Installationusingthehybrisinstaller Installation using the hybris installer. If you want to use the installation locally for testing and development purposes, see the B2C B2B Accelerator Quick Installation Guide at: Adding Business Event Extensions You can add the hybris Business Event Extensions to an existing installation of the hybris Commerce Suite. For the details about how to add the extensions manually, see the hybris Business Event Extensions - Technical Guide at: +Technical+Guide#hybrisBusinessEventExtensions-TechnicalGuide-Manualinstallation Manual installation SAP AG or an SAP affiliate company. All rights reserved.

7 3 Verifying hybris Business Event Extensions We recommend to verify the installation of Apache ActiveMQ in connection with hybris Business Event Extensions. For the details, see the Documentation of the hybris Commerce Suite at: +Technical+Guide#hybrisBusinessEventExtensions-TechnicalGuide-Verifyingtheinstallation Verifying the installation. In addition, consider that the standard configuration only works for local testing as by default, the tracking URLs point to your localhost. For information about how to change the URLs, see the Documentation of the hybris Commerce Accelerator at: ConfiguringtheTrackingURLs Configuring the Tracking URLs SAP AG or an SAP affiliate company. All rights reserved. 7

8 4 SAP Event Stream Processor To enable the processing of the business events provided by the ECP, and buffered by the message oriented middleware server, install the SAP Event Stream Processor (ESP) as described in the following sections. 4.1 License To run the ESP you require a license. Place the license key it in the licenses folder, for example, in the folder <Sybase installation path>\sysam-2_0\licenses. 4.2 Installation To install the ESP, download the ESP 5.1 SP10 installation package from SAP Marketplace at: Installations and Upgrades E SAP EVENT STREAM PROCESSOR SAP EVENT STREAM PROCESSOR 5.1. Choose the Windows system you are using, and select the ESP 5.1 SP10 release. Extract the installation package. Run the setup considering the following: Use the GUI installer, and choose the typical installation. If you perform a custom installation, make sure the following components are included in the installation: o ESP Server o ESP Cockpit o ESP Studio Note the cluster password, the cluster name, and the node name; the information is required in the following setup process. Copy the Apache ActiveMQ jar file activemq-all.jar from <ActiveMQ home> to the %STREAMING_HOME%/libj and %STREAMING_HOME%/adapters/framework/libj directories. 4.3 SAP Java Connector To enable the communication between the ABAP backend system and the ESP server, install the SAP Java Connector (SAP JCo) in the system where you have installed the ESP server. To install SAP JCo, proceed as follows: Download the SAP JCo release 3.0 from the SAP Service Marketplace at: SAP Java Connector (SAP JCo) Tools & Services Download SAP JCo Release 3.0. Extract the package into a folder in your system. Copy the file sapjco3.jar into the following folders: SAP AG or an SAP affiliate company. All rights reserved.

9 o %ESP_HOME%\adapters\rfc\libj Copy the file sapjco3.dll into the following folders: o %ESP_HOME%\adapters\rfc\bin o %ESP_HOME%\adapters\rfc\lib Set up the following environmental variables: o Add <SAP JCo install path> to the PATH environmental variable o Add <SAP JCo install path>\sapjco3.jar to CLASSPATH environmental variable 4.4 Starting the ESP Cluster Start the ESP cluster to enable the deployment of ESP projects in the ESP runtime environment. In the following sections, we refer to a single-node cluster, which you can use as a starting point to create multinode clusters as required. Setting Variables for the ESP Cockpit Before opening a new Command Prompt to execute ESP commands, run the batch processing <Sybase installation path>\streaming.bat. It sets the %STREAMING_HOME% environment variable, and it sets additional variables for the ESP cockpit. Cluster Database and an ESP Node Start the cluster database and an ESP node as follows: Start the cluster database. At the command prompt, enter %STREAMING_HOME%\cluster\config\<Cluster name>\start_db.bat. By default, the cluster name is esp1. Start an ESP Node. At the command prompt, enter %STREAMING_HOME%\cluster\config\<Cluster name>\start_node.bat <Node name>. By default, the node name is node1. When you start the ESP 5.1 SP10 the shared cache is stored in the cluster database, which contains configuration information for all nodes in the cluster. Managing ESP User By default, you manage ESP users in the native operating system mode. As a result, you can use the operating system user and password also for the ESP logon. Note that the operating system user has to be entered as <OS user>@<domain>. Proceed as follows: At the command prompt, enter %STREAMING_HOME%/bin/streamingclusteradmin -- uri=esps://<streaming host name>:<cluster port> --username=sys_streaming. By default, the cluster port is The streaming host name is found in the cluster configuration file %STREAMING_HOME%\cluster\config\<Node name>\cluster.xml. In the interactive mode, enter the cluster password you have noted in the course of the ESP installation (see section SAP Event Stream Processor Installation). In the interactive mode, you create roles, assign permissions to roles, assign roles to users, or assign permissions directly to a user SAP AG or an SAP affiliate company. All rights reserved. 9

10 Example To create a cluster manager role that allows you to configure a cluster, and to manage projects, execute the following commands: o add role clustermanagerrole o grant perm all to role clustermanagerrole o grant role clustermanagerrole to user <OS user>@<domain> 4.5 Logon to the ESP Cockpit To start the ESP cockpit server, start the Command Prompt as an administrator, and enter: %SYBASE%\COCKPIT- 4\bin\cockpit.bat. Note the URL <Cockpit Web Console> from the Command Prompt output, which shows the following pattern: host name>:<port>/cockpit. Start the ESP cockpit in web browser with the URL <Cockpit Web Console>. Logon to the ESP cockpit with user <OS user>@<domain>, and password <OS password>. 4.6 Providing an Restricted User for Project Access Provide a restricted user for the project access as described in the following sections. Preconfigured User and Password Define a name <Restricted user> and password <Password of restricted user> for the restricted user as follows. 1. To generate a password value in an encoded form, enter the following command (in the Console): $STREAMING_HOME/bin/streamingclusteradmin --encode_text Please enter text to be encoded: (enter the password to be encoded) Please re-enter text to be encoded: Copy the encoded password <Encoded password of restricted user> from the console. 2. Change the default user password in the cluster configuration file %STREAMING_HOME%\cluster\config\<Node name>\cluster.xml. In the element <Security> <Authenticator>, add the PreConfiguredUserLoginModule authenticator provider, and transfer the encoded value to the option password. Example: <Security> <Authenticators> <xi:include href="auth_native_nt.xml" parse="xml"/> <Authenticator> <Provider>com.sybase.security.core.PreConfiguredUserLoginModule</Provider> <Options> <Option name="username"><restricted User></Option> SAP AG or an SAP affiliate company. All rights reserved.

11 <Option name="password"><encoded password of restricted user></option> </Options> </Authenticator> </Authenticators> Adding a Pre-Configured Authentication (ESP Cockpit) To add a preconfigured user authentication to the ESP Cockpit proceed as follows: 1. Logon to ESP Cockpit. 2. Select the EXPLORE workset. 3. Select ESP Nodes, then select Actions Configure Cluster. 4. Expand the Security folder, and the Authenticators folder. 5. Click Add Authenticator. 6. Select the authenticator type Pre-Configured User, Click Done. 7. Edit the values for the following options: o Username: <Restricted user> o Password: <Encoded password of restricted user> 8. Click Apply. 9. Restart all running nodes to apply the changes. Changes are stored in the cluster database. Assign the Authorization In the console, enter the following utility in the command line to assign the minimum authorization to your preconfigured user: %STREAMING_HOME%/bin/streamingclusteradmin --uri=esps:// <Streaming host name>:<cluster port> --username=sys_streaming Password: (the password you have noted during the installation of the ESP) > grant perm write stream on stream sap_project_workspace/web_tracking_01/window1 to user <Restricted user> 4.7 Configuring the Web Service Provider If you have installed an Event Stream Processor (ESP) using a typical installation (as described in this guide), SSL is enabled by default. When SSL is enabled, gateway communication is encrypted, all incoming URLs must use HTTPS, and URIs must use ESPS. Make sure in file %STREAMING_HOME%\wsp\wsp.xml, line 5, <protocol> is set to https</protocol>. To start the ESP web service provider, start the Command Prompt as an administrator, and enter: %SYBASE%\wsp\wsp.bat SAP AG or an SAP affiliate company. All rights reserved. 11

12 4.8 Setting up the Standard Project With SAP hybris Marketing we deliver a standard ESP project. The standard project allows you to track web events, and it allows you to create corresponding Interactions in the SAP hybris Marketing system. To set up the standard project, which is delivered by SAP, proceed as follows: Download the project package from the SCN at: Extract the project package into an arbitrary folder. The folder includes a subfolder sap_web_tracking. We refer to that subfolder in the following sections as <Project file folder>. Adjusting the.ccr File Open the <Project file folder>/sap_web_tracking.ccr file using a text editor and proceed as follows: In line 6 (SAP RFC Output adapter), replace the string $project_file_folder by the full path of the project file. Encrypting the RFC Password For security reasons, encrypt the password for the RFC connection. Proceed as follows using the JDK keytool utility to create a keystore, and a self-signed certificate, which you then can use to encrypt the password: Open the Command Prompt, and enter: %SYBASE%\jre64\bin\keytool.exe -genkey -keyalg RSA - alias <RFC user name> -keystore <Keystore.jks> -storepass <Keystore password> -validity 360 -keysize Encrypt the password for the RFC connection entering: %SYBASE%\jre64\bin\java.exe -cp %SYBASE%\ESP-5_1\adapters\repserver\libj\streaming-adapter-api.jar; %SYBASE%\ESP- 5_1\adapters\repserver\libj\commons-codec-1.3.jar com.sybase.esp.adapter.api.cryptutils encrypt <RFC password> <RFC user name> RSA <Keystore.jks> <Keystore password> Copy the string resulting from the encryption; you require the string in the adapter configuration (see next step). Adjusting the Adapter Configuration Adjust the adapter configuration file as follows: Open the <Project file folder>/adapter_config/adapter_rfc_output.xml file using a text editor. In line 24, specify the corresponding backend ABAP system with host name, system number (instance number), client, RFC user, RFC password, and specify the full path of the file <Project file folder>/adapter_config/rfc_mapping.xml: <RFCOutputTransporterParameters> <Host>$host_name</Host> <SystemNumber>$system_number</SystemNumber> <Client>$client</Client> <SAPUser>$RFC_user</SAPUser> <SAPPassword encrypted="false">$rfc_password</sappassword> <Keystore>$keystore.jks</Keystore> <KeystorePassword>$keystore_password</KeystorePassword> <BatchSize>0</BatchSize> SAP AG or an SAP affiliate company. All rights reserved.

13 <RFC> <Function>CUAN_CE_INTERACTIONS_POST</Function> <Mapping><$project_file_folder/adapter_config/rfc_mapping.xml</Mapping> </RFC> </RFCOutputTransporterParameters> Enabling Cold Failover Open the <Project file folder>/sap_web_tracking.ccr file using a text editor and proceed as follows: In line 19, you can optionally enable a restart for failed projects by setting cold failover for the project. Set the following properties: <Failover enable="true"> <FailureInterval>120</FailureInterval> <!-- in seconds --> <FailuresPerInterval>4</FailuresPerInterval> <!-- counter --> </Failover> (<FailureInterval> specifies the time of an interval; <FailuresPerInterval> specifies how many times a project is restarted within an interval, before the cluster stops) Compiling the.ccx File To compile the.ccl file to a.ccx file, enter the following at the Command Prompt: %STREAMING_HOME%/bin/streamingcompiler i <CCL File> -o <CCX File>. In the string, replace -i, and -o as follows: For -i enter the name, and the location of the.ccl file you want to compile For -o you can optionally enter the name, and the location of the compiled.ccx file For example, %STREAMING_HOME%/bin/streamingcompiler -i <Project file folder>\sap_web_tracking.ccl -o <Project file folder>\bin\sap_web_tracking.ccx 4.9 Using the ESP Cockpit to Manage Projects In the ESP cockpit, choose Explore ESP Nodes Manage Projects SAP AG or an SAP affiliate company. All rights reserved. 13

14 Add the project specifying sap_project_workspace for the Workspace, and sap_web_tracking for the Project Name. Select the.ccx and.ccr file from folder <Project file folder>. Choose Start Project SAP AG or an SAP affiliate company. All rights reserved.

15 4.9.1 Manage Projects with the Command Console As alternative, you can use the Command Prompt to manage projects as follows: To deploy the project to a node proceed as follows: o At the Command Prompt, enter: %STREAMING_HOME%/bin/streamingclusteradmin -- uri=esps://<streaming host name>:<cluster port> --username=<os user>@<domain>. By default, the cluster port is o In the interactive mode, enter the following commands: o Password: <OS password> o add project <Workspace>/<Project Name> <CCX File> <CCR File> o For example, add project sap_project_workspace/sap_web_tracking <Project file folder>\bin\sap_web_tracking.ccx <Project file folder>\sap_web_tracking.ccr o When the project is successfully deployed the system messages done. o Enter get projects to view all deployed projects. Start or stop the project entering: start project sap_project_workspace/sap_web_tracking. View the project status entering: get projects Configuring a Web Server or CMS To enable the Web tracking on your web server, or content management system (CMS), configure your system as follows: Download the piwik.js file from Deploy the piwik.js file on your web server, or CMS. In each Web page where you want to enable the Web tracking, enter the following tracking snippet below the <body> tag: <script type="text/javascript"> var _paq = _paq []; _paq.push(['trackpageview']); _paq.push(['enablelinktracking']); (function() { _paq.push(['settrackerurl', '<URL of endpoint >']); _paq.push(['setsiteid', 1]); _paq.push(['setrequestmethod', 'POST']); _paq.push(['setcustomrequestprocessing', function (request) { 2015 SAP AG or an SAP affiliate company. All rights reserved. 15

16 try { var oreturn = { connectiondetails: { clustername: "<Cluster name>", port: "<Cluster port>", authentication: { type: "user", data: "<Restricted user>:<password of restricted user>", sslenabled: "true" } } }; var pairs = request.split('&'); var requestparametersarray = {}; for (var index = 0; index < pairs.length; ++index) { var pair = pairs[index].split('='); requestparametersarray[pair[0]] = decodeuricomponent(pair[1] ''); } oreturn.content = requestparametersarray; return JSON.stringify(oReturn); } catch (err) { return request; } }]); var d=document, g=d.createelement('script'), s=d.getelementsbytagname('script')[0]; g.type='text/javascript'; g.async=true; g.defer=true; g.src='<path to piwik.js>'; s.parentnode.insertbefore(g,s); })(); </script> Placeholder In the tracking snippet, replace the highlighted placeholders entering your specific information as follows: Placeholder URL of endpoint Path to Piwik.js Specific Information Endpoint for the requests of the tracking snippet. In addition, see Security Note below. Enter the path and filename that points to the piwik.js file on your webserver The URL of the SAP ESP web service provider is host name>:<rest provider port>/espws/restservice/stream/bulk?action=insert&workspace=sap_project_workspace&proj ect=sap_web_tracking. The REST provider port can be found in file %STREAMING_HOME%\wsp\wsp.xml SAP AG or an SAP affiliate company. All rights reserved.

17 Security Note For security reasons, we strongly recommend to implement a proxy web service in front of the SAP ESP web service provider, which serves as endpoint for the requests of the tracking snippet. Use the proxy web service to provide security measures, such as a filtering of malicious IP addresses, blacklisting of IP addresses causing abnormal traffic, filtering of requests with unexpected size, or format. We strongly advice you not to allow the tracking snippet to send the information directly to the SAP ESP web service provider. If you do allow it, you do it at your own risk More Information For additional information about the ESP, see SAP Event Stream Processor at: SAP AG or an SAP affiliate company. All rights reserved. 17

18 SAP AG or an SAP affiliate company. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. National product specifications may vary. These materials are provided by SAP AG and its affiliated companies ( SAP Group ) for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty. SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and other countries. Please see for additional trademark information and notices. Material Number: