Mapping device-specific requests to a JSP file template

Smart phone and tablet starter stores uses the incoming HTTP request headers and the wc-devices.xml file by default to route mobile devices to the mobile starter store pages. You can add to the wc-devices.xml file to route additional devices to specific mobile pages. The wc-devices.xml file is reloaded automatically by default when WebSphere Commerce detects changes to the file.

Before you begin

Ensure that you understand the contents and purpose of the wc-devices.xml file:

The smart phone and tablet starter stores use the wc-devices.xml file to identify mobile devices and route them to specific mobile optimized pages. The wc-devices.xml file contains a list of mobile devices that can be identified based on their name and user agent pattern.

WebSphere Commerce provides the following processing logic by default for each device-specific HTTP request:

It searches for a pattern in the User-Agent HTTP header and maps it to a specific device internal ID.
It looks up the JSP file template specific to the device internal ID.

The wc-devices.xml file is reloaded automatically by default when WebSphere Commerce detects changes to the file.

Note:

If you have not deployed the smart phone and tablet starter stores, or if you want to disable the auto-reload functionality, remove the wc-devices.xml entry from the WC_eardir/xml/config/com.ibm.commerce.foundation/.reloadfilelist file. If the .reloadfilelist file is empty, you can simply remove the file from the directory.
A reload interval can be specified in the .reloadfilelist file by adding the following property:
```
reloadinterval=numberOfSeconds
```
For example, if you use a property of reloadinterval=300 in the .reloadfilelist file, the specified files are only reloaded 5 minutes after the last reload time. By default, this property is not specified in the file and when it is not specified, the reload interval is set to 3600, or 60 minutes.
You can force the loading of the mobile storefront from a non-mobile browser by entering the following URL:
- http://host_name/webapp/wcs/stores/servlet/mStoreView?storeId=storeId

WebSphere Commerce provides a default mapping configuration file that maps a specific User-Agent pattern to a device ID. The pattern specified in this file uses the Java regular expression syntax specified in Sun's Pattern class API documentation.

The mapping configuration file is contained at the following location:

WC_eardir/xml/config/com.ibm.commerce.foundation/wc-devices.xml

It contains the following information by default: Feature Pack 1

<_config:Devices
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.ibm.com/xmlns/prod/commerce/foundation/config ../xsd/wc-devices.xsd" xmlns:_config="http://www.ibm.com/xmlns/prod/commerce/foundation/config">
 	<_config:DeviceGroup internalID="-11" channelID="-6" >
		<_config:Device name="BlackBerry Bold 9000" userAgentPattern="BlackBerry9000.*" />
		<_config:Device name="BlackBerry Storm 9530" userAgentPattern="BlackBerry9500.*" />
		<_config:Device name="BlackBerry Curve 8320" userAgentPattern="BlackBerry8320.*"  />
		<_config:Device name="HTC S740" userAgentPattern=".*MSIEMobile.*" />
		<_config:Device name="Nokia S60" userAgentPattern=".*SymbianOS.*Series60/3.1.*Nokia3250.*" />
		<_config:Device name="Nokia N97" userAgentPattern=".*SymbianOS.*Series60/5.0.*Nokia3250.*" />
	</_config:DeviceGroup>
</_config:Devices>


