Overview

ChangeUp for Charity offers merchants the ability to allow their customers to make charitable donations using three type options: 1) fixed, 2) percentage of the order total, and 3) round-up to the next whole monetary value.  How the donation amount is calculated is variable based on several configurable options.  These options can be configured on the ChangeUp dashboard; functionality that is made possible by the Business Manager cartridge included in the distribution.  

Once the cartridge is installed, merchants will choose a default charity.  This is the charity that all donations will be sent to unless other featured charities are chosen by the merchant. Several featured organizations may be selected in the configuration, which are displayed to the user on the order confirmation page to select from. 

Installation

This section describes the installation of the cartridge which includes several tasks:

  • Data import
  • ChangeUp cartridge integration into merchant code base
  • Setup and configuration

Compatibility

The ChangeUp for Charity cartridge is built using and is compatible with SFRA architecture.

Data Import

Locate the metadata > changeup_import directory within the distribution.  We’re going to have to make a few changes to the data files within.

1) Rename the metadata > changeup_import > sites > [MERCHANT-SITE-ID] directory to be the ID of the site the cartridge is being installed for.

  • If the site is assigned to a shared library, open library.xml for editing and in the primary <library> node, add the attribute library-id, making its value the ID of the shared library to import the content assets into.
<library xmlns=“http://www.demandware.com/xml/impex/library/2006-10-31" library-id=“site-lib-id”>

2) Open metadata > changeup_import > inventory-lists > inventory.xml for editing.  Modify the list-id value in the <header> node to be the ID of the inventory list the site is assigned to.

<header list-id="MERCHANT-LIST-ID">
NOTICE:  If your recurring inventory import is using the REPLACE method, you will need to include the donation product’s inventory within that feed so it is always present.  For reference of the inventory setup, look to the inventory.xml file included in the distribution.

3) Open metadata > changeup_import > catalogs > storefront-catalog > catalog.xml for editing. Modify the catalog-id value in the <catalog> node to be the ID of the storefront catalog the site is using for categorization.

<catalog xmlns="http://www.demandware.com/xml/impex/catalog/2006-10-31" catalog-id="MERCHANT-STOREFRONT-CATALOG-ID">

4) Open metadata > changeup_import > jobs.xml for editing.  Modify the site-id value in the context node to be the ID of the site the cartridge is being installed for.

<context site-id="[MERCHANT_SITE_ID]"/>
NOTICE:  If your recurring storefront catalog import is using the REPLACE method, you will need to include the donation product within that feed so it is always present. For reference of the inventory setup, look at the catalog.xml file under the storefront-catalog directory included in the distribution.

5) Now create a zip file from the changeup_import directory, ensuring the zip file is named changeup_import.zip

6) On the Commerce Cloud instance you are installing the data on, navigate to Administration > Site Development > Site Import & Export and upload the changeup_import.zip file you created in the last step.

7) Import the data. Select the changeup_import.zip archive and click the Import button.

 

Code Integration

Templates

There are three templates which must be integrated into your storefront templates:

  • int_changeup_sfra/cartridge/templates/default/changeUp/checkout/checkout.isml
  • int_changeup_sfra/cartridge/templates/default/changeUp/checkout/confirmation.isml
  • int_changeup_sfra/cartridge/templates/default/changeUp/checkout/donationPrice.isml

These files need to be included into these existing SFRA files, respectively:

  • [app_storefront_overlay]/cartridge/templates/[locale]/checkout/checkout.isml
  • [app_storefront_overlay]/cartridge/templates/[locale]/checkout/confirmation/confirmation.isml
  • [app_storefront_overlay]/cartidge/templates/[locale]/product/components/pricing/main.isml
NOTICE: 
[app_storefront_overlay] refers to the storefront cartridge where app_storefront_base templates are overridden, so that base templates remain unaltered.  This can vary from merchant to merchant, and you may need to copy these files from the app_storefront_base cartridge if you have not already.

[locale] refers to the locale directory, which is typically “default”, but may be different depending on your architecture.

[app_storefront_overlay]/cartridge/templates/[locale]/checkout/checkout.isml

NOTICE: 
The exact location to include this template is up to the merchant and their desired checkout user experience.  This example renders the donation module at the bottom of the right column, below the order summary.  For example, you may choose to include it on the left side, in the billing area.  The donation UI will function independent of any other checkout elements and forms, and therefore can be included anywhere. Below is a screen shot of the reference placement.

 

[app_storefront_overlay]/cartridge/templates/[locale]/checkout/confirmation/confirmation.isml

