Setting Up Visitor Behavior Tracking

Note: All customers who configured their Recommendation module before January 8, 2024 need to switch their Recommendations modules in CX Tag to the new Data Ingestion API before March 01st, 2024 in order to keep their recommendation models updated with the new behavioral data. If you do not see the check box, see What to do if Data Ingestion API checkbox is disabled.

To successfully set up recommendations in Infinity, visitor behavioral data for actions such as viewed, and purchased need to be collected. This type of behavioral information is essential for the recommendations engine to work.

Visitor Behavior Tracking is implemented by setting up and enabling the Recommendations module within Oracle CX Tag.

Oracle CX Tag helps consolidate multiple tags for the Oracle Marketing Cloud suite of products under a single tag. The individual products are available as modules within the Data Collection application.

Assuming you have the CX Tag already implemented for your website, follow the steps below to set up Visitor Behavior Tracking by enabling the Recommendations module for your CX Tag.

Note: All customers who configured their Recommendation module before January 8, 2024 need to switch their Recommendations modules in CX Tag to the new Data Ingestion API before March 01st, 2024 in order to keep their recommendation models updated with the new behavioral data. If you do not see the check box, see What to do if Data Ingestion API checkbox is disabled.

To set up Visitor Behavior Tracking:

1. Navigate to the Data Collection section of Infinity IQ by either clicking Manage Data Collection in the Data Collection tile on the IQ homepage or in the IQ navigation menu.



2. Locate your CX Tag in the Data Collection section. In the example below, you can enable recommendations for the CX Tag Recommendations_Demo_Tag. The modules Published column for this CX Tag shows [In], which means only the Infinity Analytics Module is enabled for this CX Tag.



3. Click the CX Tag name you want to enable for recommendations. The screen below will display.



4. Hover your mouse over the Test section. + Add Module will display. Click + Add Module. The Add module dialog displays.



5. Select Recommendations to create a new Recommendations module and click Next. The options for the module display.



6. The next screen shows the options available for configuration for the Recommendation module. Check New Data Ingestion API checkbox as shown below. Refer to Configuration options for Recommendations module. If the checkbox is disabled, see below.

   

7. Confirm the details and click Save.

Once the configuration is saved, you will be taken to the Tag Detail page.

The tag is initially added to a test environment. Once the tag is available in the test environment, you can validate if the tag is working properly and reading all the required events you have set up. To validate the tag, refer to Test tag functionality. Once the validation is successful, you can then use the context menu to publish the tag to production.

Configuration options for Recommendations module

Available modes of data collection for Recommendations modules

You can choose from two modes for data collection.

• Oracle Infinity

• Custom Scripts

Oracle Infinity

Use this mode if you intend to use Oracle Infinity for data collection.

The events that you wish to collect, such as View and Purchase, should be auto populated on the screen.

Example

You configure the View and Purchase events as displayed below.

The values for the event name and trigger value for the View and Purchase events have the following values.

• View event

  • Event name: View

  • Trigger - Value: v

• Purchase event

  • Event name: Purchase

  • Trigger - Value: p

The values for the rest of the parameters would depend on the CX Tag implementation and how these parameters were initially set up. Refer below for information on the other parameters.

• Trigger Parameter: The Recommendations module listens to an Infinity Analytics parameter that stores the type of event. For example, if Infinity Analytics stores the trigger event in Trigger Parameter wt.tx_e, and the value of this trigger parameter is “v”, it's a View event. If the value is “p”, it's a Purchase event, and so on.

• You also need to read the SKU and Number of Units of the item on the same screen, and the corresponding events in Infinity IQ Analytics should be provided here.

The parameter names for Trigger Parameter, SKU , and Units will depend on how your Infinity Analytics module was set up. Please reach out to your account manager to identify the variable names to be used for Trigger Parameter, SKU and Units. If the parameters are now properly configured, Recommendations will not get the data corresponding to these events (View and Purchase).

Custom Scripts

Use this mode if you do not intend to use Oracle Infinity for data collection. You will need to define custom scripts that do the data collection on your website.

BeforeInit and AfterInit parameters

For both the Oracle Infinity and Custom Scripts modes, you have the option to define custom JavaScript code that executes before or after the Recommendation module initializes in the BeforeInit and AfterInit sections.

Refer to the following sample JavaScript codes.

View Event

function(){
  varproductID=0//putherehowtogetaproductIDfromthepageif(productID){
    ratings.set('View',
    1,
    productID);
  }
}

Purchase Event

