Storefront Widgets Integration Guide

👍

Who should read this:

The webmaster or developer with HTML/CSS -level access to the e-commerce website.

Pre-Integration

1. A Store ID is required from ShoppingGives in order to render widgets. Please request this Store ID from your ShoppingGives representative.

2. Invite [email protected] to your development environment for development support purposes.

Basic Instructions

A complete implementation of the ShoppingGives widget involves adding it to an e-commerce website.

1. Widget Implementation

a. Global Tracking Script

b. PDP Page (Product Page)

c. Pre-Conversion (Cart / Checkout Page)

d. Post-Conversion

e. Sale Webhook

f. Styles and Customization

2. Once these pieces of code are added to the e-commerce website the new implementation can be tested.

📘

Note

If you use a Content Management System to manage your e-commerce website, check with your ShoppingGives rep for a CMS-specific implementation guide. This guide is generic and does not take any CMS into account.

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=true"></script>

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

<!-- TEMPLATE -->

<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>

<!-- EXAMPLE -->

<script type="text/javascript" src="https://cdn.shoppinggives.com/cc-utilities/contained-product.js?sid=ab123456-c78d-9ef0-g1h2-345i678j90k1&price=98.76&subitem-id=SUBITEM123"></script>

📘

Note

If a product has multiple variants (e.g. size, color, etc) and the sub-item Id is not defined yet, you can populate “subitem-id” with the first variant’s ID.

4. Handle updating of subitem on the page

a. On subitem change, run:

window.sgProductControllers[0].setSubitem('{subitem-id}', {price});

window.sgProductControllers[0].setSubitem('SUBITEM123', 98.76);

5. Confirm the donation amount shown on product pages is dynamically changing based on the product value.

Pre-Conversion (Cart / Checkout Page)

📘

Shopify will be migrating merchants to a new checkout experience in September 2023

Check out the ShoppingGives checkout extension widget!
https://faq.shoppinggives.com/hc/en-us/articles/12414842885911-Shopify-Plus-Implementing-a-ShoppingGives-Checkout-Extension

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. Create a hidden CSS Element “amount” to target for dynamic donation on cart and checkout.

a. “Amount” is the term used to describe line items minus discounts, pre-tax, pre-shipping(this is the value we calculate donations based on).

📷

For example, with a $100.00 subtotal and 10% off coupon, $4.99 Shipping, and $3.00 tax, “amount” would calculate to $90.00

3. Craft URL Params

🚧

Please remove all optional URL parameters not being used.

4. Place the widget code on the cart/checkout pages

<!-- TEMPLATE -->

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

<!-- EXAMPLE -->

<script type="text/javascript" src="https://cdn.shoppinggives.com/cc-utilities/contained-cart.js?sid=ab123456-c78d-9ef0-g1h2-345i678j90k1></script>

5. Add Cart Items:

<!-- TEMPLATE -->

if (!window.cc_cart_items) { window.cc_cart_items = [] }

// Foreach Item
window.cc_cart_items.push({ id: '{itemId}', price: {price}, quantity: {quantity}, discount: {discount} });

6. Update all carts:

if(window.sgCartControllers) {
   for (var x = 0; x < window.sgCartControllers.length; x++) {
      window.sgCartControllers[x].refreshCart();
   }
}

a. On cart change (item removed, quantity changed, etc), retry refresh all carts.

b. Once the cart page is loaded and cc_cart_items array is populated, check if the cart controllers are null. If the cart controllers are NOT null, then you'll call refreshCart() to update its current state.

c. Handle Cart Discount changes – You can change this by applying the discount to each product yourself and ignoring the cart level discount

if(window.sgCartControllers) {
   for (var x = 0; x < window.sgCartControllers.length; x++) {              
       window.sgCartControllers[x].setDiscount({cart discount}); 
   }
}

👍

Confirm correct donation amounts displayed:

Confirm the donation amount shown on cart and checkout pages is dynamically changing based on the value of the cart, pre-tax, pre-shipping, post-discounts.

Post-Conversion

1. Check CMS Specific documentation. CMS steps may vary based on specific CMS requirements. Please request your specific CMS integration guide if you have not received it.

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

🚧

Please remove all optional URL Params not being used

3. Place the widget on the confirmation (post-conversion / thank you) page

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.

Sale Data Transfer Process

Please reference your specific CMS integration requirements:

• Shopify Plus Integration Guide
• BigCommerce Post Conversion Integration Guide
• Magento 2 Extension Integration Guide
• Salesforce Commerce Cloud
• ETL Data Transfer Process
• Direct Custom API