Configuring the IBM Digital Data Exchange integration

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

Before you begin

To complete the following steps, ensure that your complete the following tasks:
  • Integrate your store with IBM Digital Analytics. The following steps use an integration with IBM Digital Analytics to demonstrate how to integrate WebSphere Commerce with DDX to relay data to an analytics provider.

Procedure

  1. Go to the following directory, which contains the deployed biConfig.xml file for your integration between WebSphere Commerce and your analytics provider, such as IBM Digital Analytics.
    • WC_eardir/xml/config/bi
    • WebSphere Commerce Developer WCDE_installdir\workspace\WC\xml\config\bi
  2. Open the biConfig.xml file for editing.
    This file includes the configuration settings for how WebSphere Commerce integrates with IBM Digital Analytics.

    For more information about configuring the values for an analytics provider in this file, see Configuring the store to communicate with IBM Digital Analytics(biConfig.xml).

  3. Update the analytics provider configuration for your 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 that is associated with that analytics provider. You 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 your 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 that is 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 that is specified as the Analytics_Provider_site value.
    Analytics_Provider_site
    The domain name for your analytics site. For example, "data.coremetrics.com".
    WebSphere_Commerce_server
    The domain name of your 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 you can configure when you use 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 your 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 your store is not based on this starter store, or you want to change the default page type values sent to DDX, include the page type values on your 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 you are configuring page group rules in DDX to determine whether the tags that are 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 you are including a page type parameter value within.
    2. Add the page type parameter to the page view tag on your store pages. Set the value for the parameter to include any page types that you want 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 you are adding custom pages to your store that you want to gather analytics information from to send to DDX, add this value.

      You 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. You 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 you enable the DDX support, there is no change to how the campaign tag behaves.
      If you do not include the page type parameter on your 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.
      For more information, 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