Integrating IBM Mobile Web Push with WebSphere Commerce

Add Mobile Web Push to your mobile website's marketing platform

IBM® Mobile Web Push extends WebSphere® Commerce with the ability to send customized and targeted marketing offers to your mobile web pages. In this article, you will quickly integrate Mobile Web Push with WebSphere Commerce, then build an inbox of offers that can be triggered by specified user actions on your mobile web pages.

Share:

Bob Balfe (balfe@us.ibm.com), Senior Technical Staff Member, Smarter Commerce, IBM

Bob BalfeBob Balfe is a Senior Technical Staff Member on the North American Smarter Commerce Team at IBM. He specializes in using IBM products such as WebSphere Commerce, Order Management, Enterprise Marketing Management, Enterprise Content Management, and Contract Management to assist customers in realizing their Smarter Commerce vision. Bob gives public presentations and writes about software, smarter commerce, and WebSphere in his professional blog. Follow him at @bobbalfe.



12 May 2014

IBM Mobile Web Push is a messaging platform that pushes marketing offers to mobile devices and websites. With Mobile Web Push, you can dynamically trigger content for display on mobile devices and websites that is based on a visitor's actions. Mobile Web Push runs on an event-driven API called Reactor. When a mobile user interacts with your mobile website, page or click events are sent to a backend Reactor server. The user then receives offers based on the rules that are defined on the server.

In this article, you'll integrate IBM Mobile Web Push with WebSphere Commerce. The integration enables you to take mobile marketing campaigns beyond the restrictions of WebSphere Commerce's traditional page layouts. Using Mobile Web Push widgets or eSpots, which are dynamic areas on the screen, you are able to quickly and easily configure an inbox of offers that you can customize for different displays. Mobile Web Push marketing offers can be designed as pop-up windows, fly-ins, and even basic header-bar messages on your commerce pages. A pop-up offer is shown in Figure 1:

Figure 1. A Mobile Web Push pop-up offer
Screen capture of a Mobile Web Push pop-up offer.

To follow the demonstrations in this article, you should be familiar with using the following tools for mobile development:

The article assumes that you are familiar with WebSphere Commerce and the OpenLaszlo API. Demonstrations are based on AuroraESite, a mobile website that you enable for Mobile Web Push.

WebSphere Commerce with Mobile Web Push

The first thing you'll do is integrate IBM Mobile Web Push into WebSphere Commerce. Start by opening the WebSphere Commerce Management Center's Configurations tab. Then, turn on IBM Mobile Web Push in WebSphere Commerce, add a field for the IBM Mobile Web Push API key, and add an optional check box to enable and disable the inbox experience. The customized Configurations panel looks like the screen capture in Figure 2. The new Mobile Web Push configuration options (outlined in red) are:

  • Enable IBM Mobile Web Push Feature check box
  • IBM Mobile Web Push API Key field (displays the API key)
  • Show the IBM Mobile Web Push Mail Box check box
Figure 2. New store options in the WebSphere Commerce Management Center
A screen capture of the WebSphere Commerce Management Center with new storefront options

On the backend, you need to register the new Mobile Web Push options in your database. Then, use the new options to configure your OpenLaszlo display code. Create a file for each extended site that accesses Mobile Web Push features.

First, get the STOREENT_ID value for AuroraESite. You can find this value for any store on the Store Properties tab in the WebSphere Commerce Management Center's Configurations panel, as shown in Figure 3.

Figure 3. Finding STOREENT_ID in Store Properties
A screen capture of the WebSphere Commerce Management Center Store Properties tab

Save the following XML to a file named wc.ibmMobileWebPush.xml in your <WC7Toolkit>/schema/xml directory. This code needs to be in the same directory as the wcs.dtd file. The STOREENT_ID value appears in each emspot and dmemspotdef.

Listing 1. Mobile Web Push configuration
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE import SYSTEM "wcs.dtd">
<import>
<emspot
       EMSPOT_ID="@counter_0000000114"
       STOREENT_ID="10152"
       NAME="IBMMobileWebPush"
       DESCRIPTION="IBMMobileWebPushFeature"
       USAGETYPE="STOREFEATURE">