NOTICE: 
The exact location to include this template is up to the merchant and their desired checkout user experience.  This example renders the charity selection module above the order confirmation.  The charity selection UI will function independent of any other elements and forms, and therefore can be included anywhere. Below is a screen shot of the reference placement.

 

[app_storefront_overlay]/cartridge/templates/default/product/components/pricing/main.isml

Script

There is one small change needed to the calculateProductPrices() function, in the scripts/hooks/cart/calculate.js file, or whichever file you use for the dw.order.calculate hook.  Because the donation line item does not have a pricebook price, you must handle the product id explicitly.  Here is an example applied to the default SFRA script. On line 125, you need to replace

if (!productLineItem.catalogProduct) 

with

if (!productLineItem.catalogProduct || productLineItem.productID == ‘changeup-donation’)

 

 

Cartridge Paths and Permissions

bm_changeup

  1. Put a reference to the bm_changeup cartridge in the Business Manager cartridge path.

int_changeup_sfra

  1. Put a reference to the int_changeup_sfra cartridge in the cartridge path of the site(s) the cartridge will be enabled for.
    1. Ensure the reference is to the left of the SFRA base cartridge’s entry on the path.
  2. Put a reference to the int_changeup_sfra cartridge in the Business Manager cartridge path.

Business Manager Module Permissions

  1. Navigate to Administration > Organization > Roles & Permissions, click the role that will be using the dashboard to configure ChangeUp. (Administrator for example)
  2. Click on the Business Manager Module tab
  3. In the Select Context modal, select the sites that will be using ChangeUp, and click Apply.
  4. Select the Write checkbox for the ChangeUp > Dashboard module, and click Update.

Setup and Configuration

Site Preferences

API Key

An API key is required to send requests to the ChangeUp API.  Once you obtain this key, you will need to place it in the site preferences for the site the cartridge is being installed for.

  1. Navigate to Merchant Tools > Site Preferences > Custom Preferences > ChangeUp
  2. Enter the API key in the field next to ChangeUp API Key
  3. Click Save.

Enable ChangeUp

To enable the cartridge’s functionality on the storefront, you must enable a site preference setting:

  1. Navigate to Merchant Tools > Site Preferences > Custom Preferences > ChangeUp
  2. Choose Yes in the drop-down field next to ChangeUp Enabled.
  3. Click Save.

Functionality

Donation Confirmation

The donation confirmation is a widget that displays on checkout.  It provides the following functionality:

  • Agreement to donate — For donation types Customer and Merchant/Customer Match, the donation confirmation element provides a checkbox that allows the user to decide whether to agree to donate or not.
  • Charity Logos – If the default charity is the only charity saved on the dashboard, and no featured charities have been saved, then the default charity’s logo will be shown on the left side of the widget (and to the right of the checkbox when present). If at least one featured charity has been saved in addition to the default charity, up to 5 logos will display in a row at the bottom of the widget.
  • Total donations – If the total donations display toggle has been enabled on the dashboard, and the minimum threshold is less than the starting value plus the real time total, then a message “$x.xx donated to date.” is shown.
  • User Messaging – Depending on the dashboard settings, including the number of charities, the donation actor and option, and the customer search toggle, a dynamic set of messages are displayed to the customer. All of the text for this area is found in the int_changeup_sfra/cartridge/templates/resources/changeup.properties file, and can be customized or translated during integration.
  • Donation amount — The amount calculated for the donation is shown on the right side of the element.

 

When the donor is configured to be the Merchant on the dashboard, no monetary changes are made to the order because the donation amount will be funded by the merchant.  When the donor is configured to be the Customer or Customer/Merchant Match, the customer will be presented with a checkbox on the widget that allows them to consent to funding the donation.  When the checkbox is checked on or off, the donation amount will be added to the order, or removed.  The donation is applied to the cart as a Product Line Item, with dynamic pricing, based on the Donation Actor, Donation Option, and cart totals.

NOTE: Because a donation product is used to affect monetary change for the donation amount, the product has the potential for displaying to the customer within the product line item summary on checkout and confirmation page.  If the checkout page is reloaded for instance, the line item will display in the summary without a custom approach to hide it.  It is up to the merchant whether they want to hide this line item or not.  To hide, custom code will be needed in the template to look for the donation product’s ID, place identifying attributes (e.g. class or id) on the parent element of the line item, then use CSS to hide it.  Keep in mind that any product counts displayed will also display the number of products plus one for the donation product unless custom code is used to affect this.

Donation Confirmation Examples:

Charity Selector

The charity selector is a widget that displays on the order confirmation and allows customers to choose a charity to donate to, based on the options the merchant has configured on the dashboard. The default charity and any featured charities chosen on the merchant's dashboard will be displayed as tiles with the option to select one.

