Updating storefront assets for Apple Pay on the Web using the Accelerator assets

Update your storefront assets to include the Apple Pay on the Web functionality and payment buttons where required.

Before you begin

Understand the Apple Pay on the Web sequential flows to get familiar with how the Aurora starter store interacts with Apple Pay on the Web: Apple Pay on the Web sequential flows.

Procedure

  1. Adding Apple Pay helpers:

    The Apple Pay sample helper assets contain new JSP and JavaScript files that enable the Aurora starter store to call out to Apple Pay on the Web functionality from the storefront. The samples are designed and written so that they can provide new self-contained code assets that can be inserted into any store. The new code in these samples has no dependency on Dojo.

    The following list describes some of the files that are involved with the integration:
    storedir/ApplePay/GetOrderInfoForApplePay.jsp
    This JSP file maps to a Struts view that calls several server-side REST services to construct the payment request JSON object that is required to start an Apple Pay payment sheet session. It contains information such as the order total, detailed line-item descriptions for discounts, shipping and taxes, shipping and billing address, and applicable shipping methods.
    storedir/ApplePay/GetCSRFAuthToken.jsp
    This JSP file retrieves the current shopper session's WebSphere Commerce authorization token. This is retrieved by using AJAX, as AJAX is required to run protected services from cached browsing pages. That is, the authorization token cannot be used in the HTML DOM on cached browsing pages.
    storedir/javascript/ApplePay.js
    This JavaScript file facilitates all the client and server-side interaction between WebSphere Commerce and Apple Pay. It contains all the business logic to display the Apple Pay button (if allowed), it facilitates starting the Apple Pay payment sheet session, and it implements all the required JavaScript call-back methods as instructed in the Apple Pay for the Web documentation.
    1. Download the sample helper assets to be used to enable Apple Pay on the Web: smapplepaysampleassets_helpers.zip
    2. Extract the sample helper assets storefront into your store directory, WC_eardir/Stores.war/storedir.
    3. Edit the extracted AuroraStorefrontAssetStore\javascript\ApplePay.js file. Search for the following line: var merchantIdentifier = 'merchant.com.ibm.commerce.aurora'; and replace it with your merchant identifier from the Apple Portal when you register your site for Apple Pay.
    4. Create new Struts entries for the new JSP files that are packaged with the sample.
      For example, create a file that is called struts-config-applepay.xml with the following initial content:
      
      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE struts-config PUBLIC "-//Apache Software Foundation//DTD Struts Configuration 1.2//EN" "http://struts.apache.org/dtds/struts-config_1_2.dtd">
      <struts-config>
      	<global-forwards>
      		<forward className="com.ibm.commerce.struts.ECActionForward" name="GetOrderInfoForApplePay/10101" path="/ApplePay/GetOrderInfoForApplePay.jsp"/>
      		<forward className="com.ibm.commerce.struts.ECActionForward" name="GetCSRFAuthToken/10101" path="/ApplePay/GetCSRFAuthToken.jsp"/>
      	</global-forwards>
      	<action-mappings type="com.ibm.commerce.struts.ECActionMapping">
      		<action path="/GetOrderInfoForApplePay" type="com.ibm.commerce.struts.BaseAction">
      			<set-property property="https" value="10101:1"/>
      		</action>
      		<action path="/GetCSRFAuthToken" type="com.ibm.commerce.struts.BaseAction">
      			<set-property property="https" value="10101:1"/>
      		</action>
      	</action-mappings>
      </struts-config>
      
      Then, replace 10101 with your store ID that applies to your storefront asset stores and direct stores that require Apple Pay on the Web support.
    5. Download the sample policy XML files: smapplepaypolicies.zip.
    6. Extract the sample policy XML files to the following directory: WC_installdir/xml/policies/xml.
    7. Update the AccessControlPolicies_ApplePay_Store.xml file and replace AuroraStorefrontAssetStore with your asset store identifier.
    8. Run acpload and acpnlsload on the sample policy XML files.
      For more information about running the utilities, see the following topics:
    9. Restart the WebSphere Commerce Server.
  2. Adding Apple Pay on the Web to your storefront.

    You can add the Apple Pay button anywhere that you require in the store, even pages outside the scope of this sample. This is done by calling the added functions from the Apple Pay helpers from your storefront. In the provided sample and following steps, the Apple Pay button is added the product details page, the shopping cart page, and the mini shopping cart.

    As a guidance, you can download the following sample code and compare the changes that you make with the updated storefront code samples: smapplepaysampleassets_store.zip. The sample assets are based off files in the Aurora starter store in WebSphere Commerce Version 7 Feature Pack 8 with all of the latest cumulative fixes.

    1. Securing store pages.

      Apple mandates that any page that contains the Apple Pay button must be served as a secure page (HTTPS). The following options are available to make a page secure:

      Option A: Make the page secure for all browsers. This option might not be ideal since the penalty to serve a page in HTTPS increases the service demands on the web server. Another consideration is the potential cost increase of caching HTTP pages versus caching HTTPS pages.
      1. Open the struts-config-ext.xml file for editing.
      2. Update the ProductDisplay entry to contain the HTTPS setting to 1.
      3. Update the HTTPS setting to 1 for any other entries for store pages that require Apple Pay on the Web. For example, CategoryDisplay and SearchDisplay. The shopping cart page might already be enabled for HTTPS.
      4. If any entries do not exist for a page that requires Apple Pay on the Web, create them.
      Option B: Make the page secure for only the Safari browser. This option sets up a web server redirect rule to redirect all requests to HTTPS mode if they come from a Safari browser or user agent. A sample rule to use is:
      
      RewriteCond %{HTTP_USER_AGENT} Safari
      RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}  [L]
      
    2. Adding Apple Pay on the Web integration helper code to all store pages.
      1. Find a JSP file in the store that is included in every page. For example, in the Aurora starter store, storedir/Common/CommonJSToInclude.jspf is included in every page by default.
      2. Open the JSP file for editing.
      3. Add the following code to the end of the file:
        
        <%-- APPLEPAY BEGIN --%>
        <link rel="apple-touch-icon" size="120x120" href="images/touch-icon-120x120.png">
        <link rel="apple-touch-icon" size="152x152" href="images/touch-icon-152x152.png">
        <link rel="apple-touch-icon" size="180x180" href="images/touch-icon-180x180.png">
        <script type="text/javascript" src="<c:out value="${jsAssetsDir}javascript/ApplePay.js"/>"></script>
        <%-- APPLEPAY END --%>
        
      4. Save your changes to the file.
    3. Adding the official Apple Pay button styling to the store CSS.
      1. Edit your store CSS file to include a new button style that uses the official Apple recommended CSS. For example, in the Aurora starter store, storedir/css/styles.css is the default CSS file.
      2. Open the CSS file for editing.
      3. Add the following code to the end of the file:
        
        /* -----------------------------------------------------------------------------*/
        /* APPLEPAY BEGIN
        /* -----------------------------------------------------------------------------*/	
        	#applePayShopcartButton {
        		padding-right: 5px;
        	}
        	
        	.apple-pay-button {
        		display: none;		
        		background-color: white;
        		background-image: -webkit-named-image(apple-pay-logo-black);
        		background-position: 50% 50%;
        		background-repeat: no-repeat;
        		background-size: 100% calc(60% + 2px);
        		border: 1px solid black;
        		box-sizing: border-box;
        		height: 30px;
        		margin: 5px auto;
        		min-height: 30px;
        		min-width: 50px;
        		padding: 0px;
        		transition: background-color .15s;
        		width: 100%;
        		border-radius: 5px;
        		/*max-width: 200px;*/
        		cursor: pointer;
        	}
        	
        	.apple-pay-button.visible {
        		display: block;
        	}
        	.apple-pay-button-clear-float {
        		clear: both;
        	}
        	
        	.apple-pay-button:active {
        		background-color: rgb(152, 152, 152);
        	}
        	.apple-pay-checkout {
        		max-width: 120px;
        	}
        	.apple-pay-pdp {
        		max-width: 270px;
        	}
        /* -----------------------------------------------------------------------------*/
        /* APPLEPAY END
        /* -----------------------------------------------------------------------------*/
        
      4. Save your changes to the file.
    4. Adding the Apple Pay button to the shopping cart page.
      1. Add the Apple Pay button to the shopping cart page in your preferred location. For example, in the Aurora starter store, an ideal location is in the storedir/ShoppingArea/CheckoutSection/SingleShipment/SingleShipmentOrderTotalsSummary.jsp file.
      2. Open the JSP file for editing.
      3. Add the following code near the end of the file after the final <div>:
        <%-- APPLEPAY BEGIN --%>
        <c:if test="${param.fromPage == 'shoppingCartDisplay'}">
        <div class="apple-pay-button left apple-pay-checkout" id="applePayButtonDiv" onclick="javascript: applePayButtonClicked();"></div>
        <div class="apple-pay-button-clear-float"></div>
        </c:if>
        <%-- APPLEPAY END --%>
        
      4. Save your changes to the file.
    5. Adding the Apple Pay button to the mobile shopping cart page.
      1. Open the storedir/mobile30/ShoppingArea/ShopcartSection/OrderItemDisplay.jsp file for editing.
      2. Locate the following line of code: <%@ include file="../../include/CommonAssetsForHeader.jspf" %>
      3. Add the following code before it:
        
        <%-- APPLEPAY BEGIN --%>
        <link rel="apple-touch-icon" size="120x120" href="images/touch-icon-120x120.png">
        <link rel="apple-touch-icon" size="152x152" href="images/touch-icon-152x152.png">
        <link rel="apple-touch-icon" size="180x180" href="images/touch-icon-180x180.png">
        
        <script type="text/javascript" src="<c:out value="${jsAssetsDir}javascript/ApplePay.js"/>"></script>
        <%-- APPLEPAY END --%>
        
      4. Add the following code before the check out button:
        
        <%-- APPLEPAY BEGIN --%>
        <div class="apple-pay-button left" id="applePayButtonDiv" onclick="javascript: applePayButtonClicked();"></div>
        <%-- APPLEPAY END --%>
        
      5. Save your changes to the file.
    6. Adding the Apple Pay button to the product details page.
      1. Add the Apple Pay button to the product details page near the section that contains the Add to Cart button. For example, in the Aurora starter store, Widgets_701/com.ibm.commerce.store.widgets.PDP_ShopperActions/ShopperActions_UI.jspf is the default file.
      2. Open the JSPF file for editing.
      3. Add the following code:
        For a product:
        <%-- APPLEPAY BEGIN --%>
        <div class="clear_float"></div>
        <div class="item_spacer_10px"></div>
        <div class="apple-pay-button left apple-pay-pdp" id="applePayButtonDiv" onclick="javascript: applePayButtonClicked('entitledItem_<c:out value='${catalogEntryID}'/>', 					document.getElementById('quantity_<c:out value='${catalogEntryID}'/>').value);"></div>
        <div class="apple-pay-button-clear-float"></div>
        <%-- APPLEPAY END --%>
        
        For a package:
        <%-- APPLEPAY BEGIN --%>
        <div class="clear_float"></div>
        <div class="item_spacer_10px"></div>
        <div class="apple-pay-button button left apple-pay-pdp" id="applePayButtonDiv" onclick="javascript: applePayButtonClicked(null, document.getElementById('packageQty').value, 				'${catalogEntryID}');"></div>
        <div class="apple-pay-button-clear-float"></div>
        <%-- APPLEPAY END --%>
        
      4. Save your changes to the file.
    7. Adding the Apple Pay button to the mini shopping cart widget.
      1. Add the Apple Pay button to the mini shopping cart widget before the Go to Cart button. For example, in the Aurora starter store, storedir/Widgets/MiniShopCartDisplay/MiniShopCartContents_UI.jspf is the default file.
      2. Open the JSPF file for editing.
      3. Add the following code:
        <%-- APPLEPAY BEGIN --%>
        <div class="apple-pay-button left" id="applePayButtonDiv_minishopcart" onclick="javascript: applePayButtonClicked();"></div>
        <%-- APPLEPAY END --%>
        
      4. Save your changes to the file.
    8. Displaying the Apple Pay button in the mini shopping cart refresh area. This step is required as the Apple Pay button must be loaded on widget refresh, instead of on page load.
      1. Open the MiniShopCartDisplay.js file for editing.
      2. Add the following code in the positionMiniShopCartDropDown method after the wc.widgetWCDialog is created:
        
        /* APPLEPAY BEGIN */
        if (typeof(showApplePayButtons) == "function") {
        showApplePayButtons();
        }
        /* APPLEPAY END */ 
        
      3. Save your changes to the file.
  3. Optional: It is recommended that you display some basic secure information about the credit card that is being used for the Apple Pay transaction on the Order Confirmation and Order History pages.
    1. Open the storedir/ShoppingArea/CheckoutSection/CheckoutPaymentAndBillingAddressSummary.jspf file for editing.
    2. Find the following line:
      
      <c:set var="knownProtocolData" value="account,expire_month,expire_year,cc_cvc,check_routing_number,installmentOption,CPFNumber" />
      
    3. Replace it with the following line:
      
      <c:set var="knownProtocolData" value="account,expire_month,expire_year,cc_cvc,check_routing_number,installmentOption,CPFNumber,paymentMethod_displayName" />
      
    4. Add the following code in bold:
      
      <c:if test="${paymentInstance.payMethodId !='LineOfCredit'}">
      	<c:choose>
      		<c:when test="${isBrazilStore and knowProtocolDataItem eq 'installmentOption'}">
      			<p><fmt:message bundle="${storeText}" key="${knowProtocolDataItem}"/></p>
      			<p><c:out value="${protocolDataMap[knowProtocolDataItem]}"/></p>
      		</c:when>
      		<c:when test="${isBrazilStore and knowProtocolDataItem eq 'CPFNumber'}">
      			<%--set this value for the Boleto form and don't display the CPF since its sensitive info  --%>
      			<c:set var="CPFNumber" value="${protocolDataMap[knowProtocolDataItem]}"/>
      		</c:when>
      		<c:when test="${knowProtocolDataItem eq 'paymentMethod_displayName'}">
      			<p><fmt:message bundle="${storeText}" key="PAYMENT_NUMBER_OF_METHODS"/></p>
      			<p><c:out value="${protocolDataMap[knowProtocolDataItem]}"/></p>
      		</c:when>
      		<c:otherwise> <%-- Output AuroraESite store text  --%>
      			<p><fmt:message bundle="${storeText}" key="${knowProtocolDataItem}"/></p>
      			<p><c:out value="${protocolDataMap[knowProtocolDataItem]}"/></p>
      		</c:otherwise>
      	</c:choose>
      </c:if>
      
      
    5. Save your changes to the file.

What to do next

Go to the storefront and ensure that Apple Pay buttons are displayed wherever you placed them.