</emspot>
<dmemspotdef
       DMEMSPOTDEF_ID="@counter_0000000115"
       EMSPOT_ID="@counter_0000000114"
       STOREENT_ID="10152"
       CONTENTTYPE="FeatureEnabled"
       CONTENT="false">
</dmemspotdef>
<emspot
       EMSPOT_ID="@counter_0000000115"
       STOREENT_ID="10152"
       NAME="IBMMobileWebPushAPIKey"
       DESCRIPTION="IBMMobileWebPushFeature"
       USAGETYPE="STOREFEATURE">
</emspot>
<dmemspotdef
       DMEMSPOTDEF_ID="@counter_0000000116"
       EMSPOT_ID="@counter_0000000115"
       STOREENT_ID="10152"
       CONTENTTYPE="FeatureEnabled"
       CONTENT="false">
</dmemspotdef>
<emspot
       EMSPOT_ID="@counter_0000000116"
       STOREENT_ID="10152"
       NAME="IBMMobileWebPushMailBox"
       DESCRIPTION="IBMMobileWebPushFeature"
       USAGETYPE="STOREFEATURE">
</emspot>
<dmemspotdef
       DMEMSPOTDEF_ID="@counter_0000000117"
       EMSPOT_ID="@counter_0000000116"
       STOREENT_ID="10152"
       CONTENTTYPE="FeatureEnabled"
       CONTENT="false">
</dmemspotdef>
</import>

After you create the file, issue two commands: idresgen followed by massload.


Generate and load unique IDs

The idresgen command iterates through the original file and looks for @counters. It then generates unique IDs for those elements to prevent a collision with existing IDs in the system. You must run idresgen commands from the <WCTOOLKIT>/bin directory. The first command generates a new file named wcs.ibmMobileWebPush_resolved.xml. The database name, credentials, and schema are for the base demo asset only; if your database information is different then adjust accordingly:

Click to see code listing

idresgen ..\schema\xml\wcs.ibmMobileWebPush.xml ..\schema\xml\wcs.ibmMobileWebPush_resolved.xml inst1db db2admin passw0rd DB2ADMIN

When this command completes, you should find that a new file (wcs.ibmMobileWebPush_resolved.xml) was generated in the same directory. If the file wasn't created, check the logs in the <WCTOOLKIT>/logs directory. If you don't see any information about the idresgen tool, then you might need to enable logging for the tool. Enable the log for massload as well, by adding the following lines to the WCALoggerConfig.xml in the <WCTOOLKIT>/xml/loader directory:

         <component name="COMPONENT_IDRESGEN"/> 
         <component name="COMPONENT_MASSLOAD"/>

Next, run the massload command on the newly generated XML file from the same bin directory:

massload  ..\schema\xml\wcs.ibmMobileWebPush_resolved.xml  inst1db db2admin passw0rd DB2ADMIN

To verify that this procedure worked, issue the SQL command: select * from emspot;. Look for the string "IBMMobileWebPush" in the results. You should see a record similar to this one:

12501 	10152 	'IBMMobileWebPush' 	'IBMMobileWebPushFeature'

Creating a Management Center UI

In this section, you create a user interface that your marketing team can use to manage campaigns from the mobile website's Management Center.

Start by creating a new properties file under a new package in Rational Application Developer's LOBTools src folder. First, create a new package named com.ibm.mobilewebpush.client.lobtools.properties, then create a new file named StoreLOB_en_US.properties and place the following contents inside:

Listing 2. Contents of StoreLOB_en_US.properties
IBMMobileWebPushPanel.description=IBM Mobile Web Push configuration (click here to get your key):
IBMMobileWebPushPanel=IBM Mobile Web Push.
IBMMobileWebPushPanel.title=IBM Mobile Web Push.
IBMMobileWebPushPanel.checkboxEnable.title=Allow customers to enable IBM Mobile Web Push feature.
IBMMobileWebPushPanel.checkboxEnable.label=Enable IBM Mobile Web Push Feature.
IBMMobileWebPushPanel.apikey.label=IBM Mobile Web Push API Key
IBMMobileWebPushPanel.apikey.help=Enter the IBM Mobile Web Push API Key
IBMMobileWebPushPanel.mailbox.label=Show the IBM Mobile Web Push Mail Box
IBMMobileWebPushPanel.mailbox.help=Show the IBM Mobile Web Push Mail Box

