Configure the IBM Digital Data Exchange integration

We can enable the integration between WebSphere Commerce and IBM Digital Data Exchange (DDX) by updating the analytics provider configuration for the site.


Before beginning

To complete the following steps, ensure that your complete the following tasks:


Procedure

  1. Go to the following directory, which contains the deployed biConfig.xml file for our integration between WebSphere Commerce and your analytics provider, such as IBM Digital Analytics.

  2. Open the biConfig.xml file for editing. This file includes the configuration settings for how WebSphere Commerce integrates with IBM Digital Analytics.

  3. Update the analytics provider configuration for the site or stores to include the "useDDX" configuration option. When the value for this option is set to "true" or is included with no value, the JavaScript output for all analytics tags is included in a JavaScript object and sent to DDX. Include the option in the <biprovider/> element to set the configuration to be the default value for every store associated with that analytics provider. We can also override the setting for a store, by including the option with a different value in the <store/> element configuration for a store.

    • All stores 

        <biprovider name="coremetrics"
 enabled="true"> 
 ...
 <options>
   <attribute name="useDDX" />
 </options>
 ...
</biprovider>

    • Specific stores 

        <store 
 storeId="10101,10102,10103" 
 biprovider="coremetrics" 
 enabled="true"> 
 ...
 <options>
  <attribute name="useDDX" value="true" />
 </options> 
 ...
</store>

      Where storeId is the store ID value or list of store ID values. For example, "10101,10102,10103".

  4. Update the output configuration for the site or stores to include the cmSetClientID function in your JavaScript if the setting is not already configured. Set the appropriate values for the function as shown in the following example. 

      <output section="header">
<![CDATA[
...
<script type="text/javascript">
cmSetupNormalization("krypto-_-krypto");
cmSetClientID(Client_ID,Data_collection_method,Analytics_Provider_site,WebSphere_Commerce_server);
</script>                 
]]>
</output>

    Where

      Client_ID
      The client ID that is provided by your analytics provider. For example, "99999999".

      Data_collection_method
      The data collection method. Set one of the following values:

        true
        The data collection browser cookies are managed at the browser client, which is set in the domain specified as the WebSphere_Commerce_server value.

        false
        The data collection browser cookies are managed by your analytics provider, which is set in the domain specified as the Analytics_Provider_site value.

      Analytics_Provider_site
      The domain name for our analytics site. For example, "data.coremetrics.com".

      WebSphere_Commerce_server
      The domain name of the WebSphere Commerce server. For example, "thesite.com".

    For example, 

      <output section="header">
