Articles in this section

Integrating ShoppingGives on BigCommerce

ShoppingGives
  • Updated

 

Who should read this: the webmaster or developer with Admin access to the eCommerce 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 dev@shoppinggives.com 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.

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>

Param

Type

Description

Required

Default

sid

text

Store Id - Provided by ShoppingGives

Yes

n/a

test-mode

bool

Toggles test mode on and off. Should only ever be true on non-production environments.

No

false

 

 

PDP Page (Product Page)

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

 

 

 

2. Craft URL Parameters

Param

Type

Description

Required

Default

sid

text

Store Id - Provided by ShoppingGives

Yes

n/a

price

text

Price of the current subitem

Yes

n/a

subitem-id

text

Identifier of the current subitem

Yes

n/a

target-element

text

CSS Selector value that dictates where you want the widget to go. 

No

Without, it replaces script tag with widget HTML

after

bool

Append after target-element

No

false

before

bool

Append before target-element

No

false

debug

bool

Allows to turn on debug logging for the widget

No

false


NOTE:  Remove all optional URL Params 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

On subitem change, run:

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

For example:

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)

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

 

 

2. Create a hidden CSS Element “amount” to target for dynamic donation on cart and checkout. 

Note: Disregard if an entity with a similar calculation already exists for other uses like affiliate tracking.

  • “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. Crafting the URL Parameters 

Param

Type

Description

Required

Default

sid

text

Store Id - Provided by ShoppingGives

Yes

n/a

target-element

text

CSS Selector value that dictates where you want the widget to go.

No

Replaces script tag with widget HTML

after

bool

Append after target-element

No

false

before

bool

Append before target-element

No

false

debug

bool

Allows to turn on debug logging for the widget

No

false


NOTE: Please remove all optional URL Params 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} });

<!-- EXAMPLE -->


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

// Foreach Item
window.cc_cart_items.push({ id: 'SUBITEM123', price: 98.76, quantity: 3, discount: 10.00 });

 

6. Update all carts:

if(window.sgCartControllers) {

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

}

 

  • On cart change (item removed, quantity changed, etc), refresh all carts again.
  • 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.

7. Handle Cart Discount Changes by Product (Optional)

You can update the product level price by applying the discount to each product 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 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. Create API Key in your BigCommerce admin, go to Advanced Settings → API Accounts:

Screen_Shot_2020-11-11_at_11.45.58_AM.png


2. Click Create API Account -> Create V2/V3 API Token:Screen_Shot_2020-11-11_at_11.46.40_AM.png


3. Name it “ShoppingGives” 

Screen_Shot_2020-11-11_at_11.47.51_AM.png

4. Under OAuth Scopes: Set Orders and Order Transactions to Read-Only, the remaining fields can be left as none.

Screen_Shot_2020-11-11_at_11.51.19_AM.png

5. Upon completion of step 4, a text .txt file will download, email to developers@shoppinggives.com as an attachment.

 

Add Post-Conversion Script

1. In your BigCommerce admin, go to Advanced Settings -> Web Analytics:

Screen_Shot_2020-11-11_at_11.53.38_AM.png

 

2. Ensure that Affiliate Conversion Tracking is selected and saved:

Screen_Shot_2020-11-11_at_11.53.43_AM.png

4. Replace **storeId** with your Shopping Gives Store Id and place the following script tag in the input:

<script src="https://cdn.shoppinggives.com/cc-utilities/conversion.js?sid=**storeId**&oid=%%ORDER_ID%%"></script>

 

Styles and Customization 

You can use the CSS editor to customize the appearance of our widget with any style sheet. It is better to make the customization on the theme’s main style sheet.

To edit the container to add padding, target main-element

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

Upon completion of the above, please notify your account representative or support@shoppinggives.com of your completion. Upon receipt, our team will configure settings to ensure the setup is correct. Please wait for ShoppingGives' support to notify you of the completion of the setup of your store before testing.

 

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

1. Running a test purchase – Expected outcome:

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

      1. 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
      2. Make a Test Purchase: Take note of the donation amount listed and cause supported before checkout. 
      3. 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.
      4. 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. 
      5. Test with alternative payment methods. Note, if the final transaction does not redirect to the standard thank you page, please contact Support@shoppinggives.com for specific instructions.

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

 

END OF DOCUMENT.

Related articles