Configure settings in the biConfig.xml file so that
integration with IBM Digital Analytics, formerly known as Coremetrics Analytics is
enabled and configured for your store.
About this task
After you update you biConfig.xml file in your development
environment, deploy the file to the WebSphere Commerce Enterprise Archive
(WC_eardir/xml/config/bi/) in your production environment.When you are updating the biConfig.xml file to define the
analytics provider configuration, you can set default values for each configuration setting. By
setting default values, you can quickly configure multiple stores to use the same configuration for
an analytics provider. You can also override any of the default values for an individual store by
including a different value in the configuration for the store. For more information, see Configuring default values for an analytics provider.
Procedure
In your development environment, define your
biConfig.xml file.
Then, deploy your file to the
WebSphere Commerce
enterprise archive (EAR) on your staging or production environment.
When you are updating the
biConfig.xml file in your development environment, you can use a reload file to
help you quickly test configuration changes. By using this reload file, you do not need to
continually restart your server to apply configuration changes from the
biConfig.xml file. For more information, see Using a reload file to test the analytics integration configuration.
-
Go to the following directory, which contains the sample biConfig.xml
file:
- WCDE_installdir/samples/Coremetrics/xml/biConfig.xml
-
Copy the sample biConfig.xml file to the following directory:
- WCDE_installdir/workspace/WC/xml/config/bi/
-
Open the biConfig.xml file for editing.
-
Configure the analytics reporting options for each store that must be associated with an
analytics provider:
-
Find a line similar to the following code:
<store
storeId = "10101"
biprovider = "coremetrics"
enabled = "true"
debug = "true"
marketingCenterEnabled="true"
useHostedCMHLibraries = "true"
useEmailForCustomerId = "false"
segmentExportMode = "append">
When
you are configuring the analytics reporting options for multiple stores, you can apply one
configuration to multiple stores by including a list of store ID values. You can also copy the
sample configuration to create multiple configurations and apply each configuration to one or more
stores.
-
Change the value for the store ID and analytics provider identifier to associate the store to
the analytics provider. You can set values for the following attributes:
- storeId
- Specifies the
storeId
of the store or stores that you want
to enable for IBM Digital Analytics. You can
specify the storeId
value as:
- A single
storeId
value.
- A comma-separated list of
storeId
values. For example, specify
storeId="10000, 10001"
to enable IBM Digital Analytics for two stores by using the same
IBM Digital Analytics client ID and tag library
that is defined in the configuration.
- A range of
storeId
values. For example, specify
storeId="10000-10200"
to enable IBM Digital Analytics for all of the stores that have
storeId
values that fall within the range that include the specified upper and
lower bounds. The stores that are specified in the range must share the IBM Digital Analytics client ID and tag library that is
defined in the configuration.
- biprovider
- The analytics provider. Leave this value set to coremetrics.
-
Set values for any of the following reporting options that you want to configure for each
store.
If you configured any default values for an analytics provider, you can override any of
these values by setting store-specific values. To use a default value again, remove the
store-specific value.
- clientId
- The client ID for the store, as provided by the analytics provider.
- enabled
- Indicates whether tracking is enabled, which means that analytics data is sent to IBM Digital Analytics. Values are
true or false.
- debug
- Indicates whether debug mode is enabled. The debug messages display on the web page where the
tag is located, generally at the bottom of the page. Values are true or
false.
- instrumentation
- Instrumentation code that is related to the integration between a store and the analytics
provider. For example, code that includes JavaScript libraries or other related tasks specific for
the store inside the element, as shown in the following example:
<instrumentation>
<![CDATA[
<script type="text/javascript">
/* Instrumentation code if any */
</script>
]]>
</instrumentation>
You
can define the default CDATA
section within this attribute
- marketingCenterEnabled
- The enablement flag for integrating Management Center with IBM Marketing Center. For more information, see
IBM Marketing Center integration.
- marketingCenterUrl
- If you are integrating Management Center with IBM Marketing Center, you can include this
element to override the default URL to IBM Marketing Center. For more information, see IBM Marketing Center integration.
- includeShipAdjustInProductPrice
-
The enablement flag that controls whether shipping adjustments are applied to the product prices
in an order or to the shipping charge when order data is sent to
IBM Digital Analytics. This setting does not affect the
order details that a shopper views when they are submitting or reviewing an order.
- true
- The default value. Shipping adjustments are applied to the products in an order instead of being
applied to the shipping charge when order data is sent to IBM Digital Analytics. For example, a product costs $40
with a shipping charge of $10. If a promotion that offers a $5 discount on shipping is applied, the
order total is $45. When the
includeShipAdjustInProductPrice
flag is set to true,
the order and shopping cart tags send the order data to IBM Digital Analytics. The information that is sent
indicates that the order total was $45, the product price $35, not $40, and the shipping charge $10,
not $5.
- false
- Shipping adjustments are applied to the shipping charge when data is sent to IBM Digital Analytics. For example, if the
includeShipAdjustInProductPrice
flag is false in the previous scenario, the
information that the order and shopping cart tags send to IBM Digital Analytics indicates that the order total was
$45, the product price $40 and the shipping charge was $5.
- options
- If you are integrating with IBM Digital Data Exchange (DDX), you can include this element and
the
useDDX
attribute with a value of "true"
to enable the
integration. For more information about this integration, see IBM Digital Data Exchange integration.
- output
- The JavaScript snippets, or any other content, that you want to write to a specific location in
your store pages.
- url
- The URL for launching the analytics provider from Management Center.
- useCookies
- Indicates whether category information is stored in cookies. For more information, see Storing category information in cookies for analytics reporting.
- useHostedCMHLibraries
- Indicates whether the store uses the standard IBM Digital Analytics library. Values are
true for the standard IBM Digital Analytics library or
false for the custom IBM Digital Analytics library. Leave this value set to
true.
- useEmailForCustomerId
- Indicates whether to use an email address instead of a WebSphere Commerce member ID to
identify customers in IBM Digital Analytics Valid
values are:
- true
- Use the customer's email address as the IBM Digital Analytics customer ID.
- false
- Use the WebSphere Commerce member ID as the IBM Digital Analytics customer ID. This value is the
default value.
Set this parameter to true
only if your store requires customers to provide
their email address when they register and when they place an order as a guest shopper. Using the
customer's email address as the customer ID is useful if only the email address can be collected
consistently when customers set up a new account, sign up to receive a newsletter, or complete some
other identifying form. For example, by using the email address, you can correlate a customer that
completes a product inquiry form on an external site to the same customer that registers with a
WebSphere Commerce store. Using the email address can also help you to track multiple orders
that are placed by the same guest shopper. When a customer places an order, a guest shopper is
assigned a different unique member ID each time; however, the guest shopper's email address is
likely to stay the same.
The customer ID parameter is passed to IBM Digital Analytics in the
cmCreateRegistrationTag
data tag (which is generated by the
<cm:registration />
tag), and in the cmCreateShopAction9
and
cmCreateOrderTag
data tag (which are both generated by the <cm:order
/>
tag).
- segmentExportMode
- Indicates the export mode to use when you update IBM Digital Analytics based customer segments. See Configuring the export mode for IBM Digital Analytics based customer segments.
- Optional:
Configure your analytics reporting for each store to
use cookies to store category information.
-
Set the IBM Digital Analytics client ID for
each store:
-
Find the following line:
<clientid>69999999</clientid>
-
Replace
69999999
with client ID for your store, as provided by IBM Digital Analytics:
This value controls which client ID the integration uses to launch
IBM Digital Analytics reports from Management Center.
- To launch reports from the IBM Digital Analytics test server, use your test client
ID, which typically starts with the digit 6.
- To launch reports from the IBM Digital Analytics production server, use your
production client ID.
- Optional:
Configure the
<url>
element for each store to override the default URLs to
open your analytics provider from Management Center.
-
Update the
<output>
element contents for each store:
-
Find the following lines:
<output section = "header">
<![CDATA[
<script type="text/javascript" src="//libs.coremetrics.com/eluminate.js"></script>
<script type="text/javascript">
cmSetupNormalization("krypto-_-krypto");
// send data to production system
//cmSetClientID("99999999",true,"data.coremetrics.com","thesite.com");
// send data to test system
cmSetClientID("69999999",false,"testdata.coremetrics.com","thesite.com");
</script>
]]>
</output>
-
Replace
99999999
with your IBM Digital Analytics production client ID.
-
Replace
69999999
with your IBM Digital Analytics test client ID.
Notice that the line that contains your production client ID is commented out, whereas the
line that contains your test client ID is not. This ID means that your analytics data is sent to the
IBM Digital Analytics test server initially. When
you are ready to send data to the production server, you can comment out the line that contains your
test client ID, remove the comments from the line that contains your production ID, and then switch
the client ID you configured in step 6.a to your
production client ID.
Note: If you are using IBM Digital Analytics Multisite, with a Multisite Analytics Client ID such as
'88888888' and a Sub-ID, where
<SiteID>
is the configured Multisite Analytics
Sub-ID, then to send to production, update the
cmSetClientID()
to:
cmSetClientID("88888888|SiteID",true,"data.coremetrics.com","thesite.com");
For
more information, see
cmSetClientID.
-
Replace both occurrences of
thesite.com
with the domain name of your WebSphere Commerce server.
- Optional:
Within
<header>
and <footer>
elements of the
biConfig.xml
file, you can include any common JavaScript functions or statements
that must be placed in the store JSP files along with the tagging functions.
- Optional:
If you want to configure single sign-on between Management Center and IBM Digital Analytics, you can add secret key for single
sign-on to your biConfig.xml file now. Alternatively, you can configure single
sign-on later. For complete steps, see Configuring single sign-on between Management Center and IBM Digital Analytics.
-
Save and close the file.
-
Restart the WebSphere Commerce server.