Next, open the StoreFlexFlowPropertiesView.def file in the following directory:

Click to see code listing

<WC7Toolkit>\workspace\LOBTools\WebContent\config\commerce\store\propertiesViews\AuroraStorefrontAssetStore\

Declare the new properties file at the top of this file where you see a ResourceBundle element. Copy that to a new element right below it and name your definition with the same name, but with "Ext" added to it, as shown:

Click to see code listing

<ResourceBundle definitionName="stoFlexFlow_10651" baseName="tools.stores.AuroraStorefrontAssetStore.devtools.flow.ui.config" />
<ResourceBundle definitionName="stoFlexFlowExt_10651" baseName="com.ibm.mobilewebpush.client.lobtools.properties.StoreLOB" />

Now, in the same file, find the following line of code:

<PropertyPane definitionName="stoConfigurationsFlexFlow_10651" >

Append the code in Listing 3 to the end of that PropertyGroup:

Listing 3. StoreFlow objects

Click to see code listing

Listing 3. StoreFlow objects

    <PropertyStaticText text="${stoFlexFlowExt_10651.IBMMobileWebPushPanel.description}" />

    <PropertyCheckbox name="MobileWebPush.checkbox" helpText="${stoFlexFlowExt_10651.IBMMobileWebPushPanel.title}" promptText="${stoFlexFlowExt_10651.IBMMobileWebPushPanel.checkboxEnable.label}" objectPath="StoreFlow[name=IBMMobileWebPush]" propertyName="enabled"/>

    <PropertyInputText name="MobileWebPush.apikey" promptText="${stoFlexFlowExt_10651.IBMMobileWebPushPanel.apikey.label}" objectPath="StoreFlow[name=IBMMobileWebPushAPIKey]" propertyName="enabled">
        <EnablementCondition parentProperty="true" objectPath="StoreFlow[name=IBMMobileWebPush]" propertyName="enabled" enablementValue="true" />
    </PropertyInputText>

    <PropertyCheckbox name="MobileWebPushMailBox.checkbox" helpText="${stoFlexFlowExt_10651.IBMMobileWebPushPanel.title}" promptText="${stoFlexFlowExt_10651.IBMMobileWebPushPanel.mailbox.label}" objectPath="StoreFlow[name=IBMMobileWebPushMailBox]" propertyName="enabled">
            <EnablementCondition parentProperty="true" objectPath="StoreFlow[name=IBMMobileWebPush]" propertyName="enabled" enablementValue="true" />
    </PropertyCheckbox>

The EnablementCondition in Listing 3 disables the IBM Mobile Web Push API Key and Show the IBM Mobile Web Push Mail Box fields if the primary feature isn't checked. With this, we can use the parent's StoreFlow object and property name IBMMobileWebPush to see whether a feature is enabled.

The key point in this code is that the StoreFlow object names need to be the same names that are used in the massload-generated XML file. In this case, the object names are IBMMobileWebPush, IBMMobileWebPushAPIKey, and IBMMobileWebPushMailBox. That's how you tie the user interface to the database objects.


Creating the storefront

The last thing you'll do is to instrument the storefront with your new code. This is the easiest part of the demo and you'll use a footer extension to accomplish it.

To start, download the Reactor API JavaScript file and the simple inbox JavaScript file and store them in the following directory:

<WCTOOLKIT>\workspace\stores\WebContent\AuroraStorefrontAssetStore\javascript

Now navigate to the ext directory of the footer:

<WCTOOLKIT>\workspace\Stores\WebContent\AuroraStorefrontAssetStore\Widgets\Footer\ext)