The thank you page header is configurable using the content assets:

changeup-charity-selector-header

The merchant statement is configurable using the content asset:

changeup-charity-selector-merchant-statement

Once the customer selects a charity by clicking the Send it! button associated with the charity, a message is shown to the customer confirming their actions. This message is configurable via the content asset:

changeup-sendit-submit-merchant-statement

If there is no charity selection made by the customer within 10 minutes of loading the order confirmation page, the donation is automatically set to use the merchant selected default charity as receiving the donations. There is a customer-side timer code that will hide the charity selector and display a message similar to the message for the Send it! action. The copy in this message is exclusively configurable like the Send it! action via the content asset:

changeup-timer-submit-merchant-statement

Donation Reporting

ChangeUp requires donation data reporting after the payment of the order has been captured.  For that, we have developed a job that will send order data to our API. Below is a screenshot about that job definition.

Commerce Cloud Injection

The merchant should point you to where in their code base they are capturing on order payments. It is within this code that you will need to construct an Object resembling the request example above from the orders that are being processed.  To make the process more efficient, you could pre-flight a check on each order’s custom attribute changeupAgreedToDonate to see if it should be sent to the donation reporting code.  After you have constructed the object, inject this line of code and pass the object to the constructor (data is the object in the example).  The result can be used to throw errors or ensure that the capture reporting completed successfully.

var result = require('~/cartridge/scripts/changeup/services/captureReporting')(data);

 

Testing

Dashboard

Test the functionality of the dashboard within the Business Manager module.

  • Search — Ensure the charity search works correctly by delivering search results after 3 characters are typed into the input.
  • Save Configuration — Save a configuration and reload the dashboard to confirm that the settings have been saved.

 

Donation Confirmation Widget

Test the functionality of the donation confirmation widget on checkout.

  • Donation Type | Actor — Check that as each actor is set, the donation confirmation widget displays the correct layout and copy from the associated content assets.
  • Donation Type | Option — Check that as each option is set, the donation is calculating correctly (refer to Donation Type: Option section for details on calculations).
  • Agreed to Donate — For actors Customer and Customer/Merchant Match, ensure when checking the box to agree to donate that the order total is recalculated; adding and removing the donation amount respectively.

 

Charity Selector Widget

Test the functionality of the charity selector widget on order confirmation.

  • Displays Correctly — The charity selection widget should display only if the customer has checked the box on the donation confirmation widget (applies to when donation type actor is set to Customer or Customer/Merchant Match). Also, check that the copy from the content assets are correct.
  • Send It — Ensure the Send It action performs correctly and that the correct messaging is displayed after the action.
  • Timer End — Ensure the timer ending action performs correctly and that the correct messaging is displayed after the timer counts down (10 minutes after the confirmation page load the timer should trigger its actions).

 

ChangeUp Custom Order Attributes

Check the custom attributes on the test orders placed while testing the different configurations.  Ensure that the donation amounts are applied to the correct attribute (customer and/or merchant).

 

Donation Reporting

Within the code in the distribution, navigate to cartridges > int_changeup_sfra > cartridge > tests > endpoints.txt.  Using VS Code, install the REST Client for Visual Studio Code extension referenced at the top of the file.  Read the documentation on how to trigger a request.  Replace [your-instance-url.demandware.net] with the domain of the instance you are testing on.  Trigger the request with a JSON request using orders that you have created testing the ChangeUp cartridge.  Once this is complete, the order should have confirmation UUIDS within the ChangeUp custom attribute group.  This confirms the necessary reporting data has been transmitted.

 

Failover

If the ChangeUp API experiences a failure, users will be given the option of donating only to the default selected charity.

 

Known Issues

Array.prototype.every = function (callback) {
     const { length } = this;
     
     for (let index = 0; index < length; index += 1) {
      const value = this[index];

     if (!callback(value, index, this)) {
      return false;
     }
    }

    return true;
   };

If for some reason the client-side Javascript needs to be recompiled for the bm_changeup cartridge, there is a code update needed in an autocomplete.js file node_modules > autocomplete.js > zepto.js.  This update needs to go in on line 7 of the aforementioned file.  This is due to Business Manager utilizing the Prototype.js library that overrides the default functionality of the Array.prototype.every function.  This leads to client-side script errors when autocomplete.js tries to initialize its DOM elements.

 

User Interface Design

The UI design shown above is for demonstration purposes only. Merchants may custom-design the ChangeUp endpoints to match their own eCommerce style and design. Here are some best practices for implementing the UI.