function(){
  varproductIDs=[
    
  ];//putherehowtogetaproductIDfromthepagevarpurchasedUnits=[
    
  ];//putherehowtogetaproductIDfrompageif(productIDs){
    ratings.set('Purchase',
    purchasedUnits,
    productIDs);
  }
}

Test tag functionality

Once the test environment for the tag is ready, you can copy the tag URL by clicking the context menu for the test environment and clicking Copy URL.

There are two ways to test the tag to ensure it can be published to production: 

• If you have a QA environment for your website, you can set up the test tag URL directly on the website.

• If your website doesn't have a separate QA environment, you can complete the steps below.

To test a tag without using a QA environment:

1. From the previously copied tag URL, you need to take _ora.config parameter, which is in the end of it. For example, if you were editing tag configuration named Test, you parameter will look like the following: ?_ora.config=recommender:test;analytics:test. It may be different depending on the name of the tag configuration you use for test and the list of tag modules you have.

2. Open any product detail page on your production website and append the URL with the following: &_ora.debug=vv&[_ora.config parameter with its value you've copied from the previous step]

   Please note that you need to add ? before &_ora.debug if your URL has no other parameters. If there are some parameters you need to use & before _ora.debug

   • _ora.debug=vv enables debug mode for your tag which allows to test and troubleshoot the new tag configuration

   • _ora.config with the value you copied from the tag configuration menu applies this configuration to the tag in your browser

   Example: 

   If your testing configuration of the CX tag is called Test and you have only Analytics and Recommendations module enabled, your _ora.config parameter in the copied tag, the URL will be: _ora.config=recommender:test;analytics:test.

   If the product detail page URL for your website is https://www.sample.com/product.php?someparam=somevalue then you would update the test URL to the following: https://www.sample.com/product.php?someparam=somevalue&_ora.debug=vv&_ora.config=analytics:test;recommender:test.

   If the original product detail page URL does not have any parameter and looks like https://www.sample.com/product.php?myproductpage, then you would update the test URL to the following: https://www.sample.com/product.php?myproductpage?&ora.debug=vv&_ora.config=analytics:test;recommender:test.

3. Open Network Tools in your browser by using Function Key + F12.

4. Refresh the product detail page again with the _ora.config parameter appended to the URL.

5. You should notice that recommender-test.js script should be loaded and the site variable in the network call should be same as the site defined in Recommendation Tag setup done in the Data Collection section. Compare that site name is the same one configured in the Data Collection section while creating the tag. Refer to the image below showing that the correct test tag is loaded on the website.

6. In the network tab search for requests having "service.recommendations.ocs.oraclecloud.com/apps/dia/".

   The full request URL may look like:

   • https://eu.service.recommendations.ocs.oraclecloud.com/apps/dia/v1/projects/[Your workspace ID]/actions
   • https://us.service.recommendations.ocs.oraclecloud.com/apps/dia/v1/projects/[Your workspace ID]/actions

   The response code should be 201 - created. That means that the Product View event has been successfully registered by the system.





7. The Recommendation module should be sending the history data to Infinity using the tx_rechist1, tx_rechist2, and tx_rechist3 variables. The name of these variables will depend on your tag implementation.



8. You should validate that the right View event with the correct product ID is being passed to Recommendations as shown below.



Similar to validating the View event, test the Purchase event.

9. Make a purchase on your website. The data for the purchase event should be sent to Recommendations module. Validate if the WorkspaceID is correct as set up during the Recommendation module setup in the Data Collection section.

10. Validate that the purchase data is collected correctly.

Once you have performed the testing to ensure the tag is correctly sending event data for the View and Purchase events, you can publish the test tag to production.

Publish the tag to production

Once testing is successful, the tag can be pushed to production.

To publish the tag to production: 

1. Visit the Data Collection page.

2. Click the name of the tag you want to publish.

3. In the Test section, open the context menu for the tag and click Publish to Production.

Once the tag is deployed to production, visitor behavior tracking should be enabled.

What to do if Data Ingestion API checkbox is disabled

If you observe that the New Data Ingestion API checkbox is disabled, this means that your Recommendation module version does not support the new API yet. You need to update your module to a new version that is supported. Currently, Recommendation module version 4.0.1 and above are supported.

1. On module configuration editing panel switch to Advanced option tab. You need to have Tag Consultant role for Data Collection to access this tab. Learn more.

2. In the JSON editor change moduleVersion value to 4.0.1 so the line looks like "moduleVersion": "4.0.1".

3. Switch back to Options. You should be able to check New Data Ingestion API checkbox now.

4. Save changes and perform testing as described above.

Next steps

Setting Up Inventory for Recommendations