First, modify the existing Footer_Data.jspf and Footer_UI.jspf files. Unless you have other extensions in the footer, these files should be blank. Add the following code to Footer_Data.jspf:

<flow:ifEnabled feature="IBMWebMobilePush">
	<%@ include file="mobile_web_push_Data.jspf" %>
</flow:ifEnabled>

And add this code to Footer_UI.jspf:

<flow:ifEnabled feature="IBMWebMobilePush">
	<%@ include file="mobile_web_push_UI.jspf" %>
</flow:ifEnabled>

The IfEnabled statements ensure that the custom files are only included if the IBMMobileWebPush feature is enabled in the store configuration.

Storefront files

Next, create two new files in the following directory:

<WCTOOLKIT>\workspace\Stores\WebContent\AuroraStorefrontAssetStore\Widgets\Footer\ext\

By putting the primary code into the ext directory, you will not completely disturb the base code, which will prevent problems during upgrade. Here are the files:

Listing 4. mobile_web_push_Data.jspf

Click to see code listing

Listing 4. mobile_web_push_Data.jspf

<wcf:getData type="com.ibm.commerce.marketing.facade.datatypes.MarketingSpotDataType" var="espot" expressionBuilder="findByMarketingSpotName">
	<wcf:contextData name="storeId" data="${param.storeId}" />
	<wcf:param name="DM_Emspot_Usage" value="STOREFEATURE"/>
	<wcf:param name="DM_EmsName" value="IBMMobileWebPushAPIKey" />
</wcf:getData>

<c:forEach var="content" items="${espot.baseMarketingSpotActivityData}">
	<c:if test="${content.dataType == 'FeatureEnabled'}">
		<c:set var="api_key" value="${content.name}"/>
	</c:if>
</c:forEach>
Listing 5. mobile_web_push_UI.jspf

Click to see code listing

Listing 5. mobile_web_push_UI.jspf

<!-- IBM Web Mobile Push Start -->
<script src="/wcsstore/AuroraStorefrontAssetStore/javascript/reactor-bundle.min.js" id="reactor-sdk" auto-run="true" data-app-key="<c:out value="${api_key}"/>" ></script>

<flow:ifEnabled feature="IBMWebMobilePush">
	<flow:ifEnabled feature="IBMWebMobilePushMailBox">
<!-- Simple Inbox Module -->
<script src="/wcsstore/AuroraStorefrontAssetStore/javascript/simple-inbox.min.js"></script>
	</flow:ifEnabled>
</flow:ifEnabled>
<script src="http://code.jquery.com/jquery-1.11.0.min.js"></script>
  
