Magento 2 Integration Guide

👍

Who should read this:

The webmaster or developer with root-level access to Magento 2

🚧

Downloading the Extension

There are 2 extensions, one intended for Dev/Staging stores and one for Production

Make sure you install the correct one as well as using the corresponding Widget Scripts for each enviroment

Credentials such as API keys and Store ID's are enviroment specific. Make sure to use the correct ones for each enviroment

Download the Extension

• Production

https://cdn.shoppinggives.com/magento-2-extension/ChangeCommerce.Magento2.Extension.latest.zip

• Staging

https://cdn.staging1.shoppinggives.com/magento-2-extension/ChangeCommerce.Magento2.Extension.latest.zip

Install the Extension

1. Copy the contents of the zip folder to {MagentoBasePath}/app/code/ChangeCommerce/Core (create the directories that do not exist; “app” should already exist, “code” may not, the rest definitely shouldn’t)

2. From the Magento Root Directory Run:

a. bin/magento setup:upgrade

b. bin/magento setup:static-content:deploy

From the Admin, navigate to Stores -> Configuration -> ChangeCommerce -> Setup
If you are able to do that, then the extension has been successfully installed!

Configure the Extension

1. From the Admin, navigate to Stores -> Configuration -> ChangeCommerce -> Setup

2. Provide the Store ID and API Key (Secret) provided to you previously

Run Consumers

In order to have a seamless experience for you and your customers, we defer all processing to services that run in the background.

Our suggestion is to run these as configurable services and not allow Magento’s CRON to start the consumers, but this is completely up to the developers maintaining this site.

We have 3 consumers: changecommerce_ordercreate, changecommerce_creditmemo, and changecommerce_order

If you need guidance on how to set up the consumers as services, continue on, otherwise you are done!

Setup Consumers as Services (Optional)

Order Creation:

Run: sudo nano /etc/systemd/system/changecommerce_ordercreate.service
Update, then paste the following:

[Unit]
Description=ChangeCommerce Create Order Consumer
After=network.target
StartLimitIntervalSec=0
[Service]
Type=simple
Restart=always
RestartSec=1
User=root
ExecStart={magentoCliLocation} queue:consumers:start changecommerce_ordercreate

[Install]
WantedBy=multi-user.target

To start the service run:

📘

Note

{magentoCliLocation} is usually {MagentoBasePath}/bin/magento but we don’t want to assume it for you. ALSO don’t put ExecStart should be a single line, the line wrapping here pushes it down.

Credit Memo:

Run: sudo nano /etc/systemd/system/changecommerce_creditmemo.service
Update, then paste the following:

[Unit]
Description=ChangeCommerce Credit Memo Consumer
After=network.target
StartLimitIntervalSec=0
[Service]
Type=simple
Restart=always
RestartSec=1
User=root
ExecStart={magentoCliLocation} queue:consumers:start changecommerce_creditmemo
[Install]
WantedBy=multi-user.target

📘

Note

{magentoCliLocation} is usually {MagentoBasePath}/bin/magento but we don’t want to assume it for you. ALSO don’t put ExecStart should be a single line, the line wrapping here pushes it down.

To start the service run:

Order Cancel:

Run:
sudo nano /etc/systemd/system/changecommerce_ordercancel.service
Update, then paste the following:

[Unit]
Description=ChangeCommerce Order Cancel Consumer
After=network.target
StartLimitIntervalSec=0
[Service]
Type=simple
Restart=always
RestartSec=1
User=root
ExecStart={magentoCliLocation} queue:consumers:start changecommerce_ordercancel
[Install]
WantedBy=multi-user.target

📘

Note

{magentoCliLocation} is usually {MagentoBasePath}/bin/magento but we don’t want to assume it for you. ALSO don’t put ExecStart should be a single line, the line wrapping here pushes it down.

To start the service run:

Widget Integration

Pre-Integration

A Store ID is required from ShoppingGives in order to render widgets. Please request this Store ID from your ShoppingGives representative.
Invite [email protected] to your development environment for development support purposes.

Global Tracking Script

Place script on every page in header tag (if not already done)

<script type="text/javascript" src="https://cdn.shoppinggives.com/cc-utilities/sgloader.js?sid=XXXXXXXXXX&test-mode=false"></script>