<_config:Devices
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.ibm.com/xmlns/prod/commerce/foundation/config ../xsd/wc-devices.xsd" xmlns:_config="http://www.ibm.com/xmlns/prod/commerce/foundation/config">

	<_config:DeviceGroup internalID="-31" channelID="-6" >
		<_config:Device name="Apple iPad" userAgentPattern=".*iPad.*Safari.*" />
		<_config:Device name="BlackBerry Playbook" userAgentPattern=".*PlayBook.*Safari.*" />
		<_config:Device name="Android Tablets" userAgentPattern=".*Android.((?!Mobile).)*Safari.*" />
	</_config:DeviceGroup>

	<_config:DeviceGroup internalID="-21" channelID="-6" >
		<_config:Device name="Apple iPhone" userAgentPattern=".*iPhone.*Mobile.*Safari.*" />
		<_config:Device name="Android Handsets" userAgentPattern=".*Android.*Mobile.*Safari.*" />
	</_config:DeviceGroup>

	<_config:DeviceGroup internalID="-22" channelID="-6" >
		<_config:Device name="Android Hybrid Smartphone Client" userAgentPattern=".*Android Smartphone Hybrid.*" />
	</_config:DeviceGroup>

	<_config:DeviceGroup internalID="-11" channelID="-6" >
		<_config:Device name="BlackBerry Bold 9000" userAgentPattern="BlackBerry9000.*" />
		<_config:Device name="BlackBerry Storm 9530" userAgentPattern="BlackBerry9500.*" />
		<_config:Device name="BlackBerry Curve 8320" userAgentPattern="BlackBerry8320.*"  />
		<_config:Device name="HTC S740" userAgentPattern=".*MSIEMobile.*" />
		<_config:Device name="Nokia S60" userAgentPattern=".*SymbianOS.*Series60/3.1.*Nokia3250.*" />
		<_config:Device name="Nokia N97" userAgentPattern=".*SymbianOS.*Series60/5.0.*Nokia3250.*" />
	</_config:DeviceGroup>

</_config:Devices>

Where the following enhancements are:

The storefront can differentiate between an iPhone shopper using its native browser, and an iPhone shopper using a mobile application.
The storefront can differentiate between a shopper using a smart phone or tablet device, and if the device is using its native browser or a mobile application.

Where the following parameters are:

config:DeviceGroup

Defines a logical group of mobile devices with the same internal device ID and channel ID.

internalID: The internal device ID for this device group.
channelID: The channel ID for this device group.

config:Device

Defines a mobile device. This mobile device configuration is used for mapping a User-Agent HTTP header to a specific device.

When a device is found, WebSphere Commerce runtime will set the corresponding device ID and channel ID in the session.

name: The name of the device.
userAgentPattern: Regular expression used to pattern match the User-Agent HTTP header.

The existing WebSphere Commerce Struts framework is used to load the JSP file template specific to the device internal ID.

For example:

When a request is initiated from a Blackberry Storm 9530 device, its User-Agent HTTP header is specified and resembles the following snippet:


BlackBerry9530/4.7.0.41 Profile/MIDP-2.0 Configuration/CLDC-1.1 VendorID/-1

WebSphere Commerce searches the wc-devices.xml configuration file for a matching User-Agent and finds the following snippet:


<_config:Device name="BlackBerry Storm 9530" userAgentPattern="BlackBerry9530.*" />

WebSphere Commerce sets the defined deviceID (-11) and channelID (-6) in the session. This device ID is then used by the Struts presentation layer to render the specific JSP file template response to the user.

For example, to create a device mapping for Google Android, use the following snippet:


<_config:DeviceGroup internalID="-11" channelID="-6">
    <_config:Device name="Google Android" userAgentPattern=".*Android.*" />
</_config:DeviceGroup>

The User-Agent header mappings are cached to maximize performance, where multiple requests with the same User-Agent header do use the same lookup multiple times.

Procedure

Create an extensions directory and new wc-devices.xml extension file:
1. Navigate to the WC_eardir/xml/config directory.
2. Create a new directory called com.ibm.commerce.foundation-ext, if it does not already exist.
  Note: When creating an extensions folder, the folder name ends with -ext. This ensures the default file you are extending remains unchanged.
  By extending the configuration, you can override the properties of the existing wc-devices.xml file.
3. Navigate to the WC_eardir/xml/config/com.ibm.commerce.foundation directory and copy the wc-devices.xml file into the extensions directory you created in the preceding step.
Add your devices to the wc-devices.xml extension file:
1. Open the new wc-devices.xml, located in your extensions directory.
2. Locate the default device mappings.
3. Replace the default device mappings with your own mappings
  For example, to create a device mapping for Google Android, use the following snippet:
```
<_config:DeviceGroup internalID="-11" channelID="-6">
     <_config:Device name="Google Android" userAgentPattern=".*Android.*" /> 
</_config:DeviceGroup>
```
4. Save your changes and close the file.
Your extension file changes are automatically deployed to WebSphere Commerce, without needing to restart your server. The wc-devices.xml file is reloaded automatically by default when WebSphere Commerce detects changes to the file.