<script>
function createPopupDIV(){
	var left = (window.innerWidth+100);
	var top = 200;
	var element = document.createElement("div");
	element.setAttribute("id", "web-push-popup");
	element.setAttribute("style", "opacity:0.95;z-index:1000;background-color:white;border-style:solid;border-width:2px;display:none;position:absolute;left:" + left + "px;top:" + top +"px;height:400px;width:400px;");
	
	var content = document.createElement("div");
	content.setAttribute("id", "web-push-popup-content");

	var close = document.createElement("p");
	close.setAttribute("id", "close-web-push-popup-content");
	close.setAttribute("style", "cursor:pointer;position:relative;left:150px;");
	
	var ct = document.createTextNode("click to close");
	close.appendChild(ct);
	
	element.appendChild(content);
	element.appendChild(close);
	
	document.body.appendChild(element);
}
dojo.addOnLoad = function () {
						
		createPopupDIV();
		
		Reactor.reset();
		
		Reactor.onMessage(function(message){
			var b = "<p style='text-align:center;font-weight:bold;'><em>" + message.subject + "</em></p><hr>" + message.body;
			
			if (message.customData && message.customData.position){
				if (message.customData.position == "popup"){
					$('#web-push-popup-content').html(b);
					
					var left = (window.innerWidth/2-200);
					$('#web-push-popup').show().animate({"left":left + "px"}, 500);
					
					$('#close-web-push-popup-content').click( function(){
						$('#web-push-popup').animate({"left":"-600px"}, 500, function(){
							$('#web-push-popup').hide();
						});
					});
				}else if (message.customData.position == "message"){	
					MessageHelper.displayStatusMessage(b, 30);
				}
			}					
		});
		
		
		Reactor.Client.setAttribute("productId", '<c:out value="${WCParam.productId}"/>');
		Reactor.Client.setAttribute("categoryId", '<c:out value="${WCParam.categoryId}"/>');
		Reactor.Client.setAttribute("parentCategoryId", '<c:out value="${WCParam.parent_category_rn}"/>');
		Reactor.Client.setAttribute("catalogId", '<c:out value="${WCParam.catalogId}"/>');
		Reactor.Client.setAttribute("storeId", '<c:out value="${WCParam.storeId}"/>');
		Reactor.Client.setAttribute("locale", '<c:out value="${WCParam.locale}"/>');
		Reactor.Client.setAttribute("userId", '<c:out value="${WCParam.logonId}"/>');
		Reactor.Client.setAttribute("searchTerm", '<c:out value="${WCParam.searchTerm}"/>');
		Reactor.Client.setAttribute("commandName", '<c:out value="${WCParam.commandName}"/>');
		
				
		var newPage = new Reactor.Event("PAGE_VIEW", function(message){
			
		});
		Reactor.EventManager.fireEvent(newPage);			
}
</script>	
<!--  IBM Web Mobile Push End  -->

You might want to extract the JavaScript from the JSP but for brevity I included it in the file.

In the next sections, I'll explain the details of the Web Mobile Push code and show you how to control campaigns in the Reactor administration panel. If you prefer to get started with the new features right away, restart your WebSphere Commerce server now and you are good to go.


Inside Mobile Web Push

The job of the mobile_web_push_Data.jspf file is to extract the API key from the field. In the case of multiple values, the values are stored in an array, so you simply iterate through the array and store the value in the variable api_key to be used in the UI file. The UI file just happens to be the first line of code in the mobile_web_push_UI.jspf. In the following script definition, the extraction of this field is placed in the data-app-key parameter.

Listing 6. Script definition

Click to see code listing

Listing 6. Script definition

<script src="/wcsstore/AuroraStorefrontAssetStore/javascript/reactor-bundle.min.js" id="reactor-sdk" auto-run="true" data-app-key="&kt;c:out value="${api_key}"/>" ></script>

Next, you want to optionally output the simple inbox code that is based on the selection in the configuration panel:

Listing 7. Simple inbox module
<flow:ifEnabled feature="IBMWebMobilePush">
	<flow:ifEnabled feature="IBMWebMobilePushMailBox">
<!-- Simple Inbox Module -->
<script src="/wcsstore/AuroraStorefrontAssetStore/javascript/simple-inbox.min.js"></script>
	</flow:ifEnabled>
</flow:ifEnabled>

First, test that the entire feature is enabled, then test that the inbox is enabled. The simple-inbox.min.js in Listing 7 puts a small envelope at the bottom of the UI screen, where previous offers can be viewed:

Figure 4. Inbox is enabled
A screen capture of the inbox.

The code in Listing 7 uses jQuery to animate and show pop-up offers. It's here that you can instrument different kinds of user experiences. I coded two message types: Pop-up and Message. The pop-up type has the offer fly in from the right. If the shopper clicks the offer, she sees a landing page or a category page. The other option is a standard WebSphere Commerce message that shows at the top of the screen, as shown in Figure 5.

Figure 5. Test message
A screen capture of a test message.

Using the Reactor API is fairly straightforward. Since this code is in the site's footer, it is enabled for all pages on the site. You can send as much data as you can up to the Reactor server for evaluation in your rules. The block of code that runs on every page view is shown in Listing 8.