<![CDATA[
...
<script type="text/javascript">
cmSetupNormalization("krypto-_-krypto");
cmSetClientID("99999999",true,"data.coremetrics.com","thesite.com");
</script>                 
]]>
</output>

  5. Save and close the file. For an example of a complete biConfig.xml file and for more configuration settings that we can configure when using IBM Digital Analytics as your analytics provider, see
    Sample biConfig.xml file for IBM Digital Analytics.

  6. Add page type parameter values to the page view tags on the store pages to identify the analytics data entries in the JavaScript object that is being sent to DDX.

    Stores that are based on the WebSphere Commerce Aurora starter store already include page type (unique page identifier) values defined in digitalData.pageInstanceID. If the store is not based on this starter store, or we want to change the default page type values sent to DDX, include the page type values on the store pages. By default, all pages for stores that are based on the WebSphere Commerce Aurora starter store include a default configuration that associates the "wcs-standardpages" value with the page view tag. Some pages also include other values. For example, the OrderItemDisplay.jsp Aurora starter store page includes the following page type parameter configuration: 

      <cm:pageview pageType="wcs-cart"/>

    Note: If the support for integrating with DDX is not enabled, the page type parameter and value is ignored.

    The page view tag collects information about store pages that a customer viewed. For more information about this tag, see Page view tag.

    WebSphere Commerce defines the page type parameter value in digitalData.pageInstanceID. The pageInstanceID value is referenced when we are configuring page group rules in DDX to determine whether the tags assigned to that page group are deployed to a store page. In this way, tags can be logically grouped within DDX for deployment to types of pages that should receive those tags. For example, tags needed to collect page and product information from a shopping cart page are added to a DDX page group with a rule of pageInstanceID = 'wcs-cart'.

    1. Open the JSP for the store page that includes the page view tag that we are including a page type parameter value within.

    2. Add the page type parameter to the page view tag on the store pages. Set the value for the parameter to include any page types to associate with the page. When you include multiple values, separate the values with an " _ " underscore character. For example, the OrderShippingBillingConfirmationPage.jsp Aurora starter store page includes the following page type parameter and value configuration: 

        <cm:pageview pageType="wcs-order_wcs-registration"/>

      By default, the following parameter values are available for use on WebSphere Commerce Aurora starter store pages.

        wcs-productdetail
        This value is included on pages to identify that the data that is being added to the digitalData JavaScript object is catalog entry data. For example, this value is included by default on the ProductDisplay.jsp Aurora starter store page. Consider adding this value to pages that include the product <cm:product /> tag.

        wcs-cart
        This value is included on pages to identify that the data that is being added to the digitalData JavaScript object is shopping cart data. For example, this value is included by default on the OrderItemDisplay.jsp Aurora starter store page. Consider adding this value to pages that include the shopping <cm:cart /> tag.

        wcs-registration
        This value is included on pages to identify that the data that is being added to the digitalData JavaScript object is registration or user-related. For example this value is included by default on the OrderShippingBillingConfirmationPage.jsp Aurora starter store page. Consider adding this value to pages that include the registration <cm:registration /> tag.

        wcs-order
        This value is included on pages to identify that the data that is being added to the digitalData JavaScript object is order-related data. For example, this value is included by default on the OrderShippingBillingConfirmationPage.jsp Aurora starter store page. Consider adding this value to pages that include the order <cm:order /> tag.

        wcs-element
        This value is included on pages to identify that the data that is being added to the digitalData JavaScript object is customer interaction data. Consider adding this value to pages that include the element <cm:element /> tag.

        wcs-conversionevent
        This value is included on pages to identify that the data that is being added to the digitalData JavaScript object is event-related data that is not related to product purchases. Consider adding this value to pages that include the shopping <cm:conversion /> tag.

        wcs-standardpage
        This value is the default value for all store JSP pages that include the page view tag. If we are adding custom pages to the store to gather analytics information from to send to DDX, add this value.

      We can override the "wcs-standardpage" value or other default values by extending the CommonBaseTag class and changing the value of the variables that hold these values. For example, the variable that holds the "wcs-standardpage" value is a protected variable, DEFAULT_PAGE_TYPE. We can also override the use of the " _ " underscore character as the separator character. The variable that holds this value is also a protected variable, DEFAULT_PAGE_TYPE_SEPARATOR in the CommonBaseTag class.

      Note: The DDX configuration does not affect the functionality or output of the campaign <cm:campurl /> tag. This tag does not generate a JavaScript section in the output so there is no corresponding DDX change. When we enable the DDX support, there is no change to how the campaign tag behaves. If you do not include the page type parameter on the store pages, you need to complete one of the following configurations to identify your data entries. For more information about completing either of the following configurations, see the documentation that is provided by DDX.

      • Define JavaScript to detect the page type on each store page, such as determining the page type from the URL that is provided by window.location.href in JavaScript.

      • Use the DDX Tag Manager to register code that can determine the page type, such as from the URL that is provided by window.location.href in JavaScript.

      If you do not include any values other than the default "wcs-standardpage" parameter value, the following value is output to the digitalData JavaScript object: 

        digitalData = { pageInstanceID: "wcs-standardpage" }

      If you do include other page type values, the values are appended to the "wcs-standardpage" value in the JavaScript object: 

        digitalData = { pageInstanceID: "wcs-standardpage_wcs-order_wcs-registration" }

    3. Configure DDX to create the page groups and rules to register the page type parameter values and define how DDX is to relay the data that is included in the digitalData JavaScript object. See the documentation that is provided by DDX.


Results

Your analytics integration can generate an output to send to DDX. With this output, all data to be sent to DDX and relayed to IBM Digital Analytics is included in the digitalData JavaScript object. For examples of how the existing WebSphere Commerce analytics tags, which include a corresponding page type parameter value, output data to the JavaScript object, see


Related concepts
Integrating a store with IBM Digital Analytics for WebSphere Commerce


Related tasks
Configure the store to communicate with IBM Digital Analytics(biConfig.xml)