<script type="text/javascript" src="https://cdn.staging1.shoppinggives.com/cc-utilities/sgloader.js?sid=XXXXXXXXXX&test-mode=false"></script>

For Magento platform, in the admin page of the store.
Go to the Content -> Design Configuration

Click on the “Edit” function on the theme your store is using

Open the HTML Head settings and place the script in the “Scripts and Style Sheets” section.

PDP Page (Product Page)

1. Choose the style of widget you’d like to use:

a. Contained (https://cdn.shoppinggives.com/cc-utilities/contained-product.js)

b. Compact (https://cdn.shoppinggives.com/cc-utilities/compact-product.js)

c. Full (https://cdn.shoppinggives.com/cc-utilities/full-product.js)

2. Craft URL Parameters

🚧

Please remove all optional URL parameters not being used.

3. Place the widget on the product pages

<script type="text/javascript" src="https://cdn.shoppinggives.com/cc-utilities/{product-widget-style}.js?sid={store-id-provided}&price={price-of-item}&subitem-id={identifier-for-specific-product-variant}"></script>

<script type="text/javascript" src="https://cdn.staging1.shoppinggives.com/cc-utilities/{product-widget-style}.js?sid={store-id-provided}&price={price-of-item}&subitem-id={identifier-for-specific-product-variant}"></script>

For Magento Platform, in order to place the script under or around the “Add To Cart” button it is necessary to access the store’s files.

📘

It is beneficial to have knowledge of bash

Once in the root folder for the magento store, perform the following commands:

cd vendor
Find ./ -name addtocart.phtml

The “find” command should return the path to the file it is necessary to edit.
Perfom the following command :

cd the/path/returned/by/the/find/command

Once in the folder of the addtocart.phtml file we will need to edit the file.

There are many ways to edit a file in this case we will use vim since it comes already with the app by default, however if you are comfortable using nano or another text editor will work with the following steps too.

Perform the following command:

sudo vim addtocart.phtml

It should open the file in the terminal

At the top of the file, right under the button tittle add the following:

<?php $priceData = $_product->getPriceInfo()->getPrice('final_price')->getAmount()->getBaseAmount(); ?>
<?php $id = $_product->getId(); ?>

After adding it, you can add the widget script under the button:

<script type="text/javascript" src="https://cdn.shoppinggives.com/cc-utilities/{product-widget-style}.js?sid={store-id-provided}&price=<?=$priceData?>&subitem-id=<?=$id?>"></script>

<script type="text/javascript" src="https://cdn.staging1.shoppinggives.com/cc-utilities/{product-widget-style}.js?sid={store-id-provided}&price=<?=$priceData?>&subitem-id=<?=$id?>"></script>

Once you added the widget you are safe to save the file and flush the Cache of the page. It should start showing the widget on any product page.

🚧

This will make the same widget show in every product page. In order to have it render only on products you choose there is extra steps.

Pre-Conversion (Cart / Checkout Page)

1. Choose the style of widget you’d like to use:

a. Contained (https://cdn.shoppinggives.com/cc-utilities/contained-cart.js)

b. Compact (https://cdn.shoppinggives.com/cc-utilities/compact-cart.js)

c. Full (https://cdn.shoppinggives.com/cc-utilities/full-cart.js)

2. Craft URL Params

3. Prepare the Cart Page for Custom Content

Add the below code in checkout_index_index.xml file at app\code\Vendor\Module\view\frontend\layout.

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="content">
            <block class="Magento\Framework\View\Element\Template" name="custom_text_summary"
                   template="Vendor_Module::checkout/custom_content.phtml"/>
        </referenceContainer>
    </body>
</page>

Then create a new file at app\code\Vendor\Module\view\frontend\templates\checkout.
Naming it custom_content.phtml and add the following code:

<?php
$objectManager = \Magento\Framework\App\ObjectManager::getInstance();
$cart = $objectManager->get('\Magento\Checkout\Model\Cart');
$allItems = $cart->getQuote()->getAllItems();
?>
 
 
<script type="text/javascript">
 
    if (!window.cc_cart_items) { window.cc_cart_items = [] }
 
    <?php foreach($allItems as $item) :?>
        window.cc_cart_items.push({ id: '<?=$item-> getItemId();?>', price: '<?= $item->getPriceInfo()->getPrice('final_price')->getAmount()->getBaseAmount();?>', quantity: 1, discount: 0 });
    <?php endforeach;?>
    window.customText = '<?php echo __('<script type="text/javascript" src="https://cdn.shoppinggives.com/cc-utilities/contained-cart.js?sid=ab123456-c78d-9ef0-g1h2-345i678j90k1></script>'); ?>';
</script>

<?php
$objectManager = \Magento\Framework\App\ObjectManager::getInstance();
$cart = $objectManager->get('\Magento\Checkout\Model\Cart');
$allItems = $cart->getQuote()->getAllItems();
?>
 
 
<script type="text/javascript">
 
    if (!window.cc_cart_items) { window.cc_cart_items = [] }
 
    <?php foreach($allItems as $item) :?>
        window.cc_cart_items.push({ id: '<?=$item-> getItemId();?>', price: '<?= $item->getPriceInfo()->getPrice('final_price')->getAmount()->getBaseAmount();?>', quantity: 1, discount: 0 });
    <?php endforeach;?>
    window.customText = '<?php echo __('<script type="text/javascript" src="https://cdn.staging1.shoppinggives.com/cc-utilities/contained-cart.js?sid=ab123456-c78d-9ef0-g1h2-345i678j90k1></script>'); ?>';
</script>

Add in the bottom to grand-total.html theme file located at app\design\Theme\Theme_Name\Magento_Tax\view\frontend\web\template\checkout\summary.

<tr class="grand totals">  
    <div data-bind="html: customText"></div>
</tr>

Post-Conversion

1. Add Url Params to https://cdn.shoppinggives.com/cc-utilities/conversion.js

2.Place the widget on the confirmation at vendor/magento/module-inventory-in-store-pickup-frontend/view/frontend/templates in the file success.phtml

<script type="text/javascript" src="https://cdn.shoppinggives.com/cc-utilities/conversion.js?sid={store-id-provided}&oid=<?=$block->getOrderId()?>"></script>

<script type="text/javascript" src="https://cdn.staging1.shoppinggives.com/cc-utilities/conversion.js?sid={store-id-provided}&oid=<?=$block->getOrderId()?>"></script>

Styles and Customization

You can use the CSS editor to customize the appearance of our widget with any style sheet or by leveraging our CSS Editor in the Impact Portal.

Style Fields for the Compact Widget Style:

1. To modify the eligibility tag main text, target class id sg-main-text to provide the stylings (don't forget to use !important)

2. If you have to fix the logo size, target class id powered-by-logo

Style Fields for the Contained Widget Style:

1. To modify the eligibility tag description, target class id sg-text-wrap to provide the stylings (don't forget to use !important)

2. To modify the main title, target the id cc-shop-give to provide the stylings (don't forget to use !important)

3. If you have to fix the logo size, target class id powered-by-logo

Style Fields for the Full Widget Style:

1. To modify the main title, target the id sg-title to provide the stylings (don't forget to use !important)

2. To modify the eligibility tag description, target class id sg-text-wrap to provide the stylings (don't forget to use !important)

3. If you have to fix the logo size, use class id sg-powered-by-wrap.

Testing the Integration

🚧

Note When Testing

Ensure that test mode URL parameters on the tracking script is set to “true”

1. Running a test purchase – Expected outcome:

a. Make a Test Purchase: Take note of the donation amount listed and cause supported before checkout.

i. Confirm the donation amount shown pre-purchase on the widget is 1% of the amount (pre-tax, pre-shipping, post discount)

b. Post-conversion: After a successful conversion the customer will be shown the post-conversion share modal. Use this modal to verify the correct donation amount and cause are displayed.

i. Confirm the donation amount shown post-purchase on the modal is 1% of the amount (pre-tax, pre-shipping, post discount), and the same amount shown pre-purchase

c. Testing with Coupon Code: Repeat step “a.” with the use of a coupon code that updates the price of the order. Ensure that the donation amount dynamically updates before the purchase is completed and that the donation amount post-purchase reflects the same amount shown pre-purchase.

2. Check for z-index, global typeface, padding settings to ensure that the widget is displayed optimally.