Listing 8. PAGE_VIEW event
Reactor.Client.setAttribute("productId", '<c:out value="${WCParam.productId}"/>');
Reactor.Client.setAttribute("categoryId", '<c:out value="${WCParam.categoryId}"/>');
Reactor.Client.setAttribute("parentCategoryId", '<c:out value="${WCParam.parent_category_rn}"/>');
Reactor.Client.setAttribute("catalogId", '<c:out value="${WCParam.catalogId}"/>');
Reactor.Client.setAttribute("storeId", '<c:out value="${WCParam.storeId}"/>');
Reactor.Client.setAttribute("locale", '<c:out value="${WCParam.locale}"/>');
Reactor.Client.setAttribute("userId", '<c:out value="${WCParam.logonId}"/>');
Reactor.Client.setAttribute("searchTerm", '<c:out value="${WCParam.searchTerm}"/>');
Reactor.Client.setAttribute("commandName", '<c:out value="${WCParam.commandName}"/>');
		
				
var newPage = new Reactor.Event("PAGE_VIEW", function(message){
			
});
Reactor.EventManager.fireEvent(newPage);

The rules on the server can key off of things like what category or product that the shopper views, or even the user ID or locale of the customer. I used the ready-to-use PAGE_VIEW event in Listing 8, but you can customize this code if needed.

Next, you want to capture the messages that come in from the server so you register your callback with the onMessage function:

        Reactor.onMessage(function(message){

Your function is called if an offer matches the rules on the server.

I hardcoded the user interface in the JavaScript files. Optionally, you can add features on the Management Center Configurations profile to give your marketing team better control of the pop-up UI.


The Reactor admin panel

To send offers to your storefront, you need a free 30-day trial of IBM Mobile Web Push. With the trial, you get a key that you can use to create a campaign. I'll quickly review the steps to create and manage a campaign by using the Reactor administration panel.

Start by launching the campaign tool, then create a new campaign. Use the values (Name, Description, Start Date, and End Date) in Figure 6 to set up your campaign:

Figure 6. Start a new campaign
A screen capture of the Reactor admin panel: Describe Your Campaign.

Next, create the content that is to be sent in the message, notice the JSON parameter that I am sending down to the client: "position":"popup." This value tells the JavaScript to execute the fly-in animation:

Figure 7. Build a message
A screen capture of the Reactor admin panel: Build a message.

In Figure 8, I set a parameter to delay the experience by one second so that it doesn't pop up immediately when the page loads. I also place a restriction on how many times the pop-up offer can happen in a day:

Figure 8. Set message frequency
A screen capture of the Reactor admin panel: Set Content Experience.

I want this offer to be pushed to all users of my mobile website. You also can opt to send an offer to a particular segment of visitors, or to specific devices:

Figure 9. Define the target
A screen capture of the Reactor admin panel: Choose Your Target.

I used the default PAGE_VIEW, so the next section remains unchanged:

Figure 10. Select a triggering event
A screen capture of the Reactor admin panel: Select a Triggering Event.

In the rule builder, I key off the categoryId to be blank. Users might see the offer on any page that was not tied to a product category. You might want to send some additional data to identify the front page or specific static pages and key off of that parameter:

Figure 11. Specify rules
A screen capture of the Reactor admin panel: Get More Specific.

And with that you have a rudimentary campaign — enable it and watch the magic!


Next steps

In this article, I showed you how to integrate the magic of IBM Mobile Web Push into your WebSphere Commerce mobile marketing platform. Working from the demonstration, you can do a couple of things to make your Management Center more user-friendly and upgrade the campaign features:

  • Adding a field to set the style of the inbox would give your marketing team more control of the shopper's experience.
  • Supporting left and right fly-ins can improve the pop-up offer by making it less intrusive. Rather than having it pop-up in the middle of the screen, you might have it fly in from the right or left, then be aligned to the left or right edge of the screen. The pop-up offer might also disappear after a number of seconds.

Resources

Learn

Get products and technologies

Discuss

  • Visit the PushDev forum: Where you can ask questions and get technical help by using IBM’s new push technologies.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Mobile development on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Mobile development, WebSphere
ArticleID=971055
ArticleTitle=Integrating IBM Mobile Web Push with WebSphere Commerce
publish-date=05122014